Поделиться через

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

  • Статья

Получение сообщения и десериализация текста сообщения в качестве значения.

Синтаксис

HRESULT WsReceiveMessage(
  [in]           WS_CHANNEL                   *channel,
  [in]           WS_MESSAGE                   *message,
                 const WS_MESSAGE_DESCRIPTION **messageDescriptions,
  [in]           ULONG                        messageDescriptionCount,
  [in]           WS_RECEIVE_OPTION            receiveOption,
  [in]           WS_READ_OPTION               readBodyOption,
  [in, optional] WS_HEAP                      *heap,
                 void                         *value,
  [in]           ULONG                        valueSize,
                 ULONG                        *index,
  [in, optional] const WS_ASYNC_CONTEXT       *asyncContext,
  [in, optional] WS_ERROR                     *error
);

Параметры

[in] channel

Канал для получения.

[in] message

Объект сообщения, используемый для получения.

Сообщение должно находиться в WS_MESSAGE_STATE_EMPTY состоянии.

messageDescriptions

Массив указателей на описания сообщений, указывающий метаданные для ожидаемых типов сообщений.

[in] messageDescriptionCount

Количество элементов в массиве messageDescriptions.

[in] receiveOption

Является ли сообщение обязательным. Дополнительные сведения см. в разделе WS_RECEIVE_OPTION .

[in] readBodyOption

Требуется ли элемент body и как выделить значение.
Дополнительные сведения см. в разделе WS_READ_OPTION .

[in, optional] heap

Куча для хранения десериализованных значений. Если куча не требуется для заданного типа, этот параметр может иметь значение NULL.

value

Интерпретация этого параметра зависит от WS_READ_OPTION.

Если для параметра receiveOption указано WS_RECEIVE_OPTIONAL_MESSAGE и больше нет доступных сообщений в канале, этот параметр не касается. В этом случае функция возвращает WS_S_END. (См. раздел Возвращаемые значения веб-служб Windows.)

Если bodyElementDescription совпадающего WS_MESSAGE_DESCRIPTION имеет значение NULL, то этот параметр не касается. В этом случае указывать параметр не нужно.

[in] valueSize

Интерпретация этого параметра зависит от WS_READ_OPTION.

index

Если для параметра receiveOption задано WS_RECEIVE_OPTIONAL_MESSAGE и больше нет доступных сообщений в канале, этот параметр не будет тронут. В этом случае функция вернет WS_S_END.

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

Этот параметр может иметь значение NULL , если вызывающий объект не заинтересован в значении (например, если имеется только одно описание сообщения).

[in, optional] asyncContext

Сведения об асинхронном вызове функции или значении NULL при синхронном вызове.

[in, optional] error

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

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

Эта функция может возвращать одно из этих значений.

Код возврата Описание
WS_S_ASYNC
 Асинхронная операция по-прежнему находится в состоянии ожидания.
WS_S_END
 Параметр получения WS_RECEIVE_OPTIONAL_MESSAGE указан, и для канала больше нет доступных сообщений.
WS_E_ENDPOINT_FAULT_RECEIVED
 Полученное сообщение содержит ошибку. Ошибку можно извлечь из WS_ERROR с помощью WsGetErrorProperty.
WS_E_OPERATION_ABORTED
 Операция была прервана.
WS_E_INVALID_OPERATION
 Операция не разрешена из-за текущего состояния объекта .
WS_E_ENDPOINT_NOT_FOUND
 Удаленная конечная точка не существует или не может быть найдена.
WS_E_ENDPOINT_ACCESS_DENIED
 Удаленная конечная точка запретила доступ.
WS_E_ENDPOINT_DISCONNECTED
 Подключение к удаленной конечной точке было прервано.
WS_E_ENDPOINT_FAILURE
 Удаленной конечной точке не удалось обработать запрос.
WS_E_ENDPOINT_NOT_AVAILABLE
 Удаленная конечная точка в настоящее время не обслуживается в этом расположении.
WS_E_ENDPOINT_TOO_BUSY
 Удаленная конечная точка не может обработать запрос из-за перегрузки.
WS_E_ENDPOINT_UNREACHABLE
 Удаленная конечная точка недоступна.
WS_E_INVALID_ENDPOINT_URL
 Недопустимый URL-адрес конечной точки.
WS_E_INVALID_FORMAT
 Входные данные не были в ожидаемом формате или не имели ожидаемого значения.
WS_E_OPERATION_TIMED_OUT
 Операция не была завершена в отведенное время.
WS_E_PROXY_ACCESS_DENIED
 Прокси-сервер HTTP отказал в доступе.
WS_E_PROXY_FAILURE
 Прокси-серверу HTTP не удалось обработать запрос.
WS_E_QUOTA_EXCEEDED
 Превышена квота.
WS_E_SECURITY_VERIFICATION_FAILURE
 Проверка безопасности не прошла успешно для полученных данных.
WS_E_SECURITY_SYSTEM_FAILURE
 Сбой операции безопасности в платформе веб-служб Windows.
WS_E_SECURITY_TOKEN_EXPIRED
 Маркер безопасности был отклонен сервером, так как срок его действия истек.
WS_E_PROXY_REQUIRES_BASIC_AUTH
 Для прокси-сервера HTTP требуется базовая схема проверки подлинности HTTP.
WS_E_PROXY_REQUIRES_DIGEST_AUTH
 Для прокси-сервера HTTP требуется схема проверки подлинности HTTP "digest".
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
 Для прокси-сервера HTTP требуется схема проверки подлинности HTTP negotiate.
WS_E_PROXY_REQUIRES_NTLM_AUTH
 Для прокси-сервера HTTP требуется схема проверки подлинности HTTP NTLM.
WS_E_SERVER_REQUIRES_BASIC_AUTH
 Для удаленной конечной точки требуется базовая схема проверки подлинности HTTP.
WS_E_SERVER_REQUIRES_DIGEST_AUTH
 Для удаленной конечной точки требуется схема проверки подлинности HTTP "digest".
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
 Для удаленной конечной точки требуется схема проверки подлинности HTTP negotiate.
WS_E_SERVER_REQUIRES_NTLM_AUTH
 Для удаленной конечной точки требуется схема проверки подлинности HTTP NTLM.
CERT_E_EXPIRED
 При проверке на соответствие текущим системным часам или метке времени в подписанном файле обязательный сертификат не является сроком действия.
CERT_E_CN_NO_MATCH
 Имя cn certificates не соответствует переданное значение.
CERT_E_UNTRUSTEDROOT
 Цепочка сертификатов обрабатывается, но завершается в корневом сертификате, который не является доверенным поставщиком доверия.
CERT_E_WRONG_USAGE
 Сертификат не действителен для запрошенного применения.
CRYPT_E_REVOCATION_OFFLINE
 Функция отзыва не смогла проверить отзыв, потому что сервер отзыва был отключен.
E_OUTOFMEMORY
 Не хватает памяти.
E_INVALIDARG
 Один или несколько аргументов недопустимы.
Другие ошибки
Эта функция может возвращать другие ошибки, не перечисленные выше.

Комментарии

Эта функция использует метаданные об ожидаемых типах сообщений для десериализации текста.
Метаданные представляют собой массив указателей на WS_MESSAGE_DESCRIPTION. Каждое описание сообщения содержит значение действия, которое используется для сопоставления с действием сообщения, и WS_ELEMENT_DESCRIPTION , предоставляющий метаданные для элемента body.

После получения заголовков сообщений функция сканирует массив, чтобы найти совпадение с действием. Первое соответствующее описание сообщения используется для десериализации текста, а отсчитываемый от нуля индекс этого описания сообщения в массиве возвращается в параметре index out. Если функция выполнена успешно, всегда будет задан параметр index out, указывающий, какое описание сообщения было использовано.

Чтобы описание сообщения соответствовало, значение действия должно точно соответствовать значению сообщения. Если действие в WS_MESSAGE_DESCRIPTION имеет значение NULL, то действие всегда совпадает. Это можно использовать в случае, если в полученном сообщении нет заголовка действия или если текст всегда один и тот же, независимо от того, какое действие является.

Если ожидается, что текст будет пустым, поле bodyElementDescription WS_MESSAGE_DESCRIPTION может иметь значение NULL.

Если bodyElementDescription не равно NULL, эта функция десериализует тело, как описано в WsReadBody.

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

Требования

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