WsReadEnvelopeStart function (webservices.h)

Article
02/22/2024

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

Share via