1:
2: /*
3: * Copyright (c) 2001-2002 Packet Design, LLC.
4: * All rights reserved.
5: *
6: * Subject to the following obligations and disclaimer of warranty,
7: * use and redistribution of this software, in source or object code
8: * forms, with or without modifications are expressly permitted by
9: * Packet Design; provided, however, that:
10: *
11: * (i) Any and all reproductions of the source or object code
12: * must include the copyright notice above and the following
13: * disclaimer of warranties; and
14: * (ii) No rights are granted, in any manner or form, to use
15: * Packet Design trademarks, including the mark "PACKET DESIGN"
16: * on advertising, endorsements, or otherwise except as such
17: * appears in the above copyright notice or in the software.
18: *
19: * THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
20: * TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
21: * REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
22: * THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
23: * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
24: * OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
25: * OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
26: * OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
27: * RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
28: * LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
29: * OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
30: * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
31: * DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
32: * USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
33: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
35: * THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
36: * THE POSSIBILITY OF SUCH DAMAGE.
37: *
38: * Author: Archie Cobbs <archie@freebsd.org>
39: */
40:
41: #ifndef _PDEL_STRUCTS_STRUCTS_H_
42: #define _PDEL_STRUCTS_STRUCTS_H_
43:
44: /*********************************************************************
45:
46: STRUCTS TYPES
47: -------------
48:
49: A "structs type" is a descriptor for a C data structure that
50: allows access to the data structure in an automated fashion.
51: For example, once a data structure is described by a associated
52: structs type, the following operations can be performed
53: automatically on any instance of the data structure:
54:
55: o Initialization to default value
56: o Comparison of two instances for equality
57: o "Deep" copying (aka. "cloning")
58: o Access to arbitrary sub-fields by name (aka. "introspection")
59: o Conversion to/from ASCII (primitive types)
60: o Import/export from/to XML, with precise input validation,
61: automating conversion between internal and external formats
62: o Conversion into XML-RPC request or reply
63: o Import/export from/to a machine independent binary encoding
64: o Inserting, deleting, and extending elements in arrays
65:
66: In addition, any required dynamic memory allocation and free'ing
67: is handled automatically.
68:
69: Supported data structures include the normal primitive C types,
70: plus arrays, structures, unions, and pointers to supported types,
71: as well as some other useful types such as opaque binary data,
72: IP address, regular expression, etc. User-defined types may be
73: added as well.
74:
75: Put simply, a structs type describes how to interpret a region
76: of memory so that the operations listed above may be peformed
77: in an automated fashion.
78:
79: Arrays must be defined using the "structs_array" structure.
80: Unions must be defined using the "structs_union" structure.
81:
82: Nested items in a data structure can be identified by names,
83: where each name component is either the name of a structure or
84: union field, or an array index. Name components are separated
85: by dots. For example, "foo.list.12" (see below).
86:
87: EXAMPLE
88: -------
89:
90: Consider the C data structure defined by "struct janfu":
91:
92: struct fubar {
93: struct structs_array list; // array of strings
94: };
95:
96: struct janfu {
97: u_int16_t value; // 16 bit hex value
98: struct fubar *foo; // fubar structure
99: };
100:
101: A memory region containing a 'struct janfu' would be described
102: in C code like so:
103:
104: // Descriptor for field 'list' in 'struct fubar': array of strings
105: static const struct structs_type list_array_type =
106: STRUCTS_ARRAY_TYPE(&structs_type_string, "list_elem", "list_elem");
107:
108: // Descriptor for 'struct fubar'
109: static const struct structs_field fubar_fields[] = {
110: STRUCTS_STRUCT_FIELD(fubar, list, &list_array_type),
111: STRUCTS_STRUCT_FIELD_END
112: };
113: static const struct structs_type fubar_type =
114: STRUCTS_STRUCT_TYPE(fubar, &fubar_fields);
115:
116: // Descriptor for a variable of type 'struct fubar *'
117: static const struct structs_type foo_ptr_type =
118: STRUCTS_POINTER_TYPE(&fubar_type, "struct fubar");
119:
120: // Descriptor for 'struct janfu'
121: static const struct structs_field janfu_fields[] = {
122: STRUCTS_STRUCT_FIELD(janfu, value, &structs_type_uint16),
123: STRUCTS_STRUCT_FIELD(janfu, foo, &foo_ptr_type),
124: STRUCTS_STRUCT_FIELD_END
125: };
126: static const struct structs_type janfu_type =
127: STRUCTS_STRUCT_TYPE(janfu, &janfu_fields);
128:
129: The type "janfu_type" describes a 'struct janfu' data structure.
130:
131: Then "foo.list.12" refers to the 12th item in the "list" array
132: (assuming it actually exists), counting from zero. It's value
133: could be accessed like this:
134:
135: void
136: print_list_12(const struct janfu *j)
137: {
138: char *s;
139:
140: s = structs_get_string(&janfu_type, "foo.list.12", j, NULL);
141: if (s == NULL) {
142: fprintf(stderr, "structs_get_string: %s: %s",
143: "foo.list.12", strerror(errno));
144: exit(1);
145: }
146: printf("foo.list.12 = %s\n", s);
147: free(s);
148: }
149:
150: An instance of a "struct janfu", if output as XML, might look
151: like this:
152:
153: <?xml version="1.0" standalone="yes"?>
154: <janfu>
155: <value>0x1234</value>
156: <list>
157: <list_elem>first list element</list_elem>
158: <list_elem>second list element</list_elem>
159: <list_elem>third list element</list_elem>
160: </list>
161: </janfu>
162:
163: A function call that would produce the above output is:
164:
165: void
166: dump_janfu(struct janfu *j)
167: {
168: structs_xml_output(&janfu_type, "janfu", NULL, j, stdout, NULL, 0);
169: }
170:
171: *********************************************************************/
172:
173: /* Name component separator */
174: #define STRUCTS_SEPARATOR '.'
175:
176: struct structs_type;
177:
178: /* For representing arbitrary binary data */
179: struct structs_data {
180: u_int length; /* number of bytes */
181: u_char *data; /* bytes */
182: };
183:
184: /*********************************************************************
185: STRUCTS TYPE METHODS
186: *********************************************************************/
187:
188: /*
189: * The structs type "init" method.
190: *
191: * The region of memory pointed to by "data" must be at least
192: * type->size bytes and should be uninitialized (i.e., it should
193: * not contain a valid instance of the type).
194: *
195: * This method should initialize the memory with a valid instance
196: * of the type, setting this new instance to be equal to the default
197: * value for the type, and allocating any resources required for the
198: * instance in the process.
199: *
200: * Returns 0 if successful, or -1 (and sets errno) if there was an error.
201: */
202: typedef int structs_init_t(const struct structs_type *type, void *data);
203:
204: /*
205: * The structs type "copy" method.
206: *
207: * The region of memory pointed to by "from" contains a valid instance
208: * of the type described by "type".
209: *
210: * The region of memory pointed to by "to" is uninitialized.
211: *
212: * This method should initialize "to" with a "deep" copy of the
213: * data structure pointed to by "from". The copy must be equal
214: * (according to the "equal" method) to the original.
215: *
216: * Returns 0 if successful, or -1 (and sets errno) if there was an error.
217: */
218: typedef int structs_copy_t(const struct structs_type *type,
219: const void *from, void *to);
220:
221: /*
222: * The structs type "equal" method.
223: *
224: * The regions of memory pointed to by "data1" and "data2" contain valid
225: * instances of the type described by "type".
226: *
227: * Returns 1 if "data1" and "data2" are equal (by a "deep" comparison), or
228: * 0 if not, or -1 (and sets errno) if there was an error.
229: */
230: typedef int structs_equal_t(const struct structs_type *type,
231: const void *data1, const void *data2);
232:
233: /*
234: * The structs type "ascify" method.
235: *
236: * The region of memory pointed to by "data" contains a valid instance
237: * of the type described by "type".
238: *
239: * The method should convert this instance into a NUL-terminated
240: * ASCII string stored in a dynamically allocated buffer that is
241: * allocated with the memory type described by "mtype".
242: *
243: * The ASCII string must be unique, in that it can be used as input
244: * to the "binify" method to create an instance equal (according to the
245: * "equal" method) to the original.
246: *
247: * Returns the ASCII string buffer if successful, or NULL
248: * (and sets errno) if error.
249: */
250: typedef char *structs_ascify_t(const struct structs_type *type,
251: const char *mtype, const void *data);
252:
253: /*
254: * The structs type "binify" method.
255: *
256: * The region of memory pointed to by "data" is uninitialized.
257: *
258: * The variable "ascii" points to a NUL-terminated string. This method
259: * should use the contents of the string to create a new instace of
260: * the type in the memory pointed to by "data".
261: *
262: * Returns 0 if successful, or -1 if there was an error. In the latter
263: * case, either errno should be set, or a more informative error string
264: * may be printed (including NUL) into "ebuf", which has total size "emax"
265: * (see snprintf(3)).
266: *
267: * This method must be robust in the face of bogus data in "ascii";
268: * it must return an error if "ascii" is invalid.
269: */
270: typedef int structs_binify_t(const struct structs_type *type,
271: const char *ascii, void *data, char *ebuf, size_t emax);
272:
273: /*
274: * The structs type "encode" method.
275: *
276: * The region of memory pointed to by "data" contains a valid instance
277: * of the type described by "type".
278: *
279: * This method should encode the data structure into a host order
280: * independent, self-delimiting sequence of bytes. The sequence must be
281: * stored in a dynamically allocated buffer allocated with the memory type
282: * described by "mtype", and "code" must be filled in with the buffer's
283: * pointer and length.
284: *
285: * The binary sequence must be unique, in that it can be used as input
286: * to the "decode" method to create an instance equal (according to the
287: * "equal" method) to the original.
288: *
289: * Returns 0 if successful, or -1 (and sets errno) if there was an error.
290: */
291: typedef int structs_encode_t(const struct structs_type *type,
292: const char *mtype, struct structs_data *code,
293: const void *data);
294:
295: /*
296: * The structs type "decode" method.
297: *
298: * The region of memory pointed to by "data" is uninitialized.
299: *
300: * The "code" parameter points to a sequence of "cmax" binary data bytes.
301: * This method should decode the binary data and use it to reconstruct
302: * an instance of "type" in the memory region pointed to by "data".
303: *
304: * Returns the number of bytes consumed in the decoding process if
305: * successful, or -1 (and sets errno) if there was an error. In the
306: * latter case, either errno should be set, or a more informative error
307: * string may be printed (including NUL) into "ebuf", which has total
308: * size "emax" (see snprintf(3)).
309: */
310: typedef int structs_decode_t(const struct structs_type *type,
311: const u_char *code, size_t cmax, void *data,
312: char *ebuf, size_t emax);
313:
314: /*
315: * The structs type "uninit" method.
316: *
317: * The region of memory pointed to by "data" contains a valid instance
318: * of the type described by "type".
319: *
320: * This method should free any resources associated with the instance
321: * pointed to by "data". Upon return, the memory pointed to by "data"
322: * may be no longer used or referenced.
323: */
324: typedef void structs_uninit_t(const struct structs_type *type, void *data);
325:
326: /*********************************************************************
327: STRUCTS TYPE DEFINITION
328: *********************************************************************/
329:
330: /*
331: * This structure defines a structs type.
332: */
333: struct structs_type {
334: size_t size; /* size of an instance */
335: const char *name; /* human informative name */
336: int tclass; /* see classes listed below */
337: structs_init_t *init; /* type "init" method */
338: structs_copy_t *copy; /* type "copy" method */
339: structs_equal_t *equal; /* type "equal" method */
340: structs_ascify_t *ascify; /* type "ascify" method */
341: structs_binify_t *binify; /* type "binify" method */
342: structs_encode_t *encode; /* type "encode" method */
343: structs_decode_t *decode; /* type "decode" method */
344: structs_uninit_t *uninit; /* type "uninit" method */
345: union { /* type specific arguments */
346: const void *v;
347: const char *s;
348: int i;
349: } args[3];
350: };
351:
352: /* Classes of types */
353: #define STRUCTS_TYPE_PRIMITIVE 0
354: #define STRUCTS_TYPE_POINTER 1
355: #define STRUCTS_TYPE_ARRAY 2
356: #define STRUCTS_TYPE_FIXEDARRAY 3
357: #define STRUCTS_TYPE_STRUCTURE 4
358: #define STRUCTS_TYPE_UNION 5
359:
360: /*********************************************************************
361: GENERIC TYPE METHODS
362: *********************************************************************/
363:
364: __BEGIN_DECLS
365:
366: /* These operate on simple block regions of memory */
367: extern structs_init_t structs_region_init;
368: extern structs_copy_t structs_region_copy;
369: extern structs_equal_t structs_region_equal;
370:
371: extern structs_encode_t structs_region_encode;
372: extern structs_decode_t structs_region_decode;
373: extern structs_encode_t structs_region_encode_netorder;
374: extern structs_decode_t structs_region_decode_netorder;
375:
376: /* These always return an error with errno set to EOPNOTSUPP */
377: extern structs_init_t structs_notsupp_init;
378: extern structs_copy_t structs_notsupp_copy;
379: extern structs_equal_t structs_notsupp_equal;
380: extern structs_ascify_t structs_notsupp_ascify;
381: extern structs_binify_t structs_notsupp_binify;
382: extern structs_encode_t structs_notsupp_encode;
383: extern structs_decode_t structs_notsupp_decode;
384:
385: /* This copies any type that is ascifyable by converting to ASCII and back */
386: extern structs_copy_t structs_ascii_copy;
387:
388: /* This does nothing */
389: extern structs_uninit_t structs_nothing_free;
390:
391: __END_DECLS
392:
393: /*********************************************************************
394: BASIC STRUCTS FUNCTIONS
395: *********************************************************************/
396:
397: __BEGIN_DECLS
398:
399: /*
400: * Initialize an item in a data structure to its default value.
401: * This assumes the item is not already initialized.
402: *
403: * If "name" is NULL or empty string, the entire structure is initialied.
404: *
405: * Returns 0 if successful, otherwise -1 and sets errno.
406: */
407: extern int structs_init(const struct structs_type *type,
408: const char *name, void *data);
409:
410: /*
411: * Reset an item in a data structure to its default value.
412: * This assumes the item is already initialized.
413: *
414: * If "name" is NULL or empty string, the entire structure is reset.
415: *
416: * Returns 0 if successful, otherwise -1 and sets errno.
417: */
418: extern int structs_reset(const struct structs_type *type,
419: const char *name, void *data);
420:
421: /*
422: * Free an item in a data structure, returning it to its uninitialized state.
423: * This function can be thought of as the opposite of structs_init().
424: *
425: * If "name" is NULL or empty string, the entire structure is free'd.
426: *
427: * Returns 0 if successful, otherwise -1 and sets errno.
428: */
429: extern int structs_free(const struct structs_type *type,
430: const char *name, void *data);
431:
432: /*
433: * Compare two data structures of the same type for equality.
434: *
435: * If "name" is NULL or empty string, the entire structures are compared.
436: * Otherwise, the "name" sub-elements of both structures are compared.
437: *
438: * Returns zero or one (for not equal or equal, respectively),
439: * or -1 (and sets errno) if there was an error.
440: */
441: extern int structs_equal(const struct structs_type *type,
442: const char *name, const void *data1, const void *data2);
443:
444: /*
445: * Find an item in a data structure structure.
446: *
447: * If "name" is NULL or empty string, "type" is returned and "datap"
448: * is unmodified.
449: *
450: * If "set_union" is true, then any unions in the path will be reset
451: * so that their fields agree with "name" in the case that "name" contains
452: * a different field name than is currently set for that union. However,
453: * these changes will only occur if "name" is actually found.
454: *
455: * Returns the type of the item and points *datap at it, or NULL
456: * (and sets errno) if there was an error.
457: */
458: extern const struct structs_type *structs_find(
459: const struct structs_type *type, const char *name,
460: void **datap, int set_union);
461:
462: /*
463: * Get a copy of an item from a data structure.
464: *
465: * If "name" is NULL or empty string, the entire structure is copied.
466: *
467: * It is assumed that "to" points to a region big enough to hold
468: * the copy of the item. "to" will not be free'd first, so it should
469: * not already be initialized.
470: *
471: * Note: "name" is only applied to "from". The structs types of
472: * "from.<name>" and "to" must be the same.
473: *
474: * Returns 0 if successful, otherwise -1 and sets errno.
475: */
476: extern int structs_get(const struct structs_type *type,
477: const char *name, const void *from, void *to);
478:
479: /*
480: * Set an item in a data structure.
481: *
482: * If "name" is NULL or empty string, the entire structure is copied.
483: *
484: * It is assumed that "to" is already initialized.
485: *
486: * Note: "name" is only applied to "to". The structs types of
487: * "from" and "to.<name>" must be the same.
488: *
489: * Returns 0 if successful, otherwise -1 and sets errno.
490: */
491: extern int structs_set(const struct structs_type *type,
492: const void *from, const char *name, void *to);
493:
494: /*
495: * Get the ASCII form of an item, in a string allocated with the
496: * memory type described by "mtype".
497: *
498: * The caller is reponsible for freeing the returned string.
499: *
500: * Returns the ASCII string if successful, otherwise NULL and sets errno.
501: */
502: extern char *structs_get_string(const struct structs_type *type,
503: const char *name, const void *data, const char *mtype);
504:
505: /*
506: * Set the value of an item in a data structure from an ASCII string.
507: *
508: * The referred to item must be of a type that supports ASCII encoding,
509: * and is assumed to be already initialized.
510: *
511: * Returns 0 if successful, otherwise -1 and sets errno.
512: */
513: extern int structs_set_string(const struct structs_type *type,
514: const char *name, const char *ascii,
515: void *data, char *ebuf, size_t emax);
516:
517: /*
518: * Get the binary encoded form of an item, put into a buffer
519: * allocated with memory type "mtype" and described by "code".
520: *
521: * The caller is reponsible for freeing the allocated bytes.
522: *
523: * Returns 0 if successful, otherwise -1 and sets errno.
524: */
525: extern int structs_get_binary(const struct structs_type *type,
526: const char *name, const void *data,
527: const char *mtype, struct structs_data *code);
528:
529: /*
530: * Set an item's value from its binary encoded value.
531: *
532: * The referred to item is assumed to be already initialized.
533: *
534: * Returns 0 if successful, otherwise -1 and sets errno.
535: */
536: extern int structs_set_binary(const struct structs_type *type,
537: const char *name, const struct structs_data *code,
538: void *data, char *ebuf, size_t emax);
539:
540: /*
541: * Traverse a structure, returning the names of all primitive fields
542: * (i.e., the "leaves" of the data structure).
543: *
544: * The number of items is returned, or -1 and errno if there was an error.
545: * The caller must free the list by freeing each string in the array,
546: * and then the array itself; all memory is allocated using memory type
547: * "mtype".
548: *
549: * If "type" is a primitive type, a list of length one is returned
550: * containing an empty string.
551: */
552: extern int structs_traverse(const struct structs_type *type,
553: const void *data, char ***listp, const char *mtype);
554:
555: __END_DECLS
556:
557: #endif /* _PDEL_STRUCTS_STRUCTS_H_ */
558:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to structs.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / structs