Edit

WsWriteEnvelopeStart function (webservices.h)

  • Article

Writes the start of the message including the current set of headers of the message and prepares to write the body elements.

This function is designed for writing messages to destinations other than channels. To write a message to a channel use WsWriteMessageStart.

Syntax

HRESULT WsWriteEnvelopeStart(
  [in]           WS_MESSAGE               *message,
  [in]           WS_XML_WRITER            *writer,
  [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 write. The pointer must reference a valid WS_MESSAGE object.

[in] writer

A pointer to the XML Writer object to write the Message. The Message object uses the Writer in subsequent calls to write the message. The caller must keep the writer valid until WsResetMessage or WsFreeMessage is called.

The WS_MESSAGE_DONE_CALLBACK parameter can be used to determine that the WS_XML_WRITER is no longer in use.

[in, optional] doneCallback

The callback function invoked when the Message is released or reset. This callback can be used to indicate that the WS_XML_WRITER object is no longer in use by this message. If this function fails the callback is not called. If the function succeeds the callback is invoked one time only.

[in, optional] doneCallbackState

A void pointer to a user-defined state that will be passed to the specified callback. This parameter may be NULL.

[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 start of the message, including the current set of headers that exist in the message, are written to the writer.

The message state must be set to WS_MESSAGE_STATE_INITIALIZED. On success the Message state transitions to WS_MESSAGE_STATE_WRITING.
On failure state transition does not occur.

To write an element of the message body use WsWriteBody. To write directly to the Writer of the Message obtain the Reader with the WS_MESSAGE_PROPERTY_ID set to WS_MESSAGE_PROPERTY_BODY_WRITER property.

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