Overview
The CURL plugin for gSOAP provides a bridge for the gSOAP engine to use libcurl for internet communications. While gSOAP provides a full HTTP stack, libcurl can be used to support additional protocols and features by replacing gSOAP's HTTP stack.
CURL plugin setup
To use the CURL plugin:
- Add #include "plugin/curlapi.h" to your client-side code and compile your code together with plugin/curlapi.c. Link your code with libcurl.
- Add curl_global_init(CURL_GLOBAL_ALL) at the start of your program to initialize CURL. Add curl_global_cleanup() at the end of your program.
- In your source code where you create a soap context, register the plugin with this soap context, Or use the soap member of a soapcpp2-generated C++ proxy class. Use soap_register_plugin(soap, soap_curl) to register.
- Alternatively, if you have a CURL *curl handle already set up, then register the plugin with soap_register_plugin_arg(soap, soap_curl, curl). The benefit of this is that you can set CURL options of the handle. Do not delete this handle until the soap context is deleted.
- If you register multiple other plugins with the context, you should register the CURL plugin always first.
The plugin is not limited to SOAP calls, you can use it with XML REST and JSON in gSOAP. The plugin registry steps are the same for any client-side API service calls.
The CURL plugin supports SOAP with MTOM attachments, including streaming MTOM. Other plugins can be combined with this plugin, such as WSSE for WS-Security.
- Note
- The CURL plugin increases the overhead of HTTP calls compared to the gSOAP HTTP stack. The overhead is due to buffering of the entire outbound message before sending and buffering of the entire message received. By contrast, gSOAP uses a streaming approach and only buffers the socket communications to (de)serialize XML directly into C/C++ data.
Configuration and settings
To use the CURL plugin, register the plugin with the current soap context using soap_register_plugin(soap, soap_curl). This also creates a new CURL handle that is internally used by the plugin until the soap context is deleted. For C++ proxy classes generated with soapcpp2, register the plugin with the soap member of the proxy class.
The gSOAP HTTP chunked transfer mode SOAP_IO_CHUNK and timeout settings are also used by the CURL plugin, when set, as follows:
...
struct soap *soap;
curl_global_init(CURL_GLOBAL_ALL);
soap = soap_new1(SOAP_IO_CHUNK | SOAP_XML_INDENT);
soap->connect_timeout = 60;
soap->send_timeout = 10;
soap->recv_timeout = 10;
soap->transfer_timeout = 20;
...
...
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
curl_global_cleanup();
SOAP_FMAC1 int SOAP_FMAC2 soap_curl(struct soap *soap, struct soap_plugin *p, void *arg)
Plugin registry function, used with soap_register_plugin and soap_register_plugin_arg.
Definition curlapi.c:361
It is strongly recommended to set timeouts. The timeout values specified here are just examples. Actual values depend on the application's performance characteristics.
HTTP proxy settings are used by the CURL plugin. You can specify the HTTP proxy settings soap->proxy_host and soap->proxy_port with the HTTP proxy host and port, respectively, and specify the HTTP proxy access credentials soap->proxy_userid and soap->proxy_passwd.
Also compression is used by the CURL plugin when enabled with SOAP_ENC_ZLIB:
...
struct soap *soap;
curl_global_init(CURL_GLOBAL_ALL);
soap = soap_new1(SOAP_IO_CHUNK | SOAP_ENC_ZLIB | SOAP_XML_INDENT);
...
...
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
curl_global_cleanup();
When an transmission error occurs, use soap_curl_reset(soap) to reset the plugin. This ensures that the gSOAP IO operations are reset and will behave again normally.
Alternatively, you can create your own CURL *curl handle, configure it, and pass it to the plugin as follows:
...
struct soap *soap;
CURL *curl;
curl_global_init(CURL_GLOBAL_ALL);
curl = curl_easy_init();
curl_easy_setopt(data->curl, CURLOPT_CONNECTTIMEOUT, 60L);
curl_easy_setopt(data->curl, CURLOPT_TIMEOUT, 10L);
soap = soap_new1(SOAP_XML_INDENT);
soap_register_plugin_arg(soap,
soap_curl, curl);
...
...
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
curl_easy_cleanup(curl);
...
curl_global_cleanup();
Note that C++ proxy classes generated by soapcpp2 with option -j have a soap member that should be used to register the plugin with:
...
Proxy proxy(SOAP_XML_INDENT);
CURL *curl;
curl_global_init(CURL_GLOBAL_ALL);
curl = curl_easy_init();
curl_easy_setopt(data->curl, CURLOPT_CONNECTTIMEOUT, 60L);
curl_easy_setopt(data->curl, CURLOPT_TIMEOUT, 10L);
soap_register_plugin_arg(proxy.soap,
soap_curl, curl);
...
...
proxy.destroy();
curl_easy_cleanup(curl);
...
curl_global_cleanup();
SOAP client example
This example shows a calculator client application with CURL and gSOAP.
The soapcpp2 command is applied to calc.h with soapcpp2 -c -CL calc.h, where calc.h is:
int ns__add(double a, double b, double *result);
int ns__sub(double a, double b, double *result);
int ns__mul(double a, double b, double *result);
int ns__div(double a, double b, double *result);
int ns__pow(double a, double b, double *result);
This generates soapStub.h, soapH.h, soapC.c, soapClient.c, and calc.nsmap.
To keep this example small, the main program uses the calculator service to add two values:
#include "soapH.h"
#include "calc.nsmap"
const char server[] = "http://websrv.cs.fsu.edu/~engelen/calcserver.cgi";
int main(int argc, char **argv)
{
struct soap *soap = soap_new1(SOAP_XML_INDENT);
double result;
curl_global_init(CURL_GLOBAL_ALL);
if (soap_call_ns__add(soap, server, "", 2.0, 3.0, &result))
{
soap_print_fault(soap, stderr);
}
else
printf("2 +3 = %g\n", result);
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
curl_global_cleanup();
return 0;
}
SOAP_FMAC1 void SOAP_FMAC2 soap_curl_reset(struct soap *soap)
Reset the plugin so gSOAP IO behaves normally. This is an optional API call, not required except when...
Definition curlapi.c:450
We compile this example program together with stdsoap2.c, soapC.c, soapClient.c, plugin/curlapi.c and we link it with libcurl.
As stated previously, to use a current CURL *curl handle that you have created, use soap_register_plugin_arg(soap, soap_curl, curl) to register the plugin.
JSON REST example
See the gSOAP JSON documentation for details about using JSON with gSOAP in C and in C++.
A JSON client in C with CURL has the following outline:
#include "json.h"
struct Namespace namespaces[] = {{NULL,NULL,NULL,NULL}};
...
struct soap *ctx = soap_new1(SOAP_C_UTFSTRING | SOAP_XML_INDENT);
struct value *request = new_value(ctx);
struct value response;
curl_global_init(CURL_GLOBAL_ALL);
...
if (json_call(ctx, "endpoint URL", request, &response))
{
soap_print_fault(ctx, stderr);
}
else
{
...
}
soap_destroy(ctx);
soap_end(ctx);
...
soap_free(ctx);
curl_global_cleanup();
As stated previously, to use a current CURL *curl handle that you have created, use soap_register_plugin_arg(soap, soap_curl, curl) to register the plugin.
JSON in C++ is similar to the C example shown with the benefit of the easy-to-use JSON C++ API.