Mensagem (Serviços Web do Windows)

Uma mensagem é um objeto que encapsula dados transmitidos ou recebidos. A estrutura de uma mensagem é definida por SOAP e inclui um conjunto de cabeçalhos e um corpo. Os cabeçalhos são sempre armazenados em buffer na memória, mas o corpo é lido e gravado como uma API de streaming.

Diagram showing a message with the header being buffered and the body being streamed.

As mensagens têm um conjunto de propriedades que podem ser usadas para especificar configurações opcionais que controlam o comportamento de uma mensagem e para fornecer uma maneira de recuperar informações adicionais sobre mensagens recebidas (como informações de segurança). Consulte WS_MESSAGE_PROPERTY_ID para obter uma lista completa das propriedades da mensagem.

Uma mensagem é endereçada a um endereço do ponto de extremidade específico.

Um WS_FAULT é um tipo especial de conteúdo de mensagem usado para representar falhas retornadas de um ponto de extremidade remoto.

As mensagens passam por uma codificação que transforma o XML em um formato de fio linear antes de serem transmitidas.

Para obter mais informações sobre mensagens, consulte o tópico Visão geral da camada de canal.

Os exemplos a seguir ilustram o uso de mensagens em WWSAPI.

Exemplo Descrição
CustomHeaderExample Ilustra o uso de cabeçalhos de mensagem personalizados.
MessageEncodingExample Ilustra a codificação e a decodificação de uma mensagem.
ForwardMessageExample Ilustra o encaminhamento de uma mensagem.

 

Os seguintes elementos de API são usados com mensagens.

Retorno de Chamada Descrição
WS_MESSAGE_DONE_CALLBACK Notifica o chamador de que a mensagem concluiu o uso da estrutura WS_XML_READER fornecida à função WsReadEnvelopeStart ou da estrutura WS_XML_WRITER fornecida à função WsWriteEnvelopeStart.

 

Enumeração Descrição
WS_ADDRESSING_VERSION A versão da especificação usada para os cabeçalhos de endereçamento.
WS_ENVELOPE_VERSION A versão da especificação usada para a estrutura do envelope.
WS_HEADER_ATTRIBUTES Um conjunto de sinalizadores que representam os atributos SOAP mustUnderstand e relay de um cabeçalho.
WS_HEADER_TYPE O tipo do cabeçalho.
WS_MESSAGE_INITIALIZATION Especifica quais cabeçalhos WsInitializeMessage deve adicionar à mensagem.
WS_MESSAGE_PROPERTY_ID A ID de cada propriedade de mensagem.
WS_MESSAGE_STATE O estado da mensagem.

 

Função Descrição
WsAddressMessage Atribui um endereço de destino a uma mensagem.
WsCheckMustUnderstandHeaders Verifica se os cabeçalhos especificados foram adequadamente compreendidos pelo receptor.
WsCreateMessage Cria uma instância de um objeto WS_MESSAGE.
WsCreateMessageForChannel Cria uma mensagem apropriada para uso com um canal específico.
WsFillBody Garante que haja um número suficiente de bytes disponíveis em uma mensagem para leitura.
WsFlushBody Libera todos os dados acumulados do corpo da mensagem que foram gravados.
WsFreeMessage Libera o recurso de memória associado a uma mensagem.
WsGetCustomHeader Localiza o cabeçalho da mensagem definido pelo aplicativo e o desserializa.
WsGetHeader Localiza um cabeçalho padrão específico na mensagem e o desserializa.
WsGetHeaderAttributes Preenche um parâmetro ULONG com WS_HEADER_ATTRIBUTES do elemento do cabeçalho no qual o leitor está posicionado.
WsGetMessageProperty Recupera uma propriedade de objeto de mensagem especificada.
WsInitializeMessage Inicializa os cabeçalhos da mensagem em preparação para processamento.
WsMarkHeaderAsUnderstood Marca um cabeçalho conforme entendido pelo aplicativo.
WsReadBody Desserializa um valor do leitor de XML da mensagem.
WsReadEnvelopeEnd Lê os elementos de fechamento de uma mensagem.
WsReadEnvelopeStart Lê os cabeçalhos da mensagem e se prepara para ler os elementos do corpo.
WsRemoveCustomHeader Remove um cabeçalho personalizado da mensagem.
WsRemoveHeader Remove o objeto WS_HEADER_TYPE padrão de uma mensagem.
WsResetMessage Define o estado da mensagem de volta para WS_MESSAGE_STATE_EMPTY.
WsSetHeader Adiciona ou substitui o cabeçalho padrão especificado na mensagem.
WsWriteBody Grava um valor no corpo de uma mensagem.
WsWriteEnvelopeEnd Grava os elementos de fechamento de uma mensagem.
WsWriteEnvelopeStart Grava o início da mensagem, incluindo o conjunto atual de cabeçalhos da mensagem e se prepara para gravar os elementos do corpo.

 

Handle Descrição
WS_MESSAGE O tipo opaco usado para fazer referência a um objeto de mensagem.

 

Estrutura Descrição
WS_FAULT Um valor de falha transportado no corpo de uma mensagem que indica uma falha de processamento.
WS_FAULT_CODE Representa um código de falha.
WS_FAULT_REASON Contém uma explicação da falha.
WS_MESSAGE_PROPERTIES Especifica um conjunto de estruturas WS_MESSAGE_PROPERTY.
WS_MESSAGE_PROPERTY Especifica uma configuração específica da mensagem.