git.maemo.org Git - xmlrpc-c/blob - include/xmlrpc-c/client.h

   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 <xmlrpc-c/base.h>
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif /* __cplusplus */
  18
  19 struct xmlrpc_client;
  20 #ifndef __cplusplus
  21 typedef struct xmlrpc_client xmlrpc_client;
  22 #endif
  23
  24 struct xmlrpc_xportparms;
  25     /* This is a "base class".  The struct is never complete; you're
  26        supposed to cast between struct xmlrpc_xportparms * and
  27        "struct xmlrpc_..._xportparms *" in order to use it.
  28     */
  29
  30 enum xmlrpc_sslversion {
  31     XMLRPC_SSLVERSION_DEFAULT,
  32     XMLRPC_SSLVERSION_TLSv1,
  33     XMLRPC_SSLVERSION_SSLv2,
  34     XMLRPC_SSLVERSION_SSLv3
  35 };
  36
  37 struct xmlrpc_curl_xportparms {
  38     /* This is designed so that zero values are always the defaults. */
  39     const char * network_interface;
  40     xmlrpc_bool  no_ssl_verifypeer;
  41     xmlrpc_bool  no_ssl_verifyhost;
  42     const char * user_agent;
  43     const char * ssl_cert;
  44     const char * sslcerttype;
  45     const char * sslcertpasswd;
  46     const char * sslkey;
  47     const char * sslkeytype;
  48     const char * sslkeypasswd;
  49     const char * sslengine;
  50     xmlrpc_bool  sslengine_default;
  51     enum xmlrpc_sslversion sslversion;
  52     const char * cainfo;
  53     const char * capath;
  54     const char * randomfile;
  55     const char * egdsocket;
  56     const char * ssl_cipher_list;
  57 };
  58
  59
  60 #define XMLRPC_CXPSIZE(mbrname) \
  61     XMLRPC_STRUCTSIZE(struct xmlrpc_curl_xportparms, mbrname)
  62
  63 /* XMLRPC_CXPSIZE(xyz) is analogous to XMLRPC_CPSIZE, below */
  64
  65 struct xmlrpc_wininet_xportparms {
  66     int allowInvalidSSLCerts;
  67 };
  68
  69 #define XMLRPC_WXPSIZE(mbrname) \
  70     XMLRPC_STRUCTSIZE(struct xmlrpc_wininet_xportparms, mbrname)
  71
  72 /* XMLRPC_WXPSIZE(xyz) is analogous to XMLRPC_CPSIZE, below */
  73
  74 struct xmlrpc_clientparms {
  75     const char *               transport;
  76     struct xmlrpc_xportparms * transportparmsP;
  77         /* Cast a "struct ..._xportparms *" to fit here */
  78     size_t                     transportparm_size;
  79 };
  80
  81 #define XMLRPC_CPSIZE(mbrname) \
  82   XMLRPC_STRUCTSIZE(struct xmlrpc_clientparms, mbrname)
  83
  84 /* XMLRPC_CPSIZE(xyz) is the minimum size a struct xmlrpc_clientparms
  85    must be to include the 'xyz' member.  This is essential to forward and
  86    backward compatbility, as new members will be added to the end of the
  87    struct in future releases.  This is how the callee knows whether or
  88    not the caller is new enough to have supplied a certain parameter.
  89 */
  90
  91 const char *
  92 xmlrpc_client_get_default_transport(xmlrpc_env * const env);
  93
  94 /* A callback function to handle the response to an asynchronous call.
  95 ** If 'fault->fault_occurred' is true, then response will be NULL. All
  96 ** arguments except 'user_data' will be deallocated internally; please do
  97 ** not free any of them yourself.
  98 ** WARNING: param_array may (or may not) be NULL if fault->fault_occurred
  99 ** is true, and you set up the call using xmlrpc_client_call_asynch.
 100 ** WARNING: If asynchronous calls are still pending when the library is
 101 ** shut down, your handler may (or may not) be called with a fault. */
 102 typedef void (*xmlrpc_response_handler) (const char *server_url,
 103                                          const char *method_name,
 104                                          xmlrpc_value *param_array,
 105                                          void *user_data,
 106                                          xmlrpc_env *fault,
 107                                          xmlrpc_value *result);
 108
 109
 110 /*=========================================================================
 111 **  xmlrpc_server_info
 112 **=========================================================================
 113 **  We normally refer to servers by URL. But sometimes we need to do extra
 114 **  setup for particular servers. In that case, we can create an
 115 **  xmlrpc_server_info object, configure it in various ways, and call the
 116 **  remote server.
 117 **
 118 **  (This interface is also designed to discourage further multiplication
 119 **  of xmlrpc_client_call APIs. We have enough of those already. Please
 120 **  add future options and flags using xmlrpc_server_info.)
 121 */
 122
 123 typedef struct _xmlrpc_server_info xmlrpc_server_info;
 124
 125 /* Create a new server info record, pointing to the specified server. */
 126 xmlrpc_server_info *
 127 xmlrpc_server_info_new(xmlrpc_env * const env,
 128                        const char * const server_url);
 129
 130 /* Create a new server info record, with a copy of the old server. */
 131 extern xmlrpc_server_info *
 132 xmlrpc_server_info_copy(xmlrpc_env *env, xmlrpc_server_info *src_server);
 133
 134 /* Delete a server info record. */
 135 extern void
 136 xmlrpc_server_info_free (xmlrpc_server_info *server);
 137
 138 void
 139 xmlrpc_server_info_set_basic_auth(xmlrpc_env *         const envP,
 140                                   xmlrpc_server_info * const serverP,
 141                                   const char *         const username,
 142                                   const char *         const password);
 143
 144
 145 void
 146 xmlrpc_client_setup_global_const(xmlrpc_env * const envP);
 147
 148 void
 149 xmlrpc_client_teardown_global_const(void);
 150
 151 void
 152 xmlrpc_client_create(xmlrpc_env *                      const envP,
 153                      int                               const flags,
 154                      const char *                      const appname,
 155                      const char *                      const appversion,
 156                      const struct xmlrpc_clientparms * const clientparmsP,
 157                      unsigned int                      const parmSize,
 158                      xmlrpc_client **                  const clientPP);
 159
 160 void
 161 xmlrpc_client_destroy(xmlrpc_client * const clientP);
 162
 163 void
 164 xmlrpc_client_transport_call2(
 165     xmlrpc_env *               const envP,
 166     xmlrpc_client *            const clientP,
 167     const xmlrpc_server_info * const serverP,
 168     xmlrpc_mem_block *         const callXmlP,
 169     xmlrpc_mem_block **        const respXmlPP);
 170
 171 void
 172 xmlrpc_client_call2(xmlrpc_env *               const envP,
 173                     struct xmlrpc_client *     const clientP,
 174                     const xmlrpc_server_info * const serverInfoP,
 175                     const char *               const methodName,
 176                     xmlrpc_value *             const paramArrayP,
 177                     xmlrpc_value **            const resultPP);
 178
 179 void
 180 xmlrpc_client_call2f(xmlrpc_env *    const envP,
 181                      xmlrpc_client * const clientP,
 182                      const char *    const serverUrl,
 183                      const char *    const methodName,
 184                      xmlrpc_value ** const resultPP,
 185                      const char *    const format,
 186                      ...);
 187
 188 void
 189 xmlrpc_client_event_loop_finish(xmlrpc_client * const clientP);
 190
 191 void
 192 xmlrpc_client_event_loop_finish_timeout(xmlrpc_client * const clientP,
 193                                         unsigned long   const milliseconds);
 194
 195 void
 196 xmlrpc_client_start_rpc(xmlrpc_env *             const envP,
 197                         struct xmlrpc_client *   const clientP,
 198                         xmlrpc_server_info *     const serverInfoP,
 199                         const char *             const methodName,
 200                         xmlrpc_value *           const argP,
 201                         xmlrpc_response_handler        responseHandler,
 202                         void *                   const userData);
 203
 204 void
 205 xmlrpc_client_start_rpcf(xmlrpc_env *    const envP,
 206                          xmlrpc_client * const clientP,
 207                          const char *    const serverUrl,
 208                          const char *    const methodName,
 209                          xmlrpc_response_handler callback,
 210                          void *          const userData,
 211                          const char *    const format,
 212                          ...);
 213
 214 #include <xmlrpc-c/client_global.h>
 215
 216 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
 217 **
 218 ** Redistribution and use in source and binary forms, with or without
 219 ** modification, are permitted provided that the following conditions
 220 ** are met:
 221 ** 1. Redistributions of source code must retain the above copyright
 222 **    notice, this list of conditions and the following disclaimer.
 223 ** 2. Redistributions in binary form must reproduce the above copyright
 224 **    notice, this list of conditions and the following disclaimer in the
 225 **    documentation and/or other materials provided with the distribution.
 226 ** 3. The name of the author may not be used to endorse or promote products
 227 **    derived from this software without specific prior written permission.
 228 **
 229 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 230 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 231 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 232 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 233 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 234 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 235 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 236 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 237 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 238 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 239 ** SUCH DAMAGE. */
 240
 241
 242 #ifdef __cplusplus
 243 }
 244 #endif /* __cplusplus */
 245
 246 #endif /* _XMLRPC_CLIENT_H_ */