axlDoc * axl_doc_parse ( const char *  entity,
int  entity_size,
axlError **  error 
)

Parse an XML entity that is hold inside the memory pointed by entity and limited by entity_size.

The function parses the XML document inside the memory hold inside the given reference. The function returns an XML document, represented by axlDoc.

The function, optionall, could report error found inside the given axlError variable. In the case the function returns a NULL value, this variable is filled containing the a textual diagnostic error to be showed to the user interface and an error code.

Here is an example:

 // axl document representation 
 axlDoc   * doc;
 axlError * error;
        

 // parse the given string 
 doc = axl_doc_parse ("<?xml version='1.0' ?><axldoc />", 32, &error);
 if (doc == NULL) {
      printf ("Error found: %s\n", axl_error_get (error));
      axl_error_free (error);
      return false;
 }

 // release document parsed 
 axl_doc_free (doc);    

Parameters:
entity The XML document to load.
entity_size The XML document size to load. If a -1 is provided, strlen function is used to figure out current document size. This is not recomended while using xml documents that include binary data, that maybe comes inside the CDATA section or because an utf caracter used that includes the \0 inside its value.
error Optional axlError reference that will be used to report errors found while processing xml into the axlDoc instance.
Returns:
A newly allocated Axl Document, that must be deallocated using axl_doc_free, when no longer needed. The function could return NULL if the document is not loaded properly.
In the case an error is found while procesing the document, error variable will be filled, if defined. -1 will be returned is received parameter are wrong. -2 will be returned if there some error is found while processing the document.