SolarCapture C Bindings User Guide  SF-115721-CD
Issue 3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
declare_types.h File Reference

This header is used to generate C type definitions and corresponding runtime type information for data structures that are shared by SolarCapture with other processes. More...

Macros

#define ST_CONSTANT(name, val)   enum { name = val };a
 A constant value in the template definition. More...
 
#define ST_STRUCT(name)   struct name {
 Start of the template definition. More...
 
#define ST_FIELD_STR(name, len, kind)   char name[len];
 A string field in the template definition. More...
 
#define ST_FIELD(type, name, kind)   type name;
 A C basic type field in the template definition. More...
 
#define ST_STRUCT_END   };
 End of the template definition.
 

Detailed Description

This header is used to generate C type definitions and corresponding runtime type information for data structures that are shared by SolarCapture with other processes.

In order to create runtime type information a template header file must be created. For example a node called my_node could have a template file my_node_tmpl.h as follows

ST_STRUCT(my_node_stats)
  ST_FIELD(double,   some_stat,         config)
  ST_FIELD(int,      some_other_stat,   pkt_count)
  ST_FIELD(double,   another_stat,      magnitude)
  ST_FIELD(double,   yet_one_more_stat, ev_count)
  ...
ST_STRUCT_END

In the node source file the node must

  1. Define SC_TYPE_TEMPLATE to be a header file containing the node's type template definition.
  2. Define SC_DECLARE_TYPES to be the name of the declaration function to create.
  3. Include declare_types.h
  4. Call the function defined by (2)
  5. Call sc_node_export_state to allocate a struct of the type defined in the node's type template definition.

Stats can them be updated by changing the values of the fields in the newly created struct from step (5). If stats need to be updated during runtime a means of accessing this struct should be kept in the nodes nd_private field.

For example, a node which would like to create a declaration function with name my_node_declare using the template my_node_tmpl.h would do the following

#define SC_TYPE_TEMPLATE  <my_node_tmpl.h>
#define SC_DECLARE_TYPES my_node_declare
#include <solar_capture/declare_types.h>

...

static int my_node_init(struct sc_node* node, const struct sc_attr* attr,
                const struct sc_node_factory* factory)
{
  ...
  my_node_declare(sc_thread_get_session(sc_node_get_thread(node)));
  ...
  struct my_node_stats* stats;
  sc_node_export_state(node, "my_node_stats",
                 sizeof(struct my_node_stats), &stats);

Macro Definition Documentation

#define ST_CONSTANT (   name,
  val 
)    enum { name = val };a

A constant value in the template definition.

After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.

Parameters
nameThe field name.
valThe constant.
#define ST_FIELD (   type,
  name,
  kind 
)    type name;

A C basic type field in the template definition.

After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.

Parameters
typeThe basic data type.
nameThe field name.
kindA string to describe the kind of data. Examples used by SolarCapture nodes are pkt_count, ev_count, config, const, magnitude.
#define ST_FIELD_STR (   name,
  len,
  kind 
)    char name[len];

A string field in the template definition.

After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.

Parameters
nameThe field name.
lenThe length of the string.
kindA string to describe the kind of data. Examples used by SolarCapture nodes are pkt_count, ev_count, config, const, magnitude.
#define ST_STRUCT (   name)    struct name {

Start of the template definition.

After the node has initialised its shared data structures the resulting struct type for updating the stats will use name for its type.

Parameters
nameThe name of the template.