Compartilhar via

enumeração WS_READ_OPTION (webservices.h)

  • Artigo

Especifica se um valor é necessário e como o valor deve ser alocado.

Syntax

typedef enum {
  WS_READ_REQUIRED_VALUE = 1,
  WS_READ_REQUIRED_POINTER = 2,
  WS_READ_OPTIONAL_POINTER = 3,
  WS_READ_NILLABLE_POINTER = 4,
  WS_READ_NILLABLE_VALUE = 5
} WS_READ_OPTION;

Constantes

 
WS_READ_REQUIRED_VALUE
Valor: 1
A opção especifica que o valor deve existir no conteúdo XML.


O chamador deve especificar o armazenamento para ler o tipo de nível superior.


O tamanho do armazenamento especificado pelo chamador varia de acordo com o tipo
sendo desserializado, da seguinte maneira:

  • Para primitivos (como WS_INT32_TYPE), o armazenamento deve
    ser do tamanho do primitivo. Nesse caso, o heap não precisa ser especificado.

  • Para estruturas (se o usuário definiu as que usam WS_STRUCT_TYPE,
    ou predefinidos como WS_STRING), o armazenamento deve ser o
    tamanho exato da estrutura.
    Observe que os campos da estrutura que apontam para outros dados ainda são necessários para
    ser alocado do WS_HEAP. Se nenhum campo existir para o
    estrutura específica e, em seguida, o heap não precisa ser especificado.




Tipos de ponteiro (WS_WSZ_TYPE e WS_XML_BUFFER_TYPE),
pode não ser usado com WS_READ_REQUIRED_VALUE. O WS_READ_REQUIRED_POINTER
em vez disso, o valor deve ser usado.


Se o valor não estiver presente no XML que está sendo lido,
um erro de WS_E_INVALID_FORMAT será retornado.
(Consulte Valores retornados dos Serviços Web do Windows.)
WS_READ_REQUIRED_POINTER
Valor: 2
A opção especifica que o valor deve existir no conteúdo XML.


O valor desserializado é sempre alocado no WS_HEAP, independentemente de seu tamanho.
O ponteiro para o valor desserializado é retornado. Ao usar essa opção,
o chamador deve passar o endereço de um ponteiro e o tamanho de um ponteiro,
independentemente do tipo que está sendo desserializado.


Se o valor não estiver presente, um erro será retornado.
NULL nunca será retornado quando essa opção for usada. Se a opção
value é opcional, use WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Valor: 3
A opção especifica que o valor não precisa existir no conteúdo XML.


O valor desserializado é sempre alocado no WS_HEAP, independentemente de seu tamanho.
O ponteiro para o valor desserializado é retornado. Ao usar essa opção,
o chamador deve passar o endereço de um ponteiro e o tamanho de um ponteiro,
independentemente do tipo que está sendo desserializado.


Se o valor não estiver presente no XML que está sendo lido, a função será
bem-sucedido e NULL será retornado para o valor .


Um aplicativo que usa essa opção deve ter cuidado para marcar para NULL antes de acessar o valor.
Se um valor NULL nunca for esperado, use WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Valor: 4
A opção especifica que o valor pode ser nulo ou ausente no conteúdo XML.


O valor desserializado é sempre alocado no WS_HEAP, independentemente de seu tamanho.
O ponteiro para o valor desserializado é retornado. Ao usar essa opção,
o chamador deve passar o endereço de um ponteiro e o tamanho de um ponteiro,
independentemente do tipo que está sendo desserializado.


Se o elemento estiver nulo ou ausente no XML que está sendo lido, a função terá êxito e
um ponteiro NULL será retornado.
Se o elemento não for zero no XML que está sendo lido, o valor será retornado normalmente.


Um aplicativo que usa essa opção deve ter cuidado para marcar para NULL antes de acessar o valor.
Se um valor NULL nunca for esperado, use WS_READ_REQUIRED_POINTER.


Não há suporte para essa opção em combinação com WS_TYPE_MAPPING em APIs
que lê XML, incluindo chamadas WsReadType e WsReadElement .
WS_READ_NILLABLE_VALUE
Valor: 5
A opção especifica que o valor pode ser nulo ou ausente no conteúdo XML.


O chamador deve especificar o armazenamento para ler o tipo de nível superior.


Se o elemento XML estiver nulo ou ausente, um valor zero será retornado. Se o elemento XML for
não nulo e, em seguida, o valor é desserializado normalmente.


Não há suporte para essa opção em combinação com WS_TYPE_MAPPING em APIs
que lê XML, incluindo chamadas WsReadType e WsReadElement .


Essa opção só tem suporte para os seguintes tipos, listados abaixo,
que têm uma maneira intrínseca de representar um valor nulo. Confira a documentação
para cada tipo para obter informações sobre como nil é representado.

Comentários

Cada WS_READ_OPTION discute quando um objeto WS_HEAP deve ser especificado. Dependendo da função, ainda pode ser possível passar um parâmetro de heap NULL nesse caso; consulte a documentação da função específica para obter detalhes sobre se um heap padrão será usado se o parâmetro heap for NULL.

Veja a seguir as coisas a serem consideradas ao desserializar valores em um objeto heap (WS_HEAP):

  • Os valores desserializados permanecem alocados até que o heap seja liberado (WsFreeHeap) ou redefinido (WsResetHeap).
  • Cada vez que os valores são desserializados, eles são acrescentados ao heap (em vez de substituir os valores existentes).
  • Se forem encontrados erros durante a função de desserialização e a função falhar, a memória alocada do objeto heap até que o erro não seja liberado.
  • O tamanho do heap pode ser usado para limitar as alocações totais feitas durante a desserialização. O tamanho máximo do heap pode ser determinado da seguinte maneira:
    • Determine o tamanho máximo, em bytes, de cada valor que será alocado no heap durante a desserialização. Lembre-se de levar em conta que tamanhos de estruturas de dados desserializadas podem variar de acordo com a plataforma.
    • Cada matriz é considerada um valor. Observe que o tamanho real de um item na matriz pode ser afetado pelo alinhamento necessário do item.
    • Arredondar o tamanho máximo de cada valor para um limite de 16 bytes.

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]
Cabeçalho webservices.h