Annotation of gpl/axl/src/axl_decl.h, revision 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