XDS_Lite_Library_API_Reference

XDS Lite Library API Reference The XDS-Lite library is a lightweight XML and XDS serialization library that you can use in your projects. In order to make the library efficient, it supports only the most important features of XML and XDS. 1. Library Customization To use the library, you must perform a small level of customization. All of this customization is isolated into a single file named XDSConfig.h. To perform the customization, copy the XDSConfig_sample.h file to your project and rename it XDSConfig.h. Then modify the file by commenting and un-commenting the configuration #defines and callback function declarations. 1.1 Configuration #defines XDS_SUPPORT_ALLOCNODES If this symbol is defined, the library will allocate memory for all data that is passed to XDS_PROCESSNODE. If this is not defined, the data passed to XDS_PROCESSNODE is temporary and must be copied by the host program before returning from the function. XDS_SUPPORT_COMPACTDSD If this symbol is defined, the library will build a stripped down version of the Data Stream Definition containing only the bare minimum amount of data needed to read an XDS file. This option is not compatible with XDS_SUPPORT_DEFTYPE or XDS_SUPPORT_XML. XDS_SUPPORT_DEFTYPE If this symbol is defined, the library will include functions to allow the programmatic definition of XDS Data Stream Definitions. This option has little effect on the internals of the library. This option is not compatible with XDS_SUPPORT_COMPACTDSD. XDS_SUPPORT_READBYRECORD If this symbol is defined, the library will read entire records into memory and then process each element in the record. If it is not defined, the library will read each element individually. Reading entire records makes more efficient use of the I/O interface, but requires a larger read buffer. XDS_SUPPORT_SIGNATURE If this symbol is defined, the library will include support to read and write XDS signature records. XDS_SUPPORT_WRITING If this symbol is defined, the library will include support for writing XDS data files. XDS_SUPPORT_XML If this symbol is defined, the library will include support for reading XML instance documents that are compliant with a specified DSD. XDS_SUPPORT_XMLCOMMENTS If this symbol is defined, the library will pass comments read from XML instance documents to the XDS_PROCESSNODE callback function. If the symbol is not defined, XML comments are ignored. XDS_CONFIG_NUMIDS The default number of user-defined DSD type/element IDs to handle. The behavior of the library is optimal when this number exactly matches (or only slightly exceeds) the actual number of IDs used. This value is only used when XDS_SUPPORT_COMPACTDSD is defined. XDS_CONFIG_XMLALLSTRUCTFIELDS If this symbol is defined, the library requires all fields of a structure to be present when reading XML data. If it is not defined, any absent structure field will be initialized to all zeros. 1.2 Callback Functions The XDS-Lite library callback functions greatly simplify the work required to integrate the XDS-Lite library into an operating environment. Any program using the XDS-Lite library must provide implementations of six callback functions. These functions are called when the library needs to access resources managed by the host program. These callbacks are used to read from and write to ‘files’, allocate and free memory, process loaded data, and report errors. I/O The XDS_READ and XDS_WRITE callback functions are used to read a block of data from or write a block of data to an application-defined data stream. int XDS_READ(void *hFile, void *buf, int iSize); int XDS_WRITE(void *hFile, void *buf, int iSize); Memory Management The XDS_ALLOC and XDS_FREE functions are used to allocate, reallocate and release memory. If a NULL buffer is passed into XDS_ALLOC it performs a new allocation; otherwise, the buffer is reallocated with the new size while preserving its original contents. The iMemType argument to XDS_ALLOC is used to specify the general type of data being allocated. This argument can be ignored if you do not want to handle different types of memory differently. The possible memory types are XDS_MEMTYPE_SCRATCH, used to allocate internal memory for the XDS-Lite library; XDS_MEMTYPE_BUFFER, used to allocate I/O buffers; and XDS_MEMTYPE_NODE, used to allocate user data passed to XDS_PROCESSNODE. void *XDS_ALLOC(void *buf, int iSize, int iMemType); void XDS_FREE(void *buf); Data Handling The XDS_PROCESSNODE function is used to pass a decoded piece of data from the stream to the host program. This function is called once for the data record being read and once for each attribute, element and sub-record within the record. This function is also called whenever a comment records is found in the data stream If XDS_SUPPORT_ALLOCNODES is defined, it is the responsibility of the host program to release the node data passed to this function. The host program should never free node data for comment records. void XDS_PROCESSNODE(unsigned short nodeType, void *nodeData, int nodeSize); Error Handling The XDS_ERROR function is called to report errors in reading XML, reading or writing XDS, or in arguments to other API calls. Every XDS error is treated as fatal. The API may not always gracefully handle returns from this function. void XDS_ERROR(const char *errText); 2. API Functions 2.1 Stream Setup, Cleanup functions The xdsInit and xdsFini functions are used to initialize and terminate an XDS stream respectively. The xdsRestart function is used to reuse an pre-initialized XDS stream handle to process a new XDS stream. xdsFini should not be called on a handle that is to be reused with a subsequent call to xdsRestart. The file handle hFile passed to the xdsInit function is never used directly by the XDS-Lite library; it is instead passed to the XDS_READ and XDS_WRITE callback functions when the library needs to read or write data. struct xdsHandle *xdsInit(void *hFile, const char *szStreamName, const unsigned char *pDSD, char mode=’r’); bool xdsFini(struct xdsHandle *hXds); bool xdsRestart(struct xdsHandle *hXds, void *hFile, char mode='r'); 2.2 Data Type Definition functions The xdsDef… functions are used to programmatically create a data stream definition. Functions are present to declare records, elements, attributes, and all XDS data types. With the exception of the structure field and enumeration value definition functions, the return value for each of these functions is the type ID used in the XDS stream to represent the defined type. Declaring complex types requires multiple function calls. Defining a complex type such as structures and enumerations requires multiple function calls. Once call starts the definition (xdsDefStructType, xdsDefEnumeratedType), another call defines is made for each member of the complex type (xdsDefStructField, xdsDefEnumerand) and a third is made to complete the type definition (xdsDefStructDone, xdsDefEnumeratedDone). 2.3 Reading and Writing functions xdsReadRecord is the one and only reading function in the library. This function reads one entire record in the input stream including all of its associated attributes, elements and sub-records. It returns false if the end of the input stream is reached. bool xdsReadRecord(struct xdsHandle *hXds); The xdsStartRecord, xdsWriteNode, xdsEndRecord and xdsEndStream functions are used to write data records to the output stream. bool xdsStartRecord(struct xdsHandle *hXds, unsigned short iType); Since XDS records contain a size value to simplify parsing, no data is actually written to the stream until the xdsEndRecord function is called. Until that time, data is accumulated in an internally allocated buffer. bool xdsWriteNode(struct xdsHandle *hXds, unsigned short iType, void *data, int iCount); Since data can only exist within an active record, this function will return false if it is called prior to xdsStartRecord. The iCount argument to xdsWriteNode is only used when writing variable-size string and array elements. bool xdsEndRecord(struct xdsHandle *hXds); bool xdsEndStream(struct xdsHandle *hXds); The library will cleanly handle situations where xdsFini is called prior to closing a record or closing the stream. Once xdsEndStream is called, no further writing is possible. 3. Limitations of the XDS-Lite library As the name may suggest, the XDS-Lite library is neither a fully featured XML parser nor is it a fully featured XDS parser. XDS-Lite has the following limitations:. When reading XML data · Only supports XML documents in the UTF-8 character set. · Only reads XML documents that follow a provided XDS DSD. · Does not support any XML entities (e.g. “&”, “'”, “>”, “<”,). · Does not support embedded references to other XML documents. · Does not support writing XML documents. When reading or writing XDS data · Only supports tag names in the UTF-8 character set. · Requires that the data in the XDS file was created with host-native byte order and structure padding – does no reordering or re-padding of data types. · Requires that the data in the XDS file matches the data stream definition – does no remapping of data types. · Does not use the constructor to create C++ class instances. While this may be okay for some classes, it is a problem for virtual classes and for classes where special processing (e.g. registration, resource allocation) is done during construction.