WsReceiveMessage function (webservices.h)
Receive a message and deserialize the body of the message as a value.
Syntax
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
);
Parameters
[in] channel
The channel to receive from.
[in] message
The message object used to receive.
The message should be in WS_MESSAGE_STATE_EMPTY state.
messageDescriptions
An array of pointers to message descriptions that specifies the metadata for the expected types of messages.
[in] messageDescriptionCount
The number of items in the messageDescriptions array.
[in] receiveOption
Whether the message is required. See WS_RECEIVE_OPTION for more information.
[in] readBodyOption
Whether the body element is required, and how to allocate the value.
See WS_READ_OPTION for more information.
[in, optional] heap
The heap to store the deserialized values in. If the heap is not required for the given type, then this parameter can be NULL.
value
The interpretation of this parameter depends on the WS_READ_OPTION.
If WS_RECEIVE_OPTIONAL_MESSAGE is specified for the receiveOption parameter, and no more messages are available on the channel, this parameter is not touched. In this case, the function returns WS_S_END. (See Windows Web Services Return Values.)
If the bodyElementDescription of the WS_MESSAGE_DESCRIPTION that matched is NULL, then this parameter is not touched. In this case, the parameter does not need to be specified.
[in] valueSize
The interpretation of this parameter depends on the WS_READ_OPTION.
index
If WS_RECEIVE_OPTIONAL_MESSAGE is specified for the receiveOption parameter, and no more messages are available on the channel, this parameter is untouched. In this case, the function will return WS_S_END.
Otherwise, if the function succeeds this will contain the zero-based index into the array of message descriptions indicating which one matched.
This parameter may be NULL if the caller is not interested in the value (for example, if there is only one message description).
[in, optional] asyncContext
Information on how to invoke the function asynchronously, or NULL if invoking synchronously.
[in, optional] error
Specifies where additional error information should be stored if the function fails.
Return value
This function can return one of these values.
Return code | Description |
---|---|
|
The asynchronous operation is still pending. |
|
The receive option WS_RECEIVE_OPTIONAL_MESSAGE was specified and there are no more messages available for the channel. |
|
The received message contained a fault. The fault can be extracted from the WS_ERROR using WsGetErrorProperty. |
|
The operation was aborted. |
|
The operation is not allowed due to the current state of the object. |
|
The remote endpoint does not exist or could not be located. |
|
Access was denied by the remote endpoint. |
|
The connection with the remote endpoint was terminated. |
|
The remote endpoint could not process the request. |
|
The remote endpoint is not currently in service at this location. |
|
The remote endpoint is unable to process the request due to being overloaded. |
|
The remote endpoint was not reachable. |
|
The endpoint address URL is invalid. |
|
The input data was not in the expected format or did not have the expected value. |
|
The operation did not complete within the time allotted. |
|
Access was denied by the HTTP proxy server. |
|
The HTTP proxy server could not process the request. |
|
A quota was exceeded. |
|
Security verification was not successful for the received data. |
|
A security operation failed in the Windows Web Services framework. |
|
A security token was rejected by the server because it has expired. |
|
The HTTP proxy server requires HTTP authentication scheme 'basic'. |
|
The HTTP proxy server requires HTTP authentication scheme 'digest'. |
|
The HTTP proxy server requires HTTP authentication scheme 'negotiate'. |
|
The HTTP proxy server requires HTTP authentication scheme 'NTLM'. |
|
The remote endpoint requires HTTP authentication scheme 'basic'. |
|
The remote endpoint requires HTTP authentication scheme 'digest'. |
|
The remote endpoint requires HTTP authentication scheme 'negotiate'. |
|
The remote endpoint requires HTTP authentication scheme 'NTLM'. |
|
A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file. |
|
The certificates CN name does not match the passed value. |
|
A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider. |
|
The certificate is not valid for the requested usage. |
|
The revocation function was unable to check revocation because the revocation server was offline. |
|
Ran out of memory. |
|
One or more arguments are invalid. |
|
This function may return other errors not listed above. |
Remarks
This function uses metadata about the expected message types in order to deserialize the body.
The metadata is an array of pointers to WS_MESSAGE_DESCRIPTIONs.
Each message description contains an action value, which is used to match against
the action of the message, and an WS_ELEMENT_DESCRIPTION which provides the metadata for the body element.
When the message headers have been received, the function will scan the array in order to find a match against the action. The first message description that matches is used to deserialize the body, and the zero-based index of this message description in the array is returned in the index out parameter. If the function succeeds, the index out parameter will always be set to indicate which message description was used.
In order for a message description to match, the action value must match that of the message exactly. If the action in the WS_MESSAGE_DESCRIPTION is NULL, then the action always matches. This can be used in the case where there is no action header in the received message, or if the body is always the same no matter what the action is.
If the body is expected to be empty, the bodyElementDescription field of the WS_MESSAGE_DESCRIPTION may be NULL.
If the bodyElementDescription is non-NULL, then this function deserializes the body as described in WsReadBody.
After a message has been received, its headers can be inspected using WsGetHeader or WsGetCustomHeader.
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 7 [desktop apps | UWP apps] |
Minimum supported server | Windows Server 2008 R2 [desktop apps | UWP apps] |
Target Platform | Windows |
Header | webservices.h |
Library | WebServices.lib |
DLL | WebServices.dll |