Vue d’ensemble de la couche XML

L’API XML dans WWSAPI est basée sur les objets lecteur XML et Writer XML , qui autorisent la lecture ou l’écriture de documents XML en mode avant uniquement. La couche XML offre à l’application un accès complet et un contrôle sur le contenu des messages.

Encodage

L’API XML prend en charge les documents encodés comme suit :

  • Texte (UTF-8, UTF-16LE, UTF-16BE)
  • Binary
  • MTOM

Stockage

L’API XML prend en charge le traitement des documents stockés en tant que :

Une mémoire tampon XML est une représentation en mémoire structurée d’un document XML. Il s’agit d’une représentation plus efficace qu’un document encodé comme octets. Un document XML stocké dans une mémoire tampon XML peut être parcouru, lu ou écrit.

E/S

L’API XML n’effectuera jamais d’e/s, sauf si elle est demandée spécifiquement. En outre, toutes les e/s peuvent être lancées de manière asynchrone. Pour plus d’informations sur le traitement asynchrone avec l’API XML, consultez WsFillReader et WsFlushWriter .

Traitement en cours

L’API XML a trois niveaux distincts au niveau desquels le document peut être traité.

Un document peut être traité à un nœud à la fois. Cela offre la gestion la plus fine du contenu XML et fournit une fidélité complète des données du document. À ce niveau, les fonctions WsReadNode et WsWriteNode et WsCopyNode sont utilisées.

Le niveau de contrôle suivant est des API telles que WsReadStartElement, WsReadValue et WsReadEndElement. Ces API fournissent de nombreux genres de validation, ignorent l’espace blanc et les commentaires, et normalisent le texte et CDATA pour présenter le consommateur avec une vue plus simple du code XML.

Le niveau de contrôle le plus élevé consiste à utiliser l’API de sérialisation. Ces API sont basées sur un mappage entre les types de données C et XML, et peuvent lire ou écrire une structure en mémoire complexe dans XML et en retour avec une fonction unique comme WsWriteElement et WsReadElement.

Les API de canonisation XML peuvent être utilisées pour générer une forme canonique de code XML qui peut à son tour être utilisée pour générer des signatures de chiffrement sur du contenu XML.

Création d’un enregistreur

Pour créer et utiliser un enregistreur pour écrire dans une mémoire tampon :

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

Pour créer et utiliser un enregistreur pour écrire dans un flux :

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

Pour créer et utiliser un enregistreur pour écrire dans une _ _ mémoire tampon XML WS:

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

Dans tous les cas, il est possible d’inclure le retrait de propriété du _ _ writer _ _ XML de la propriété pour mettre en forme le code XML.

Écriture d'éléments

Pour écrire un élément dans un enregistreur :

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

Vous pouvez également utiliser les éléments suivants :

WsWriteArray                 // Write an array of primitive values as a series of repeated elements

Écriture de contenu

Pour écrire du contenu dans un élément ou un attribut, les éléments suivants peuvent être utilisés :

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

Les éléments suivants peuvent être utilisés pour écrire dans un document, mais ils ne peuvent pas être utilisés dans un attribut.

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

Les éléments suivants peuvent être utilisés pour écrire une section CDATA dans un document texte :

WsWriteStartCData            // Start a CDATA section in a text encoding
// Write Content
WsWriteEndCData              // End a CDATA section in text encoding

Divers

WsGetPrefixFromNamespace     // Find a prefix bound to a namespace

Création d’un lecteur

Pour créer et utiliser un lecteur pour lire à partir d’une mémoire tampon en mémoire :

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

Pour créer et utiliser un lecteur pour effectuer un lecteur à partir d’un flux :

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

Pour créer et utiliser un lecteur pour lire à partir d’une _ _ mémoire tampon XML WS:

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

Lecture d'éléments

Pour lire un élément d’un lecteur :

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

Vous pouvez également utiliser les éléments suivants :

WsReadArray                  // Read an array of primitive values as a series of repeated elements

Lecture du contenu

Pour lire le contenu d’un élément ou d’un attribut, les éléments suivants peuvent être utilisés :

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

Les éléments suivants peuvent être utilisés pour inspecter le nœud actuel sur lequel le lecteur est positionné :

WsGetReaderNode             // Get the current node

Utilisation d’une mémoire tampon

Lors de l’écriture dans une _ _ mémoire tampon XML WS , les éléments suivants peuvent être utilisés :

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

Lors de la lecture à partir d’une _ _ mémoire tampon XML WS , les éléments suivants peuvent être utilisés :

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

Les éléments suivants peuvent être utilisés pour modifier une _ _ mémoire tampon XML WS:


WsRemoveNode                 // Delete an element or text from a document

Autres

WsGetNamespaceFromPrefix     // Find a namespace bound to a prefix
WsGetXmlAttribute            // Find an "xml:space" or "xml:lang" attribute in scope