WsReadToStartElement-Funktion (webservices.h)

Bringt den Leser zum nächsten Startelement und überspringt bei Bedarf Leerzeichen und Kommentare. Optional können auch der localName und der Namespace des Elements überprüft werden.

Syntax

HRESULT WsReadToStartElement(
  [in]           WS_XML_READER       *reader,
  [in, optional] const WS_XML_STRING *localName,
  [in, optional] const WS_XML_STRING *ns,
                 BOOL                *found,
  [in, optional] WS_ERROR            *error
);

Parameter

[in] reader

Der Leser, der das Startelement lesen soll.

[in, optional] localName

Der localName-Name, den das Element sein soll. Bei NULL ist jeder localName zulässig.

[in, optional] ns

Der Namespace, der das Element sein soll. Bei NULL ist ein beliebiger Namespace zulässig.

found

Wenn angegeben, gibt dies an, ob ein Element gefunden wird und localName und Namespace übereinstimmen, sofern ebenfalls angegeben. Wenn nicht angegeben, und ein Element nicht gefunden wird oder localName und Namespace nicht übereinstimmen, wird WS_E_INVALID_FORMAT zurückgegeben. (Siehe Rückgabewerte für Windows-Webdienste.)

[in, optional] error

Gibt an, wo zusätzliche Fehlerinformationen gespeichert werden sollen, wenn die Funktion fehlschlägt.

Rückgabewert

Diese Funktion kann einen dieser Werte zurückgeben.

Hinweise

Betrachten Sie den folgenden XML-Code:

<!-- A purchase order -->
        <PurchaseOrder xmlns='http://tempuri.org'>
            <Item>
                Pencil
            </Item>
        </PurchaseOrder>

Die folgenden Beispiele veranschaulichen das Verhalten von WsReadToStartElement , wenn der Reader an verschiedenen Stellen im Dokument positioniert ist.

WS_XML_STRING purchaseOrder = WS_XML_STRING_VALUE("PurchaseOrder");
WS_XML_STRING item = WS_XML_STRING_VALUE("Item");
WS_XML_STRING ns = WS_XML_STRING("http://tempuri.org");
WS_ERROR* error = NULL;

// Example 1: Reader on comment, element has specified name and namespace, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, &purchaseOrder, &ns, NULL, error);
// hr = NOERROR, the reader is positioned on <PurchaseOrder>

// Example 2: Reader on comment, element has specified name and namespace, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, &purchaseOrder, &ns, found, error);
// hr = NOERROR, found = TRUE, the reader is positioned on <PurchaseOrder>

// Example 3: Reader on comment, element does not have specified name and namespace, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, &item, &ns, NULL, error);
// hr = WS_E_INVALID_FORMAT, the reader is faulted

// Example 4: Reader on comment, element does not have specified name and namespace, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, &item, &ns, &found, error);
// hr = NOERROR, found = FALSE, the reader is positioned on <PurchaseOrder>

// Example 5: Reader on comment, name and namespace not specified, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, &found, error);
// hr = NOERROR, found = TRUE, the reader is positioned on <PurchaseOrder>

// Example 6: Reader on </Item>, name and namespace not specified, found argument is not provided
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, NULL, error);
// hr = WS_E_INVALID_FORMAT, the reader is faulted

// Example 7: Reader on </Item>, name and namespace not specified, found argument is provided
BOOL found;
HRESULT hr = WsReadToStartElement(reader, NULL, NULL, &found, error);
// hr = NOERROR, found = FALSE, the reader is positioned on </Item>

Wenn WsReadToStartElement angibt, dass ein Element gefunden wurde, kann WsReadStartElement oder WsReadNode verwendet werden, um den Reader über das Startelement in den Inhalt des Elements zu verschieben.

WsSkipNode kann verwendet werden, um das Element und alle untergeordneten Elemente zu überspringen, damit der Leser auf der WS_XML_NODE dem entsprechenden Endelement folgt.

Diese Funktion kann aus einem der in WsReadNode aufgeführten Gründe fehlschlagen.

Anforderungen