libtrap 1.18.1
Simple API

Functions

int trap_free_ifc_spec (trap_ifc_spec_t ifc_spec)
 
int trap_init (trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec)
 
int trap_terminate ()
 
int trap_finalize ()
 
int trap_send_data (unsigned int ifcidx, const void *data, uint16_t size, int timeout)
 
int trap_recv (uint32_t ifcidx, const void **data, uint16_t *size)
 Receive data from input interface.
 
int trap_recv_with_seq_number (uint32_t ifcidx, const void **data, uint16_t *size, uint64_t *seq_number)
 Receive data from input interface with sequence number.
 
void trap_get_input_ifc_stats (uint32_t ifcidx, struct input_ifc_stats *stats)
 Get statistics about input interface.
 
int trap_send (uint32_t ifcidx, const void *data, uint16_t size)
 Send data via output interface.
 
void trap_set_verbose_level (int level)
 
int trap_get_verbose_level ()
 
void trap_set_help_section (int level)
 
void trap_print_help (const trap_module_info_t *module_info)
 
void trap_print_ifc_spec_help ()
 
int trap_ifcctl (int8_t type, uint32_t ifcidx, int32_t request,...)
 Control TRAP interface.
 
void trap_send_flush (uint32_t ifc)
 Force flush of buffer.
 

Variables

int trap_last_error
 Code of last error (one of the codes above)
 
const char * trap_last_error_msg
 Human-readable message about last error.
 

Detailed Description

Function Documentation

◆ trap_finalize()

int trap_finalize ( )

Cleanup function. Disconnect all interfaces and do all necessary cleanup.

Returns
Error code

◆ trap_free_ifc_spec()

int trap_free_ifc_spec ( trap_ifc_spec_t ifc_spec)

Destructor of trap_ifc_spec_t structure.

Parameters
[in]ifc_spectrap_ifc_spec_t structure to clear.
Returns
Error code (0 on success)

◆ trap_get_input_ifc_stats()

void trap_get_input_ifc_stats ( uint32_t ifcidx,
struct input_ifc_stats * stats )

Get statistics about input interface.

Parameters
[out]statsPointer to structure where statistics will be stored.
Note
This function is optional. If not implemented, the zeroed stats are returned.

◆ trap_get_verbose_level()

int trap_get_verbose_level ( )

Get verbosity level. See trap_set_verbose_level for list of levels.

Returns
Verbosity level currently set in the library.

◆ trap_ifcctl()

int trap_ifcctl ( int8_t type,
uint32_t ifcidx,
int32_t request,
... )

Control TRAP interface.

Note
Type and request types were changed from enum because of python wrapper.
Parameters
[in]typetrap_ifc_type direction of interface
[in]ifcidxindex of TRAP interface
[in]requesttrap_ifcctl_request type of operation
[in,out]...arguments of request, see trap_ifcctl_request for more details on requests and their arguments.

Examples:

// set 4 seconds timeout
// disable auto-flush
// disable buffering
@ TRAPCTL_BUFFERSWITCH
Enable/disable buffering - could be dangerous on input interface!!! expects char argument with value ...
Definition trap.h:200
@ TRAPCTL_AUTOFLUSH_TIMEOUT
Set timeout of automatic buffer flushing for interface, expects uint64_t argument with number of micr...
Definition trap.h:199
@ TRAPCTL_SETTIMEOUT
Set interface timeout (int32_t): in microseconds for non-blocking mode; timeout can be also: TRAP_WAI...
Definition trap.h:201
@ TRAPIFC_OUTPUT
interface is used for sending data out of module
Definition trap.h:185
@ TRAPIFC_INPUT
interface acts as source of data for module
Definition trap.h:184
int trap_ifcctl(int8_t type, uint32_t ifcidx, int32_t request,...)
Control TRAP interface.
#define TRAP_NO_AUTO_FLUSH
value to disable autoflushing on output interface
Definition trap.h:134
Returns
TRAP_E_OK on success

◆ trap_init()

int trap_init ( trap_module_info_t * module_info,
trap_ifc_spec_t ifc_spec )

Initialization function. Create and initialize all interfaces.

Parameters
[in]module_infoPointer to struct containing info about the module.
[in]ifc_specStructure with specification of interface types and their parameters.
Returns
Error code (0 on success)

◆ trap_print_help()

void trap_print_help ( const trap_module_info_t * module_info)

Print common TRAP help message. The help message contains information from module_info and describes common TRAP command-line parameters.

Parameters
[in]module_infoPointer to struct containing info about the module.

◆ trap_print_ifc_spec_help()

void trap_print_ifc_spec_help ( )

Print help about interface specifier. Prints help message about format of interface specifier and description of all available interface types. This message is normally a part of help printed by trap_print_help, this function is useful when you don't use standard TRAP command-line parameters but you still use the same format of interface specifier.

◆ trap_recv()

int trap_recv ( uint32_t ifcidx,
const void ** data,
uint16_t * size )

Receive data from input interface.

Receive a message from interface specified by ifcidx and set pointer to the data. When function returns due to timeout, contents of data and size are undefined.

Parameters
[in]ifcidxIndex of input IFC.
[out]dataPointer to received data.
[out]sizeSize of received data in bytes of data.
Returns
Error code - TRAP_E_OK on success, TRAP_E_TIMEOUT if timeout elapses.
Note
Data must not be freed! Library stores incomming data into static array and rewrites it during every trap_recv() call.
See also
trap_ifcctl() to set timeout (TRAPCTL_SETTIMEOUT)

◆ trap_recv_with_seq_number()

int trap_recv_with_seq_number ( uint32_t ifcidx,
const void ** data,
uint16_t * size,
uint64_t * seq_number )

Receive data from input interface with sequence number.

Receive a message from interface specified by ifcidx and set pointer to the data. When function returns due to timeout, contents of data and size are undefined.

Sequence number is used to identify messages. Starts from 1 and is incremented by 1 for every message. If there is a gap in sequence numbers, it means that some messages were lost due to buffer overflow.

Parameters
[in]ifcidxIndex of input IFC.
[out]dataPointer to received data.
[out]sizeSize of received data in bytes of data.
[out]seq_numberSequence number of received message.
Returns
Error code - TRAP_E_OK on success, TRAP_E_TIMEOUT if timeout elapses.
Note
Data must not be freed! Library stores incomming data into static array and rewrites it during every trap_recv() call.
This function is optional. If not implemented, the default trap_recv is used and zero seq_number is returned.
See also
trap_ifcctl() to set timeout (TRAPCTL_SETTIMEOUT)

◆ trap_send()

int trap_send ( uint32_t ifcidx,
const void * data,
uint16_t size )

Send data via output interface.

Send a message given by data pointer of size message size via interface specified by ifcidx that is the index of output interfaces (counted from 0).

Parameters
[in]ifcidxIndex of input IFC.
[out]dataPointer to message to send.
[out]sizeSize of message in bytes.
Returns
Error code - TRAP_E_OK on success, TRAP_E_TIMEOUT if timeout elapses.
See also
trap_ifcctl() to set timeout (TRAPCTL_SETTIMEOUT)

◆ trap_send_data()

int trap_send_data ( unsigned int ifcidx,
const void * data,
uint16_t size,
int timeout )

Send data to output interface. Write data of size size given by data pointer into interface ifc. If data cannot be written immediately (e.g. because of full buffer or lost connection), wait until write is possible or timeout microseconds elapses. If timeout < 0, wait indefinitely.

Parameters
[in]ifcidxIndex of interface to write into.
[in]dataPointer to data.
[in]sizeNumber of bytes of data.
[in]timeoutTimeout in microseconds for non-blocking mode; timeout can be also: TRAP_WAIT, TRAP_HALFWAIT, or TRAP_NO_WAIT.
Returns
Error code - 0 on success, TRAP_E_TIMEOUT if timeout elapses.
Deprecated
This function should be replaced by trap_send().

◆ trap_send_flush()

void trap_send_flush ( uint32_t ifc)

Force flush of buffer.

Parameters
[in]ifcIFC Index of interface to write into.

◆ trap_set_help_section()

void trap_set_help_section ( int level)

Set section for trap_print_help()

Parameters
[in]level0 for default info about module, 1 for info about IFC specifier

◆ trap_set_verbose_level()

void trap_set_verbose_level ( int level)

Set verbosity level of library functions. Verbosity levels may be:

  • -3 - errors
  • -2 - warnings
  • -1 - notices (default)
  • 0 - verbose
  • 1 - more verbose
  • 2 - even more verbose
Parameters
[in]levelDesired level of verbosity.

◆ trap_terminate()

int trap_terminate ( )

Function to terminate module's operation. This function stops all read/write operations on all interfaces. Any waiting in trap_recv() and trap_send()_data is interrupted and these functions return immediately with TRAP_E_TERMINATED. Any call of trap_recv() or trap_send() after call of this function returns TRAP_E_TERMINATED.

This function is used to terminate module's operation (asynchronously), e.g. in SIGTERM handler.

Returns
Always TRAP_E_OK (0).

Variable Documentation

◆ trap_last_error

int trap_last_error
extern

Code of last error (one of the codes above)

◆ trap_last_error_msg

const char* trap_last_error_msg
extern

Human-readable message about last error.