SolarCapture C Bindings User Guide  SF-115721-CD
Draft 2A
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
ext_node.h File Reference

Interface for writing custom nodes. More...

#include <stdarg.h>

Data Structures

struct  sc_node
 Description of a node. More...
 
struct  sc_node_link
 Description of a link the node has. More...
 
struct  sc_node_factory
 Struct to hold information about how to create an instance of this node. More...
 
struct  sc_node_type
 Describes a type of node. More...
 

Macros

#define sc_node_set_error(node, errno_code,...)
 Set error from within the implementation of a node. More...
 
#define sc_node_set_errorv(node, errno_code, fmt, args)
 Set error from within the implementation of a node. More...
 
#define sc_node_fwd_error(node, rc)   __sc_node_fwd_error((node), __FILE__, __LINE__, __func__, (rc))
 Forward error from a failed sc call. More...
 

Typedefs

typedef int( sc_node_init_fn )(struct sc_node *node, const struct sc_attr *attr, const struct sc_node_factory *factory)
 Signature of function to initialise a node. More...
 
typedef int( sc_node_prep_fn )(struct sc_node *node, const struct sc_node_link *const *links, int n_links)
 Signature of nt_prep_fn function. More...
 
typedef void( sc_node_pkts_fn )(struct sc_node *node, struct sc_packet_list *packet_list)
 Signature of nt_pkts_fn function. More...
 
typedef int( sc_node_add_link_fn )(struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt)
 Signature of nt_add_link_fn function. More...
 
typedef struct sc_node *( sc_node_select_subnode_fn )(struct sc_node *node, const char *name_opt, char **new_name_out)
 Signature of nt_select_subnode_fn function. More...
 
typedef void( sc_node_end_of_stream_fn )(struct sc_node *node)
 Signature of nt_end_of_stream_fn function. More...
 

Functions

int sc_node_type_alloc (struct sc_node_type **nt_out, const struct sc_attr *attr_opt, const struct sc_node_factory *factory)
 Allocate an sc_node_type instance. More...
 
void sc_forward_list (struct sc_node *node, const struct sc_node_link *link, struct sc_packet_list *pl)
 Forward a list of packets. More...
 
void sc_forward_list2 (const struct sc_node_link *link, struct sc_packet_list *pl)
 Forward a list of packets. More...
 
void sc_forward (struct sc_node *node, const struct sc_node_link *link, struct sc_packet *packet)
 Forward a single packet. More...
 
void sc_forward2 (const struct sc_node_link *link, struct sc_packet *packet)
 Forward a single packet. More...
 
int sc_node_init_get_arg_int (int *v_out, struct sc_node *node, const char *name, int v_default)
 Get an integer argument. More...
 
int sc_node_init_get_arg_int64 (int64_t *v_out, struct sc_node *node, const char *name, int64_t v_default)
 Get a 64 bit integer argument. More...
 
int sc_node_init_get_arg_str (const char **v_out, struct sc_node *node, const char *name, const char *v_default)
 Get an string argument. More...
 
int sc_node_init_get_arg_obj (struct sc_object **obj_out, struct sc_node *node, const char *name, enum sc_object_type obj_type)
 Get an sc_object argument. More...
 
int sc_node_init_get_arg_dbl (double *v_out, struct sc_node *node, const char *name, double v_default)
 Get a double argument. More...
 
struct sc_node_linksc_node_prep_get_link (struct sc_node *node, const char *link_name)
 Find a named outgoing link. More...
 
struct sc_node_linksc_node_prep_get_link_or_free (struct sc_node *node, const char *link_name)
 Find a named outgoing link or return a link for freeing. More...
 
int sc_node_prep_check_links (struct sc_node *node)
 Check the node's links for any unused links. More...
 
int sc_node_prep_get_pool (struct sc_pool **pool_out, const struct sc_attr *attr, struct sc_node *node, const struct sc_node_link *const *links, int n_links)
 Get a packet pool that can be used to obtain empty packet buffers that can be passed to any of the given set of links. More...
 
void sc_node_prep_does_not_forward (struct sc_node *node)
 Indicate that this node does not forward to all of its links. More...
 
void sc_node_prep_link_forwards_from_node (struct sc_node *node, const struct sc_node_link *link, struct sc_node *from_node)
 Indicate that packets arriving at a node pass through a link. More...
 
void sc_node_link_end_of_stream (struct sc_node *node, const struct sc_node_link *link)
 Indicate end-of-stream on a link. More...
 
void sc_node_link_end_of_stream2 (const struct sc_node_link *link)
 Indicate end-of-stream on a link. More...
 
int sc_node_export_state (struct sc_node *node, const char *type_name, int type_size, void *pp_area)
 Export dynamic state to solar_capture_monitor. More...
 

Detailed Description

Interface for writing custom nodes.

Macro Definition Documentation

#define sc_node_fwd_error (   node,
  rc 
)    __sc_node_fwd_error((node), __FILE__, __LINE__, __func__, (rc))

Forward error from a failed sc call.

Parameters
nodeThe node that forwards the error
rcThe error code returned by the sc call

Call this function to propagate an error generated by SolarCapture.

#define sc_node_set_error (   node,
  errno_code,
  ... 
)
Value:
__sc_node_set_error((node), __FILE__, __LINE__, __func__, \
(errno_code), __VA_ARGS__)

Set error from within the implementation of a node.

Parameters
nodeThe node that originates the error
errno_codeAn error code from errno.h (or can be zero)

Call this function when returning an error to SolarCapture from a node. The value returned by this function should be passed on to the caller of the function reporting the error.

#define sc_node_set_errorv (   node,
  errno_code,
  fmt,
  args 
)
Value:
__sc_node_set_errorv((node), __FILE__, __LINE__, __func__, \
(errno_code), (fmt), (args))

Set error from within the implementation of a node.

Parameters
nodeThe node that originates the error
errno_codeAn error code from errno.h (or can be zero)
fmtvprintf style format string
argsvprintf arguments matching format string

Call this function when returning an error to SolarCapture from a node. The value returned by this function should be passed on to the caller of the function reporting the error.

See also sc_node_set_error.

Typedef Documentation

typedef int( sc_node_add_link_fn)(struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt)

Signature of nt_add_link_fn function.

Parameters
from_nodeThe node being linked from
link_nameThe name of the link
to_nodeThe node being linked to
to_name_optOptional name of ingress link

This method is optional and supports compound nodes. It is invoked on from_node when sc_node_add_link(from_node, link_name, to_node, to_name_opt) is called, and gives the implementation an opportunity to select the subnode(s) to be linked from or issue an error if an attempt is made to create an unwanted link.

The implementation of this function should invoke sc_node_add_link() on from_node or on a subnode, or should return an error. If it returns an error it should do so by calling sc_node_set_error with a suitable error message, and return the value returned by sc_node_set_error.

The to_node and to_name_opt arguments should be passed unmodified. The implementation may invoke sc_node_add_link() multiple times to create links from multiple subnodes.

typedef void( sc_node_end_of_stream_fn)(struct sc_node *node)

Signature of nt_end_of_stream_fn function.

Parameters
nodeThe node.

This method is invoked when all incoming upstream nodes have indicated end-of-stream. After this method has been called sc_node_pkts_fn will not be called again. The implementation of this function may propagate end-of-stream through its outgoing links by calling sc_node_link_end_of_stream(). If this function is not provided end-of-stream will not propagate further through the node graph.

After the node has propagated end-of-stream to a node through its outgoing link it should not pass any more packets to this node.

This method is optional.

typedef int( sc_node_init_fn)(struct sc_node *node, const struct sc_attr *attr, const struct sc_node_factory *factory)

Signature of function to initialise a node.

Parameters
nodeThe node being initialised
attrAttributes used to create the node
factoryThe node factory

This callback is used to initialise the private state of a node instance. It is called in response to sc_node_alloc() (or similar).

This function must set sc_node::nd_type before invoking any other function call on the node.

The lifetime of the attr argument is limited to this call only. Use sc_attr_dup() if a copy is needed after this call returns.

typedef void( sc_node_pkts_fn)(struct sc_node *node, struct sc_packet_list *packet_list)

Signature of nt_pkts_fn function.

Parameters
nodeThe node receiving the packets
packet_listList of packets

This function will be called when packets are received on any incoming link to the node. It is not possible to distinguish which incoming link the packets arrived from directly. If the node needs to distinguish between incoming streams then either upstream nodes must append metadata to the packets or the node must be constructed from subnodes with each subnode connected to a subset of incoming links.

Once this function is invoked the node gets ownership of the packets. Ownership is relinquished by invoking sc_forward_list, sc_forward_list2, sc_forward or sc_forward2 to forward or free the packets.

typedef int( sc_node_prep_fn)(struct sc_node *node, const struct sc_node_link *const *links, int n_links)

Signature of nt_prep_fn function.

Parameters
nodeThe node being prepared
linksArray of outgoing links the node has
n_linksNumber of outgoing links in the array

This callback is invoked to prepare node for live packet processing. The implementation typically checks the egress links and saves them to private storage.

Any initialisation that could not be done in sc_node_init should be done here.

If the node needs to create subnodes and establish links it should be done before this stage in one of sc_node_init_fn, sc_node_select_subnode_fn or sc_node_add_link_fn.

Note that the array links is only valid for the duration of this function call, but the sc_node_link objects are valid for at least the lifetime of the node.

typedef struct sc_node*( sc_node_select_subnode_fn)(struct sc_node *node, const char *name_opt, char **new_name_out)

Signature of nt_select_subnode_fn function.

Parameters
nodeThe node being linked to
name_optThe name of the link (may be NULL)
new_name_outUse to set a different name for sub-node

This method is optional and supports compound nodes. It is invoked on to_node when sc_node_add_link(from_node, link_name, to_node, to_name_opt) is called, and gives the implementation an opportunity to select an alternative subnode that should be linked to or issue an error if an attempt is made to create an unwanted link.

The implementation should return node or a subnode, or NULL to indicate that name_opt2 is not valid for this node. If returning NULL the implementation should first call sc_node_set_error() to give the reason for the error.

name_opt2 comes from the to_name_opt argument passed to sc_node_add_link(), and may be NULL. If multiple links are added with the same non-NULL name_opt2 then they should be treated as being logically the same link.

If a new name is specified via new_name_out then ownership is passed to the caller, and it will be freed with free().

Function Documentation

void sc_forward ( struct sc_node node,
const struct sc_node_link link,
struct sc_packet packet 
)

Forward a single packet.

Parameters
nodeThe node
linkThe link to forward through
packetThe packet to forward

See also sc_forward2.

void sc_forward2 ( const struct sc_node_link link,
struct sc_packet packet 
)

Forward a single packet.

Parameters
linkThe link to forward through
packetThe packet to forward
void sc_forward_list ( struct sc_node node,
const struct sc_node_link link,
struct sc_packet_list pl 
)

Forward a list of packets.

Parameters
nodeThe node
linkThe link to forward through
plThe list of packets to forward

See also sc_forward_list2.

void sc_forward_list2 ( const struct sc_node_link link,
struct sc_packet_list pl 
)

Forward a list of packets.

Parameters
linkThe link to forward through
plThe list of packets to forward
int sc_node_export_state ( struct sc_node node,
const char *  type_name,
int  type_size,
void *  pp_area 
)

Export dynamic state to solar_capture_monitor.

Parameters
nodeThe node exporting state
type_nameName of the exported datastructure
type_sizeSize in bytes of the exported datastructure
pp_areaPointer to memory is returned here
Returns
0 on success, or a negative error code.

Use this function to export dynamic runtime information about a node to solar_capture_monitor. The information can include configuration information, statistics and/or other runtime state.

pp_area gives the address of a pointer that is overwritten with a pointer to the memory area large enough for an instance of type_name. So pp_area should be of type 'struct type_name**'.

The type type_name must already have been declared by creating the type_name_declare() function using declare_types.h::SC_DECLARE_TYPES and calling it.

See also sc_node_add_info_str() and sc_node_add_info_int(), which are useful for exporting static data.

int sc_node_init_get_arg_dbl ( double *  v_out,
struct sc_node node,
const char *  name,
double  v_default 
)

Get a double argument.

Parameters
v_outOn success, the value is returned here
nodeThe node
nameThe name of the argument
v_defaultDefault returned if arg not found
Returns
0 on success
1 if the argument is not found (in which case v_default is copied
to v_out)
-1 if the argument was found but is of the wrong type.

This may only be called from sc_node_init_fn.

int sc_node_init_get_arg_int ( int *  v_out,
struct sc_node node,
const char *  name,
int  v_default 
)

Get an integer argument.

Parameters
v_outOn success, the value is returned here
nodeThe node
nameThe name of the argument
v_defaultDefault returned if arg not found
Returns
0 on success
1 if the argument is not found (in which case v_default is copied
to v_out)
-1 if the argument was found but is of the wrong type.

This may only be called from sc_node_init_fn.

int sc_node_init_get_arg_int64 ( int64_t *  v_out,
struct sc_node node,
const char *  name,
int64_t  v_default 
)

Get a 64 bit integer argument.

Parameters
v_outOn success, the value is returned here
nodeThe node
nameThe name of the argument
v_defaultDefault returned if arg not found
Returns
0 on success
1 if the argument is not found (in which case v_default is copied
to v_out)
-1 if the argument was found but is of the wrong type.

This may only be called from sc_node_init_fn.

int sc_node_init_get_arg_obj ( struct sc_object **  obj_out,
struct sc_node node,
const char *  name,
enum sc_object_type  obj_type 
)

Get an sc_object argument.

Parameters
obj_outOn success, the value is returned here
nodeThe node
nameThe name of the argument
obj_typeThe type of object wanted, or SC_OBJ_ANY
Returns
0 on success
1 if the argument is not found (in which case v_default is copied
to v_out)
-1 if the argument was found but is of the wrong type.

This may only be called from sc_node_init_fn.

int sc_node_init_get_arg_str ( const char **  v_out,
struct sc_node node,
const char *  name,
const char *  v_default 
)

Get an string argument.

Parameters
v_outOn success, the value is returned here
nodeThe node
nameThe name of the argument
v_defaultDefault returned if arg not found
Returns
0 on success
1 if the argument is not found (in which case v_default is copied
to v_out)
-1 if the argument was found but is of the wrong type.

This may only be called from sc_node_init_fn.

The string returned is valid only until the sc_node_init_fn call returns.

void sc_node_link_end_of_stream ( struct sc_node node,
const struct sc_node_link link 
)

Indicate end-of-stream on a link.

Parameters
nodeThe node
linkThe link

It is a fatal error to forward any further packets through the link after calling this function.

void sc_node_link_end_of_stream2 ( const struct sc_node_link link)

Indicate end-of-stream on a link.

Parameters
linkThe link

It is a fatal error to forward any further packets through the link after calling this function.

int sc_node_prep_check_links ( struct sc_node node)

Check the node's links for any unused links.

Parameters
nodeThe node
Returns
0 if all is fine (or only warnings are needed)
-1 on error, which should be propagated out of sc_node_prep_fn().

This may only be called from sc_node_prep_fn(), and should only be used by nodes that find their links by calling sc_node_prep_get_link().

This function will complain about any links added to the node that have not been queried by sc_node_prep_get_link(). It may emit a warning, or generate an error.

void sc_node_prep_does_not_forward ( struct sc_node node)

Indicate that this node does not forward to all of its links.

Parameters
nodeA node

By default it is assumed that packets arriving at a node may be forwarded through any of the node's outgoing links. The effect of this call is to break that assumption. SolarCapture will assume that packets arriving at node are not forwarded via any of the outgoing links, unless overridden by sc_node_prep_link_forwards_from_node.

struct sc_node_link* sc_node_prep_get_link ( struct sc_node node,
const char *  link_name 
)

Find a named outgoing link.

Parameters
nodeThe node
link_nameName of the link
Returns
The named link, or NULL if the named link doesn't exist.

A node's sc_node_prep_fn can either use this mechanism to query its links, or it can simply iterate over the links passed as arguments to sc_node_prep_fn.

This function may only be called from sc_node_prep_fn.

See also sc_node_prep_check_links().

struct sc_node_link* sc_node_prep_get_link_or_free ( struct sc_node node,
const char *  link_name 
)

Find a named outgoing link or return a link for freeing.

Parameters
nodeThe node
link_nameName of the link
Returns
The named link, or a special link that frees packets if the named link doesn't exist.

This function behaves just like sc_node_prep_get_link(), except that if no link of that name has been added to the node, a special link is returned that frees packets.

link_name may be NULL, in which case a link for freeing packets is returned.

int sc_node_prep_get_pool ( struct sc_pool **  pool_out,
const struct sc_attr attr,
struct sc_node node,
const struct sc_node_link *const *  links,
int  n_links 
)

Get a packet pool that can be used to obtain empty packet buffers that can be passed to any of the given set of links.

Parameters
pool_outOn success, the pool is returned here
attrPacket pool attributes (optional, may be NULL)
nodeThe node
linksThe link(s) packets from the pool may be passed to (set to NULL for all)
n_linksNumber of links in 'links' (set to 0 for all)
Returns
0 on success, or a negative error code.

The node must only forward packets from the returned pool over the links identified by links and n_links. If n_links is 0 then it is assumed that packets from the pool may be forwarded over any of the node's links.

Restricting the links packets can be sent along allows SolarCapture to optimise the releasing of packets back to the pool when the node graph is finished with them.

This may only be called from sc_node_prep_fn.

void sc_node_prep_link_forwards_from_node ( struct sc_node node,
const struct sc_node_link link,
struct sc_node from_node 
)

Indicate that packets arriving at a node pass through a link.

Parameters
nodeThe node that link originates from
linkA link from node to another node
from_nodeNode at which packets arrive

This call tells SolarCapture that packets arriving at from_node are forwarded via link.

You will also need to call sc_node_prep_does_not_forward to cancel the default assumption that all links are used for forwarding.

Note that most nodes do not need to use this function, because SolarCapture assumes by default that packets arriving at a node may be forwarded through any of the node's outgoing links. This call is useful when either (a) only a subset of links are used for forwarding or (b) a node forwards packets that arrived at a different node.

int sc_node_type_alloc ( struct sc_node_type **  nt_out,
const struct sc_attr attr_opt,
const struct sc_node_factory factory 
)

Allocate an sc_node_type instance.

Parameters
nt_outThe allocated sc_node_type instance
attr_optOptional attributes (may be NULL)
factoryThe factory that created the node
Returns
0 on success, or a negative error code.

At the time of writing attr_opt is not used and this call always succeeds. In future it may fail if the attributes are invalid in some way.