Funzione WsAbandonMessage (webservices.h)

Ignora il resto di un messaggio specificato in un canale specificato.

Sintassi

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

Parametri

[in] channel

Puntatore a una struttura WS_CHANNEL che rappresenta il canale in cui viene letto o scritto il messaggio.

[in] message

Puntatore a una struttura WS_MESSAGE che rappresenta il messaggio da abbandonare. Deve essere lo stesso messaggio passato alla funzione WsWriteMessageStart o WsReadMessageStart .

[in, optional] error

Puntatore a una struttura WS_ERROR che riceve informazioni di errore aggiuntive se la funzione ha esito negativo.

Valore restituito

Se la funzione ha esito positivo, restituisce NO_ERROR; in caso contrario, restituisce un codice di errore HRESULT.

Codice restituito	Descrizione
WS_E_INVALID_OPERATION	Il canale non è nello stato WS_CHANNEL_STATE_OPEN o WS_CHANNEL_STATE_FAULTED. Per gli stati del canale, vedere l'enumerazione WS_CHANNEL_STATE .
E_INVALIDARG	Il messaggio specificato non è attualmente in lettura o scritto nel canale specificato.

Commenti

WsAbandonMessage viene usato per ignorare la lettura o scrivere il contenuto rimanente di un messaggio, consentendo la lettura o la scrittura del messaggio successivo per il canale. In questo senso, è un'alternativa alle funzioni WsReadMessageEnd o WsWriteMessageEnd, come illustrato nel diagramma dello stato seguente:

Per le operazioni di lettura, un'applicazione chiama in genere WsAbandonMessage quando non è necessario che l'applicazione continui a leggere i dati del messaggio, ad esempio se il messaggio non soddisfa i requisiti dell'applicazione. Questa funzione può essere usata anche se il messaggio contiene xml non formattato o se il lettore XML ha generato un errore durante la lettura del messaggio.

Se il canale viene trasmesso (vedere il valore WS_STREAMED_INPUT_TRANSFER_MODE dell'enumerazione WS_TRANSFER_MODE ), il resto dei dati dei messaggi trasmessi viene letto e eliminato automaticamente con la chiamata successiva a WsReadMessageStart o WsCloseChannel per il canale. Se il canale non viene trasmesso, i dati dei messaggi buffer non letti vengono semplicemente eliminati.

Per le operazioni di scrittura, un'applicazione chiama in genere WsAbandonMessage quando l'applicazione non può continuare a scrivere il messaggio perché ha rilevato un errore, ad esempio uno restituito dal writer XML o deve interrompere la generazione del messaggio per un altro motivo.

Se il canale viene trasmesso (vedere il valore WS_STREAMED_INPUT_TRANSFER_MODE dell'enumerazione WS_TRANSFER_MODE ), i dati del messaggio verranno troncati e potrebbero causare errori durante la lettura dalla parte remota. Se il canale non viene trasmesso, i dati memorizzati nel buffer per il messaggio vengono semplicemente eliminati (poiché non è mai stato trasmesso).

Questa funzione consente all'utente del canale di mantenere aperto il canale e inviare o ricevere messaggi aggiuntivi (ad esempio l'invio di un errore), anche se si è verificato un errore. Al contrario, WsAbortChannel causerà l'errore del canale. Un utilizzo tipico è innanzitutto quello di tentare di abbandonare il messaggio e inviare un errore. In caso contrario, il canale può essere interrotto.

Questa funzione non esegue alcun blocco di I/O.

Questa funzione è valida solo quando il canale si trova negli stati di WS_CHANNEL_STATE_OPEN o di WS_CHANNEL_STATE_FAULTED. Per gli stati del canale, vedere l'enumerazione WS_CHANNEL_STATE .

Il messaggio specificato deve essere il messaggio corrente da leggere o il messaggio corrente scritto per il canale specificato.

Se viene chiamato correttamente, questa funzione non avrà esito negativo (ad esempio, a causa della mancanza di risorse di sistema).

Requisiti

Requisito	Valore
Client minimo supportato	Windows 7 [app desktop | App UWP]
Server minimo supportato	Windows Server 2008 R2 [app desktop | App UWP]
Piattaforma di destinazione	Windows
Intestazione	webservices.h
Libreria	WebServices.lib
DLL	WebServices.dll