Función WsAbandonMessage (webservices.h)

Omite el resto de un mensaje especificado en un canal especificado.

Sintaxis

HRESULT WsAbandonMessage(
  [in]           WS_CHANNEL *channel,
  [in]           WS_MESSAGE *message,
  [in, optional] WS_ERROR   *error
);

Parámetros

[in] channel

Puntero a una estructura de WS_CHANNEL que representa el canal en el que se está leyendo o escribiendo el mensaje.

[in] message

Puntero a una estructura de WS_MESSAGE que representa el mensaje que se va a abandonar. Debe ser el mismo mensaje que se pasó a la función WsWriteMessageStart o WsReadMessageStart .

[in, optional] error

Puntero a una estructura de WS_ERROR que recibe información de error adicional si se produce un error en la función.

Valor devuelto

Si la función se realiza correctamente, devuelve NO_ERROR; de lo contrario, devuelve un código de error HRESULT.

Código devuelto	Descripción
WS_E_INVALID_OPERATION	El canal no está en el estado WS_CHANNEL_STATE_OPEN o WS_CHANNEL_STATE_FAULTED. (Para los estados del canal, consulte la enumeración WS_CHANNEL_STATE ).
E_INVALIDARG	El mensaje especificado no se está leyendo ni escribiendo actualmente en el canal especificado.

Comentarios

WsAbandonMessage se usa para omitir la lectura o escritura del contenido restante de un mensaje, lo que permite que el siguiente mensaje del canal se lea o escriba. A este respecto, es una alternativa a las funciones WsReadMessageEnd o WsWriteMessageEnd , como se muestra en el diagrama de estado siguiente:

En el caso de las operaciones de lectura, una aplicación normalmente llama a WsAbandonMessage cuando no es necesario que la aplicación siga leyendo los datos del mensaje, por ejemplo, si el mensaje no cumple los requisitos de la aplicación. Esta función también se puede usar si el mensaje contiene XML con formato incorrecto o si el lector XML ha generado un error al leer el mensaje.

Si el canal se transmite (vea el valor WS_STREAMED_INPUT_TRANSFER_MODE de la enumeración WS_TRANSFER_MODE ), el resto de los datos del mensaje transmitido se lee y descarta automáticamente con la siguiente llamada a WsReadMessageStart o WsCloseChannel para el canal. Si el canal no se transmite, los datos del mensaje almacenados en búfer no leídos simplemente se descartan.

En el caso de las operaciones de escritura, una aplicación normalmente llama a WsAbandonMessage cuando la aplicación no puede seguir escribiendo el mensaje porque ha encontrado algún error, como uno devuelto por el escritor XML, o debe dejar de generar el mensaje por algún otro motivo.

Si el canal se transmite (vea el valor WS_STREAMED_INPUT_TRANSFER_MODE de la enumeración de WS_TRANSFER_MODE ), los datos del mensaje se truncarán y pueden producir errores cuando lo lea la parte remota. Si el canal no se transmite, los datos almacenados en búfer del mensaje se descartan simplemente (ya que nunca se transmitieron).

Esta función permite al usuario del canal mantener el canal abierto y enviar o recibir mensajes adicionales (por ejemplo, enviar un error), aunque se haya producido un error. Por el contrario, WsAbortChannel hará que se produzca un error en el canal. Un uso típico es primero intentar abandonar el mensaje y enviar un error. Si se produce un error, se puede anular el canal.

Esta función no realiza ninguna E/S de bloqueo.

Esta función solo es válida cuando el canal está en los estados WS_CHANNEL_STATE_OPEN o WS_CHANNEL_STATE_FAULTED. (Para los estados del canal, consulte la enumeración WS_CHANNEL_STATE ).

El mensaje especificado debe ser el mensaje actual que se está leyendo o el mensaje actual que se está escribiendo para el canal especificado.

Si se llama correctamente, esta función no producirá un error (por ejemplo, debido a la falta de recursos del sistema).

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	webservices.h
Library	WebServices.lib
Archivo DLL	WebServices.dll