Edit

WsReadEnvelopeStart function (webservices.h)

  • Article

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.

 

Syntax

HRESULT WsReadEnvelopeStart(
  [in]           WS_MESSAGE               *message,
  [in]           WS_XML_READER            *reader,
  [in, optional] WS_MESSAGE_DONE_CALLBACK doneCallback,
  [in, optional] void                     *doneCallbackState,
  [in, optional] WS_ERROR                 *error
);

Parameters

[in] message

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

[in] reader

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.

 

[in, optional] doneCallback

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.

[in, optional] doneCallbackState

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.

[in, optional] error

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 code Description
WS_E_INVALID_FORMAT
 The input data was not in the expected format or did not have the expected value.
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

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.

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