Função WsReceiveMessage (webservices.h)

Receba uma mensagem e desserialize o corpo da mensagem como um valor.

Sintaxe

HRESULT WsReceiveMessage(
  [in]           WS_CHANNEL                   *channel,
  [in]           WS_MESSAGE                   *message,
                 const WS_MESSAGE_DESCRIPTION **messageDescriptions,
  [in]           ULONG                        messageDescriptionCount,
  [in]           WS_RECEIVE_OPTION            receiveOption,
  [in]           WS_READ_OPTION               readBodyOption,
  [in, optional] WS_HEAP                      *heap,
                 void                         *value,
  [in]           ULONG                        valueSize,
                 ULONG                        *index,
  [in, optional] const WS_ASYNC_CONTEXT       *asyncContext,
  [in, optional] WS_ERROR                     *error
);

Parâmetros

[in] channel

O canal do qual receber.

[in] message

O objeto de mensagem usado para receber.

A mensagem deve estar em WS_MESSAGE_STATE_EMPTY estado.

messageDescriptions

Uma matriz de ponteiros para descrições de mensagens que especifica os metadados para os tipos esperados de mensagens.

[in] messageDescriptionCount

O número de itens na matriz messageDescriptions.

[in] receiveOption

Se a mensagem é necessária. Consulte WS_RECEIVE_OPTION para obter mais informações.

[in] readBodyOption

Se o elemento body é necessário e como alocar o valor.
Consulte WS_READ_OPTION para obter mais informações.

[in, optional] heap

O heap no qual armazenar os valores desserializados. Se o heap não for necessário para o tipo fornecido, esse parâmetro poderá ser NULL.

value

A interpretação desse parâmetro depende do WS_READ_OPTION.

Se WS_RECEIVE_OPTIONAL_MESSAGE for especificado para o parâmetro receiveOption e não houver mais mensagens disponíveis no canal, esse parâmetro não será tocado. Nesse caso, a função retorna WS_S_END. (Consulte Valores retornados dos Serviços Web do Windows.)

Se o bodyElementDescription do WS_MESSAGE_DESCRIPTION correspondente for NULL, esse parâmetro não será tocado. Nesse caso, o parâmetro não precisa ser especificado.

[in] valueSize

A interpretação desse parâmetro depende do WS_READ_OPTION.

index

Se WS_RECEIVE_OPTIONAL_MESSAGE for especificado para o parâmetro receiveOption e não houver mais mensagens disponíveis no canal, esse parâmetro não será alterado. Nesse caso, a função retornará WS_S_END.

Caso contrário, se a função for bem-sucedida, conterá o índice baseado em zero na matriz de descrições de mensagens que indicam qual correspondeu.

Esse parâmetro poderá ser NULL se o chamador não estiver interessado no valor (por exemplo, se houver apenas uma descrição da mensagem).

[in, optional] asyncContext

Informações sobre como invocar a função de forma assíncrona ou NULL se estiver invocando de forma síncrona.

[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_S_ASYNC	A operação assíncrona ainda está pendente.
WS_S_END	A opção de recebimento WS_RECEIVE_OPTIONAL_MESSAGE foi especificada e não há mais mensagens disponíveis para o canal.
WS_E_ENDPOINT_FAULT_RECEIVED	A mensagem recebida continha uma falha. A falha pode ser extraída do WS_ERROR usando WsGetErrorProperty.
WS_E_OPERATION_ABORTED	A operação foi anulada.
WS_E_INVALID_OPERATION	A operação não é permitida devido ao estado atual do objeto.
WS_E_ENDPOINT_NOT_FOUND	O ponto de extremidade remoto não existe ou não pôde ser localizado.
WS_E_ENDPOINT_ACCESS_DENIED	O acesso foi negado pelo ponto de extremidade remoto.
WS_E_ENDPOINT_DISCONNECTED	A conexão com o ponto de extremidade remoto foi encerrada.
WS_E_ENDPOINT_FAILURE	O ponto de extremidade remoto não pôde processar a solicitação.
WS_E_ENDPOINT_NOT_AVAILABLE	O ponto de extremidade remoto não está atualmente em serviço neste local.
WS_E_ENDPOINT_TOO_BUSY	O ponto de extremidade remoto não pode processar a solicitação devido à sobrecarga.
WS_E_ENDPOINT_UNREACHABLE	O ponto de extremidade remoto não estava acessível.
WS_E_INVALID_ENDPOINT_URL	A URL do endereço do ponto de extremidade é inválida.
WS_E_INVALID_FORMAT	Os dados de entrada não estavam no formato esperado ou não tinham o valor esperado.
WS_E_OPERATION_TIMED_OUT	A operação não foi concluída dentro do tempo alocado.
WS_E_PROXY_ACCESS_DENIED	O acesso foi negado pelo servidor proxy HTTP.
WS_E_PROXY_FAILURE	O servidor proxy HTTP não pôde processar a solicitação.
WS_E_QUOTA_EXCEEDED	Uma cota foi excedida.
WS_E_SECURITY_VERIFICATION_FAILURE	A verificação de segurança não foi bem-sucedida para os dados recebidos.
WS_E_SECURITY_SYSTEM_FAILURE	Falha em uma operação de segurança na estrutura dos Serviços Web do Windows.
WS_E_SECURITY_TOKEN_EXPIRED	Um token de segurança foi rejeitado pelo servidor porque expirou.
WS_E_PROXY_REQUIRES_BASIC_AUTH	O servidor proxy HTTP requer o esquema de autenticação HTTP 'basic'.
WS_E_PROXY_REQUIRES_DIGEST_AUTH	O servidor proxy HTTP requer o esquema de autenticação HTTP 'digest'.
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH	O servidor proxy HTTP requer o esquema de autenticação HTTP 'negotiate'.
WS_E_PROXY_REQUIRES_NTLM_AUTH	O servidor proxy HTTP requer o esquema de autenticação HTTP 'NTLM'.
WS_E_SERVER_REQUIRES_BASIC_AUTH	O ponto de extremidade remoto requer o esquema de autenticação HTTP 'básico'.
WS_E_SERVER_REQUIRES_DIGEST_AUTH	O ponto de extremidade remoto requer o esquema de autenticação HTTP 'digest'.
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH	O ponto de extremidade remoto requer o esquema de autenticação HTTP 'negotiate'.
WS_E_SERVER_REQUIRES_NTLM_AUTH	O ponto de extremidade remoto requer o esquema de autenticação HTTP 'NTLM'.
CERT_E_EXPIRED	Um certificado necessário não está dentro de seu período de validade ao verificar o relógio do sistema atual ou o carimbo de data/hora no arquivo assinado.
CERT_E_CN_NO_MATCH	O nome CN dos certificados não corresponde ao valor passado.
CERT_E_UNTRUSTEDROOT	Uma cadeia de certificados processada, mas encerrada em um certificado raiz que não é confiável pelo provedor de confiança.
CERT_E_WRONG_USAGE	O certificado não é válido para o uso solicitado.
CRYPT_E_REVOCATION_OFFLINE	A função de revogação não pôde verificar a revogação porque o servidor de revogação estava offline.
E_OUTOFMEMORY	Ficou sem memória.
E_INVALIDARG	Um ou mais argumentos são inválidos.
Outros erros	Essa função pode retornar outros erros não listados acima.

Comentários

Essa função usa metadados sobre os tipos de mensagem esperados para desserializar o corpo.
Os metadados são uma matriz de ponteiros para WS_MESSAGE_DESCRIPTIONs. Cada descrição da mensagem contém um valor de ação, que é usado para corresponder à ação da mensagem e um WS_ELEMENT_DESCRIPTION que fornece os metadados para o elemento body.

Quando os cabeçalhos de mensagem forem recebidos, a função examinará a matriz para encontrar uma correspondência com a ação. A primeira descrição da mensagem que corresponde é usada para desserializar o corpo e o índice baseado em zero dessa descrição de mensagem na matriz é retornado no parâmetro index out. Se a função for bem-sucedida, o parâmetro index out sempre será definido para indicar qual descrição da mensagem foi usada.

Para que uma descrição da mensagem corresponda, o valor da ação deve corresponder exatamente ao da mensagem. Se a ação no WS_MESSAGE_DESCRIPTION for NULL, a ação sempre corresponderá. Isso pode ser usado no caso em que não há nenhum cabeçalho de ação na mensagem recebida ou se o corpo é sempre o mesmo, independentemente de qual seja a ação.

Se o corpo estiver vazio, o campo bodyElementDescription do WS_MESSAGE_DESCRIPTION poderá ser NULL.

Se bodyElementDescription não for NULL, essa função desserializará o corpo, conforme descrito em WsReadBody.

Depois que uma mensagem for recebida, seus cabeçalhos poderão ser inspecionados usando WsGetHeader ou WsGetCustomHeader.

Requisitos

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