2.12 Additional Tips for C++ Drivers

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.

Documents submitted to DirXML. Documents submitted to DirXML are submitted either through the XmlCommandProcessor interface passed to the PublicationShim::start method or through the XmlQueryProcessor interface passed to the SubscriptionShim::execute method. In either case the driver must handle destroying the XmlDocument object passed to DirXML as well as the underlying XML representation. For example, if the driver uses the factory methods Document_new and XmlDocument_newFromDOM, then the driver must destroy the XmlDocument object through XmlDocument_destroy method and the DOM object through DOM::Document::destroy method.

Documents returned to DirXML. Documents returned to DirXML are returned from DriverShim::init, DriverShim::shutdown, SubscriptionShim::init, SubscriptionShim::execute, PublicationShim::init, and PublicationShim::start. Such documents must not be destroyed until they are no longer used. DirXML guarantees that a return document is no longer referenced when

  • 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.