Funzione WsReadToStartElement (webservices.h)

Articolo
03/09/2024

Sposta il lettore all'elemento iniziale successivo ignorando gli spazi vuoti e i commenti, se necessario. Facoltativamente, può anche verificare localName e lo spazio dei nomi dell'elemento.

Sintassi

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
);

Parametri

[in] reader

Lettore da leggere all'elemento iniziale.

[in, optional] localName

Nome localName che l'elemento deve essere. Se NULL, è consentito qualsiasi localName.

[in, optional] ns

Spazio dei nomi che l'elemento deve essere. Se NULL, è consentito qualsiasi spazio dei nomi.

found

Se specificato, verrà indicato se viene trovato un elemento e localName e lo spazio dei nomi, se specificato anche, corrispondenze. Se non specificato, e un elemento non viene trovato o lo spazio dei nomi localName e lo spazio dei nomi non corrispondono, restituirà WS_E_INVALID_FORMAT. Vedere Valori restituiti di Servizi Web Windows.

[in, optional] error

Specifica dove archiviare informazioni aggiuntive sull'errore se la funzione ha esito negativo.

Valore restituito

Questa funzione può restituire uno di questi valori.

Codice restituito	Descrizione
WS_E_INVALID_FORMAT	I dati di input non erano nel formato previsto o non hanno il valore previsto.
WS_E_QUOTA_EXCEEDED	È stata superata una quota.

Commenti

Si consideri il codice XML seguente:

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

Negli esempi seguenti vengono illustrati i comportamenti di WsReadToStartElement quando il lettore viene posizionato in varie posizioni del documento.

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>

Se WsReadToStartElement indica che è stato trovato un elemento, è possibile usare WsReadStartElement o WsReadNode per spostare il lettore oltre l'elemento iniziale nel contenuto dell'elemento.

WsSkipNode può essere usato per ignorare l'elemento e tutti i relativi elementi figlio lasciando il lettore posizionato sul WS_XML_NODE dopo l'elemento finale corrispondente.

Questa funzione può non riuscire per uno dei motivi elencati in WsReadNode.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [app desktop \| App UWP]
Server minimo supportato	Windows Server 2008 R2 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	webservices.h
Libreria	WebServices.lib
DLL	WebServices.dll

Condividi tramite