|  | Home | Documentation | Callback functions updated Fri Mar 19 2021 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Variables
Callback functions

This module defines the callback functions of the `soap` context to modify its behavior, as is done by plugins. More...

## Variables
int(* | soap::fpost )(struct soap *soap, const char *endpoint, const char *host, int port, const char *path, const char *action, ULONG64 count)
| Callback that populates and then sends HTTP headers from the client-side to a connected HTTP server. More...
int(* | soap::fresponse )(struct soap *soap, int status, ULONG64 count)
| Callback that populates and then sends HTTP headers from the server-side to a connected client. More...
int(* | soap::fposthdr )(struct soap *soap, const char *key, const char *val)
| Callback that sends a single HTTP header given a key-value pair. More...
int(* | soap::fparse )(struct soap *soap)
| Callback that reads and parses HTTP and MIME headers. More...
int(* | soap::fparsehdr )(struct soap *soap, const char *key, const char *val)
| Callback that consumes an HTTP header that consists of a key-value pair. More...
int(* | soap::fget )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP GET requests from clients. More...
int(* | soap::fput )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP PUT requests from clients. More...
int(* | soap::fpatch )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP PATCH requests from clients. More...
int(* | soap::fdel )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP DELETE requests from clients. More...
int(* | soap::fopt )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP OPTION requests from clients. More...
int(* | soap::fhead )(struct soap *soap)
| Callback to implement logic at the server-side to serve responses to HTTP HEAD requests from clients. More...
int(* | soap::fform )(struct soap *soap)
| Callback to implement logic at the server-side to handle HTML forms, such as done by the callbacks provided by the HTTP FORM handler plugin. More...
int(* | soap::fheader )(struct soap *soap)
| Callback to inspect the SOAP Header received before the rest of the message with the SOAP Body is consumed. More...
int(* | soap::fignore )(struct soap *soap, const char *tag)
| Callback to catch unrecognized XML elements and overrides `SOAP_XML_STRICT` validation errors for these. More...
int(* | soap::fsvalidate )(struct soap *soap, const char *pattern, const char *string)
| Callback to validate strings against XML regex patterns. More...
int(* | soap::fwvalidate )(struct soap *soap, const char *pattern, const wchar_t *string)
| Callback to validate wide strings against XML regex patterns. More...
void(* | soap::fseterror )(struct soap *soap, const char **faultcode, const char **faultstring)
| Callback to inspect or override fault code or fault string messages. More...
SOAP_SOCKET(* | soap::fopen )(struct soap *soap, const char *endpoint, const char *host, int port)
| Callback that opens a socket connection to a server endpoint. More...
SOAP_SOCKET(* | soap::faccept )(struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len)
| Callback that waits for and accepts a socket connection requested by a client. More...
int(* | soap::fclose )(struct soap *soap)
| Callback that closes the current socket connection. More...
int(* | soap::fresolve )(struct soap *soap, const char *name, struct in_addr *inaddr)
| Callback that resolves a host name by address translation. More...
int(* | soap::fconnect )(struct soap *soap, const char *endpoint, const char *host, int port)
| Callback that overrides the client-side connecting operations. More...
int(* | soap::fdisconnect )(struct soap *soap)
| Callback that executes disconnect logic before closing. More...
int(* | soap::fclosesocket )(struct soap *soap, SOAP_SOCKET sock)
| Callback that closes a given socket. More...
int(* | soap::fshutdownsocket )(struct soap *soap, SOAP_SOCKET sock, int how)
| Callback that shuts down a given socket. More...
int(* | soap::fpoll )(struct soap *soap)
| Callback that blocks until activity is detected on the `soap::socket` or `soap::master` socket, times out when `soap::send_timeout` or `soap::recv_timeout` are set. More...
size_t(* | soap::frecv )(struct soap *soap, char *buf, size_t len)
| Callback that receives bytes of data into the given buffer. More...
int(* | soap::fsend )(struct soap *soap, const char *data, size_t len)
| Callback that sends the given bytes of data. More...
int(* | soap::fserveloop )(struct soap *soap)
| Callback executed by the engine at the server side immediately after a server operation successfully completed. More...
void *(* | soap::fmalloc )(struct soap *soap, size_t size)
| Callback to override dynamic memory allocation and management. More...
void *(* | soap::fdimereadopen )(struct soap *soap, void *handle, const char *id, const char *type, const char *options)
| Callback to open a streaming DIME attachment for reading. More...
size_t(* | soap::fdimeread )(struct soap *soap, void *handle, char *buf, size_t len)
| Callback to read data in a DIME attachment stream. More...
void(* | soap::fdimereadclose )(struct soap *soap, void *handle)
| Callback to close a DIME attachment stream after reading. More...
void *(* | soap::fdimewriteopen )(struct soap *soap, const char *id, const char *type, const char *options)
| Callback to open a streaming DIME attachment for writing. More...
int(* | soap::fdimewrite )(struct soap *soap, void *, const char *, size_t)
| Callback to write data in a DIME attachment stream. More...
void(* | soap::fdimewriteclose )(struct soap *soap, void *handle)
| Callback to close a DIME attachment stream after writing. More...
void *(* | soap::fmimereadopen )(struct soap *soap, void *, const char *, const char *, const char *)
| Callback to open a streaming MIME/MTOM attachment for reading. More...
size_t(* | soap::fmimeread )(struct soap *soap, void *handle, char *buf, size_t len)
| Callback to read data in a MIME/MTOM attachment stream. More...
void(* | soap::fmimereadclose )(struct soap *soap, void *handle)
| Callback to close a MIME/MTOM attachment stream after reading. More...
void *(* | soap::fmimewriteopen )(struct soap *soap, void *handle, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding)
| Callback to open a streaming MIME/MTOM attachment for writing. More...
int(* | soap::fmimewrite )(struct soap *soap, void *handle, const char *buf, size_t len)
| Callback to write data in a MIME attachment stream. More...
void(* | soap::fmimewriteclose )(struct soap *soap, void *handle)
| Callback to close a MIME/MTOM attachment stream after writing. More...
int(* | soap::fsslauth )(struct soap *soap)
| Callback to initialize the OpenSSL library. More...
int(* | soap::fsslverify )(int ok, X509_STORE_CTX *store)
| Callback to manage the verification of the certificate provided by a peer (typically a server) More...

## Detailed Description

This module defines the callback functions of the `soap` context to modify its behavior, as is done by plugins.

HTTP callbacks:

- `soap::fpost`
- `soap::fresponse`
- `soap::fposthdr`
- `soap::fparse`
- `soap::fparsehdr`
- `soap::fget`
- `soap::fput`
- `soap::fdel`
- `soap::fopt`
- `soap::fhead`
- `soap::fform`

XML and SOAP callbacks:

- `soap::fheader`
- `soap::fignore`
- `soap::fsvalidate`
- `soap::fwvalidate`
- `soap::fseterror`

Socket connection callbacks:

- `soap::fopen`
- `soap::faccept`
- `soap::fclose`
- `soap::fresolve`
- `soap::fconnect`
- `soap::fdisconnect`
- `soap::fclosesocket`
- `soap::fshutdownsocket`
- `soap::fpoll`

IO callbacks:

- `soap::frecv`
- `soap::fsend`

Server keep-alive loop callback:

- `soap::fserveloop`

Memory allocation callback:

- `soap::fmalloc`

Streaming DIME attachment callbacks:

- `soap::fdimereadopen`
- `soap::fdimeread`
- `soap::fdimereadclose`
- `soap::fdimewriteopen`
- `soap::fdimewrite`
- `soap::fdimewriteclose`

Streaming MIME/MTOM attachment callbacks:

- `soap::fmimereadopen`
- `soap::fmimeread`
- `soap::fmimereadclose`
- `soap::fmimewriteopen`
- `soap::fmimewrite`
- `soap::fmimewriteclose`

OpenSSL and GNUTLS SSL/TLS callbacks:

- `soap::fsslauth`
- `soap::fsslverify`

To pass user-specified data to callbacks and plugins, assign a value to the `soap::user` variable of the context which can be accessed within the callback or plugin.

## Variable Documentation

SOAP_SOCKET(* soap::faccept) (struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len)

Callback that waits for and accepts a socket connection requested by a client.

This callback is called by `soap_accept` (or the C++ service class `accept` method) to wait for and accept a socket connection requested by a client. Returns a valid socket or `SOAP_INVALID_SOCKET` when an error occurred and sets `soap::error` to a `soap_status` value. The built-in function assigned to `soap::faccept` is `tcp_accept`.

See also
  `soap::fopen`, `soap::user`.

Parameters

  soap | `soap` context
  sock | master socket
  addr | points to a `sockaddr` structure to be populated
  len | points to the length of the `sockaddr` structure, the length may be reduced by the callback function with the actual size of the `sockaddr` structure populated

Returns
  socket or `SOAP_INVALID_SOCKET` if an error occurred

int(* soap::fclose) (struct soap *soap)

Callback that closes the current socket connection.

This callback is called by the engine at the client-side to close the current socket connection before a new socket connection is established. This callback may be called multiple times (e.g. by the engine and by plugins) to close the same socket `soap::socket`. Checks internally if `soap::socket` == `SOAP_INVALID_SOCKET` before closing, which means that the socket was already closed. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fclose` is `tcp_disconnect`.

See also
  `soap::fopen`, `soap::faccept`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  socket or `SOAP_INVALID_SOCKET` if an error occurred

int(* soap::fclosesocket) (struct soap *soap, SOAP_SOCKET sock)

Callback that closes a given socket.

This callback is called to close a socket by the engine. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fclosesocket` is `tcp_closesocket`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  sock | socket to close

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fconnect) (struct soap *soap, const char *endpoint, const char *host, int port)

Callback that overrides the client-side connecting operations.

This callback is called by the engine to optionally override client-side connecting. The parameters `host` and `port` were micro-parsed from the `endpoint` prior to passing them to this callback. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fconnect`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  endpoint | URL of the endpoint connected to (string)
  host | URL host of the endpoint connected to (string)
  port | URL port of the endpoint connected to (int)

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fdel) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP DELETE requests from clients.

This callback is called by the service dispatcher when an HTTP DELETE request is pending. Redefine this callback to respond to HTTP DELETE requests, see the `http_post` HTTP POST plugin for more details. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fdel` is the internal static function `http_del` that returns the `SOAP_DEL_METHOD` error.

See also
  `http_post`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

size_t(* soap::fdimeread) (struct soap *soap, void *handle, char *buf, size_t len)

Callback to read data in a DIME attachment stream.

This callback is called by the engine to read a chunk of attachment data to transmit. The `handle` parameter contains the handle returned by the `soap::fdimereadopen` callback. The `buf` parameter is the buffer of length `len` into which a chunk of data should be written by the callback. The actual amount of data written into the buffer may be less than `len` and this actual amount should be returned by the callback. A return value of zero indicates an error and `soap::error` should be set. The `__size` member variable of the attachment struct/class with data (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members) should be set by the application prior to the serialization of the message with attachments. The value of `__size` indicates the total size of the attachment data to be transmitted. If the `__size` member variable is zero and HTTP chunking is enabled (with `SOAP_IO_CHUNK`), then DIME chunked transfers are activated by the engine, which is more flexible since the attachment data size does not need to be determined in adance. To use DIME chunked transfers, enable HTTP chunking with `SOAP_IO_CHUNK` (also `SOAP_IO_STORE` can be used, but this buffers the entire message in memory before transmission) and set the `__size` member variable of the attachment struct/class to zero. When DIME attachment chunking is enabled, this callback should completely fill the `buf` buffer with `len` bytes unless the last data chunk is reached and fewer bytes are returned.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Example:

See the example provided with the documentation for `soap::fdimereadopen`. To enable chunked DIME attachments, replace the last part of the example with:

struct soap *soap = soap_new1(SOAP_IO_CHUNK);
struct _xop__Include data; // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = "Picture.png"; // file name to open for streaming with dime_read_open
data.__size = 0; // zero size means chunked DIME attachments are sent
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png"; // attachment type
data.options = soap_dime_option(soap, 0, "Picture.png"); // DIME option 0 = "Picture.png" to store file name
... // add data to the message and then send it, which will stream the DIME attachment content from Picture.png

Parameters

  soap | `soap` context
  handle | the value of the handle returned by `soap::fdimereadopen`
  buf | buffer to fill
  len | length of the buffer in bytes

Returns
  the number of bytes written to the buffer

void(* soap::fdimereadclose) (struct soap *soap, void *handle)

Callback to close a DIME attachment stream after reading.

This callback is called by the engine to close the DIME attachment stream after reading. The `handle` parameter contains the handle returned by the `soap::fdimereadopen` callback.

See also
  `SOAP_ENC_DIME`, `soap::fdimereadopen`, `soap::fdimeread`, `soap::user`.

Example:

See the examples provided with the documentation for `soap::fdimereadopen` and `soap::fdimeread`.

Parameters

  soap | `soap` context
  handle | the value of the of the handle returned by `soap::fdimereadopen`

void*(* soap::fdimereadopen) (struct soap *soap, void *handle, const char *id, const char *type, const char *options)

Callback to open a streaming DIME attachment for reading.

This callback is called by the engine to start sending a streaming DIME attachment. This callback opens a stream to start reading the attachment data to send. The actual data stream will be read in chunks using the `soap::fdimeread` callback until no more data is available and the `soap::fdimereadclose` callback is called to close the stream. The `handle` parameter contains the value of the `__ptr` member variable of the attachment struct/class with data (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members), which should be a pointer to specific information such as a file descriptor or a pointer to a some application-specific data to be passed to this callback. Both the `__ptr` and `__size` members of the attachment struct/class should have been set by the application prior to the serialization of the message with attachments. If the `__size` is zero and HTTP chunking is enabled (with `SOAP_IO_CHUNK`), then chunked DIME attachments are sent, see `soap::fdimeread`. The `id`, `type` and `options` parameters are the `id` (optional ID), `type` (a MIME type) and `options` (DIME options are set with `soap_dime_option`) of the attachment struct/class, respectively, of which at least one member should be non-NULL. The callback should return the `handle` parameter value or another pointer value, which is passed as the new `handle` parameter to `soap::fdimeread` and `soap::fdimereadclose` callbacks. When an error occurred in this callback, the callback should return NULL and set `soap::error` to an error code, e.g. using `soap_receiver_fault`. The callback may return NULL and set `soap::error` to `SOAP_OK` when this specific DIME attachment should not to be streamed and the engine will simply skip it.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Example:

void * dime_read_open(struct soap *soap, void *handle, const char *id, const char *type, const char *options)
{
return (void*)fopen((char*)handle, "rb");
}
size_t dime_read(struct soap *soap, void *handle, char *buf, size_t len)
{
return fread(buf, 1, len, (FILE*)handle);
}
void dime_read_close(struct soap *soap, void *handle)
{
fclose((FILE*)handle);
}
struct soap *soap = soap_new();
soap->fdimereadopen = dime_read_open;
soap->fdimeread = dime_read;
soap->fdimereadclose = dime_read_close;
struct _xop__Include data; // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = "Picture.png"; // file name to open for streaming with dime_read_open
data.__size = 1024; // file has 1024 bytes of data
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png"; // attachment type
data.options = soap_dime_option(soap, 0, "Picture.png"); // DIME option 0 = "Picture.png" to store file name
... // add data to the message and then send it, which will stream the DIME attachment content from Picture.png

This mechanism also works for DIME attachments attached with `soap_set_dime_attachment`.

The maximum size of DIME attachments that the engine allows to be received is limited to `SOAP_MAXDIMESIZE`. Increase this size as necessary.

Parameters

  soap | `soap` context
  handle | the value of the `__ptr` member variable of the attachment struct/class with data
  id | the value of the `id` member variable of the attachment struct/class with data
  type | the value of the `type` member variable of the attachment struct/class with data
  options | the value of the `options` member variable of the attachment struct/class with data

Returns
  a handle or NULL when an error occurred (`soap::error` is nonzero) or when the attachment should be skipped (`soap::error` is `SOAP_OK`)

int(* soap::fdimewrite) (struct soap *soap, void *, const char *, size_t)

Callback to write data in a DIME attachment stream.

This callback is called by the engine to write a chunk of attachment data received. The `handle` parameter contains the handle returned by the `soap::fdimewriteopen` callback. The `buf` parameter contains the data of length `len`. Returns `SOAP_OK` or a `soap_status` (int) error code.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Parameters

  soap | `soap` context
  handle | the value of the handle returned by `soap::fdimewriteopen`

Returns
  `SOAP_OK` or a `soap_status` error code

void(* soap::fdimewriteclose) (struct soap *soap, void *handle)

Callback to close a DIME attachment stream after writing.

This callback is called by the engine to close the DIME attachment stream after writing. The `handle` parameter contains the handle returned by the `soap::fdimewriteopen` callback.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Parameters

  soap | `soap` context
  handle | the value of the of the handle returned by `soap::fdimewriteopen`

void*(* soap::fdimewriteopen) (struct soap *soap, const char *id, const char *type, const char *options)

Callback to open a streaming DIME attachment for writing.

Called by the to start receiving a streaming DIME attachment. This callback opens a stream to start writing the attachment data received. The actual data stream will be written in chunks using the `soap::fdimewrite` callback until no more data is available and the `soap::fdimewriteclose` callback is called to close the stream. The `id`, `type` and `options` parameters are the `id`, `type` and `options` of the attachment struct/class (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members), respectively. The callback should return a handle, which is passed to the `soap::fdimewrite` and `soap::fdimewriteclose` callbacks. The `__ptr` member variable of the attachment struct/class is set by the engine to the value of this handle. The `__size` member variable is set to the size of the attachment received. The maximum DIME attachment size received is limited by `SOAP_MAXDIMESIZE`.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Example:

void * dime_write_open(struct soap *soap, const char *id, const char *type, const char *options)
{
if (options)
{
FILE *handle = NULL;
char *name;
size_t len = ((unsigned char)options[2] << 8) | ((unsigned char)options[3]); // get option string length
name = (char*)soap_malloc(soap, len + 1);
strncpy(name, options + 4, len); // get file name from options (as an example)
name[len] = '\0';
handle = fopen(name, "wb");
if (!handle)
{
soap->error = SOAP_EOF; // could not open file for writing
soap->errnum = errno; // to report errno value
return NULL;
}
}
else
{
soap->error = soap_receiver_fault(soap, "Cannot save to file: no file name was present in the attachment", NULL);
}
return (void*)handle;
}
int dime_write(struct soap *soap, void *handle, const char *buf, size_t len)
{
while (len)
{
size_t nwritten = fwrite(buf, 1, len, (FILE*)handle);
if (!nwritten)
{
soap->errnum = errno;
return SOAP_EOF;
}
len -= nwritten;
buf += nwritten;
}
return SOAP_OK;
}
void dime_write_close(struct soap *soap, void *handle)
{
fclose((FILE*)handle);
}
struct soap *soap = soap_new();
soap->fdimewriteopen = dime_write_open;
soap->fdimewrite = dime_write;
soap->fdimewriteclose = dime_write_close;
... // when a service responds to the client request with DIME attachment(s), the attachment data is saved via the callbacks

The maximum size of DIME attachments that the engine allows to be received is limited to `SOAP_MAXDIMESIZE`. Increase this size as necessary.

Parameters

  soap | `soap` context
  id | the value of the `id` member variable of the attachment struct/class with data
  type | the value of the `type` member variable of the attachment struct/class with data
  options | the value of the `options` member variable of the attachment struct/class with data

Returns
  a handle or NULL when an error occurred (`soap::error` should be nonzero)

int(* soap::fdisconnect) (struct soap *soap)

Callback that executes disconnect logic before closing.

This callback is called by the engine `soap_closesock` before the `soap::fclose` callback is called to shutdown/disconnect. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fdisconnect`.

See also
  `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fform) (struct soap *soap)

Callback to implement logic at the server-side to handle HTML forms, such as done by the callbacks provided by the HTTP FORM handler plugin.

This callback is called by the HTTP FORM handler plugin to parse HTML forms received with HTTP POST and PUT requests, see the `;:http_form` HTTP FORM plugin for more details. The HTTP body with the form data should be parsed by this callback, otherwise HTTP keep-alive messages will end up out of sync as a result of the current position not being advanced to the end of the HTTP body. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fform`.

See also
  `http_post`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fget) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP GET requests from clients.

This callback is called by the service dispatcher when an HTTP GET request is pending. Redefine this callback to respond to HTTP GET requests with content, see the `http_get` HTTP GET plugin for more details. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fget` is the internal static function `http_get` that returns the `SOAP_GET_METHOD` error.

See also
  `http_get`, `soap::user`.

Example

int main()
{
struct soap *soap = soap_new();
soap->user = ... // set this to pass data to the callback
soap->fget = http_get;
... //
}
// return a service.wsdl WSDL document on HTTP GET service path ending in ?wsdl
int http_get(struct soap * soap)
{
FILE *fd = NULL;
char *s = strchr(soap->path, '?'); // soap->path has the URL path of soap->endpoint
if (s == NULL || strcmp(s, "?wsdl") != 0)
return SOAP_GET_METHOD; // return GET method not available error
fd = fopen("service.wsdl", "r"); // open WSDL file to copy
if (!fd)
return 404; // return HTTP not found error
soap->http_content = "text/xml"; // HTTP header with text/xml content
soap_response(soap, SOAP_FILE);
while (1)
{
size_t r = fread(soap->tmpbuf, 1, sizeof(soap->tmpbuf), fd);
if (r == 0)
break;
if (soap_send_raw(soap, soap->tmpbuf, r))
break; // can't send
}
fclose(fd);
return soap_end_send(soap);
}

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fhead) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP HEAD requests from clients.

This callback is called by the service dispatcher when an HTTP HEAD request is pending. Redefine this callback to respond to HTTP HEAD requests more specifically. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fhead` is the internal static function `http_200` that returns HTTP 200 OK.

See also
  `::http_opt`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fheader) (struct soap *soap)

Callback to inspect the SOAP Header received before the rest of the message with the SOAP Body is consumed.

This callback is called immediately after parsing a SOAP Header into the `soap::header` structure. The SOAP Header structure `soap::header` can be inspected by this function and verified or rejected before the rest of the message with the SOAP Body is consumed. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fheader`.

See also
  `http_form`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fignore) (struct soap *soap, const char *tag)

Callback to catch unrecognized XML elements and overrides `SOAP_XML_STRICT` validation errors for these.

This callback is called when an unrecognized XML element was encountered on the input that could be ignored depending on some specified logic. The `tag` parameter is the offending XML element tag name string. The callback should return `SOAP_OK` to ignore the element or return an `soap_status` error code such as `SOAP_TAG_MISMATCH` to trigger a validation error. This callback also overrides `mustUnderstand` attributes on unrecognized SOAP Header elements that normally raise faults. It is strongly recommended that the callback returns `SOAP_MUSTUNDERSTAND` when `soap::mustUnderstand` != `0`. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fignore`.

Note
  This callback was not called in gSOAP versions prior to 2.8.54 when `SOAP_XML_STRICT` is set.

See also
  `soap::user`.

Example:

int main()
{
struct soap *soap = soap_new();
soap->fignore = ignore;
... //
}
int ignore(struct soap *soap, const char *tag)
{
// do not ignore mustUnderstand="true"
if (!soap->mustUnderstand)
{
// tags <ns:someElement> can be safely ignored
if (soap_match_tag(soap, tag, "ns:someElement") == SOAP_OK)
return SOAP_OK;
}
return SOAP_MUSTUNDERSTAND;
}

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

void*(* soap::fmalloc) (struct soap *soap, size_t size)

Callback to override dynamic memory allocation and management.

This callback can be used to override memory allocation and management done by `soap_malloc` in C. Memory allocated via this callback will not be managed and not be automatically released by the engine. Instead, the application using this callback should release allocated memory. All allocations done by `soap_malloc` are replaced with a call to `soap::fmalloc`. However, no other allocations, such as `soap_new` and `soap_new_T` for C++ classes, are affected. This callback is therefore not useful for C++ applications. Returns a pointer to dynamically allocated memory or NULL on failure to allocate. No built-in function is assigned to `soap::fmalloc`.

Warning
  Deprecated since 2.8.72. Define `SOAP_MALLOC` and `SOAP_FREE` instead.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  size | number of bytes to allocate

Returns
  pointer to allocated memory or NULL on failure to allocate (out of memory)

size_t(* soap::fmimeread) (struct soap *soap, void *handle, char *buf, size_t len)

Callback to read data in a MIME/MTOM attachment stream.

This callback is called by the engine to read a chunk of attachment data to transmit. The `handle` parameter contains the handle returned by the `soap::fmimereadopen` callback. The `buf` parameter is the buffer of length `len` into which a chunk of data should be written by the callback. The actual amount of data written into the buffer may be less than `len` and this actual amount should be returned by the callback. A return value of zero indicates an error and `soap::error` should be set. The `__size` member variable of the attachment struct/class with data (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members) should be set by the application prior to the serialization of the message with attachments. The value of `__size` indicates the total size of the attachment data to be transmitted. If the `__size` member variable is zero and HTTP chunking is enabled (with `SOAP_IO_CHUNK`), then MIME/MTOM chunked transfers are activated by the engine, which is more flexible since the attachment data size does not need to be determined in advance. To use MIME/MTOM chunked transfers, enable HTTP chunking with `SOAP_IO_CHUNK` (also `SOAP_IO_STORE` can be used, but this buffers the entire message in memory before transmission) and set the `__size` member variable of the attachment struct/class to zero. When MIME/MTOM attachment chunking is enabled, this callback should completely fill the `buf` buffer with `len` bytes unless the last data chunk is reached and fewer bytes are returned.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap::fmimereadopen`, `soap::user`.

Example:

See the example provided with the documentation for `soap::fmimereadopen`.

Parameters

  soap | `soap` context
  handle | the value of the handle returned by `soap::fmimereadopen`
  buf | buffer to fill
  len | length of the buffer in bytes

Returns
  the number of bytes written to the buffer

void(* soap::fmimereadclose) (struct soap *soap, void *handle)

Callback to close a MIME/MTOM attachment stream after reading.

This callback is called by the engine to close the MIME/MTOM attachment stream after reading. The `handle` parameter contains the handle returned by the `soap::fmimereadopen` callback.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap::fmimereadopen`, `soap::user`.

Example:

See the example provided with the documentation for `soap::fmimereadopen`.

Parameters

  soap | `soap` context
  handle | the value of the of the handle returned by `soap::fmimereadopen`

void*(* soap::fmimereadopen) (struct soap *soap, void *, const char *, const char *, const char *)

Callback to open a streaming MIME/MTOM attachment for reading.

This callback is called by the engine to start sending a streaming MIME/MTOM attachment. This callback opens a stream to start reading the attachment data to send. The actual data stream will be read in chunks using the `soap::fmimeread` callback until no more data is available and the `soap::fmimereadclose` callback is called to close the stream. The `handle` parameter contains the value of the `__ptr` member variable of the attachment struct/class with data (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members), which should be a pointer to specific information such as a file descriptor or a pointer to a some application-specific data to be passed to this callback. Both the `__ptr` and `__size` members of the attachment struct/class should have been set by the application prior to the serialization of the message with attachments. If the `__size` is zero and HTTP chunking is enabled (with `SOAP_IO_CHUNK`), then chunked MIME/MTOM attachments are sent, see `soap::fmimeread`. The `id`, `type` and `options` parameters are the `id` (an optional ID), `type` (a MIME type) and `options` (a descriptive string) of the attachment struct/class, respectively, of which at least one member should be non-NULL. The callback should return the `handle` parameter value or another pointer value, which is passed as the new `handle` parameter to `soap::fmimeread` and `soap::fmimereadclose` callbacks. When an error occurred in this callback, the callback should return NULL and set `soap::error` to an error code, e.g. using `soap_receiver_fault`. The callback may return NULL and set `soap::error` to `SOAP_OK` when this specific MIME/MTOM attachment should not to be streamed and the engine will simply skip it.

See also
  `SOAP_ENC_DIME`, `soap::user`.

Example:

void * mime_read_open(struct soap *soap, void *handle, const char *id, const char *type, const char *options)
{
return (void*)fopen((char*)handle, "rb");
}
size_t mime_read(struct soap *soap, void *handle, char *buf, size_t len)
{
return fread(buf, 1, len, (FILE*)handle);
}
void mime_read_close(struct soap *soap, void *handle)
{
fclose((FILE*)handle);
}
struct soap *soap = soap_new1(SOAP_ENC_MTOM);
soap->fmimereadopen = mime_read_open;
soap->fmimeread = mime_read;
soap->fmimereadclose = mime_read_close;
struct _xop__Include data; // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = "Picture.png"; // file name to open for streaming with mime_read_open
data.__size = 1024; // file has 1024 bytes of data
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png"; // attachment type
data.options = "Picture.png"; // we store the file name with the attachment description
... // add data to the message and then send it, which will stream the MIME/MTOM attachment content from Picture.png

To enable chunked MIME/MTOM attachments, replace the last part of the example with:

struct soap *soap = soap_new1(SOAP_IO_CHUNK);
struct _xop__Include data; // here we're using gsoap/import/xop.h to store a blob of raw data
data.__ptr = "Picture.png"; // file name to open for streaming with dime_read_open
data.__size = 0; // zero size means chunked MIME/MTOM attachments are sent
data.id = soap_strdup(soap, soap_rand_uuid(soap, "uuid:")); // attachment id (optional, can use NULL)
data.type = "image/png"; // attachment type
data.options = "Picture.png"; // we store the file name with the attachment description
... // add data to the message and then send it, which will stream the MIME/MTOM attachment content from Picture.png

This mechanism also works for MIME/MTOM attachments that are explicitly attached with `soap_set_mime_attachment`.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap_set_mime_attachment`.

Parameters

  soap | `soap` context
  handle | the value of the `__ptr` member variable of the attachment struct/class with data
  id | the value of the `id` member variable of the attachment struct/class with data
  type | the value of the `type` member variable of the attachment struct/class with data
  options | the value of the `options` member variable of the attachment struct/class with data

Returns
  a handle or NULL when an error occurred (`soap::error` is nonzero) or when the attachment should be skipped (`soap::error` is `SOAP_OK`)

int(* soap::fmimewrite) (struct soap *soap, void *handle, const char *buf, size_t len)

Callback to write data in a MIME attachment stream.

This callback is called by the engine to write a chunk of attachment data received. The `handle` parameter contains the handle returned by the `soap::fmimewriteopen` callback. The `buf` parameter contains the data of length `len`. Returns `SOAP_OK` or a `soap_status` (int) error code.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap::user`.

Parameters

  soap | `soap` context
  handle | the value of the handle returned by `soap::fmimewriteopen`

Returns
  `SOAP_OK` or a `soap_status` error code

void(* soap::fmimewriteclose) (struct soap *soap, void *handle)

Callback to close a MIME/MTOM attachment stream after writing.

This callback is called by the engine to close the MIME/MTOM attachment stream after writing. The `handle` parameter contains the handle returned by the `soap::fmimewriteopen` callback.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap::user`.

Parameters

  soap | `soap` context
  handle | the value of the of the handle returned by `soap::fmimewriteopen`

void*(* soap::fmimewriteopen) (struct soap *soap, void *handle, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding)

Callback to open a streaming MIME/MTOM attachment for writing.

Called by the to start receiving a streaming MIME/MTOM attachment. This callback opens a stream to start writing the attachment data received. The actual data stream will be written in chunks using the `soap::fmimewrite` callback until no more data is available and the `soap::fmimewriteclose` callback is called to close the stream. The `id`, `type` and `options` parameters are the `id`, `type` and `options` of the attachment struct/class (e.g. `xsd__base64Binary` or `_xop__Include` with `__ptr`, `__size`, `id`, `type` and `options` members), respectively. The callback should return a handle, which is passed to the `soap::fmimewrite` and `soap::fmimewriteclose` callbacks. The `__ptr` member variable of the attachment struct/class is set by the engine to the value of this handle. The `__size` member variable is set to the size of the attachment received.

See also
  `SOAP_ENC_MIME`, `SOAP_ENC_MTOM`, `soap::fmimereadopen`, `soap::user`.

Example:

void * mime_write_open(struct soap *soap, const char *id, const char *type, const char *options)
{
if (options)
{
FILE *handle = NULL;
char *name;
size_t len = ((unsigned char)options[2] << 8) | ((unsigned char)options[3]); // get option string length
name = (char*)soap_malloc(soap, len + 1);
strncpy(name, options + 4, len); // get file name from options (as an example)
name[len] = '\0';
handle = fopen(name, "wb");
if (!handle)
{
soap->error = SOAP_EOF; // could not open file for writing
soap->errnum = errno; // to report errno value
return NULL;
}
}
else
{
soap->error = soap_receiver_fault(soap, "Cannot save to file: no file name was present in the attachment", NULL);
}
return (void*)handle;
}
int mime_write(struct soap *soap, void *handle, const char *buf, size_t len)
{
while (len)
{
size_t nwritten = fwrite(buf, 1, len, (FILE*)handle);
if (!nwritten)
{
soap->errnum = errno;
return SOAP_EOF;
}
len -= nwritten;
buf += nwritten;
}
return SOAP_OK;
}
void mime_write_close(struct soap *soap, void *handle)
{
fclose((FILE*)handle);
}
struct soap *soap = soap_new();
soap->fmimewriteopen = mime_write_open;
soap->fmimewrite = mime_write;
soap->fmimewriteclose = mime_write_close;
... // when a service responds to the client request with MIME/MTOM attachment(s), the attachment data is saved via the callbacks

Parameters

  soap | `soap` context
  id | the value of the `id` member variable of the attachment struct/class with data
  type | the value of the `type` member variable of the attachment struct/class with data
  options | the value of the `options` member variable of the attachment struct/class with data

Returns
  a handle or NULL when an error occurred (`soap::error` should be nonzero)

SOAP_SOCKET(* soap::fopen) (struct soap *soap, const char *endpoint, const char *host, int port)

Callback that opens a socket connection to a server endpoint.

This callback is called by the engine at the client-side by `soap_connect` or `soap_connect_command` to open a TCP or UDP connection to a server specified at an endpoint. Parameters `host` and `port` are micro-parsed from `endpoint` before being passed to `soap::fopen`. Returns a valid socket or `SOAP_INVALID_SOCKET` with a `soap::error` set to a `soap_status` (int) error code and `soap::errnum` set to `errno` of the connection failure. The built-in function assigned to `soap::fopen` is `tcp_connect`.

See also
  `soap::faccept`, `soap::user`.

Parameters

  soap | `soap` context
  endpoint | URL of the endpoint to connect to (string)
  host | URL host of the endpoint to connect to (string)
  port | URL port of the endpoint to connect to (int)

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fopt) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP OPTION requests from clients.

Called by the service dispatcher when an HTTP OPTION request is pending. Redefine this callback to respond to HTTP OPTION requests, see the `http_post` HTTP POST plugin for more details. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fopt` is the internal static function `http_200` that returns HTTP 200 OK.

See also
  `http_post`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fparse) (struct soap *soap)

Callback that reads and parses HTTP and MIME headers.

This callback is called by the engine (as a client or server) to read and parse HTTP headers or MIME headers. When redefined, this function should read or skip the entire HTTP header to reach the message body. Function `soap_getline` is used by this callback to read each header line into an internal buffer `soap::msgbuf` with `soap_getline(soap, soap->msgbuf, sizeof(soap->msgbuf))`. Returns `SOAP_OK`, or a gSOAP error code. The built-in function assigned to `soap::fparse` is `http_parse`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

See also
  `soap::fparsehdr`.

int(* soap::fparsehdr) (struct soap *soap, const char *key, const char *val)

Callback that consumes an HTTP header that consists of a key-value pair.

This callback is called by `soap::fparse`, consumes an HTTP header that is split in a key-value pair and updates the `soap` context state accordingly. The context is updated with the HTTP header information received, but HTTP headers are not literally retained by the engine. Returns `SOAP_OK` or `SOAP_STOP` to prevent further reading of the HTTP body, or a `soap_status` (int) error code. The built-in function assigned to `soap::fparsehdr` is `http_parse_header`.

Note
  This callback can be used to parse (custom) HTTP headers, which is typically done by plugins.

See also
  `soap::fparse`, `soap::http_extra_header`, `soap::user`.

Example:

int main()
{
struct soap *soap = soap_new();
soap->user = (void*)soap->fparsehdr; // to call the engine's fparsehdr()
soap->fparsehdr = parse_header;
... //
}
int parse_header(struct soap *soap, const char *key, const char *val)
{
... // use key and val, then pass the key-val to the engine:
return ((int(*)(struct soap*, const char*, const char*))(soap->user))(soap, key, val);
}

Parameters

  soap | `soap` context
  key | HTTP header key received (non-NULL string)
  val | HTTP header value received (non-NULL string) or an empty string

Returns
  `SOAP_OK`, `SOAP_STOP` or a `soap_status` error code

int(* soap::fpatch) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP PATCH requests from clients.

This callback is called by the service dispatcher when an HTTP PATCH request is pending. Redefine this callback to respond to HTTP PATCH requests, see the `http_post` HTTP POST plugin for more details. Returns `SOAP_OK` or a `soap_status` error code. The built-in function assigned to `soap::fpatch` is the internal static function `http_patch` that returns the `SOAP_PATCH_METHOD` error.

See also
  `http_post`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fpoll) (struct soap *soap)

Callback that blocks until activity is detected on the `soap::socket` or `soap::master` socket, times out when `soap::send_timeout` or `soap::recv_timeout` are set.

This callback is called by the engine to wait for activity on the `soap::socket` or `soap::master` socket using `poll` or `select`. Times out when `soap::send_timeout` or `soap::recv_timeout` are nonzero. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fpoll` is `soap_poll`.

See also
  `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fpost) (struct soap *soap, const char *endpoint, const char *host, int port, const char *path, const char *action, ULONG64 count)

Callback that populates and then sends HTTP headers from the client-side to a connected HTTP server.

This callback is called at the client side by the engine to send HTTP headers to the connected server. The parameters `host`, `port`, and `path` were micro-parsed from the `endpoint` prior to passing them to this callback. Parameter `action` is the SOAP Action header. Parameter `count` is the length of the HTTP body with the message or 0 when HTTP chunking is used. This callback sends the headers with POST by default, or when `soap::status` == `SOAP_POST` or `soap::status` == `SOAP_POST_FILE`. Alternatively, sends the HTTP headers with GET when `soap::status` == `SOAP_GET`, PATCH when `soap::status` == `SOAP_PATCH`, PUT when `soap::status` == `SOAP_PUT`, DELETE when `soap::status` == `SOAP_DEL`, CONNECT when `soap::status` == `SOAP_CONNECT`, HEAD when `soap::status` == `SOAP_HEAD` or OPTIONS when `soap::status` == `SOAP_OPTIONS`. Extra HTTP headers are added when `soap::http_extra_header` is set to one or more header lines separated by CRLF. When redefining this callback, use function `soap_send` to write the header contents. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap:fpost` is `http_post`.

Parameters

  soap | `soap` context
  endpoint | URL of the endpoint connected to (string)
  host | URL host of the endpoint connected to (string)
  port | URL port of the endpoint connected to (int)
  path | URL path of the endpoint connected to (string)
  action | SOAP Action or NULL (string)
  count | HTTP content-length or 0 for HTTP chunked transfers (size_t)

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fposthdr) (struct soap *soap, const char *key, const char *val)

Callback that sends a single HTTP header given a key-value pair.

This callback is called by `soap::fpost` and `soap::fresponse` to send an HTTP header with a key and an optional value. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fposthdr` is `http_post_header`.

Parameters

  soap | `soap` context
  key | HTTP header key (string)
  val | optional HTTP header value (string), omitted when NULL

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fput) (struct soap *soap)

Callback to implement logic at the server-side to serve responses to HTTP PUT requests from clients.

This callback is called by the service dispatcher when an HTTP PUT request is pending. Redefine this callback to respond to HTTP PUT requests, see the `http_post` HTTP POST plugin for more details. Returns `SOAP_OK` or a `soap_status` error code. The built-in function assigned to `soap::fput` is the internal static function `http_put` that returns the `SOAP_PUT_METHOD` error.

See also
  `http_post`, `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

size_t(* soap::frecv) (struct soap *soap, char *buf, size_t len)

Callback that receives bytes of data into the given buffer.

This callback is called by the engine to receive (or read) data into a specified buffer `buf` and `len`. The source for the data to read by this callback is `soap::is` when non-NULL, `soap::socket` when valid, or `soap::recvfd`. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::frecv` is `frecv`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  buf | buffer to fill with bytes to be read (string)
  len | maximum size of the buffer (size_t)

Returns
  the nonzero number of bytes that were placed in the buffer or 0 to indicate EOF was reached (size_t)

int(* soap::fresolve) (struct soap *soap, const char *name, struct in_addr *inaddr)

Callback that resolves a host name by address translation.

This callback is called by `soap_bind` (or the C++ service class `bind` method) at the server-side and by `soap_connect` or `soap_connect_command` at the client-side with a host `name` parameter to resolve to address `inaddr` by address translation. When successful sets parameter `inaddr` and returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fresolve` is `tcp_gethost`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  name | host name (string)
  inaddr | points to in_addr structure to set

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fresponse) (struct soap *soap, int status, ULONG64 count)

Callback that populates and then sends HTTP headers from the server-side to a connected client.

This callback is called at the server side by the engine to send the HTTP headers to the connected client. The parameter `status` should be an HTTP status error code or `SOAP_OK` (200 OK) or `SOAP_HTML` or `SOAP_FILE`. Using `SOAP_HTML` sets the content-type header to `text/html; charset=utf-8`. Using `SOAP_FILE` sets the content-type header to the value of `soap::http_content`. Extra HTTP headers are added when `soap::http_extra_header` is set to one or more header lines separated by CRLF. When redefining this callback, use function `soap_send` to write the header contents. Returns `SOAP_OK` or a `soap_status` error code. The built-in function assigned to `soap::fresponse` is `http_response`.

Parameters

  soap | `soap` context
  status | HTTP status code (> 100) or `SOAP_OK` (200 OK), or `SOAP_HTML` or `SOAP_FILE`
  count | HTTP content-length or 0 for HTTP chunked transfers

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fsend) (struct soap *soap, const char *data, size_t len)

Callback that sends the given bytes of data.

This callback is called by the engine to send (or write) data specified by `data` bytes of length `len`. The sink for the data to be sent to is typically `soap::socket`, `soap::sendfd` or `soap::os`. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fsend` is `fsend`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  data | bytes to be send (string)
  len | number of bytes to be send (size_t)

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fserveloop) (struct soap *soap)

Callback executed by the engine at the server side immediately after a server operation successfully completed.

This callback is called after each successful completion of a server operation in the server loop. Executes immediately after sending the response to a client and before the next keep-alive server loop iteration when enabled with `SOAP_IO_KEEPALIVE`. This callback can be used to reclaim resources in the keep-alive server loop, for example managed memory can be reclaimed by calling `soap_destroy` and `soap_end` in that order and all deserialized and other dynamically-allocated data managed by the context will be deallocated. Returns `SOAP_OK` or a `soap_status` (int) error code. No built-in function is assigned to `soap::fserveloop`.

See also
  `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

void(* soap::fseterror) (struct soap *soap, const char **faultcode, const char **faultstring)

Callback to inspect or override fault code or fault string messages.

This callback is called by the engine when an error is raised to allow inspection or overriding of the fault code or fault string messages before the error is reported or transmitted. No built-in function is assigned to `soap::fseterror`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  faultcode | pointer to a string with the fault code message or NULL, can be reassigned
  faultstring | pointer to a string with the fault string message or NULL, can be reassigned

int(* soap::fshutdownsocket) (struct soap *soap, SOAP_SOCKET sock, int how)

Callback that shuts down a given socket.

This callback is called to shut down a socket by the engine. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fshutdownsocket` is `tcp_shutdownsocket`.

See also
  `soap::user`.

Parameters

  soap | `soap` context
  sock | socket to shut down
  how | `SHUT_RD` (=0), `SHUT_WR` (=1) or `SHUT_RDWR` (=2)

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fsslauth) (struct soap *soap)

Callback to initialize the OpenSSL library.

This callback is called to initialize the OpenSSL or GNUTLS context for HTTPS connections configured with the parameters passed to `soap_ssl_client_context` and `soap_ssl_server_context`. Returns `SOAP_OK` or a `soap_status` (int) error code. The built-in function assigned to `soap::fsslauth` is `ssl_auth_init`.

See also
  `soap::user`.

Parameters

  soap | `soap` context

Returns
  `SOAP_OK` or a `soap_status` error code

int(* soap::fsslverify) (int ok, X509_STORE_CTX *store)

Callback to manage the verification of the certificate provided by a peer (typically a server)

This callback is called by the engine to manage the verification of the certificate provided by a peer, such as the certificate provided by a server connected over HTTPS or to verify the certificate included with a WS-Security message. To require certificate verification of a server connected via HTTPS, use `soap_ssl_client_context` with `SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION`. To require certificate verification of a client connected to a server, use `soap_ssl_server_context` with `SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION`. The `ok` parameter of this callback indicates whether the verification of the certificate in question passed (`ok` == 1) or failed (`ok` == 0) as determined by the OpenSSL library based on the `soap_ssl_client_context` or `soap_ssl_server_context` configuration. If the callback returns 1 then the handshake is continued and the connection maybe established. To return 1 when `ok` == 0 requires resetting the error state with `X509_STORE_CTX_set_error(store, X509_V_OK)`. If the callback returns 0 then the handshake is immediately terminated with "verification failed" and a verification failure alert is sent to the peer. The built-in function assigned to `soap::fsslverify` is `ssl_verify_callback` or when `SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE` is used `ssl_verify_callback_allow_expired_certificate`.

See also
  `soap::user`.

Example:

int ssl_verify_callback_allow_self_signed_cert(int ok, X509_STORE_CTX *store)
{
if (!ok && X509_STORE_CTX_get_error(store) == X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN)
{
X509_STORE_CTX_set_error(store, X509_V_OK);
ok = 1;
}
return ok;
}
struct soap *soap = soap_new();
soap->fsslverify = ssl_verify_callback_allow_self_signed_cert;

Parameters

  ok | when 1: the certificate passed, when 0: the certificate did not pass

Returns
  1 to pass and 0 to fail

See also
  `soap_ssl_client_context`.

int(* soap::fsvalidate) (struct soap *soap, const char *pattern, const char *string)

Callback to validate strings against XML regex patterns.

This callback is called to validate a string against an XML regex pattern. Patterns use XML schema regex syntax. This callback allows user-defined pattern validation that is normally disabled. Returns `SOAP_OK` when the string matches the pattern or `SOAP_TYPE` when the string does not match. No built-in function is assigned to `soap::fsvalidate`.

See also
  `soap::fwvalidate`,`soap::user`.

Parameters

  soap | `soap` context
  pattern | regex in XML schema syntax
  string | to match pattern against

Returns
  `SOAP_OK` (match) or `SOAP_TYPE` (mismatch) or a `soap_status` error code

int(* soap::fwvalidate) (struct soap *soap, const char *pattern, const wchar_t *string)

Callback to validate wide strings against XML regex patterns.

This callback is called to validate a wide string against an XML regex pattern. Patterns use XML schema regex syntax. This callback allows user-defined pattern validation that is normally disabled. Returns `SOAP_OK` when the string matches the pattern or `SOAP_TYPE` when the string does not match. No built-in function is assigned to `soap::fwvalidate`.

See also
  `soap::fsvalidate`, `soap::user`.

Parameters

  soap | `soap` context
  pattern | regex in XML schema syntax
  string | to match pattern against

Returns
  `SOAP_OK` (match) or `SOAP_TYPE` (mismatch) or a `soap_status` error code