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
xo_streq(const char * one,const char * two)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