2 * LibAxl: Another XML library
3 * Copyright (C) 2006 Advanced Software Production Line, S.L.
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.
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.
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
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
27 * For commercial support on build XML enabled solutions contact us:
30 * Advanced Software Production Line, S.L.
31 * C/ Dr. Michavila NÂș 14
32 * Coslada 28820 Madrid
36 * info@aspl.es - http://fact.aspl.es
38 #ifndef __AXL_DECL_H__
39 #define __AXL_DECL_H__
41 /* include platform specific configuration */
42 #include <axl_config.h>
44 /* include this at this place to load GNU extensions */
49 # define __AXL_PRETTY_FUNCTION__ __PRETTY_FUNCTION__
50 # define __AXL_LINE__ __LINE__
51 # define __AXL_FILE__ __FILE__
53 /* non gnu compiler */
54 #define __AXL_PRETTY_FUNCTION__ ""
55 #define __AXL_LINE__ ""
56 #define __AXL_FILE__ ""
64 /* only include unistd.h if unix platform is found or gnu gcc compiler
66 #if defined(__GNUC__) || defined(AXL_OS_UNIX)
70 #include <sys/types.h>
76 * \defgroup axl_decl_module Axl Declarations: Common Axl declarations, Types, macros, and support functions.
80 * \addtogroup axl_decl_module
86 * @brief Axl XML document type definition.
88 * This type represents a reference to an entiry XML document loaded
89 * into memory. Functions to be used to load XML document could be the
92 * - \ref axl_doc_parse
93 * - \ref axl_doc_parse_strings
94 * - \ref axl_doc_parse_from_file
96 * You can also create an empty document by using \ref axl_doc_create
97 * and fill the initial root node using the \ref axl_doc_set_root
98 * function. Once the document have an initial root node, you can add
99 * more nodes as childs to the root element previously added.
101 * Check the \ref axl_doc_module "axlDoc API reference" to get more
104 typedef struct _axlDoc axlDoc
;
107 * @brief An abstraction that allows to hold an xml node or any other
108 * content that can be found inside an xml node: comments, content,
109 * CDATA-content, PI, entity references.
111 * This type is mainly used inside the MIXED API, which allows to get
112 * access to every particular item found inside a particular node
113 * (\ref axlNode). Every item has a type (\ref AxlItemType) and a
114 * content that is being encapsulated and usually accessed by \ref
117 * Check the \ref axl_item_module "Axl Item interface" for more information.
119 typedef struct _axlItem axlItem
;
122 * @internal Factory allocation type.
124 typedef struct _axlFactory axlFactory
;
127 * @internal String factory allocation type.
129 typedef struct _axlStrFactory axlStrFactory
;
132 * @brief Axl XML node type definition.
134 * This type reference represents a single XML node. To create a xml node you can use:
136 * - \ref axl_node_create
138 * To get the node name or if the node have childs or if it is empty,
139 * you can use the following functions:
141 * - \ref axl_node_get_name
142 * - \ref axl_node_is_empty
143 * - \ref axl_node_have_childs
145 * To get the \ref axlNode content you can use the following
148 * - \ref axl_node_get_content
149 * - \ref axl_node_get_content_copy
150 * - \ref axl_node_get_content_trans
152 * For attributes manipulation, you can using the following functions
153 * to set them and retrieve them:
155 * - \ref axl_node_get_attribute_value
156 * - \ref axl_node_get_attribute_value_copy
157 * - \ref axl_node_get_attribute_value_trans
159 * To retrive childs number or childs inside the given \ref axlNode
160 * you can use the following function:
162 * - \ref axl_node_get_child_num
163 * - \ref axl_node_get_child_nth
165 * You can also use the following functions to get the parent node for
166 * a provided xml node child and the next xml node found at the same
167 * level, for a provided xml node reference.
169 * - \ref axl_node_get_parent
170 * - \ref axl_node_get_next
172 * Check the axlNode \ref axl_node_module "API for more information".
174 typedef struct _axlNode axlNode
;
177 * @brief Public cursor type used to iterate over attributes installed
178 * on a particular node (see \ref axl_node_attr_cursor_new to get examples and more information).
180 typedef struct _axlAttrCursor axlAttrCursor
;
183 * @brief Axl DTD entity representation.
185 typedef struct _axlDtd axlDtd
;
188 * @brief Axl DTD entity element declaration.
190 typedef struct _axlDtdElement axlDtdElement
;
193 * @brief Axl DTD item list element declaration.
195 typedef struct _axlDtdElementList axlDtdElementList
;
198 * @brief Axl DTD item list element declaration.
200 typedef struct _axlDtdElementListNode axlDtdElementListNode
;
204 * @brief Axl DTD attribute declaration (<!ATTLIST..>)
206 typedef struct _axlDtdAttribute axlDtdAttribute
;
209 * @brief Axl DTD attribute list decleration inside \ref axlDtdAttribute.
211 typedef struct _axlDtdAttributeDecl axlDtdAttributeDecl
;
214 * @brief Axl DTD entity declaration (<!ENTITY support>)
216 typedef struct _axlDtdEntity axlDtdEntity
;
219 * @brief Support type definition for \ref axlDtdEntity, which holds
220 * information about external resource pointed by the \ref
221 * axlDtdEntity instance.
223 typedef struct _axlDtdEntityExternalData axlDtdEntityExternalData
;
226 * @brief Declares the entity type for a provided \ref axlDtdEntity.
230 * @brief The \ref axlDtdEntity definition represents a
231 * general entity definition (that comes without % before the
236 * @brief The \ref axlDtdEntity definition represents a
237 * parameter entity definition (that comes with a % before the
238 * entity name, making this entity definition to be only
239 * usable from a DTD definition).
245 * @brief Attribute type declaration (the type of the attribute
246 * constrain). This type is used to identifier the attribute contains
247 * applied to the node selected.
251 * @brief The attribute type is defined but its content is
252 * CDATA (any string value is allowed), activated when used 'CDATA'.
256 * @brief Especific token declaration that implicitly contrain
257 * the node attribute value, activated when used 'ID'.
261 * @brief Especific token declaration that implicitly contrain
262 * the node attribute value, activated when used 'IDREF'.
264 TOKENIZED_TYPE_IDREF
,
266 * @brief Especific token declaration that implicitly contrain
267 * the node attribute value, activated when used 'IDREFS'.
269 TOKENIZED_TYPE_IDREFS
,
271 * @brief Especific token declaration that implicitly contrain
272 * the node attribute value, activated when used 'ENTITY'.
274 TOKENIZED_TYPE_ENTITY
,
276 * @brief Especific token declaration that implicitly contrain
277 * the node attribute value, activated when used 'ENTITIES'.
279 TOKENIZED_TYPE_ENTITIES
,
281 * @brief Especific token declaration that implicitly contrain
282 * the node attribute value, activated when used 'NMTOKEN'.
284 TOKENIZED_TYPE_NMTOKEN
,
286 * @brief Especific token declaration that implicitly contrain
287 * the node attribute value, activated when used 'NMTOKENS'.
289 TOKENIZED_TYPE_NMTOKENS
,
291 * @brief The attribute type declaration is constrained to a
292 * set of values. This values are considered as an
297 * @brief Attribute type not supported yet (although defined).
300 } AxlDtdAttributeType
;
303 * @brief Defines the DTD attribute declaration default state.
307 * @brief The attribute is required as especified by the
308 * attribute declaration.
312 * @brief The attribute is not requried, however, if it
313 * appears it must follow the attribute type declaration.
317 * @brief The attribute must appear and have the value
318 * provided as the default.
321 }AxlDtdAttributeDefaults
;
325 * @brief The type of the DTD sequences stored by the \ref
332 * Internal value used by the library to support mixing
333 * content seperator types detection.
337 * @brief Represents that the item selection is configured to
338 * be a choice (a selection allowed from any item inside the
343 * @brief Represents that the item selection is configured to
344 * select each item in the order they apper.
350 * @brief An indication of the element type stored on the provided
351 * \ref axlDtdElementListNode reference.
353 * An \ref axlDtdElementListNode reference could contain a single
354 * reference to a content particule name, that is the XML node name to
355 * be allowed to be used at the provided position or a reference to an
356 * \ref axlDtdElementList which contains a nested list containing more
357 * content particules.
363 * Represents the not defined value.
365 AXL_ELEMENT_NOT_DEFINED
= 1,
367 * @brief The reference contains an \ref axlDtdElementList.
369 AXL_ELEMENT_LIST
= 2,
371 * @brief The reference contains a reference to a leaf node, a
378 * @brief DTD element type enumeration.
380 * While using DTD declaration, <b>ELEMENT</b> used to define how your
381 * xml document is structured and constrained, are clasified using the
384 * This type specification must not be confused with \ref NodeType,
385 * which is the configuration for an element, inside the content DTD
386 * element specification.
392 * Internal value to avoid confusing EMPTY declaration with a
395 ELEMENT_TYPE_UNKNOWN
= 0,
397 * @brief Used to represent that the element declaration have
398 * no content inside it. This includes not only PCDATA (data
399 * stored between xml tags) but also any child declaration.
401 ELEMENT_TYPE_EMPTY
= 1,
403 * @brief Used to represent that the element used in your xml
404 * document could contain anthing without any contraint.
406 ELEMENT_TYPE_ANY
= 2,
408 * @brief Used to represent that the following xml node have
409 * content not only defined by a set of allowed xml nodes but
412 ELEMENT_TYPE_MIXED
= 3,
414 * @brief Used to represent that the folowing xml node have
415 * only xml nodes as content, in the form of xml childs,
416 * without inlucing PCDATA.
418 ELEMENT_TYPE_CHILDREN
= 4,
420 * @brief Used to represent that the DTD element specification
421 * contains only PCDATA. No child nodes or childs nodes mixed
424 ELEMENT_TYPE_PCDATA
= 5
428 * @brief Current configuration for elements definied inside a ELEMENT
435 * Internal representation to identify wrong repetition
436 * especification values.
438 DTD_TIMES_UNKNOWN
= 0,
440 * Current configuration for DTD element content specification
441 * signals that it must appear one and only one times.
443 ONE_AND_ONLY_ONE
= 1,
445 * Current configuration for DTD element content specification
446 * signals that it could appear zero or one time.
450 * Current configuration for DTD element content specification
455 * Current configuration for DTD element content specification
456 * signals that it must appear one up to many times.
462 * @brief Item types that can hold an xml node (\ref axlNode).
464 * \ref AxlItemType is used to notify the type for a particular item
465 * (\ref axlItem) that is stored as a child on a particular \ref
468 * This is mainly used inside the MIXED API, which is the way that Axl
469 * exposes the content of a xml node that is expected to contain more
470 * nodes mixed with more content.
472 * Each type represents a particular basic unit that could be found as
473 * a child item inside an xml node.
477 * @brief The \ref axlItem is encapsulating another item
478 * node. Calling to \ref axl_item_get_data will return a
479 * reference to an \ref axlNode.
484 * @brief The \ref axlItem is encapsulating an node
485 * content. Calling to the convenience function \ref
486 * axl_item_get_content to get the content and the size that
487 * is stored in the \ref axlItem with this type.
489 ITEM_CONTENT
= 1 << 1,
491 * @brief The \ref axlItem is encapsulating an application
492 * process instruction. Calling to \ref axl_item_get_data will
493 * return a reference to a \ref axlPI.
499 * @brief The \ref axlItem is encapsulating an xml
502 * XML comments inside Axl are handled xml node content. The
503 * comment that is returned from the function has the initial
504 * '<!--' and the ending '-->' elements stripped from its
507 * You must use the convenience function \ref
508 * axl_item_get_content to get the comment content and the
509 * size that is stored on the \ref axlItem.
511 ITEM_COMMENT
= 1 << 3,
513 * @brief The \ref axlItem is encapsulating an xml entity
514 * reference that wasn't resolved yet.
516 * Not implemented yet.
520 * @brief The \ref axlItem is encapsulating an xml content
521 * that was enclosed using the <![CDATA[]]> construction. This
522 * child item works the same as \ref ITEM_CONTENT but, adding
523 * the CDATA semantic and the fact that the content wasn't
524 * parsed by the Axl XML engine.
526 * You must use the convenience function \ref
527 * axl_item_get_content to get the CDATA content and the size
528 * that is stored on the \ref axlItem.
534 * @internal Item type which allows to signal that the item
535 * comes from an item factory and shouldn't be deallocated in
538 ITEM_FROM_FACTORY
= 1 << 7,
540 * @internal Item type which allows to signal that the content
541 * item comes from an item factory and shouldn't be
542 * deallocated in the usual manner.
544 ITEM_CONTENT_FROM_FACTORY
= 1 << 8
548 * @brief Simple alias for the AxlDtdElementType.
550 typedef AxlDtdElementType ElementType
;
553 * @brief Axl DTD entity attribute element declaration.
555 typedef struct _axtDtdAttr axlDtdAttr
;
558 * @brief Axl Processing instruction type definition.
560 typedef struct _axlPI axlPI
;
563 * @brief Axl error reporting variable.
565 * All Axl interface report errors found, with a textual diagnostic,
566 * to the application level using this variable. You have to know that
567 * it is also optional, so every function that receives an \ref
568 * axlError, will properly handle a NULL reference received.
570 * Once an error was detected, for that condition you must check the
571 * documentation provided for the function that is failing, you can
572 * get the error code and the error textual diagnostic by using the
573 * following functions:
575 * - \ref axl_error_get_code
576 * - \ref axl_error_get
578 * If an error is not detected, there is no especial operation to be
579 * done once returned the function that has received the \ref axlError
580 * error reference. However, if an error is detected, the reference
581 * must be deallocated by using the following function:
583 * - \ref axl_error_free
585 * Here is an example:
587 * // declare the axlError reference
590 * // parse the document, giving a reference to the axlError
591 * // NOTE: you can safely provide a NULL reference.
592 * doc = axl_doc_parse_from_file ("test.xml", &error);
594 * printf ("Parse error: code=%d, message=%s\n",
595 * axl_error_get_code (error), axl_error_get (error));
596 * axl_error_free (error);
600 * // beyond this point, it is not required to do
601 * // any especial task with the axlError reference
604 * To get more information about the \ref axlError check its \ref axl_error_module "API documentation".
606 typedef struct _axlError axlError
;
609 * @brief Axl Stream representation (an abstraction API to manage
610 * source of data with convenience functions).
612 typedef struct _axlStream axlStream
;
615 * @brief (DEPRECATED use \ref true) Type definition to represent a
616 * boolean true value, that is equal to 1.
621 * @brief (DEPRECATED use \ref false) Type definition to represent a
622 * boolean false value, that is equal to 0.
624 #define AXL_FALSE (0)
627 * @brief Alias declaration to bind the <i>int</i> to the <b>boolean</b>
628 * concept (TRUE / FALSE states) (DEPRECATED).
630 * This is mainly used to emphasize that some integer values that
631 * returns some function must be considered to be \ref true or \ref
632 * false, that represents the boolean TRUE and FALSE values.
634 * This allows to perform boolean comparations using structure
635 * controls like if, while, but also making a differenciation about
636 * the boolean values and integer values.
638 * You are also allowed to use <b>bool</b> as boolean type definition.
640 typedef int aboolean
;
645 * Internal definition to retain compatibility with programs that
646 * define the bool value but the compiler doesn't provide it.
652 * @brief Common definition to have false value (which is defined to 0
657 * @brief Common definition to have true value (which is defined to 1
661 #endif /* __cplusplus */
664 * @brief Pointer to any structure definition. It should be required
665 * to use this definition, however, some platforms doesn't support the
666 * <b>void *</b> making it necessary to use the <b>char *</b>
667 * definition as a general way to represent references.
669 typedef void * axlPointer
;
672 * @brief \ref axlList definition, a list implementation.
673 * See \ref axl_list_new for more information about using this type.
675 typedef struct _axlList axlList
;
678 * @brief \ref axlListCursor definition, a iterator type used to
679 * traverse an axlList in a efficient way. See \ref axl_list_cursor_get.
681 typedef struct _axlListCursor axlListCursor
;
684 * @brief \ref axlStack definitinon, a stack implementation on top of \ref
686 * See \ref axl_stack_new for more information about using this type.
688 typedef struct _axlStack axlStack
;
691 * @brief \ref axlHash definition, a hash table to store key indexed
693 * See \ref axl_hash_new for more information about using this type.
695 typedef struct _axlHash axlHash
;
698 * @brief \ref axlHashCursor definition, a support type that is used
699 * to iterate a hash in a linear mode, without calling to \ref
700 * axl_hash_foreach family functions (see \ref axl_hash_cursor_new).
702 typedef struct _axlHashCursor axlHashCursor
;
705 * @brief Handler definition used to compare two elements.
707 * In the case they are equal, 0 is returned. In the case a should be
708 * before b the -1 is returned. In the case a should be after b then 1
709 * should be returned. A properly configured handler should help
710 * collections and other function to order elements.
712 * @param a The element to compare
713 * @param b The other element to compare
715 * @return A value selected from {-1,0,1} according to previous
718 typedef int (*axlEqualFunc
) (axlPointer a
, axlPointer b
);
721 * @brief Handler definition which represent deallocation functions.
723 * @param ptr The pointer to the memory to be released.
725 typedef void (*axlDestroyFunc
) (axlPointer ptr
);
728 * @brief Handler used to represent the set of functions that could be
729 * used to configure the axl stream allocation method. See \ref
730 * axl_stream_set_buffer_alloc.
732 * @param size The amount of memory to be allocated (memory requested by the axl stream).
734 * @param data User defined pointer configured at \ref axl_stream_set_buffer_alloc.
736 * @return The handler must return newly allocated memory to hold <b>size</b>
739 typedef char * (*axlStreamAlloc
) (int size
, axlPointer data
);
742 * @brief Axl debug levels.
744 * While reporting log to the console, these levels are used to report
745 * the severity for such log.
749 * @brief Debug level. Only used to report common
750 * circumstances that represent the proper functionality.
754 * @brief Warning level. Only used to report that an internal
755 * issue have happend that could be interesting while
756 * reporting error, but it could also mean common situations.
760 * @brief Critical level. Only used to report critical
761 * situations where some that have happened shouldn't.
763 * This level should only be used while reporting critical
770 * @brief Support macro to allocate memory using the calloc function,
771 * making a casting and using the sizeof keyword.
773 * @param type The type to allocate
774 * @param count How many items to allocate.
776 * @return A newly allocated pointer.
778 #define axl_new(type, count) (type *) calloc (count, sizeof (type))
781 * @brief Free the provided pointer that was allocated using \ref
784 * @param ref The reference to deallocate.
786 void axl_free(axlPointer ref
);
789 * @brief Allows to check a condition and return if it is not meet.
791 * @param expr The expresion to check.
793 #define axl_return_if_fail(expr) \
794 if (!(expr)) {__axl_log ("", AXL_LEVEL_CRITICAL, "Expresion '%s' have failed at %s (%s:%d)", #expr, __AXL_PRETTY_FUNCTION__, __AXL_FILE__, __AXL_LINE__); return;}
797 * @brief Allows to check a condition and return the given value if it
800 * @param expr The expresion to check.
802 * @param val The value to return if the expression is not meet.
804 #define axl_return_val_if_fail(expr, val) \
805 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;}
809 * @brief Consumes all spaces found and tabulars on the given stream
810 * until a different char is found.
812 * This internal function also consumes coments inside the xml read.
814 * @param stream The stream where the operation will be performed.
816 #define AXL_CONSUME_SPACES(stream) \
817 axl_stream_consume_white_spaces (stream)
822 * @brief Allows to check if the provided string is empty either
823 * because it is NULL of because the string contains no data.
825 * @param str The string to check for emptyness.
827 * @return Returns true if the string is empty and false if
830 #define AXL_IS_STR_EMPTY(str) (((str == NULL) || strlen (str) == 0) ? true : false)
835 * C++ support declarations borrowed from the libtool webpage. Thanks
836 * you guys for this information.
838 * BEGIN_C_DECLS should be used at the beginning of your declarations,
839 * so that C++ compilers don't mangle their names. Use END_C_DECLS at
840 * the end of C declarations.
845 # define BEGIN_C_DECLS extern "C" {
846 # define END_C_DECLS }
848 # define BEGIN_C_DECLS /* empty */
849 # define END_C_DECLS /* empty */
852 #define _memcmp(i,s1,s2,size)\
854 while (s1 [i] != 0 && s2 [i] != 0) {\
855 if (s1 [i] != s2 [i])\
864 * @brief Allows to configure how is performed the iteration other the xml document.
866 * An xml document could be considered as a tree structure, where the
867 * root document node is the root of the tree. This enumerator allows
868 * to configure how is visited each node of the tree.
872 * @brief Makes a deep iteration, visiting first childs of a
873 * visited node instead of brother nodes at the same level.
877 * @brief Makes a wide iteration, visiting first all nodes for
878 * a given level, after visiting nodes for the next level.
884 * \defgroup axl_handlers Axl Handlers: Handlers declarations used by Axl Library functions.
888 * \addtogroup axl_handlers
893 * @brief Axl iteration function definition.
895 * This handler definition is used by \ref axl_doc_iterate as the
896 * function definition that will be called for each node found in the
899 * The function provides a pointer to the node found, the first
900 * paramenter, and additionally, provides a pointer to the parent node
901 * for the node found, the document where the node is found and an
902 * optional user defined pointer provided at the function calling
903 * (\ref axl_doc_iterate).
905 * The function returns a boolean value to signal the library to stop
906 * iterating over the XML structure if \ref false is returned. So, to
907 * continue the iteration, you must always return \ref true.
909 * @param node The node found inside the document.
911 * @param parent The parent node for the node found (first parameter).
913 * @param doc The document that contains the node found.
915 * @param was_removed If contains a reference to a boolean value that
916 * helps the invoked funtion to notify the iteration system that the
917 * node was removed from the tree, using \ref axl_node_remove or \ref
918 * axl_node_replace. Iteration support inside axl library is built in
919 * a way that allows the programmer to remove a node (including its
920 * childs) without breaking the loop, however, you must use this
921 * variable to notify that the node was removed, so the iteration
922 * system won't iterate over its childs.
924 * @param ptr A user defined pointer that the user provided at \ref
927 * @return The callback must return false in the case the iteration
928 * must be stopped. Otherwise, true must be returned.
930 typedef bool (*axlIterationFunc
) (axlNode
* node
, axlNode
* parent
, axlDoc
* doc
, bool * was_removed
, axlPointer ptr
);
933 * @brief Axl iteration function definition (with two user defined
936 * This handler definition is used by \ref axl_doc_iterate_full as the
937 * function definition that will be called for each node found in the
940 * The function provides a pointer to the node found, the first
941 * paramenter, and additionally, provides a pointer to the parent node
942 * for the node found, the document where the node is found and an
943 * optional user defined pointer provided at the function calling
944 * (\ref axl_doc_iterate_full).
946 * The function returns a boolean value to signal the library to stop
947 * iterating over the XML structure if \ref false is returned. So, to
948 * continue the iteration, you must always return \ref true.
950 * @param node The node found inside the document.
952 * @param parent The parent node for the node found (first parameter).
954 * @param doc The document that contains the node found.
956 * @param was_removed If contains a reference to a boolean value that
957 * helps the invoked funtion to notify the iteration system that the
958 * node was removed from the tree, using \ref axl_node_remove or \ref
959 * axl_node_replace. Iteration support inside axl library is built in
960 * a way that allows the programmer to remove a node (including its
961 * childs) without breaking the loop, however, you must use this
962 * variable to notify that the node was removed, so the iteration
963 * system won't iterate over its childs.
965 * @param ptr A user defined pointer that the user provided at \ref
966 * axl_doc_iterate_full.
968 * @param ptr2 Second user defined pointer that the user provided at
969 * \ref axl_doc_iterate_full.
971 * @return The callback must return false in the case the iteration
972 * must be stopped. Otherwise, true must be returned.
974 typedef bool (*axlIterationFunc2
) (axlNode
* node
, axlNode
* parent
, axlDoc
* doc
, bool * was_removed
, axlPointer ptr
, axlPointer ptr2
);
977 * @brief Defines a signature for a set of function that are used to
978 * duplicate the content provided at the first parameter, returning a
981 * This handler definition is used by:
983 * - \ref axl_list_copy
985 * @param ptr The data to duplicate.
987 * @return A newly allocated data duplicated.
989 typedef axlPointer (*axlDuplicateFunc
) (axlPointer ptr
);
992 * @brief Handler used by the \ref axl_list_module "axl list module"
993 * to perform linear and efficient lookups.
995 * @param ptr A pointer to the object stored inside the list and to be
996 * checked if it is the one looked up.
998 * @param data A pointer to a user defined data that is received at
999 * the lookup function and passed to this handler.
1001 * @return The function should return true (found). Otherwise, false
1002 * must be returned to keep on searching.
1004 typedef bool (*axlLookupFunc
) (axlPointer ptr
, axlPointer data
);
1007 * @brief Hashing function used by the axl hash module to implement
1008 * translation from an user defined pointer into a number that should
1009 * be as much unique as possible.
1011 * @param key User defined data that represents the key for a data to
1012 * be stored into the hash. The value provided here usually is an
1013 * string but it could be any other data used as key.
1015 * @return The function must return a positive value that will be used
1016 * to index the content into the hash table. It doesn't matter if the
1017 * number is greater than the table size. A modulo operation is
1018 * applied to the result.
1020 typedef unsigned int (*axlHashFunc
) (axlPointer key
);
1023 * @brief Foreach function signature used to represent the set of
1024 * functions used at \ref axl_hash_foreach.
1026 * The function receives the item found (key and data values) as well
1027 * as a user defined pointer also defined at \ref
1028 * axl_hash_foreach. The function must return \ref true (<i>"item
1029 * found"</i>) to make the search to stop. In the case a full
1030 * iteration over all items inside the hash is required, the function
1031 * must always return \ref false.
1033 * @param key The key for the item stored.
1034 * @param data The data associated to the key found
1035 * @param user_data User defined data that was provided to the axl_hash_foreach function.
1037 * @return \ref true to make the foreach process to stop. \ref false
1038 * to make the process to continue.
1040 typedef bool (* axlHashForeachFunc
) (axlPointer key
, axlPointer data
, axlPointer user_data
);
1043 * @brief Foreach function signature used to represent the set of
1044 * functions used at \ref axl_hash_foreach2.
1046 * The function receives the item found (key and data values) as well
1047 * as two user defined pointers also defined at \ref
1048 * axl_hash_foreach2. The function must return \ref true (<i>"item
1049 * found"</i>) to make the search to stop. In the case a full
1050 * iteration over all items inside the hash is required, the function
1051 * must always return \ref false.
1053 * @param key The key for the item stored.
1054 * @param data The data associated to the key found
1055 * @param user_data User defined data that was provided to the axl_hash_foreach2 function.
1056 * @param user_data2 Second User defined data that was provided to the axl_hash_foreach2 function.
1058 * @return \ref true to make the foreach process to stop. \ref false
1059 * to make the process to continue.
1061 typedef bool (* axlHashForeachFunc2
) (axlPointer key
, axlPointer data
, axlPointer user_data
, axlPointer user_data2
);
1064 * @brief Foreach function signature used to represent the set of
1065 * functions used at \ref axl_hash_foreach3.
1067 * The function receives the item found (key and data values) as well
1068 * as tree user defined pointers also defined at \ref
1069 * axl_hash_foreach3. The function must return \ref true (<i>"item
1070 * found"</i>) to make the search to stop. In the case a full
1071 * iteration over all items inside the hash is required, the function
1072 * must always return \ref false.
1074 * @param key The key for the item stored.
1076 * @param data The data associated to the key found
1078 * @param user_data User defined data that was provided to the
1079 * axl_hash_foreach3 function.
1081 * @param user_data2 Second User defined data that was provided to the
1082 * axl_hash_foreach3 function.
1084 * @param user_data3 Third User defined data that was provided to the
1085 * axl_hash_foreach3 function.
1087 * @return \ref true to make the foreach process to stop. \ref false
1088 * to make the process to continue.
1090 typedef bool (* axlHashForeachFunc3
) (axlPointer key
, axlPointer data
, axlPointer user_data
, axlPointer user_data2
, axlPointer user_data3
);
1093 * @brief Foreach function signature used to represent the set of
1094 * functions used at \ref axl_hash_foreach4.
1096 * The function receives the item found (key and data values) as well
1097 * as tree user defined pointers also defined at \ref
1098 * axl_hash_foreach4. The function must return \ref true (<i>"item
1099 * found"</i>) to make the search to stop. In the case a full
1100 * iteration over all items inside the hash is required, the function
1101 * must always return \ref false.
1103 * @param key The key for the item stored.
1105 * @param data The data associated to the key found
1107 * @param user_data User defined data that was provided to the
1108 * axl_hash_foreach4 function.
1110 * @param user_data2 Second User defined data that was provided to the
1111 * axl_hash_foreach4 function.
1113 * @param user_data3 Third User defined data that was provided to the
1114 * axl_hash_foreach4 function.
1116 * @param user_data4 Forth User defined data that was provided to the
1117 * axl_hash_foreach4 function.
1119 * @return \ref true to make the foreach process to stop. \ref false
1120 * to make the process to continue.
1122 typedef bool (* axlHashForeachFunc4
) (axlPointer key
, axlPointer data
, axlPointer user_data
, axlPointer user_data2
, axlPointer user_data3
, axlPointer user_data4
);
1125 * @brief Function handler definition for to allowing copying items at
1126 * the hash by \ref axl_hash_copy function.
1128 * The function receive both pointers the key and the data value but,
1129 * only one of them must be copied. This is done to provide more
1130 * control at the copy process, but only the required value must be
1131 * returned. There is no indication to about which pointer must be
1132 * returned, so, don't use the same function to copy both pointers.
1134 * The function also receive pointers to the current function
1135 * deallocation associated to the key and value being copied. This
1136 * could also work as information to know if the data must be
1137 * replicated or not. Having the destroy function defined for the item
1138 * is a clue to return an allocated item.
1140 * @param key The key to be copied if the function was provided to copy the key.
1142 * @param key_destroy The key destroy function associated to the value
1145 * @param data The data to be copied if the function was provided to copy the data.
1147 * @param data_destroy The data destroy function associated to the
1148 * data value being copied.
1150 * @return A newly allocated reference representing the copy.
1152 typedef axlPointer (*axlHashItemCopy
) (axlPointer key
, axlDestroyFunc key_destroy
, axlPointer data
, axlDestroyFunc data_destroy
);
1155 * @brief Foreach function handler used at \ref axl_stack_foreach
1156 * function to iterate all elements inside the stack, from the head to
1159 * The function receives two user defined pointers that are defined at
1160 * the \ref axl_stack_foreach function.
1162 * @param stack_data A reference to the stack data stored.
1164 * @param user_data A reference to a user defined pointer passed to
1165 * \ref axl_stack_foreach.
1167 * @param user_data2 A second reference to a user defined pointer
1168 * passed to \ref axl_stack_foreach.
1170 * @return \ref true to make the foreach process to stop. \ref false
1171 * to make the process to continue.
1173 typedef bool (* axlStackForeach2
) (axlPointer stack_data
, axlPointer user_data
, axlPointer user_data2
);
1176 * @brief Foreach function handler used at \ref axl_stack_foreach3
1177 * function to iterate all elements inside the stack, from the head to
1180 * The function receives three user defined pointers that are defined
1181 * at the \ref axl_stack_foreach3 function.
1183 * @param stack_data A reference to the stack data stored.
1185 * @param user_data A reference to a user defined pointer passed to
1186 * \ref axl_stack_foreach3.
1188 * @param user_data2 A second reference to a user defined pointer
1189 * passed to \ref axl_stack_foreach3.
1191 * @param user_data3 Third reference to a user defined pointer passed
1192 * to \ref axl_stack_foreach3.
1194 * @return \ref true to make the foreach process to stop. \ref false
1195 * to make the process to continue.
1197 typedef bool (* axlStackForeach3
) (axlPointer stack_data
, axlPointer user_data
, axlPointer user_data2
, axlPointer user_data3
);
1200 * @brief Foreach function used by \ref axl_node_attr_foreach function.
1202 * @param key The attribute name.
1204 * @param value The attribute value.
1206 * @param data User defined pointer provided at \ref
1207 * axl_node_attr_foreach.
1209 * @param data2 Second user defined data provided at \ref
1210 * axl_node_attr_foreach.
1212 * @return The foreach function can stop the process at a particular
1213 * attribute by returning \ref true ("item found"). To iterate all
1214 * attributes return \ref false.
1216 typedef bool (* axlNodeAttrForeachFunc
) (const char * key
, const char * value
, axlPointer data
, axlPointer data2
);
1219 * @brief Entity resolver function used by the library to translate
1220 * entity references into the replacement text. This is normally used
1221 * by the library itself, not by the application programmer.
1223 * This handler is currently used at \ref axl_dtd_check_entity_ref_and_expand
1225 * @param entityName The entity name that is being requested to be
1228 * @return The user defined data provided at \ref
1229 * axl_dtd_check_entity_ref_and_expand, which is passed to the
1230 * resolver function once it is executed.
1232 typedef const char * (* axlDtdEntityResolver
) (const char * entityName
, axlPointer data
);