Libtrap: Internal development docs  1.16.1
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
trap.h File Reference

Interface of TRAP library. More...

#include <stdint.h>
#include <stdarg.h>
#include "trap_module_info.h"
#include "jansson.h"
Include dependency graph for trap.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  trap_ifc_spec_s
 

Macros

#define trap_ctx_t   void
 
#define TRAP_E_OK   0
 Success, no error. More...
 
#define TRAP_E_TIMEOUT   1
 Read or write operation timeout. More...
 
#define TRAP_E_INITIALIZED   10
 TRAP library already initilized. More...
 
#define TRAP_E_BADPARAMS   11
 Bad parameters passed to interface initializer. More...
 
#define TRAP_E_BAD_IFC_INDEX   12
 Interface index out of range. More...
 
#define TRAP_E_BAD_FPARAMS   13
 Bad parameters of function. More...
 
#define TRAP_E_IO_ERROR   14
 IO Error. More...
 
#define TRAP_E_TERMINATED   15
 Interface was terminated during reading/writing. More...
 
#define TRAP_E_NOT_SELECTED   16
 Interface was not selected reading/writing. More...
 
#define TRAP_E_BAD_CERT   17
 Wrong certificate given to TLS interface. More...
 
#define TRAP_E_HELP   20
 Returned by parse_parameters when help is requested. More...
 
#define TRAP_E_FIELDS_MISMATCH   21
 Returned when receiver fields are not subset of sender fields. More...
 
#define TRAP_E_FIELDS_SUBSET   22
 Returned when receivers fields are subset of senders fields and both sets are not identical. More...
 
#define TRAP_E_FORMAT_CHANGED   23
 Returned by trap_recv when format or format spec of the receivers interface has been changed. More...
 
#define TRAP_E_FORMAT_MISMATCH   24
 Returned by trap_recv when data format or data specifier of the output and input interfaces doesn't match. More...
 
#define TRAP_E_NEGOTIATION_FAILED   25
 Returned by trap_recv when negotiation of the output and input interfaces failed. More...
 
#define TRAP_E_NOT_INITIALIZED   254
 TRAP library not initilized. More...
 
#define TRAP_E_MEMORY   255
 Memory allocation error. More...
 
#define TRAP_NO_WAIT   0
 
#define TRAP_WAIT   -1
 
#define TRAP_HALFWAIT   -2
 
#define TRAP_TIMEOUT_STR(t)   (t==TRAP_WAIT?"TRAP_WAIT":(t==TRAP_NO_WAIT?"TRAP_NO_WAIT":(t==TRAP_HALFWAIT?"TRAP_HALFWAIT":"")))
 
#define TRAP_NO_AUTO_FLUSH   (-1l)
 value to disable autoflushing on output interface More...
 
#define TRAP_IFC_DELIMITER   ','
 
#define TRAP_IFC_PARAM_DELIMITER   ':'
 
#define TRAP_IFC_TYPE_GENERATOR   'g'
 trap_ifc_dummy generator (input) More...
 
#define TRAP_IFC_TYPE_BLACKHOLE   'b'
 trap_ifc_dummy blackhole (output) More...
 
#define TRAP_IFC_TYPE_TCPIP   't'
 trap_ifc_tcpip (input&output part) More...
 
#define TRAP_IFC_TYPE_TLS   'T'
 trap_ifc_tls (input&output part) More...
 
#define TRAP_IFC_TYPE_UNIX   'u'
 trap_ifc_tcpip via UNIX socket(input&output part) More...
 
#define TRAP_IFC_TYPE_SERVICE   's'
 service ifc More...
 
#define TRAP_IFC_TYPE_FILE   'f'
 trap_ifc_file (input&output part) More...
 
#define TRAP_IFC_MESSAGEQ_SIZE   100000
 size of message queue used for buffering More...
 
#define TRAP_DEFAULT_SIGNAL_HANDLER(stop_cmd)
 Define default signal handler function Defines function to handle SIGTERM and SIGINT signals. When a signal is received, it runs the specified command and calls trap_terminate(). Place this macro before your main function. More...
 
#define TRAP_REGISTER_DEFAULT_SIGNAL_HANDLER()
 Register default signal handler. Register function defined by TRAP_DEFAULT_SIGNAL_HANDLER as handler of SIGTERM and SIGINT signals. Place this macro between TRAP initialization and the main loop. More...
 
#define TRAP_DEFAULT_INITIALIZATION(argc, argv, module_info)
 Initialize TRAP using command-line parameters and handle errors. Generates code that parses command-line parameters using trap_parse_params, intializes TRAP library using trap_init and handle possible errors. It calls exit(1) when an error has occured. Place this macro at the beginning of your main function. More...
 
#define TRAP_DEFAULT_FINALIZATION()   trap_finalize();
 Generate TRAP cleanup code. Only calls trap_finalize function. Place this macro at the end of your main function. More...
 
#define TRAP_DEFAULT_GET_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd)
 Handle possible errors after call to trap_recv(). More...
 
#define TRAP_DEFAULT_RECV_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd)
 Handle possible errors after call to trap_recv. More...
 
#define TRAP_DEFAULT_SEND_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd)
 Handle possible errors after call to trap_send_data. More...
 
#define TRAP_DEFAULT_SEND_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd)
 Handle possible errors after call to trap_send. More...
 

Typedefs

typedef struct trap_ifc_spec_s trap_ifc_spec_t
 

Enumerations

enum  trap_ifc_type { TRAPIFC_INPUT = 1, TRAPIFC_OUTPUT = 2 }
 
enum  trap_data_format_t { TRAP_FMT_UNKNOWN = 0, TRAP_FMT_RAW = 1, TRAP_FMT_UNIREC = 2, TRAP_FMT_JSON = 3 }
 
enum  trap_in_ifc_state_t { FMT_WAITING = 0, FMT_OK = 1, FMT_MISMATCH = 2, FMT_CHANGED = 3 }
 
TRAP interface control request
enum  trap_ifcctl_request { TRAPCTL_AUTOFLUSH_TIMEOUT = 1, TRAPCTL_BUFFERSWITCH = 2, TRAPCTL_SETTIMEOUT = 3 }
 

Functions

void trap_set_data_fmt (uint32_t out_ifc_idx, uint8_t data_type,...)
 
int trap_set_required_fmt (uint32_t in_ifc_idx, uint8_t data_type,...)
 
int trap_get_data_fmt (uint8_t ifc_dir, uint32_t in_ifc_idx, uint8_t *data_type, const char **spec)
 
void trap_ctx_set_data_fmt (trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type,...)
 
void trap_ctx_vset_data_fmt (trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, va_list ap)
 
int trap_ctx_get_in_ifc_state (trap_ctx_t *ctx, uint32_t ifc_idx)
 
int trap_ctx_set_required_fmt (trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type,...)
 
int trap_ctx_vset_required_fmt (trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type, va_list ap)
 
int trap_ctx_get_data_fmt (trap_ctx_t *ctx, uint8_t ifc_dir, uint32_t ifc_idx, uint8_t *data_type, const char **spec)
 
const char * trap_get_type_and_name_from_string (const char *source, const char **name, const char **type, int *length_name, int *length_type)
 
int trap_ctx_cmp_data_fmt (const char *sender_ifc_data_fmt, const char *receiver_ifc_data_fmt)
 
void * trap_get_global_ctx ()
 
int trap_get_in_ifc_state (uint32_t ifc_idx)
 
int trap_parse_params (int *argc, char **argv, trap_ifc_spec_t *ifc_spec)
 
char * trap_get_param_by_delimiter (const char *source, char **dest, const char delimiter)
 Splitter of params string. Cut the first param, copy it into dest and returns pointer to the start of following parameter. More...
 
int trap_check_buffer_content (void *buffer, uint32_t buffer_size)
 Check content of buffer, iterate over message headers. More...
 
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. More...
 
int trap_send (uint32_t ifcidx, const void *data, uint16_t size)
 Send data via output interface. More...
 
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. More...
 
void trap_send_flush (uint32_t ifc)
 Force flush of buffer. More...
 
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)
 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...
 
int output_ifc_negotiation (void *ifc_priv_data, char ifc_type, uint32_t client_idx)
 
int input_ifc_negotiation (void *ifc_priv_data, char ifc_type)
 

Variables

const char trap_version []
 
const char trap_git_version [] = GIT_VERSION
 
char * trap_default_socket_path_format
 
char trap_ifc_type_supported []
 
enum trap_ifc_type __attribute__
 
int trap_last_error
 Code of last error (one of the codes above) More...
 
const char * trap_last_error_msg
 Human-readable message about last error. More...
 

Detailed Description

Interface of TRAP library.

Author
Vaclav Bartos ibart.nosp@m.osv@.nosp@m.fit.v.nosp@m.utbr.nosp@m..cz
Tomas Cejka cejka.nosp@m.t@ce.nosp@m.snet..nosp@m.cz
Tomas Jansky jansk.nosp@m.to1@.nosp@m.fit.c.nosp@m.vut..nosp@m.cz
Date
2013 - 2018

Definition in file trap.h.

Macro Definition Documentation

◆ trap_ctx_t

#define trap_ctx_t   void

Definition at line 59 of file trap.h.

Function Documentation

◆ input_ifc_negotiation()

int input_ifc_negotiation ( void *  ifc_priv_data,
char  ifc_type 
)

Function handles input interface negotiation (receives hello message from output interface with its data format and data specifier and compares it with its own data format and data specifier). Hello message contains message header (data format and data specifier size) and data specifier.

Parameters
[in,out]ifc_priv_dataPointer to input interface private structure.
[in]ifc_typeType of IFC, e.g. TRAP_IFC_TYPE_FILE, TRAP_IFC_TYPE_TCPIP, or TRAP_IFC_TYPE_UNIX.
Returns
NEG_RES_FAILED if receiving the data from output interface fails, NEG_RES_FMT_UNKNOWN if the output interface has not specified data format, NEG_RES_FMT_SUBSET if the data format of input and output interfaces is the same and data specifier of the input interface is subset of the output interface data specifier, NEG_RES_CONT if the data format and data specifier of input and output interface are the same (input interface can receive the data for module right after the negotiation), NEG_RES_FMT_MISMATCH if the data format or data specifier of input and output interfaces does not match.

Receive hello msg header with data_type and data_fmt_spec_size



Compare data_type


Receive data_fmt_spec

Compare data_fmt_spec
Save senders data_type and data_fmt_spec

Definition at line 2995 of file trap.c.

◆ output_ifc_negotiation()

int output_ifc_negotiation ( void *  ifc_priv_data,
char  ifc_type,
uint32_t  client_idx 
)

Function handles output interface negotiation (sends hello message to input interface with its data format and data specifier). Hello message contains message header (data format and data specifier size) and data specifier.

Parameters
[in]ifc_priv_dataPointer to output interface private structure.
[in]ifc_typeType of IFC, e.g. TRAP_IFC_TYPE_FILE, TRAP_IFC_TYPE_TCPIP, or TRAP_IFC_TYPE_UNIX.
[in]client_idxIndex of new connected client.
Returns
NEG_RES_FAILED if sending the data to input interface fails, NEG_RES_FMT_UNKNOWN if the output interface has not specified data format, NEG_RES_OK signaling success (hello message successfully sent to input interface).

In case of file output interface, return NEG_RES_FMT_UNKNOWN In case of tcpip or unix output interface, send hello message header with format unknown value and return NEG_RES_FMT_UNKNOWN

Definition at line 2833 of file trap.c.