XML Layer Overview
The XML API in WWSAPI is based on the XML Reader and XML Writer objects, which allow reading or writing of XML documents in a forward only fashion. The XML Layer give the application full access to and control over the content of messages.
Encoding
The XML API supports documents encoded as:
- Text (UTF-8, UTF-16LE, UTF-16BE)
- Binary
- MTOM
Storage
The XML API supports processing documents stored as:
- An in-memory buffer of encoded bytes
- A stream
- An XML Buffer
An XML Buffer is a structured in-memory representation of an XML document. This is a more efficient representation than a document encoded as bytes. An XML document stored in an XML Buffer can be navigated, read, or written.
I/O
The XML API will never perform I/O unless specifically requested. Furthermore, any I/O may be initiated in an asynchronous fashion. See WsFillReader and WsFlushWriter for details on asynchronous processing with the XML API.
Processing
The XML API has three distinct levels at which the document may be processed.
A document may be processed a node at a time. This offers the most fine-grained handling of the XML content, and provides complete fidelity of data from the document. At this level, the functions WsReadNode and WsWriteNode and WsCopyNode would be used.
The next level of control are APIs like WsReadStartElement, WsReadValue and WsReadEndElement. These APIs provide numerous kinds of validation, skip whitespace and comments, and normalize text and CDATA to present the consumer with a simpler view of the xml.
The highest level of control is to use the Serialization API. These APIs are driven off a mapping between C data types and XML, and can read or write a complex in-memory structure to xml and back with a single function like WsWriteElement and WsReadElement.
The XML Canonicalization APIs may be used to generate a canonical form of XML which may in turn be used for generating cryptographic signatures over XML content.
Creating a writer
To create and use a writer to write to an in-memory buffer:
WsCreateWriter // Create an instance of a WS_XML_WRITER
// Initialize a WS_XML_WRITER_BUFFER_OUTPUT
WsSetOutput // Set the encoding and output of the writer along with any other writer properties
// Write Elements
WsGetWriterProperty(..., WS_XML_WRITER_PROPERTY_BYTES, ...) // Get the generated bytes as a single byte array
// Use the generated bytes
WsFreeWriter // Free the writer
To create and use a writer to write to a stream:
WsCreateWriter // Create an instance of a WS_XML_WRITER
// Initialize a WS_XML_WRITER_STREAM_OUTPUT
WsSetOutput // Set the encoding and output of the writer along with any other writer properties
// Write Elements
WsFlushWriter // Force any buffered data to be written
WsFreeWriter // Free the writer
To create and use a writer to write to a WS_XML_BUFFER:
WsCreateXmlBuffer // Create the buffer to write to
WsCreateWriter // Create an instance of a WS_XML_WRITER
WsSetOutputToBuffer // Set the output buffer along with any other writer properties
// Write Elements
WsFreeWriter // Free the writer
// The buffer has the generated document
In all cases, the property WS_XML_WRITER_PROPERTY_INDENT may be included to format the xml.
Writing Elements
To write an element to a writer:
WsWriteStartElement // Write a start element
for each attribute
{
// Write an attribute using either
WsWriteStartAttribute // Write a start attribute
// Write Content
WsWriteEndAttribute // Write an end attribute
// Or one of the following
WsWriteXmlnsAttribute // Write an explicit xmlns attribute
}
// Write Elements or Content
WsWriteEndElement
The following may also be used:
WsWriteArray // Write an array of primitive values as a series of repeated elements
Writing Content
To write content to an element or attribute, the following may be used:
WsWriteChars // Write unicode characters from memory
WsWriteCharsUtf8 // Write UTF-8 encoded characters from memory
WsWriteBytes // Write binary data encoded as base64
WsPushBytes // Direct the writer to request that bytes be written
WsPullBytes // Direct the writer to read the bytes to be written
WsWriteValue // Write primitive values such as ints and BOOLs
WsWriteText // Write an WS_XML_TEXT
WsWriteQualifiedName // Write a qualified name
The following can be used to write to a document, but may not be used when within an attribute.
WsWriteNode // Write a single WS_XML_NODE
WsCopyNode // Copy a single node, or an entire WS_XML_ELEMENT_NODE and children from an WS_XML_READER
The following may be used to write a CDATA section in a text document:
WsWriteStartCData // Start a CDATA section in a text encoding
// Write Content
WsWriteEndCData // End a CDATA section in text encoding
Miscellaneous
WsGetPrefixFromNamespace // Find a prefix bound to a namespace
Creating a reader
To create and use a reader to read from an in-memory buffer:
WsCreateReader // Create an instance of a WS_XML_READER
// Initialize a WS_XML_READER_BUFFER_INPUT
WsSetInput // Set the encoding and input of the reader along with any other reader properties
// Read Elements
WsFreeReader // Free the reader
To create and use a reader to reader from a stream:
WsCreateReader // Create an instance of a WS_XML_READER
// Initialize a WS_XML_READER_STREAM_INPUT
WsSetInput // Set the encoding and input of the reader along with any other reader properties
WsFillReader // Populate the reader with data from the underlying stream
// Read Elements
WsFreeReader // Free the reader
To create and use a reader to read from a WS_XML_BUFFER:
WsCreateXmlBuffer // Create the buffer to write to
WsCreateReader // Create an instance of a WS_XML_READER
WsSetInputToBuffer // Set the input buffer along with any other reader properties
// Read Elements
WsFreeReader // Free the reader
Reading Elements
To read an element from a reader:
WsReadToStartElement // Skip whitespace and comments to position the reader on a specific element
for each attribute of interest
{
WsFindAttribute // Try Locate the attribute
if (found)
{
WsReadStartAttribute // Set the reader to read the attribute
// Read Content
WsReadEndAttribute // Return the reader to the element
}
}
WsReadStartElement // Advance the reader past the current element
// Read Elements or Content
WsWriteEndElement // Advance the reader past the corresponding end element
The following may also be used:
WsReadArray // Read an array of primitive values as a series of repeated elements
Reading Content
To read content from an element or attribute, the following may be used:
WsReadChars // Read characters to memory as unicode
WsReadCharsUtf8 // Read characters to memory encoded as UTF-8
WsReadBytes // Read binary data encoded as base64
WsReadValue // Read primitive values such as ints and BOOLs
WsReadQualifiedName // Read a qualified name
The following may be used to inspect the current node the reader is positioned on:
WsGetReaderNode // Get the current node
Using a buffer
When writing to a WS_XML_BUFFER the following may be used:
WsGetWriterPosition // Get the current position of the writer in the document
WsSetWriterPosition // Set the current position of the writer in the document
WsMoveWriter // Move relative to the current position in the document
WsRemoveNode // Delete an element or text from a document
When reading from a WS_XML_BUFFER the following may be used:
WsGetReaderPosition // Get the current position of the reader in the document
WsSetReaderPosition // Set the current position of the reader in the document
WsMoveReader // Move relative to the current position in the document
The following may be used to modify a WS_XML_BUFFER:
WsRemoveNode // Delete an element or text from a document
Other
WsGetNamespaceFromPrefix // Find a namespace bound to a prefix
WsGetXmlAttribute // Find an "xml:space" or "xml:lang" attribute in scope
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for