1 /* 2 * Copyright (c) 2015, Juniper Networks, Inc. 3 * All rights reserved. 4 * This SOFTWARE is licensed under the LICENSE provided in the 5 * ../Copyright file. By downloading, installing, copying, or otherwise 6 * using the SOFTWARE, you agree to be bound by the terms of that 7 * LICENSE. 8 * Phil Shafer, August 2015 9 */ 10 11 /* 12 * NOTE WELL: This file is needed to software that implements an 13 * external encoder for libxo that allows libxo data to be encoded in 14 * new and bizarre formats. General libxo code should _never_ 15 * include this header file. 16 */ 17 18 #ifndef XO_ENCODER_H 19 #define XO_ENCODER_H 20 21 #include <string.h> 22 23 /* 24 * Expose libxo's memory allocation functions 25 */ 26 extern xo_realloc_func_t xo_realloc; 27 extern xo_free_func_t xo_free; 28 29 /* 30 * Simple string comparison function (without the temptation 31 * to forget the "== 0"). 32 */ 33 static inline int 34 xo_streq (const char *one, const char *two) 35 { 36 return strcmp(one, two) == 0; 37 } 38 39 /* Flags for formatting functions */ 40 typedef unsigned long xo_xff_flags_t; 41 #define XFF_COLON (1<<0) /* Append a ":" */ 42 #define XFF_COMMA (1<<1) /* Append a "," iff there's more output */ 43 #define XFF_WS (1<<2) /* Append a blank */ 44 #define XFF_ENCODE_ONLY (1<<3) /* Only emit for encoding styles (XML, JSON) */ 45 46 #define XFF_QUOTE (1<<4) /* Force quotes */ 47 #define XFF_NOQUOTE (1<<5) /* Force no quotes */ 48 #define XFF_DISPLAY_ONLY (1<<6) /* Only emit for display styles (text, html) */ 49 #define XFF_KEY (1<<7) /* Field is a key (for XPath) */ 50 51 #define XFF_XML (1<<8) /* Force XML encoding style (for XPath) */ 52 #define XFF_ATTR (1<<9) /* Escape value using attribute rules (XML) */ 53 #define XFF_BLANK_LINE (1<<10) /* Emit a blank line */ 54 #define XFF_NO_OUTPUT (1<<11) /* Do not make any output */ 55 56 #define XFF_TRIM_WS (1<<12) /* Trim whitespace off encoded values */ 57 #define XFF_LEAF_LIST (1<<13) /* A leaf-list (list of values) */ 58 #define XFF_UNESCAPE (1<<14) /* Need to printf-style unescape the value */ 59 #define XFF_HUMANIZE (1<<15) /* Humanize the value (for display styles) */ 60 61 #define XFF_HN_SPACE (1<<16) /* Humanize: put space before suffix */ 62 #define XFF_HN_DECIMAL (1<<17) /* Humanize: add one decimal place if <10 */ 63 #define XFF_HN_1000 (1<<18) /* Humanize: use 1000, not 1024 */ 64 #define XFF_GT_FIELD (1<<19) /* Call gettext() on a field */ 65 66 #define XFF_GT_PLURAL (1<<20) /* Call dngettext to find plural form */ 67 #define XFF_ARGUMENT (1<<21) /* Content provided via argument */ 68 69 /* Flags to turn off when we don't want i18n processing */ 70 #define XFF_GT_FLAGS (XFF_GT_FIELD | XFF_GT_PLURAL) 71 72 typedef unsigned xo_encoder_op_t; 73 74 /* Encoder operations; names are in xo_encoder.c:xo_encoder_op_name() */ 75 #define XO_OP_UNKNOWN 0 76 #define XO_OP_CREATE 1 /* Called when the handle is init'd */ 77 #define XO_OP_OPEN_CONTAINER 2 78 #define XO_OP_CLOSE_CONTAINER 3 79 #define XO_OP_OPEN_LIST 4 80 #define XO_OP_CLOSE_LIST 5 81 #define XO_OP_OPEN_LEAF_LIST 6 82 #define XO_OP_CLOSE_LEAF_LIST 7 83 #define XO_OP_OPEN_INSTANCE 8 84 #define XO_OP_CLOSE_INSTANCE 9 85 #define XO_OP_STRING 10 /* Quoted UTF-8 string */ 86 #define XO_OP_CONTENT 11 /* Other content */ 87 #define XO_OP_FINISH 12 /* Finish any pending output */ 88 #define XO_OP_FLUSH 13 /* Flush any buffered output */ 89 #define XO_OP_DESTROY 14 /* Clean up function */ 90 #define XO_OP_ATTRIBUTE 15 /* Attribute name/value */ 91 #define XO_OP_VERSION 16 /* Version string */ 92 #define XO_OP_OPTIONS 17 /* Additional command line options */ 93 #define XO_OP_OPTIONS_PLUS 18 /* Additional command line options */ 94 95 #define XO_ENCODER_HANDLER_ARGS \ 96 xo_handle_t *xop __attribute__ ((__unused__)), \ 97 xo_encoder_op_t op __attribute__ ((__unused__)), \ 98 const char *name __attribute__ ((__unused__)), \ 99 const char *value __attribute__ ((__unused__)), \ 100 void *private __attribute__ ((__unused__)), \ 101 xo_xff_flags_t flags __attribute__ ((__unused__)) 102 103 typedef int (*xo_encoder_func_t)(XO_ENCODER_HANDLER_ARGS); 104 105 typedef struct xo_encoder_init_args_s { 106 unsigned xei_version; /* Current version */ 107 xo_encoder_func_t xei_handler; /* Encoding handler */ 108 } xo_encoder_init_args_t; 109 110 #define XO_ENCODER_VERSION 1 /* Current version */ 111 112 #define XO_ENCODER_INIT_ARGS \ 113 xo_encoder_init_args_t *arg __attribute__ ((__unused__)) 114 115 typedef int (*xo_encoder_init_func_t)(XO_ENCODER_INIT_ARGS); 116 /* 117 * Each encoder library must define a function named xo_encoder_init 118 * that takes the arguments defined in XO_ENCODER_INIT_ARGS. It 119 * should return zero for success. 120 */ 121 #define XO_ENCODER_INIT_NAME_TOKEN xo_encoder_library_init 122 #define XO_STRINGIFY(_x) #_x 123 #define XO_STRINGIFY2(_x) XO_STRINGIFY(_x) 124 #define XO_ENCODER_INIT_NAME XO_STRINGIFY2(XO_ENCODER_INIT_NAME_TOKEN) 125 extern int XO_ENCODER_INIT_NAME_TOKEN (XO_ENCODER_INIT_ARGS); 126 127 void 128 xo_encoder_register (const char *name, xo_encoder_func_t func); 129 130 void 131 xo_encoder_unregister (const char *name); 132 133 void * 134 xo_get_private (xo_handle_t *xop); 135 136 void 137 xo_encoder_path_add (const char *path); 138 139 void 140 xo_set_private (xo_handle_t *xop, void *opaque); 141 142 xo_encoder_func_t 143 xo_get_encoder (xo_handle_t *xop); 144 145 void 146 xo_set_encoder (xo_handle_t *xop, xo_encoder_func_t encoder); 147 148 int 149 xo_encoder_init (xo_handle_t *xop, const char *name); 150 151 xo_handle_t * 152 xo_encoder_create (const char *name, xo_xof_flags_t flags); 153 154 int 155 xo_encoder_handle (xo_handle_t *xop, xo_encoder_op_t op, 156 const char *name, const char *value, xo_xff_flags_t flags); 157 158 void 159 xo_encoders_clean (void); 160 161 const char * 162 xo_encoder_op_name (xo_encoder_op_t op); 163 164 /* 165 * xo_failure is used to announce internal failures, when "warn" is on 166 */ 167 void 168 xo_failure (xo_handle_t *xop, const char *fmt, ...); 169 170 #endif /* XO_ENCODER_H */ 171