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 dballe::Message : public std::enable_shared_from_this<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.
-
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.
- Returns
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.
- Returns
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.
- Returns
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::shared_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.
- Parameters
query – The query data (note: currently ignored)
- Returns
The cursor to use to iterate over the results
-
virtual std::shared_ptr<CursorStationData> query_station_data(const Query &query) const = 0¶
Query the station variables in the message.
- Parameters
query – The query data (note: currently ignored)
- Returns
The cursor to use to iterate over the results
-
virtual std::shared_ptr<CursorData> query_data(const Query &query) const = 0¶
Query the variables in the message.
- Parameters
query – The query data (note: currently ignored)
- Returns
The cursor to use to iterate over the results
-
virtual void print(FILE *out) const = 0¶
Print all the contents of this message to an output stream.
Public Static Functions
-
static std::shared_ptr<Message> create(MessageType type)¶
Create a new empty message.
-
virtual MessageType get_type() const = 0¶
-
class dballe::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.
-
operator bool() const¶
-
class dballe::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.
- Returns
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.
- Returns
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.
- Parameters
pathname – The pathname of the file to access.
mode – The opening mode of the file, as used by fopen.
- Returns
The new File object.
-
static std::unique_ptr<File> create(Encoding type, const std::string &pathname, const char *mode)¶
Open a file from the filesystem.
- 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.
- Returns
The new File object.
-
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.
-
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.
- 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
- Returns
The new File object.
-
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.
-
virtual std::string pathname() const = 0¶
-
class dballe::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
-
static const ImporterOptions defaults¶
Default importer options.
-
void print(FILE *out)¶
-
class dballe::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 values
msgs – The resulting messages
-
virtual std::vector<std::shared_ptr<Message>> from_bulletin(const wreport::Bulletin &msg) const¶
Import a decoded BUFR/CREX message.
Decode a message from its raw encoded representation, calling dest on each resulting Message.
Return false from dest to stop decoding.
- Parameters
msg – Encoded message.
dest – The function that consumes the decoded messages.
- Returns
true if it got to the end of decoding, false if dest returned false.
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
-
virtual Encoding encoding() const = 0¶
-
class dballe::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.
-
void print(FILE *out)¶
-
class dballe::Exporter¶
Message exporter interface.
Subclassed by dballe::BulletinExporter, dballe::impl::msg::JsonExporter
Public Functions
Encode a message.
- Parameters
messages – Message to encode
- Returns
The resulting encoded data
Export to a Bulletin.
-
virtual std::unique_ptr<wreport::Bulletin> make_bulletin() const¶
Create a bulletin that works with this exporter.
- Returns
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 class dballe::MessageType¶
Type of the data in a message.
Values:
-
enumerator SYNOP¶
Synop measured data.
-
enumerator PILOT¶
Pilot sounding data.
-
enumerator TEMP¶
Temp sounding data.
-
enumerator TEMP_SHIP¶
Temp ship sounding data.
-
enumerator AIREP¶
Airep airplane data.
-
enumerator AMDAR¶
Amdar airplane data.
-
enumerator ACARS¶
Acars airplane data.
-
enumerator SHIP¶
Ship measured data.
-
enumerator BUOY¶
Buoy measured data.
-
enumerator METAR¶
Metar data.
-
enumerator SAT¶
Satellite data.
-
enumerator POLLUTION¶
Pollution data.
-
enumerator SYNOP¶
-
const char *dballe::format_message_type(MessageType type)¶
Return a string with the name of a MessageType.
- Parameters
type – The MessageType value to format
- Returns
The name, as a const string. This function is thread safe.