WsAbandonMessage, fonction (webservices.h)

Ignore le reste d’un message spécifié sur un canal spécifié.

Syntaxe

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

Paramètres

[in] channel

Pointeur vers une structure WS_CHANNEL représentant le canal sur lequel le message est lu ou écrit.

[in] message

Pointeur vers une structure WS_MESSAGE représentant le message à abandonner. Il doit s’agir du même message que celui qui a été passé à la fonction WsWriteMessageStart ou WsReadMessageStart .

[in, optional] error

Pointeur vers une structure de WS_ERROR qui reçoit des informations d’erreur supplémentaires en cas d’échec de la fonction.

Valeur retournée

Si la fonction réussit, elle retourne NO_ERROR ; sinon, il retourne un code d’erreur HRESULT.

Code de retour	Description
WS_E_INVALID_OPERATION	Le canal n’est pas à l’état WS_CHANNEL_STATE_OPEN ou WS_CHANNEL_STATE_FAULTED. (Pour connaître les états du canal, consultez l’énumération WS_CHANNEL_STATE .)
E_INVALIDARG	Le message spécifié n’est pas en cours de lecture ou d’écriture sur le canal spécifié.

Remarques

WsAbandonMessage permet d’ignorer la lecture ou l’écriture du contenu restant d’un message, ce qui permet de lire ou d’écrire le message suivant pour le canal. À cet égard, il s’agit d’une alternative aux fonctions WsReadMessageEnd ou WsWriteMessageEnd , comme illustré dans le diagramme d’état suivant :

Pour les opérations de lecture, une application appelle généralement WsAbandonMessage lorsqu’il n’est pas nécessaire pour l’application de continuer à lire les données de message, par exemple, si le message ne répond pas aux exigences de l’application. Cette fonction peut également être utilisée si le message contient du code XML mal formé ou si le lecteur XML a généré une erreur lors de la lecture du message.

Si le canal est diffusé en continu (consultez la valeur WS_STREAMED_INPUT_TRANSFER_MODE de l’énumération WS_TRANSFER_MODE ), le reste des données de message diffusées est lu et automatiquement ignoré lors de l’appel suivant à WsReadMessageStart ou WsCloseChannel pour le canal. Si le canal n’est pas diffusé en continu, les données de message tampon non lues sont simplement ignorées.

Pour les opérations d’écriture, une application appelle généralement WsAbandonMessage lorsque l’application ne peut pas continuer à écrire le message, car elle a rencontré une erreur, telle qu’une erreur renvoyée par l’enregistreur XML, ou doit cesser de générer le message pour une autre raison.

Si le canal est diffusé en continu (voir la valeur WS_STREAMED_INPUT_TRANSFER_MODE de l’énumération WS_TRANSFER_MODE ), les données de message sont tronquées et peuvent entraîner des erreurs lors de la lecture par la partie distante. Si le canal n’est pas diffusé en continu, les données mises en mémoire tampon pour le message sont simplement ignorées (car elles n’ont jamais été transmises).

Cette fonction permet à l’utilisateur du canal de maintenir le canal ouvert et d’envoyer ou de recevoir des messages supplémentaires (par exemple, l’envoi d’une erreur), même si une erreur s’est produite. En revanche, WsAbortChannel provoque la défaillance du canal. Une utilisation classique consiste d’abord à essayer d’abandonner le message et d’envoyer une erreur. En cas d’échec, le canal peut être abandonné.

Cette fonction n’effectue aucune E/S bloquante.

Cette fonction n’est valide que lorsque le canal est dans les états WS_CHANNEL_STATE_OPEN ou WS_CHANNEL_STATE_FAULTED. (Pour connaître les états du canal, consultez l’énumération WS_CHANNEL_STATE .)

Le message spécifié doit être le message en cours de lecture ou le message en cours d’écriture pour le canal spécifié.

Si elle est appelée correctement, cette fonction n’échoue pas (par exemple, en raison d’un manque de ressources système).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 7 [applications de bureau | Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 R2 [applications de bureau | Applications UWP]
Plateforme cible	Windows
En-tête	webservices.h
Bibliothèque	WebServices.lib
DLL	WebServices.dll