Expand Minimize

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.

Syntax


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
);

Parameters

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
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

Minimum supported client

Windows 7 [desktop apps | Windows Store apps]

Minimum supported server

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

Header

WebServices.h

Library

WebServices.lib

DLL

WebServices.dll

 

 

Community Additions

ADD
Show:
© 2014 Microsoft