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