libtrap  1.17.0
Libtrap

TRAP is represented by a shared object called libtrap. It is dynamically linked with every Nemea module. This library implements the communication interfaces used by all Nemea modules to exchange data. There are different types of interfaces using various underlying methods of communication (TCP/IP, Unix domain socket, shared memory) and each interface has several parameters. However, libtrap abstracts a module from the underlying interface and its specifics. The main features of libtrap are:

  • Blocking or non-blocking mode of transmission based on configuration parameters
  • Buffering for throughput increase
  • Automatic reconnection after failure
  • Local or remote machine communication

The interface type and behaviour is fully configurable by module and is usually set by user when module starts. Because some interface types support communication over a network, the system may be easily distributed on several hosts.

Libtrap supplies Simple API and Context API, both using Common libtrap API. For writing new Nemea modules, Nemea module macros can be useful.

The example of usage in pseudocode:

trap_ctx_t *ctx = NULL;
int res;
ctx = trap_ctx_init(...);
if (ctx != NULL) {
trap_ctx_ifcctl(ctx, TRAPIFC_OUTPUT /* direction */,
0 /* ifc index */, TRAPCTL_SETTIMEOUT,
res = trap_ctx_recv(ctx, 0 /* in ifc idx */, &d, &ds);
if (res != TRAP_E_OK) {
/* recv failed */
}
res = trap_ctx_send(ctx, 0 /* out ifc idx */, d, ds);
if (res != TRAP_E_OK) {
/* send failed */
}
}
@ TRAPCTL_SETTIMEOUT
Set interface timeout (int32_t): in microseconds for non-blocking mode; timeout can be also: TRAP_WAI...
Definition: trap.h:201
int trap_ctx_recv(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size)
Read data from input interface.
trap_ctx_t * trap_ctx_init(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec)
Initialize and return the context of libtrap.
int trap_ctx_finalize(trap_ctx_t **ctx)
Terminate libtrap context and free resources.
int trap_ctx_ifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request,...)
Control TRAP interface.
int trap_ctx_send(trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size)
Send data via output interface.
#define TRAP_E_OK
Success, no error.
Definition: trap.h:87
@ TRAPIFC_OUTPUT
interface is used for sending data out of module
Definition: trap.h:185
#define TRAP_HALFWAIT
Definition: trap.h:130
#define trap_ctx_t
Definition: trap.h:59

To initialize libtrap, module_info and ifc_spec must be provided. The trap_parse_params() function can be used to prepare ifc_spec from process arguments.

The trap_module_info_s parameter is usually defined in the beginning of Nemea modules. It contains module's name and description.