C++ requires memory management and does
not provide generated documentation for helper classes and methods.
The following sections provide information on these topics.
2.12.1 Memory Management
As with any C++ program, a DirXML driver
must carefully manage the objects it creates. Primarily, a driver
must destroy any XML document objects that it creates, and a driver
must not destroy any XML document objects passed to it. This requires
management for two primary areas.
- Another method in the same interface
is called. For example, the document returned from SubscriptionShim::init()
may be destroyed when SubscriptionShim::execute method is called.
- The same method is called again. For example, a
document returned from a previous call of SubscriptionShim::execute
method may be destroyed during a subsequent call to SubscriptionShim::execute
method.
- The DriverShim::destroy method is called.
Any other objects that the driver creates are also the driver’s
responsibility to destroy. For example, if the driver calls FileOutputStream_newFromName,
then the driver must also call FileOutputStream_destroy
with the returned object when it is no longer used.
2.12.2 C++ Utility Functions
and Interfaces
There are a number of utility functions available. These fall
into the following general categories:
- Interface factories and destructors
- Encoding support
- Support for DirXML’s XML dialect (XDS Support)
The following sections provide a brief overview of the utility
functions. For a more complete description, see XML
Interfaces for C++.
Interface Factories and Destructors
DirXML SDK supplies implementations of all required interfaces.The
interface factories and corresponding destructors are defined in InterfaceFactory.h.
If a factory method does not have a corresponding destructor method,
the destructor method is defined in the interface itself (see DOM::Node::destroy,
for example).
A driver writer is free to implement the interfaces for passing
data to DirXML from the driver if such an implementation works better
for a particular driver. However, all interfaces passed to the driver
from DirXML will use DirXML’s underlying implementation.
General Interfaces
- DriverFilter_new—Creates
an implementation of DriverFilter. This is a useful for drivers
who need to make use of the Event Filter in their driver.
- DriverFilter_destroy—Destroys an implementation
of DriverFilter returned from the factory method.
- Trace_new—Creates an implementation of
Trace. This is useful for debugging. The Trace interface causes
messages to be written to the DSTrace screen and, optionally, a
file.
- Trace_destroy—Destroys an implementation
of Trace returned from Trace_new.
DOM Interfaces
- Document_new—Creates a new
DOM Document object using the DirXML native implementation.
- Document_destroyInstance—Destroys a DOM
Document object returned from Document_new.
- XmlDocument_newFromDOM—Creates a new XmlDocument
implementation from a DOM Document object.
- XmlDocument_destroy—Destroys an XmlDocument
implementation returned from a factory method.
Serialized XML Interfaces
- FileOutputStream_newFromName—Creates
an implementation of OutputStream that uses a standard C library
FILE as the underlying stream.
- FileOutputStream_newFromFILE—Creates an
implementation of OutputStream that uses a standard C library FILE
as the underlying stream.
- FileOutputStream_destroy—Destroyes a FileOutputStream
returned from a factory method.
- ByteArrayOutputStream_new—Creates an implementation
of OutputStream that uses a byte array as the underlying stream.
- ByteArrayOutputStream_getDataSize—Returns
the size of the data in a ByteArrayOutputStream returned from ByteArrayOutputStream_new.
- ByteArrayOutputStream_getBytes—Returns
a pointer to the data in a ByteArrayOutputStream returned from ByteArrayOutputStream_new.
- ByteArrayOutputStream_destroy—Destroyes
a ByteArrayOutputStream returned from the factory method.
- XmlDocument_newFromBytes—Creates a new
XmlDocument implementation from a byte array using the DirXML native
implementation.
- XmlDocument_destroy—Destroys an XmlDocument
implementation returned from a factory method.
SAX Interfaces
- Parser_new—Creates a new
SAX Parser implementation using the DirXML native implementation.
- Parser_destroy—Destroys a SAX Parser returned
from Parser_new.
- InputSource_new—Creates a new SAX InputSource
implementation using the DirXML native implementation.
- InputSource_destroy—Destroys a SAX InputSource
returned from InputSource_new.
- SAXException_new—Creates an implementation
of SAXException. This is useful for drivers implementing the SAX
DocumentHandler interface.
- SAXParseException_new—Creates an implementation
of SAXParseException. This is useful for drivers implementing the
SAX Parser interface.
- XmlDocument_newFromSAX—Creates a new XmlDocument
implementation from a SAX Parser and InputSource.
- XmlDocument_destroy—Destroys an XmlDocument
implementation returned from a factory method.
Encoding Support
The encoding support functions are for converting to and from
Base64 encoding and for converting between UTF-8 and UTF-16 encoding.
Base64 encoding is how DirXML encodes binary data in the XML documents
used for encoding commands and events. UTF-8 and UTF-16 are two
encoding methods for Unicode characters using 8- and 16-bit encoding
units, respectively. Base64 functions are declared in Base64Codec.h,
and the UTF functions are in UTFConverter.h.
- Base64Codec_encode—Encodes
a byte array into UTF-16 characters using Base64 encoding.
- Base64Codec_encodeFree—Frees the UTF-16
string returned from Base64Codec_encode.
- Base64Codec_decode—Decodes a UTF-16 character
string that represents binary data into a byte array.
- Base64Codec_decodeFree—Frees the byte array
returned from Base64Codec_decode.
- UTFConverter_16to8—Converts a UTF-16 string
to UTF-8.
- UTFConverter_8to16—Converts a UTF-8 string
to UTF-16.
- UTFConverter_free—Frees a string returned
from UTFConverter_16to8 or UTFConverter_8to16.
XDS Support
XDS (XML Directory Services) is the name of the XML dialect
used by DirXML. The XDS support functions allow access to the strings
necessary to create a valid XDS document and provide simple methods
to create empty XDS input and output documents. The XDS support
functions are in NdsDtd.h and include the following:
- NdsDtd_getStrings—Returns
a pointer to a structure containing pointers to const unicode strings.
These strings are tag names, attribute names, and attribute values
defined in nds.dtd. See the actual include file for the structure
declaration.
- NdsDtd_newInputDocument—Creates a new,
empty input document for publishing data to DirXML.
- NdsDtd_newOutputDocument—Creates a new,
empty output document for returning data to DirXML.
- NdsDtd_addStatus—Adds a status element
to an input or an output element in an XDS document.