C++ API structure

[ctriant]

The required operations of the gr-sigmf blocks, upon the SigMF JSON metafile, should be described and provided through a clear and efficient API. Since, at least for now, the main task is to support gr-sigmf blocks with C++, an efficient library for manipulating JSON files is needed. In my proposal for this GSoC project the RapidJSON library was referenced. Below, I'll present an example of the SigMF API structure.

• Three classes Global, Capture and Annotation, that represent the respective SigMF segmets and provide the appropriate fields and their setter & getters.

• A SigMF class that represents the SigMF metafile and operates as a wrapper of RapidJSON. This class provides the core functions in order to manipulate the three main segments of the metafile.

  • Holds the RapidJSON iterators for the three main segments.
  • Global get_global (): Function to get the global segment as an instance of Global class
  • std::vector\ get_capture (): Function to get the capture segment as a vector of Capture objects
  • std::vector\ get_capture (std::string filter_expression): Function to get the capture segments that satisfy the criteria specified by the filter_expression.
  • std::vector\ get_annotation (): Function to get the annotation segment as a vector of Annotation objects
  • std::vector\ get_annotation (std::string filter_expression): Function to get the annotation segments that satisfy the criteria specified by the filter_expression.
  • bool validate_sigmf (): Function to validate a SigMF JSON metafile.
  • bool validate_capture (): Function to validate the format of a capture segment.
  • bool validate_annotation (): Function to validate the format of an annotation segment.
  • bool append_capture_segment(): Function to append a capture segment into the metafile
  • bool append_annotation_segment(): Function to append a capture segment into the metafile
  • std::vector\<pair<name,value> get_custom_namespaces: Function that returns a list of <name,value> pairs for custom namespaces.

I open this issue here as a place to discuss possible additions or changes.

[bhilburn]

Hey @ctriant!

Some first-pass thoughts:

Holds the RapidJSON iterators for the three main segments. Global get_global (): Function to get the global segment as an instance of Global class std::vector get_capture (): Function to get the capture segment as a vector of Capture objects std::vector get_capture (std::string filter_expression): Function to get the capture segments that satisfy the criteria specified by the filter_expression. std::vector get_annotation (): Function to get the annotation segment as a vector of Annotation objects std::vector get_annotation (std::string filter_expression): Function to get the annotation segments that satisfy the criteria specified by the filter_expression.

Do you have any thoughts on how you will structure the filter_expressions?

bool validate_sigmf (): Function to validate a SigMF JSON metafile.

Does the validator in RapidJSON return different types of error codes / warnings? If so, how will the user access these?

bool validate_capture (): Function to validate the format of a capture segment. bool validate_annotation (): Function to validate the format of an annotation segment. bool append_capture_segment(): Function to append a capture segment into the metafile bool append_annotation_segment(): Function to append a capture segment into the metafile std::vector<pair<name,value> get_custom_namespaces: Function that returns a list of <name,value> pairs for custom namespaces.

Do you need something like this for core? How do you anticipate users querying the core namespace once they have the objects?

[sbmueller]

Generally, @ctriant is trying not to store the entire SigMF metadata in the memory. Instead, the RapidJSON API is queried with filters to just return the relevant parts of the JSON. As I got to know RapidJSON shows a nice performance here.

I think filter_expressions could also be a std::map with key/value pairs. If a known key is missing or an unknown key is passed, it would be ignored for the filtering. For instance { freq_lower_edge: 2.4e9, freq_higher_edge: 2.5e9, comment: 'test' }.

[ctriant]

Do you have any thoughts on how you will structure the filter_expressions?

Well, a naive approach could be to define a method that receives the string filter_expression and act appropriately for the cases of "==", "<", ">", "<=", ">=", "!=" operators. ie. for the case of an expression like annotation:core::freq_lower_edge > 950000000 I could define a syntax like {top_level_object}:{namespace}::{name}{operator}{value}. I dont know at the moment if it is possible to support logical operations for more complex queries.

Another approach could be to abandon the idea of filter_expression and define a method for each relational operation.

Does the validator in RapidJSON return different types of error codes / warnings? If so, how will the user access these?

I really need to check this further. I thinks that there are messages for missing objects, unexpected values etc so it could be possible to use them for the needs of SigMF. I'll return to this a soon as possible.