WsReadMessageStart function (webservices.h)

Read the headers of the next message from the channel, and prepare to read the body elements.

Syntax

HRESULT WsReadMessageStart(
  [in]           WS_CHANNEL             *channel,
  [in]           WS_MESSAGE             *message,
  [in, optional] const WS_ASYNC_CONTEXT *asyncContext,
  [in, optional] WS_ERROR               *error
);

Parameters

[in] channel

The channel to receive from.

[in] message

The message to receive into.

[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
S_OK
Start of message was received successfully.
WS_S_END
There are no more messages available on the channel.
WS_S_ASYNC
The asynchronous operation is still pending.
WS_E_OPERATION_ABORTED
The operation was aborted.
WS_E_INVALID_OPERATION
The operation is not allowed due to the current state of the object.
WS_E_ENDPOINT_NOT_FOUND
The remote endpoint does not exist or could not be located.
WS_E_ENDPOINT_ACCESS_DENIED
Access was denied by the remote endpoint.
WS_E_ENDPOINT_DISCONNECTED
The connection with the remote endpoint was terminated.
WS_E_ENDPOINT_FAILURE
The remote endpoint could not process the request.
WS_E_ENDPOINT_NOT_AVAILABLE
The remote endpoint is not currently in service at this location.
WS_E_ENDPOINT_TOO_BUSY
The remote endpoint is unable to process the request due to being overloaded.
WS_E_ENDPOINT_UNREACHABLE
The remote endpoint was not reachable.
WS_E_INVALID_ENDPOINT_URL
The endpoint address URL is invalid.
WS_E_INVALID_FORMAT
The input data was not in the expected format or did not have the expected value.
WS_E_OPERATION_TIMED_OUT
The operation did not complete within the time allotted.
WS_E_PROXY_ACCESS_DENIED
Access was denied by the HTTP proxy server.
WS_E_PROXY_FAILURE
The HTTP proxy server could not process the request.
WS_E_QUOTA_EXCEEDED
A quota was exceeded.
WS_E_SECURITY_VERIFICATION_FAILURE
Security verification was not successful for the received data.
WS_E_SECURITY_SYSTEM_FAILURE
A security operation failed in the Windows Web Services framework.
WS_E_SECURITY_TOKEN_EXPIRED
A security token was rejected by the server because it has expired.
WS_E_PROXY_REQUIRES_BASIC_AUTH
The HTTP proxy server requires HTTP authentication scheme 'basic'.
WS_E_PROXY_REQUIRES_DIGEST_AUTH
The HTTP proxy server requires HTTP authentication scheme 'digest'.
WS_E_PROXY_REQUIRES_NEGOTIATE_AUTH
The HTTP proxy server requires HTTP authentication scheme 'negotiate'.
WS_E_PROXY_REQUIRES_NTLM_AUTH
The HTTP proxy server requires HTTP authentication scheme 'NTLM'.
WS_E_SERVER_REQUIRES_BASIC_AUTH
The remote endpoint requires HTTP authentication scheme 'basic'.
WS_E_SERVER_REQUIRES_DIGEST_AUTH
The remote endpoint requires HTTP authentication scheme 'digest'.
WS_E_SERVER_REQUIRES_NEGOTIATE_AUTH
The remote endpoint requires HTTP authentication scheme 'negotiate'.
WS_E_SERVER_REQUIRES_NTLM_AUTH
The remote endpoint requires HTTP authentication scheme 'NTLM'.
CERT_E_EXPIRED
A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.
CERT_E_CN_NO_MATCH
The certificates CN name does not match the passed value.
CERT_E_UNTRUSTEDROOT
A certificate chain processed, but terminated in a root certificate which is not trusted by the trust provider.
CERT_E_WRONG_USAGE
The certificate is not valid for the requested usage.
CRYPT_E_REVOCATION_OFFLINE
The revocation function was unable to check revocation because the revocation server was offline.
E_OUTOFMEMORY
Ran out of memory.
E_INVALIDARG
One or more arguments are invalid.
Other Errors
This function may return other errors not listed above.

Remarks

This reads the start of the next message from the channel, including the headers of the message.

This function is like WsReadEnvelopeStart but is used with channels.

Upon success, the headers will be stored in the message and can be accessed in a random-access fashion (for example, using WsGetHeader).

The message must be in WS_MESSAGE_STATE_EMPTY state. Upon success, the message will have transitioned to WS_MESSAGE_STATE_READING state.

To deserialize an element of the message body, use WsReadBody. To read directly from the XML Reader of the message, first get the reader using the WS_MESSAGE_PROPERTY_BODY_READER property.

If the channel input is streamed (WS_STREAMED_INPUT_TRANSFER_MODE), then WsFillBody must be called to receive the next part of the body before it is actually read.

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