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

sc_vi: Supports receiving packets from the network. More...

Functions

int sc_vi_alloc (struct sc_vi **vi_out, const struct sc_attr *attr, struct sc_thread *thread, const char *interface)
 Allocate a VI instance. More...
 
int sc_vi_set_recv_node (struct sc_vi *vi, struct sc_node *node, const char *name_opt)
 Set the node a VI should deliver its received packets to. More...
 
int sc_vi_add_stream (struct sc_vi *vi, struct sc_stream *stream)
 Direct a packet stream to a VI. More...
 
struct sc_thread * sc_vi_get_thread (const struct sc_vi *vi)
 Return the thread associated with a VI. More...
 
const char * sc_vi_get_interface_name (const struct sc_vi *vi)
 Return the name of the network interface associated with a VI. More...
 
int sc_vi_group_alloc (struct sc_vi_group **vi_out, const struct sc_attr *attr, struct sc_session *session, const char *interface, int num_vis)
 Allocate a VI group. More...
 
struct sc_session * sc_vi_group_get_session (const struct sc_vi_group *vi_group)
 Return the session associated with a VI group. More...
 
int sc_vi_alloc_from_group (struct sc_vi **vi_out, const struct sc_attr *attr, struct sc_thread *thread, struct sc_vi_group *vi_group)
 Allocate a VI instance from a VI group. More...
 
int sc_vi_group_add_stream (struct sc_vi_group *vi_group, struct sc_stream *stream)
 Direct a packet stream to a group of VIs. More...
 

Detailed Description

sc_vi: Supports receiving packets from the network.

Function Documentation

int sc_vi_add_stream ( struct sc_vi vi,
struct sc_stream stream 
)

Direct a packet stream to a VI.

Parameters
viThe VI receiving packets
streamThe packet stream
Returns
0 on success, or a negative error code.

Arrange for the packet stream identified by stream to be copied or steered to vi.

int sc_vi_alloc ( struct sc_vi **  vi_out,
const struct sc_attr attr,
struct sc_thread *  thread,
const char *  interface 
)

Allocate a VI instance.

Parameters
vi_outThe allocated VI is returned here
attrAttributes
threadThe thread the VI will be in
interfaceThe network interface to receive packets from
Returns
0 on success, or a negative error code.

A VI is a "virtual network interface" and supports receiving packets from the network. Packets received by a VI are passed to nodes (sc_node) for processing.

int sc_vi_alloc_from_group ( struct sc_vi **  vi_out,
const struct sc_attr attr,
struct sc_thread *  thread,
struct sc_vi_group *  vi_group 
)

Allocate a VI instance from a VI group.

Parameters
vi_outThe allocated VI is returned here
attrAttributes
threadThe thread the VI will be in
vi_groupThe VI group
Returns
0 on success, or a negative error code.

See also sc_vi_group_alloc() and sc_vi_alloc().

const char* sc_vi_get_interface_name ( const struct sc_vi vi)

Return the name of the network interface associated with a VI.

Parameters
viThe VI
Returns
The name of the network interface associated with the sc_vi object

This call returns the name of the network interface associated with the sc_vi object. This can be different from the interface name used to create the sc_vi when application clustering is used.

The network interface name is most often needed so that the application can create an injector on the same interface as a VI.

struct sc_thread* sc_vi_get_thread ( const struct sc_vi vi)

Return the thread associated with a VI.

Parameters
viThe VI
Returns
The thread associated with the VI.
int sc_vi_group_add_stream ( struct sc_vi_group *  vi_group,
struct sc_stream stream 
)

Direct a packet stream to a group of VIs.

Parameters
vi_groupThe VI group receiving packets
streamThe packet stream
Returns
The session associated with the VI group.

Arrange for the packet stream identified by stream to be copied or steered to the VIs that comprise vi_group.

Note that packets are spread over the VIs in a group by computing a hash on the addresses in the packet headers. Normally the hash is computed over the IP addresses, and for TCP packets also the port numbers. The hash selects a VI within the group, so that packets with the same addresses are consistently delivered to the same VI.

If stream identifies a set of packets that all have the same source and destination IP addresses (and ports in the case of TCP) then they will all be received by a single VI.

int sc_vi_group_alloc ( struct sc_vi_group **  vi_out,
const struct sc_attr attr,
struct sc_session *  session,
const char *  interface,
int  num_vis 
)

Allocate a VI group.

Parameters
vi_outThe allocated VI is returned here
attrAttributes
sessionThe SolarCapture session
interfaceThe network interface to receive packets from
num_visThe number of VIs in the group
Returns
0 on success, or a negative error code.

A VI group provides a way to distribute packet capture over multiple threads. A VI group consists of a set of VIs, each of which receives a distinct subset of the streams directed at the group.

Streams are directed to a group by calling sc_vi_group_add_stream().

While a VI allocated from a group receives packets from streams directed to the group (sc_vi_group_add_stream()), it is also possible to use sc_vi_add_stream() to direct a specific stream to a specific member of the group.

struct sc_session* sc_vi_group_get_session ( const struct sc_vi_group *  vi_group)

Return the session associated with a VI group.

Parameters
vi_groupThe VI group
Returns
The session associated with the VI group.
int sc_vi_set_recv_node ( struct sc_vi vi,
struct sc_node node,
const char *  name_opt 
)

Set the node a VI should deliver its received packets to.

Parameters
viThe VI receiving packets
nodeThe node to deliver packets to
name_optOptional ingress port name (may be NULL)
Returns
0 on success, or a negative error code.

Since SolarCapture 1.1, if node is in a different thread from vi, then this function automatically creates a link between the threads using mailboxes.