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
50 extern "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 
71 extern const char trap_version[];
72 
76 extern 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'
178 extern char trap_ifc_type_supported[];
179 
185  TRAPIFC_OUTPUT = 2
186 };
187 /* ifctypes *//* trapifcspec */
194 
201  TRAPCTL_SETTIMEOUT = 3
202 };
205 #ifndef TRAP_IFC_MESSAGEQ_SIZE
206 #define TRAP_IFC_MESSAGEQ_SIZE 100000
207 #endif
208 
213 typedef struct trap_ifc_spec_s {
214  char *types;
215  char **params;
217 
225  uint64_t received_bytes;
226  uint64_t received_records;
227  uint64_t missed_records;
228 };
229 
237 typedef enum {
240 
243 
246 
248  TRAP_FMT_JSON = 3
250 
254 typedef enum {
257 
259  FMT_OK = 1,
260 
263 
265  FMT_CHANGED = 3
267 
276 void trap_set_data_fmt(uint32_t out_ifc_idx, uint8_t data_type, ...);
277 
287 int trap_set_required_fmt(uint32_t in_ifc_idx, uint8_t data_type, ...);
288 
301 int trap_get_data_fmt(uint8_t ifc_dir, uint32_t ifc_idx, uint8_t *data_type, const char **spec);
302 
314 void trap_ctx_set_data_fmt(trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, ...);
315 
327 void trap_ctx_vset_data_fmt(trap_ctx_t *ctx, uint32_t out_ifc_idx, uint8_t data_type, va_list ap);
328 
339 int trap_ctx_get_in_ifc_state(trap_ctx_t *ctx, uint32_t ifc_idx);
340 
353 int trap_ctx_set_required_fmt(trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type, ...);
354 
367 int trap_ctx_vset_required_fmt(trap_ctx_t *ctx, uint32_t in_ifc_idx, uint8_t data_type, va_list ap);
368 
383 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);
384 /* trap_mess_fmt */
388 
401 const char *trap_get_type_and_name_from_string(const char *source, const char **name, const char **type, int *length_name, int *length_type);
402 
412 int trap_ctx_cmp_data_fmt(const char *sender_ifc_data_fmt, const char *receiver_ifc_data_fmt);
413 
420 
427 int trap_get_in_ifc_state(uint32_t ifc_idx);
428 
442 int trap_parse_params(int *argc, char **argv, trap_ifc_spec_t *ifc_spec);
443 
453 char *trap_get_param_by_delimiter(const char *source, char **dest, const char delimiter);
454 
461 int trap_check_buffer_content(void *buffer, uint32_t buffer_size);
462 /* commonapi */
466 
467 /*****************************************************************************/
468 /***************************** Library interface *****************************/
469 
475 extern int trap_last_error;
476 extern const char *trap_last_error_msg;
477 
483 
491 int trap_init(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec);
492 
505 
511 
525 int trap_send_data(unsigned int ifcidx, const void *data, uint16_t size, int timeout);
526 
542 int trap_recv(uint32_t ifcidx, const void **data, uint16_t *size);
543 
564 int trap_recv_with_seq_number(uint32_t ifcidx, const void **data, uint16_t *size, uint64_t *seq_number);
565 
573 void trap_get_input_ifc_stats(uint32_t ifcidx, struct input_ifc_stats* stats);
574 
588 int trap_send(uint32_t ifcidx, const void *data, uint16_t size);
589 
601 void trap_set_verbose_level(int level);
602 
608 
613 void trap_set_help_section(int level);
614 
620 void trap_print_help(const trap_module_info_t *module_info);
621 
630 
652 int trap_ifcctl(int8_t type, uint32_t ifcidx, int32_t request, ... /* arg */);
653 
659 void trap_send_flush(uint32_t ifc);
660 /* basic API */
664 
665 /********** Macros generating pieces of common code **********/
666 
689 
701 trap_ctx_t *trap_ctx_init2(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec, const char *service_ifcname);
702 
717 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);
718 
728 
738 
752 int trap_ctx_recv(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size);
753 
768 int trap_ctx_recv_with_seq_number(trap_ctx_t *ctx, uint32_t ifc, const void **data, uint16_t *size, uint64_t *seq_number);
769 
786 int trap_ctx_send(trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size);
787 
803 
813 
839 int trap_ctx_ifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, ... /* arg */);
840 
855 int trap_ctx_vifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, va_list ap);
856 
866 
876 
885 void trap_ctx_send_flush(trap_ctx_t *ctx, uint32_t ifc);
886 
898 int trap_ctx_get_client_count(trap_ctx_t *ctx, uint32_t ifcidx);
899 
912 void 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 
1129 int output_ifc_negotiation(void *ifc_priv_data, char ifc_type, int client_sd, void *ssl);
1130 
1131 
1146 int 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)
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...
const char trap_git_version[]
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_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)
void * trap_get_global_ctx()
char * trap_default_socket_path_format
@ 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.
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.
void trap_ctx_create_ifc_dump(trap_ctx_t *ctx, const char *path)
Create dump files.
const char * trap_ctx_get_last_error_msg(trap_ctx_t *ctx)
Get last (error) message from libtrap context.
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.
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.
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...