Функция WsAbandonMessage (webservices.h)

Пропускает оставшуюся часть указанного сообщения в указанном канале.

Синтаксис

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

Параметры

[in] channel

Указатель на структуру WS_CHANNEL , представляющую канал, по которому считывается или записывается сообщение.

[in] message

Указатель на структуру WS_MESSAGE , представляющую сообщение, которое необходимо прервать. Это должно быть то же сообщение, которое было передано функции WsWriteMessageStart или WsReadMessageStart .

[in, optional] error

Указатель на структуру WS_ERROR , которая получает дополнительные сведения об ошибке в случае сбоя функции.

Возвращаемое значение

Если функция завершается успешно, она возвращает NO_ERROR; в противном случае возвращается код ошибки HRESULT.

Код возврата	Описание
WS_E_INVALID_OPERATION	Канал не находится в состоянии WS_CHANNEL_STATE_OPEN или WS_CHANNEL_STATE_FAULTED. (Сведения о состояниях каналов см. в перечислении WS_CHANNEL_STATE .)
E_INVALIDARG	Указанное сообщение в настоящее время не считывается или не записывается в указанном канале.

Комментарии

WsAbandonMessage используется для пропуска чтения или записи оставшегося содержимого сообщения, что позволяет прочитать или записать следующее сообщение для канала. В этом отношении это альтернатива функциям WsReadMessageEnd или WsWriteMessageEnd , как показано на следующей схеме состояния:

Для операций чтения приложение обычно вызывает WsAbandonMessage , когда приложению не нужно продолжать чтение данных сообщения, например, если сообщение не соответствует требованиям приложения. Эту функцию также можно использовать, если сообщение содержит неправильный формат XML или если средство чтения XML создало ошибку при чтении сообщения.

При потоковой передаче канала (см. значение WS_STREAMED_INPUT_TRANSFER_MODE перечисления WS_TRANSFER_MODE ), остальные данные потокового сообщения считываются и автоматически удаляются при следующем вызове WsReadMessageStart или WsCloseChannel для канала. Если канал не передается в потоковую передачу, непрочитанные данные буферизованного сообщения просто удаляются.

Для операций записи приложение обычно вызывает WsAbandonMessage , если приложению не удается продолжить запись сообщения, так как возникла ошибка, например ошибка, возвращенная модулем записи XML, или оно должно прекратить создание сообщения по какой-либо другой причине.

Если канал передается потоком (см. значение WS_STREAMED_INPUT_TRANSFER_MODE перечисления WS_TRANSFER_MODE ), данные сообщения будут усечены и могут привести к ошибкам при чтении удаленной стороной. Если канал не передается в потоковую передачу, буферизированные данные для сообщения просто удаляются (так как они никогда не передавались).

Эта функция позволяет пользователю канала оставаться открытым и отправлять или получать дополнительные сообщения (например, отправку ошибки), даже если произошла ошибка. В отличие от этого, WsAbortChannel приведет к сбою канала. Обычно сначала пытается отказаться от сообщения и отправить ошибку. В случае сбоя канал может быть прерван.

Эта функция не выполняет блокирующие операции ввода-вывода.

Эта функция действительна, только если канал находится в состоянии WS_CHANNEL_STATE_OPEN или WS_CHANNEL_STATE_FAULTED. (Сведения о состояниях каналов см. в перечислении WS_CHANNEL_STATE .)

Указанное сообщение должно быть текущим считываемым или текущим сообщением, которое записывается для указанного канала.

При правильном вызове эта функция не завершится ошибкой (например, из-за нехватки системных ресурсов).

Требования

Требование	Значение
Минимальная версия клиента	Windows 7 [классические приложения | Приложения UWP]
Минимальная версия сервера	Windows Server 2008 R2 [классические приложения | Приложения UWP]
Целевая платформа	Windows
Header	webservices.h
Библиотека	WebServices.lib
DLL	WebServices.dll