WsCheckMustUnderstandHeaders function (webservices.h)

Verifies that the specified headers were understood by the receiver.

Syntax

HRESULT WsCheckMustUnderstandHeaders(
  [in]           WS_MESSAGE *message,
  [in, optional] WS_ERROR   *error
);

Parameters

[in] message

Pointer to the WS_MESSAGE structure containing the headers to be understood.

[in, optional] error

Pointer to a WS_ERROR structure where additional error information is stored if the function fails.

Return value

If the function succeeds, it returns NO_ERROR; otherwise, it returns an HRESULT error code.

Remarks

Because the set of headers is extensible, it is necessary to determine whether a message has been sufficiently understood to be processed. Therefore, the sender can use this function to indicate which headers must be understood, which headers can be treated as optional or informational.

Standard addressing headers, such as the ones defined in WS_HEADER_TYPE, are automatically assumed to be understood, even if they are never read by calling WsGetHeader.

Custom, application-defined headers that are read by WsGetCustomHeader are also assumed to be understood. Calling WsGetCustomHeader will automatically mark the particular header as understood.

For any other header processed by the application, the application must explicitly mark the header as understood by calling WsMarkHeaderAsUnderstood. Otherwise, the header is considered to not be understood.

This function should be called after all headers have been read for a received message. An exception to having to call this function is the case of an intermediary that forwards the message to another node without changing its identity (message ID), since the final node will do the check.

The function will fail if any of the specified headers were not understood. If an error object is supplied to the function, it will be populated with information that can be used to send a fault (see WsCreateFaultFromError).

The message must be in the WS_MESSAGE_STATE_READING state.

Requirements