1 /*============================================================================ 2 xmlrpc_client.h 3 ============================================================================== 4 This header file defines the interface between xmlrpc.c and its users, 5 related to clients. 6 7 Copyright information is at the end of the file. 8 ============================================================================*/ 9 10 #ifndef XMLRPC_CLIENT_H_INCLUDED 11 #define XMLRPC_CLIENT_H_INCLUDED 12 13 #include <stdarg.h> 14 #include <xmlrpc-c/c_util.h> /* For XMLRPC_DLLEXPORT */ 15 #include <xmlrpc-c/base.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif /* __cplusplus */ 20 21 struct xmlrpc_client; 22 struct xmlrpc_client_transport; 23 struct xmlrpc_client_transport_ops; 24 #ifndef __cplusplus 25 typedef struct xmlrpc_client xmlrpc_client; 26 typedef struct xmlrpc_client_transport xmlrpc_client_transport; 27 typedef struct xmlrpc_client_transport_ops xmlrpc_client_transport_ops; 28 #endif 29 30 /* 31 XMLRPC_CLIENT_EXPORTED marks a symbol in this file that is exported from 32 libxmlrpc_client. 33 34 XMLRPC_BUILDING_CLIENT says this compilation is part of libxmlrpc_client, as 35 opposed to something that _uses_ libxmlrpc_client. 36 */ 37 #ifdef XMLRPC_BUILDING_CLIENT 38 #define XMLRPC_CLIENT_EXPORTED XMLRPC_DLLEXPORT 39 #else 40 #define XMLRPC_CLIENT_EXPORTED 41 #endif 42 43 /* libxmlrpc_client typically does _not_ actually include all of the 44 XML transports declared here by xmlrpc_*_transport_ops. 45 46 Use 'xmlrpc-c-config --features' to determine which features are 47 installed. 48 */ 49 50 /* Before Xmlrpc-c 1.13 (December 2007), we declared struct 51 xmlrpc_xportparms, as a sort of "base class." The struct was never 52 complete -- you just cast pointer to it it to pointers to other 53 types. It turned out not to be really helpful and casts are ugly, 54 so now we just use void * as a base class pointer. 55 */ 56 57 XMLRPC_CLIENT_EXPORTED 58 extern struct xmlrpc_client_transport_ops xmlrpc_libwww_transport_ops; 59 XMLRPC_CLIENT_EXPORTED 60 extern struct xmlrpc_client_transport_ops xmlrpc_wininet_transport_ops; 61 XMLRPC_CLIENT_EXPORTED 62 extern struct xmlrpc_client_transport_ops xmlrpc_curl_transport_ops; 63 64 enum xmlrpc_sslversion { 65 XMLRPC_SSLVERSION_DEFAULT, 66 XMLRPC_SSLVERSION_TLSv1, 67 XMLRPC_SSLVERSION_SSLv2, 68 XMLRPC_SSLVERSION_SSLv3 69 }; 70 71 72 enum xmlrpc_httpauthtype { 73 /* These are just constants. They can be or'ed as integers to create 74 a set. 75 */ 76 XMLRPC_HTTPAUTH_BASIC = (1<<0), 77 XMLRPC_HTTPAUTH_DIGEST = (1<<1), 78 XMLRPC_HTTPAUTH_GSSNEGOTIATE = (1<<2), 79 XMLRPC_HTTPAUTH_NTLM = (1<<3) 80 }; 81 82 /* The following are useful combinations of the HTTP authentication types 83 above. 84 */ 85 #define XMLRPC_HTTPAUTH_NONE 0 86 #define XMLRPC_HTTPAUTH_ANY ~0 87 #define XMLRPC_HTTPAUTH_ANYSAFE (~XMLRPC_HTTPAUTH_BASIC) 88 89 enum xmlrpc_httpproxytype { 90 XMLRPC_HTTPPROXY_HTTP = 0, 91 XMLRPC_HTTPPROXY_SOCKS5 = 5 92 }; 93 94 struct xmlrpc_curl_xportparms { 95 /* This is designed so that zero values are always the defaults. */ 96 const char * network_interface; 97 xmlrpc_bool no_ssl_verifypeer; 98 xmlrpc_bool no_ssl_verifyhost; 99 const char * user_agent; 100 const char * ssl_cert; 101 const char * sslcerttype; 102 const char * sslcertpasswd; 103 const char * sslkey; 104 const char * sslkeytype; 105 const char * sslkeypasswd; 106 const char * sslengine; 107 xmlrpc_bool sslengine_default; 108 enum xmlrpc_sslversion sslversion; 109 const char * cainfo; 110 const char * capath; 111 const char * randomfile; 112 const char * egdsocket; 113 const char * ssl_cipher_list; 114 unsigned int timeout; 115 xmlrpc_bool dont_advertise; 116 const char * proxy; 117 unsigned int proxy_port; 118 enum xmlrpc_httpproxytype proxy_type; 119 unsigned int proxy_auth; 120 /* A set of authentication schemes -- an OR of 121 enum xmlrpc_httpproxyauth values 122 */ 123 const char * proxy_userpwd; 124 xmlrpc_bool gssapi_delegation; 125 const char * referer; 126 unsigned int connect_timeout; 127 }; 128 129 130 #define XMLRPC_CXPSIZE(mbrname) \ 131 XMLRPC_STRUCTSIZE(struct xmlrpc_curl_xportparms, mbrname) 132 133 /* XMLRPC_CXPSIZE(xyz) is analogous to XMLRPC_CPSIZE, below */ 134 135 struct xmlrpc_wininet_xportparms { 136 int allowInvalidSSLCerts; 137 }; 138 139 #define XMLRPC_WXPSIZE(mbrname) \ 140 XMLRPC_STRUCTSIZE(struct xmlrpc_wininet_xportparms, mbrname) 141 142 /* XMLRPC_WXPSIZE(xyz) is analogous to XMLRPC_CPSIZE, below */ 143 144 struct xmlrpc_transfer_progress { 145 double total; 146 double now; 147 }; 148 149 struct xmlrpc_progress_data { 150 struct xmlrpc_transfer_progress call; 151 struct xmlrpc_transfer_progress response; 152 }; 153 154 typedef void xmlrpc_progress_fn(void * const, 155 struct xmlrpc_progress_data const); 156 157 struct xmlrpc_clientparms { 158 /* (transport, transportparmsP, transportparm_size) and 159 (transportOpsP, transportP) are mutually exclusive. 160 */ 161 const char * transport; 162 const void * transportparmsP; 163 /* This should be type "const struct ..._xportparms *" */ 164 size_t transportparm_size; 165 166 const struct xmlrpc_client_transport_ops * transportOpsP; 167 xmlrpc_client_transport * transportP; 168 xmlrpc_dialect dialect; 169 xmlrpc_progress_fn * progressFn; 170 }; 171 172 #define XMLRPC_CPSIZE(mbrname) \ 173 XMLRPC_STRUCTSIZE(struct xmlrpc_clientparms, mbrname) 174 175 /* XMLRPC_CPSIZE(xyz) is the minimum size a struct xmlrpc_clientparms 176 must be to include the 'xyz' member. This is essential to forward and 177 backward compatibility, as new members will be added to the end of the 178 struct in future releases. This is how the callee knows whether or 179 not the caller is new enough to have supplied a certain parameter. 180 */ 181 182 XMLRPC_CLIENT_EXPORTED 183 const char * 184 xmlrpc_client_get_default_transport(xmlrpc_env * const env); 185 186 /* A user's function to handle the response to an asynchronous call. 187 ** If 'fault->fault_occurred' is true, then response will be NULL. All 188 ** arguments except 'userHandle' will be deallocated internally; please do 189 ** not free any of them yourself. 190 ** WARNING: 'paramArray' may (or may not) be NULL if fault->fault_occurred 191 ** is true, and you set up the call using xmlrpc_client_call_asynch. 192 ** WARNING: If asynchronous calls are still pending when the library is 193 ** shut down, your handler may (or may not) be called with a fault. */ 194 typedef void xmlrpc_response_handler(const char * serverUrl, 195 const char * methodName, 196 xmlrpc_value * paramArray, 197 void * userHandle, 198 xmlrpc_env * fault, 199 xmlrpc_value * result); 200 201 202 /*========================================================================= 203 xmlrpc_server_info 204 =========================================================================== 205 We normally refer to servers by URL. But sometimes we need to do extra 206 setup for particular servers. In that case, we can create an 207 xmlrpc_server_info object, configure it in various ways, and call the 208 remote server. 209 210 (This interface is also designed to discourage further multiplication 211 of xmlrpc_client_call APIs. We have enough of those already. Please 212 add future options and flags using xmlrpc_server_info.) 213 =========================================================================*/ 214 215 typedef struct _xmlrpc_server_info xmlrpc_server_info; 216 217 /* Create a new server info record, pointing to the specified server. */ 218 XMLRPC_CLIENT_EXPORTED 219 xmlrpc_server_info * 220 xmlrpc_server_info_new(xmlrpc_env * const envP, 221 const char * const serverUrl); 222 223 /* Create a new server info record, with a copy of the old server. */ 224 XMLRPC_CLIENT_EXPORTED 225 extern xmlrpc_server_info * 226 xmlrpc_server_info_copy(xmlrpc_env * const envP, 227 xmlrpc_server_info * const srcP); 228 229 XMLRPC_CLIENT_EXPORTED 230 void 231 xmlrpc_server_info_free(xmlrpc_server_info * const serverP); 232 233 234 XMLRPC_CLIENT_EXPORTED 235 void 236 xmlrpc_server_info_set_user(xmlrpc_env * const envP, 237 xmlrpc_server_info * const serverInfoP, 238 const char * const username, 239 const char * const password); 240 241 XMLRPC_CLIENT_EXPORTED 242 void 243 xmlrpc_server_info_set_basic_auth(xmlrpc_env * const envP, 244 xmlrpc_server_info * const serverP, 245 const char * const username, 246 const char * const password); 247 248 XMLRPC_CLIENT_EXPORTED 249 void 250 xmlrpc_server_info_allow_auth_basic(xmlrpc_env * const envP, 251 xmlrpc_server_info * const sP); 252 253 XMLRPC_CLIENT_EXPORTED 254 void 255 xmlrpc_server_info_disallow_auth_basic(xmlrpc_env * const envP, 256 xmlrpc_server_info * const sP); 257 258 XMLRPC_CLIENT_EXPORTED 259 void 260 xmlrpc_server_info_allow_auth_digest(xmlrpc_env * const envP, 261 xmlrpc_server_info * const sP); 262 263 XMLRPC_CLIENT_EXPORTED 264 void 265 xmlrpc_server_info_disallow_auth_digest(xmlrpc_env * const envP, 266 xmlrpc_server_info * const sP); 267 268 XMLRPC_CLIENT_EXPORTED 269 void 270 xmlrpc_server_info_allow_auth_negotiate(xmlrpc_env * const envP, 271 xmlrpc_server_info * const sP); 272 273 XMLRPC_CLIENT_EXPORTED 274 void 275 xmlrpc_server_info_disallow_auth_negotiate(xmlrpc_env * const envP, 276 xmlrpc_server_info * const sP); 277 278 XMLRPC_CLIENT_EXPORTED 279 void 280 xmlrpc_server_info_allow_auth_ntlm(xmlrpc_env * const envP, 281 xmlrpc_server_info * const sP); 282 283 XMLRPC_CLIENT_EXPORTED 284 void 285 xmlrpc_server_info_disallow_auth_ntlm(xmlrpc_env * const envP, 286 xmlrpc_server_info * const sP); 287 288 /* These are for backward compatibility -- they can't be exported from a 289 Windows DLL. xmlrpc_server_version() is preferred. 290 */ 291 extern unsigned int const xmlrpc_client_version_major; 292 extern unsigned int const xmlrpc_client_version_minor; 293 extern unsigned int const xmlrpc_client_version_point; 294 295 XMLRPC_CLIENT_EXPORTED 296 void 297 xmlrpc_client_version(unsigned int * const majorP, 298 unsigned int * const minorP, 299 unsigned int * const pointP); 300 301 XMLRPC_CLIENT_EXPORTED 302 void 303 xmlrpc_client_setup_global_const(xmlrpc_env * const envP); 304 305 XMLRPC_CLIENT_EXPORTED 306 void 307 xmlrpc_client_teardown_global_const(void); 308 309 XMLRPC_CLIENT_EXPORTED 310 void 311 xmlrpc_client_create(xmlrpc_env * const envP, 312 int const flags, 313 const char * const appname, 314 const char * const appversion, 315 const struct xmlrpc_clientparms * const clientparmsP, 316 unsigned int const parmSize, 317 xmlrpc_client ** const clientPP); 318 319 XMLRPC_CLIENT_EXPORTED 320 void 321 xmlrpc_client_destroy(xmlrpc_client * const clientP); 322 323 XMLRPC_CLIENT_EXPORTED 324 void 325 xmlrpc_client_transport_call2( 326 xmlrpc_env * const envP, 327 xmlrpc_client * const clientP, 328 const xmlrpc_server_info * const serverP, 329 xmlrpc_mem_block * const callXmlP, 330 xmlrpc_mem_block ** const respXmlPP); 331 332 XMLRPC_CLIENT_EXPORTED 333 void 334 xmlrpc_client_call2(xmlrpc_env * const envP, 335 struct xmlrpc_client * const clientP, 336 const xmlrpc_server_info * const serverInfoP, 337 const char * const methodName, 338 xmlrpc_value * const paramArrayP, 339 xmlrpc_value ** const resultPP); 340 341 XMLRPC_CLIENT_EXPORTED 342 void 343 xmlrpc_client_call2f(xmlrpc_env * const envP, 344 xmlrpc_client * const clientP, 345 const char * const serverUrl, 346 const char * const methodName, 347 xmlrpc_value ** const resultPP, 348 const char * const format, 349 ...); 350 351 XMLRPC_CLIENT_EXPORTED 352 void 353 xmlrpc_client_call2f_va(xmlrpc_env * const envP, 354 xmlrpc_client * const clientP, 355 const char * const serverUrl, 356 const char * const methodName, 357 const char * const format, 358 xmlrpc_value ** const resultPP, 359 va_list args); 360 361 XMLRPC_CLIENT_EXPORTED 362 void 363 xmlrpc_client_event_loop_finish(xmlrpc_client * const clientP); 364 365 XMLRPC_CLIENT_EXPORTED 366 void 367 xmlrpc_client_event_loop_finish_timeout(xmlrpc_client * const clientP, 368 unsigned long const milliseconds); 369 370 XMLRPC_CLIENT_EXPORTED 371 void 372 xmlrpc_client_start_rpc(xmlrpc_env * const envP, 373 struct xmlrpc_client * const clientP, 374 const xmlrpc_server_info * const serverInfoP, 375 const char * const methodName, 376 xmlrpc_value * const paramArrayP, 377 xmlrpc_response_handler responseHandler, 378 void * const userData); 379 380 XMLRPC_CLIENT_EXPORTED 381 void 382 xmlrpc_client_start_rpcf(xmlrpc_env * const envP, 383 xmlrpc_client * const clientP, 384 const char * const serverUrl, 385 const char * const methodName, 386 xmlrpc_response_handler responseHandler, 387 void * const userData, 388 const char * const format, 389 ...); 390 391 XMLRPC_CLIENT_EXPORTED 392 void 393 xmlrpc_client_start_rpcf_va(xmlrpc_env * const envP, 394 xmlrpc_client * const clientP, 395 const char * const serverUrl, 396 const char * const methodName, 397 xmlrpc_response_handler responseHandler, 398 void * const userData, 399 const char * const format, 400 va_list args); 401 402 XMLRPC_CLIENT_EXPORTED 403 void 404 xmlrpc_client_set_interrupt(xmlrpc_client * const clientP, 405 int * const interruptP); 406 407 #include <xmlrpc-c/client_global.h> 408 409 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved. 410 ** 411 ** Redistribution and use in source and binary forms, with or without 412 ** modification, are permitted provided that the following conditions 413 ** are met: 414 ** 1. Redistributions of source code must retain the above copyright 415 ** notice, this list of conditions and the following disclaimer. 416 ** 2. Redistributions in binary form must reproduce the above copyright 417 ** notice, this list of conditions and the following disclaimer in the 418 ** documentation and/or other materials provided with the distribution. 419 ** 3. The name of the author may not be used to endorse or promote products 420 ** derived from this software without specific prior written permission. 421 ** 422 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 423 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 424 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 425 ** ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 426 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 427 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 428 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 429 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 430 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 431 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 432 ** SUCH DAMAGE. */ 433 434 435 #ifdef __cplusplus 436 } 437 #endif /* __cplusplus */ 438 439 #endif /* _XMLRPC_CLIENT_H_ */ 440