Edit

WsSendFaultMessageForError function (webservices.h)

  • Article

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