|  | Home | Documentation | Callback functions updated by Robert van Engelen |

Callback functions

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

## Functions

*Callback to manage the verification of the certificate provided by a | soap::peer (typically a server) int(*fsslverify)(int ok

## Variables

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

## Detailed Description

This module describes 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, GNUTLS and WolfSSL client-side SSL/TLS certificate verification 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.

## Function Documentation

## ◆ peer()

*Callback to manage the verification of the certificate provided by a soap::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;
soap::soap
soap()
Construct a soap context (C++ only, in C use soap_new or soap_init).
soap::store
*Callback to manage the verification of the certificate provided by a X509_STORE_CTX * store
Definition stdsoap2.h:5201

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.

## Variable Documentation

## ◆ faccept

*Callback that waits for and accepts a socket connection requested by a client SOAP_SOCKET(* soap::faccept) (struct soap *soap, SOAP_SOCKET sock, struct sockaddr *addr, int *len)

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

## ◆ fclose

*Callback that closes the current socket connection int(* soap::fclose) (struct soap *soap)

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

## ◆ fclosesocket

*Callback that closes a given socket int(* soap::fclosesocket) (struct soap *soap, SOAP_SOCKET sock)

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

## ◆ fconnect

*Callback that overrides the client side connecting operations int(* soap::fconnect) (struct soap *soap, const char *endpoint, const char *host, int port)

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

## ◆ fdel

*Callback to implement logic at the server side to serve responses to HTTP DELETE requests from clients int(* soap::fdel) (struct soap *soap)

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

## ◆ fdimeread

*Callback to read data in a DIME attachment stream size_t(* soap::fdimeread) (struct soap *soap, void *handle, char *buf, size_t len)

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
soap_strdup
*Copy a string to managed memory char * soap_strdup(struct soap *soap, const char *string) * @returns copy of string or NULL when the specified string is NULL or on failure to allocate(out of memory)
soap_dime_option
char * soap_dime_option(struct soap *soap, unsigned short optype, const char *option)
Creates a DIME option.
SOAP_IO_CHUNK
#define SOAP_IO_CHUNK
soap_mode IO output flag value to send HTTP chunked messages, buffers the message in packets of size ...
Definition stdsoap2.h:1672
soap_rand_uuid
const char * soap_rand_uuid(struct soap *soap, const char *prefix)
Returns a randomized unique UUID string.
_xop__Include
XOP include structure with attachment data.
Definition stdsoap2.h:10091
_xop__Include::__ptr
unsigned char * __ptr
pointer to binary data
Definition stdsoap2.h:10092

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

## ◆ fdimereadclose

*Callback to close a DIME attachment stream after reading void(* soap::fdimereadclose) (struct soap *soap, void *handle)

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

## ◆ fdimereadopen

*Callback to open a streaming DIME attachment for reading void *(* soap::fdimereadopen) (struct soap *soap, void *handle, const char *id, const char *type, const char *options)

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
soap::fopen
*Callback that opens a socket connection to a server endpoint SOAP_SOCKET(* fopen)(struct soap *soap, const char *endpoint, const char *host, int port)
Definition stdsoap2.h:4635
soap::fclose
*Callback that closes the current socket connection int(* fclose)(struct soap *soap)
Definition stdsoap2.h:4660
soap
Context with the engine state.
Definition stdsoap2.h:2929
soap::buf
*Internal buffer with partial data received or partial data to be where the data occupies ::soap::buflen bytes char buf[SOAP_BUFLEN]
Definition stdsoap2.h:4320

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)

## ◆ fdimewrite

*Callback to write data in a DIME attachment stream int(* soap::fdimewrite) (struct soap *soap, void *, const char *, size_t)

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

## ◆ fdimewriteclose

*Callback to close a DIME attachment stream after writing void(* soap::fdimewriteclose) (struct soap *soap, void *handle)

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

## ◆ fdimewriteopen

*Callback to open a streaming DIME attachment for writing void *(* soap::fdimewriteopen) (struct soap *soap, const char *id, const char *type, const char *options)

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
soap_malloc
*Allocate a block of heap memory managed by the specified ::soap context void * soap_malloc(struct soap *soap, size_t len) * @returns pointer to the allocated block of memory or NULL on failure to allocate(out of memory)
SOAP_EOF
#define SOAP_EOF
A soap_status error code: unexpected end of file, no input, transmission interrupted or timed out (sa...
Definition stdsoap2.h:2488
SOAP_OK
#define SOAP_OK
The soap_status code for no error (zero).
Definition stdsoap2.h:2392
soap_receiver_fault
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.

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)

## ◆ fdisconnect

*Callback that executes disconnect logic before closing int(* soap::fdisconnect) (struct soap *soap)

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

## ◆ fencoding

*Callback to catch unrecognized XML encoding formats int(* soap::fencoding) (struct soap *soap, const char *encoding)

This callback is called when an unrecognized XML encoding format is encountered in an XML PI. Supported encoding formats are latin (ASCII) and UTF-8. Other encoding formats can be rejected or supported by setting this callback. To reject the encoding, return a nonzero error code. To accept the encoding without further action, return #SOAP_OK. To decode the encoding, the input stream should be redictected through a decoder, for example by overriding the soap::frecv callback with a specific handler to convert the encoding.

See also
  soap::user and soap::frecv.

Example:

Parameters

  soap | soap context
  encoding | XML encoding extracted from the XML PI header

Returns
  #SOAP_OK or a soap_status error code

## ◆ fform

*Callback to implement logic at the server side to handle HTML such as done by the callbacks provided by the HTTP FORM handler plugin int(* soap::fform) (struct soap *soap)

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

## ◆ fget

*Callback to implement logic at the server side to serve responses to HTTP GET requests from clients int(* soap::fget) (struct soap *soap)

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);
}
SOAP_GET_METHOD
#define SOAP_GET_METHOD
A soap_status error code: an HTTP GET request was received by the service but the GET request callbac...
Definition stdsoap2.h:2520
SOAP_FILE
#define SOAP_FILE
A special soap_status error code to signal that a custom file-based HTTP response is present and no H...
Definition stdsoap2.h:2842
soap_send_raw
*Send raw bytes int soap_send_raw(struct soap *soap, const char *s, size_t n) * @returns `
http_get
*The HTTP GET plugin registration function int http_get(struct soap *, struct soap_plugin *, void *)
soap_response
*Initialize the context for server side sending and send a HTTP response header int soap_response(struct soap *soap, int status) * @returns `
soap_end_send
*Finalize the context after sending int soap_end_send(struct soap *soap) * @returns `
soap::tmpbuf
*Internal buffer to hold temporary strings such as string representations of primitive XML tag HTTP header lines and so must have at least char tmpbuf[SOAP_TMPLEN]
Definition stdsoap2.h:4324
soap::path
char path[SOAP_TAGLEN]
The client request path as received on the server side.
Definition stdsoap2.h:4157
soap::http_content
const char * http_content
String with HTTP content type header value received, can also be assigned to specify a content type h...
Definition stdsoap2.h:3105

Parameters

  soap | soap context

Returns
  #SOAP_OK or a soap_status error code

## ◆ fhead

*Callback to implement logic at the server side to serve responses to HTTP HEAD requests from clients int(* soap::fhead) (struct soap *soap)

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

## ◆ fheader

*Callback to inspect the SOAP Header received before the rest of the message with the SOAP Body is consumed int(* soap::fheader) (struct soap *soap)

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

## ◆ fignore

*Callback to catch unrecognized XML elements and overrides int(* soap::fignore) (struct soap *soap, const char *tag)

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;
}
SOAP_MUSTUNDERSTAND
#define SOAP_MUSTUNDERSTAND
A soap_status error code: an XML element is present with a mustUnderstand attribute which must be und...
Definition stdsoap2.h:2613
soap_match_tag
int soap_match_tag(struct soap *soap, const char *tag1, const char *tag2)
Match an XML tag name.
soap::mustUnderstand
short mustUnderstand
The soap::mustUnderstand flag is set when a SOAP Header element carries a SOAP-ENV:mustUnderstand att...
Definition stdsoap2.h:3086

Parameters

  soap | soap context
  tag | XML tag name

Returns
  #SOAP_OK or a soap_status error code

## ◆ fmalloc

*Callback to override dynamic memory allocation and management void *(* soap::fmalloc) (struct soap *soap, size_t size)

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)

## ◆ fmimeread

*Callback to read data in a MIME MTOM attachment stream size_t(* soap::fmimeread) (struct soap *soap, void *handle, char *buf, size_t len)

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

## ◆ fmimereadclose

*Callback to close a MIME MTOM attachment stream after reading void(* soap::fmimereadclose) (struct soap *soap, void *handle)

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

## ◆ fmimereadopen

*Callback to open a streaming MIME MTOM attachment for reading void *(* soap::fmimereadopen) (struct soap *soap, void *, const char *, const char *, const char *)

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
SOAP_ENC_MTOM
#define SOAP_ENC_MTOM
soap_mode ENC output flag value to enable MTOM XOP attachments in messages to be sent,...
Definition stdsoap2.h:1892

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)

## ◆ fmimewrite

*Callback to write data in a MIME attachment stream int(* soap::fmimewrite) (struct soap *soap, void *handle, const char *buf, size_t len)

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

## ◆ fmimewriteclose

*Callback to close a MIME MTOM attachment stream after writing void(* soap::fmimewriteclose) (struct soap *soap, void *handle)

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

## ◆ fmimewriteopen

*Callback to open a streaming MIME MTOM attachment for writing void *(* soap::fmimewriteopen) (struct soap *soap, void *handle, const char *id, const char *type, const char *description, enum soap_mime_encoding encoding)

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)

## ◆ fopen

*Callback that opens a socket connection to a server endpoint SOAP_SOCKET(* soap::fopen) (struct soap *soap, const char *endpoint, const char *host, int port)

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

## ◆ fopt

*Callback to implement logic at the server side to serve responses to HTTP OPTION requests from clients int(* soap::fopt) (struct soap *soap)

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

## ◆ fparse

*Callback that reads and parses HTTP and MIME headers int(* soap::fparse) (struct soap *soap)

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.

## ◆ fparsehdr

*Callback that consumes an HTTP header that consists of a key value pair int(* soap::fparsehdr) (struct soap *soap, const char *key, const char *val)

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);
}
soap::user
void * user
User-definable variable that may point to user-specified data of any type to pass the data through to...
Definition stdsoap2.h:3084

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

## ◆ fpatch

*Callback to implement logic at the server side to serve responses to HTTP PATCH requests from clients int(* soap::fpatch) (struct soap *soap)

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

## ◆ fpoll

*Callback that blocks until activity is detected on the ::soap::socket or ::soap::master times out when ::soap::send_timeout or ::soap::recv_timeout are set int(* soap::fpoll) (struct soap *soap)

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

## ◆ fpost

*Callback that populates and then sends HTTP headers from the client side to a connected HTTP server int(* soap::fpost) (struct soap *soap, const char *endpoint, const char *host, int port, const char *path, const char *action, ULONG64 count)

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

## ◆ fposthdr

*Callback that sends a single HTTP header given a key value pair int(* soap::fposthdr) (struct soap *soap, const char *key, const char *val)

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

## ◆ fput

*Callback to implement logic at the server side to serve responses to HTTP PUT requests from clients int(* soap::fput) (struct soap *soap)

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

## ◆ frecv

*Callback that receives bytes of data into the given buffer size_t(* soap::frecv) (struct soap *soap, char *buf, size_t len)

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)

## ◆ fresolve

*Callback that resolves a host name by address translation int(* soap::fresolve) (struct soap *soap, const char *name, struct in_addr *inaddr)

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

## ◆ fresponse

*Callback that populates and then sends HTTP headers from the server side to a connected client int(* soap::fresponse) (struct soap *soap, int status, ULONG64 count)

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

## ◆ fsend

*Callback that sends the given bytes of data int(* soap::fsend) (struct soap *soap, const char *data, size_t len)

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

## ◆ fserveloop

*Callback executed by the engine at the server side immediately after a server operation successfully completed int(* soap::fserveloop) (struct soap *soap)

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

## ◆ fseterror

*Callback to inspect or override fault code or fault string messages void(* soap::fseterror) (struct soap *soap, const char **faultcode, const char **faultstring)

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

## ◆ fshutdownsocket

*Callback that shuts down a given socket int(* soap::fshutdownsocket) (struct soap *soap, SOAP_SOCKET sock, int how)

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

## ◆ fsslauth

*Callback to initialize the OpenSSL library int(* soap::fsslauth) (struct soap *soap)

This callback is called to initialize the OpenSSL, GNUTLS, or WolfSSL 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

## ◆ fsvalidate

*Callback to validate strings against XML regex patterns int(* soap::fsvalidate) (struct soap *soap, const char *pattern, const char *string)

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

## ◆ fwvalidate

*Callback to validate wide strings against XML regex patterns int(* soap::fwvalidate) (struct soap *soap, const char *pattern, const wchar_t *string)

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