Función WsReadToStartElement (webservices.h)

Avanza el lector al siguiente elemento de inicio omitiendo espacios en blanco y comentarios si es necesario. Opcionalmente, también puede comprobar el localName y el espacio de nombres del elemento.

Sintaxis

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

Parámetros

[in] reader

Lector que se va a leer en el elemento start.

[in, optional] localName

Nombre localName que debe ser el elemento. Si es NULL, se permite cualquier localName.

[in, optional] ns

Espacio de nombres que debe ser el elemento. Si es NULL, se permite cualquier espacio de nombres.

found

Si se especifica, esto indicará si se encuentra un elemento y el localName y el espacio de nombres, si también se especifica, coinciden. Si no se especifica y no se encuentra un elemento o el espacio de nombres localName y no coinciden, devolverá WS_E_INVALID_FORMAT. (Consulte Valores devueltos de servicios web de Windows).

[in, optional] error

Especifica dónde se debe almacenar información de error adicional si se produce un error en la función.

Valor devuelto

Esta función puede devolver uno de estos valores.

Comentarios

Tenga en cuenta el siguiente XML:

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

En los ejemplos siguientes se muestran los comportamientos de WsReadToStartElement cuando el lector se coloca en varios lugares 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>

Si WsReadToStartElement indica que se ha encontrado un elemento, se puede usar WsReadStartElement o WsReadNode para mover el lector más allá del elemento de inicio al contenido del elemento.

WsSkipNode se puede usar para omitir el elemento y todos sus elementos secundarios dejando el lector colocado en el WS_XML_NODE después del elemento final correspondiente.

Esta función puede producir un error por cualquiera de los motivos enumerados en WsReadNode.

Requisitos