WsReadToStartElement, fonction (webservices.h)

Avance le lecteur vers l’élément de démarrage suivant en ignorant les espaces blancs et les commentaires si nécessaire. Si vous le souhaitez, il peut également vérifier le localName et l’espace de noms de l’élément .

Syntaxe

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

Paramètres

[in] reader

Lecteur qui doit lire l’élément start.

[in, optional] localName

Nom localName que l’élément doit être. Si la valeur est NULL, n’importe quel localName est autorisé.

[in, optional] ns

Espace de noms que l’élément doit être. Si la valeur est NULL, tout espace de noms est autorisé.

found

S’il est spécifié, cela indique si un élément est trouvé et si localName et l’espace de noms, s’ils sont également spécifiés, correspondent. S’il n’est pas spécifié et qu’un élément est introuvable ou que le localName et l’espace de noms ne correspondent pas, il retourne WS_E_INVALID_FORMAT. (Voir Valeurs de retour des services Web Windows.)

[in, optional] error

Spécifie l’emplacement où des informations d’erreur supplémentaires doivent être stockées en cas d’échec de la fonction.

Valeur retournée

Cette fonction peut retourner l’une de ces valeurs.

Remarques

Considérez le code XML suivant :

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

Les exemples suivants illustrent les comportements de WsReadToStartElement lorsque le lecteur est positionné à différents emplacements dans le document.

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>

Si WsReadToStartElement indique qu’un élément a été trouvé, WsReadStartElement ou WsReadNode peut être utilisé pour déplacer le lecteur au-delà de l’élément start dans le contenu de l’élément.

WsSkipNode peut être utilisé pour ignorer l’élément et tous ses enfants en laissant le lecteur positionné sur le WS_XML_NODE suivant l’élément de fin correspondant.

Cette fonction peut échouer pour l’une des raisons répertoriées dans WsReadNode.

Configuration requise