CMakeLua/Utilities/cmxmlrpc/xmlrpc.h

   1 /* Copyright (C) 2001 by First Peer, Inc. All rights reserved.
   2 **
   3 ** Redistribution and use in source and binary forms, with or without
   4 ** modification, are permitted provided that the following conditions
   5 ** are met:
   6 ** 1. Redistributions of source code must retain the above copyright
   7 **    notice, this list of conditions and the following disclaimer.
   8 ** 2. Redistributions in binary form must reproduce the above copyright
   9 **    notice, this list of conditions and the following disclaimer in the
  10 **    documentation and/or other materials provided with the distribution.
  11 ** 3. The name of the author may not be used to endorse or promote products
  12 **    derived from this software without specific prior written permission.
  13 **
  14 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 ** SUCH DAMAGE. */
  25
  26
  27 #ifndef  _XMLRPC_H_
  28 #define  _XMLRPC_H_ 1
  29
  30 #include <stddef.h>
  31 #include <stdarg.h>
  32 #include <cmxmlrpc/xmlrpc_config.h>
  33
  34 #ifdef HAVE_UNICODE_WCHAR
  35 #include <wchar.h>
  36 #endif
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42
  43 /*=========================================================================
  44 **  Typedefs
  45 **=========================================================================
  46 **  We define names for these types, because they may change from platform
  47 **  to platform.
  48 */
  49
  50 typedef signed int xmlrpc_int;
  51     /* An integer of the type defined by XML-RPC <int>; i.e. 32 bit */
  52 typedef signed int xmlrpc_int32;
  53     /* An integer of the type defined by XML-RPC <int4>; i.e. 32 bit */
  54 typedef int xmlrpc_bool;
  55     /* A boolean (of the type defined by XML-RPC <boolean>, but there's
  56        really only one kind)
  57     */
  58 typedef double xmlrpc_double;
  59     /* A double precision floating point number as defined by
  60        XML-RPC <float>.  But the C "double" type is universally the same,
  61        so it's probably clearer just to use that.  This typedef is here
  62        for mathematical completeness.
  63     */
  64
  65 #define XMLRPC_INT32_MAX (2147483647)
  66 #define XMLRPC_INT32_MIN (-XMLRPC_INT32_MAX - 1)
  67
  68
  69
  70 /*=========================================================================
  71 **  C struct size computations
  72 **=======================================================================*/
  73
  74 /* Use XMLRPC_STRUCT_MEMBER_SIZE() to determine how big a structure is
  75    up to and including a specified member.  E.g. if you have
  76    struct mystruct {int red; int green; int blue};, then
  77    XMLRPC_STRUCT_MEMBER_SIZE(mystruct, green) is (8).
  78 */
  79
  80 #define _XMLRPC_STRUCT_MEMBER_OFFSET(TYPE, MBRNAME) \
  81   ((unsigned int)(char*)&((TYPE *)0)->MBRNAME)
  82 #define _XMLRPC_STRUCT_MEMBER_SIZE(TYPE, MBRNAME) \
  83   sizeof(((TYPE *)0)->MBRNAME)
  84 #define XMLRPC_STRUCTSIZE(TYPE, MBRNAME) \
  85   (_XMLRPC_STRUCT_MEMBER_OFFSET(TYPE, MBRNAME) + \
  86   _XMLRPC_STRUCT_MEMBER_SIZE(TYPE, MBRNAME))
  87
  88 /*=========================================================================
  89 **  Assertions and Debugging
  90 **=========================================================================
  91 **  We use xmlrpc_assert for internal sanity checks. For example:
  92 **
  93 **    xmlrpc_assert(ptr != NULL);
  94 **
  95 **  Assertions are only evaluated when debugging code is turned on. (To
  96 **  turn debugging off, define NDEBUG.) Some rules for using assertions:
  97 **
  98 **    1) Assertions should never have side effects.
  99 **    2) Assertions should never be used for run-time error checking.
 100 **       Instead, they should be used to check for "can't happen" errors.
 101 */
 102
 103 #ifndef NDEBUG
 104
 105 #define XMLRPC_ASSERT(cond) \
 106     do \
 107         if (!(cond)) \
 108             xmlrpc_assertion_failed(__FILE__, __LINE__); \
 109     while (0)
 110
 111 #else
 112 #define XMLRPC_ASSERT(cond) (0)
 113 #endif
 114
 115 extern void xmlrpc_assertion_failed (char* file, int line);
 116
 117 /* Validate a pointer. */
 118 #define XMLRPC_ASSERT_PTR_OK(ptr) \
 119     XMLRPC_ASSERT((ptr) != NULL)
 120
 121 /* We only call this if something truly drastic happens. */
 122 #define XMLRPC_FATAL_ERROR(msg) xmlrpc_fatal_error(__FILE__, __LINE__, (msg))
 123
 124 extern void xmlrpc_fatal_error (char* file, int line, char* msg);
 125
 126
 127 /*=========================================================================
 128 **  Strings
 129 **=======================================================================*/
 130
 131 /* Traditional C strings are char *, because they come from a time before
 132    there was 'const'.  Now, const char * makes a lot more sense.  Also,
 133    in modern times, we tend to dynamically allocate memory for strings.
 134    We need this free function accordingly.  Ordinary free() doesn't check
 135    the type, and can generate a warning due to the 'const'.
 136 */
 137 void
 138 xmlrpc_strfree(const char * const string);
 139
 140
 141
 142 /*=========================================================================
 143 **  xmlrpc_env
 144 **=========================================================================
 145 **  XML-RPC represents runtime errors as <fault> elements. These contain
 146 **  <faultCode> and <faultString> elements.
 147 **
 148 **  Since we need as much thread-safety as possible, we borrow an idea from
 149 **  CORBA--we store exception information in an "environment" object.
 150 **  You'll pass this to many different functions, and it will get filled
 151 **  out appropriately.
 152 **
 153 **  For example:
 154 **
 155 **    xmlrpc_env env;
 156 **
 157 **    xmlrpc_env_init(&env);
 158 **
 159 **    xmlrpc_do_something(&env);
 160 **    if (env.fault_occurred)
 161 **        report_error_appropriately();
 162 **
 163 **    xmlrpc_env_clean(&env);
 164 */
 165
 166 #define XMLRPC_INTERNAL_ERROR               (-500)
 167 #define XMLRPC_TYPE_ERROR                   (-501)
 168 #define XMLRPC_INDEX_ERROR                  (-502)
 169 #define XMLRPC_PARSE_ERROR                  (-503)
 170 #define XMLRPC_NETWORK_ERROR                (-504)
 171 #define XMLRPC_TIMEOUT_ERROR                (-505)
 172 #define XMLRPC_NO_SUCH_METHOD_ERROR         (-506)
 173 #define XMLRPC_REQUEST_REFUSED_ERROR        (-507)
 174 #define XMLRPC_INTROSPECTION_DISABLED_ERROR (-508)
 175 #define XMLRPC_LIMIT_EXCEEDED_ERROR         (-509)
 176 #define XMLRPC_INVALID_UTF8_ERROR           (-510)
 177
 178 typedef struct _xmlrpc_env {
 179     int   fault_occurred;
 180     xmlrpc_int32 fault_code;
 181     char* fault_string;
 182 } xmlrpc_env;
 183
 184 /* Initialize and destroy the contents of the provided xmlrpc_env object.
 185 ** These functions will never fail. */
 186 void xmlrpc_env_init (xmlrpc_env* env);
 187 void xmlrpc_env_clean (xmlrpc_env* env);
 188
 189 /* Fill out an xmlrpc_fault with the specified values, and set the
 190 ** fault_occurred flag. This function will make a private copy of 'string',
 191 ** so you retain responsibility for your copy. */
 192 void
 193 xmlrpc_env_set_fault(xmlrpc_env * const env,
 194                      int          const faultCode,
 195                      const char * const faultDescription);
 196
 197 /* The same as the above, but using a printf-style format string. */
 198 void
 199 xmlrpc_env_set_fault_formatted (xmlrpc_env * const envP,
 200                                 int          const code,
 201                                 const char * const format,
 202                                 ...);
 203
 204 /* A simple debugging assertion. */
 205 #define XMLRPC_ASSERT_ENV_OK(env) \
 206     XMLRPC_ASSERT((env) != NULL && !(env)->fault_occurred)
 207
 208 /* This version must *not* interpret 'str' as a format string, to avoid
 209 ** several evil attacks. */
 210 #define XMLRPC_FAIL(env,code,str) \
 211     do { xmlrpc_env_set_fault((env),(code),(str)); if(*(str)) goto cleanup; } while (0)
 212
 213 #define XMLRPC_FAIL1(env,code,str,arg1) \
 214     do { \
 215         xmlrpc_env_set_fault_formatted((env),(code),(str),(arg1)); \
 216         if(*(str)) goto cleanup; \
 217     } while (0)
 218
 219 #define XMLRPC_FAIL2(env,code,str,arg1,arg2) \
 220     do { \
 221         xmlrpc_env_set_fault_formatted((env),(code),(str),(arg1),(arg2)); \
 222         if(*(str)) goto cleanup; \
 223     } while (0)
 224
 225 #define XMLRPC_FAIL3(env,code,str,arg1,arg2,arg3) \
 226     do { \
 227         xmlrpc_env_set_fault_formatted((env),(code), \
 228                                        (str),(arg1),(arg2),(arg3)); \
 229         if(*(str)) goto cleanup; \
 230     } while (0)
 231
 232 #define XMLRPC_FAIL_IF_NULL(ptr,env,code,str) \
 233     do { \
 234         if ((ptr) == NULL) \
 235             XMLRPC_FAIL((env),(code),(str)); \
 236     } while (0)
 237
 238 #define XMLRPC_FAIL_IF_FAULT(env) \
 239     do { if ((env)->fault_occurred) goto cleanup; } while (0)
 240
 241
 242 /*=========================================================================
 243 **  Resource Limits
 244 **=========================================================================
 245 **  To discourage denial-of-service attacks, we provide several adjustable
 246 **  resource limits. These functions are *not* re-entrant.
 247 */
 248
 249 /* Limit IDs. There will be more of these as time goes on. */
 250 #define XMLRPC_NESTING_LIMIT_ID   (0)
 251 #define XMLRPC_XML_SIZE_LIMIT_ID  (1)
 252 #define XMLRPC_LAST_LIMIT_ID      (XMLRPC_XML_SIZE_LIMIT_ID)
 253
 254 /* By default, deserialized data may be no more than 64 levels deep. */
 255 #define XMLRPC_NESTING_LIMIT_DEFAULT  (64)
 256
 257 /* By default, XML data from the network may be no larger than 512K.
 258 ** Some client and server modules may fail to enforce this properly. */
 259 #define XMLRPC_XML_SIZE_LIMIT_DEFAULT (512*1024)
 260
 261 /* Set a specific limit to the specified value. */
 262 extern void xmlrpc_limit_set (int limit_id, size_t value);
 263
 264 /* Get the value of a specified limit. */
 265 extern size_t xmlrpc_limit_get (int limit_id);
 266
 267
 268 /*=========================================================================
 269 **  xmlrpc_mem_block
 270 **=========================================================================
 271 **  A resizable chunk of memory. This is mostly used internally, but it is
 272 **  also used by the public API in a few places.
 273 **  The struct fields are private!
 274 */
 275
 276 typedef struct _xmlrpc_mem_block {
 277     size_t _size;
 278     size_t _allocated;
 279     void*  _block;
 280 } xmlrpc_mem_block;
 281
 282 /* Allocate a new xmlrpc_mem_block. */
 283 xmlrpc_mem_block* xmlrpc_mem_block_new (xmlrpc_env* const env, size_t const size);
 284
 285 /* Destroy an existing xmlrpc_mem_block, and everything it contains. */
 286 void xmlrpc_mem_block_free (xmlrpc_mem_block* block);
 287
 288 /* Initialize the contents of the provided xmlrpc_mem_block. */
 289 void xmlrpc_mem_block_init
 290     (xmlrpc_env* env, xmlrpc_mem_block* block, size_t size);
 291
 292 /* Deallocate the contents of the provided xmlrpc_mem_block, but not the
 293 ** block itself. */
 294 void xmlrpc_mem_block_clean (xmlrpc_mem_block* block);
 295
 296 /* Get the size and contents of the xmlrpc_mem_block. */
 297 size_t
 298 xmlrpc_mem_block_size(const xmlrpc_mem_block * const block);
 299
 300 void *
 301 xmlrpc_mem_block_contents(const xmlrpc_mem_block * const block);
 302
 303 /* Resize an xmlrpc_mem_block, preserving as much of the contents as
 304 ** possible. */
 305 void xmlrpc_mem_block_resize
 306     (xmlrpc_env* const env, xmlrpc_mem_block* const block, size_t const size);
 307
 308 /* Append data to an existing xmlrpc_mem_block. */
 309 void xmlrpc_mem_block_append
 310     (xmlrpc_env* const env, xmlrpc_mem_block* const block, void *const data, size_t const len);
 311
 312 #define XMLRPC_MEMBLOCK_NEW(type,env,size) \
 313     xmlrpc_mem_block_new((env), sizeof(type) * (size))
 314 #define XMLRPC_MEMBLOCK_FREE(type,block) \
 315     xmlrpc_mem_block_free(block)
 316 #define XMLRPC_MEMBLOCK_INIT(type,env,block,size) \
 317     xmlrpc_mem_block_init((env), (block), sizeof(type) * (size))
 318 #define XMLRPC_MEMBLOCK_CLEAN(type,block) \
 319     xmlrpc_mem_block_clean(block)
 320 #define XMLRPC_MEMBLOCK_SIZE(type,block) \
 321     (xmlrpc_mem_block_size(block) / sizeof(type))
 322 #define XMLRPC_MEMBLOCK_CONTENTS(type,block) \
 323     ((type*) xmlrpc_mem_block_contents(block))
 324 #define XMLRPC_MEMBLOCK_RESIZE(type,env,block,size) \
 325     xmlrpc_mem_block_resize(env, block, sizeof(type) * (size))
 326 #define XMLRPC_MEMBLOCK_APPEND(type,env,block,data,size) \
 327     xmlrpc_mem_block_append(env, block, data, sizeof(type) * (size))
 328
 329 /* Here are some backward compatibility definitions.  These longer names
 330    used to be the only ones and typed memory blocks were considered
 331    special.
 332 */
 333 #define XMLRPC_TYPED_MEM_BLOCK_NEW(type,env,size) \
 334     XMLRPC_MEMBLOCK_NEW(type,env,size)
 335 #define XMLRPC_TYPED_MEM_BLOCK_FREE(type,block) \
 336     XMLRPC_MEMBLOCK_FREE(type,block)
 337 #define XMLRPC_TYPED_MEM_BLOCK_INIT(type,env,block,size) \
 338     XMLRPC_MEMBLOCK_INIT(type,env,block,size)
 339 #define XMLRPC_TYPED_MEM_BLOCK_CLEAN(type,block) \
 340     XMLRPC_MEMBLOCK_CLEAN(type,block)
 341 #define XMLRPC_TYPED_MEM_BLOCK_SIZE(type,block) \
 342     XMLRPC_MEMBLOCK_SIZE(type,block)
 343 #define XMLRPC_TYPED_MEM_BLOCK_CONTENTS(type,block) \
 344     XMLRPC_MEMBLOCK_CONTENTS(type,block)
 345 #define XMLRPC_TYPED_MEM_BLOCK_RESIZE(type,env,block,size) \
 346     XMLRPC_MEMBLOCK_RESIZE(type,env,block,size)
 347 #define XMLRPC_TYPED_MEM_BLOCK_APPEND(type,env,block,data,size) \
 348     XMLRPC_MEMBLOCK_APPEND(type,env,block,data,size)
 349
 350
 351
 352 /*=========================================================================
 353 **  xmlrpc_value
 354 **=========================================================================
 355 **  An XML-RPC value (of any type).
 356 */
 357
 358 typedef enum {
 359     XMLRPC_TYPE_INT      = 0,
 360     XMLRPC_TYPE_BOOL     = 1,
 361     XMLRPC_TYPE_DOUBLE   = 2,
 362     XMLRPC_TYPE_DATETIME = 3,
 363     XMLRPC_TYPE_STRING   = 4,
 364     XMLRPC_TYPE_BASE64   = 5,
 365     XMLRPC_TYPE_ARRAY    = 6,
 366     XMLRPC_TYPE_STRUCT   = 7,
 367     XMLRPC_TYPE_C_PTR    = 8,
 368     XMLRPC_TYPE_DEAD     = 0xDEAD
 369 } xmlrpc_type;
 370
 371 /* These are *always* allocated on the heap. No exceptions. */
 372 typedef struct _xmlrpc_value xmlrpc_value;
 373
 374 #define XMLRPC_ASSERT_VALUE_OK(val) \
 375     XMLRPC_ASSERT((val) != NULL && (val)->_type != XMLRPC_TYPE_DEAD)
 376
 377 /* A handy type-checking routine. */
 378 #define XMLRPC_TYPE_CHECK(env,v,t) \
 379     do \
 380         if ((v)->_type != (t)) \
 381             XMLRPC_FAIL(env, XMLRPC_TYPE_ERROR, "Expected " #t); \
 382     while (0)
 383
 384 void
 385 xmlrpc_abort_if_array_bad(xmlrpc_value * const arrayP);
 386
 387 #define XMLRPC_ASSERT_ARRAY_OK(val) \
 388     xmlrpc_abort_if_array_bad(val)
 389
 390 /* Increment the reference count of an xmlrpc_value. */
 391 extern void xmlrpc_INCREF (xmlrpc_value* const value);
 392
 393 /* Decrement the reference count of an xmlrpc_value. If there
 394 ** are no more references, free it. */
 395 extern void xmlrpc_DECREF (xmlrpc_value* const value);
 396
 397 /* Get the type of an XML-RPC value. */
 398 extern xmlrpc_type xmlrpc_value_type (xmlrpc_value* value);
 399
 400 /* Build an xmlrpc_value from a format string.
 401 ** Increments the reference counts of input arguments if necessary.
 402 ** See the xmlrpc-c documentation for more information. */
 403 xmlrpc_value *
 404 xmlrpc_build_value(xmlrpc_env * const env,
 405                    const char * const format,
 406                    ...);
 407
 408 /* The same as the above, but using a va_list and more general */
 409 void
 410 xmlrpc_build_value_va(xmlrpc_env *    const env,
 411                       const char *    const format,
 412                       va_list               args,
 413                       xmlrpc_value ** const valPP,
 414                       const char **   const tailP);
 415
 416 /* Extract values from an xmlrpc_value and store them into C variables.
 417 ** Does not increment the reference counts of output values.
 418 ** See the xmlrpc-c documentation for more information. */
 419 void
 420 xmlrpc_parse_value(xmlrpc_env *   const envP,
 421                    xmlrpc_value * const value,
 422                    const char *   const format,
 423                    ...);
 424
 425 /* The same as the above, but using a va_list. */
 426 void
 427 xmlrpc_parse_value_va(xmlrpc_env *   const envP,
 428                       xmlrpc_value * const value,
 429                       const char *   const format,
 430                       va_list              args);
 431
 432 void
 433 xmlrpc_read_int(xmlrpc_env *         const envP,
 434                 const xmlrpc_value * const valueP,
 435                 int *                const intValueP);
 436
 437 void
 438 xmlrpc_read_double(xmlrpc_env *         const envP,
 439                    const xmlrpc_value * const valueP,
 440                    xmlrpc_double *      const doubleValueP);
 441
 442 void
 443 xmlrpc_read_bool(xmlrpc_env *         const envP,
 444                  const xmlrpc_value * const valueP,
 445                  xmlrpc_bool *        const boolValueP);
 446
 447 void
 448 xmlrpc_read_string(xmlrpc_env *         const envP,
 449                    const xmlrpc_value * const valueP,
 450                    const char **        const stringValueP);
 451
 452
 453 void
 454 xmlrpc_read_string_lp(xmlrpc_env *         const envP,
 455                       const xmlrpc_value * const valueP,
 456                       unsigned int *       const lengthP,
 457                       const char **        const stringValueP);
 458
 459 /* Return the number of elements in an XML-RPC array.
 460 ** Sets XMLRPC_TYPE_ERROR if 'array' is not an array. */
 461 int
 462 xmlrpc_array_size(xmlrpc_env *         const env,
 463                   const xmlrpc_value * const array);
 464
 465 /* Append an item to an XML-RPC array.
 466 ** Increments the reference count of 'value' if no fault occurs.
 467 ** Sets XMLRPC_TYPE_ERROR if 'array' is not an array. */
 468 extern void
 469 xmlrpc_array_append_item (xmlrpc_env*   const env,
 470                           xmlrpc_value* const array,
 471                           xmlrpc_value* const value);
 472
 473 void
 474 xmlrpc_array_read_item(xmlrpc_env *         const envP,
 475                        const xmlrpc_value * const arrayP,
 476                        unsigned int         const xmIndex,
 477                        xmlrpc_value **      const valuePP);
 478
 479 /* Get an item from an XML-RPC array.
 480 ** Does not increment the reference count of the returned value.
 481 ** Sets XMLRPC_TYPE_ERROR if 'array' is not an array.
 482 ** Sets XMLRPC_INDEX_ERROR if 'index' is out of bounds. */
 483 xmlrpc_value *
 484 xmlrpc_array_get_item(xmlrpc_env *         const env,
 485                       const xmlrpc_value * const array,
 486                       int                  const xmIndex);
 487
 488 /* Not implemented--we don't need it yet.
 489 extern
 490 int xmlrpc_array_set_item (xmlrpc_env* env,
 491 xmlrpc_value* array,
 492 int index,
 493                                   xmlrpc_value* value);
 494 */
 495
 496 /* Create a new struct.  Deprecated.  xmlrpc_build_value() is the
 497    general way to create an xmlrpc_value, including an empty struct.
 498 */
 499 xmlrpc_value *
 500 xmlrpc_struct_new(xmlrpc_env * env);
 501
 502 /* Return the number of key/value pairs in a struct.
 503 ** Sets XMLRPC_TYPE_ERROR if 'strct' is not a struct. */
 504 int
 505 xmlrpc_struct_size (xmlrpc_env   * env,
 506                     xmlrpc_value * strct);
 507
 508 /* Returns true iff 'strct' contains 'key'.
 509 ** Sets XMLRPC_TYPE_ERROR if 'strct' is not a struct. */
 510 int
 511 xmlrpc_struct_has_key(xmlrpc_env *   const envP,
 512                       xmlrpc_value * const strctP,
 513                       const char *   const key);
 514
 515 /* The same as the above, but the key may contain zero bytes.
 516    Deprecated.  xmlrpc_struct_get_value_v() is more general, and this
 517    case is not common enough to warrant a shortcut.
 518 */
 519 int
 520 xmlrpc_struct_has_key_n(xmlrpc_env   * const envP,
 521                         xmlrpc_value * const strctP,
 522                         const char *   const key,
 523                         size_t         const key_len);
 524
 525 #if 0
 526 /* Not implemented yet, but needed for completeness. */
 527 int
 528 xmlrpc_struct_has_key_v(xmlrpc_env *   env,
 529                         xmlrpc_value * strct,
 530                         xmlrpc_value * const keyval);
 531 #endif
 532
 533
 534 void
 535 xmlrpc_struct_find_value(xmlrpc_env *    const envP,
 536                          xmlrpc_value *  const structP,
 537                          const char *    const key,
 538                          xmlrpc_value ** const valuePP);
 539
 540
 541 void
 542 xmlrpc_struct_find_value_v(xmlrpc_env *    const envP,
 543                            xmlrpc_value *  const structP,
 544                            xmlrpc_value *  const keyP,
 545                            xmlrpc_value ** const valuePP);
 546
 547 void
 548 xmlrpc_struct_read_value_v(xmlrpc_env *    const envP,
 549                            xmlrpc_value *  const structP,
 550                            xmlrpc_value *  const keyP,
 551                            xmlrpc_value ** const valuePP);
 552
 553 void
 554 xmlrpc_struct_read_value(xmlrpc_env *    const envP,
 555                          xmlrpc_value *  const strctP,
 556                          const char *    const key,
 557                          xmlrpc_value ** const valuePP);
 558
 559 /* The "get_value" functions are deprecated.  Use the "find_value"
 560    and "read_value" functions instead.
 561 */
 562 xmlrpc_value *
 563 xmlrpc_struct_get_value(xmlrpc_env *   const envP,
 564                         xmlrpc_value * const strctP,
 565                         const char *   const key);
 566
 567 /* The same as above, but the key may contain zero bytes.
 568    Deprecated.  xmlrpc_struct_get_value_v() is more general, and this
 569    case is not common enough to warrant a shortcut.
 570 */
 571 xmlrpc_value *
 572 xmlrpc_struct_get_value_n(xmlrpc_env *   const envP,
 573                           xmlrpc_value * const strctP,
 574                           const char *   const key,
 575                           size_t         const key_len);
 576
 577 /* Set the value associated with 'key' in 'strct' to 'value'.
 578 ** Increments the reference count of value.
 579 ** Sets XMLRPC_TYPE_ERROR if 'strct' is not a struct. */
 580 void
 581 xmlrpc_struct_set_value(xmlrpc_env *   const env,
 582                         xmlrpc_value * const strct,
 583                         const char *   const key,
 584                         xmlrpc_value * const value);
 585
 586 /* The same as above, but the key may contain zero bytes.  Deprecated.
 587    The general way to set a structure value is xmlrpc_struct_set_value_v(),
 588    and this case is not common enough to deserve a shortcut.
 589 */
 590 void
 591 xmlrpc_struct_set_value_n(xmlrpc_env *    const env,
 592                           xmlrpc_value *  const strct,
 593                           const char *    const key,
 594                           size_t          const key_len,
 595                           xmlrpc_value *  const value);
 596
 597 /* The same as above, but the key must be an XML-RPC string.
 598 ** Fails with XMLRPC_TYPE_ERROR if 'keyval' is not a string. */
 599 void
 600 xmlrpc_struct_set_value_v(xmlrpc_env *   const env,
 601                           xmlrpc_value * const strct,
 602                           xmlrpc_value * const keyval,
 603                           xmlrpc_value * const value);
 604
 605 /* Given a zero-based index, return the matching key and value. This
 606 ** is normally used in conjunction with xmlrpc_struct_size.
 607 ** Fails with XMLRPC_TYPE_ERROR if 'struct' is not a struct.
 608 ** Fails with XMLRPC_INDEX_ERROR if 'index' is out of bounds. */
 609
 610 void
 611 xmlrpc_struct_read_member(xmlrpc_env *    const envP,
 612                           xmlrpc_value *  const structP,
 613                           unsigned int    const xmIndex,
 614                           xmlrpc_value ** const keyvalP,
 615                           xmlrpc_value ** const valueP);
 616
 617 /* The same as above, but does not increment the reference count of the
 618    two values it returns, and return NULL for both if it fails, and
 619    takes a signed integer for the index (but fails if it is negative).
 620
 621    Deprecated.
 622 */
 623 void
 624 xmlrpc_struct_get_key_and_value(xmlrpc_env *    const env,
 625                                 xmlrpc_value *  const strct,
 626                                 int             const xmIndex,
 627                                 xmlrpc_value ** const out_keyval,
 628                                 xmlrpc_value ** const out_value);
 629
 630
 631 /*=========================================================================
 632 **  Encoding XML
 633 **=======================================================================*/
 634
 635 /* Serialize an XML value without any XML header. This is primarily used
 636 ** for testing purposes. */
 637 void
 638 xmlrpc_serialize_value(xmlrpc_env *       env,
 639                        xmlrpc_mem_block * output,
 640                        xmlrpc_value *     value);
 641
 642 /* Serialize a list of parameters without any XML header. This is
 643 ** primarily used for testing purposes. */
 644 void
 645 xmlrpc_serialize_params(xmlrpc_env *       env,
 646                         xmlrpc_mem_block * output,
 647                         xmlrpc_value *     param_array);
 648
 649 /* Serialize an XML-RPC call. */
 650 void
 651 xmlrpc_serialize_call (xmlrpc_env *       const env,
 652                        xmlrpc_mem_block * const output,
 653                        const char *       const method_name,
 654                        xmlrpc_value *     const param_array);
 655
 656 /* Serialize an XML-RPC return value. */
 657 extern void
 658 xmlrpc_serialize_response(xmlrpc_env *       env,
 659                           xmlrpc_mem_block * output,
 660                           xmlrpc_value *     value);
 661
 662 /* Serialize an XML-RPC fault (as specified by 'fault'). */
 663 extern void
 664 xmlrpc_serialize_fault(xmlrpc_env *       env,
 665                        xmlrpc_mem_block * output,
 666                        xmlrpc_env *       fault);
 667
 668
 669 /*=========================================================================
 670 **  Decoding XML
 671 **=======================================================================*/
 672
 673 /* Parse an XML-RPC call. If an error occurs, set a fault and set
 674 ** the output variables to NULL.
 675 ** The caller is responsible for calling free(*out_method_name) and
 676 ** xmlrpc_DECREF(*out_param_array). */
 677 void
 678 xmlrpc_parse_call(xmlrpc_env *    const envP,
 679                   const char *    const xml_data,
 680                   size_t          const xml_len,
 681                   const char **   const out_method_name,
 682                   xmlrpc_value ** const out_param_array);
 683
 684 /* Parse an XML-RPC response. If a fault occurs (or was received over the
 685 ** wire), return NULL and set up 'env'. The calling is responsible for
 686 ** calling xmlrpc_DECREF on the return value (if it isn't NULL). */
 687 xmlrpc_value *
 688 xmlrpc_parse_response(xmlrpc_env * env,
 689                       const char * xml_data,
 690                       size_t       xml_len);
 691
 692
 693 /*=========================================================================
 694 **  XML-RPC Base64 Utilities
 695 **=========================================================================
 696 **  Here are some lightweight utilities which can be used to encode and
 697 **  decode Base64 data. These are exported mainly for testing purposes.
 698 */
 699
 700 /* This routine inserts newlines every 76 characters, as required by the
 701 ** Base64 specification. */
 702 xmlrpc_mem_block *
 703 xmlrpc_base64_encode(xmlrpc_env *    env,
 704                      unsigned char * bin_data,
 705                      size_t          bin_len);
 706
 707 /* This routine encodes everything in one line. This is needed for HTTP
 708 ** authentication and similar tasks. */
 709 xmlrpc_mem_block *
 710 xmlrpc_base64_encode_without_newlines(xmlrpc_env *    env,
 711                                       unsigned char * bin_data,
 712                                       size_t          bin_len);
 713
 714 /* This decodes Base64 data with or without newlines. */
 715 extern xmlrpc_mem_block *
 716 xmlrpc_base64_decode(xmlrpc_env * env,
 717                      char *       ascii_data,
 718                      size_t       ascii_len);
 719
 720
 721 /*=========================================================================
 722 **  UTF-8 Encoding and Decoding
 723 **=========================================================================
 724 **  We need a correct, reliable and secure UTF-8 decoder. This decoder
 725 **  raises a fault if it encounters invalid UTF-8.
 726 **
 727 **  Note that ANSI C does not precisely define the representation used
 728 **  by wchar_t--it may be UCS-2, UTF-16, UCS-4, or something from outer
 729 **  space. If your platform does something especially bizarre, you may
 730 **  need to reimplement these routines.
 731 */
 732
 733 #ifdef HAVE_UNICODE_WCHAR
 734
 735 /* Ensure that a string contains valid, legally-encoded UTF-8 data.
 736 ** (Incorrectly-encoded UTF-8 strings are often used to bypass security
 737 ** checks.) */
 738 void
 739 xmlrpc_validate_utf8 (xmlrpc_env * const env,
 740                       const char * const utf8_data,
 741                       size_t       const utf8_len);
 742
 743 /* Decode a UTF-8 string. */
 744 xmlrpc_mem_block *
 745 xmlrpc_utf8_to_wcs(xmlrpc_env * env,
 746                    char *       utf8_data,
 747                    size_t       utf8_len);
 748
 749 /* Encode a UTF-8 string. */
 750 xmlrpc_mem_block *
 751 xmlrpc_wcs_to_utf8(xmlrpc_env * env,
 752                    wchar_t *    wcs_data,
 753                    size_t       wcs_len);
 754
 755 #endif /* HAVE_UNICODE_WCHAR */
 756
 757 /*=========================================================================
 758 **  Authorization Cookie Handling
 759 **=========================================================================
 760 **  Routines to get and set values for authorizing via authorization
 761 **  cookies. Both the client and server use HTTP_COOKIE_AUTH to store
 762 **  the representation of the authorization value, which is actually
 763 **  just a base64 hash of username:password. (This entire method is
 764 **  a cookie replacement of basic authentication.)
 765 **/
 766
 767 extern void xmlrpc_authcookie_set(xmlrpc_env * env,
 768                                   const char * username,
 769                                   const char * password);
 770
 771 char *xmlrpc_authcookie(void);
 772
 773 #ifdef __cplusplus
 774 }
 775 #endif
 776
 777 /* In the days before xmlrpc_server.h existed, some of what's in it was
 778    in here.  For backward compatibility, we need to include it here, even
 779    though it really isn't logical to do so.
 780 */
 781 #include <cmxmlrpc/xmlrpc_server.h>
 782
 783 #endif
 784