Annotation of gpl/axl/src/axl_decl.h, revision 1.1.1.1
1.1 misho 1: /*
2: * LibAxl: Another XML library
3: * Copyright (C) 2006 Advanced Software Production Line, S.L.
4: *
5: * This program is free software; you can redistribute it and/or
6: * modify it under the terms of the GNU Lesser General Public License
7: * as published by the Free Software Foundation; either version 2.1 of
8: * the License, or (at your option) any later version.
9: *
10: * This program is distributed in the hope that it will be useful,
11: * but WITHOUT ANY WARRANTY; without even the implied warranty of
12: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13: * GNU Lesser General Public License for more details.
14: *
15: * You should have received a copy of the GNU Lesser General Public
16: * License along with this program; if not, write to the Free
17: * Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
18: * 02111-1307 USA
19: *
20: * You may find a copy of the license under this software is released
21: * at COPYING file. This is LGPL software: you are welcome to
22: * develop proprietary applications using this library without any
23: * royalty or fee but returning back any change, improvement or
24: * addition in the form of source code, project image, documentation
25: * patches, etc.
26: *
27: * For commercial support on build XML enabled solutions contact us:
28: *
29: * Postal address:
30: * Advanced Software Production Line, S.L.
31: * Edificio Alius A, Oficina 102,
32: * C/ Antonio Suarez Nº 10,
33: * Alcalá de Henares 28802 Madrid
34: * Spain
35: *
36: * Email address:
37: * info@aspl.es - http://www.aspl.es/xml
38: */
39: #ifndef __AXL_DECL_H__
40: #define __AXL_DECL_H__
41:
42: /* include platform specific configuration */
43: #include <axl_config.h>
44:
45: /* include this at this place to load GNU extensions */
46: #if defined(__GNUC__)
47: # ifndef _GNU_SOURCE
48: # define _GNU_SOURCE
49: # endif
50: # define __AXL_PRETTY_FUNCTION__ __PRETTY_FUNCTION__
51: # define __AXL_LINE__ __LINE__
52: # define __AXL_FILE__ __FILE__
53: #elif defined(_MSC_VER)
54: # define __AXL_PRETTY_FUNCTION__ __FUNCDNAME__
55: # define __AXL_LINE__ __LINE__
56: # define __AXL_FILE__ __FILE__
57: #else
58: /* unknown compiler */
59: #define __AXL_PRETTY_FUNCTION__ ""
60: #define __AXL_LINE__ 0
61: #define __AXL_FILE__ ""
62: #endif
63:
64: #include <stdio.h>
65: #include <stdlib.h>
66: #include <stdarg.h>
67: #include <string.h>
68:
69: /* only include unistd.h if unix platform is found or gnu gcc compiler
70: * is found */
71: #if defined(__GNUC__) || defined(AXL_OS_UNIX)
72: # include <unistd.h>
73: #endif
74:
75: #include <sys/types.h>
76: #include <sys/stat.h>
77: #include <fcntl.h>
78: #include <ctype.h>
79:
80: /**
81: * \defgroup axl_decl_module Axl Declarations: Common Axl declarations, Types, macros, and support functions.
82: */
83:
84: /**
85: * \addtogroup axl_decl_module
86: * @{
87: */
88:
89:
90: /**
91: * @brief Axl XML document type definition.
92: *
93: * This type represents a reference to an entiry XML document loaded
94: * into memory. Functions to be used to load XML document could be the
95: * following:
96: *
97: * - \ref axl_doc_parse
98: * - \ref axl_doc_parse_strings
99: * - \ref axl_doc_parse_from_file
100: *
101: * You can also create an empty document by using \ref axl_doc_create
102: * and fill the initial root node using the \ref axl_doc_set_root
103: * function. Once the document have an initial root node, you can add
104: * more nodes as childs to the root element previously added.
105: *
106: * Check the \ref axl_doc_module "axlDoc API reference" to get more
107: * information.
108: */
109: typedef struct _axlDoc axlDoc;
110:
111: /**
112: * @brief An abstraction that allows to hold an xml node or any other
113: * content that can be found inside an xml node: comments, content,
114: * CDATA-content, PI, entity references.
115: *
116: * This type is mainly used inside the MIXED API, which allows to get
117: * access to every particular item found inside a particular node
118: * (\ref axlNode). Every item has a type (\ref AxlItemType) and a
119: * content that is being encapsulated and usually accessed by \ref
120: * axl_item_get_data.
121: *
122: * Check the \ref axl_item_module "Axl Item interface" for more information.
123: */
124: typedef struct _axlItem axlItem;
125:
126: /**
127: * @internal Factory allocation type.
128: */
129: typedef struct _axlFactory axlFactory;
130:
131: /**
132: * @internal String factory allocation type.
133: */
134: typedef struct _axlStrFactory axlStrFactory;
135:
136: /**
137: * @brief Axl XML node type definition.
138: *
139: * This type reference represents a single XML node. To create a xml node you can use:
140: *
141: * - \ref axl_node_create
142: *
143: * To get the node name or if the node have childs or if it is empty,
144: * you can use the following functions:
145: *
146: * - \ref axl_node_get_name
147: * - \ref axl_node_is_empty
148: * - \ref axl_node_have_childs
149: *
150: * To get the \ref axlNode content you can use the following
151: * functions:
152: *
153: * - \ref axl_node_get_content
154: * - \ref axl_node_get_content_copy
155: * - \ref axl_node_get_content_trans
156: *
157: * For attributes manipulation, you can using the following functions
158: * to set them and retrieve them:
159: *
160: * - \ref axl_node_get_attribute_value
161: * - \ref axl_node_get_attribute_value_copy
162: * - \ref axl_node_get_attribute_value_trans
163: *
164: * To retrive childs number or childs inside the given \ref axlNode
165: * you can use the following function:
166: *
167: * - \ref axl_node_get_child_num
168: * - \ref axl_node_get_child_nth
169: *
170: * You can also use the following functions to get the parent node for
171: * a provided xml node child and the next xml node found at the same
172: * level, for a provided xml node reference.
173: *
174: * - \ref axl_node_get_parent
175: * - \ref axl_node_get_next
176: *
177: * Check the axlNode \ref axl_node_module "API for more information".
178: */
179: typedef struct _axlNode axlNode;
180:
181: /**
182: * @brief Public cursor type used to iterate over attributes installed
183: * on a particular node (see \ref axl_node_attr_cursor_new to get examples and more information).
184: */
185: typedef struct _axlAttrCursor axlAttrCursor;
186:
187: /**
188: * @brief Axl DTD entity representation.
189: */
190: typedef struct _axlDtd axlDtd;
191:
192: /**
193: * @brief Axl DTD entity element declaration.
194: */
195: typedef struct _axlDtdElement axlDtdElement;
196:
197: /**
198: * @brief Axl DTD item list element declaration.
199: */
200: typedef struct _axlDtdElementList axlDtdElementList;
201:
202: /**
203: * @brief Axl DTD item list element declaration.
204: */
205: typedef struct _axlDtdElementListNode axlDtdElementListNode;
206:
207:
208: /**
209: * @brief Axl DTD attribute declaration (<!ATTLIST..>)
210: */
211: typedef struct _axlDtdAttribute axlDtdAttribute;
212:
213: /**
214: * @brief Axl DTD attribute list decleration inside \ref axlDtdAttribute.
215: */
216: typedef struct _axlDtdAttributeDecl axlDtdAttributeDecl;
217:
218: /**
219: * @brief Axl DTD entity declaration (<!ENTITY support>)
220: */
221: typedef struct _axlDtdEntity axlDtdEntity;
222:
223: /**
224: * @brief Support type definition for \ref axlDtdEntity, which holds
225: * information about external resource pointed by the \ref
226: * axlDtdEntity instance.
227: */
228: typedef struct _axlDtdEntityExternalData axlDtdEntityExternalData;
229:
230: /**
231: * @brief Declares the entity type for a provided \ref axlDtdEntity.
232: */
233: typedef enum {
234: /**
235: * @brief The \ref axlDtdEntity definition represents a
236: * general entity definition (that comes without % before the
237: * entity name).
238: */
239: GENERAL_ENTITY,
240: /**
241: * @brief The \ref axlDtdEntity definition represents a
242: * parameter entity definition (that comes with a % before the
243: * entity name, making this entity definition to be only
244: * usable from a DTD definition).
245: */
246: PARAMETER_ENTITY
247: }axlDtdEntityType;
248:
249: /**
250: * @brief Attribute type declaration (the type of the attribute
251: * constrain). This type is used to identifier the attribute contains
252: * applied to the node selected.
253: */
254: typedef enum {
255: /**
256: * @brief The attribute type is defined but its content is
257: * CDATA (any string value is allowed), activated when used 'CDATA'.
258: */
259: CDATA_ATTRIBUTE,
260: /**
261: * @brief Especific token declaration that implicitly contrain
262: * the node attribute value, activated when used 'ID'.
263: */
264: TOKENIZED_TYPE_ID,
265: /**
266: * @brief Especific token declaration that implicitly contrain
267: * the node attribute value, activated when used 'IDREF'.
268: */
269: TOKENIZED_TYPE_IDREF,
270: /**
271: * @brief Especific token declaration that implicitly contrain
272: * the node attribute value, activated when used 'IDREFS'.
273: */
274: TOKENIZED_TYPE_IDREFS,
275: /**
276: * @brief Especific token declaration that implicitly contrain
277: * the node attribute value, activated when used 'ENTITY'.
278: */
279: TOKENIZED_TYPE_ENTITY,
280: /**
281: * @brief Especific token declaration that implicitly contrain
282: * the node attribute value, activated when used 'ENTITIES'.
283: */
284: TOKENIZED_TYPE_ENTITIES,
285: /**
286: * @brief Especific token declaration that implicitly contrain
287: * the node attribute value, activated when used 'NMTOKEN'.
288: */
289: TOKENIZED_TYPE_NMTOKEN,
290: /**
291: * @brief Especific token declaration that implicitly contrain
292: * the node attribute value, activated when used 'NMTOKENS'.
293: */
294: TOKENIZED_TYPE_NMTOKENS,
295: /**
296: * @brief The attribute type declaration is constrained to a
297: * set of values. This values are considered as an
298: * enumeration.
299: */
300: ENUMERATION_TYPE,
301: /**
302: * @brief Attribute type not supported yet (although defined).
303: */
304: NOTATION_TYPE
305: } AxlDtdAttributeType;
306:
307: /**
308: * @brief Defines the DTD attribute declaration default state.
309: */
310: typedef enum {
311: /**
312: * @brief The attribute is required as especified by the
313: * attribute declaration.
314: */
315: ATT_REQUIRED,
316: /**
317: * @brief The attribute is not requried, however, if it
318: * appears it must follow the attribute type declaration.
319: */
320: ATT_IMPLIED,
321: /**
322: * @brief The attribute must appear and have the value
323: * provided as the default.
324: */
325: ATT_FIXED
326: }AxlDtdAttributeDefaults;
327:
328:
329: /**
330: * @brief The type of the DTD sequences stored by the \ref
331: * axlDtdElementList.
332: */
333: typedef enum {
334: /**
335: * @internal
336: *
337: * Internal value used by the library to support mixing
338: * content seperator types detection.
339: */
340: STILL_UNDEF = 0,
341: /**
342: * @brief Represents that the item selection is configured to
343: * be a choice (a selection allowed from any item inside the
344: * collection).
345: */
346: CHOICE = 1,
347: /**
348: * @brief Represents that the item selection is configured to
349: * select each item in the order they apper.
350: */
351: SEQUENCE = 2
352: }AxlDtdNestedType;
353:
354: /**
355: * @brief An indication of the element type stored on the provided
356: * \ref axlDtdElementListNode reference.
357: *
358: * An \ref axlDtdElementListNode reference could contain a single
359: * reference to a content particule name, that is the XML node name to
360: * be allowed to be used at the provided position or a reference to an
361: * \ref axlDtdElementList which contains a nested list containing more
362: * content particules.
363: *
364: */
365: typedef enum {
366: /**
367: * @internal
368: * Represents the not defined value.
369: */
370: AXL_ELEMENT_NOT_DEFINED = 1,
371: /**
372: * @brief The reference contains an \ref axlDtdElementList.
373: */
374: AXL_ELEMENT_LIST = 2,
375: /**
376: * @brief The reference contains a reference to a leaf node, a
377: * content particule.
378: */
379: AXL_ELEMENT_NODE = 3
380: } NodeType;
381:
382: /**
383: * @brief DTD element type enumeration.
384: *
385: * While using DTD declaration, <b>ELEMENT</b> used to define how your
386: * xml document is structured and constrained, are clasified using the
387: * following values.
388: *
389: * This type specification must not be confused with \ref NodeType,
390: * which is the configuration for an element, inside the content DTD
391: * element specification.
392: */
393: typedef enum {
394: /**
395: * @internal
396: *
397: * Internal value to avoid confusing EMPTY declaration with a
398: * non-defined value.
399: */
400: ELEMENT_TYPE_UNKNOWN = 0,
401: /**
402: * @brief Used to represent that the element declaration have
403: * no content inside it. This includes not only PCDATA (data
404: * stored between xml tags) but also any child declaration.
405: */
406: ELEMENT_TYPE_EMPTY = 1,
407: /**
408: * @brief Used to represent that the element used in your xml
409: * document could contain anthing without any contraint.
410: */
411: ELEMENT_TYPE_ANY = 2,
412: /**
413: * @brief Used to represent that the following xml node have
414: * content not only defined by a set of allowed xml nodes but
415: * also PCDATA.
416: */
417: ELEMENT_TYPE_MIXED = 3,
418: /**
419: * @brief Used to represent that the folowing xml node have
420: * only xml nodes as content, in the form of xml childs,
421: * without inlucing PCDATA.
422: */
423: ELEMENT_TYPE_CHILDREN = 4,
424: /**
425: * @brief Used to represent that the DTD element specification
426: * contains only PCDATA. No child nodes or childs nodes mixed
427: * with PCDATA.
428: */
429: ELEMENT_TYPE_PCDATA = 5
430: } AxlDtdElementType;
431:
432: /**
433: * @brief Current configuration for elements definied inside a ELEMENT
434: * DTD declaration.
435: */
436: typedef enum {
437: /**
438: * @internal
439: *
440: * Internal representation to identify wrong repetition
441: * especification values.
442: */
443: DTD_TIMES_UNKNOWN = 0,
444: /**
445: * Current configuration for DTD element content specification
446: * signals that it must appear one and only one times.
447: */
448: ONE_AND_ONLY_ONE = 1,
449: /**
450: * Current configuration for DTD element content specification
451: * signals that it could appear zero or one time.
452: */
453: ZERO_OR_ONE = 2,
454: /**
455: * Current configuration for DTD element content specification
456: * signals
457: */
458: ZERO_OR_MANY = 3,
459: /**
460: * Current configuration for DTD element content specification
461: * signals that it must appear one up to many times.
462: */
463: ONE_OR_MANY = 4
464: }AxlDtdTimes;
465:
466: /**
467: * @brief Item types that can hold an xml node (\ref axlNode).
468: *
469: * \ref AxlItemType is used to notify the type for a particular item
470: * (\ref axlItem) that is stored as a child on a particular \ref
471: * axlNode.
472: *
473: * This is mainly used inside the MIXED API, which is the way that Axl
474: * exposes the content of a xml node that is expected to contain more
475: * nodes mixed with more content.
476: *
477: * Each type represents a particular basic unit that could be found as
478: * a child item inside an xml node.
479: */
480: typedef enum {
481: /**
482: * @brief The \ref axlItem is encapsulating another item
483: * node. Calling to \ref axl_item_get_data will return a
484: * reference to an \ref axlNode.
485: *
486: */
487: ITEM_NODE = 1 << 0,
488: /**
489: * @brief The \ref axlItem is encapsulating an node
490: * content. Calling to the convenience function \ref
491: * axl_item_get_content to get the content and the size that
492: * is stored in the \ref axlItem with this type.
493: */
494: ITEM_CONTENT = 1 << 1,
495: /**
496: * @brief The \ref axlItem is encapsulating an application
497: * process instruction. Calling to \ref axl_item_get_data will
498: * return a reference to a \ref axlPI.
499: *
500: */
501: ITEM_PI = 1 << 2,
502:
503: /**
504: * @brief The \ref axlItem is encapsulating an xml
505: * comment.
506: *
507: * XML comments inside Axl are handled xml node content. The
508: * comment that is returned from the function has the initial
509: * '<!--' and the ending '-->' elements stripped from its
510: * body.
511: *
512: * You must use the convenience function \ref
513: * axl_item_get_content to get the comment content and the
514: * size that is stored on the \ref axlItem.
515: */
516: ITEM_COMMENT = 1 << 3,
517: /**
518: * @brief The \ref axlItem is encapsulating an xml entity
519: * reference that wasn't resolved yet.
520: *
521: * Not implemented yet.
522: */
523: ITEM_REF = 1 << 4,
524: /**
525: * @brief The \ref axlItem is encapsulating an xml content
526: * that was enclosed using the <![CDATA[]]> construction. This
527: * child item works the same as \ref ITEM_CONTENT but, adding
528: * the CDATA semantic and the fact that the content wasn't
529: * parsed by the Axl XML engine.
530: *
531: * You must use the convenience function \ref
532: * axl_item_get_content to get the CDATA content and the size
533: * that is stored on the \ref axlItem.
534: *
535: */
536: ITEM_CDATA = 1 << 6,
537:
538: /**
539: * @internal Item type which allows to signal that the item
540: * comes from an item factory and shouldn't be deallocated in
541: * the usual manner.
542: */
543: ITEM_FROM_FACTORY = 1 << 7,
544: /**
545: * @internal Item type which allows to signal that the content
546: * item comes from an item factory and shouldn't be
547: * deallocated in the usual manner.
548: */
549: ITEM_CONTENT_FROM_FACTORY = 1 << 8
550: }AxlItemType;
551:
552: /**
553: * @brief Simple alias for the AxlDtdElementType.
554: */
555: typedef AxlDtdElementType ElementType;
556:
557: /**
558: * @brief Axl DTD entity attribute element declaration.
559: */
560: typedef struct _axtDtdAttr axlDtdAttr;
561:
562: /**
563: * @brief Axl Processing instruction type definition.
564: */
565: typedef struct _axlPI axlPI;
566:
567: /**
568: * @brief Axl error reporting variable.
569: *
570: * All Axl interface report errors found, with a textual diagnostic,
571: * to the application level using this variable. You have to know that
572: * it is also optional, so every function that receives an \ref
573: * axlError, will properly handle a NULL reference received.
574: *
575: * Once an error was detected, for that condition you must check the
576: * documentation provided for the function that is failing, you can
577: * get the error code and the error textual diagnostic by using the
578: * following functions:
579: *
580: * - \ref axl_error_get_code
581: * - \ref axl_error_get
582: *
583: * If an error is not detected, there is no especial operation to be
584: * done once returned the function that has received the \ref axlError
585: * error reference. However, if an error is detected, the reference
586: * must be deallocated by using the following function:
587: *
588: * - \ref axl_error_free
589: *
590: * Here is an example:
591: * \code
592: * // declare the axlError reference
593: * axlError * error;
594: *
595: * // parse the document, giving a reference to the axlError
596: * // NOTE: you can safely provide a NULL reference.
597: * doc = axl_doc_parse_from_file ("test.xml", &error);
598: * if (doc == NULL) {
599: * printf ("Parse error: code=%d, message=%s\n",
600: * axl_error_get_code (error), axl_error_get (error));
601: * axl_error_free (error);
602: * return axl_false;
603: * }
604: *
605: * // beyond this point, it is not required to do
606: * // any especial task with the axlError reference
607: * \endcode
608: *
609: * To get more information about the \ref axlError check its \ref axl_error_module "API documentation".
610: */
611: typedef struct _axlError axlError;
612:
613: /**
614: * @brief Axl Stream representation (an abstraction API to manage
615: * source of data with convenience functions).
616: */
617: typedef struct _axlStream axlStream;
618:
619: /**
620: * @brief (DEPRECATED use \ref axl_true) Type definition to represent a boolean true value, that is equal to 1.
621: */
622: #define AXL_TRUE (axl_true)
623:
624: /**
625: * @brief (DEPRECATED use \ref axl_false) Type definition to represent a* boolean false value, that is equal to 0.
626: */
627: #define AXL_FALSE (axl_false)
628:
629: /**
630: * @brief Alias declaration to bind the <i>int</i> to the <b>boolean</b>
631: * concept (TRUE / FALSE states) (DEPRECATED).
632: *
633: * This is mainly used to emphasize that some integer values that
634: * returns some function must be considered to be \ref axl_true or \ref
635: * axl_false, that represents the boolean TRUE and FALSE values.
636: *
637: * This allows to perform boolean comparations using structure
638: * controls like if, while, but also making a differenciation about
639: * the boolean values and integer values.
640: *
641: * You are also allowed to use <b>bool</b> as boolean type definition.
642: */
643: typedef int aboolean;
644:
645: /**
646: * @brief Bool definition for the Axl library. This type built on top
647: * of <b>int</b> is used along with \ref axl_false and \ref axl_true
648: * to model those API functions and attributes that returns or receive
649: * a boolean state.
650: */
651: typedef int axl_bool;
652:
653: /**
654: * @brief Common definition to have false (\ref axl_false) value (which is defined to 0 integer value).
655: */
656: #define axl_false ((int)0)
657: /**
658: * @brief Common definition to have true (\ref axl_true) value (which is defined to 1 integer value).
659: */
660: #define axl_true ((int)1)
661:
662: /**
663: * @brief Boolean, deprecated, compatibility mode provided for those
664: * applications and libraries built on top of Axl Library or any
665: * library on top of it (like Vortex Library) to support people from C
666: * user space using bool type definition and its corresponding values
667: * false and true as they was available before 0.5.5 release.
668: *
669: * Definitions provided by this compatibility mode are:
670: *
671: * - \ref bool
672: * - \ref true
673: * - \ref false
674: */
675: #if !defined(__cplusplus) && !defined(__bool_true_false_are_defined) && !defined(__axl_disable_broken_bool_def__)
676: /**
677: * @brief <b>DEPRECATED:</b> boolean definition provided to support
678: * applications and libraries using this type as defined by Axl
679: * Library before 0.5.5 release. Do use this for newly written code.
680: */
681: typedef int bool;
682:
683: /**
684: * @brief <b>DEPRECATED:</b> boolean false definition provided to
685: * support applications and libraries using this type as defined by
686: * Axl Library before 0.5.5 release. Do use this for newly written
687: * code.
688: */
689: #define false axl_false
690:
691: /**
692: * @brief <b>DEPRECATED:</b> boolean true definition provided to
693: * support applications and libraries using this type as defined by
694: * Axl Library before 0.5.5 release. Do use this for newly written
695: * code.
696: */
697: #define true axl_true
698: #endif
699:
700:
701: /**
702: * @brief Pointer to any structure definition. It should be required
703: * to use this definition, however, some platforms doesn't support the
704: * <b>void *</b> making it necessary to use the <b>char *</b>
705: * definition as a general way to represent references.
706: */
707: typedef void * axlPointer;
708:
709: /**
710: * @brief \ref axlList definition, a list implementation.
711: * See \ref axl_list_new for more information about using this type.
712: */
713: typedef struct _axlList axlList;
714:
715: /**
716: * @brief \ref axlListCursor definition, a iterator type used to
717: * traverse an axlList in a efficient way. See \ref axl_list_cursor_get.
718: */
719: typedef struct _axlListCursor axlListCursor;
720:
721: /**
722: * @brief \ref axlStack definitinon, a stack implementation on top of \ref
723: * axlList.
724: * See \ref axl_stack_new for more information about using this type.
725: */
726: typedef struct _axlStack axlStack;
727:
728: /**
729: * @brief Compact binary state representation stack.
730: *
731: * This data structure allows to store binary/boolean values in an
732: * efficient way.
733: *
734: * See \ref axl_binary_stack_new for more information.
735: */
736: typedef struct _axlBinaryStack axlBinaryStack;
737:
738: /**
739: * @brief \ref axlHash definition, a hash table to store key indexed
740: * values.
741: * See \ref axl_hash_new for more information about using this type.
742: */
743: typedef struct _axlHash axlHash;
744:
745: /**
746: * @brief \ref axlHashCursor definition, a support type that is used
747: * to iterate a hash in a linear mode, without calling to \ref
748: * axl_hash_foreach family functions (see \ref axl_hash_cursor_new).
749: */
750: typedef struct _axlHashCursor axlHashCursor;
751:
752: /**
753: * @brief Handler definition used to compare two elements.
754: *
755: * In the case they are equal, 0 is returned. In the case a should be
756: * before b the -1 is returned. In the case a should be after b then 1
757: * should be returned. A properly configured handler should help
758: * collections and other function to order elements.
759: *
760: * @param a The element to compare
761: * @param b The other element to compare
762: *
763: * @return A value selected from {-1,0,1} according to previous
764: * description.
765: */
766: typedef int (*axlEqualFunc) (axlPointer a, axlPointer b);
767:
768: /**
769: * @brief Handler definition which represent deallocation functions.
770: *
771: * @param ptr The pointer to the memory to be released.
772: */
773: typedef void (*axlDestroyFunc) (axlPointer ptr);
774:
775: /**
776: * @brief Handler used to represent the set of functions that could be
777: * used to configure the axl stream allocation method. See \ref
778: * axl_stream_set_buffer_alloc.
779: *
780: * @param size The amount of memory to be allocated (memory requested by the axl stream).
781: *
782: * @param data User defined pointer configured at \ref axl_stream_set_buffer_alloc.
783: *
784: * @return The handler must return newly allocated memory to hold <b>size</b>
785: * bytes.
786: */
787: typedef char * (*axlStreamAlloc) (int size, axlPointer data);
788:
789: /**
790: * @brief Handler definition for the set of functions that allows to
791: * translate content into a particular format back to utf-8, which is
792: * the default format used for internal data stored by Axl.
793: *
794: * @param source The source content to be decoded into utf-8.
795: *
796: * @param source_size The size of the source content to be decoded.
797: *
798: * @param source_encoding The encoding of the source.
799: *
800: * @param output The output of the decode operation. This buffer is
801: * memory allocated by the caller. The size to be written is limited
802: * by the following parameter.
803: *
804: * @param output_size The size of the output produced (in terms of
805: * octects not utf-8 logical units).
806: *
807: * @param remain_source_index Reference where the last index of valid
808: * input still pending to be process. Especially useful under
809: * situation where the decode function returns 2.
810: *
811: * @return The handler must return 1 if the operation was completed, 2
812: * if the operation was completed but not enough size was found on
813: * output buffer to store the content or 0 if the function fails.
814: */
815: typedef int (*axlStreamDecode) (const char * source, int source_size,
816: const char * source_encoding,
817: char * output, int output_size,
818: int * output_converted,
819: int * remain_source_index,
820: axlPointer user_data);
821:
822: /**
823: * @brief A handler definition used by axl stream API to define the
824: * set of functions that can be used to check content read from a file
825: * into the axl stream buffer. The initial intention was to allow axl
826: * babel to install an utf-8 content checked if an xml entity in utf-8
827: * was detected but it allows more features.
828: *
829: * This handler is configured using \ref axl_stream_setup_check.
830: *
831: * @param source The source to check.
832: *
833: * @param source_size The size of the source to check.
834: *
835: * @param source_encoding The source encoding found.
836: *
837: * @param user_data User defined pointer
838: *
839: * @return
840: */
841: typedef int (*axlStreamContentCheck) (const char * source,
842: int source_size,
843: const char * source_encoding,
844: axlPointer user_data,
845: axlError ** error);
846:
847:
848: /**
849: * @brief Axl debug levels.
850: *
851: * While reporting log to the console, these levels are used to report
852: * the severity for such log.
853: */
854: typedef enum {
855: /**
856: * @brief Debug level. Only used to report common
857: * circumstances that represent the proper functionality.
858: */
859: AXL_LEVEL_DEBUG,
860: /**
861: * @brief Warning level. Only used to report that an internal
862: * issue have happend that could be interesting while
863: * reporting error, but it could also mean common situations.
864: */
865: AXL_LEVEL_WARNING,
866: /**
867: * @brief Critical level. Only used to report critical
868: * situations where some that have happened shouldn't.
869: *
870: * This level should only be used while reporting critical
871: * situations.
872: */
873: AXL_LEVEL_CRITICAL}
874: AxlDebugLevel;
875:
876: /**
877: * @brief Support macro to allocate memory using axl_calloc function,
878: * making a casting and using the sizeof keyword.
879: *
880: * @param type The type to allocate
881: * @param count How many items to allocate.
882: *
883: * @return A newly allocated pointer.
884: */
885: #define axl_new(type, count) (type *) axl_calloc (count, sizeof (type))
886:
887: /**
888: * @brief Allows to check a condition and return if it is not meet.
889: *
890: * @param expr The expresion to check.
891: */
892: #define axl_return_if_fail(expr) \
893: if (!(expr)) {__axl_log ("", AXL_LEVEL_CRITICAL, "Expresion '%s' have failed at %s (%s:%d)", #expr, __AXL_PRETTY_FUNCTION__, __AXL_FILE__, __AXL_LINE__); return;}
894:
895: /**
896: * @brief Allows to check a condition and return the given value if it
897: * is not meet.
898: *
899: * @param expr The expresion to check.
900: *
901: * @param val The value to return if the expression is not meet.
902: */
903: #define axl_return_val_if_fail(expr, val) \
904: if (!(expr)) { __axl_log ("", AXL_LEVEL_CRITICAL, "Expresion '%s' have failed, returning: %s at %s (%s:%d)", #expr, #val, __AXL_PRETTY_FUNCTION__, __AXL_FILE__, __AXL_LINE__); return val;}
905:
906:
907: /**
908: * @brief Consumes all spaces found and tabulars on the given stream
909: * until a different char is found.
910: *
911: * This internal function also consumes coments inside the xml read.
912: *
913: * @param stream The stream where the operation will be performed.
914: */
915: #define AXL_CONSUME_SPACES(stream) \
916: axl_stream_consume_white_spaces (stream)
917:
918: /**
919: * @internal
920: *
921: * @brief Allows to check if the provided string is empty either
922: * because it is NULL of because the string contains no data.
923: *
924: * @param str The string to check for emptyness.
925: *
926: * @return Returns axl_true if the string is empty and axl_false if
927: * not.
928: */
929: #define AXL_IS_STR_EMPTY(str) (((str == NULL) || strlen (str) == 0) ? axl_true : axl_false)
930:
931: /**
932: * @internal
933: *
934: * C++ support declarations borrowed from the libtool webpage. Thanks
935: * you guys for this information.
936: *
937: * BEGIN_C_DECLS should be used at the beginning of your declarations,
938: * so that C++ compilers don't mangle their names. Use END_C_DECLS at
939: * the end of C declarations.
940: */
941: #undef BEGIN_C_DECLS
942: #undef END_C_DECLS
943: #ifdef __cplusplus
944: # define BEGIN_C_DECLS extern "C" {
945: # define END_C_DECLS }
946: #else
947: # define BEGIN_C_DECLS /* empty */
948: # define END_C_DECLS /* empty */
949: #endif
950:
951: #define _memcmp(i,s1,s2,size)\
952: i = 0;\
953: while (s1 [i] != 0 && s2 [i] != 0) {\
954: if (s1 [i] != s2 [i])\
955: return axl_false;\
956: i++;\
957: if (i == size)\
958: return axl_true;\
959: }\
960: return axl_false
961:
962: /**
963: * @brief Allows to configure how is performed the iteration other the xml document.
964: *
965: * An xml document could be considered as a tree structure, where the
966: * root document node is the root of the tree. This enumerator allows
967: * to configure how is visited each node of the tree.
968: */
969: typedef enum {
970: /**
971: * @brief Makes a deep iteration, visiting first childs of a
972: * visited node instead of brother nodes at the same level.
973: */
974: DEEP_ITERATION,
975: /**
976: * @brief Makes a wide iteration, visiting first all nodes for
977: * a given level, after visiting nodes for the next level.
978: */
979: WIDE_ITERATION
980: } AxlIterationMode;
981:
982: /**
983: * \defgroup axl_handlers Axl Handlers: Handlers declarations used by Axl Library functions.
984: */
985:
986: /**
987: * \addtogroup axl_handlers
988: * @{
989: */
990:
991: /**
992: * @brief Axl iteration function definition.
993: *
994: * This handler definition is used by \ref axl_doc_iterate as the
995: * function definition that will be called for each node found in the
996: * document.
997: *
998: * The function provides a pointer to the node found, the first
999: * paramenter, and additionally, provides a pointer to the parent node
1000: * for the node found, the document where the node is found and an
1001: * optional user defined pointer provided at the function calling
1002: * (\ref axl_doc_iterate).
1003: *
1004: * The function returns a boolean value to signal the library to stop
1005: * iterating over the XML structure if \ref axl_false is returned. So, to
1006: * continue the iteration, you must always return \ref axl_true.
1007: *
1008: * @param node The node found inside the document.
1009: *
1010: * @param parent The parent node for the node found (first parameter).
1011: *
1012: * @param doc The document that contains the node found.
1013: *
1014: * @param was_removed If contains a reference to a boolean value that
1015: * helps the invoked funtion to notify the iteration system that the
1016: * node was removed from the tree, using \ref axl_node_remove or \ref
1017: * axl_node_replace. Iteration support inside axl library is built in
1018: * a way that allows the programmer to remove a node (including its
1019: * childs) without breaking the loop, however, you must use this
1020: * variable to notify that the node was removed, so the iteration
1021: * system won't iterate over its childs.
1022: *
1023: * @param ptr A user defined pointer that the user provided at \ref
1024: * axl_doc_iterate.
1025: *
1026: * @return The callback must return axl_false in the case the iteration
1027: * must be stopped. Otherwise, axl_true must be returned.
1028: */
1029: typedef axl_bool (*axlIterationFunc) (axlNode * node, axlNode * parent, axlDoc * doc, axl_bool * was_removed, axlPointer ptr);
1030:
1031: /**
1032: * @brief Axl iteration function definition (with two user defined
1033: * pointer support).
1034: *
1035: * This handler definition is used by \ref axl_doc_iterate_full as the
1036: * function definition that will be called for each node found in the
1037: * document.
1038: *
1039: * The function provides a pointer to the node found, the first
1040: * paramenter, and additionally, provides a pointer to the parent node
1041: * for the node found, the document where the node is found and an
1042: * optional user defined pointer provided at the function calling
1043: * (\ref axl_doc_iterate_full).
1044: *
1045: * The function returns a axl_boolean value to signal the library to stop
1046: * iterating over the XML structure if \ref axl_false is returned. So, to
1047: * continue the iteration, you must always return \ref axl_true.
1048: *
1049: * @param node The node found inside the document.
1050: *
1051: * @param parent The parent node for the node found (first parameter).
1052: *
1053: * @param doc The document that contains the node found.
1054: *
1055: * @param was_removed If contains a reference to a boolean value that
1056: * helps the invoked funtion to notify the iteration system that the
1057: * node was removed from the tree, using \ref axl_node_remove or \ref
1058: * axl_node_replace. Iteration support inside axl library is built in
1059: * a way that allows the programmer to remove a node (including its
1060: * childs) without breaking the loop, however, you must use this
1061: * variable to notify that the node was removed, so the iteration
1062: * system won't iterate over its childs.
1063: *
1064: * @param ptr A user defined pointer that the user provided at \ref
1065: * axl_doc_iterate_full.
1066: *
1067: * @param ptr2 Second user defined pointer that the user provided at
1068: * \ref axl_doc_iterate_full.
1069: *
1070: * @return The callback must return axl_false in the case the iteration
1071: * must be stopped. Otherwise, axl_true must be returned.
1072: */
1073: typedef axl_bool (*axlIterationFunc2) (axlNode * node, axlNode * parent, axlDoc * doc, axl_bool * was_removed, axlPointer ptr, axlPointer ptr2);
1074:
1075: /**
1076: * @brief Defines a signature for a set of function that are used to
1077: * duplicate the content provided at the first parameter, returning a
1078: * copy.
1079: *
1080: * This handler definition is used by:
1081: *
1082: * - \ref axl_list_copy
1083: *
1084: * @param ptr The data to duplicate.
1085: *
1086: * @return A newly allocated data duplicated.
1087: */
1088: typedef axlPointer (*axlDuplicateFunc) (axlPointer ptr);
1089:
1090: /**
1091: * @brief Handler used by the \ref axl_list_module "axl list module"
1092: * to perform linear and efficient lookups.
1093: *
1094: * @param ptr A pointer to the object stored inside the list and to be
1095: * checked if it is the one looked up.
1096: *
1097: * @param data A pointer to a user defined data that is received at
1098: * the lookup function and passed to this handler.
1099: *
1100: * @return The function should return axl_true (found). Otherwise, axl_false
1101: * must be returned to keep on searching.
1102: */
1103: typedef axl_bool (*axlLookupFunc) (axlPointer ptr, axlPointer data);
1104:
1105: /**
1106: * @brief Hashing function used by the axl hash module to implement
1107: * translation from an user defined pointer into a number that should
1108: * be as much unique as possible.
1109: *
1110: * @param key User defined data that represents the key for a data to
1111: * be stored into the hash. The value provided here usually is an
1112: * string but it could be any other data used as key.
1113: *
1114: * @return The function must return a positive value that will be used
1115: * to index the content into the hash table. It doesn't matter if the
1116: * number is greater than the table size. A modulo operation is
1117: * applied to the result.
1118: */
1119: typedef unsigned int (*axlHashFunc) (axlPointer key);
1120:
1121: /**
1122: * @brief Foreach function signature used to represent the set of
1123: * functions used at \ref axl_hash_foreach.
1124: *
1125: * The function receives the item found (key and data values) as well
1126: * as a user defined pointer also defined at \ref
1127: * axl_hash_foreach. The function must return \ref axl_true (<i>"item
1128: * found"</i>) to make the search to stop. In the case a full
1129: * iteration over all items inside the hash is required, the function
1130: * must always return \ref axl_false.
1131: *
1132: * @param key The key for the item stored.
1133: * @param data The data associated to the key found
1134: * @param user_data User defined data that was provided to the axl_hash_foreach function.
1135: *
1136: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1137: * to make the process to continue.
1138: */
1139: typedef axl_bool (* axlHashForeachFunc) (axlPointer key, axlPointer data, axlPointer user_data);
1140:
1141: /**
1142: * @brief Foreach function signature used to represent the set of
1143: * functions used at \ref axl_hash_foreach2.
1144: *
1145: * The function receives the item found (key and data values) as well
1146: * as two user defined pointers also defined at \ref
1147: * axl_hash_foreach2. The function must return \ref axl_true (<i>"item
1148: * found"</i>) to make the search to stop. In the case a full
1149: * iteration over all items inside the hash is required, the function
1150: * must always return \ref axl_false.
1151: *
1152: * @param key The key for the item stored.
1153: * @param data The data associated to the key found
1154: * @param user_data User defined data that was provided to the axl_hash_foreach2 function.
1155: * @param user_data2 Second User defined data that was provided to the axl_hash_foreach2 function.
1156: *
1157: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1158: * to make the process to continue.
1159: */
1160: typedef axl_bool (* axlHashForeachFunc2) (axlPointer key, axlPointer data, axlPointer user_data, axlPointer user_data2);
1161:
1162: /**
1163: * @brief Foreach function signature used to represent the set of
1164: * functions used at \ref axl_hash_foreach3.
1165: *
1166: * The function receives the item found (key and data values) as well
1167: * as tree user defined pointers also defined at \ref
1168: * axl_hash_foreach3. The function must return \ref axl_true (<i>"item
1169: * found"</i>) to make the search to stop. In the case a full
1170: * iteration over all items inside the hash is required, the function
1171: * must always return \ref axl_false.
1172: *
1173: * @param key The key for the item stored.
1174: *
1175: * @param data The data associated to the key found
1176: *
1177: * @param user_data User defined data that was provided to the
1178: * axl_hash_foreach3 function.
1179: *
1180: * @param user_data2 Second User defined data that was provided to the
1181: * axl_hash_foreach3 function.
1182: *
1183: * @param user_data3 Third User defined data that was provided to the
1184: * axl_hash_foreach3 function.
1185: *
1186: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1187: * to make the process to continue.
1188: */
1189: typedef axl_bool (* axlHashForeachFunc3) (axlPointer key, axlPointer data, axlPointer user_data, axlPointer user_data2, axlPointer user_data3);
1190:
1191: /**
1192: * @brief Foreach function signature used to represent the set of
1193: * functions used at \ref axl_hash_foreach4.
1194: *
1195: * The function receives the item found (key and data values) as well
1196: * as tree user defined pointers also defined at \ref
1197: * axl_hash_foreach4. The function must return \ref axl_true (<i>"item
1198: * found"</i>) to make the search to stop. In the case a full
1199: * iteration over all items inside the hash is required, the function
1200: * must always return \ref axl_false.
1201: *
1202: * @param key The key for the item stored.
1203: *
1204: * @param data The data associated to the key found
1205: *
1206: * @param user_data User defined data that was provided to the
1207: * axl_hash_foreach4 function.
1208: *
1209: * @param user_data2 Second User defined data that was provided to the
1210: * axl_hash_foreach4 function.
1211: *
1212: * @param user_data3 Third User defined data that was provided to the
1213: * axl_hash_foreach4 function.
1214: *
1215: * @param user_data4 Forth User defined data that was provided to the
1216: * axl_hash_foreach4 function.
1217: *
1218: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1219: * to make the process to continue.
1220: */
1221: typedef axl_bool (* axlHashForeachFunc4) (axlPointer key, axlPointer data, axlPointer user_data, axlPointer user_data2, axlPointer user_data3, axlPointer user_data4);
1222:
1223: /**
1224: * @brief Function handler definition for to allowing copying items at
1225: * the hash by \ref axl_hash_copy function.
1226: *
1227: * The function receive both pointers the key and the data value but,
1228: * only one of them must be copied. This is done to provide more
1229: * control at the copy process, but only the required value must be
1230: * returned. There is no indication to about which pointer must be
1231: * returned, so, don't use the same function to copy both pointers.
1232: *
1233: * The function also receive pointers to the current function
1234: * deallocation associated to the key and value being copied. This
1235: * could also work as information to know if the data must be
1236: * replicated or not. Having the destroy function defined for the item
1237: * is a clue to return an allocated item.
1238: *
1239: * @param key The key to be copied if the function was provided to copy the key.
1240: *
1241: * @param key_destroy The key destroy function associated to the value
1242: * being copied.
1243: *
1244: * @param data The data to be copied if the function was provided to copy the data.
1245: *
1246: * @param data_destroy The data destroy function associated to the
1247: * data value being copied.
1248: *
1249: * @return A newly allocated reference representing the copy.
1250: */
1251: typedef axlPointer (*axlHashItemCopy) (axlPointer key, axlDestroyFunc key_destroy, axlPointer data, axlDestroyFunc data_destroy);
1252:
1253: /**
1254: * @brief Foreach function handler used at \ref axl_stack_foreach
1255: * function to iterate all elements inside the stack, from the head to
1256: * the tail.
1257: *
1258: * The function receives two user defined pointers that are defined at
1259: * the \ref axl_stack_foreach function.
1260: *
1261: * @param stack_data A reference to the stack data stored.
1262: *
1263: * @param user_data A reference to a user defined pointer passed to
1264: * \ref axl_stack_foreach.
1265: *
1266: * @param user_data2 A second reference to a user defined pointer
1267: * passed to \ref axl_stack_foreach.
1268: *
1269: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1270: * to make the process to continue.
1271: */
1272: typedef axl_bool (* axlStackForeach2) (axlPointer stack_data, axlPointer user_data, axlPointer user_data2);
1273:
1274: /**
1275: * @brief Foreach function handler used at \ref axl_stack_foreach3
1276: * function to iterate all elements inside the stack, from the head to
1277: * the tail.
1278: *
1279: * The function receives three user defined pointers that are defined
1280: * at the \ref axl_stack_foreach3 function.
1281: *
1282: * @param stack_data A reference to the stack data stored.
1283: *
1284: * @param user_data A reference to a user defined pointer passed to
1285: * \ref axl_stack_foreach3.
1286: *
1287: * @param user_data2 A second reference to a user defined pointer
1288: * passed to \ref axl_stack_foreach3.
1289: *
1290: * @param user_data3 Third reference to a user defined pointer passed
1291: * to \ref axl_stack_foreach3.
1292: *
1293: * @return \ref axl_true to make the foreach process to stop. \ref axl_false
1294: * to make the process to continue.
1295: */
1296: typedef axl_bool (* axlStackForeach3) (axlPointer stack_data, axlPointer user_data, axlPointer user_data2, axlPointer user_data3);
1297:
1298: /**
1299: * @brief Foreach function used by \ref axl_node_attr_foreach function.
1300: *
1301: * @param key The attribute name.
1302: *
1303: * @param value The attribute value.
1304: *
1305: * @param data User defined pointer provided at \ref
1306: * axl_node_attr_foreach.
1307: *
1308: * @param data2 Second user defined data provided at \ref
1309: * axl_node_attr_foreach.
1310: *
1311: * @return The foreach function can stop the process at a particular
1312: * attribute by returning \ref axl_true ("item found"). To iterate all
1313: * attributes return \ref axl_false.
1314: */
1315: typedef axl_bool (* axlNodeAttrForeachFunc) (const char * key, const char * value, axlPointer data, axlPointer data2);
1316:
1317: /**
1318: * @brief Entity resolver function used by the library to translate
1319: * entity references into the replacement text. This is normally used
1320: * by the library itself, not by the application programmer.
1321: *
1322: * This handler is currently used at \ref axl_dtd_check_entity_ref_and_expand
1323: *
1324: * @param entityName The entity name that is being requested to be
1325: * resolved.
1326: *
1327: * @return The user defined data provided at \ref
1328: * axl_dtd_check_entity_ref_and_expand, which is passed to the
1329: * resolver function once it is executed.
1330: */
1331: typedef const char * (* axlDtdEntityResolver) (const char * entityName, axlPointer data);
1332:
1333: /**
1334: * @brief Handler definition for the set of functions that allows to
1335: * detect codification found at the document being opened by the
1336: * \ref axlStream reference provided.
1337: *
1338: * @param stream The stream where the detection will be implemented.
1339: *
1340: * @param detected A reference to the codification detected or NULL if
1341: * nothing clearly detected. For example (ascii, iso-8859) but still
1342: * not enough information. Handler implementator must configure an
1343: * static string for this value.
1344: *
1345: * @param user_data A reference to user-defined data. This value was
1346: * configured at \ref axl_doc_set_detect_codification_func.
1347: *
1348: * @return axl_true if the detection was implemented properly, otherse
1349: * axl_false is returned. The handler could return axl_true and no
1350: * codification be clearly detected.
1351: */
1352: typedef axl_bool (* axlDocDetectCodification) (axlStream * stream, const char ** detected, axlPointer user_data, axlError ** error);
1353:
1354: /**
1355: * @brief Handler definition for the set of functions that allows to
1356: * finally configure codification to be used for the provided stream.
1357: *
1358: * @param stream A reference to the stream to be configured.
1359: *
1360: * @param encoding A reference to the encoding detected. It could be
1361: * NULL.
1362: *
1363: * @param detected_encoding A reference to the detected encoding (a
1364: * value provided by the \ref axlDocDetectCodification if defined).
1365: *
1366: * @param user_data A reference to user defined data.
1367: *
1368: * @param error An optional error that will be filled in the case an
1369: * error is found.
1370: *
1371: * @return axl_true if the configuration operation was done, otherwise
1372: * axl_false is returned.
1373: */
1374: typedef axl_bool (* axlDocConfigureCodification) (axlStream * stream, const char * encoding, const char * detected_encoding, axlPointer user_data, axlError ** error);
1375:
1376: BEGIN_C_DECLS
1377:
1378: axlPointer axl_calloc (size_t count, size_t size);
1379:
1380: axlPointer axl_realloc (axlPointer ref, size_t size);
1381:
1382: void axl_free (axlPointer ref);
1383:
1384: END_C_DECLS
1385:
1386: /* @} */
1387: #endif
1388:
1389: /* @} */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to axl_decl.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / gpl / axl / src