![]() |
SolarCapture C Bindings User Guide
SF-115721-CD
Draft 2A
|
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_link * | sc_node_prep_get_link (struct sc_node *node, const char *link_name) |
Find a named outgoing link. More... | |
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. 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... | |
Interface for writing custom nodes.
#define sc_node_fwd_error | ( | node, | |
rc | |||
) | __sc_node_fwd_error((node), __FILE__, __LINE__, __func__, (rc)) |
Forward error from a failed sc call.
node | The node that forwards the error |
rc | The 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, | |||
... | |||
) |
Set error from within the implementation of a node.
node | The node that originates the error |
errno_code | An 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 | |||
) |
Set error from within the implementation of a node.
node | The node that originates the error |
errno_code | An error code from errno.h (or can be zero) |
fmt | vprintf style format string |
args | vprintf 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 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.
from_node | The node being linked from |
link_name | The name of the link |
to_node | The node being linked to |
to_name_opt | Optional 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.
node | The 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.
node | The node being initialised |
attr | Attributes used to create the node |
factory | The 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.
node | The node receiving the packets |
packet_list | List 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.
node | The node being prepared |
links | Array of outgoing links the node has |
n_links | Number 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.
node | The node being linked to |
name_opt | The name of the link (may be NULL) |
new_name_out | Use 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().
void sc_forward | ( | struct sc_node * | node, |
const struct sc_node_link * | link, | ||
struct sc_packet * | packet | ||
) |
Forward a single packet.
node | The node |
link | The link to forward through |
packet | The packet to forward |
See also sc_forward2.
void sc_forward2 | ( | const struct sc_node_link * | link, |
struct sc_packet * | packet | ||
) |
Forward a single packet.
link | The link to forward through |
packet | The 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.
node | The node |
link | The link to forward through |
pl | The 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.
link | The link to forward through |
pl | The 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.
node | The node exporting state |
type_name | Name of the exported datastructure |
type_size | Size in bytes of the exported datastructure |
pp_area | Pointer to memory is returned here |
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.
v_out | On success, the value is returned here |
node | The node |
name | The name of the argument |
v_default | Default returned if arg not found |
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.
v_out | On success, the value is returned here |
node | The node |
name | The name of the argument |
v_default | Default returned if arg not found |
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.
v_out | On success, the value is returned here |
node | The node |
name | The name of the argument |
v_default | Default returned if arg not found |
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.
obj_out | On success, the value is returned here |
node | The node |
name | The name of the argument |
obj_type | The type of object wanted, or SC_OBJ_ANY |
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.
v_out | On success, the value is returned here |
node | The node |
name | The name of the argument |
v_default | Default returned if arg not found |
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.
node | The node |
link | The 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.
link | The 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.
node | The node |
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.
node | A 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.
node | The node |
link_name | Name of the link |
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.
node | The node |
link_name | Name of the link |
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.
pool_out | On success, the pool is returned here |
attr | Packet pool attributes (optional, may be NULL) |
node | The node |
links | The link(s) packets from the pool may be passed to (set to NULL for all) |
n_links | Number of links in 'links' (set to 0 for all) |
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.
node | The node that link originates from |
link | A link from node to another node |
from_node | Node 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.
nt_out | The allocated sc_node_type instance |
attr_opt | Optional attributes (may be NULL) |
factory | The factory that created the node |
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.