![]() |
Home | Documentation |
HTTP and IO functions
updated Fri Jan 17 2025 by Robert van Engelen
|
This module defines functions for HTTP operations and functions for receiving and sending data. More...
Macros | |
#define | SOAP_HTML |
A special soap_status error code to signal that a custom HTTP response is present and no HTTP response must be produced. | |
#define | SOAP_FILE |
A special soap_status error code to signal that a custom file-based HTTP response is present and no HTTP response must be produced. | |
#define | SOAP_POST |
HTTP POST command code. | |
#define | SOAP_POST_FILE |
HTTP POST command code with custom content type. | |
#define | SOAP_GET |
HTTP GET command code. | |
#define | SOAP_PUT |
HTTP PUT command code with custom content type. | |
#define | SOAP_DEL |
HTTP DEL command code. | |
#define | SOAP_CONNECT |
HTTP CONNECT command code. | |
#define | SOAP_HEAD |
HTTP HEAD command code. | |
#define | SOAP_OPTIONS |
HTTP OPTIONS command code. | |
#define | SOAP_PATCH |
HTTP PATCH command code with custom content type. |
Typedefs | |
typedef int | soap_http_command |
HTTP command methods for soap_connect_command | |
typedef int32_t | soap_wchar |
Wide char type. |
Functions | |
int | soap_GET (struct soap *soap, const char *endpoint, const char *action) |
HTTP GET content from server. | |
int | soap_PUT (struct soap *soap, const char *endpoint, const char *action, const char *type) |
HTTP PUT content to server. | |
int | soap_PATCH (struct soap *soap, const char *endpoint, const char *action, const char *type) |
HTTP PATCH content to server. | |
int | soap_POST (struct soap *soap, const char *endpoint, const char *action, const char *type) |
HTTP POST content to server. | |
int | soap_DELETE (struct soap *soap, const char *endpoint) |
HTTP DELETE content from server. | |
int | soap_connect_command (struct soap *soap, soap_http_command http_command, const char *endpoint, const char *action) |
Connect to a server. | |
int | soap_connect (struct soap *soap, const char *endpoint, const char *action) |
Connect to a server using HTTP POST. | |
SOAP_SOCKET | soap_bind (struct soap *soap, const char *host, int port, int backlog) |
Bind and listen to a port. | |
SOAP_SOCKET | soap_accept (struct soap *soap) |
Accept a connection with a client. | |
int | soap_serve (struct soap *soap) |
Serve a pending request. | |
int | soap_begin_serve (struct soap *soap) |
Initiates serving a pending client request. | |
int | soap_serve_request (struct soap *soap) |
Process a pending request. | |
int | soap_response (struct soap *soap, int status) |
Initialize the context for server-side sending and send a HTTP response header. | |
int | soap_begin_recv (struct soap *soap) |
Initialize the context for receiving. | |
int | soap_end_recv (struct soap *soap) |
Finalize the context after receiving. | |
int | soap_begin_send (struct soap *soap) |
Initialize the context for sending. | |
int | soap_end_send (struct soap *soap) |
Finalize the context after sending. | |
int | soap_begin_count (struct soap *soap) |
Initialize context to count message length for sending. | |
int | soap_end_count (struct soap *soap) |
Finalize context to count message length for sending. | |
int | soap_closesock (struct soap *soap) |
Close the socket connection. | |
int | soap_force_closesock (struct soap *soap) |
Forcibly close the socket connection. | |
void | soap_close_connection (struct soap *soap) |
Close the connection of the specified context using a self-pipe. | |
int | soap_send (struct soap *soap, const char *s) |
Send a string. | |
int | soap_send_raw (struct soap *soap, const char *s, size_t n) |
Send raw bytes. | |
int | soap_http_has_body (struct soap *soap) |
Check if HTTP body message is not empty. | |
char * | soap_http_get_body (struct soap *soap, size_t *len) |
Get the HTTP body message as a string. | |
int | soap_getline (struct soap *soap, char *buf, int len) |
Get a header line. | |
soap_wchar | soap_get0 (struct soap *soap) |
Get next byte without consuming it. | |
soap_wchar | soap_get1 (struct soap *soap) |
Get next byte. | |
int | soap_poll (struct soap *soap) |
Poll the connection. | |
int | soap_ready (struct soap *soap) |
Check if the connection is ready to receive pending data. | |
int | soap_recv_empty_response (struct soap *soap) |
Receive an HTTP response message from the server that is assumed to be empty. | |
int | soap_send_empty_response (struct soap *soap, int status) |
Return an HTTP response message with an empty HTTP body from a service back to the client or peer. | |
int | soap_envelope_begin_in (struct soap *soap) |
Parse the XML <SOAP-ENV:Envelope> element opening tag if present. | |
int | soap_envelope_end_in (struct soap *soap) |
Parse the XML </SOAP-ENV:Envelope> element closing tag if present. | |
int | soap_envelope_begin_out (struct soap *soap) |
Emit the XML <SOAP-ENV:Envelope> element opening tag if soap::version is nonzero. | |
int | soap_envelope_end_out (struct soap *soap) |
Emit the XML </SOAP-ENV:Envelope> element closing tag if soap::version is nonzero. | |
int | soap_body_begin_in (struct soap *soap) |
Parse the XML <SOAP-ENV:Body> element opening tag if present. | |
int | soap_body_end_in (struct soap *soap) |
Parse the XML </SOAP-ENV:Body> element closing tag if present. | |
int | soap_body_begin_out (struct soap *soap) |
Emit the XML <SOAP-ENV:Body> element opening tag if soap::version is nonzero. | |
int | soap_body_end_out (struct soap *soap) |
Emit the XML </SOAP-ENV:Body> element closing tag if soap::version is nonzero. | |
int | soap_recv_fault (struct soap *soap, int check) |
Parse and deserialize the SOAP Fault. | |
int | soap_send_fault (struct soap *soap) |
Return an HTTP error with a SOAP Fault message from a service. | |
int | soap_recv_header (struct soap *soap) |
Parse and deserialize the SOAP Header. | |
int | soap_putheader (struct soap *soap) |
Emit the SOAP Header pointed to by soap::header | |
void | soap_serializeheader (struct soap *soap) |
Serialize the SOAP Header pointed to by soap::header before emitting it with soap_putheader | |
int | http_get (struct soap *, struct soap_plugin *, void *) |
The HTTP GET plugin registration function. | |
void | soap_http_get_stats (struct soap *soap, size_t *stat_get, size_t *stat_post, size_t *stat_fail, size_t **hist_min, size_t **hist_hour, size_t **hist_day) |
Collect access statistics with the http_get plugin. | |
char * | soap_query (struct soap *soap) |
Extract the query string from the URL path at the server side with the http_get plugin. | |
char * | soap_query_key (struct soap *soap, char **query) |
Extract the next query string key at the server side with the http_get plugin. | |
char * | soap_query_val (struct soap *soap, char **query) |
Extract the next query string value at the server side with the http_get plugin. | |
int | http_post (struct soap *, struct soap_plugin *, void *) |
The HTTP POST plugin registration function. | |
int | http_form (struct soap *, struct soap_plugin *, void *) |
The HTTP POST form plugin registration function. | |
char * | soap_http_get_form (struct soap *soap) |
Get the HTTP POST application/x-www-form-urlencoded data as a string. | |
int | http_pipe (struct soap *, struct soap_plugin *, void *) |
The HTTP pipelining plugin registration function. |
This module defines functions for HTTP operations and functions for receiving and sending data.
This module defines the following client-side functions:
This module defines the following server-side functions:
This module defines the following input/output functions:
This module defines the following SOAP message input/output functions:
This module defines three HTTP-related plugins;
#define SOAP_CONNECT |
HTTP CONNECT command code.
This code is to be used with soap_connect_command.
#define SOAP_DEL |
HTTP DEL command code.
This code is to be used with soap_connect_command. The soap_DELETE performs the same operation as soap_connect_command with #SOAP_DEL. soap_DELETE is recommended.
#define SOAP_FILE |
A special soap_status error code to signal that a custom file-based HTTP response is present and no HTTP response must be produced.
This code is used with soap_response to return a file-based response message with a HTTP content type specified by the soap::http_content string variable. The soap_response function normally returns HTTP 200 OK, but the HTTP status code can be specified as #SOAP_FILE + status where status is a HTTP status code between 200 and 599.
#define SOAP_GET |
HTTP GET command code.
This code is to be used with soap_connect_command. The soap_GET performs the same operation as soap_connect_command with #SOAP_GET. soap_GET is recommended.
#define SOAP_HEAD |
HTTP HEAD command code.
This code is to be used with soap_connect_command.
#define SOAP_HTML |
A special soap_status error code to signal that a custom HTTP response is present and no HTTP response must be produced.
This code is used with soap_response to return a HTML response message with a HTTP content type "text/html".
#define SOAP_OPTIONS |
HTTP OPTIONS command code.
This code is to be used with soap_connect_command.
#define SOAP_PATCH |
HTTP PATCH command code with custom content type.
This code is to be used with soap_connect_command and requires soap::http_content to be set to the content type of the data to be sent. The soap_PATCH function performs the same operation as soap_connect_command with #SOAP_PATCH. soap_PATCH is recommended.
#define SOAP_POST |
HTTP POST command code.
This code is to be used with soap_connect_command and produces HTTP content type text/xml; charset=utf-8. Use code #SOAP_POST_FILE to customize the content type by setting soap::http_content. Before calling soap_connect_command, either the HTTP content length soap::count must be determined with soap_begin_count and soap_end_count, or the mode of the context should be set to #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE. The soap_POST function performs the same operation as soap_connect_command with #SOAP_POST_FILE and sets the context mode to #SOAP_IO_STORE when required. soap_POST is recommended.
#define SOAP_POST_FILE |
HTTP POST command code with custom content type.
This code is to be used with soap_connect_command and requires soap::http_content to be set to the content type of the data to be sent. Before calling soap_connect_command, either the HTTP content length soap::count must be determined with soap_begin_count and soap_end_count, or the mode of the context should be set to #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE. The soap_POST function performs the same operation as soap_connect_command with #SOAP_POST_FILE and sets the context mode to #SOAP_IO_STORE when required. soap_POST is recommended.
#define SOAP_PUT |
HTTP PUT command code with custom content type.
This code is to be used with soap_connect_command and requires soap::http_content to be set to the content type of the data to be sent. The soap_PUT performs the same operation as soap_connect_command with #SOAP_PUT and is recommended.
typedef int soap_http_command |
HTTP command methods for soap_connect_command
The choice of options are: #SOAP_CONNECT #SOAP_DEL #SOAP_GET #SOAP_HEAD #SOAP_OPTIONS #SOAP_PATCH #SOAP_POST_FILE #SOAP_POST #SOAP_PUT
typedef int32_t soap_wchar |
Wide char type.
int http_form | ( | struct soap * | , |
struct soap_plugin * | , | ||
void * | ) |
The HTTP POST form plugin registration function.
This function is used to register the http_form HTTP POST form plugin to handle application/x-www-form-urlencoded data with soap_register_plugin_arg(soap, http_form, http_form_handler) where the http_form_handler is a function to parse the application/x-www-form-urlencoded data received by the server. The HTTP POST form plugin API is declared and defined in gsoap/plugin/httpform.h and gsoap/plugin/httpform.c.
Handling multipart/related and multipart/form-data at the server side is done by iterating over the soap_multipart linked list containing the MIME attachments received, see the detailed description of MIME attachment functions.
int http_get | ( | struct soap * | , |
struct soap_plugin * | , | ||
void * | ) |
The HTTP GET plugin registration function.
This function is used to register the http_get HTTP GET plugin with soap_register_plugin_arg(soap, http_get, http_get_handler) where the http_get_handler is a user-defined function to handle HTTP GET requests. The HTTP GET plugin API is declared and defined in gsoap/plugin/httpget.h and gsoap/plugin/httpget.c. The soap::path string contains the URL path, starting with a leading /.
int http_pipe | ( | struct soap * | , |
struct soap_plugin * | , | ||
void * | ) |
The HTTP pipelining plugin registration function.
This function is used to register the http_pipe HTTP pipelining plugin to support HTTP pipelining. HTTP pipelining requires #SOAP_IO_KEEPALIVE enabled. At the server side, multiple threads should be used to serve requests, such as with a gSOAP multi-threaded stand-alone server. HTTP pipelining at the client side requires two threads, one to send request messages and one to receive the response messages, with logic to handle transmission errors and to resend failed request messages until all responses have been received.
int http_post | ( | struct soap * | , |
struct soap_plugin * | , | ||
void * | ) |
The HTTP POST plugin registration function.
This function is used to register the http_post HTTP POST plugin with soap_register_plugin_arg(soap, http_post, http_post_handler) where the http_post_handler is a table of HTTP POST handler functions and generic POST, PUT, PATCH, and DELETE handler functions. The HTTP POST plugin API is declared and defined in gsoap/plugin/httppost.h and gsoap/plugin/httppost.c.
SOAP_SOCKET soap_accept | ( | struct soap * | soap | ) |
Accept a connection with a client.
This function accepts a connection requested by a client on a given port that is bound with soap_bind first to set soap::master. To accept HTTPS connections, call soap_ssl_accept after this function to perform the HTTPS handshake with the client. Returns the soap::socket connected to the client or the invalid socket handle #SOAP_INVALID_SOCKET when an error occurred.
In addition, HTTP keep-alive connections with HTTP chunked messages are enabled with struct soap *soap = soap_new1(SOAP_IO_CHUNK | SOAP_IO_KEEPALIVE). HTTP keep-alive should only be enabled with multi-threaded gsoap services.
soap | soap context |
int soap_begin_count | ( | struct soap * | soap | ) |
Initialize context to count message length for sending.
This function is used to determine the HTTP content length. This is done by sending the message after calling this function to update soap::count. To activate message length counting the #SOAP_IO_LENGTH mode is enabled, which prevents the message from being sent by not passing the data to the (internal) soap::fsend callback. HTTP requires either the HTTP content length header or HTTP transfer encoding chunked with #SOAP_IO_CHUNK. Alternatively, the mode of the context can be set to #SOAP_IO_STORE to buffer the entire message in memory to determine the message content length.
Same examples but using HTTP transfer encoding chunked:
soap | soap context |
int soap_begin_recv | ( | struct soap * | soap | ) |
Initialize the context for receiving.
This function should be called to initialize the context for receiving a message or to begin parsing a document. This function is called in the server and client-side code generated by soapcpp2, and in the generated soap_T_read functions to deserialize data of type T. For example, it is called by soap_serve (via soap_begin_serve) at the server side when a client request is pending. This function parses HTTP, DIME, MIME and SOAP headers if present and updates the context with the engine state. Therefore, this function should not be called more than once to initialize the context for receiving. The source of the data read is soap::is when non-NULL, or soap::socket when valid, or soap::recvfd. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
int soap_begin_send | ( | struct soap * | soap | ) |
Initialize the context for sending.
This function should be called to initialize the context for sending a message or to write a document. This function is called in the server and client-side code generated by soapcpp2, and in the generated soap_T_write functions to serialize data of type T. For example, it is called by soap_connect (via soap_connect_command) at the client side when a client connects to a server to send the HTTP headers and message body. The destination of the data to be send is soap::socket when valid, or soap::sendfd when nonzero or soap::os when non-NULL. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
int soap_begin_serve | ( | struct soap * | soap | ) |
Initiates serving a pending client request.
This function processes the HTTP headers and XML SOAP headers if present of the pending request on soap::socket or on standard input/output soap::recvfd and soap::sendfd, e.g. for CGI and FastCGI services. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
SOAP_SOCKET soap_bind | ( | struct soap * | soap, |
const char * | host, | ||
int | port, | ||
int | backlog ) |
Bind and listen to a port.
This function binds to the specified port and starts listening for client requests. The host parameter when non-NULL is the name of the host on which this service runs. The port parameter is the port number to bind, which must not be in use by another service. The call may also fail if the port was recently in use by this service. Use SO_REUSEADDR with soap::bind_flags to immediately reuse the port, but use this option with caution to prevent "port stealing" attacks. The backlog parameter is used with listen, which defines the maximum length for the queue of pending connections. If a connection request arrives with the queue full, the client may receive an error with an indication of ECONNREFUSED or a connection reset. Alternatively, if the underlying protocol supports retransmission, the request may be ignored so that retries may succeed. Returns the soap::master socket bound to the port or the invalid socket handle #SOAP_INVALID_SOCKET when an error occurred.
This function effectively deployes a stand-alone server on the specified port. There are three other alternatives for deploying services:
soap | soap context |
host | name of the host or NULL |
port | port number to bind |
backlog | maximum queue length of pending requests |
int soap_body_begin_in | ( | struct soap * | soap | ) |
Parse the XML <SOAP-ENV:Body> element opening tag if present.
soap | soap context |
int soap_body_begin_out | ( | struct soap * | soap | ) |
Emit the XML <SOAP-ENV:Body> element opening tag if soap::version is nonzero.
soap | soap context |
int soap_body_end_in | ( | struct soap * | soap | ) |
Parse the XML </SOAP-ENV:Body> element closing tag if present.
soap | soap context |
int soap_body_end_out | ( | struct soap * | soap | ) |
Emit the XML </SOAP-ENV:Body> element closing tag if soap::version is nonzero.
soap | soap context |
void soap_close_connection | ( | struct soap * | soap | ) |
Close the connection of the specified context using a self-pipe.
This function closes the connection of the specified context, i.e. when it hangs on socket IO and the specified soap::recv_timeout and soap::send_timeout timeouts are not sufficient to release the blocking socket IO. This function force-closes a connection, which is typically done by another thread that detects a termination condition. Requires compilation with #WITH_SELF_PIPE and requires soap::recv_timeout set to a nonzero timeout value.
Alternatively, #THREAD_CANCEL can be used with a thread cleanup function added with pthread_cleanup_push. See #THREAD_CANCEL for details.
soap | soap context |
int soap_closesock | ( | struct soap * | soap | ) |
Close the socket connection.
This function should be called to close soap::socket. The socket is closed and soap::socket is set to #SOAP_INVALID_SOCKET if the socket is valid, keep-alive is not enabled and not currently active, i.e. the socket is closed when soap::socket != #SOAP_INVALID_SOCKET and soap::keep_alive == 0. Therefore, this function keeps the socket connection open when keep-alive is currently active. This function may be called multiple times but closes the socket just once if the socket connection was open. This function is called in the server and client-side code generated by soapcpp2. Returns the current value of soap::error to propagate the error state when used as return soap_closesock(soap);.
soap | soap context |
int soap_connect | ( | struct soap * | soap, |
const char * | endpoint, | ||
const char * | action ) |
Connect to a server using HTTP POST.
This function connects to the server specified by the endpoint URL string, using HTTP POST and the HTTP SOAP Action header specified by the action string (or NULL). Upon successful completion, messages can be sent to and/or received from the server.
In addition, HTTP keep-alive connections can be enabled with struct soap *soap = soap_new1(SOAP_IO_CHUNK | SOAP_IO_KEEPALIVE).
soap | soap context |
endpoint | URL string |
action | SOAP Action string or NULL |
int soap_connect_command | ( | struct soap * | soap, |
soap_http_command | http_command, | ||
const char * | endpoint, | ||
const char * | action ) |
Connect to a server.
This function connects to the server specified by the endpoint URL string, using the HTTP method specified by the http_command with a soap_http_command value and using the HTTP SOAP Action header specified by the action string (or NULL). Before calling soap_connect_command with #SOAP_POST, #SOAP_POST_FILE, #SOAP_PATCH or #SOAP_PUT, either the HTTP content length soap::count must be determined with soap_begin_count and soap_end_count, or the mode of the context should be set to #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE. ALso for HTTP methods #SOAP_POST, #SOAP_POST_FILE, #SOAP_PATCH and #SOAP_PUT the soap::http_content string should be set before calling soap_connect_command. Upon successful completion of this function, messages can be sent to and/or received from the server. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
http_command | soap_http_command with HTTP method code |
endpoint | URL string |
action | SOAP Action string or NULL |
int soap_DELETE | ( | struct soap * | soap, |
const char * | endpoint ) |
HTTP DELETE content from server.
This function connects to the server specified by the endpoint URL string, using HTTP DELETE. No messages are sent and received. Returns #SOAP_OK or a soap_status error code.
To implement server-side HTTP DELETE handling use soap::fdel.
soap | soap context |
endpoint | URL string |
int soap_end_count | ( | struct soap * | soap | ) |
Finalize context to count message length for sending.
This function is used to determine the HTTP content length. This is done by sending the message after calling this function to update soap::count. HTTP requires either the HTTP content length header or HTTP transfer encoding chunked with #SOAP_IO_CHUNK. Alternatively, the mode of the context can be set to #SOAP_IO_STORE to buffer the entire message in memory to determine the message content length.
soap | soap context |
int soap_end_recv | ( | struct soap * | soap | ) |
Finalize the context after receiving.
This function should be called to finalize the context after receiving a message or to end parsing a document. This function is called in the server and client-side code generated by soapcpp2, and in the generated soap_T_read functions to deserialize data of type T. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
int soap_end_send | ( | struct soap * | soap | ) |
Finalize the context after sending.
This function should be called to finalize the context after sending a message or to end writing a document. This function is called in the server and client-side code generated by soapcpp2, and in the generated soap_T_write functions to serialize data of type T. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
int soap_envelope_begin_in | ( | struct soap * | soap | ) |
Parse the XML <SOAP-ENV:Envelope> element opening tag if present.
soap | soap context |
int soap_envelope_begin_out | ( | struct soap * | soap | ) |
Emit the XML <SOAP-ENV:Envelope> element opening tag if soap::version is nonzero.
soap | soap context |
int soap_envelope_end_in | ( | struct soap * | soap | ) |
Parse the XML </SOAP-ENV:Envelope> element closing tag if present.
soap | soap context |
int soap_envelope_end_out | ( | struct soap * | soap | ) |
Emit the XML </SOAP-ENV:Envelope> element closing tag if soap::version is nonzero.
soap | soap context |
int soap_force_closesock | ( | struct soap * | soap | ) |
Forcibly close the socket connection.
This function immediately closes soap::socket and should only be used when soap_closesock does not suffice. By contrast, soap_closesock gently finalizes the SSL connection, and when soap::keep_alive == 0 calls shutdown and close on soap::socket. By calling soap_force_closesock the socket is forcibly closed immediately and soap::socket is set to #SOAP_INVALID_SOCKET, even when keep-alive is currently active. This function may be called multiple times but closes the socket just once if the socket connection was open. Returns the current value of soap::error to propagate the error state when used as return soap_force_closesock(soap);.
soap | soap context |
int soap_GET | ( | struct soap * | soap, |
const char * | endpoint, | ||
const char * | action ) |
HTTP GET content from server.
This function connects to the server specified by the endpoint URL string, using HTTP GET and the HTTP SOAP Action header specified by the action string (or NULL). This call should be followed by soap_end_send to send an empty HTTP body. Upon successful completion, messages can be received from the server. Returns #SOAP_OK or a soap_status error code.
This function is used by the soapcpp2-generated soap_GET_T functions for types T to HTTP GET the XML deserialized value of type T from a server.
To implement server-side HTTP GET handling use soap::fget.
soap | soap context |
endpoint | URL string |
action | SOAP Action string or NULL |
soap_wchar soap_get0 | ( | struct soap * | soap | ) |
Get next byte without consuming it.
This function returns the next byte on the input without consuming it, i.e. peeks one byte ahead. Reads a byte from soap::is when non-NULL, or from soap::socket when valid, or from soap::recvfd. Returns the next byte or EOF when an error occurred and sets soap::error to a soap_status value and soap::errnum to the errno value of the failure.
soap | soap context |
soap_wchar soap_get1 | ( | struct soap * | soap | ) |
Get next byte.
This function returns the next byte on the input. Reads a byte from soap::is when non-NULL, or from soap::socket when valid, or from soap::recvfd. Returns the next byte or EOF when an error occurred and sets soap::error to a soap_status value and soap::errnum to the errno value of the failure.
soap | soap context |
int soap_getline | ( | struct soap * | soap, |
char * | buf, | ||
int | len ) |
Get a header line.
This function stores a header line into the specified buffer buf of maxiumum length len. This function should be used to read HTTP and MIME headers, which end with CRLF or LF. The function handles header continuations (indents). This function reads input from soap::is when non-NULL, or from soap::socket when valid, or from soap::recvfd. Returns #SOAP_OK or a soap_status error code.
soap | soap context |
buf | buffer to fill (string) |
len | maximum size of the buffer (int) |
char * soap_http_get_body | ( | struct soap * | soap, |
size_t * | len ) |
Get the HTTP body message as a string.
This function parses an HTTP body message into a string, whether or not an HTTP body message is present. This function should be called immediately after calling soap_begin_recv. Note that soap_begin_recv is called at the server side before a HTTP callback is called, such as soap::fput and soap::fpatch. Callbacks and the http_post HTTP POST plugin handlers should therefore not call soap_begin_recv. Also, soap_begin_recv is called at the client side by HTTP functions such as soap_GET, after which the HTTP body can then be then be checked with soap_http_has_body and retrieved with soap_http_get_body. This function reads input from from soap::is when non-NULL, or soap::socket when valid, or from soap::recvfd, and sets the len pointer parameter to the length of the string read if len is not NULL. After calling this function, soap_end_recv should be called. Returns the HTTP body as a string allocated in managed memory or returns "" (empty string, since version 2.8.71 or returns NULL for previous versions) when no HTTP message body is present or NULL when an error occurred and sets soap::error.
soap | soap context |
len | pointer to the length variable to assign or NULL |
char * soap_http_get_form | ( | struct soap * | soap | ) |
Get the HTTP POST application/x-www-form-urlencoded data as a string.
This function parses an HTTP body with application/x-www-form-urlencoded data into a string, prepends a ?, and returns this string allocated in managed memory or NULL when an error occurred and sets soap::error.
soap | soap context |
void soap_http_get_stats | ( | struct soap * | soap, |
size_t * | stat_get, | ||
size_t * | stat_post, | ||
size_t * | stat_fail, | ||
size_t ** | hist_min, | ||
size_t ** | hist_hour, | ||
size_t ** | hist_day ) |
Collect access statistics with the http_get plugin.
This function sets the specified minutes, hour, and day parameters to point to an array of requests per minute, an array of request per hour, and an array of requests per day of the year. The minutes array has 60 entries, the hour array has 24 entries, and the day array has 365 entries (a leap year will roll over). The plugin will collect the stats among a set of server threads if the spawned thread contexts are created with soap_copy.
soap | soap context |
stat_get | points to a variable to assign the number of GET requests |
stat_post | points to a variable to assign the number of POST requests |
stat_fail | points to a variable to assign the number of failed requests |
hist_min | points to a pointer to an array of 60 entries with histogram of requests per minute |
hist_hour | points to a pointer to an array of 24 entries with histogram of requests per hour |
hist_day | points to a pointer to an array of 365 entries with histogram of requests per day |
int soap_http_has_body | ( | struct soap * | soap | ) |
Check if HTTP body message is not empty.
This function returns nonzero if an HTTP message body is present, zero otherwise. This function should be called immediately after calling soap_begin_recv. Note that soap_begin_recv is called at the server side before a HTTP callback is called, such as soap::fput and soap::fpatch. Callbacks and the http_post HTTP POST plugin handlers should therefore not call soap_begin_recv. Also, soap_begin_recv is called at the client side by HTTP functions such as soap_GET, after which the HTTP body can then be checked with soap_http_has_body and retrieved with soap_http_get_body.
soap | soap context |
int soap_PATCH | ( | struct soap * | soap, |
const char * | endpoint, | ||
const char * | action, | ||
const char * | type ) |
HTTP PATCH content to server.
This function connects to the server specified by the endpoint URL string, using HTTP PATCH and the HTTP SOAP Action header specified by the action string (or NULL). The HTTP content type of the data sent to the server is specified by type. If the mode is not #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE then this function temporarily sets the mode of the context to #SOAP_IO_STORE to compute the HTTP content length. Upon successful completion, messages can be sent to the server and an empty response should be received by calling soap_recv_empty_response. Returns #SOAP_OK or a soap_status error code.
If the soap::http_content string is non-NULL, this string is used as the HTTP content type to be included in the HTTP header. Otherwise, the HTTP content header is text/xml by default. The soap::http_content string is automatically reset to NULL after the HTTP POST call and has to be set again for the next call.
This function is used by the soapcpp2-generated soap_PATCH_T functions for types T to HTTP PATCH the XML serialized value of type T to a server.
To implement server-side HTTP PATCH handling use soap::fpatch.
soap | soap context |
endpoint | URL string |
action | SOAP Action string or NULL |
type | HTTP content type string |
int soap_poll | ( | struct soap * | soap | ) |
Poll the connection.
This function returns #SOAP_OK if the connection is ready to send and receive data, #SOAP_EOF otherwise. Also returns #SOAP_OK if the socket connection is closed but data can still be read or written from/to other streams.
soap | soap context |
int soap_POST | ( | struct soap * | soap, |
const char * | endpoint, | ||
const char * | action, | ||
const char * | type ) |
HTTP POST content to server.
This function connects to the server specified by the endpoint URL string, using HTTP POST and the HTTP SOAP Action header specified by the action string (or NULL). The HTTP content type of the data sent to the server is specified by type. If the mode is not #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE then this function temporarily sets the mode of the context to #SOAP_IO_STORE to compute the HTTP content length. Upon successful completion, messages can be sent to and received from the server. Returns #SOAP_OK or a soap_status error code.
If the soap::http_content string is non-NULL, this string is used as the HTTP content type to be included in the HTTP header. Otherwise, the HTTP content header is text/xml by default. The soap::http_content string is automatically reset to NULL after the HTTP POST call and has to be set again for the next call.
This function is used by the soapcpp2-generated soap_POST_send_T functions for types T to HTTP POST the XML serialized value of type T to a server. Use soap_POST_recv_T to receive a HTTP POST response deserialized into a value of (another) type T.
soap | soap context |
endpoint | URL string |
action | SOAP Action string or NULL |
type | HTTP content type string |
int soap_PUT | ( | struct soap * | soap, |
const char * | endpoint, | ||
const char * | action, | ||
const char * | type ) |
HTTP PUT content to server.
This function connects to the server specified by the endpoint URL string, using HTTP PUT and the HTTP SOAP Action header specified by the action string (or NULL). The HTTP content type of the data sent to the server is specified by type. If the mode is not #SOAP_IO_CHUNK (preferred) or #SOAP_IO_STORE then this function temporarily sets the mode of the context to #SOAP_IO_STORE to compute the HTTP content length. Upon successful completion, messages can be sent to the server and an empty response should be received by calling soap_recv_empty_response. Returns #SOAP_OK or a soap_status error code.
If the soap::http_content string is non-NULL, this string is used as the HTTP content type to be included in the HTTP header. Otherwise, the HTTP content header is text/xml by default. The soap::http_content string is automatically reset to NULL after the HTTP POST call and has to be set again for the next call.
This function is used by the soapcpp2-generated soap_PUT_T functions for types T to HTTP PUT the XML serialized value of type T to a server.
To implement server-side HTTP PUT handling use soap::fput.
soap | soap context |
endpoint | URL string |
action | SOAP Action string or NULL |
type | HTTP content type string |
int soap_putheader | ( | struct soap * | soap | ) |
Emit the SOAP Header pointed to by soap::header
soap | soap context |
char * soap_query | ( | struct soap * | soap | ) |
Extract the query string from the URL path at the server side with the http_get plugin.
At the server side the value soap::path is set to the URL's path string which may include a query string of the form "?key=val&key=val" with a sequence of key=val pairs, where the value is optional. Returns the query string or NULL when none is present. To extract the keys and values from the string returned by this function, use soap_query_key and soap_query_val.
The http_get plugin sets a HTTP GET handler function to serve HTTP GET requests (or NULL to remove a handler) with soap_register_plugin_arg(soap, http_get, http_get_handler) and keeps track of the number of GET and POST invocations made and the number of server requests by the minute, by the hour, and by the day.
soap | soap context |
char * soap_query_key | ( | struct soap * | soap, |
char ** | query ) |
Extract the next query string key at the server side with the http_get plugin.
This function takes a pointer to the string variable returned by soap_query and updates it to point to the value (if present), then returns the query key or NULL if no more query key-value pairs are present in the query string.
soap | soap context |
query | points to the string returned by soap_query and soap_query_val |
char * soap_query_val | ( | struct soap * | soap, |
char ** | query ) |
Extract the next query string value at the server side with the http_get plugin.
This function takes a pointer to the string variable returned by soap_query and updates it to point to the next key (if present), then returns the query value or NULL if no value is bound to the key.
soap | soap context |
query | points to the string returned by soap_query and soap_query_key |
int soap_ready | ( | struct soap * | soap | ) |
Check if the connection is ready to receive pending data.
This function returns #SOAP_OK if the connection is ready to receive pending data, #SOAP_EOF otherwise. Also returns #SOAP_OK if the socket connection is closed but data can still be read from other streams.
soapcpp2 -c file.h
soap | soap context |
int soap_recv_empty_response | ( | struct soap * | soap | ) |
Receive an HTTP response message from the server that is assumed to be empty.
This function receives an HTTP response message from the server and is typically used when HTTP 202 Accepted or HTTP 200 OK is expected without data. Therefore the HTTP response message body is assumed to be empty. If the message is not empty then a fault message with the HTTP body as the fault string will be produced and the soap::error is set to the HTTP status code received. This function reads input from soap::is when non-NULL, or from soap::socket when valid, or from soap::recvfd. Returns #SOAP_OK or a soap_status error code such as the HTTP status code received.
soap | soap context |
int soap_recv_fault | ( | struct soap * | soap, |
int | check ) |
Parse and deserialize the SOAP Fault.
This function parses and deserializes the SOAP Fault such that soap::fault points to a SOAP_ENV__Fault structure. If the specified check parameter is nonzero, this function attempts to parse the SOAP Fault that may be present (it checks), but if no SOAP-ENV:Fault element is present returns #SOAP_OK. If the specified check parameter is zero, this function parses the SOAP Fault that is expected to be present, but if SOAP-ENV:Fault element is present returns the HTTP error code received (when between 300 and 599) or the soap::error code.
soap | soap context |
check | flag to check or expect a SOAP Fault |
int soap_recv_header | ( | struct soap * | soap | ) |
Parse and deserialize the SOAP Header.
This function parses and deserializes the SOAP Header such that soap::header points to a SOAP_ENV__Header structure.
soap | soap context |
int soap_response | ( | struct soap * | soap, |
int | status ) |
Initialize the context for server-side sending and send a HTTP response header.
This function initializes the context for sending at the server side and sends a HTTP response header with the specified status code. The status code parameter controls the behavior of the HTTP header sent and how the message should be send after calling this function:
Besides soap_response, other options to return a HTTP status code are:
soap | soap context |
status | HTTP status code 200 to 599 or #SOAP_OK (same as 200 OK) or #SOAP_HTML or #SOAP_FILE |
int soap_send | ( | struct soap * | soap, |
const char * | s ) |
Send a string.
This function sends a 0-terminated string to soap::os when non-NULL, or to soap::socket when valid, or or to soap::sendfd when nonzero.
soap | soap context |
s | 0-terminated string to send |
int soap_send_empty_response | ( | struct soap * | soap, |
int | status ) |
Return an HTTP response message with an empty HTTP body from a service back to the client or peer.
This function sends an empty response back to the client. The response includes the specified status HTTP status code in the HTTP header but the HTTP body is empty. This function should be used with HTTP PUT or PATCH requests and "one-way" SOAP messaging with HTTP POST. This function sends to soap::socket when valid, or to soap::os when non-NULL, or to soap::sendfd. Returns #SOAP_STOP and sets soap::error to #SOAP_STOP to halt further response messaging to the client or a soap_status error code when the message could not be sent.
Besides soap_send_empty_response, other options to return an HTTP status code are:
soap | soap context |
status | HTTP status code 200 to 599 or #SOAP_OK (same as 200 OK) |
int soap_send_fault | ( | struct soap * | soap | ) |
Return an HTTP error with a SOAP Fault message from a service.
This function sends an error response back to the client and is used at the server side by soap_serve after an error occurred to propagate the fault to the client. This function sends to soap::socket when valid, or to soap::os when non-NULL, or to soap::sendfd.
soap | soap context |
int soap_send_raw | ( | struct soap * | soap, |
const char * | s, | ||
size_t | n ) |
Send raw bytes.
This function sends raw bytes of data to soap::os when non-NULL, or to soap::socket when valid, or or to soap::sendfd when nonzero.
soap | soap context |
s | data to send |
n | length of data to send |
void soap_serializeheader | ( | struct soap * | soap | ) |
Serialize the SOAP Header pointed to by soap::header before emitting it with soap_putheader
soap | soap context |
int soap_serve | ( | struct soap * | soap | ) |
Serve a pending request.
This function is auto-generated by soapcpp2 and serves the pending request on soap::socket or on standard input/output soap::recvfd and soap::sendfd, e.g. for CGI and FastCGI services. Returns #SOAP_OK or a soap_status error code.
This auto-generated function implements the following behavior:
The soap_begin_serve function processes the HTTP headers and XML SOAP headers if present. The soap_serve_request function is auto-generated by soapcpp2, when applicable, and parses the SOAP/XML request element to dispatch the SOAP/XML request to a service operation.
If soapcpp2 is not used or does not generate soap_serve but soap_serve is required to serve non-SOAP requests, for example to serve JSON or GET/PUT/PATCH/DELETE requests, then the following simplified soap_serve implementation works just fine:
soap | soap context |
int soap_serve_request | ( | struct soap * | soap | ) |
Process a pending request.
This function is auto-generated by soapcpp2 and parses the SOAP/XML request element to dispatch the SOAP/XML request to a service operation. Returns #SOAP_OK or a soap_status error code.
soap | soap context |