Messages

DB-All.e can read weather bulletins via wreport and scan their contents to given them a physical interpretation.

Interpreted messages are represented by the dballe::Message. Binary messages are represented by the dballe::BinaryMessage, and are read via dballe::File.

You can use dballe::Importer to go from a dballe::BinaryMessage to a dballe::Message.

You can use dballe::Exporter to go from a dballe::Message to a dballe::BinaryMessage.

class Message

A bulletin that has been decoded and physically interpreted.

Message collects zero or more variables that have been forecast or measured by the same station in the same instant.

Each variable is annotated with its vertical level/layer information, and its time range / statistical information.

The representation in Message is as connected as possible to physics rather than to observations.

Subclassed by dballe::impl::Message

Public Functions

virtual MessageType get_type() const = 0

Return the type of the data in the message.

virtual Datetime get_datetime() const = 0

Get the reference Datetime for this message.

virtual Coords get_coords() const = 0

Get the reference coordinates for this message.

virtual Ident get_ident() const = 0

Get the station identifier for this message.

virtual std::string get_report() const = 0

Get the report for this message.

virtual std::unique_ptr<Message> clone() const = 0

Return a copy of this message.

const wreport::Var *get(const Level &lev, const Trange &tr, wreport::Varcode code) const

Get a variable given its code, level and time range information.

Return

A pointer to the variable, or nullptr if it was not found.

const wreport::Var *get(const char *shortcut) const

Get a variable given its shortcut name.

Return

A pointer to the variable, or nullptr if it was not found.

const wreport::Var *get(const std::string &shortcut) const

Get a variable given its shortcut name.

Return

A pointer to the variable, or nullptr if it was not found.

void set(const Level &lev, const Trange &tr, wreport::Varcode code, const wreport::Var &var)

Add or replace a value.

Parameters
  • lev: The Level of the value

  • tr: The Trange of the value

  • code: The Varcode of the destination value. If it is different than the varcode of var, a conversion will be attempted.

  • var: The Var with the value to set

void set(const Level &lev, const Trange &tr, const wreport::Var &var)

Add or replace a value.

Parameters
  • lev: The Level of the value

  • tr: The Trange of the value

  • var: The Var with the value to set

void set(const Level &lev, const Trange &tr, std::unique_ptr<wreport::Var> var)

Add or replace a value, taking ownership of the source variable without copying it.

Parameters
  • lev: The Level of the value

  • tr: The Trange of the value

  • var: The Var with the value to set. This Message will take ownership of memory management.

void set(const char *shortcut, std::unique_ptr<wreport::Var> var)

Add or replace a value, taking ownership of the source variable without copying it.

Parameters
  • shortcut: Shortcut name mapping to a (Level, Trange, Varcode) triplet

  • var: The Var with the value to set. This Message will take ownership of memory management.

void set(const char *shortcut, const wreport::Var &var)

Add or replace a value.

Parameters
  • shortcut: Shortcut name mapping to a (Level, Trange, Varcode) triplet

  • var: The Var with the value to set. If its varcode is different than the varcode of the shortcut, a conversion will be attempted.

virtual bool foreach_var(std::function<bool(const Level&, const Trange&, const wreport::Var&)>) const = 0

Iterate the contents of the message.

virtual std::unique_ptr<CursorStation> query_stations(const Query &query) const = 0

Return a Cursor to access the station information in the message.

The cursor will have only one result, with the one station present in the message, contain all station vars.

Return

The cursor to use to iterate over the results

Parameters
  • query: The query data (note: currently ignored)

virtual std::unique_ptr<CursorStationData> query_station_data(const Query &query) const = 0

Query the station variables in the message.

Return

The cursor to use to iterate over the results

Parameters
  • query: The query data (note: currently ignored)

virtual std::unique_ptr<CursorData> query_data(const Query &query) const = 0

Query the variables in the message.

Return

The cursor to use to iterate over the results

Parameters
  • query: The query data (note: currently ignored)

virtual void print(FILE *out) const = 0

Print all the contents of this message to an output stream.

virtual unsigned diff(const Message &msg) const = 0

Compute the differences between two Messages.

Details of the differences found will be formatted using the wreport notes system (

See

wreport/notes.h).

Return

The number of differences found

Public Static Functions

static std::unique_ptr<Message> create(MessageType type)

Create a new empty message.

class BinaryMessage

Binary message.

Public Functions

operator bool() const

Return true if the message is not empty.

Public Members

Encoding encoding

Format of the binary data.

std::string data

Binary message data.

std::string pathname

Pathname of the file from where the BinaryMessage has been read.

It can be empty when not applicable, such as when the message is created from scratch and not yet written

off_t offset = (off_t)-1

Start offset of this message inside the file.

int index = MISSING_INT

Index of the message from the beginning of the file.

class File

File object for doing I/O on binary message streams.

It provides a unified interface to read and write messages to files.

Subclassed by dballe::core::File

Public Functions

virtual std::string pathname() const = 0

Get the file pathname.

virtual Encoding encoding() const = 0

Get the file encoding.

virtual void close() = 0

Close the underlying file.

virtual BinaryMessage read() = 0

Read a message from the file.

Return

the BinaryMessage with the binary data that have been read, or nullptr when the end of file has been reached.

virtual bool foreach(std::function<bool(const BinaryMessage&)> dest) = 0

Read all the messages from the file, calling the function on each of them.

If dest returns false, reading will stop.

Return

true if all file was read, false if reading was stopped because dest returned false.

virtual void write(const std::string &msg) = 0

Append the binary message to the file.

Public Static Functions

static std::unique_ptr<File> create(const std::string &pathname, const char *mode)

Open a file from the filesystem, autodetecting the encoding type.

Return

The new File object.

Parameters
  • pathname: The pathname of the file to access.

  • mode: The opening mode of the file, as used by fopen.

static std::unique_ptr<File> create(Encoding type, const std::string &pathname, const char *mode)

Open a file from the filesystem.

Return

The new File object.

Parameters
  • type: The type of data contained in the file.

  • pathname: The pathname of the file to access.

  • mode: The opening mode of the file, as used by fopen.

static std::unique_ptr<File> create(FILE *file, bool close_on_exit, const std::string &name = "(fp)")

Create a File from an existing FILE* stream, autodetecting the encoding type.

Return

The new File object.

Parameters
  • file: The FILE* stream for the file to access.

  • close_on_exit: If true, fclose() will be called on the stream when the File object is destroyed.

  • name: Pathname or description of the stream, used when generating error messages

static std::unique_ptr<File> create(Encoding type, FILE *file, bool close_on_exit, const std::string &name = "(fp)")

Create a File from an existing FILE* stream.

Return

The new File object.

Parameters
  • type: The type of data contained in the file.

  • file: The FILE* stream for the file to access.

  • close_on_exit: If true, fclose() will be called on the stream when the File object is destroyed.

  • name: Pathname or description of the stream, used when generating error messages

static const char *encoding_name(Encoding enc)

Return a string with the name of this encoding.

static Encoding parse_encoding(const char *s)

Return the Encoding corresponding to the given name.

static Encoding parse_encoding(const std::string &s)

Return the Encoding corresponding to the given name.

class ImporterOptions

Options to control message import.

To maintain ABI stability and allow to add options to this class, code using the stable ABI cannot create objects, but need to use the create() static methods.

Subclassed by dballe::impl::ImporterOptions

Public Functions

void print(FILE *out)

Print a summary of the options to out.

std::string to_string() const

Generate a string summary of import options.

Public Static Functions

static std::unique_ptr<ImporterOptions> create()

Create with default values.

static std::unique_ptr<ImporterOptions> create(const std::string &s)

Opposite of to_string: create an Options from a string.

Public Static Attributes

const ImporterOptions defaults

Default importer options.

class Importer

Message importer interface.

Subclassed by dballe::BulletinImporter, dballe::impl::msg::JsonImporter

Public Functions

virtual Encoding encoding() const = 0

Return the encoding for this importer.

std::vector<std::shared_ptr<Message>> from_binary(const BinaryMessage &msg) const

Decode a message from its raw encoded representation.

Parameters
  • msg: Encoded message

Return Value
  • msgs: The resulting messages

virtual std::vector<std::shared_ptr<Message>> from_bulletin(const wreport::Bulletin &msg) const

Import a decoded BUFR/CREX message.

virtual bool foreach_decoded(const BinaryMessage &msg, std::function<bool(std::unique_ptr<Message>)> dest) const = 0

Decode a message from its raw encoded representation, calling dest on each resulting Message.

Return false from dest to stop decoding.

Return

true if it got to the end of decoding, false if dest returned false.

Parameters
  • msg: Encoded message.

  • dest: The function that consumes the decoded messages.

Public Static Functions

static std::unique_ptr<Importer> create(Encoding type, const ImporterOptions &opts = ImporterOptions::defaults)

Instantiate an importer.

Parameters
  • type: The input file type

  • opts: Options controlling import behaviour

static std::unique_ptr<Importer> create(Encoding type, const std::string &opts)

Instantiate an importer.

Parameters
  • type: The input file type

  • opts: Options controlling import behaviour

class ExporterOptions

Options to control message export.

To maintain ABI stability and allow to add options to this class, code using the stable ABI cannot create objects, but need to use the create() static methods.

Subclassed by dballe::impl::ExporterOptions

Public Functions

void print(FILE *out)

Print a summary of the options to out.

std::string to_string() const

Generate a string summary of export options.

Public Members

std::string template_name

Name of template to use for output (leave empty to autodetect)

int centre = MISSING_INT

Originating centre.

int subcentre = MISSING_INT

Originating subcentre.

int application = MISSING_INT

Originating application ID.

Public Static Functions

static std::unique_ptr<ExporterOptions> create()

Create with default values.

class Exporter

Message exporter interface.

Subclassed by dballe::BulletinExporter, dballe::impl::msg::JsonExporter

Public Functions

virtual std::string to_binary(const std::vector<std::shared_ptr<Message>> &messages) const = 0

Encode a message.

Return

The resulting encoded data

Parameters

virtual std::unique_ptr<wreport::Bulletin> to_bulletin(const std::vector<std::shared_ptr<Message>> &msgs) const

Export to a Bulletin.

virtual std::unique_ptr<wreport::Bulletin> make_bulletin() const

Create a bulletin that works with this exporter.

Return

the bulletin, or NULL of this is an exporter for a format not covered by Bulletin

Public Static Functions

static std::unique_ptr<Exporter> create(Encoding type, const ExporterOptions &opts = ExporterOptions::defaults)

Instantiate the right importer for the given type.

enum dballe::MessageType

Type of the data in a message.

Values:

GENERIC = 1

Data from unspecified source.

SYNOP = 2

Synop measured data.

PILOT = 3

Pilot sounding data.

TEMP = 4

Temp sounding data.

TEMP_SHIP = 5

Temp ship sounding data.

AIREP = 6

Airep airplane data.

AMDAR = 7

Amdar airplane data.

ACARS = 8

Acars airplane data.

SHIP = 9

Ship measured data.

BUOY = 10

Buoy measured data.

METAR = 11

Metar data.

SAT = 12

Satellite data.

POLLUTION = 13

Pollution data.

const char *dballe::format_message_type(MessageType type)

Return a string with the name of a MessageType.

Return

The name, as a const string. This function is thread safe.

Parameters
  • type: The MessageType value to format