Collaboration diagram for Context API:

Modules
	Message format

Functions
trap_ctx_priv_t *	trap_create_ctx_t ()

void	trap_free_ctx_t (trap_ctx_priv_t **ctx)

int	trap_ctx_terminate (trap_ctx_t *ctx)
	Terminate libtrap context. More...

static uint64_t	get_cur_timestamp ()

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_finalize (trap_ctx_t **ctx)
	Terminate libtrap context and free resources. More...

int	trap_ctx_send (trap_ctx_t ctx, unsigned int ifc, const void data, uint16_t size)
	Send data via output interface. More...

static void	remove_setter_from_param (char params, char setter)

static void	handle_inifc_setters (trap_input_ifc_t ifc, char params)

static int	trapifc_in_construct (trap_ctx_priv_t ctx, trap_ifc_spec_t ifc_spec, int idx)

static void	handle_outifc_setters (trap_output_ifc_t ifc, char params)

static int	trapifc_out_construct (trap_ctx_priv_t ctx, trap_ifc_spec_t ifc_spec, int idx)

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

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

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

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_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

◆ get_cur_timestamp()

static uint64_t get_cur_timestamp ( )

inlinestatic

Definition at line 1370 of file trap.c.

◆ handle_inifc_setters()

static void handle_inifc_setters	(	trap_input_ifc_t *	ifc,
		char *	params
	)

inlinestatic

Find setters in IFC parameters and set values if needed.

Parameters

[in,out]	ifc	Pointer to IFC structure from the array in context.
[in,out]	params	String passed as argument of -i, found setters are removed after their processing.

Definition at line 1506 of file trap.c.

◆ handle_outifc_setters()

static void handle_outifc_setters	(	trap_output_ifc_t *	ifc,
		char *	params
	)

inlinestatic

Find setters in IFC parameters and set values if needed.

Parameters

[in,out]	ifc	Pointer to IFC structure from the array in context.
[in,out]	params	String passed as argument of -i, found setters are removed after their processing.

Definition at line 1600 of file trap.c.

◆ remove_setter_from_param()

static void remove_setter_from_param	(	char *	params,
		char *	setter
	)

inlinestatic

Remove setter starting from params string.

Parameters

[in,out]	params	String with parameters of IFC.
[in]	setter	Pointer to the start of setter that should be removed. It ends by TRAP_IFC_PARAM_DELIMITER or zero-byte in the string.

Definition at line 1482 of file trap.c.

◆ trap_create_ctx_t()

trap_ctx_priv_t* trap_create_ctx_t ( )

Definition at line 1251 of file trap.c.

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

Definition at line 2473 of file trap.c.

◆ trap_ctx_finalize()

int trap_ctx_finalize ( trap_ctx_t ** ctx )

Terminate libtrap context and free resources.

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

Returns: Error code

This function is thread safe.

Parameters

[in] ctx Pointer to the private libtrap context data (trap_ctx_init()).

Returns: TRAP_E_OK on success.

Definition at line 1409 of file trap.c.

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

Definition at line 2495 of file trap.c.

◆ 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

Definition at line 2102 of file trap.c.

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

Definition at line 2108 of file trap.c.

◆ 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

Definition at line 2019 of file trap.c.

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

Returns: context, NULL when allocation failed.

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.

Definition at line 1786 of file trap.c.

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

Definition at line 1802 of file trap.c.

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

Definition at line 1731 of file trap.c.

◆ 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

Definition at line 1379 of file trap.c.

◆ 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

Definition at line 1448 of file trap.c.

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

Definition at line 2115 of file trap.c.

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

Definition at line 1342 of file trap.c.

◆ 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().

Definition at line 2032 of file trap.c.

◆ trap_free_ctx_t()

void trap_free_ctx_t ( trap_ctx_priv_t ** ctx )

Definition at line 1258 of file trap.c.

◆ trapifc_in_construct()

static int trapifc_in_construct	(	trap_ctx_priv_t *	ctx,
		trap_ifc_spec_t *	ifc_spec,
		int	idx
	)

inlinestatic

Switch of supported IFC types, place to call input IFC constructor.

Parameters

[in,out]	ctx	pointer to context
[in]	ifc_spec	IFC specifiers
[in]	idx	index into IFC array

Returns: EXIT_SUCCESS on success, EXIT_FAILURE on error.

Definition at line 1542 of file trap.c.

◆ trapifc_out_construct()

static int trapifc_out_construct	(	trap_ctx_priv_t *	ctx,
		trap_ifc_spec_t *	ifc_spec,
		int	idx
	)

inlinestatic

Switch of supported IFC types, place to call output IFC constructor.

Parameters

[in,out]	ctx	pointer to context
[in]	ifc_spec	IFC specifiers
[in]	idx	index into IFC array

Returns: EXIT_SUCCESS on success, EXIT_FAILURE on error.

Definition at line 1675 of file trap.c.

Modules

Functions

Detailed Description

Function Documentation

◆ get_cur_timestamp()

◆ handle_inifc_setters()

◆ handle_outifc_setters()

◆ remove_setter_from_param()

◆ trap_create_ctx_t()

◆ 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()

◆ trap_free_ctx_t()

◆ trapifc_in_construct()

◆ trapifc_out_construct()