libtrap 1.18.2
trap.h
Go to the documentation of this file.
1
9/*
10 * Copyright (C) 2013 - 2018 CESNET
11 *
12 * LICENSE TERMS
13 *
14 * Redistribution and use in source and binary forms, with or without
15 * modification, are permitted provided that the following conditions
16 * are met:
17 * 1. Redistributions of source code must retain the above copyright
18 * notice, this list of conditions and the following disclaimer.
19 * 2. Redistributions in binary form must reproduce the above copyright
20 * notice, this list of conditions and the following disclaimer in
21 * the documentation and/or other materials provided with the
22 * distribution.
23 * 3. Neither the name of the Company nor the names of its contributors
24 * may be used to endorse or promote products derived from this
25 * software without specific prior written permission.
26 *
27 * ALTERNATIVELY, provided that this notice is retained in full, this
28 * product may be distributed under the terms of the GNU General Public
29 * License (GPL) version 2 or later, in which case the provisions
30 * of the GPL apply INSTEAD OF those given above.
31 *
32 * This software is provided ``as is'', and any express or implied
33 * warranties, including, but not limited to, the implied warranties of
34 * merchantability and fitness for a particular purpose are disclaimed.
35 * In no event shall the company or contributors be liable for any
36 * direct, indirect, incidental, special, exemplary, or consequential
37 * damages (including, but not limited to, procurement of substitute
38 * goods or services; loss of use, data, or profits; or business
39 * interruption) however caused and on any theory of liability, whether
40 * in contract, strict liability, or tort (including negligence or
41 * otherwise) arising in any way out of the use of this software, even
42 * if advised of the possibility of such damage.
43 *
44 */
45
46#ifndef _TRAP_H_
47#define _TRAP_H_
48
49#ifdef __cplusplus
50extern "C" {
51#endif
52
53#include <stdint.h>
54#include <stdarg.h>
55
56#include "trap_module_info.h"
57#include "jansson.h"
58
59#define trap_ctx_t void
60
71extern const char trap_version[];
72
76extern const char trap_git_version[];
77
83
87#define TRAP_E_OK 0
88#define TRAP_E_TIMEOUT 1
89#define TRAP_E_INITIALIZED 10
90#define TRAP_E_BADPARAMS 11
91#define TRAP_E_BAD_IFC_INDEX 12
92#define TRAP_E_BAD_FPARAMS 13
93#define TRAP_E_IO_ERROR 14
94#define TRAP_E_TERMINATED 15
95#define TRAP_E_NOT_SELECTED 16
96#define TRAP_E_BAD_CERT 17
97#define TRAP_E_HELP 20
98#define TRAP_E_FIELDS_MISMATCH 21
99#define TRAP_E_FIELDS_SUBSET 22
100#define TRAP_E_FORMAT_CHANGED 23
101#define TRAP_E_FORMAT_MISMATCH 24
102#define TRAP_E_NEGOTIATION_FAILED 25
103#define TRAP_E_NOT_INITIALIZED 254
104#define TRAP_E_MEMORY 255
119#define TRAP_NO_WAIT 0
124#define TRAP_WAIT -1
130#define TRAP_HALFWAIT -2
131
132#define TRAP_TIMEOUT_STR(t) (t==TRAP_WAIT?"TRAP_WAIT":(t==TRAP_NO_WAIT?"TRAP_NO_WAIT":(t==TRAP_HALFWAIT?"TRAP_HALFWAIT":"")))
133
134#define TRAP_NO_AUTO_FLUSH (-1l)
135
160#define TRAP_IFC_DELIMITER ','
161
165#define TRAP_IFC_PARAM_DELIMITER ':'
166
171#define TRAP_IFC_TYPE_GENERATOR 'g'
172#define TRAP_IFC_TYPE_BLACKHOLE 'b'
173#define TRAP_IFC_TYPE_TCPIP 't'
174#define TRAP_IFC_TYPE_TLS 'T'
175#define TRAP_IFC_TYPE_UNIX 'u'
176#define TRAP_IFC_TYPE_SERVICE 's'
177#define TRAP_IFC_TYPE_FILE 'f'
178extern char trap_ifc_type_supported[];
179
185 TRAPIFC_OUTPUT = 2
187/* ifctypes *//* trapifcspec */
194
205#ifndef TRAP_IFC_MESSAGEQ_SIZE
206#define TRAP_IFC_MESSAGEQ_SIZE 100000
207#endif
208
213typedef struct trap_ifc_spec_s {
214 char *types;
215 char **params;
217
225 uint64_t received_bytes;
227 uint64_t missed_records;
228};
229
237typedef enum {
240
243
246
248 TRAP_FMT_JSON = 3
250
254typedef enum {
257
260
263
265 FMT_CHANGED = 3
267
276void trap_set_data_fmt(uint32_t out_ifc_idx, uint8_t data_type, ...);
277
287int trap_set_required_fmt(uint32_t in_ifc_idx, uint8_t data_type, ...);
288
301int trap_get_data_fmt(uint8_t ifc_dir, uint32_t ifc_idx, uint8_t *data_type, const char **spec);
302
314void trap_ctx_set_data_fmt(trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, ...);
315
327void trap_ctx_vset_data_fmt(trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, va_list ap);
328
339int trap_ctx_get_in_ifc_state(trap_ctx_t *ctx, uint32_t ifc_idx);
340
353int trap_ctx_set_required_fmt(trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type, ...);
354
367int trap_ctx_vset_required_fmt(trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type, va_list ap);
368
383int trap_ctx_get_data_fmt(trap_ctx_t *ctx, uint8_t ifc_dir, uint32_t ifc_idx, uint8_t *data_type, const char **spec);
384/* trap_mess_fmt */
388
401const char *trap_get_type_and_name_from_string(const char *source, const char **name, const char **type, int *length_name, int *length_type);
402
412int trap_ctx_cmp_data_fmt(const char *sender_ifc_data_fmt, const char *receiver_ifc_data_fmt);
413
420
427int trap_get_in_ifc_state(uint32_t ifc_idx);
428
442int trap_parse_params(int *argc, char **argv, trap_ifc_spec_t *ifc_spec);
443
453char *trap_get_param_by_delimiter(const char *source, char **dest, const char delimiter);
454
461int trap_check_buffer_content(void *buffer, uint32_t buffer_size);
462/* commonapi */
466
467/*****************************************************************************/
468/***************************** Library interface *****************************/
469
475extern int trap_last_error;
476extern const char *trap_last_error_msg;
477
483
491int trap_init(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec);
492
505
511
525int trap_send_data(unsigned int ifcidx, const void *data, uint16_t size, int timeout);
526
542int trap_recv(uint32_t ifcidx, const void **data, uint16_t *size);
543
564int trap_recv_with_seq_number(uint32_t ifcidx, const void **data, uint16_t *size, uint64_t *seq_number);
565
573void trap_get_input_ifc_stats(uint32_t ifcidx, struct input_ifc_stats* stats);
574
588int trap_send(uint32_t ifcidx, const void *data, uint16_t size);
589
602
608
613void trap_set_help_section(int level);
614
620void trap_print_help(const trap_module_info_t *module_info);
621
630
652int trap_ifcctl(int8_t type, uint32_t ifcidx, int32_t request, ... /* arg */);
653
659void trap_send_flush(uint32_t ifc);
660/* basic API */
664
665/********** Macros generating pieces of common code **********/
666
689
701trap_ctx_t *trap_ctx_init2(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec, const char *service_ifcname);
702
717trap_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);
718
728
738
752int trap_ctx_recv(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size);
753
768int trap_ctx_recv_with_seq_number(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size, uint64_t *seq_number);
769
786int trap_ctx_send(trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size);
787
803
813
839int trap_ctx_ifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, ... /* arg */);
840
855int trap_ctx_vifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, va_list ap);
856
866
876
885void trap_ctx_send_flush(trap_ctx_t *ctx, uint32_t ifc);
886
898int trap_ctx_get_client_count(trap_ctx_t *ctx, uint32_t ifcidx);
899
912void trap_ctx_create_ifc_dump(trap_ctx_t *ctx, const char *path);
913/* contextapi */
917
931#define TRAP_DEFAULT_SIGNAL_HANDLER(stop_cmd) \
932 void trap_default_signal_handler(int signal)\
933 {\
934 if (signal == SIGTERM || signal == SIGINT) { \
935 stop_cmd;\
936 trap_terminate();\
937 }\
938 }
939
945#ifdef HAVE_SIGACTION
946#define TRAP_REGISTER_DEFAULT_SIGNAL_HANDLER() \
947 do {\
948 if (trap_get_verbose_level() >= 1)\
949 printf("Setting signal handler for SIGINT and SIGTERM using 'sigaction' function.\n");\
950 struct sigaction act;\
951 /* Set default signal handler function*/\
952 act.sa_handler = trap_default_signal_handler;\
953 act.sa_flags = 0;\
954 /* Prevent interruption of signal handler by another SIGTERM or SIGINT */\
955 sigemptyset(&act.sa_mask);\
956 sigaddset(&act.sa_mask, SIGTERM);\
957 sigaddset(&act.sa_mask, SIGINT);\
958 /* Register signal hander */\
959 sigaction(SIGTERM, &act, NULL);\
960 sigaction(SIGINT, &act, NULL);\
961 } while(0)
962#else
963#define TRAP_REGISTER_DEFAULT_SIGNAL_HANDLER() \
964 do {\
965 if (trap_get_verbose_level() >= 1)\
966 printf("Setting signal handler for SIGINT and SIGTERM using 'signal' function.\n");\
967 signal(SIGTERM, trap_default_signal_handler);\
968 signal(SIGINT, trap_default_signal_handler);\
969 } while(0)
970#endif
971
972
973
984#define TRAP_DEFAULT_INITIALIZATION(argc, argv, module_info) \
985 {\
986 trap_ifc_spec_t ifc_spec;\
987 int ret = trap_parse_params(&argc, argv, &ifc_spec);\
988 if (ret != TRAP_E_OK) {\
989 if (ret == TRAP_E_HELP) {\
990 trap_print_help(&module_info);\
991 FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
992 return 0;\
993 }\
994 trap_free_ifc_spec(ifc_spec);\
995 fprintf(stderr, "ERROR in parsing of parameters for TRAP: %s\n", trap_last_error_msg);\
996 FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
997 return 1;\
998 }\
999 ret = trap_init(&module_info, ifc_spec);\
1000 if (ret != TRAP_E_OK) {\
1001 trap_free_ifc_spec(ifc_spec);\
1002 fprintf(stderr, "ERROR in TRAP initialization: %s\n", trap_last_error_msg);\
1003 FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
1004 return 1;\
1005 }\
1006 trap_free_ifc_spec(ifc_spec);\
1007 }
1008
1013#define TRAP_DEFAULT_FINALIZATION() \
1014 trap_finalize();
1015
1023#define TRAP_DEFAULT_GET_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
1024 if ((ret_code) != TRAP_E_OK) {\
1025 if ((ret_code) == TRAP_E_TIMEOUT) {\
1026 timeout_cmd;\
1027 } else if ((ret_code) == TRAP_E_TERMINATED) {\
1028 error_cmd;\
1029 } else if (ret_code == TRAP_E_FORMAT_CHANGED) { \
1030 /* Nothing to do here, TRAP_E_FORMAT_CHANGED has to be skipped by this macro */ \
1031 /* (module can perform some special operations with templates after trap_recv() signals format change) */ \
1032 } else if (ret_code == TRAP_E_FORMAT_MISMATCH) { \
1033 fprintf(stderr, "trap_recv() error: output and input interfaces data formats or data specifiers mismatch.\n"); \
1034 error_cmd; \
1035 } else if (ret_code == TRAP_E_NEGOTIATION_FAILED) { \
1036 fprintf(stderr, "trap_recv() error: interface negotiation failed (caused by invalid reply from a remote module, corrupted file or an unknown error).\n"); \
1037 error_cmd; \
1038 } else {\
1039 fprintf(stderr, "Error: trap_recv() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
1040 error_cmd;\
1041 }\
1042 }
1043
1050#define TRAP_DEFAULT_RECV_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
1051 if ((ret_code) != TRAP_E_OK) {\
1052 if ((ret_code) == TRAP_E_TIMEOUT) {\
1053 timeout_cmd;\
1054 } else if ((ret_code) == TRAP_E_TERMINATED) {\
1055 error_cmd;\
1056 } else if (ret_code == TRAP_E_FORMAT_CHANGED) { \
1057 /* Nothing to do here, TRAP_E_FORMAT_CHANGED has to be skipped by this macro */ \
1058 /* (module can perform some special operations with templates after trap_recv() signals format change) */ \
1059 } else if (ret_code == TRAP_E_FORMAT_MISMATCH) { \
1060 fprintf(stderr, "trap_recv() error: output and input interfaces data formats or data specifiers mismatch.\n"); \
1061 error_cmd; \
1062 } else if (ret_code == TRAP_E_NEGOTIATION_FAILED) { \
1063 fprintf(stderr, "trap_recv() error: interface negotiation failed (caused by invalid reply from a remote module, corrupted file or an unknown error).\n"); \
1064 error_cmd; \
1065 } else {\
1066 fprintf(stderr, "Error: trap_recv() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
1067 error_cmd;\
1068 }\
1069 }
1070
1071
1080#define TRAP_DEFAULT_SEND_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
1081 if ((ret_code) != TRAP_E_OK) {\
1082 if ((ret_code) == TRAP_E_TIMEOUT) {\
1083 timeout_cmd;\
1084 } else if ((ret_code) == TRAP_E_TERMINATED) {\
1085 error_cmd;\
1086 } else {\
1087 fprintf(stderr, "Error: trap_send_data() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
1088 error_cmd;\
1089 }\
1090 }
1091
1099#define TRAP_DEFAULT_SEND_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
1100 if ((ret_code) != TRAP_E_OK) {\
1101 if ((ret_code) == TRAP_E_TIMEOUT) {\
1102 timeout_cmd;\
1103 } else if ((ret_code) == TRAP_E_TERMINATED) {\
1104 error_cmd;\
1105 } else {\
1106 fprintf(stderr, "Error: trap_send() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
1107 error_cmd;\
1108 }\
1109 }/* modulemacros */
1113
1114
1115
1129int output_ifc_negotiation(void *ifc_priv_data, char ifc_type, int client_sd, void *ssl);
1130
1131
1146int input_ifc_negotiation(void *ifc_priv_data, char ifc_type);
1147
1148
1149#ifdef __cplusplus
1150} // extern "C"
1151#endif
1152
1153#endif
int trap_get_in_ifc_state(uint32_t ifc_idx)
int trap_ctx_cmp_data_fmt(const char *sender_ifc_data_fmt, const char *receiver_ifc_data_fmt)
const char * trap_get_type_and_name_from_string(const char *source, const char **name, const char **type, int *length_name, int *length_type)
void * trap_get_global_ctx()
const char trap_git_version[]
int trap_check_buffer_content(void *buffer, uint32_t buffer_size)
Check content of buffer, iterate over message headers.
const char trap_version[]
struct trap_ifc_spec_s trap_ifc_spec_t
trap_ifcctl_request
Definition trap.h:198
int trap_parse_params(int *argc, char **argv, trap_ifc_spec_t *ifc_spec)
char * trap_default_socket_path_format
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...
@ 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
int trap_ctx_recv(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size)
Read data from input interface.
void trap_ctx_create_ifc_dump(trap_ctx_t *ctx, const char *path)
Create dump files.
int trap_ctx_get_last_error(trap_ctx_t *ctx)
Get last result code from libtrap context.
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.
int trap_ctx_finalize(trap_ctx_t **ctx)
Terminate libtrap context and free resources.
int trap_ctx_vifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, va_list ap)
Control TRAP interface.
int trap_ctx_ifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request,...)
Control TRAP interface.
int trap_ctx_recv_with_seq_number(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size, uint64_t *seq_number)
Read data from input interface with sequence number.
const char * trap_ctx_get_last_error_msg(trap_ctx_t *ctx)
Get last (error) message from libtrap context.
int trap_ctx_terminate(trap_ctx_t *ctx)
Terminate libtrap context.
void trap_ctx_set_verbose_level(trap_ctx_t *ctx, int level)
Set verbosity level of library functions.
int trap_ctx_send(trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size)
Send data via output interface.
void trap_ctx_send_flush(trap_ctx_t *ctx, uint32_t ifc)
Force flush of buffer.
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.
int trap_ctx_get_client_count(trap_ctx_t *ctx, uint32_t ifcidx)
Get number of connected clients.
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.
int trap_ctx_get_verbose_level(trap_ctx_t *ctx)
Get verbosity level.
char trap_ifc_type_supported[]
trap_ifc_type
Definition trap.h:183
@ 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_send(uint32_t ifcidx, const void *data, uint16_t size)
Send data via output interface.
int trap_finalize()
const char * trap_last_error_msg
Human-readable message about last error.
void trap_get_input_ifc_stats(uint32_t ifcidx, struct input_ifc_stats *stats)
Get statistics about input interface.
int trap_terminate()
void trap_send_flush(uint32_t ifc)
Force flush of buffer.
void trap_print_ifc_spec_help()
int trap_last_error
Code of last error (one of the codes above)
int trap_ifcctl(int8_t type, uint32_t ifcidx, int32_t request,...)
Control TRAP 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_set_help_section(int level)
int trap_init(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec)
void trap_set_verbose_level(int level)
int trap_free_ifc_spec(trap_ifc_spec_t ifc_spec)
void trap_print_help(const trap_module_info_t *module_info)
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_get_verbose_level()
int trap_ctx_set_required_fmt(trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type,...)
int trap_ctx_get_in_ifc_state(trap_ctx_t *ctx, uint32_t ifc_idx)
int trap_get_data_fmt(uint8_t ifc_dir, uint32_t ifc_idx, uint8_t *data_type, const char **spec)
int trap_set_required_fmt(uint32_t in_ifc_idx, uint8_t data_type,...)
void trap_set_data_fmt(uint32_t out_ifc_idx, uint8_t data_type,...)
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)
trap_in_ifc_state_t
Definition trap.h:254
void trap_ctx_vset_data_fmt(trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, va_list ap)
void trap_ctx_set_data_fmt(trap_ctx_t *ctx, uint32_t out_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)
trap_data_format_t
Definition trap.h:237
@ FMT_OK
Definition trap.h:259
@ FMT_MISMATCH
Definition trap.h:262
@ FMT_CHANGED
Definition trap.h:265
@ FMT_WAITING
Definition trap.h:256
@ TRAP_FMT_UNKNOWN
Definition trap.h:239
@ TRAP_FMT_RAW
Definition trap.h:242
@ TRAP_FMT_UNIREC
Definition trap.h:245
@ TRAP_FMT_JSON
Definition trap.h:248
Input interface statistics.
Definition trap.h:224
uint64_t received_records
Number of received records.
Definition trap.h:226
uint64_t missed_records
Number of missed records.
Definition trap.h:227
uint64_t received_bytes
Number of received bytes.
Definition trap.h:225
char ** params
Definition trap.h:215
char * types
Definition trap.h:214
#define trap_ctx_t
Definition trap.h:59
int input_ifc_negotiation(void *ifc_priv_data, char ifc_type)
int output_ifc_negotiation(void *ifc_priv_data, char ifc_type, int client_sd, void *ssl)
Structures containing information about Nemea modules and macros for initialization and release of th...