src/libcharon/plugins/vici/vici_message.h

   1 /*
   2  * Copyright (C) 2015 Tobias Brunner
   3  * Hochschule fuer Technik Rapperswil
   4  *
   5  * Copyright (C) 2014 Martin Willi
   6  * Copyright (C) 2014 revosec AG
   7  *
   8  * This program is free software; you can redistribute it and/or modify it
   9  * under the terms of the GNU General Public License as published by the
  10  * Free Software Foundation; either version 2 of the License, or (at your
  11  * option) any later version.  See <http://www.fsf.org/copyleft/gpl.txt>.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  15  * or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * for more details.
  17  */
  18
  19 /**
  20  * @defgroup vici_message vici_message
  21  * @{ @ingroup vici
  22  */
  23
  24 #ifndef VICI_MESSAGE_H_
  25 #define VICI_MESSAGE_H_
  26
  27 #include <library.h>
  28
  29 typedef struct vici_message_t vici_message_t;
  30 typedef struct vici_parse_context_t vici_parse_context_t;
  31 typedef enum vici_type_t vici_type_t;
  32
  33 /**
  34  * Vici message encoding types
  35  */
  36 enum vici_type_t {
  37         /** never used in an argument list, needed by dump as initial value */
  38         VICI_START =         0,
  39
  40         /** begin of new section, argument is section name as char* */
  41         VICI_SECTION_START = 1,
  42         /** end of current section, no arguments */
  43         VICI_SECTION_END =   2,
  44         /** key/value, arguments are key as char*, value as chunk_t */
  45         VICI_KEY_VALUE =     3,
  46         /** list start, argument is list name as char* */
  47         VICI_LIST_START =    4,
  48         /** list item, argument is item value as chunk_t */
  49         VICI_LIST_ITEM =     5,
  50         /** end of list, no arguments */
  51         VICI_LIST_END =      6,
  52
  53         /** end of argument list, no arguments (never encoded) */
  54         VICI_END =           7
  55 };
  56
  57 /**
  58  * Callback function for key/value and list items, invoked by parse().
  59  *
  60  * @param user          user data, as passed to parse()
  61  * @param message       message currently parsing
  62  * @param name          name of key or list
  63  * @param value         parsed value
  64  * @return                      TRUE if parsed successfully
  65  */
  66 typedef bool (*vici_value_cb_t)(void *user, vici_message_t *message,
  67                                                                 char *name, chunk_t value);
  68
  69 /**
  70  * Callback function for sections, invoked by parse().
  71  *
  72  * @param user          user data, as passed to parse()
  73  * @param message       message currently parsing
  74  * @param ctx           parse context, to pass to recursive parse() invocations.
  75  * @param name          name of the section
  76  * @return                      TRUE if parsed successfully
  77  */
  78 typedef bool (*vici_section_cb_t)(void *user, vici_message_t *message,
  79                                                                   vici_parse_context_t *ctx, char *name);
  80
  81 /**
  82  * Names for vici encoding types
  83  */
  84 extern enum_name_t *vici_type_names;
  85
  86 /**
  87  * Vici message representation, encoding/decoding routines.
  88  */
  89 struct vici_message_t {
  90
  91         /**
  92          * Create an enumerator over message contents.
  93          *
  94          * The enumerator takes a fixed list of arguments, but depending on the
  95          * type may set not all of them. It returns VICI_END as last argument
  96          * to indicate the message end, and returns FALSE if parsing the message
  97          * failed.
  98          *
  99          * @return              enumerator over (vici_type_t, char*, chunk_t)
 100          */
 101         enumerator_t* (*create_enumerator)(vici_message_t *this);
 102
 103         /**
 104          * Get the value of a key/value pair as a string.
 105          *
 106          * @param def   default value if not found
 107          * @param fmt   printf style format string for key, with sections
 108          * @param ...   arguments to fmt string
 109          * @return              string
 110          */
 111         char* (*get_str)(vici_message_t *this, char *def, char *fmt, ...);
 112
 113         /**
 114          * Get the value of a key/value pair as a string, va_list variant.
 115          *
 116          * @param def   default value if not found
 117          * @param fmt   printf style format string for key, with sections
 118          * @param args  arguments to fmt string
 119          * @return              string
 120          */
 121         char* (*vget_str)(vici_message_t *this, char *def, char *fmt, va_list args);
 122
 123         /**
 124          * Get the value of a key/value pair as integer.
 125          *
 126          * @param def   default value if not found
 127          * @param fmt   printf style format string for key, with sections
 128          * @param ...   arguments to fmt string
 129          * @return              value
 130          */
 131         int (*get_int)(vici_message_t *this, int def, char *fmt, ...);
 132
 133         /**
 134          * Get the value of a key/value pair as integer, va_list variant
 135          *
 136          * @param def   default value if not found
 137          * @param fmt   printf style format string for key, with sections
 138          * @param args  arguments to fmt string
 139          * @return              value
 140          */
 141         int (*vget_int)(vici_message_t *this, int def, char *fmt, va_list args);
 142
 143         /**
 144          * Get the value of a key/value pair as boolean.
 145          *
 146          * @param def   default value if not found
 147          * @param fmt   printf style format string for key, with sections
 148          * @param ...   arguments to fmt string
 149          * @return              value
 150          */
 151         bool (*get_bool)(vici_message_t *this, bool def, char *fmt, ...);
 152
 153         /**
 154          * Get the value of a key/value pair as boolean, va_list variant
 155          *
 156          * @param def   default value if not found
 157          * @param fmt   printf style format string for key, with sections
 158          * @param args  arguments to fmt string
 159          * @return              value
 160          */
 161         bool (*vget_bool)(vici_message_t *this, bool def, char *fmt, va_list args);
 162
 163         /**
 164          * Get the raw value of a key/value pair.
 165          *
 166          * @param def   default value if not found
 167          * @param fmt   printf style format string for key, with sections
 168          * @param ...   arguments to fmt string
 169          * @return              value
 170          */
 171         chunk_t (*get_value)(vici_message_t *this, chunk_t def, char *fmt, ...);
 172
 173         /**
 174          * Get the raw value of a key/value pair, va_list variant.
 175          *
 176          * @param def   default value if not found
 177          * @param fmt   printf style format string for key, with sections
 178          * @param args  arguments to fmt string
 179          * @return              value
 180          */
 181         chunk_t (*vget_value)(vici_message_t *this, chunk_t def,
 182                                                  char *fmt, va_list args);
 183
 184         /**
 185          * Get encoded message.
 186          *
 187          * @return              message data, points to internal data
 188          */
 189         chunk_t (*get_encoding)(vici_message_t *this);
 190
 191         /**
 192          * Parse a message using callback functions.
 193          *
 194          * Any of the callbacks may be NULL to skip this kind of item. Callbacks are
 195          * invoked for the current section level only. To descent into sections,
 196          * call parse() from within a section callback using the provided parse
 197          * context.
 198          *
 199          * @param ctx           parse context, NULL for root level
 200          * @param section       callback invoked for each section
 201          * @param kv            callback invoked for key/value pairs
 202          * @param li            callback invoked for list items
 203          * @param user          user data to pass to callbacks
 204          * @return                      TRUE if parsed successfully
 205          */
 206         bool (*parse)(vici_message_t *this, vici_parse_context_t *ctx,
 207                                   vici_section_cb_t section, vici_value_cb_t kv,
 208                                   vici_value_cb_t li, void *user);
 209
 210         /**
 211          * Dump a message text representation to a FILE stream.
 212          *
 213          * @param label         label to print for message
 214          * @param pretty        use pretty print with indentation
 215          * @param out           FILE stream to dump to
 216          * @return                      TRUE if message valid
 217          */
 218         bool (*dump)(vici_message_t *this, char *label, bool pretty, FILE *out);
 219
 220         /**
 221          * Destroy a vici_message_t.
 222          */
 223         void (*destroy)(vici_message_t *this);
 224 };
 225
 226 /**
 227  * Create a vici_message from encoded data.
 228  *
 229  * @param data                  message encoding
 230  * @param cleanup               TRUE to free data during
 231  * @return                              message representation
 232  */
 233 vici_message_t *vici_message_create_from_data(chunk_t data, bool cleanup);
 234
 235 /**
 236  * Create a vici_message from an enumerator.
 237  *
 238  * The enumerator uses the same signature as the enumerator returned
 239  * by create_enumerator(), and gets destroyed by this function. It should
 240  * return VICI_END to close the message, return FALSE to indicate a failure.
 241  *
 242  * @param enumerator    enumerator over (vici_type_t, char*, chunk_t)
 243  * @return                              message representation, NULL on error
 244  */
 245 vici_message_t *vici_message_create_from_enumerator(enumerator_t *enumerator);
 246
 247 /**
 248  * Create vici message from a variable argument list.
 249  *
 250  * @param type                  first type beginning message
 251  * @param ...                   vici_type_t and args, terminated by VICI_END
 252  * @return                              message representation, NULL on error
 253  */
 254 vici_message_t *vici_message_create_from_args(vici_type_t type, ...);
 255
 256 /**
 257  * Check if a chunk has a printable string, and print it to buf.
 258  *
 259  * @param chunk                 chunk containing potential string
 260  * @param buf                   buffer to write string to
 261  * @param size                  size of buf
 262  * @return                              TRUE if printable and string written to buf
 263  */
 264 bool vici_stringify(chunk_t chunk, char *buf, size_t size);
 265
 266 /**
 267  * Verify the occurrence of a given type for given section/list nesting
 268  */
 269 bool vici_verify_type(vici_type_t type, u_int section, bool list);
 270
 271 #endif /** VICI_MESSAGE_H_ @}*/