dom.h

linux下简单对象应用协议的开发库

The @ref soap_dom_element::type is 0 or a SOAP_TYPE_X constant, where X is the
name of the deserialized type. The @ref soap_dom_element::node points to the
deserialized object. If this is a char* string, it points directly to the
character sequence.

Note: the SOAP_DOM_TREE flag restricts the parser to DOM content only, so
deserializers is not used. When the SOAP_DOM_TREE flag is not used, an
appropriate deserializer MAY be used by gSOAP when an element contains an id
attribute and gSOAP can determine the type from the id attribute reference
and/or the xsi:type attribute of an element. 

@section dom_4 Searching

Common operations on DOM node sets in level-2 DOM parsers are searching and
filtering.

For C++ code, the built-in @ref soap_dom_element::iterator can be used to
search for matching element nodes. C programmers are out of luck as they should
write looping code to search for nodes explicitly.

The @ref soap_dom_element::find method returns a search iterator. The method
takes an optional namespace URI and element name to match elements in the DOM
node set.  For example, to iterate over all "product" elements:

@code
    soap_dom_element dom;
    ...
    for (soap_dom_element::iterator iter = dom.find(NULL, "product"); iter != dom.end(); ++iter)
      cout << "Element " << (*iter).name << endl;
    ...
@endcode

To iterate over all elements in a particular namespace:

@code
    soap_dom_element dom;
    ...
    for (soap_dom_element::iterator iter = dom.find("http://www.w3.org/2001/XMLSchema", NULL); iter != dom.end(); ++iter)
      cout << "Element " << (*iter).name << endl;
    ...
@endcode

Since namespaces may have different version, a '*' wildcard can be used with
the namespace string. Likewise, tag names may be namespace qualified with
prefixes that are not relevant to the search:

@code
    soap_dom_element dom;
    ...
    for (soap_dom_element::iterator iter = dom.find("http://www.w3.org/*XMLSchema", "*:schema"); iter != dom.end(); ++iter)
      cout << "Element " << (*iter).name << endl;
    ...
@endcode

This searches for qualified elements in one of the XSD namespaces.

@section dom_5 Constructing DOM Node Sets

The @ref soap_dom_element::set and @ref soap_dom_element::add methods are used
to decorate a DOM node set with child element nodes and attribute nodes.
Application data with serializers can be incorporated in the node set as well.

The following examples are shown in C++.  C programmers can use the @ref
soap_dom_element:elts list and @ref soap_dom_elements::atts list to add child
nodes and attribute nodes, respectively.

@code
    soap_dom_element dom;
    dom.soap = soap_new1(SOAP_C_UTFSTRING | SOAP_XML_INDENT);
    const char *myURI = "http://www.mydomain.com/myproducts";
    ns__myProduct product();
    product.soap_default(dom.soap); // method generated by soapcpp2
    product.name = "Ernie";
    product.SKU = 123;
    product.price = 9.95;
    dom.set(myURI, "list");
    dom.add(soap_dom_attribute(dom.soap, myURI, "version", "0.9"));
    dom.add(soap_dom_element(dom.soap, myURI, "documentation", "List of products"));
    dom.add(soap_dom_element(dom.soap, myURI, "product", SOAP_TYPE_ns__myProduct, &product);
    cout << dom;
    ...
@endcode

Assuming that myURI is associated with namespace prefix "ns" in the namespace
table, the rendition is

@code
<?xml version="1.0" encoding="UTF-8"?>
<ns:list
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:ns="http://domain/schemas/product.xsd"
  version="0.9" >
	<ns:documentation>List of products</ns:documentation>
	<ns:product>
		<name>Ernie</name>
		<SKU>123</SKU>
		<price>9.95</price>
	</ns:product>
</ns:list>
@endcode

Note that the namespace table content is "dumped" into the XML rendition.

The global namespace mapping table "namespaces[]" contains the namespace
bindings that should be meaningful to the application. The soap context can be
set to a new table as follows:

@code
    Namespace myNamespaces[] = { { "ns", "..." }, ... , { NULL } };
    soap_dom_element dom;
    dom.soap = soap_new1(SOAP_C_UTFSTRING | SOAP_XML_INDENT);
    dom.soap->namespaces = myNamespaces;
@endcode

To produce cleaner XML, use the SOAP_XML_CANONICAL flag to initiate the soap
context:

@code
<ns:list xmlns:ns="http://domain/schemas/product.xsd" version="0.9" >
	<ns:documentation>List of products</ns:documentation>
	<ns:product>
		<name>Ernie</name>
		<SKU>123</SKU>
		<price>9.95</price>
	</ns:product>
</ns:list>
@endcode

Note that the xmlns bindings are rendered automatically. When parsing an XML
document, xmlns bindings are not added to the attribute node set. The @ref
soap_dom_element::nstr and @ref soap_dom_attribute::nstr namespace strings are
set to retain namespace URIs. The XML rendering algorithm uses the namespace
strings to add xmlns bindings that are not already in the namespace table.

When it is desirable to render XML exactly as represented in the DOM node set,
e.g. when xmlns bindings are explicitly included in the attribute node set, use
the SOAP_DOM_ASIS flag:

@code
    soap_dom_element dom;
    dom.soap = soap_new1(SOAP_C_UTFSTRING | SOAP_DOM_ASIS);
@endcode

@section dom_6 Example

The gSOAP header file below imports DOM and declares xsd:float to enable
serializing floats embedded within DOM node sets and deserializing floats to
populate DOM node sets:

@code
    #import "dom.h"
    typedef float xsd__float;
@endcode

Consider invoking the XMethods delayed stock quote service to obtain a stock
quote. The float deserializer is used to store the floating-point value of a
stock given that the <Result> element has an xsi:type="xsd:float" attribute.

@code
    struct soap *soap = soap_new1(SOAP_C_UTFSTRING | SOAP_DOM_NODE);
    soap_dom_element envelope(soap, "http://schemas.xmlsoap.org/soap/envelope/", "Envelope");
    soap_dom_element body(soap, "http://schemas.xmlsoap.org/soap/envelope/", "Body");
    soap_dom_attribute encodingStyle(soap, "http://schemas.xmlsoap.org/soap/envelope/", "encodingStyle", "http://schemas.xmlsoap.org/soap/encoding/");
    soap_dom_element request(soap, "urn:xmethods-delayed-quotes", "getQuote");
    soap_dom_element symbol(soap, NULL, "symbol", "IBM");
    soap_dom_element response(soap);
    envelope.add(body);
    body.add(encodingStyle);
    body.add(request);
    request.add(symbol);
    cout << "Request message:" << endl << envelope << endl;
    if (soap_connect(soap, "http://services.xmethods.net/soap", "")
     || soap_out_xsd__anyType(soap, NULL, 0, &envelope, NULL)
     || soap_end_send(soap)
     || soap_begin_recv(soap)
     || NULL != soap_in_xsd__anyType(soap, NULL, &response, NULL)
     || soap_end_recv(soap)
     || soap_closesock(soap))
    { soap_print_fault(soap, stderr);
      soap_print_fault_location(soap, stderr);
    }
    else
    { cout << "Response message:" << endl << response << endl;
      for (soap_dom_element::iterator walker = response.find(SOAP_TYPE_xsd__float); walker != response.end(); ++walker)
        cout << "Quote = " << *(xsd__float*)(*walker).node << endl;
    }
    soap_destroy(soap);
    soap_end(soap);
    soap_done(soap);
    free(soap);
@endcode

@section dom_7 Summary

The DOM parser needs a soap context to allocate nodes:

@code
    soap_dom_element dom;
    dom.soap = soap_new1(... flags ...);
    ...
    soap_destroy(dom.soap);
    soap_end(dom.soap);
    soap_done(dom.soap);
    soap_free(dom.soap);
@endcode

The nodes are removed with soap_destroy (for C++) and soap_end. The soap_done
function should only be used before the soap context is deallocated.

The soap context flags that control the parsing and rendition of XML are:

- (no flag): only elements with an id attribute are deserialized as C/C++ data
  types (when a deserializer is available). XML elements with character data
  are deserialized into the @ref soap_dom_element::wide field.
- SOAP_C_UTFSTRING: store character data in UTF-8 format in @ref
  soap_dom_element::data.
- SOAP_C_MBSTRING: store character data in multi-byte format in @ref
  soap_dom_element::data, where the decoding depends on the current
  localication. The platform must support MB strings (HAVE_MBTOWC).
- SOAP_DOM_TREE: prevents deserialization of C/C++ data structures into the
  DOM.
- SOAP_DOM_NODE: attempt to deserialize C/C++ data structures when a
  deserializer is available. A deserializer is selected based on the element
  name or the xsi:type attribute.
- SOAP_DOM_ASIS: render XML "as is", i.e. do not insert xmlns bindings for URIs
  stored in nstr. Assumes the DOM is self-contained.
- SOAP_XML_INDENT: render XML with indent.
- SOAP_XML_CANONICAL: render XML in exc-c14n form.

The DOM traversal operations:

- @ref soap_dom_next_element returns the next element in an in-order traversal.
- @ref soap_dom_next_attribute returns the next attribute of a node.

The @ref soap_dom_element fields:

- @ref soap_dom_element::next pointer to next sibling in list.
- @ref soap_dom_element::prnt pointer to parent node.
- @ref soap_dom_element::elts pointer to list of child element nodes.
- @ref soap_dom_element::atts pointer to list of attribute nodes.
- @ref soap_dom_element::nstr optional namespace string of this node.
- @ref soap_dom_element::name the name of the element node (with optional
  prefix).
- @ref soap_dom_element::data optional character data in UTF-8 format.
- @ref soap_dom_element::wide optional character data in wide string format.
- @ref soap_dom_element::type optional SOAP_TYPE_X type of a C/C++ data
  structure stored with this node.
- @ref soap_dom_element::node optional pointer to the C/C++ data structure
  stored with this node.
- @ref soap_dom_element::head optional leading whitespace to the start tag.
- @ref soap_dom_element::tail optional leading whitespace to the end tag.
- @ref soap_dom_element::soap the soap context that manages this node.

The @ref soap_dom_element types:

- @ref soap_dom_element::iterator

The @ref soap_dom_element methods:

- @ref soap_dom_element::set(nstr, name);
- @ref soap_dom_element::set(data);
- @ref soap_dom_element::set(node, type);
- @ref soap_dom_element::add(soap_dom_element);
- @ref soap_dom_element::add(soap_dom_attribute);
- @ref soap_dom_element::begin();
- @ref soap_dom_element::end();
- @ref soap_dom_element::find(nstr, name);
- @ref soap_dom_element::find(type);
- @ref soap_dom_element::unlink();

The @ref soap_dom_element constructors:

- @ref soap_dom_element();
- @ref soap_dom_element(soap);
- @ref soap_dom_element(soap, nstr, name);
- @ref soap_dom_element(soap, nstr, name, data);
- @ref soap_dom_element(soap, nstr, name, node, type);

The @ref soap_dom_attribute fields:

- @ref soap_dom_attribute::next pointer to next attribute node in list.
- @ref soap_dom_attribute::nstr optional namespace string of this node.
- @ref soap_dom_attribute::name the name of the attribute (with optional
  prefix).
- @ref soap_dom_attribute::data optional character data in UTF-8 format.
- @ref soap_dom_attribute::soap the soap context that manages this node.

The @ref soap_dom_attribute types:

- @ref soap_dom_attribute::iterator

The @ref soap_dom_attribute methods:

- @ref soap_dom_attribute::set(nstr, name);
- @ref soap_dom_attribute::set(data);
- @ref soap_dom_attribute::begin();
- @ref soap_dom_attribute::end();
- @ref soap_dom_attribute::find(nstr, name);
- @ref soap_dom_attribute::unlink();

The @ref soap_dom_attribute constructors:

- @ref soap_dom_attribute();
- @ref soap_dom_attribute(soap);
- @ref soap_dom_attribute(soap, nstr, name, data);

*/

/// @brief The custom serializer for DOM element nodes is represented by xsd__anyType.
extern typedef struct soap_dom_element xsd__anyType;

/// @brief The custom serializer for DOM attribute nodes is represented by xsd__anyAttribute.
extern typedef struct soap_dom_attribute xsd__anyAttribute;