libtrap  0.11.7
Functions
Context API

Functions

trap_ctx_ttrap_ctx_init (trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec)
 Initialize and return the context of libtrap. More...
 
trap_ctx_ttrap_ctx_init2 (trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec, const char *service_ifcname)
 Initialize and return the context of libtrap. More...
 
trap_ctx_ttrap_ctx_init3 (const char *name, const char *description, int8_t i_ifcs, int8_t o_ifcs, const char *ifc_spec, const char *service_ifcname)
 Initialize and return the context of libtrap. More...
 
int trap_ctx_finalize (trap_ctx_t **ctx)
 Terminate libtrap context and free resources. More...
 
int trap_ctx_terminate (trap_ctx_t *ctx)
 Terminate libtrap context. More...
 
int trap_ctx_recv (trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size)
 
int trap_ctx_multi_recv (trap_ctx_t *ctx, uint32_t ifc_mask, const void **data, uint16_t *size)
 Read data from input interfaces according to ifc_mask. More...
 
int trap_ctx_send (trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size)
 Send data via output interface. More...
 
void trap_ctx_set_verbose_level (trap_ctx_t *ctx, int level)
 Set verbosity level of library functions. More...
 
int trap_ctx_get_verbose_level (trap_ctx_t *ctx)
 Get verbosity level. More...
 
int trap_ctx_ifcctl (trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request,...)
 Control TRAP interface. More...
 
int trap_ctx_vifcctl (trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, va_list ap)
 Control TRAP interface. More...
 
int trap_ctx_get_last_error (trap_ctx_t *ctx)
 Get last result code from libtrap context. More...
 
const char * trap_ctx_get_last_error_msg (trap_ctx_t *ctx)
 Get last (error) message from libtrap context. More...
 
void trap_ctx_send_flush (trap_ctx_t *ctx, uint32_t ifc)
 Force flush of buffer. More...
 
int trap_ctx_get_client_count (trap_ctx_t *ctx, uint32_t ifcidx)
 Get number of connected clients. More...
 
void trap_ctx_create_ifc_dump (trap_ctx_t *ctx, const char *path)
 Create dump files. More...
 

Detailed Description

This API allows user to use multiple instances of libtrap in the same process.

The API is similar to Simple API. The difference is in the private context memory that is returned by trap_ctx_init() and is freed by trap_ctx_finalize(). Obtained context pointer must be passed to all functions from context API.

Function Documentation

◆ trap_ctx_create_ifc_dump()

void trap_ctx_create_ifc_dump ( trap_ctx_t ctx,
const char *  path 
)

Create dump files.

Create dump files for debug as follows: trap-i[number]-config.txt Output interface configuration. trap-i[number]-buffer.dat Output interface buffer trap-o[number]-config.txt Input interface configuration. trap-o[number]-buffer.dat Input interface buffer

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]pathOutput directory, if NULL use current working directory.

◆ trap_ctx_finalize()

int trap_ctx_finalize ( trap_ctx_t **  ctx)

Terminate libtrap context and free resources.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
Returns
TRAP_E_OK on success.

◆ trap_ctx_get_client_count()

int trap_ctx_get_client_count ( trap_ctx_t ctx,
uint32_t  ifcidx 
)

Get number of connected clients.

Output interface (TCP or UNIX) allows to send messages to multiple clients. This function reads number of connected clients from internal interface structure.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]ifcidxIFC Index of output interface.
Returns
Number of connected clients. -1 on error.

◆ trap_ctx_get_last_error()

int trap_ctx_get_last_error ( trap_ctx_t ctx)

Get last result code from libtrap context.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
Returns
Error codes

◆ trap_ctx_get_last_error_msg()

const char* trap_ctx_get_last_error_msg ( trap_ctx_t ctx)

Get last (error) message from libtrap context.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
Returns
Text string with last (error) message from libtrap context.

◆ trap_ctx_get_verbose_level()

int trap_ctx_get_verbose_level ( trap_ctx_t ctx)

Get verbosity level.

See also
trap_set_verbose_level for the list of levels.
Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
Returns
Verbosity level currently set in the library.

◆ trap_ctx_ifcctl()

int trap_ctx_ifcctl ( trap_ctx_t ctx,
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]ctxPointer to the private libtrap context data (trap_ctx_init()).
[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
Returns
TRAP_E_OK on success

◆ trap_ctx_init()

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.

Parameters
[in]module_infoPointer to struct containing info about the module.
[in]ifc_specStructure with specification of interface types and their parameters.
Returns
Pointer to context (context needs to be checked for error value by trap_ctx_get_last_error() function), NULL on memory error.

◆ trap_ctx_init2()

trap_ctx_t* trap_ctx_init2 ( trap_module_info_t module_info,
trap_ifc_spec_t  ifc_spec,
const char *  service_ifcname 
)

Initialize and return the context of libtrap.

Parameters
[in]module_infoPointer to struct containing info about the module.
[in]ifc_specStructure with specification of interface types and their parameters.
[in]service_ifcnameIdentifier of the service IFC (used as a part of path to the UNIX socket). When NULL is used, no service IFC will be opened.
Returns
Pointer to context (context needs to be checked for error value by trap_ctx_get_last_error() function), NULL on memory error.

◆ trap_ctx_init3()

trap_ctx_t* trap_ctx_init3 ( const char *  name,
const char *  description,
int8_t  i_ifcs,
int8_t  o_ifcs,
const char *  ifc_spec,
const char *  service_ifcname 
)

Initialize and return the context of libtrap.

Parameters
[in]nameName of the NEMEA module (libtrap context).
[in]description- Detailed description of the module, can be NULL ("" will be used in such case)
[in]i_ifcsNumber of input IFCs, it can be -1 if o_ifcs > -1 (-1 means variable number of IFCs, it is then computed from ifc_spec).
[in]o_ifcsNumber of output IFCs, it can be -1 if i_ifcs > -1 (-1 means variable number of IFCs, it is then computed from ifc_spec).
[in]ifc_specIFC_SPEC stringdescribed in README.ifcspec.md
[in]service_ifcnameIdentifier of the service IFC (used as a part of path to the UNIX socket). When NULL is used, no service IFC will be opened.
Returns
Pointer to context (context needs to be checked for error value by trap_ctx_get_last_error() function), NULL on memory error.

◆ trap_ctx_multi_recv()

int trap_ctx_multi_recv ( trap_ctx_t ctx,
uint32_t  ifc_mask,
const void **  data,
uint16_t *  size 
)

Read data from input interfaces according to ifc_mask.

Read a record from one of interfaces specified by ifc_mask and store pointer to it into data. If data are not available on any of specified interfaces, wait until data are available or timeout elapses. If timeout < 0, wait indefinitely. When function returns due to timeout, contents of data and size are undefined.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]ifc_maskMask of interfaces to listen on (if i-th bit is set, interface i is enabled).
[out]dataPointer to received data. The result is an array of trap_multi_result_t. The size of array is equal to the number of input IFCs.
[out]sizeSize of data in bytes containing the size of trap_multi_result_t array in bytes.
Returns
Error code - 0 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_get_data() call.
See also
trap_ctx_ifcctl, trap_multi_result_t

◆ trap_ctx_recv()

int trap_ctx_recv ( trap_ctx_t ctx,
uint32_t  ifc,
const void **  data,
uint16_t *  size 
)

Read data from input interface.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]ifcIndex of input interface (counted from 0).
[out]dataPointer to received data.
[out]sizeSize of received data in bytes.
Returns
Error code - TRAP_E_OK on success, TRAP_E_TIMEOUT if timeout elapses.
See also
trap_ctx_ifcctl

◆ trap_ctx_send()

int trap_ctx_send ( trap_ctx_t ctx,
unsigned int  ifc,
const void *  data,
uint16_t  size 
)

Send data via 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]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]ifcIndex of interface to write into.
[in]dataPointer to data.
[in]sizeNumber of bytes of data.
Returns
Error code - 0 on success, TRAP_E_TIMEOUT if timeout elapses.
See also
trap_ctx_ifcctl

◆ trap_ctx_send_flush()

void trap_ctx_send_flush ( trap_ctx_t ctx,
uint32_t  ifc 
)

Force flush of buffer.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]ifcIFC Index of interface to write into.

◆ trap_ctx_set_verbose_level()

void trap_ctx_set_verbose_level ( trap_ctx_t ctx,
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]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]levelDesired level of verbosity.

◆ trap_ctx_terminate()

int trap_ctx_terminate ( trap_ctx_t ctx)

Terminate libtrap context.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
Returns
TRAP_E_OK on success.

◆ trap_ctx_vifcctl()

int trap_ctx_vifcctl ( trap_ctx_t ctx,
int8_t  type,
uint32_t  ifcidx,
int32_t  request,
va_list  ap 
)

Control TRAP interface.

Parameters
[in]ctxPointer to the private libtrap context data (trap_ctx_init()).
[in]typetrap_ifc_type direction of interface
[in]ifcidxindex of TRAP interface
[in]requesttrap_ifcctl_request type of operation
[in,out]aparguments of request.
Returns
TRAP_E_OK on success
See also
trap_ctx_ifcctl().