|  | Home | Documentation | Fault structure and functions updated Wed Apr 8 2026 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Classes | Functions
Fault structure and functions

This module describes the `SOAP_ENV__Fault` structure and functions to set and get fault information. More...

## Classes
struct | SOAP_ENV__Fault
| SOAP Fault structure. More...
struct | SOAP_ENV__Code
| SOAP Fault Code structure. More...
struct | SOAP_ENV__Detail
| SOAP Fault Detail structure. More...
struct | SOAP_ENV__Reason
| SOAP Fault Reason structure generated by soapcpp2. More...

## Functions
void | soap_fault (struct soap *soap)
| If `soap::fault` is NULL then allocate `SOAP_ENV__Fault` header and set `soap::fault` to point to it. More...
int | soap_sender_fault (struct soap *soap, const char *faultstring, const char *faultdetail)
| Set SOAP 1.1 client fault / SOAP 1.2 sender fault string and detail. More...
int | soap_sender_fault_subcode (struct soap *soap, const char *faultsubcode, const char *faultstring, const char *faultdetail)
| Set SOAP 1.1 client fault / SOAP 1.2 sender fault subcode, string and detail. More...
int | soap_receiver_fault (struct soap *soap, const char *faultstring, const char *faultdetail)
| Set SOAP 1.1 server fault / SOAP 1.2 receiver fault string and detail. More...
int | soap_receiver_fault_subcode (struct soap *soap, const char *faultsubcode, const char *faultstring, const char *faultdetail)
| Set SOAP 1.1 server fault / SOAP 1.2 receiver fault subcode, string and detail. More...
void | soap_print_fault (struct soap *soap, FILE *fd)
| Print error message on the specified output. More...
void | soap_stream_fault (struct soap *soap, std::ostream &os)
| Print error message on the specified output stream. More...
char * | soap_sprint_fault (struct soap *soap, char *buf, size_t len)
| Print error message to the specified string buffer. More...
void | soap_print_fault_location (struct soap *soap, FILE *fd)
| Print the location in the message where and when the error occurred. More...
void | soap_stream_fault_location (struct soap *soap, std::ostream &os)
| Print the location in the message where and when the error occurred. More...
const char * | soap_fault_subcode (struct soap *soap)
| Returns the SOAP Fault subcode QName string or NULL when absent. More...
const char * | soap_fault_string (struct soap *soap)
| Returns the SOAP Fault string/reason or NULL when absent. More...
const char * | soap_fault_detail (struct soap *soap)
| Returns the SOAP Fault detail XML string or NULL when absent. More...
const char ** | soap_faultsubcode (struct soap *soap)
| Allocates and returns a pointer to the SOAP Fault subcode QName string to set this string. More...
const char ** | soap_faultstring (struct soap *soap)
| Allocates and returns a pointer to the SOAP Fault string/reason to set this string. More...
const char ** | soap_faultdetail (struct soap *soap)
| Allocates and returns a pointer to the SOAP Fault detail XML string to set this string or NULL when not accessible. More...

## Detailed Description

This module describes the `SOAP_ENV__Fault` structure and functions to set and get fault information.

## Function Documentation

void soap_fault | ( | struct soap * | soap | ) |

If `soap::fault` is NULL then allocate `SOAP_ENV__Fault` header and set `soap::fault` to point to it.

If `soap::fault` is NULL then this function allocates a `SOAP_ENV__Fault` structure in memory managed by the context, default initializes its members, and sets `soap::fault` to point to the allocated structure. If `soap::version` == 2 (SOAP 1.2) then also allocates and default initializes `SOAP_ENV__Fault::SOAP_ENV__Code` and `SOAP_ENV__Fault::SOAP_ENV__Reason`. This function is used by `soap_sender_fault`, `soap_sender_fault_subcode`, `soap_receiver_fault` and `soap_receiver_fault_subcode` to allocate and set a SOAP Fault.

See also
  `SOAP_ENV__Fault`, `soap_sender_fault`, `soap_sender_fault_subcode`, `soap_receiver_fault`, `soap_receiver_fault_subcode`.

Parameters

  soap | `soap` context

const char* soap_fault_detail | ( | struct soap * | soap | ) |

Returns the SOAP Fault detail XML string or NULL when absent.

Returns
  string or NULL

Parameters

  soap | `soap` context

const char* soap_fault_string | ( | struct soap * | soap | ) |

Returns the SOAP Fault string/reason or NULL when absent.

Returns
  string or NULL

Parameters

  soap | `soap` context

const char* soap_fault_subcode | ( | struct soap * | soap | ) |

Returns the SOAP Fault subcode QName string or NULL when absent.

Returns
  string or NULL

const char** soap_faultdetail | ( | struct soap * | soap | ) |

Allocates and returns a pointer to the SOAP Fault detail XML string to set this string or NULL when not accessible.

Returns
  pointer to string or NULL

Parameters

  soap | `soap` context

const char** soap_faultstring | ( | struct soap * | soap | ) |

Allocates and returns a pointer to the SOAP Fault string/reason to set this string.

Returns
  pointer to string

Parameters

  soap | `soap` context

const char** soap_faultsubcode | ( | struct soap * | soap | ) |

Allocates and returns a pointer to the SOAP Fault subcode QName string to set this string.

Returns
  pointer to string

Parameters

  soap | `soap` context

void soap_print_fault | ( | struct soap * | soap,
|  | FILE * | fd
| ) |  |

Print error message on the specified output.

This function prints the error message of the nonzero `soap::error` value. The `fd` parameter specifies the output file descriptor, such as stderr. This function has no effect when `soap:error` is `SOAP_OK` (zero).

Parameters

  soap | `soap` context
  fd | output file descriptor to print to

void soap_print_fault_location | ( | struct soap * | soap,
|  | FILE * | fd
| ) |  |

Print the location in the message where and when the error occurred.

This function prints the location in the inbound message being parsed where the error occurred. Only part of the message will be printed, depending on the `SOAP_BUFLEN` size and the size of the actual data packet received into the `soap::buf` buffer. This function is usually used after calling `soap_print_fault` which makes sense when a message processing error occurred such as when `soap_xml_error_check(soap->error)` is true. This function has no effect when `soap:error` is `SOAP_OK` (zero).

Parameters

  soap | `soap` context
  fd | output file descriptor to print to

int soap_receiver_fault | ( | struct soap * | soap,
|  | const char * | faultstring,
|  | const char * | faultdetail
| ) |  |

Set SOAP 1.1 server fault / SOAP 1.2 receiver fault string and detail.

This function assigns a SOAP 1.1 server fault / SOAP 1.2 receiver fault to the `soap::fault` structure and sets `soap::error` to `SOAP_FAULT`, indicating that the receiver encountered an error in processing the request and may recover from the error later. The `faultstring` parameter is a human-readable message with the reason of the error. The `faultdetail` parameter is an XML-formatted string with details or NULL when omitted. Returns `SOAP_FAULT`.

Returns
  `SOAP_FAULT`

Parameters

  soap | `soap` context
  faultstring | SOAP Fault string with reason
  faultdetail | SOAP Fault detail with XML or NULL

int soap_receiver_fault_subcode | ( | struct soap * | soap,
|  | const char * | faultsubcode,
|  | const char * | faultstring,
|  | const char * | faultdetail
| ) |  |

Set SOAP 1.1 server fault / SOAP 1.2 receiver fault subcode, string and detail.

This function assigns a SOAP 1.1 server fault / SOAP 1.2 receiver fault to the `soap::fault` structure and sets `soap::error` to `SOAP_FAULT`, indicating that the receiver encountered an error in processing the request and may recover from the error later. The `faultcode` parameter is a QName specific to the protocol associated with the fault. The `faultstring` parameter is a human-readable message with the reason of the error. The `faultdetail` parameter is an XML-formatted string with details or NULL when omitted. Returns `SOAP_FAULT`.

Returns
  `SOAP_FAULT`

Parameters

  soap | `soap` context
  faultsubcode | SOAP Fault subcode with QName
  faultstring | SOAP Fault string with reason
  faultdetail | SOAP Fault detail with XML or NULL

int soap_sender_fault | ( | struct soap * | soap,
|  | const char * | faultstring,
|  | const char * | faultdetail
| ) |  |

Set SOAP 1.1 client fault / SOAP 1.2 sender fault string and detail.

This function assigns a SOAP 1.1 server fault / SOAP 1.2 receiver fault to the `soap::fault` structure and sets `soap::error` to `SOAP_FAULT`, indicating an invalid request by the sender, which the receiver cannot recover from. The `faultstring` parameter is a human-readable message with the reason of the error. The `faultdetail` parameter is an XML-formatted string with details or NULL when omitted. Returns `SOAP_FAULT`.

Returns
  `SOAP_FAULT`

Parameters

  soap | `soap` context
  faultstring | SOAP Fault string with reason
  faultdetail | SOAP Fault detail with XML or NULL

int soap_sender_fault_subcode | ( | struct soap * | soap,
|  | const char * | faultsubcode,
|  | const char * | faultstring,
|  | const char * | faultdetail
| ) |  |

Set SOAP 1.1 client fault / SOAP 1.2 sender fault subcode, string and detail.

This function assigns a SOAP 1.1 server fault / SOAP 1.2 receiver fault to the `soap::fault` structure and sets `soap::error` to `SOAP_FAULT`, indicating an invalid request by the sender, which the receiver cannot recover from. The `faultcode` parameter is a QName specific to the protocol associated with the fault. The `faultstring` parameter is a human-readable message with the reason of the error. The `faultdetail` parameter is an XML-formatted string with details or NULL when omitted. Returns `SOAP_FAULT`.

Returns
  `SOAP_FAULT`

Parameters

  soap | `soap` context
  faultsubcode | SOAP Fault subcode with QName
  faultstring | SOAP Fault string with reason
  faultdetail | SOAP Fault detail with XML or NULL

char* soap_sprint_fault | ( | struct soap * | soap,
|  | char * | buf,
|  | size_t | len
| ) |  |

Print error message to the specified string buffer.

This function prints the error message of the nonzero `soap::error` value to the string buffer specified by the `buf` and `len` parameters. This function has no effect when `soap:error` is `SOAP_OK` (zero).

Returns
  the `buf` parameter

Parameters

  soap | `soap` context
  buf | string buffer to store the message, 0-terminated
  len | buffer length

void soap_stream_fault | ( | struct soap * | soap,
|  | std::ostream & | os
| ) |  |

Print error message on the specified output stream.

This function prints the error message of the nonzero `soap::error` value. The `os` parameter specifies the output stream such as std::cerr. This function has no effect when `soap:error` is `SOAP_OK` (zero).

Parameters

  soap | `soap` context
  os | output stream to print to

void soap_stream_fault_location | ( | struct soap * | soap,
|  | std::ostream & | os
| ) |  |

Print the location in the message where and when the error occurred.

This function prints the location in the inbound message being parsed where the error occurred. Only part of the message will be printed, depending on the `SOAP_BUFLEN` size and the size of the actual data packet received into the `soap::buf` buffer. This function is usually used after calling `soap_stream_fault` which makes sense when a message processing error occurred such as when `soap_xml_error_check(soap->error)` is true. This function has no effect when `soap:error` is `SOAP_OK` (zero).

Parameters

  soap | `soap` context
  os | output stream to print to