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.

Código devuelto	Descripción
WS_E_INVALID_FORMAT	Los datos de entrada no tenían el formato esperado o no tenían el valor esperado.
WS_E_QUOTA_EXCEEDED	Se superó una cuota.

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

Requisito	Value
Cliente mínimo compatible	Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	webservices.h
Library	WebServices.lib
Archivo DLL	WebServices.dll