Using the object XML functions

You can use the XML functions to transform XML documents to  structures, or  structures to XML documents. You can also use the ARGetListXMLObjects call to get a list of the  structures in an XML document.

Make sure that your program calls the ARInitialization call at the beginning of its execution. See AR-System-C-API-functions.

Transforming XML documents into  structures

Use the following  XML API functions and structures to transform XML documents into  structures:

ARXMLInputDoc

Supply this structure with the XML document to parse, in one of the following forms:

• AR_XML_DOC_CHAR_ST — null-terminated character string (you must free the memory associated with this action)
• AR_XML_DOC_FILE_NAME — file name
• AR_XML_DOC_URL — URL
   See the ar.h file for definitions of this structure.

ARParseXMLDocument

This function parses the XML document and returns a parsed XML stream and a list of object names and types.
 The combination of object name and object type must be unique for each object in the XML document. For example, you cannot have two schemas named ABC in a single XML document. However, you can have a schema and a filter named ABC in one XML document, as these are different object types.

ARGetObjectFromXML

These functions retrieve the properties of the object from the parsed XML stream and places the properties into the output parameters. Supply NULL for any property that you do not want to retrieve.

FreeARXMLParsedStream

This function frees memory associated with the parsed stream. For more information, see arfree.h.

Transforming  structures into XML documents

Use the following  API functions and structures to transform  structures into XML documents:

ARXMLOutputDoc

This structure contains the XML document generated from calls to the Set functions in one of the following forms:

• AR_XML_DOC_CHAR_STR — null-terminated character string
• AR_XML_DOC_FILE_NAME — file name (A new file is created. If the file already exists, the new XML contents are appended to the end of the file.)
• AR_XML_DOC_FILE_HANDLE — file handle
   See the ar.h file for definitions of this structure.

ARSetHeaderToXML

This function generates the XML declaration and start tag for the root element (such as <?xml...?>< root> ).
 The server sets the document encoding in the XML declaration to the encoding of your local machine.

ARSetStructureToXML

This function transforms  structures into XML.

ARSetFooterToXML

This function generates the XML footer, which is the ending tag for the root element (</root>).

FreeARXMLParsedStream

This function frees memory associated with parsed stream.

If you only have a single structure to transform to XML, you can set the xmlDocHdrFtrFlag flag to TRUE (T) to automatically generate the XML document header and footer, instead of calling the ARSetHeaderToXML and ARSetFooterToXML functions. If you transform multiple structures to XML and combine them together, set this flag to FALSE (F).

Listing  structures

Use the ARGetListXMLObjects call to list the  objects in an XML document and retrieve the following object characteristics:

• The object name.
• The object type, which is in the form AR_STRUCT_ITEM_XML_ objectType, where objectType is filter, schema, or other object types.
• The object subtype. For container objects, the subtype is in the form ARCON_containerType, where containerType is a guide, application, packing list, or filter guide. Currently only containers have a valid subtype. The subtype value for non-container objects is -1.
   If you are only retrieving object names, use the object subtype to increase the retrieval speed.
  
  See the ar.h file for object values.