Compartilhar via

Função WsReadToStartElement (webservices.h)

  • Artigo

Avança o leitor para o próximo elemento inicial ignorando espaços em branco e comentários, se necessário. Opcionalmente, ele também pode verificar o localName e o namespace do elemento.

Sintaxe

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

O leitor que deve ler para o elemento start.

[in, optional] localName

O nome localName que o elemento deve ser. Se NULL, qualquer localName será permitido.

[in, optional] ns

O namespace que o elemento deve ser. Se FOR NULL, qualquer namespace será permitido.

found

Se especificado, isso indicará se um elemento foi encontrado e se o localName e o namespace, se também especificados, corresponderão. Se não for especificado e um elemento não for encontrado ou o localName e o namespace não corresponderem, ele retornará WS_E_INVALID_FORMAT. (Consulte Valores retornados dos Serviços Web do Windows.)

[in, optional] error

Especifica onde informações adicionais de erro devem ser armazenadas se a função falhar.

Retornar valor

Essa função pode retornar um desses valores.

Código de retorno Descrição
WS_E_INVALID_FORMAT
 Os dados de entrada não estavam no formato esperado ou não tinham o valor esperado.
WS_E_QUOTA_EXCEEDED
 Uma cota foi excedida.

Comentários

Considere o seguinte XML:

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

Os exemplos a seguir ilustram os comportamentos de WsReadToStartElement quando o leitor é posicionado em vários locais no 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 indicar que um elemento foi encontrado, WsReadStartElement ou WsReadNode poderá ser usado para mover o leitor além do elemento start para o conteúdo do elemento.

WsSkipNode pode ser usado para ignorar o elemento e todos os seus filhos deixando o leitor posicionado no WS_XML_NODE após o elemento final correspondente.

Essa função pode falhar por qualquer um dos motivos listados no WsReadNode.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 7 [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 R2 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho webservices.h
Biblioteca WebServices.lib
DLL WebServices.dll