Função WsAbandonMessage (webservices.h)
Ignora o restante de uma mensagem especificada em um canal especificado.
Sintaxe
HRESULT WsAbandonMessage(
[in] WS_CHANNEL *channel,
[in] WS_MESSAGE *message,
[in, optional] WS_ERROR *error
);
Parâmetros
[in] channel
Ponteiro para uma estrutura WS_CHANNEL que representa o canal no qual a mensagem está sendo lida ou gravada.
[in] message
Ponteiro para uma estrutura WS_MESSAGE que representa a mensagem a ser abandonada. Essa deve ser a mesma mensagem que foi passada para a função WsWriteMessageStart ou WsReadMessageStart .
[in, optional] error
Ponteiro para uma estrutura WS_ERROR que recebe informações de erro adicionais se a função falhar.
Retornar valor
Se a função for bem-sucedida, ela retornará NO_ERROR; caso contrário, ele retornará um código de erro HRESULT.
| Código de retorno | Descrição |
|---|---|
|
O canal não está no estado WS_CHANNEL_STATE_OPEN ou WS_CHANNEL_STATE_FAULTED. (Para estados de canal, consulte a enumeração WS_CHANNEL_STATE .) |
|
A mensagem especificada não está sendo lida ou gravada no canal especificado. |
Comentários
WsAbandonMessage é usado para ignorar a leitura ou gravação do conteúdo restante de uma mensagem, permitindo que a próxima mensagem para o canal seja lida ou gravada. Nesse sentido, é uma alternativa às funções WsReadMessageEnd ou WsWriteMessageEnd , conforme mostrado no diagrama de estado a seguir:
Para operações de leitura, um aplicativo normalmente chama WsAbandonMessage quando é desnecessário que o aplicativo continue lendo os dados da mensagem, por exemplo, se a mensagem não atender aos requisitos do aplicativo. Essa função também poderá ser usada se a mensagem contiver XML malformado ou se o leitor XML tiver gerado um erro ao ler a mensagem.
Se o canal for transmitido (consulte o valor WS_STREAMED_INPUT_TRANSFER_MODE da enumeração WS_TRANSFER_MODE ), o restante dos dados da mensagem transmitida será lido e descartado automaticamente com a próxima chamada para WsReadMessageStart ou WsCloseChannel para o canal. Se o canal não for transmitido, os dados da mensagem não lida em buffer serão simplesmente descartados.
Para operações de gravação, um aplicativo normalmente chama WsAbandonMessage quando o aplicativo não pode continuar gravando a mensagem porque encontrou algum erro, como um retornado pelo gravador XML, ou deve parar de gerar a mensagem por algum outro motivo.
Se o canal for transmitido (consulte o valor WS_STREAMED_INPUT_TRANSFER_MODE da enumeração WS_TRANSFER_MODE ), os dados da mensagem serão truncados e poderão resultar em erros quando lidos pela parte remota. Se o canal não for transmitido, os dados armazenados em buffer da mensagem serão simplesmente descartados (já que nunca foram transmitidos).
Essa função permite que o usuário do canal mantenha o canal aberto e envie ou receba mensagens adicionais (como enviar uma falha), mesmo que tenha ocorrido um erro. Por outro lado, WsAbortChannel causará falha no canal. Um uso típico é primeiro tentar abandonar a mensagem e enviar uma falha. Se isso falhar, o canal poderá ser anulado.
Essa função não executa nenhuma E/S de bloqueio.
Essa função só é válida quando o canal está nos estados WS_CHANNEL_STATE_OPEN ou WS_CHANNEL_STATE_FAULTED. (Para estados de canal, consulte a enumeração WS_CHANNEL_STATE .)
A mensagem especificada deve ser a mensagem atual que está sendo lida ou a mensagem atual que está sendo gravada para o canal especificado.
Se chamado corretamente, essa função não falhará (por exemplo, devido à falta de recursos do sistema).
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 |