Functions
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. More...

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. More...

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. 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)
	Read data from input interface. 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]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	path	Output directory, if NULL use current working directory.

◆ trap_ctx_finalize()

int trap_ctx_finalize ( trap_ctx_t ** ctx )

Terminate libtrap context and free resources.

This function is thread safe.

Parameters

[in] ctx Pointer 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]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	ifcidx	IFC 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.

This function is thread safe.

Parameters

[in] ctx Pointer 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.

This function is thread safe.

Parameters

[in] ctx Pointer 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] ctx Pointer 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.

This function is thread safe.

Note: Type and request types were changed from enum because of python wrapper.

Parameters

[in]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	type	trap_ifc_type direction of interface
[in]	ifcidx	index of TRAP interface
[in]	request	trap_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
trap_ctx_ifcctl(ctx, TRAPIFC_INPUT, 0, TRAPCTL_SETTIMEOUT, 4000000);
// disable auto-flush
trap_ctx_ifcctl(ctx, TRAPIFC_OUTPUT, 0, TRAPCTL_AUTOFLUSH_TIMEOUT, TRAP_NO_AUTO_FLUSH);
// disable buffering
trap_ctx_ifcctl(ctx, TRAPIFC_OUTPUT, 0, TRAPCTL_BUFFERSWITCH, 0);

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.

This function is thread safe.

Parameters

[in]	module_info	Pointer to struct containing info about the module.
[in]	ifc_spec	Structure 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.

This function is thread safe.

Parameters

[in]	module_info	Pointer to struct containing info about the module.
[in]	ifc_spec	Structure with specification of interface types and their parameters.
[in]	service_ifcname	Identifier 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.

This function is thread safe.

Parameters

[in]	name	Name of the NEMEA module (libtrap context).
[in]	description	- Detailed description of the module, can be NULL ("" will be used in such case)
[in]	i_ifcs	Number 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_ifcs	Number 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_spec	IFC_SPEC stringdescribed in README.ifcspec.md
[in]	service_ifcname	Identifier 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_recv()

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

Read data from input interface.

This function is thread safe.

Parameters

[in]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	ifc	Index of input interface (counted from 0).
[out]	data	Pointer to received data.
[out]	size	Size 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. This function is thread safe.

Parameters

[in]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	ifc	Index of interface to write into.
[in]	data	Pointer to data.
[in]	size	Number 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.

This function is thread safe.

Parameters

[in]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	ifc	IFC 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]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	level	Desired level of verbosity.

◆ trap_ctx_terminate()

int trap_ctx_terminate ( trap_ctx_t * ctx )

Terminate libtrap context.

This function is thread safe.

Parameters

[in] ctx Pointer 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.

This function is thread safe.

Parameters

[in]	ctx	Pointer to the private libtrap context data (trap_ctx_init()).
[in]	type	trap_ifc_type direction of interface
[in]	ifcidx	index of TRAP interface
[in]	request	trap_ifcctl_request type of operation
[in,out]	ap	arguments of request.

Returns: TRAP_E_OK on success

See also: trap_ctx_ifcctl().

Functions

Detailed Description

Function Documentation

◆ trap_ctx_create_ifc_dump()

◆ trap_ctx_finalize()

◆ trap_ctx_get_client_count()

◆ trap_ctx_get_last_error()

◆ trap_ctx_get_last_error_msg()

◆ trap_ctx_get_verbose_level()

◆ trap_ctx_ifcctl()

◆ trap_ctx_init()

◆ trap_ctx_init2()

◆ trap_ctx_init3()

◆ trap_ctx_recv()

◆ trap_ctx_send()

◆ trap_ctx_send_flush()

◆ trap_ctx_set_verbose_level()

◆ trap_ctx_terminate()

◆ trap_ctx_vifcctl()