diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/doxygen/other/metadata.dox | 45 |
1 files changed, 23 insertions, 22 deletions
diff --git a/docs/doxygen/other/metadata.dox b/docs/doxygen/other/metadata.dox index 9fad7c584..f867a06f2 100644 --- a/docs/doxygen/other/metadata.dox +++ b/docs/doxygen/other/metadata.dox @@ -9,8 +9,8 @@ the system state such as sample rate or if a receiver's frequency are not conveyed with the data in the file itself. Header of metadata solve this problem. -We write metadata files using blocks::file_meta_sink and read metadata -files using blocks::file_meta_source. +We write metadata files using gr::blocks::file_meta_sink and read metadata +files using gr::blocks::file_meta_source. Metadata files have headers that carry information about a segment of data within the file. The header structure is described in detail in @@ -88,28 +88,29 @@ keep the sample times exact. \subsection implementation Implementation -Metadata files are created using file_meta_sink. The default -behavior is to create a single file with inline headers as +Metadata files are created using gr::blocks::file_meta_sink. The +default behavior is to create a single file with inline headers as metadata. An option can be set to switch to detached header mode. Metadata file are read into a flowgraph using -file_meta_source. This source reads a metadata file, inline by -default with a settable option to use detached headers. The data from -the segments is converted into a standard streaming output. The -'rx_rate' and 'rx_time' and all key:value pairs in the extra header -are converted into tags and added to the stream tags interface. +gr::blocks::file_meta_source. This source reads a metadata file, +inline by default with a settable option to use detached headers. The +data from the segments is converted into a standard streaming +output. The 'rx_rate' and 'rx_time' and all key:value pairs in the +extra header are converted into tags and added to the stream tags +interface. \section structure Structure The file metadata consists of a static mandatory header and a dynamic optional extras header. Each header is a separate PMT -dictionary. Headers are created by building a PMT dictionary of -key:value pairs, then the dictionary is serialized into a string to be -written to file. The header is always the same length that is -predetermined by the version of the header (this must be known -already). The header will then indicate if there is an extra data to -be extracted as a separate serialized dictionary. +dictionary. Headers are created by building a PMT dictionary +(pmt::pmt_make_dict) of key:value pairs, then the dictionary is +serialized into a string to be written to file. The header is always +the same length that is predetermined by the version of the header +(this must be known already). The header will then indicate if there +is an extra data to be extracted as a separate serialized dictionary. To work with the PMTs for creating and extracting header information, we use PMT operators. For example, we create a simplified version of @@ -125,7 +126,7 @@ the header in C++ like this: std::string hdr_str = pmt_serialize_str(header); \endcode -The call to pmt_dict_add adds a new key:value pair to the +The call to pmt::pmt_dict_add adds a new key:value pair to the dictionary. Notice that it both takes and returns the 'header' variable. This is because we are actually creating a new dictionary with this function, so we just assign it to the same variable. @@ -133,10 +134,10 @@ with this function, so we just assign it to the same variable. The 'mp' functions are convenience functions provided by the PMT library. They interpret the data type of the value being inserted and call the correct 'pmt_from_xxx' function. For more direct control over -the data type, see PMT functions in pmt.h, such as pmt_from_uint64 or -pmt_from_double. +the data type, see PMT functions in pmt.h, such as +pmt::pmt_from_uint64 or pmt::pmt_from_double. -We finish this off by using 'pmt_serialize_str' to convert the PMT +We finish this off by using pmt::pmt_serialize_str to convert the PMT dictionary into a specialized string format that makes it easy to write to a file. @@ -189,7 +190,7 @@ must be the same length and structure. As of now, we only have version - version: (char) version number (usually set to METADATA_VERSION) - rx_rate: (double) Stream's sample rate -- rx_time: (pmt_t pair - (uint64_t, double)) Time stamp (format from UHD) +- rx_time: (pmt::pmt_t pair - (uint64_t, double)) Time stamp (format from UHD) - size: (int) item size in bytes - reflects vector length if any. - type: (int) data type (enum below) - cplx: (bool) true if data is complex @@ -220,7 +221,7 @@ a PMT dictionary of key:value pairs. The extras header can contain anything and can grow while a program is running. We can insert extra data into the header at the beginning if we -wish. All we need to do is use the 'pmt_dict_add' function to insert +wish. All we need to do is use the pmt::pmt_dict_add function to insert our hand-made metadata. This can be useful to add our own markers and information. @@ -238,7 +239,7 @@ When reading out data from the extras, we do not necessarily know the data type of the PMT value. The key is always a PMT symbol, but the value can be any other PMT type. There are PMT functions that allow us to query the PMT to test if it is a particular type. We also have the -ability to do 'pmt_print' on any PMT object to print it to +ability to do pmt::pmt_print on any PMT object to print it to screen. Before converting from a PMT to it's natural data type, it is necessary to know the data type. |