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

Sc_node: An object that processes packets. More...

Functions

int sc_node_alloc (struct sc_node **node_out, const struct sc_attr *attr, struct sc_thread *thread, const struct sc_node_factory *factory, const struct sc_arg *args, int n_args)
 Allocate a packet processing node. More...
 
int sc_node_alloc_named (struct sc_node **node_out, const struct sc_attr *attr, struct sc_thread *thread, const char *factory_name, const char *lib_name, const struct sc_arg *args, int n_args)
 Allocate a packet processing node by name. More...
 
int sc_node_alloc_from_str (struct sc_node **node_out, const struct sc_attr *attr, struct sc_thread *thread, const char *node_spec)
 Allocate a packet processing node using a string specification. More...
 
int sc_node_add_link (struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt)
 Add a link from one node to another. More...
 
struct sc_thread * sc_node_get_thread (const struct sc_node *node)
 Return the thread associated with a node. More...
 
int sc_node_factory_lookup (const struct sc_node_factory **factory_out, struct sc_session *session, const char *factory_name, const char *lib_name)
 Find a node factory. More...
 
void sc_node_add_info_str (struct sc_node *node, const char *field_name, const char *field_val)
 Export information to solar_capture_monitor. More...
 
void sc_node_add_info_int (struct sc_node *node, const char *field_name, int64_t field_val)
 Export information to solar_capture_monitor. More...
 
struct sc_objectsc_node_to_object (struct sc_node *node)
 Convert an sc_node to an sc_object. More...
 
struct sc_nodesc_node_from_object (struct sc_object *obj)
 Convert an sc_object to an sc_node. More...
 

Detailed Description

Sc_node: An object that processes packets.

Function Documentation

void sc_node_add_info_int ( struct sc_node node,
const char *  field_name,
int64_t  field_val 
)

Export information to solar_capture_monitor.

Parameters
nodeThe node exporting state.
field_nameName of field.
field_valState to export.

Use this function to export static runtime information about a node to solar_capture_monitor. This function can be used in the implementation of a new node type, or in an application using a node.

See also sc_node_add_info_str() and sc_node_export_state().

void sc_node_add_info_str ( struct sc_node node,
const char *  field_name,
const char *  field_val 
)

Export information to solar_capture_monitor.

Parameters
nodeThe node exporting state.
field_nameName of field.
field_valState to export.

Use this function to export static runtime information about a node to solar_capture_monitor. This function can be used in the implementation of a new node type, or in an application using a node.

See also sc_node_add_info_int() and sc_node_export_state().

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

Add a link from one node to another.

Parameters
from_nodeNode to connect from.
link_nameName of the from_node's egress link.
to_nodeNode to connect to.
to_name_optOptional ingress port name (may be NULL).
Returns
0 on success, or a negative error code.

Packets flow from node to node along links. This function adds a link from from_node to to_node.

link_name identifies from_node's egress link. By convention the default egress link is named "".

Some node types support multiple ingress ports so that the node can receive and separate multiple incoming packet streams. The name of the ingress port is given by to_name_opt.

Since SolarCapture 1.1, if the nodes are in different threads then this function automatically creates a link between the threads using mailboxes.

int sc_node_alloc ( struct sc_node **  node_out,
const struct sc_attr attr,
struct sc_thread *  thread,
const struct sc_node_factory factory,
const struct sc_arg args,
int  n_args 
)

Allocate a packet processing node.

Parameters
node_outThe allocated node is returned here
attrAttributes
threadThe thread the node will be in
factoryA node factory
argsAn array of arguments for node initialisation
n_argsThe number of arguments
Returns
0 on success, or a negative error code.

Nodes perform packet processing services such as filtering, packet modification, import/export and packet injection.

A node factory allocates nodes of a particular type, and the argument list provides configuration for the node instance.

Use this function when you have a pointer to the node factory. For built-in nodes or nodes in a separate library it is simpler to use sc_node_alloc_named().

int sc_node_alloc_from_str ( struct sc_node **  node_out,
const struct sc_attr attr,
struct sc_thread *  thread,
const char *  node_spec 
)

Allocate a packet processing node using a string specification.

Parameters
node_outThe allocated node is returned here.
attrAttributes.
threadThe thread the node will be in.
node_specString giving the node type and arguments.
Returns
0 on success, or a negative error code.

This function allocates a node as specified in node_spec, which is formatted as follows:

NODE_SPEC := NODE_TYPE [":" ARGS] ARGS := NAME=VAL [";" ARGS]

Example: "sc_vi_node:interface=eth4;streams=all"

int sc_node_alloc_named ( struct sc_node **  node_out,
const struct sc_attr attr,
struct sc_thread *  thread,
const char *  factory_name,
const char *  lib_name,
const struct sc_arg args,
int  n_args 
)

Allocate a packet processing node by name.

Parameters
node_outThe allocated node is returned here.
attrAttributes.
threadThe thread the node will be in.
factory_nameName of the node factory.
lib_nameName of the node library (may be NULL).
argsAn array of arguments for node initialisation.
n_argsThe number of arguments.
Returns
0 on success, or a negative error code.

Nodes perform packet processing services such as filtering, packet modification, import/export and packet injection.

This function allocates a node of type factory_name, and the argument list provides configuration for the node instance.

This function is a short-cut for sc_node_factory_lookup() followed by sc_node_alloc().

int sc_node_factory_lookup ( const struct sc_node_factory **  factory_out,
struct sc_session *  session,
const char *  factory_name,
const char *  lib_name 
)

Find a node factory.

Parameters
factory_outThe node factory found.
sessionThe SolarCapture session.
factory_nameName of the node factory.
lib_nameName of the node library (may be NULL).
Returns
0 on success, or a negative error code.

Finds the factory of name factory_name. It may be a built-in factory (in which case lib_name should be NULL) or a factory in an external library.

A factory library is a shared object file that contains one or more node factory instances.

lib_name may be NULL, in which case it defaults to being the same as the factory_name.

If lib_name contains a '/' character it is treated as the full path to the library object file.

Otherwise lib_name is the name of the library object file (either with or without a .so suffix). This function will search for the library object file in the following directories (in order):

  • the current working directory
  • directories specified by the SC_NODE_PATH environment variable
  • /usr/lib64/solar_capture/site-nodes
  • /usr/lib/x86_64-linux-gnu/solar_capture/site-nodes
  • /usr/lib64/solar_capture/nodes
  • /usr/lib/x86_64-linux-gnu/solar_capture/nodes

Depending on the target system, not all of the above directories may exist. In particular, the subdirectories of /usr/lib/x86_64-linux-gnu/ will only exist on Debian-derived systems using the multiarch structure for library folders. This is not expected to cause a problem at runtime.

If we decide to support 32-bit builds again, these directories will be searched instead (in order):

  • the current working directory
  • directories specified by the SC_NODE_PATH environment variable
  • /usr/lib/solar_capture/site-nodes
  • /usr/lib/i386-linux-gnu/solar_capture/site-nodes
  • /usr/lib/solar_capture/nodes
  • /usr/lib/i386-linux-gnu/solar_capture/nodes

If a library containing the named factory is not found by this search, the built-in nodes are searched last.

struct sc_node* sc_node_from_object ( struct sc_object obj)

Convert an sc_object to an sc_node.

Parameters
objAn sc_object instance or NULL
Returns
NULL if obj is NULL otherwise the sc_node.

Also returns NULL if obj is not of type SC_OBJ_NODE.

struct sc_thread* sc_node_get_thread ( const struct sc_node node)

Return the thread associated with a node.

Parameters
nodeThe node.
Returns
The thread associated with the node.
struct sc_object* sc_node_to_object ( struct sc_node node)

Convert an sc_node to an sc_object.

Parameters
nodeAn sc_node instance or NULL
Returns
NULL if node is NULL otherwise the sc_object.