Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

WsReadEnvelopeStart function

Reads the headers of the message and prepare to read the body elements. The operation reads the start of the next message from the Reader including the headers of the message. The process allows for reading of messages from other sources than channels. To read a message using a channel, use WsReadMessageStart.

Note   On success the headers is stored in the message and can be retrieved randomly using functions such as WsGetHeader or WsGetCustomHeader.


HRESULT WINAPI  WsReadEnvelopeStart(
  _In_     WS_MESSAGE*              message,
  _In_     WS_XML_READER*           reader,
  _In_opt_ WS_MESSAGE_DONE_CALLBACK doneCallback,
  _In_opt_ void*                    doneCallbackState,
  _In_opt_ WS_ERROR*                error


message [in]

A pointer to the Message object to read. The pointer must reference a valid WS_MESSAGE object.

reader [in]

A pointer to the Reader with the message to read. The Message object uses the Reader in the current and subsequent calls.

Note  The function caller must keep the Reader valid until WsResetMessage or WsFreeMessage is called. The WS_MESSAGE_DONE_CALLBACK parameter can be used a way to know that the WS_XML_READER is no longer in use.
doneCallback [in, optional]

Identifies the callback function to initiate on success of the current operation once the message has been released.

Note  Messages are released using WsFreeMessage or WsResetMessage
The callback can be used to discover whether the WS_XML_READER instance is in use by this message. If the current operation fails the callback is not called.
doneCallbackState [in, optional]

A pointer to user-defined state that can be passed to the WS_MESSAGE_DONE_CALLBACK. This parameter may be NULL if the callback is not used.

error [in, optional]

A pointer to a WS_ERROR object where additional information about the error should be stored if the function fails.

Return value

This function can return one of these values.

Return codeDescription

The input data was not in the expected format or did not have the expected value.


Ran out of memory.


One or more arguments are invalid.

Other Errors

This function may return other errors not listed above.



The message must be in WS_MESSAGE_STATE_EMPTY state. On success the message state is set to WS_MESSAGE_STATE_READING.

To read an Element of the message body, use WsReadBody. To read directly from the XML Reader get the Reader with the message property Id set to WS_MESSAGE_PROPERTY_BODY_READER.


Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2008 R2 [desktop apps | Windows Store apps]









Community Additions

© 2017 Microsoft