WsSendFaultMessageForError function (webservices.h)

Article
10/13/2021

Sends a fault message given a WS_ERROR object.

Syntax

HRESULT WsSendFaultMessageForError(
  [in]           WS_CHANNEL             *channel,
  [in]           WS_MESSAGE             *replyMessage,
  [in]           WS_ERROR               *faultError,
  [in]           HRESULT                faultErrorCode,
  [in]           WS_FAULT_DISCLOSURE    faultDisclosure,
  [in]           WS_MESSAGE             *requestMessage,
  [in, optional] const WS_ASYNC_CONTEXT *asyncContext,
  [in, optional] WS_ERROR               *error
);

Parameters

[in] channel

The channel to send the message on.

[in] replyMessage

A message object to use to send the reply message.

The message object should be in WS_MESSAGE_STATE_EMPTY or WS_MESSAGE_STATE_INITIALIZED. If an initialized message is provided, it should have been initialized using WS_FAULT_MESSAGE.

[in] faultError

The error object to use to construct the fault.

[in] faultErrorCode

The error code associated with the fault. This cannot be a success code.

This error code is never included in the fault message directly, but instead is used as a fallback mechanism for creating a fault string in the case that the WS_ERROR object does not contain any error strings.

[in] faultDisclosure

Controls how much of the error information is included in the fault message.

[in] requestMessage

The request message. This is used to obtain correlation information used in formulating the reply message.

The message can be in any state but WS_MESSAGE_STATE_EMPTY.

[in, optional] asyncContext

Information on how to invoke the function asynchronously, or NULL if invoking synchronously.

[in, optional] error

Specifies where additional error information should be stored if the function fails.

Return value

This function can return one of these values.

Return code	Description
WS_S_ASYNC	The asynchronous operation is still pending.
WS_E_OPERATION_ABORTED	The operation was aborted.
WS_E_INVALID_OPERATION	The operation is not allowed due to the current state of the object.
WS_E_ENDPOINT_DISCONNECTED	The connection with the remote endpoint was terminated.
WS_E_INVALID_FORMAT	The input data was not in the expected format or did not have the expected value.
WS_E_OPERATION_TIMED_OUT	The operation did not complete within the time allotted.
WS_E_QUOTA_EXCEEDED	A quota was exceeded.
WS_E_SECURITY_VERIFICATION_FAILURE	Security verification was not successful for the received data.
WS_E_SECURITY_SYSTEM_FAILURE	A security operation failed in the Windows Web Services framework.
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 WS_FAULT that is sent in the body of the message is constructed using the same rules as defined by WsCreateFaultFromError.

The value of the WS_ACTION_HEADER used for the reply message is computed as follows:

If the WS_CHANNEL_PROPERTY_ADDRESSING_VERSION of the channel is WS_ADDRESSING_VERSION_TRANSPORT, then no action is included in the message because the addressing version does not permit an action value for faults.
If the error object contains an action string (the length of the string returned by WS_FAULT_ERROR_PROPERTY_ACTION is greater than zero), then the action string is used.
If the error object does not contain an action, then a default action value is supplied.

If the error object contains a header used to describe the fault as specified by WS_FAULT_ERROR_PROPERTY_HEADER, then the header is added to the headers of the fault message.

The fault message will include correlation information as appropriate to the WS_ADDRESSING_VERSION. See Channel Layer Overview for more information about correlating request reply messages.

If sending a fault without a WS_ERROR object, use WsSendReplyMessage.

To add custom headers to the message, initialize the message WsInitializeMessage with WS_FAULT_MESSAGE and then add the headers using WsAddCustomHeader before calling this function.

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