Fungsi WsAbandonMessage (webservices.h)

Melewati sisa pesan tertentu pada saluran tertentu.

Sintaks

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

Parameter

[in] channel

Arahkan ke struktur WS_CHANNEL yang mewakili saluran tempat pesan dibaca atau ditulis.

[in] message

Arahkan ke struktur WS_MESSAGE yang mewakili pesan untuk ditinggalkan. Ini harus menjadi pesan yang sama yang diteruskan ke fungsi WsWriteMessageStart atau WsReadMessageStart .

[in, optional] error

Penunjuk ke struktur WS_ERROR yang menerima informasi kesalahan tambahan jika fungsi gagal.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan NO_ERROR; jika tidak, kode kesalahan HRESULT akan dikembalikan.

Menampilkan kode	Deskripsi
WS_E_INVALID_OPERATION	Saluran tidak dalam status WS_CHANNEL_STATE_OPEN atau WS_CHANNEL_STATE_FAULTED. (Untuk status saluran, lihat enumerasi WS_CHANNEL_STATE .)
E_INVALIDARG	Pesan yang ditentukan saat ini tidak sedang dibaca atau ditulis pada saluran yang ditentukan.

Keterangan

WsAbandonMessage digunakan untuk melompati membaca atau menulis konten pesan yang tersisa, memungkinkan pesan berikutnya agar saluran dibaca atau ditulis. Dalam hal ini, ini adalah alternatif untuk fungsi WsReadMessageEnd atau WsWriteMessageEnd , seperti yang ditunjukkan dalam diagram status berikut:

Untuk operasi baca, aplikasi biasanya memanggil WsAbandonMessage ketika tidak perlu bagi aplikasi untuk terus membaca data pesan, misalnya, jika pesan tidak memenuhi persyaratan aplikasi. Fungsi ini juga dapat digunakan jika pesan berisi XML yang salah bentuk atau jika pembaca XML telah menghasilkan kesalahan saat membaca pesan.

Jika saluran dialirkan (lihat nilai WS_STREAMED_INPUT_TRANSFER_MODE enumerasi WS_TRANSFER_MODE ), sisa data pesan yang dialirkan dibaca dan secara otomatis dibuang dengan panggilan berikutnya ke WsReadMessageStart atau WsCloseChannel untuk saluran. Jika saluran tidak dialirkan, data pesan buffer yang belum dibaca hanya dibuang.

Untuk operasi tulis, aplikasi biasanya memanggil WsAbandonMessage ketika aplikasi tidak dapat terus menulis pesan karena mengalami beberapa kesalahan, seperti yang dikembalikan oleh penulis XML, atau harus berhenti menghasilkan pesan karena alasan lain.

Jika saluran dialirkan (lihat nilai WS_STREAMED_INPUT_TRANSFER_MODE enumerasi WS_TRANSFER_MODE ), data pesan akan dipotong dan dapat mengakibatkan kesalahan saat dibaca oleh pihak jarak jauh. Jika saluran tidak dialirkan, data yang di-buffer untuk pesan hanya dibuang (karena tidak pernah ditransmisikan).

Fungsi ini memungkinkan pengguna saluran untuk menjaga saluran tetap terbuka dan mengirim atau menerima pesan tambahan (seperti mengirim kesalahan), meskipun terjadi kesalahan. Sebaliknya, WsAbortChannel akan menyebabkan saluran rusak. Penggunaan umum adalah pertama-tama untuk mencoba meninggalkan pesan dan mengirim kesalahan. Jika gagal, saluran dapat dibatalkan.

Fungsi ini tidak melakukan pemblokiran I/O.

Fungsi ini hanya valid ketika saluran berada dalam status WS_CHANNEL_STATE_OPEN atau WS_CHANNEL_STATE_FAULTED. (Untuk status saluran, lihat enumerasi WS_CHANNEL_STATE .)

Pesan yang ditentukan harus berupa pesan saat ini yang sedang dibaca atau pesan saat ini sedang ditulis untuk saluran yang ditentukan.

Jika dipanggil dengan benar, fungsi ini tidak akan gagal (misalnya, karena kurangnya sumber daya sistem).

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 7 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 R2 [aplikasi desktop | Aplikasi UWP]
Target Platform	Windows
Header	webservices.h
Pustaka	WebServices.lib
DLL	WebServices.dll