Función WsReceiveMessage (webservices.h)

  • Artículo

Reciba un mensaje y deserialice el cuerpo del mensaje como un valor.

Sintaxis

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
);

Parámetros

[in] channel

Canal desde el que se va a recibir.

[in] message

Objeto de mensaje que se usa para recibir.

El mensaje debe estar en WS_MESSAGE_STATE_EMPTY estado.

messageDescriptions

Matriz de punteros a descripciones de mensajes que especifica los metadatos de los tipos esperados de mensajes.

[in] messageDescriptionCount

Número de elementos de la matriz messageDescriptions.

[in] receiveOption

Indica si se requiere el mensaje. Consulte WS_RECEIVE_OPTION para obtener más información.

[in] readBodyOption

Indica si se requiere el elemento body y cómo asignar el valor.
Consulte WS_READ_OPTION para obtener más información.

[in, optional] heap

Montón en el que se almacenarán los valores deserializados. Si el montón no es necesario para el tipo especificado, este parámetro puede ser NULL.

value

La interpretación de este parámetro depende del WS_READ_OPTION.

Si se especifica WS_RECEIVE_OPTIONAL_MESSAGE para el parámetro receiveOption y no hay más mensajes disponibles en el canal, este parámetro no se toca. En este caso, la función devuelve WS_S_END. (Consulte Valores devueltos de servicios web de Windows).

Si bodyElementDescription del WS_MESSAGE_DESCRIPTION coincidente es NULL, este parámetro no se toca. En este caso, no es necesario especificar el parámetro .

[in] valueSize

La interpretación de este parámetro depende del WS_READ_OPTION.

index

Si se especifica WS_RECEIVE_OPTIONAL_MESSAGE para el parámetro receiveOption y no hay más mensajes disponibles en el canal, este parámetro no se modifica. En este caso, la función devolverá WS_S_END.

De lo contrario, si la función se ejecuta correctamente, contendrá el índice de base cero en la matriz de descripciones del mensaje que indica cuál coincide.

Este parámetro puede ser NULL si el autor de la llamada no está interesado en el valor (por ejemplo, si solo hay una descripción del mensaje).

[in, optional] asyncContext

Información sobre cómo invocar la función de forma asincrónica o NULL si invoca de forma sincrónica.

[in, optional] error

Especifica dónde se debe almacenar información de error adicional si se produce un error en la función.

Valor devuelto

Esta función puede devolver uno de estos valores.

Código devuelto Descripción
WS_S_ASYNC
 La operación asincrónica sigue pendiente.
WS_S_END
 Se especificó la opción de recepción WS_RECEIVE_OPTIONAL_MESSAGE y no hay más mensajes disponibles para el canal.
WS_E_ENDPOINT_FAULT_RECEIVED
 El mensaje recibido contenía un error. El error se puede extraer del WS_ERROR mediante WsGetErrorProperty.
WS_E_OPERATION_ABORTED
 Se anuló la operación.
WS_E_INVALID_OPERATION
 No se permite la operación debido al estado actual del objeto .
WS_E_ENDPOINT_NOT_FOUND
 El punto de conexión remoto no existe o no se pudo encontrar.
WS_E_ENDPOINT_ACCESS_DENIED
 El punto de conexión remoto denegó el acceso.
WS_E_ENDPOINT_DISCONNECTED
 Se finalizó la conexión con el punto de conexión remoto.
WS_E_ENDPOINT_FAILURE
 El punto de conexión remoto no pudo procesar la solicitud.
WS_E_ENDPOINT_NOT_AVAILABLE
 El punto de conexión remoto no está actualmente en servicio en esta ubicación.
WS_E_ENDPOINT_TOO_BUSY
 El punto de conexión remoto no puede procesar la solicitud debido a la sobrecarga.
WS_E_ENDPOINT_UNREACHABLE
 No se pudo acceder al punto de conexión remoto.
WS_E_INVALID_ENDPOINT_URL
 La dirección URL de la dirección del punto de conexión no es válida.
WS_E_INVALID_FORMAT
 Los datos de entrada no tenían el formato esperado o no tenían el valor esperado.
WS_E_OPERATION_TIMED_OUT
 La operación no se completó dentro del tiempo asignado.
WS_E_PROXY_ACCESS_DENIED
 El servidor proxy HTTP denegó el acceso.
WS_E_PROXY_FAILURE
 El servidor proxy HTTP no pudo procesar la solicitud.
WS_E_QUOTA_EXCEEDED
 Se superó una cuota.
WS_E_SECURITY_VERIFICATION_FAILURE
 La comprobación de seguridad no se realizó correctamente para los datos recibidos.
WS_E_SECURITY_SYSTEM_FAILURE
 Error en una operación de seguridad en el marco de servicios web de Windows.
WS_E_SECURITY_TOKEN_EXPIRED
 El servidor rechazó un token de seguridad porque ha expirado.
WS_E_PROXY_REQUIRES_BASIC_AUTH
 El servidor proxy HTTP requiere el esquema de autenticación HTTP "básico".
WS_E_PROXY_REQUIRES_DIGEST_AUTH
 El servidor proxy HTTP requiere el esquema de autenticación HTTP 'digest'.
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
 El servidor proxy HTTP requiere el esquema de autenticación HTTP "negotiate".
WS_E_PROXY_REQUIRES_NTLM_AUTH
 El servidor proxy HTTP requiere el esquema de autenticación HTTP "NTLM".
WS_E_SERVER_REQUIRES_BASIC_AUTH
 El punto de conexión remoto requiere el esquema de autenticación HTTP "básico".
WS_E_SERVER_REQUIRES_DIGEST_AUTH
 El punto de conexión remoto requiere el esquema de autenticación HTTP "digest".
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
 El punto de conexión remoto requiere el esquema de autenticación HTTP "negotiate".
WS_E_SERVER_REQUIRES_NTLM_AUTH
 El punto de conexión remoto requiere el esquema de autenticación HTTP "NTLM".
CERT_E_EXPIRED
 Un certificado necesario no está dentro de su período de validez al comprobar con el reloj del sistema actual o la marca de tiempo en el archivo firmado.
CERT_E_CN_NO_MATCH
 El nombre CN de los certificados no coincide con el valor pasado.
CERT_E_UNTRUSTEDROOT
 Cadena de certificados procesada, pero terminada en un certificado raíz que no es de confianza para el proveedor de confianza.
CERT_E_WRONG_USAGE
 El certificado no es válido para el uso solicitado.
CRYPT_E_REVOCATION_OFFLINE
 La función de revocación no pudo comprobar la revocación debido a que el servidor de revocación estaba sin conexión.
E_OUTOFMEMORY
 Se quedó sin memoria.
E_INVALIDARG
 Uno o más argumentos no son válidos.
Otros errores
Esta función puede devolver otros errores no enumerados anteriormente.

Comentarios

Esta función usa metadatos sobre los tipos de mensaje esperados para deserializar el cuerpo.
Los metadatos son una matriz de punteros a WS_MESSAGE_DESCRIPTIONs. Cada descripción del mensaje contiene un valor de acción, que se usa para coincidir con la acción del mensaje y un WS_ELEMENT_DESCRIPTION que proporciona los metadatos para el elemento body.

Cuando se hayan recibido los encabezados del mensaje, la función examinará la matriz para encontrar una coincidencia con la acción. La primera descripción del mensaje que coincide se usa para deserializar el cuerpo y el índice de base cero de esta descripción del mensaje en la matriz se devuelve en el parámetro index out. Si la función se ejecuta correctamente, el parámetro index out siempre se establecerá para indicar qué descripción del mensaje se usó.

Para que una descripción del mensaje coincida, el valor de la acción debe coincidir exactamente con el del mensaje. Si la acción del WS_MESSAGE_DESCRIPTION es NULL, la acción siempre coincide. Esto se puede usar en el caso de que no haya ningún encabezado de acción en el mensaje recibido, o si el cuerpo siempre es el mismo independientemente de cuál sea la acción.

Si se espera que el cuerpo esté vacío, el campo bodyElementDescription del WS_MESSAGE_DESCRIPTION puede ser NULL.

Si bodyElementDescription no es NULL, esta función deserializa el cuerpo como se describe en WsReadBody.

Una vez recibido un mensaje, sus encabezados se pueden inspeccionar mediante WsGetHeader o WsGetCustomHeader.

Requisitos

   
Cliente mínimo compatible Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino Windows
Encabezado webservices.h
Library WebServices.lib
Archivo DLL WebServices.dll