trap.h

Go to the documentation of this file.

/*
 * Copyright (C) 2013 - 2018 CESNET
 *
 * LICENSE TERMS
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name of the Company nor the names of its contributors
 *    may be used to endorse or promote products derived from this
 *    software without specific prior written permission.
 *
 * ALTERNATIVELY, provided that this notice is retained in full, this
 * product may be distributed under the terms of the GNU General Public
 * License (GPL) version 2 or later, in which case the provisions
 * of the GPL apply INSTEAD OF those given above.
 *
 * This software is provided ``as is'', and any express or implied
 * warranties, including, but not limited to, the implied warranties of
 * merchantability and fitness for a particular purpose are disclaimed.
 * In no event shall the company or contributors be liable for any
 * direct, indirect, incidental, special, exemplary, or consequential
 * damages (including, but not limited to, procurement of substitute
 * goods or services; loss of use, data, or profits; or business
 * interruption) however caused and on any theory of liability, whether
 * in contract, strict liability, or tort (including negligence or
 * otherwise) arising in any way out of the use of this software, even
 * if advised of the possibility of such damage.
 *
 */

#ifndef _TRAP_H_
#define _TRAP_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>
#include <stdarg.h>

#include "trap_module_info.h"
#include "jansson.h"

#define trap_ctx_t void

extern const char trap_version[];

extern const char trap_git_version[];

extern char *trap_default_socket_path_format;

#define TRAP_E_OK 0 
#define TRAP_E_TIMEOUT 1 
#define TRAP_E_INITIALIZED 10 
#define TRAP_E_BADPARAMS 11 
#define TRAP_E_BAD_IFC_INDEX 12 
#define TRAP_E_BAD_FPARAMS 13 
#define TRAP_E_IO_ERROR 14 
#define TRAP_E_TERMINATED 15 
#define TRAP_E_NOT_SELECTED 16 
#define TRAP_E_BAD_CERT 17 
#define TRAP_E_HELP 20 
#define TRAP_E_FIELDS_MISMATCH 21 
#define TRAP_E_FIELDS_SUBSET 22 
#define TRAP_E_FORMAT_CHANGED 23 
#define TRAP_E_FORMAT_MISMATCH 24 
#define TRAP_E_NEGOTIATION_FAILED 25 
#define TRAP_E_NOT_INITIALIZED 254 
#define TRAP_E_MEMORY 255 

#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) 


#define TRAP_IFC_DELIMITER ','

#define TRAP_IFC_PARAM_DELIMITER ':'

#define TRAP_IFC_TYPE_GENERATOR 'g' 
#define TRAP_IFC_TYPE_BLACKHOLE 'b' 
#define TRAP_IFC_TYPE_TCPIP     't' 
#define TRAP_IFC_TYPE_TLS       'T' 
#define TRAP_IFC_TYPE_UNIX      'u' 
#define TRAP_IFC_TYPE_SERVICE   's' 
#define TRAP_IFC_TYPE_FILE      'f' 
extern char trap_ifc_type_supported[];

enum trap_ifc_type {
   TRAPIFC_INPUT = 1, 
   TRAPIFC_OUTPUT = 2 
};
/* ifctypes *//* trapifcspec */

enum trap_ifcctl_request {
   TRAPCTL_AUTOFLUSH_TIMEOUT = 1,  
   TRAPCTL_BUFFERSWITCH = 2,       
   TRAPCTL_SETTIMEOUT = 3          
};
#ifndef TRAP_IFC_MESSAGEQ_SIZE
#define TRAP_IFC_MESSAGEQ_SIZE 100000 
#endif

typedef struct trap_ifc_spec_s {
   char *types;
   char **params;
} trap_ifc_spec_t;

typedef enum {
   TRAP_FMT_UNKNOWN = 0,

   TRAP_FMT_RAW = 1,

   TRAP_FMT_UNIREC = 2,

   TRAP_FMT_JSON = 3
} trap_data_format_t;

typedef enum {
   FMT_WAITING = 0,

   FMT_OK = 1,

   FMT_MISMATCH = 2,

   FMT_CHANGED = 3
} trap_in_ifc_state_t;

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 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);
/* trap_mess_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);

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);

int trap_check_buffer_content(void *buffer, uint32_t buffer_size);
/* commonapi */

/*****************************************************************************/
/***************************** Library interface *****************************/

extern int trap_last_error; 
extern const char *trap_last_error_msg; 

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);

int trap_send(uint32_t ifcidx, const void *data, uint16_t size);

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, ... /* arg */);

void trap_send_flush(uint32_t ifc);
/* basic API */

/********** Macros generating pieces of common code **********/

trap_ctx_t *trap_ctx_init(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec);

trap_ctx_t *trap_ctx_init2(trap_module_info_t *module_info, trap_ifc_spec_t ifc_spec, const char *service_ifcname);

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);

int trap_ctx_finalize(trap_ctx_t **ctx);

int trap_ctx_terminate(trap_ctx_t *ctx);

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

int trap_ctx_send(trap_ctx_t *ctx, unsigned int ifc, const void *data, uint16_t size);

void trap_ctx_set_verbose_level(trap_ctx_t *ctx, int level);

int trap_ctx_get_verbose_level(trap_ctx_t *ctx);

int trap_ctx_ifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, ... /* arg */);

int trap_ctx_vifcctl(trap_ctx_t *ctx, int8_t type, uint32_t ifcidx, int32_t request, va_list ap);

int trap_ctx_get_last_error(trap_ctx_t *ctx);

const char *trap_ctx_get_last_error_msg(trap_ctx_t *ctx);

void trap_ctx_send_flush(trap_ctx_t *ctx, uint32_t ifc);

int trap_ctx_get_client_count(trap_ctx_t *ctx, uint32_t ifcidx);

void trap_ctx_create_ifc_dump(trap_ctx_t *ctx, const char *path);
/* contextapi */

#define TRAP_DEFAULT_SIGNAL_HANDLER(stop_cmd) \
   void trap_default_signal_handler(int signal)\
   {\
      if (signal == SIGTERM || signal == SIGINT) { \
         stop_cmd;\
         trap_terminate();\
      }\
   }

#ifdef HAVE_SIGACTION
#define TRAP_REGISTER_DEFAULT_SIGNAL_HANDLER() \
   do {\
      if (trap_get_verbose_level() >= 1)\
         printf("Setting signal handler for SIGINT and SIGTERM using 'sigaction' function.\n");\
      struct sigaction act;\
      /* Set default signal handler function*/\
      act.sa_handler = trap_default_signal_handler;\
      act.sa_flags = 0;\
      /* Prevent interruption of signal handler by another SIGTERM or SIGINT */\
      sigemptyset(&act.sa_mask);\
      sigaddset(&act.sa_mask, SIGTERM);\
      sigaddset(&act.sa_mask, SIGINT);\
      /* Register signal hander */\
      sigaction(SIGTERM, &act, NULL);\
      sigaction(SIGINT, &act, NULL);\
   } while(0)
#else
#define TRAP_REGISTER_DEFAULT_SIGNAL_HANDLER() \
   do {\
      if (trap_get_verbose_level() >= 1)\
         printf("Setting signal handler for SIGINT and SIGTERM using 'signal' function.\n");\
      signal(SIGTERM, trap_default_signal_handler);\
      signal(SIGINT, trap_default_signal_handler);\
   } while(0)
#endif



#define TRAP_DEFAULT_INITIALIZATION(argc, argv, module_info) \
   {\
      trap_ifc_spec_t ifc_spec;\
      int ret = trap_parse_params(&argc, argv, &ifc_spec);\
      if (ret != TRAP_E_OK) {\
         if (ret == TRAP_E_HELP) {\
            trap_print_help(&module_info);\
            FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
            return 0;\
         }\
         trap_free_ifc_spec(ifc_spec);\
         fprintf(stderr, "ERROR in parsing of parameters for TRAP: %s\n", trap_last_error_msg);\
         FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
         return 1;\
      }\
      ret = trap_init(&module_info, ifc_spec);\
      if (ret != TRAP_E_OK) {\
         trap_free_ifc_spec(ifc_spec);\
         fprintf(stderr, "ERROR in TRAP initialization: %s\n", trap_last_error_msg);\
         FREE_MODULE_INFO_STRUCT(MODULE_BASIC_INFO, MODULE_PARAMS) \
         return 1;\
      }\
      trap_free_ifc_spec(ifc_spec);\
   }

#define TRAP_DEFAULT_FINALIZATION() \
   trap_finalize();

#define TRAP_DEFAULT_GET_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
   if ((ret_code) != TRAP_E_OK) {\
      if ((ret_code) == TRAP_E_TIMEOUT) {\
         timeout_cmd;\
      } else if ((ret_code) == TRAP_E_TERMINATED) {\
         error_cmd;\
      } else if (ret_code == TRAP_E_FORMAT_CHANGED) { \
         /* Nothing to do here, TRAP_E_FORMAT_CHANGED has to be skipped by this macro */ \
         /* (module can perform some special operations with templates after trap_recv() signals format change) */ \
      } else if (ret_code == TRAP_E_FORMAT_MISMATCH) { \
         fprintf(stderr, "trap_recv() error: output and input interfaces data formats or data specifiers mismatch.\n"); \
         error_cmd; \
      } else if (ret_code == TRAP_E_NEGOTIATION_FAILED) { \
         fprintf(stderr, "trap_recv() error: interface negotiation failed (caused by invalid reply from a remote module, corrupted file or an unknown error).\n"); \
         error_cmd; \
      } else {\
         fprintf(stderr, "Error: trap_recv() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
         error_cmd;\
      }\
   }

#define TRAP_DEFAULT_RECV_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
   if ((ret_code) != TRAP_E_OK) {\
      if ((ret_code) == TRAP_E_TIMEOUT) {\
         timeout_cmd;\
      } else if ((ret_code) == TRAP_E_TERMINATED) {\
         error_cmd;\
      } else if (ret_code == TRAP_E_FORMAT_CHANGED) { \
         /* Nothing to do here, TRAP_E_FORMAT_CHANGED has to be skipped by this macro */ \
         /* (module can perform some special operations with templates after trap_recv() signals format change) */ \
      } else if (ret_code == TRAP_E_FORMAT_MISMATCH) { \
         fprintf(stderr, "trap_recv() error: output and input interfaces data formats or data specifiers mismatch.\n"); \
         error_cmd; \
      } else if (ret_code == TRAP_E_NEGOTIATION_FAILED) { \
         fprintf(stderr, "trap_recv() error: interface negotiation failed (caused by invalid reply from a remote module, corrupted file or an unknown error).\n"); \
         error_cmd; \
      } else {\
         fprintf(stderr, "Error: trap_recv() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
         error_cmd;\
      }\
   }


#define TRAP_DEFAULT_SEND_DATA_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
   if ((ret_code) != TRAP_E_OK) {\
      if ((ret_code) == TRAP_E_TIMEOUT) {\
         timeout_cmd;\
      } else if ((ret_code) == TRAP_E_TERMINATED) {\
         error_cmd;\
      } else {\
         fprintf(stderr, "Error: trap_send_data() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
         error_cmd;\
      }\
   }

#define TRAP_DEFAULT_SEND_ERROR_HANDLING(ret_code, timeout_cmd, error_cmd) \
   if ((ret_code) != TRAP_E_OK) {\
      if ((ret_code) == TRAP_E_TIMEOUT) {\
         timeout_cmd;\
      } else if ((ret_code) == TRAP_E_TERMINATED) {\
         error_cmd;\
      } else {\
         fprintf(stderr, "Error: trap_send() returned %i (%s)\n", (ret_code), trap_last_error_msg);\
         error_cmd;\
      }\
   }
/* modulemacros */



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);


#ifdef __cplusplus
} // extern "C"
#endif

#endif