include/curl/curl.h

   1 #ifndef __CURL_CURL_H
   2 #define __CURL_CURL_H
   3 /***************************************************************************
   4  *                                  _   _ ____  _
   5  *  Project                     ___| | | |  _ \| |
   6  *                             / __| | | | |_) | |
   7  *                            | (__| |_| |  _ <| |___
   8  *                             \___|\___/|_| \_\_____|
   9  *
  10  * Copyright (C) 1998 - 2009, Daniel Stenberg, <daniel@haxx.se>, et al.
  11  *
  12  * This software is licensed as described in the file COPYING, which
  13  * you should have received as part of this distribution. The terms
  14  * are also available at http://curl.haxx.se/docs/copyright.html.
  15  *
  16  * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  17  * copies of the Software, and permit persons to whom the Software is
  18  * furnished to do so, under the terms of the COPYING file.
  19  *
  20  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  21  * KIND, either express or implied.
  22  *
  23  * $Id$
  24  ***************************************************************************/
  25
  26 /*
  27  * If you have libcurl problems, all docs and details are found here:
  28  *   http://curl.haxx.se/libcurl/
  29  *
  30  * curl-library mailing list subscription and unsubscription web interface:
  31  *   http://cool.haxx.se/mailman/listinfo/curl-library/
  32  */
  33
  34 #include "curlver.h"         /* libcurl version defines   */
  35 #include "curl/curlbuild.h"  /* libcurl build definitions */
  36 #include "curlrules.h"       /* libcurl rules enforcement */
  37
  38 /*
  39  * Define WIN32 when build target is Win32 API
  40  */
  41
  42 #if (defined(_WIN32) || defined(__WIN32__)) && \
  43      !defined(WIN32) && !defined(__SYMBIAN32__)
  44 #define WIN32
  45 #endif
  46
  47 #include <stdio.h>
  48 #include <limits.h>
  49
  50 /* The include stuff here below is mainly for time_t! */
  51 #ifdef vms
  52 # include <types.h>
  53 # include <time.h>
  54 #else
  55 # include <sys/types.h>
  56 # include <time.h>
  57 #endif /* defined (vms) */
  58
  59 #if defined(WIN32) && !defined(_WIN32_WCE) && !defined(__GNUC__) && \
  60   !defined(__CYGWIN__) || defined(__MINGW32__)
  61 #if !(defined(_WINSOCKAPI_) || defined(_WINSOCK_H))
  62 /* The check above prevents the winsock2 inclusion if winsock.h already was
  63    included, since they can't co-exist without problems */
  64 #include <winsock2.h>
  65 #include <ws2tcpip.h>
  66 #endif
  67 #else
  68
  69 /* HP-UX systems version 9, 10 and 11 lack sys/select.h and so does oldish
  70    libc5-based Linux systems. Only include it on system that are known to
  71    require it! */
  72 #if defined(_AIX) || defined(__NOVELL_LIBC__) || defined(__NetBSD__) || \
  73     defined(__minix) || defined(__SYMBIAN32__) || defined(__INTEGRITY)
  74 #include <sys/select.h>
  75 #endif
  76
  77 #ifndef _WIN32_WCE
  78 #include <sys/socket.h>
  79 #endif
  80 #if !defined(WIN32) && !defined(__WATCOMC__)
  81 #include <sys/time.h>
  82 #endif
  83 #include <sys/types.h>
  84 #endif
  85
  86 #ifdef __BEOS__
  87 #include <support/SupportDefs.h>
  88 #endif
  89
  90 #ifdef  __cplusplus
  91 extern "C" {
  92 #endif
  93
  94 typedef void CURL;
  95
  96 #ifdef USES_DIRECT_CURL_UTILITIES
  97 #define CURL_EXTERN
  98 #else /* USES_DIRECT_CURL_UTILITIES */
  99
 100 /*
 101  * Decorate exportable functions for Win32 and Symbian OS DLL linking.
 102  * This avoids using a .def file for building libcurl.dll.
 103  */
 104 #if (defined(WIN32) || defined(_WIN32) || defined(__SYMBIAN32__)) && \
 105      !defined(CURL_STATICLIB)
 106 #if defined(BUILDING_LIBCURL)
 107 #define CURL_EXTERN  __declspec(dllexport)
 108 #else
 109 #define CURL_EXTERN  __declspec(dllimport)
 110 #endif
 111 #else
 112
 113 #ifdef CURL_HIDDEN_SYMBOLS
 114 /*
 115  * This definition is used to make external definitions visible in the
 116  * shared library when symbols are hidden by default.  It makes no
 117  * difference when compiling applications whether this is set or not,
 118  * only when compiling the library.
 119  */
 120 #define CURL_EXTERN CURL_EXTERN_SYMBOL
 121 #else
 122 #define CURL_EXTERN
 123 #endif
 124 #endif
 125 #endif /* USES_DIRECT_CURL_UTILITIES */
 126
 127 #ifndef curl_socket_typedef
 128 /* socket typedef */
 129 #ifdef WIN32
 130 typedef SOCKET curl_socket_t;
 131 #define CURL_SOCKET_BAD INVALID_SOCKET
 132 #else
 133 typedef int curl_socket_t;
 134 #define CURL_SOCKET_BAD -1
 135 #endif
 136 #define curl_socket_typedef
 137 #endif /* curl_socket_typedef */
 138
 139 struct curl_httppost {
 140   struct curl_httppost *next;       /* next entry in the list */
 141   char *name;                       /* pointer to allocated name */
 142   long namelength;                  /* length of name length */
 143   char *contents;                   /* pointer to allocated data contents */
 144   long contentslength;              /* length of contents field */
 145   char *buffer;                     /* pointer to allocated buffer contents */
 146   long bufferlength;                /* length of buffer field */
 147   char *contenttype;                /* Content-Type */
 148   struct curl_slist* contentheader; /* list of extra headers for this form */
 149   struct curl_httppost *more;       /* if one field name has more than one
 150                                        file, this link should link to following
 151                                        files */
 152   long flags;                       /* as defined below */
 153 #define HTTPPOST_FILENAME (1<<0)    /* specified content is a file name */
 154 #define HTTPPOST_READFILE (1<<1)    /* specified content is a file name */
 155 #define HTTPPOST_PTRNAME (1<<2)     /* name is only stored pointer
 156                                        do not free in formfree */
 157 #define HTTPPOST_PTRCONTENTS (1<<3) /* contents is only stored pointer
 158                                        do not free in formfree */
 159 #define HTTPPOST_BUFFER (1<<4)      /* upload file from buffer */
 160 #define HTTPPOST_PTRBUFFER (1<<5)   /* upload file from pointer contents */
 161 #define HTTPPOST_CALLBACK (1<<6)    /* upload file contents by using the
 162                                        regular read callback to get the data
 163                                        and pass the given pointer as custom
 164                                        pointer */
 165
 166   char *showfilename;               /* The file name to show. If not set, the
 167                                        actual file name will be used (if this
 168                                        is a file part) */
 169   void *userp;                      /* custom pointer used for
 170                                        HTTPPOST_CALLBACK posts */
 171 };
 172
 173 typedef int (*curl_progress_callback)(void *clientp,
 174                                       double dltotal,
 175                                       double dlnow,
 176                                       double ultotal,
 177                                       double ulnow);
 178
 179 #ifndef CURL_MAX_WRITE_SIZE
 180   /* Tests have proven that 20K is a very bad buffer size for uploads on
 181      Windows, while 16K for some odd reason performed a lot better.
 182      We do the ifndef check to allow this value to easier be changed at build
 183      time for those who feel adventurous. */
 184 #define CURL_MAX_WRITE_SIZE 16384
 185 #endif
 186 /* This is a magic return code for the write callback that, when returned,
 187    will signal libcurl to pause receiving on the current transfer. */
 188 #define CURL_WRITEFUNC_PAUSE 0x10000001
 189 typedef size_t (*curl_write_callback)(char *buffer,
 190                                       size_t size,
 191                                       size_t nitems,
 192                                       void *outstream);
 193
 194 /* This is a return code for the read callback that, when returned, will
 195    signal libcurl to immediately abort the current transfer. */
 196 #define CURL_READFUNC_ABORT 0x10000000
 197 /* This is a return code for the read callback that, when returned, will
 198    signal libcurl to pause sending data on the current transfer. */
 199 #define CURL_READFUNC_PAUSE 0x10000001
 200 typedef int (*curl_seek_callback)(void *instream,
 201                                   curl_off_t offset,
 202                                   int origin); /* 'whence' */
 203
 204 typedef size_t (*curl_read_callback)(char *buffer,
 205                                       size_t size,
 206                                       size_t nitems,
 207                                       void *instream);
 208
 209 typedef enum  {
 210   CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
 211   CURLSOCKTYPE_LAST   /* never use */
 212 } curlsocktype;
 213
 214 typedef int (*curl_sockopt_callback)(void *clientp,
 215                                      curl_socket_t curlfd,
 216                                      curlsocktype purpose);
 217
 218 struct curl_sockaddr {
 219   int family;
 220   int socktype;
 221   int protocol;
 222   unsigned int addrlen; /* addrlen was a socklen_t type before 7.18.0 but it
 223                            turned really ugly and painful on the systems that
 224                            lack this type */
 225   struct sockaddr addr;
 226 };
 227
 228 typedef curl_socket_t
 229 (*curl_opensocket_callback)(void *clientp,
 230                             curlsocktype purpose,
 231                             struct curl_sockaddr *address);
 232
 233 #ifndef CURL_NO_OLDIES
 234   /* not used since 7.10.8, will be removed in a future release */
 235 typedef int (*curl_passwd_callback)(void *clientp,
 236                                     const char *prompt,
 237                                     char *buffer,
 238                                     int buflen);
 239 #endif
 240
 241 typedef enum {
 242   CURLIOE_OK,            /* I/O operation successful */
 243   CURLIOE_UNKNOWNCMD,    /* command was unknown to callback */
 244   CURLIOE_FAILRESTART,   /* failed to restart the read */
 245   CURLIOE_LAST           /* never use */
 246 } curlioerr;
 247
 248 typedef enum  {
 249   CURLIOCMD_NOP,         /* no operation */
 250   CURLIOCMD_RESTARTREAD, /* restart the read stream from start */
 251   CURLIOCMD_LAST         /* never use */
 252 } curliocmd;
 253
 254 typedef curlioerr (*curl_ioctl_callback)(CURL *handle,
 255                                          int cmd,
 256                                          void *clientp);
 257
 258 /*
 259  * The following typedef's are signatures of malloc, free, realloc, strdup and
 260  * calloc respectively.  Function pointers of these types can be passed to the
 261  * curl_global_init_mem() function to set user defined memory management
 262  * callback routines.
 263  */
 264 typedef void *(*curl_malloc_callback)(size_t size);
 265 typedef void (*curl_free_callback)(void *ptr);
 266 typedef void *(*curl_realloc_callback)(void *ptr, size_t size);
 267 typedef char *(*curl_strdup_callback)(const char *str);
 268 typedef void *(*curl_calloc_callback)(size_t nmemb, size_t size);
 269
 270 /* the kind of data that is passed to information_callback*/
 271 typedef enum {
 272   CURLINFO_TEXT = 0,
 273   CURLINFO_HEADER_IN,    /* 1 */
 274   CURLINFO_HEADER_OUT,   /* 2 */
 275   CURLINFO_DATA_IN,      /* 3 */
 276   CURLINFO_DATA_OUT,     /* 4 */
 277   CURLINFO_SSL_DATA_IN,  /* 5 */
 278   CURLINFO_SSL_DATA_OUT, /* 6 */
 279   CURLINFO_END
 280 } curl_infotype;
 281
 282 typedef int (*curl_debug_callback)
 283        (CURL *handle,      /* the handle/transfer this concerns */
 284         curl_infotype type, /* what kind of data */
 285         char *data,        /* points to the data */
 286         size_t size,       /* size of the data pointed to */
 287         void *userptr);    /* whatever the user please */
 288
 289 /* All possible error codes from all sorts of curl functions. Future versions
 290    may return other values, stay prepared.
 291
 292    Always add new return codes last. Never *EVER* remove any. The return
 293    codes must remain the same!
 294  */
 295
 296 typedef enum {
 297   CURLE_OK = 0,
 298   CURLE_UNSUPPORTED_PROTOCOL,    /* 1 */
 299   CURLE_FAILED_INIT,             /* 2 */
 300   CURLE_URL_MALFORMAT,           /* 3 */
 301   CURLE_OBSOLETE4,               /* 4 - NOT USED */
 302   CURLE_COULDNT_RESOLVE_PROXY,   /* 5 */
 303   CURLE_COULDNT_RESOLVE_HOST,    /* 6 */
 304   CURLE_COULDNT_CONNECT,         /* 7 */
 305   CURLE_FTP_WEIRD_SERVER_REPLY,  /* 8 */
 306   CURLE_REMOTE_ACCESS_DENIED,    /* 9 a service was denied by the server
 307                                     due to lack of access - when login fails
 308                                     this is not returned. */
 309   CURLE_OBSOLETE10,              /* 10 - NOT USED */
 310   CURLE_FTP_WEIRD_PASS_REPLY,    /* 11 */
 311   CURLE_OBSOLETE12,              /* 12 - NOT USED */
 312   CURLE_FTP_WEIRD_PASV_REPLY,    /* 13 */
 313   CURLE_FTP_WEIRD_227_FORMAT,    /* 14 */
 314   CURLE_FTP_CANT_GET_HOST,       /* 15 */
 315   CURLE_OBSOLETE16,              /* 16 - NOT USED */
 316   CURLE_FTP_COULDNT_SET_TYPE,    /* 17 */
 317   CURLE_PARTIAL_FILE,            /* 18 */
 318   CURLE_FTP_COULDNT_RETR_FILE,   /* 19 */
 319   CURLE_OBSOLETE20,              /* 20 - NOT USED */
 320   CURLE_QUOTE_ERROR,             /* 21 - quote command failure */
 321   CURLE_HTTP_RETURNED_ERROR,     /* 22 */
 322   CURLE_WRITE_ERROR,             /* 23 */
 323   CURLE_OBSOLETE24,              /* 24 - NOT USED */
 324   CURLE_UPLOAD_FAILED,           /* 25 - failed upload "command" */
 325   CURLE_READ_ERROR,              /* 26 - couldn't open/read from file */
 326   CURLE_OUT_OF_MEMORY,           /* 27 */
 327   /* Note: CURLE_OUT_OF_MEMORY may sometimes indicate a conversion error
 328            instead of a memory allocation error if CURL_DOES_CONVERSIONS
 329            is defined
 330   */
 331   CURLE_OPERATION_TIMEDOUT,      /* 28 - the timeout time was reached */
 332   CURLE_OBSOLETE29,              /* 29 - NOT USED */
 333   CURLE_FTP_PORT_FAILED,         /* 30 - FTP PORT operation failed */
 334   CURLE_FTP_COULDNT_USE_REST,    /* 31 - the REST command failed */
 335   CURLE_OBSOLETE32,              /* 32 - NOT USED */
 336   CURLE_RANGE_ERROR,             /* 33 - RANGE "command" didn't work */
 337   CURLE_HTTP_POST_ERROR,         /* 34 */
 338   CURLE_SSL_CONNECT_ERROR,       /* 35 - wrong when connecting with SSL */
 339   CURLE_BAD_DOWNLOAD_RESUME,     /* 36 - couldn't resume download */
 340   CURLE_FILE_COULDNT_READ_FILE,  /* 37 */
 341   CURLE_LDAP_CANNOT_BIND,        /* 38 */
 342   CURLE_LDAP_SEARCH_FAILED,      /* 39 */
 343   CURLE_OBSOLETE40,              /* 40 - NOT USED */
 344   CURLE_FUNCTION_NOT_FOUND,      /* 41 */
 345   CURLE_ABORTED_BY_CALLBACK,     /* 42 */
 346   CURLE_BAD_FUNCTION_ARGUMENT,   /* 43 */
 347   CURLE_OBSOLETE44,              /* 44 - NOT USED */
 348   CURLE_INTERFACE_FAILED,        /* 45 - CURLOPT_INTERFACE failed */
 349   CURLE_OBSOLETE46,              /* 46 - NOT USED */
 350   CURLE_TOO_MANY_REDIRECTS ,     /* 47 - catch endless re-direct loops */
 351   CURLE_UNKNOWN_TELNET_OPTION,   /* 48 - User specified an unknown option */
 352   CURLE_TELNET_OPTION_SYNTAX ,   /* 49 - Malformed telnet option */
 353   CURLE_OBSOLETE50,              /* 50 - NOT USED */
 354   CURLE_PEER_FAILED_VERIFICATION, /* 51 - peer's certificate or fingerprint
 355                                      wasn't verified fine */
 356   CURLE_GOT_NOTHING,             /* 52 - when this is a specific error */
 357   CURLE_SSL_ENGINE_NOTFOUND,     /* 53 - SSL crypto engine not found */
 358   CURLE_SSL_ENGINE_SETFAILED,    /* 54 - can not set SSL crypto engine as
 359                                     default */
 360   CURLE_SEND_ERROR,              /* 55 - failed sending network data */
 361   CURLE_RECV_ERROR,              /* 56 - failure in receiving network data */
 362   CURLE_OBSOLETE57,              /* 57 - NOT IN USE */
 363   CURLE_SSL_CERTPROBLEM,         /* 58 - problem with the local certificate */
 364   CURLE_SSL_CIPHER,              /* 59 - couldn't use specified cipher */
 365   CURLE_SSL_CACERT,              /* 60 - problem with the CA cert (path?) */
 366   CURLE_BAD_CONTENT_ENCODING,    /* 61 - Unrecognized transfer encoding */
 367   CURLE_LDAP_INVALID_URL,        /* 62 - Invalid LDAP URL */
 368   CURLE_FILESIZE_EXCEEDED,       /* 63 - Maximum file size exceeded */
 369   CURLE_USE_SSL_FAILED,          /* 64 - Requested FTP SSL level failed */
 370   CURLE_SEND_FAIL_REWIND,        /* 65 - Sending the data requires a rewind
 371                                     that failed */
 372   CURLE_SSL_ENGINE_INITFAILED,   /* 66 - failed to initialise ENGINE */
 373   CURLE_LOGIN_DENIED,            /* 67 - user, password or similar was not
 374                                     accepted and we failed to login */
 375   CURLE_TFTP_NOTFOUND,           /* 68 - file not found on server */
 376   CURLE_TFTP_PERM,               /* 69 - permission problem on server */
 377   CURLE_REMOTE_DISK_FULL,        /* 70 - out of disk space on server */
 378   CURLE_TFTP_ILLEGAL,            /* 71 - Illegal TFTP operation */
 379   CURLE_TFTP_UNKNOWNID,          /* 72 - Unknown transfer ID */
 380   CURLE_REMOTE_FILE_EXISTS,      /* 73 - File already exists */
 381   CURLE_TFTP_NOSUCHUSER,         /* 74 - No such user */
 382   CURLE_CONV_FAILED,             /* 75 - conversion failed */
 383   CURLE_CONV_REQD,               /* 76 - caller must register conversion
 384                                     callbacks using curl_easy_setopt options
 385                                     CURLOPT_CONV_FROM_NETWORK_FUNCTION,
 386                                     CURLOPT_CONV_TO_NETWORK_FUNCTION, and
 387                                     CURLOPT_CONV_FROM_UTF8_FUNCTION */
 388   CURLE_SSL_CACERT_BADFILE,      /* 77 - could not load CACERT file, missing
 389                                     or wrong format */
 390   CURLE_REMOTE_FILE_NOT_FOUND,   /* 78 - remote file not found */
 391   CURLE_SSH,                     /* 79 - error from the SSH layer, somewhat
 392                                     generic so the error message will be of
 393                                     interest when this has happened */
 394
 395   CURLE_SSL_SHUTDOWN_FAILED,     /* 80 - Failed to shut down the SSL
 396                                     connection */
 397   CURLE_AGAIN,                   /* 81 - socket is not ready for send/recv,
 398                                     wait till it's ready and try again (Added
 399                                     in 7.18.2) */
 400   CURLE_SSL_CRL_BADFILE,         /* 82 - could not load CRL file, missing or
 401                                     wrong format (Added in 7.19.0) */
 402   CURLE_SSL_ISSUER_ERROR,        /* 83 - Issuer check failed.  (Added in
 403                                     7.19.0) */
 404   CURL_LAST /* never use! */
 405 } CURLcode;
 406
 407 #ifndef CURL_NO_OLDIES /* define this to test if your app builds with all
 408                           the obsolete stuff removed! */
 409
 410 /* Backwards compatibility with older names */
 411
 412 /* The following were added in 7.17.1 */
 413 /* These are scheduled to disappear by 2009 */
 414 #define CURLE_SSL_PEER_CERTIFICATE CURLE_PEER_FAILED_VERIFICATION
 415
 416 /* The following were added in 7.17.0 */
 417 /* These are scheduled to disappear by 2009 */
 418 #define CURLE_OBSOLETE CURLE_OBSOLETE50 /* noone should be using this! */
 419 #define CURLE_BAD_PASSWORD_ENTERED CURLE_OBSOLETE46
 420 #define CURLE_BAD_CALLING_ORDER CURLE_OBSOLETE44
 421 #define CURLE_FTP_USER_PASSWORD_INCORRECT CURLE_OBSOLETE10
 422 #define CURLE_FTP_CANT_RECONNECT CURLE_OBSOLETE16
 423 #define CURLE_FTP_COULDNT_GET_SIZE CURLE_OBSOLETE32
 424 #define CURLE_FTP_COULDNT_SET_ASCII CURLE_OBSOLETE29
 425 #define CURLE_FTP_WEIRD_USER_REPLY CURLE_OBSOLETE12
 426 #define CURLE_FTP_WRITE_ERROR CURLE_OBSOLETE20
 427 #define CURLE_LIBRARY_NOT_FOUND CURLE_OBSOLETE40
 428 #define CURLE_MALFORMAT_USER CURLE_OBSOLETE24
 429 #define CURLE_SHARE_IN_USE CURLE_OBSOLETE57
 430 #define CURLE_URL_MALFORMAT_USER CURLE_OBSOLETE4
 431
 432 #define CURLE_FTP_ACCESS_DENIED CURLE_REMOTE_ACCESS_DENIED
 433 #define CURLE_FTP_COULDNT_SET_BINARY CURLE_FTP_COULDNT_SET_TYPE
 434 #define CURLE_FTP_QUOTE_ERROR CURLE_QUOTE_ERROR
 435 #define CURLE_TFTP_DISKFULL CURLE_REMOTE_DISK_FULL
 436 #define CURLE_TFTP_EXISTS CURLE_REMOTE_FILE_EXISTS
 437 #define CURLE_HTTP_RANGE_ERROR CURLE_RANGE_ERROR
 438 #define CURLE_FTP_SSL_FAILED CURLE_USE_SSL_FAILED
 439
 440 /* The following were added earlier */
 441
 442 #define CURLE_OPERATION_TIMEOUTED CURLE_OPERATION_TIMEDOUT
 443
 444 #define CURLE_HTTP_NOT_FOUND CURLE_HTTP_RETURNED_ERROR
 445 #define CURLE_HTTP_PORT_FAILED CURLE_INTERFACE_FAILED
 446 #define CURLE_FTP_COULDNT_STOR_FILE CURLE_UPLOAD_FAILED
 447
 448 #define CURLE_FTP_PARTIAL_FILE CURLE_PARTIAL_FILE
 449 #define CURLE_FTP_BAD_DOWNLOAD_RESUME CURLE_BAD_DOWNLOAD_RESUME
 450
 451 /* This was the error code 50 in 7.7.3 and a few earlier versions, this
 452    is no longer used by libcurl but is instead #defined here only to not
 453    make programs break */
 454 #define CURLE_ALREADY_COMPLETE 99999
 455
 456 #endif /*!CURL_NO_OLDIES*/
 457
 458 /* This prototype applies to all conversion callbacks */
 459 typedef CURLcode (*curl_conv_callback)(char *buffer, size_t length);
 460
 461 typedef CURLcode (*curl_ssl_ctx_callback)(CURL *curl,    /* easy handle */
 462                                           void *ssl_ctx, /* actually an
 463                                                             OpenSSL SSL_CTX */
 464                                           void *userptr);
 465
 466 typedef enum {
 467   CURLPROXY_HTTP = 0,   /* added in 7.10, new in 7.19.4 default is to use
 468                            CONNECT HTTP/1.1 */
 469   CURLPROXY_HTTP_1_0 = 1,   /* added in 7.19.4, force to use CONNECT
 470                                HTTP/1.0  */
 471   CURLPROXY_SOCKS4 = 4, /* support added in 7.15.2, enum existed already
 472                            in 7.10 */
 473   CURLPROXY_SOCKS5 = 5, /* added in 7.10 */
 474   CURLPROXY_SOCKS4A = 6, /* added in 7.18.0 */
 475   CURLPROXY_SOCKS5_HOSTNAME = 7 /* Use the SOCKS5 protocol but pass along the
 476                                    host name rather than the IP address. added
 477                                    in 7.18.0 */
 478 } curl_proxytype;  /* this enum was added in 7.10 */
 479
 480 #define CURLAUTH_NONE         0       /* nothing */
 481 #define CURLAUTH_BASIC        (1<<0)  /* Basic (default) */
 482 #define CURLAUTH_DIGEST       (1<<1)  /* Digest */
 483 #define CURLAUTH_GSSNEGOTIATE (1<<2)  /* GSS-Negotiate */
 484 #define CURLAUTH_NTLM         (1<<3)  /* NTLM */
 485 #define CURLAUTH_DIGEST_IE    (1<<4)  /* Digest with IE flavour */
 486 #define CURLAUTH_ANY (~CURLAUTH_DIGEST_IE)  /* all fine types set */
 487 #define CURLAUTH_ANYSAFE (~(CURLAUTH_BASIC|CURLAUTH_DIGEST_IE))
 488
 489 #define CURLSSH_AUTH_ANY       ~0     /* all types supported by the server */
 490 #define CURLSSH_AUTH_NONE      0      /* none allowed, silly but complete */
 491 #define CURLSSH_AUTH_PUBLICKEY (1<<0) /* public/private key files */
 492 #define CURLSSH_AUTH_PASSWORD  (1<<1) /* password */
 493 #define CURLSSH_AUTH_HOST      (1<<2) /* host key files */
 494 #define CURLSSH_AUTH_KEYBOARD  (1<<3) /* keyboard interactive */
 495 #define CURLSSH_AUTH_DEFAULT CURLSSH_AUTH_ANY
 496
 497 #define CURL_ERROR_SIZE 256
 498
 499 /* parameter for the CURLOPT_USE_SSL option */
 500 typedef enum {
 501   CURLUSESSL_NONE,    /* do not attempt to use SSL */
 502   CURLUSESSL_TRY,     /* try using SSL, proceed anyway otherwise */
 503   CURLUSESSL_CONTROL, /* SSL for the control connection or fail */
 504   CURLUSESSL_ALL,     /* SSL for all communication or fail */
 505   CURLUSESSL_LAST     /* not an option, never use */
 506 } curl_usessl;
 507
 508 #ifndef CURL_NO_OLDIES /* define this to test if your app builds with all
 509                           the obsolete stuff removed! */
 510
 511 /* Backwards compatibility with older names */
 512 /* These are scheduled to disappear by 2009 */
 513
 514 #define CURLFTPSSL_NONE CURLUSESSL_NONE
 515 #define CURLFTPSSL_TRY CURLUSESSL_TRY
 516 #define CURLFTPSSL_CONTROL CURLUSESSL_CONTROL
 517 #define CURLFTPSSL_ALL CURLUSESSL_ALL
 518 #define CURLFTPSSL_LAST CURLUSESSL_LAST
 519 #define curl_ftpssl curl_usessl
 520 #endif /*!CURL_NO_OLDIES*/
 521
 522 /* parameter for the CURLOPT_FTP_SSL_CCC option */
 523 typedef enum {
 524   CURLFTPSSL_CCC_NONE,    /* do not send CCC */
 525   CURLFTPSSL_CCC_PASSIVE, /* Let the server initiate the shutdown */
 526   CURLFTPSSL_CCC_ACTIVE,  /* Initiate the shutdown */
 527   CURLFTPSSL_CCC_LAST     /* not an option, never use */
 528 } curl_ftpccc;
 529
 530 /* parameter for the CURLOPT_FTPSSLAUTH option */
 531 typedef enum {
 532   CURLFTPAUTH_DEFAULT, /* let libcurl decide */
 533   CURLFTPAUTH_SSL,     /* use "AUTH SSL" */
 534   CURLFTPAUTH_TLS,     /* use "AUTH TLS" */
 535   CURLFTPAUTH_LAST /* not an option, never use */
 536 } curl_ftpauth;
 537
 538 /* parameter for the CURLOPT_FTP_CREATE_MISSING_DIRS option */
 539 typedef enum {
 540   CURLFTP_CREATE_DIR_NONE,  /* do NOT create missing dirs! */
 541   CURLFTP_CREATE_DIR,       /* (FTP/SFTP) if CWD fails, try MKD and then CWD
 542                                again if MKD succeeded, for SFTP this does
 543                                similar magic */
 544   CURLFTP_CREATE_DIR_RETRY, /* (FTP only) if CWD fails, try MKD and then CWD
 545                                again even if MKD failed! */
 546   CURLFTP_CREATE_DIR_LAST   /* not an option, never use */
 547 } curl_ftpcreatedir;
 548
 549 /* parameter for the CURLOPT_FTP_FILEMETHOD option */
 550 typedef enum {
 551   CURLFTPMETHOD_DEFAULT,   /* let libcurl pick */
 552   CURLFTPMETHOD_MULTICWD,  /* single CWD operation for each path part */
 553   CURLFTPMETHOD_NOCWD,     /* no CWD at all */
 554   CURLFTPMETHOD_SINGLECWD, /* one CWD to full dir, then work on file */
 555   CURLFTPMETHOD_LAST       /* not an option, never use */
 556 } curl_ftpmethod;
 557
 558 /* CURLPROTO_ defines are for the CURLOPT_*PROTOCOLS options */
 559 #define CURLPROTO_HTTP   (1<<0)
 560 #define CURLPROTO_HTTPS  (1<<1)
 561 #define CURLPROTO_FTP    (1<<2)
 562 #define CURLPROTO_FTPS   (1<<3)
 563 #define CURLPROTO_SCP    (1<<4)
 564 #define CURLPROTO_SFTP   (1<<5)
 565 #define CURLPROTO_TELNET (1<<6)
 566 #define CURLPROTO_LDAP   (1<<7)
 567 #define CURLPROTO_LDAPS  (1<<8)
 568 #define CURLPROTO_DICT   (1<<9)
 569 #define CURLPROTO_FILE   (1<<10)
 570 #define CURLPROTO_TFTP   (1<<11)
 571 #define CURLPROTO_ALL    (~0) /* enable everything */
 572
 573 /* long may be 32 or 64 bits, but we should never depend on anything else
 574    but 32 */
 575 #define CURLOPTTYPE_LONG          0
 576 #define CURLOPTTYPE_OBJECTPOINT   10000
 577 #define CURLOPTTYPE_FUNCTIONPOINT 20000
 578 #define CURLOPTTYPE_OFF_T         30000
 579
 580 /* name is uppercase CURLOPT_<name>,
 581    type is one of the defined CURLOPTTYPE_<type>
 582    number is unique identifier */
 583 #ifdef CINIT
 584 #undef CINIT
 585 #endif
 586
 587 #ifdef CURL_ISOCPP
 588 #define CINIT(name,type,number) CURLOPT_ ## name = CURLOPTTYPE_ ## type + number
 589 #else
 590 /* The macro "##" is ISO C, we assume pre-ISO C doesn't support it. */
 591 #define LONG          CURLOPTTYPE_LONG
 592 #define OBJECTPOINT   CURLOPTTYPE_OBJECTPOINT
 593 #define FUNCTIONPOINT CURLOPTTYPE_FUNCTIONPOINT
 594 #define OFF_T         CURLOPTTYPE_OFF_T
 595 #define CINIT(name,type,number) CURLOPT_/**/name = type + number
 596 #endif
 597
 598 /*
 599  * This macro-mania below setups the CURLOPT_[what] enum, to be used with
 600  * curl_easy_setopt(). The first argument in the CINIT() macro is the [what]
 601  * word.
 602  */
 603
 604 typedef enum {
 605   /* This is the FILE * or void * the regular output should be written to. */
 606   CINIT(FILE, OBJECTPOINT, 1),
 607
 608   /* The full URL to get/put */
 609   CINIT(URL,  OBJECTPOINT, 2),
 610
 611   /* Port number to connect to, if other than default. */
 612   CINIT(PORT, LONG, 3),
 613
 614   /* Name of proxy to use. */
 615   CINIT(PROXY, OBJECTPOINT, 4),
 616
 617   /* "name:password" to use when fetching. */
 618   CINIT(USERPWD, OBJECTPOINT, 5),
 619
 620   /* "name:password" to use with proxy. */
 621   CINIT(PROXYUSERPWD, OBJECTPOINT, 6),
 622
 623   /* Range to get, specified as an ASCII string. */
 624   CINIT(RANGE, OBJECTPOINT, 7),
 625
 626   /* not used */
 627
 628   /* Specified file stream to upload from (use as input): */
 629   CINIT(INFILE, OBJECTPOINT, 9),
 630
 631   /* Buffer to receive error messages in, must be at least CURL_ERROR_SIZE
 632    * bytes big. If this is not used, error messages go to stderr instead: */
 633   CINIT(ERRORBUFFER, OBJECTPOINT, 10),
 634
 635   /* Function that will be called to store the output (instead of fwrite). The
 636    * parameters will use fwrite() syntax, make sure to follow them. */
 637   CINIT(WRITEFUNCTION, FUNCTIONPOINT, 11),
 638
 639   /* Function that will be called to read the input (instead of fread). The
 640    * parameters will use fread() syntax, make sure to follow them. */
 641   CINIT(READFUNCTION, FUNCTIONPOINT, 12),
 642
 643   /* Time-out the read operation after this amount of seconds */
 644   CINIT(TIMEOUT, LONG, 13),
 645
 646   /* If the CURLOPT_INFILE is used, this can be used to inform libcurl about
 647    * how large the file being sent really is. That allows better error
 648    * checking and better verifies that the upload was successful. -1 means
 649    * unknown size.
 650    *
 651    * For large file support, there is also a _LARGE version of the key
 652    * which takes an off_t type, allowing platforms with larger off_t
 653    * sizes to handle larger files.  See below for INFILESIZE_LARGE.
 654    */
 655   CINIT(INFILESIZE, LONG, 14),
 656
 657   /* POST static input fields. */
 658   CINIT(POSTFIELDS, OBJECTPOINT, 15),
 659
 660   /* Set the referrer page (needed by some CGIs) */
 661   CINIT(REFERER, OBJECTPOINT, 16),
 662
 663   /* Set the FTP PORT string (interface name, named or numerical IP address)
 664      Use i.e '-' to use default address. */
 665   CINIT(FTPPORT, OBJECTPOINT, 17),
 666
 667   /* Set the User-Agent string (examined by some CGIs) */
 668   CINIT(USERAGENT, OBJECTPOINT, 18),
 669
 670   /* If the download receives less than "low speed limit" bytes/second
 671    * during "low speed time" seconds, the operations is aborted.
 672    * You could i.e if you have a pretty high speed connection, abort if
 673    * it is less than 2000 bytes/sec during 20 seconds.
 674    */
 675
 676   /* Set the "low speed limit" */
 677   CINIT(LOW_SPEED_LIMIT, LONG, 19),
 678
 679   /* Set the "low speed time" */
 680   CINIT(LOW_SPEED_TIME, LONG, 20),
 681
 682   /* Set the continuation offset.
 683    *
 684    * Note there is also a _LARGE version of this key which uses
 685    * off_t types, allowing for large file offsets on platforms which
 686    * use larger-than-32-bit off_t's.  Look below for RESUME_FROM_LARGE.
 687    */
 688   CINIT(RESUME_FROM, LONG, 21),
 689
 690   /* Set cookie in request: */
 691   CINIT(COOKIE, OBJECTPOINT, 22),
 692
 693   /* This points to a linked list of headers, struct curl_slist kind */
 694   CINIT(HTTPHEADER, OBJECTPOINT, 23),
 695
 696   /* This points to a linked list of post entries, struct curl_httppost */
 697   CINIT(HTTPPOST, OBJECTPOINT, 24),
 698
 699   /* name of the file keeping your private SSL-certificate */
 700   CINIT(SSLCERT, OBJECTPOINT, 25),
 701
 702   /* password for the SSL or SSH private key */
 703   CINIT(KEYPASSWD, OBJECTPOINT, 26),
 704
 705   /* send TYPE parameter? */
 706   CINIT(CRLF, LONG, 27),
 707
 708   /* send linked-list of QUOTE commands */
 709   CINIT(QUOTE, OBJECTPOINT, 28),
 710
 711   /* send FILE * or void * to store headers to, if you use a callback it
 712      is simply passed to the callback unmodified */
 713   CINIT(WRITEHEADER, OBJECTPOINT, 29),
 714
 715   /* point to a file to read the initial cookies from, also enables
 716      "cookie awareness" */
 717   CINIT(COOKIEFILE, OBJECTPOINT, 31),
 718
 719   /* What version to specifically try to use.
 720      See CURL_SSLVERSION defines below. */
 721   CINIT(SSLVERSION, LONG, 32),
 722
 723   /* What kind of HTTP time condition to use, see defines */
 724   CINIT(TIMECONDITION, LONG, 33),
 725
 726   /* Time to use with the above condition. Specified in number of seconds
 727      since 1 Jan 1970 */
 728   CINIT(TIMEVALUE, LONG, 34),
 729
 730   /* 35 = OBSOLETE */
 731
 732   /* Custom request, for customizing the get command like
 733      HTTP: DELETE, TRACE and others
 734      FTP: to use a different list command
 735      */
 736   CINIT(CUSTOMREQUEST, OBJECTPOINT, 36),
 737
 738   /* HTTP request, for odd commands like DELETE, TRACE and others */
 739   CINIT(STDERR, OBJECTPOINT, 37),
 740
 741   /* 38 is not used */
 742
 743   /* send linked-list of post-transfer QUOTE commands */
 744   CINIT(POSTQUOTE, OBJECTPOINT, 39),
 745
 746   /* Pass a pointer to string of the output using full variable-replacement
 747      as described elsewhere. */
 748   CINIT(WRITEINFO, OBJECTPOINT, 40),
 749
 750   CINIT(VERBOSE, LONG, 41),      /* talk a lot */
 751   CINIT(HEADER, LONG, 42),       /* throw the header out too */
 752   CINIT(NOPROGRESS, LONG, 43),   /* shut off the progress meter */
 753   CINIT(NOBODY, LONG, 44),       /* use HEAD to get http document */
 754   CINIT(FAILONERROR, LONG, 45),  /* no output on http error codes >= 300 */
 755   CINIT(UPLOAD, LONG, 46),       /* this is an upload */
 756   CINIT(POST, LONG, 47),         /* HTTP POST method */
 757   CINIT(DIRLISTONLY, LONG, 48),  /* return bare names when listing directories */
 758
 759   CINIT(APPEND, LONG, 50),       /* Append instead of overwrite on upload! */
 760
 761   /* Specify whether to read the user+password from the .netrc or the URL.
 762    * This must be one of the CURL_NETRC_* enums below. */
 763   CINIT(NETRC, LONG, 51),
 764
 765   CINIT(FOLLOWLOCATION, LONG, 52),  /* use Location: Luke! */
 766
 767   CINIT(TRANSFERTEXT, LONG, 53), /* transfer data in text/ASCII format */
 768   CINIT(PUT, LONG, 54),          /* HTTP PUT */
 769
 770   /* 55 = OBSOLETE */
 771
 772   /* Function that will be called instead of the internal progress display
 773    * function. This function should be defined as the curl_progress_callback
 774    * prototype defines. */
 775   CINIT(PROGRESSFUNCTION, FUNCTIONPOINT, 56),
 776
 777   /* Data passed to the progress callback */
 778   CINIT(PROGRESSDATA, OBJECTPOINT, 57),
 779
 780   /* We want the referrer field set automatically when following locations */
 781   CINIT(AUTOREFERER, LONG, 58),
 782
 783   /* Port of the proxy, can be set in the proxy string as well with:
 784      "[host]:[port]" */
 785   CINIT(PROXYPORT, LONG, 59),
 786
 787   /* size of the POST input data, if strlen() is not good to use */
 788   CINIT(POSTFIELDSIZE, LONG, 60),
 789
 790   /* tunnel non-http operations through a HTTP proxy */
 791   CINIT(HTTPPROXYTUNNEL, LONG, 61),
 792
 793   /* Set the interface string to use as outgoing network interface */
 794   CINIT(INTERFACE, OBJECTPOINT, 62),
 795
 796   /* Set the krb4/5 security level, this also enables krb4/5 awareness.  This
 797    * is a string, 'clear', 'safe', 'confidential' or 'private'.  If the string
 798    * is set but doesn't match one of these, 'private' will be used.  */
 799   CINIT(KRBLEVEL, OBJECTPOINT, 63),
 800
 801   /* Set if we should verify the peer in ssl handshake, set 1 to verify. */
 802   CINIT(SSL_VERIFYPEER, LONG, 64),
 803
 804   /* The CApath or CAfile used to validate the peer certificate
 805      this option is used only if SSL_VERIFYPEER is true */
 806   CINIT(CAINFO, OBJECTPOINT, 65),
 807
 808   /* 66 = OBSOLETE */
 809   /* 67 = OBSOLETE */
 810
 811   /* Maximum number of http redirects to follow */
 812   CINIT(MAXREDIRS, LONG, 68),
 813
 814   /* Pass a long set to 1 to get the date of the requested document (if
 815      possible)! Pass a zero to shut it off. */
 816   CINIT(FILETIME, LONG, 69),
 817
 818   /* This points to a linked list of telnet options */
 819   CINIT(TELNETOPTIONS, OBJECTPOINT, 70),
 820
 821   /* Max amount of cached alive connections */
 822   CINIT(MAXCONNECTS, LONG, 71),
 823
 824   /* What policy to use when closing connections when the cache is filled
 825      up */
 826   CINIT(CLOSEPOLICY, LONG, 72),
 827
 828   /* 73 = OBSOLETE */
 829
 830   /* Set to explicitly use a new connection for the upcoming transfer.
 831      Do not use this unless you're absolutely sure of this, as it makes the
 832      operation slower and is less friendly for the network. */
 833   CINIT(FRESH_CONNECT, LONG, 74),
 834
 835   /* Set to explicitly forbid the upcoming transfer's connection to be re-used
 836      when done. Do not use this unless you're absolutely sure of this, as it
 837      makes the operation slower and is less friendly for the network. */
 838   CINIT(FORBID_REUSE, LONG, 75),
 839
 840   /* Set to a file name that contains random data for libcurl to use to
 841      seed the random engine when doing SSL connects. */
 842   CINIT(RANDOM_FILE, OBJECTPOINT, 76),
 843
 844   /* Set to the Entropy Gathering Daemon socket pathname */
 845   CINIT(EGDSOCKET, OBJECTPOINT, 77),
 846
 847   /* Time-out connect operations after this amount of seconds, if connects
 848      are OK within this time, then fine... This only aborts the connect
 849      phase. [Only works on unix-style/SIGALRM operating systems] */
 850   CINIT(CONNECTTIMEOUT, LONG, 78),
 851
 852   /* Function that will be called to store headers (instead of fwrite). The
 853    * parameters will use fwrite() syntax, make sure to follow them. */
 854   CINIT(HEADERFUNCTION, FUNCTIONPOINT, 79),
 855
 856   /* Set this to force the HTTP request to get back to GET. Only really usable
 857      if POST, PUT or a custom request have been used first.
 858    */
 859   CINIT(HTTPGET, LONG, 80),
 860
 861   /* Set if we should verify the Common name from the peer certificate in ssl
 862    * handshake, set 1 to check existence, 2 to ensure that it matches the
 863    * provided hostname. */
 864   CINIT(SSL_VERIFYHOST, LONG, 81),
 865
 866   /* Specify which file name to write all known cookies in after completed
 867      operation. Set file name to "-" (dash) to make it go to stdout. */
 868   CINIT(COOKIEJAR, OBJECTPOINT, 82),
 869
 870   /* Specify which SSL ciphers to use */
 871   CINIT(SSL_CIPHER_LIST, OBJECTPOINT, 83),
 872
 873   /* Specify which HTTP version to use! This must be set to one of the
 874      CURL_HTTP_VERSION* enums set below. */
 875   CINIT(HTTP_VERSION, LONG, 84),
 876
 877   /* Specifically switch on or off the FTP engine's use of the EPSV command. By
 878      default, that one will always be attempted before the more traditional
 879      PASV command. */
 880   CINIT(FTP_USE_EPSV, LONG, 85),
 881
 882   /* type of the file keeping your SSL-certificate ("DER", "PEM", "ENG") */
 883   CINIT(SSLCERTTYPE, OBJECTPOINT, 86),
 884
 885   /* name of the file keeping your private SSL-key */
 886   CINIT(SSLKEY, OBJECTPOINT, 87),
 887
 888   /* type of the file keeping your private SSL-key ("DER", "PEM", "ENG") */
 889   CINIT(SSLKEYTYPE, OBJECTPOINT, 88),
 890
 891   /* crypto engine for the SSL-sub system */
 892   CINIT(SSLENGINE, OBJECTPOINT, 89),
 893
 894   /* set the crypto engine for the SSL-sub system as default
 895      the param has no meaning...
 896    */
 897   CINIT(SSLENGINE_DEFAULT, LONG, 90),
 898
 899   /* Non-zero value means to use the global dns cache */
 900   CINIT(DNS_USE_GLOBAL_CACHE, LONG, 91), /* To become OBSOLETE soon */
 901
 902   /* DNS cache timeout */
 903   CINIT(DNS_CACHE_TIMEOUT, LONG, 92),
 904
 905   /* send linked-list of pre-transfer QUOTE commands */
 906   CINIT(PREQUOTE, OBJECTPOINT, 93),
 907
 908   /* set the debug function */
 909   CINIT(DEBUGFUNCTION, FUNCTIONPOINT, 94),
 910
 911   /* set the data for the debug function */
 912   CINIT(DEBUGDATA, OBJECTPOINT, 95),
 913
 914   /* mark this as start of a cookie session */
 915   CINIT(COOKIESESSION, LONG, 96),
 916
 917   /* The CApath directory used to validate the peer certificate
 918      this option is used only if SSL_VERIFYPEER is true */
 919   CINIT(CAPATH, OBJECTPOINT, 97),
 920
 921   /* Instruct libcurl to use a smaller receive buffer */
 922   CINIT(BUFFERSIZE, LONG, 98),
 923
 924   /* Instruct libcurl to not use any signal/alarm handlers, even when using
 925      timeouts. This option is useful for multi-threaded applications.
 926      See libcurl-the-guide for more background information. */
 927   CINIT(NOSIGNAL, LONG, 99),
 928
 929   /* Provide a CURLShare for mutexing non-ts data */
 930   CINIT(SHARE, OBJECTPOINT, 100),
 931
 932   /* indicates type of proxy. accepted values are CURLPROXY_HTTP (default),
 933      CURLPROXY_SOCKS4, CURLPROXY_SOCKS4A and CURLPROXY_SOCKS5. */
 934   CINIT(PROXYTYPE, LONG, 101),
 935
 936   /* Set the Accept-Encoding string. Use this to tell a server you would like
 937      the response to be compressed. */
 938   CINIT(ENCODING, OBJECTPOINT, 102),
 939
 940   /* Set pointer to private data */
 941   CINIT(PRIVATE, OBJECTPOINT, 103),
 942
 943   /* Set aliases for HTTP 200 in the HTTP Response header */
 944   CINIT(HTTP200ALIASES, OBJECTPOINT, 104),
 945
 946   /* Continue to send authentication (user+password) when following locations,
 947      even when hostname changed. This can potentially send off the name
 948      and password to whatever host the server decides. */
 949   CINIT(UNRESTRICTED_AUTH, LONG, 105),
 950
 951   /* Specifically switch on or off the FTP engine's use of the EPRT command ( it
 952      also disables the LPRT attempt). By default, those ones will always be
 953      attempted before the good old traditional PORT command. */
 954   CINIT(FTP_USE_EPRT, LONG, 106),
 955
 956   /* Set this to a bitmask value to enable the particular authentications
 957      methods you like. Use this in combination with CURLOPT_USERPWD.
 958      Note that setting multiple bits may cause extra network round-trips. */
 959   CINIT(HTTPAUTH, LONG, 107),
 960
 961   /* Set the ssl context callback function, currently only for OpenSSL ssl_ctx
 962      in second argument. The function must be matching the
 963      curl_ssl_ctx_callback proto. */
 964   CINIT(SSL_CTX_FUNCTION, FUNCTIONPOINT, 108),
 965
 966   /* Set the userdata for the ssl context callback function's third
 967      argument */
 968   CINIT(SSL_CTX_DATA, OBJECTPOINT, 109),
 969
 970   /* FTP Option that causes missing dirs to be created on the remote server.
 971      In 7.19.4 we introduced the convenience enums for this option using the
 972      CURLFTP_CREATE_DIR prefix.
 973   */
 974   CINIT(FTP_CREATE_MISSING_DIRS, LONG, 110),
 975
 976   /* Set this to a bitmask value to enable the particular authentications
 977      methods you like. Use this in combination with CURLOPT_PROXYUSERPWD.
 978      Note that setting multiple bits may cause extra network round-trips. */
 979   CINIT(PROXYAUTH, LONG, 111),
 980
 981   /* FTP option that changes the timeout, in seconds, associated with
 982      getting a response.  This is different from transfer timeout time and
 983      essentially places a demand on the FTP server to acknowledge commands
 984      in a timely manner. */
 985   CINIT(FTP_RESPONSE_TIMEOUT, LONG, 112),
 986
 987   /* Set this option to one of the CURL_IPRESOLVE_* defines (see below) to
 988      tell libcurl to resolve names to those IP versions only. This only has
 989      affect on systems with support for more than one, i.e IPv4 _and_ IPv6. */
 990   CINIT(IPRESOLVE, LONG, 113),
 991
 992   /* Set this option to limit the size of a file that will be downloaded from
 993      an HTTP or FTP server.
 994
 995      Note there is also _LARGE version which adds large file support for
 996      platforms which have larger off_t sizes.  See MAXFILESIZE_LARGE below. */
 997   CINIT(MAXFILESIZE, LONG, 114),
 998
 999   /* See the comment for INFILESIZE above, but in short, specifies
1000    * the size of the file being uploaded.  -1 means unknown.
1001    */
1002   CINIT(INFILESIZE_LARGE, OFF_T, 115),
1003
1004   /* Sets the continuation offset.  There is also a LONG version of this;
1005    * look above for RESUME_FROM.
1006    */
1007   CINIT(RESUME_FROM_LARGE, OFF_T, 116),
1008
1009   /* Sets the maximum size of data that will be downloaded from
1010    * an HTTP or FTP server.  See MAXFILESIZE above for the LONG version.
1011    */
1012   CINIT(MAXFILESIZE_LARGE, OFF_T, 117),
1013
1014   /* Set this option to the file name of your .netrc file you want libcurl
1015      to parse (using the CURLOPT_NETRC option). If not set, libcurl will do
1016      a poor attempt to find the user's home directory and check for a .netrc
1017      file in there. */
1018   CINIT(NETRC_FILE, OBJECTPOINT, 118),
1019
1020   /* Enable SSL/TLS for FTP, pick one of:
1021      CURLFTPSSL_TRY     - try using SSL, proceed anyway otherwise
1022      CURLFTPSSL_CONTROL - SSL for the control connection or fail
1023      CURLFTPSSL_ALL     - SSL for all communication or fail
1024   */
1025   CINIT(USE_SSL, LONG, 119),
1026
1027   /* The _LARGE version of the standard POSTFIELDSIZE option */
1028   CINIT(POSTFIELDSIZE_LARGE, OFF_T, 120),
1029
1030   /* Enable/disable the TCP Nagle algorithm */
1031   CINIT(TCP_NODELAY, LONG, 121),
1032
1033   /* 122 OBSOLETE, used in 7.12.3. Gone in 7.13.0 */
1034   /* 123 OBSOLETE. Gone in 7.16.0 */
1035   /* 124 OBSOLETE, used in 7.12.3. Gone in 7.13.0 */
1036   /* 125 OBSOLETE, used in 7.12.3. Gone in 7.13.0 */
1037   /* 126 OBSOLETE, used in 7.12.3. Gone in 7.13.0 */
1038   /* 127 OBSOLETE. Gone in 7.16.0 */
1039   /* 128 OBSOLETE. Gone in 7.16.0 */
1040
1041   /* When FTP over SSL/TLS is selected (with CURLOPT_USE_SSL), this option
1042      can be used to change libcurl's default action which is to first try
1043      "AUTH SSL" and then "AUTH TLS" in this order, and proceed when a OK
1044      response has been received.
1045
1046      Available parameters are:
1047      CURLFTPAUTH_DEFAULT - let libcurl decide
1048      CURLFTPAUTH_SSL     - try "AUTH SSL" first, then TLS
1049      CURLFTPAUTH_TLS     - try "AUTH TLS" first, then SSL
1050   */
1051   CINIT(FTPSSLAUTH, LONG, 129),
1052
1053   CINIT(IOCTLFUNCTION, FUNCTIONPOINT, 130),
1054   CINIT(IOCTLDATA, OBJECTPOINT, 131),
1055
1056   /* 132 OBSOLETE. Gone in 7.16.0 */
1057   /* 133 OBSOLETE. Gone in 7.16.0 */
1058
1059   /* zero terminated string for pass on to the FTP server when asked for
1060      "account" info */
1061   CINIT(FTP_ACCOUNT, OBJECTPOINT, 134),
1062
1063   /* feed cookies into cookie engine */
1064   CINIT(COOKIELIST, OBJECTPOINT, 135),
1065
1066   /* ignore Content-Length */
1067   CINIT(IGNORE_CONTENT_LENGTH, LONG, 136),
1068
1069   /* Set to non-zero to skip the IP address received in a 227 PASV FTP server
1070      response. Typically used for FTP-SSL purposes but is not restricted to
1071      that. libcurl will then instead use the same IP address it used for the
1072      control connection. */
1073   CINIT(FTP_SKIP_PASV_IP, LONG, 137),
1074
1075   /* Select "file method" to use when doing FTP, see the curl_ftpmethod
1076      above. */
1077   CINIT(FTP_FILEMETHOD, LONG, 138),
1078
1079   /* Local port number to bind the socket to */
1080   CINIT(LOCALPORT, LONG, 139),
1081
1082   /* Number of ports to try, including the first one set with LOCALPORT.
1083      Thus, setting it to 1 will make no additional attempts but the first.
1084   */
1085   CINIT(LOCALPORTRANGE, LONG, 140),
1086
1087   /* no transfer, set up connection and let application use the socket by
1088      extracting it with CURLINFO_LASTSOCKET */
1089   CINIT(CONNECT_ONLY, LONG, 141),
1090
1091   /* Function that will be called to convert from the
1092      network encoding (instead of using the iconv calls in libcurl) */
1093   CINIT(CONV_FROM_NETWORK_FUNCTION, FUNCTIONPOINT, 142),
1094
1095   /* Function that will be called to convert to the
1096      network encoding (instead of using the iconv calls in libcurl) */
1097   CINIT(CONV_TO_NETWORK_FUNCTION, FUNCTIONPOINT, 143),
1098
1099   /* Function that will be called to convert from UTF8
1100      (instead of using the iconv calls in libcurl)
1101      Note that this is used only for SSL certificate processing */
1102   CINIT(CONV_FROM_UTF8_FUNCTION, FUNCTIONPOINT, 144),
1103
1104   /* if the connection proceeds too quickly then need to slow it down */
1105   /* limit-rate: maximum number of bytes per second to send or receive */
1106   CINIT(MAX_SEND_SPEED_LARGE, OFF_T, 145),
1107   CINIT(MAX_RECV_SPEED_LARGE, OFF_T, 146),
1108
1109   /* Pointer to command string to send if USER/PASS fails. */
1110   CINIT(FTP_ALTERNATIVE_TO_USER, OBJECTPOINT, 147),
1111
1112   /* callback function for setting socket options */
1113   CINIT(SOCKOPTFUNCTION, FUNCTIONPOINT, 148),
1114   CINIT(SOCKOPTDATA, OBJECTPOINT, 149),
1115
1116   /* set to 0 to disable session ID re-use for this transfer, default is
1117      enabled (== 1) */
1118   CINIT(SSL_SESSIONID_CACHE, LONG, 150),
1119
1120   /* allowed SSH authentication methods */
1121   CINIT(SSH_AUTH_TYPES, LONG, 151),
1122
1123   /* Used by scp/sftp to do public/private key authentication */
1124   CINIT(SSH_PUBLIC_KEYFILE, OBJECTPOINT, 152),
1125   CINIT(SSH_PRIVATE_KEYFILE, OBJECTPOINT, 153),
1126
1127   /* Send CCC (Clear Command Channel) after authentication */
1128   CINIT(FTP_SSL_CCC, LONG, 154),
1129
1130   /* Same as TIMEOUT and CONNECTTIMEOUT, but with ms resolution */
1131   CINIT(TIMEOUT_MS, LONG, 155),
1132   CINIT(CONNECTTIMEOUT_MS, LONG, 156),
1133
1134   /* set to zero to disable the libcurl's decoding and thus pass the raw body
1135      data to the application even when it is encoded/compressed */
1136   CINIT(HTTP_TRANSFER_DECODING, LONG, 157),
1137   CINIT(HTTP_CONTENT_DECODING, LONG, 158),
1138
1139   /* Permission used when creating new files and directories on the remote
1140      server for protocols that support it, SFTP/SCP/FILE */
1141   CINIT(NEW_FILE_PERMS, LONG, 159),
1142   CINIT(NEW_DIRECTORY_PERMS, LONG, 160),
1143
1144   /* Set the behaviour of POST when redirecting. Values must be set to one
1145      of CURL_REDIR* defines below. This used to be called CURLOPT_POST301 */
1146   CINIT(POSTREDIR, LONG, 161),
1147
1148   /* used by scp/sftp to verify the host's public key */
1149   CINIT(SSH_HOST_PUBLIC_KEY_MD5, OBJECTPOINT, 162),
1150
1151   /* Callback function for opening socket (instead of socket(2)). Optionally,
1152      callback is able change the address or refuse to connect returning
1153      CURL_SOCKET_BAD.  The callback should have type
1154      curl_opensocket_callback */
1155   CINIT(OPENSOCKETFUNCTION, FUNCTIONPOINT, 163),
1156   CINIT(OPENSOCKETDATA, OBJECTPOINT, 164),
1157
1158   /* POST volatile input fields. */
1159   CINIT(COPYPOSTFIELDS, OBJECTPOINT, 165),
1160
1161   /* set transfer mode (;type=<a|i>) when doing FTP via an HTTP proxy */
1162   CINIT(PROXY_TRANSFER_MODE, LONG, 166),
1163
1164   /* Callback function for seeking in the input stream */
1165   CINIT(SEEKFUNCTION, FUNCTIONPOINT, 167),
1166   CINIT(SEEKDATA, OBJECTPOINT, 168),
1167
1168   /* CRL file */
1169   CINIT(CRLFILE, OBJECTPOINT, 169),
1170
1171   /* Issuer certificate */
1172   CINIT(ISSUERCERT, OBJECTPOINT, 170),
1173
1174   /* (IPv6) Address scope */
1175   CINIT(ADDRESS_SCOPE, LONG, 171),
1176
1177   /* Collect certificate chain info and allow it to get retrievable with
1178      CURLINFO_CERTINFO after the transfer is complete. (Unfortunately) only
1179      working with OpenSSL-powered builds. */
1180   CINIT(CERTINFO, LONG, 172),
1181
1182   /* "name" and "pwd" to use when fetching. */
1183   CINIT(USERNAME, OBJECTPOINT, 173),
1184   CINIT(PASSWORD, OBJECTPOINT, 174),
1185
1186     /* "name" and "pwd" to use with Proxy when fetching. */
1187   CINIT(PROXYUSERNAME, OBJECTPOINT, 175),
1188   CINIT(PROXYPASSWORD, OBJECTPOINT, 176),
1189
1190   /* Comma separated list of hostnames defining no-proxy zones. These should
1191      match both hostnames directly, and hostnames within a domain. For
1192      example, local.com will match local.com and www.local.com, but NOT
1193      notlocal.com or www.notlocal.com. For compatibility with other
1194      implementations of this, .local.com will be considered to be the same as
1195      local.com. A single * is the only valid wildcard, and effectively
1196      disables the use of proxy. */
1197   CINIT(NOPROXY, OBJECTPOINT, 177),
1198
1199   /* block size for TFTP transfers */
1200   CINIT(TFTP_BLKSIZE, LONG, 178),
1201
1202   /* Socks Service */
1203   CINIT(SOCKS5_GSSAPI_SERVICE, LONG, 179),
1204
1205   /* Socks Service */
1206   CINIT(SOCKS5_GSSAPI_NEC, LONG, 180),
1207
1208   /* set the bitmask for the protocols that are allowed to be used for the
1209      transfer, which thus helps the app which takes URLs from users or other
1210      external inputs and want to restrict what protocol(s) to deal
1211      with. Defaults to CURLPROTO_ALL. */
1212   CINIT(PROTOCOLS, LONG, 181),
1213
1214   /* set the bitmask for the protocols that libcurl is allowed to follow to,
1215      as a subset of the CURLOPT_PROTOCOLS ones. That means the protocol needs
1216      to be set in both bitmasks to be allowed to get redirected to. Defaults
1217      to all protocols except FILE and SCP. */
1218   CINIT(REDIR_PROTOCOLS, LONG, 182),
1219
1220   CURLOPT_LASTENTRY /* the last unused */
1221 } CURLoption;
1222
1223 #ifndef CURL_NO_OLDIES /* define this to test if your app builds with all
1224                           the obsolete stuff removed! */
1225
1226 /* Backwards compatibility with older names */
1227 /* These are scheduled to disappear by 2011 */
1228
1229 /* This was added in version 7.19.1 */
1230 #define CURLOPT_POST301 CURLOPT_POSTREDIR
1231
1232 /* These are scheduled to disappear by 2009 */
1233
1234 /* The following were added in 7.17.0 */
1235 #define CURLOPT_SSLKEYPASSWD CURLOPT_KEYPASSWD
1236 #define CURLOPT_FTPAPPEND CURLOPT_APPEND
1237 #define CURLOPT_FTPLISTONLY CURLOPT_DIRLISTONLY
1238 #define CURLOPT_FTP_SSL CURLOPT_USE_SSL
1239
1240 /* The following were added earlier */
1241
1242 #define CURLOPT_SSLCERTPASSWD CURLOPT_KEYPASSWD
1243 #define CURLOPT_KRB4LEVEL CURLOPT_KRBLEVEL
1244
1245 #else
1246 /* This is set if CURL_NO_OLDIES is defined at compile-time */
1247 #undef CURLOPT_DNS_USE_GLOBAL_CACHE /* soon obsolete */
1248 #endif
1249
1250
1251   /* Below here follows defines for the CURLOPT_IPRESOLVE option. If a host
1252      name resolves addresses using more than one IP protocol version, this
1253      option might be handy to force libcurl to use a specific IP version. */
1254 #define CURL_IPRESOLVE_WHATEVER 0 /* default, resolves addresses to all IP
1255                                      versions that your system allows */
1256 #define CURL_IPRESOLVE_V4       1 /* resolve to ipv4 addresses */
1257 #define CURL_IPRESOLVE_V6       2 /* resolve to ipv6 addresses */
1258
1259   /* three convenient "aliases" that follow the name scheme better */
1260 #define CURLOPT_WRITEDATA CURLOPT_FILE
1261 #define CURLOPT_READDATA  CURLOPT_INFILE
1262 #define CURLOPT_HEADERDATA CURLOPT_WRITEHEADER
1263
1264   /* These enums are for use with the CURLOPT_HTTP_VERSION option. */
1265 enum {
1266   CURL_HTTP_VERSION_NONE, /* setting this means we don't care, and that we'd
1267                              like the library to choose the best possible
1268                              for us! */
1269   CURL_HTTP_VERSION_1_0,  /* please use HTTP 1.0 in the request */
1270   CURL_HTTP_VERSION_1_1,  /* please use HTTP 1.1 in the request */
1271
1272   CURL_HTTP_VERSION_LAST /* *ILLEGAL* http version */
1273 };
1274
1275   /* These enums are for use with the CURLOPT_NETRC option. */
1276 enum CURL_NETRC_OPTION {
1277   CURL_NETRC_IGNORED,     /* The .netrc will never be read.
1278                            * This is the default. */
1279   CURL_NETRC_OPTIONAL,    /* A user:password in the URL will be preferred
1280                            * to one in the .netrc. */
1281   CURL_NETRC_REQUIRED,    /* A user:password in the URL will be ignored.
1282                            * Unless one is set programmatically, the .netrc
1283                            * will be queried. */
1284   CURL_NETRC_LAST
1285 };
1286
1287 enum {
1288   CURL_SSLVERSION_DEFAULT,
1289   CURL_SSLVERSION_TLSv1,
1290   CURL_SSLVERSION_SSLv2,
1291   CURL_SSLVERSION_SSLv3,
1292
1293   CURL_SSLVERSION_LAST /* never use, keep last */
1294 };
1295
1296 /* symbols to use with CURLOPT_POSTREDIR.
1297    CURL_REDIR_POST_301 and CURL_REDIR_POST_302 can be bitwise ORed so that
1298    CURL_REDIR_POST_301 | CURL_REDIR_POST_302 == CURL_REDIR_POST_ALL */
1299
1300 #define CURL_REDIR_GET_ALL  0
1301 #define CURL_REDIR_POST_301 1
1302 #define CURL_REDIR_POST_302 2
1303 #define CURL_REDIR_POST_ALL (CURL_REDIR_POST_301|CURL_REDIR_POST_302)
1304
1305 typedef enum {
1306   CURL_TIMECOND_NONE,
1307
1308   CURL_TIMECOND_IFMODSINCE,
1309   CURL_TIMECOND_IFUNMODSINCE,
1310   CURL_TIMECOND_LASTMOD,
1311
1312   CURL_TIMECOND_LAST
1313 } curl_TimeCond;
1314
1315
1316 /* curl_strequal() and curl_strnequal() are subject for removal in a future
1317    libcurl, see lib/README.curlx for details */
1318 CURL_EXTERN int (curl_strequal)(const char *s1, const char *s2);
1319 CURL_EXTERN int (curl_strnequal)(const char *s1, const char *s2, size_t n);
1320
1321 /* name is uppercase CURLFORM_<name> */
1322 #ifdef CFINIT
1323 #undef CFINIT
1324 #endif
1325
1326 #ifdef CURL_ISOCPP
1327 #define CFINIT(name) CURLFORM_ ## name
1328 #else
1329 /* The macro "##" is ISO C, we assume pre-ISO C doesn't support it. */
1330 #define CFINIT(name) CURLFORM_/**/name
1331 #endif
1332
1333 typedef enum {
1334   CFINIT(NOTHING),        /********* the first one is unused ************/
1335
1336   /*  */
1337   CFINIT(COPYNAME),
1338   CFINIT(PTRNAME),
1339   CFINIT(NAMELENGTH),
1340   CFINIT(COPYCONTENTS),
1341   CFINIT(PTRCONTENTS),
1342   CFINIT(CONTENTSLENGTH),
1343   CFINIT(FILECONTENT),
1344   CFINIT(ARRAY),
1345   CFINIT(OBSOLETE),
1346   CFINIT(FILE),
1347
1348   CFINIT(BUFFER),
1349   CFINIT(BUFFERPTR),
1350   CFINIT(BUFFERLENGTH),
1351
1352   CFINIT(CONTENTTYPE),
1353   CFINIT(CONTENTHEADER),
1354   CFINIT(FILENAME),
1355   CFINIT(END),
1356   CFINIT(OBSOLETE2),
1357
1358   CFINIT(STREAM),
1359
1360   CURLFORM_LASTENTRY /* the last unused */
1361 } CURLformoption;
1362
1363 #undef CFINIT /* done */
1364
1365 /* structure to be used as parameter for CURLFORM_ARRAY */
1366 struct curl_forms {
1367   CURLformoption option;
1368   const char     *value;
1369 };
1370
1371 /* use this for multipart formpost building */
1372 /* Returns code for curl_formadd()
1373  *
1374  * Returns:
1375  * CURL_FORMADD_OK             on success
1376  * CURL_FORMADD_MEMORY         if the FormInfo allocation fails
1377  * CURL_FORMADD_OPTION_TWICE   if one option is given twice for one Form
1378  * CURL_FORMADD_NULL           if a null pointer was given for a char
1379  * CURL_FORMADD_MEMORY         if the allocation of a FormInfo struct failed
1380  * CURL_FORMADD_UNKNOWN_OPTION if an unknown option was used
1381  * CURL_FORMADD_INCOMPLETE     if the some FormInfo is not complete (or error)
1382  * CURL_FORMADD_MEMORY         if a curl_httppost struct cannot be allocated
1383  * CURL_FORMADD_MEMORY         if some allocation for string copying failed.
1384  * CURL_FORMADD_ILLEGAL_ARRAY  if an illegal option is used in an array
1385  *
1386  ***************************************************************************/
1387 typedef enum {
1388   CURL_FORMADD_OK, /* first, no error */
1389
1390   CURL_FORMADD_MEMORY,
1391   CURL_FORMADD_OPTION_TWICE,
1392   CURL_FORMADD_NULL,
1393   CURL_FORMADD_UNKNOWN_OPTION,
1394   CURL_FORMADD_INCOMPLETE,
1395   CURL_FORMADD_ILLEGAL_ARRAY,
1396   CURL_FORMADD_DISABLED, /* libcurl was built with this disabled */
1397
1398   CURL_FORMADD_LAST /* last */
1399 } CURLFORMcode;
1400
1401 /*
1402  * NAME curl_formadd()
1403  *
1404  * DESCRIPTION
1405  *
1406  * Pretty advanced function for building multi-part formposts. Each invoke
1407  * adds one part that together construct a full post. Then use
1408  * CURLOPT_HTTPPOST to send it off to libcurl.
1409  */
1410 CURL_EXTERN CURLFORMcode curl_formadd(struct curl_httppost **httppost,
1411                                       struct curl_httppost **last_post,
1412                                       ...);
1413
1414 /*
1415  * callback function for curl_formget()
1416  * The void *arg pointer will be the one passed as second argument to
1417  *   curl_formget().
1418  * The character buffer passed to it must not be freed.
1419  * Should return the buffer length passed to it as the argument "len" on
1420  *   success.
1421  */
1422 typedef size_t (*curl_formget_callback)(void *arg, const char *buf, size_t len);
1423
1424 /*
1425  * NAME curl_formget()
1426  *
1427  * DESCRIPTION
1428  *
1429  * Serialize a curl_httppost struct built with curl_formadd().
1430  * Accepts a void pointer as second argument which will be passed to
1431  * the curl_formget_callback function.
1432  * Returns 0 on success.
1433  */
1434 CURL_EXTERN int curl_formget(struct curl_httppost *form, void *arg,
1435                              curl_formget_callback append);
1436 /*
1437  * NAME curl_formfree()
1438  *
1439  * DESCRIPTION
1440  *
1441  * Free a multipart formpost previously built with curl_formadd().
1442  */
1443 CURL_EXTERN void curl_formfree(struct curl_httppost *form);
1444
1445 /*
1446  * NAME curl_getenv()
1447  *
1448  * DESCRIPTION
1449  *
1450  * Returns a malloc()'ed string that MUST be curl_free()ed after usage is
1451  * complete. DEPRECATED - see lib/README.curlx
1452  */
1453 CURL_EXTERN char *curl_getenv(const char *variable);
1454
1455 /*
1456  * NAME curl_version()
1457  *
1458  * DESCRIPTION
1459  *
1460  * Returns a static ascii string of the libcurl version.
1461  */
1462 CURL_EXTERN char *curl_version(void);
1463
1464 /*
1465  * NAME curl_easy_escape()
1466  *
1467  * DESCRIPTION
1468  *
1469  * Escapes URL strings (converts all letters consider illegal in URLs to their
1470  * %XX versions). This function returns a new allocated string or NULL if an
1471  * error occurred.
1472  */
1473 CURL_EXTERN char *curl_easy_escape(CURL *handle,
1474                                    const char *string,
1475                                    int length);
1476
1477 /* the previous version: */
1478 CURL_EXTERN char *curl_escape(const char *string,
1479                               int length);
1480
1481
1482 /*
1483  * NAME curl_easy_unescape()
1484  *
1485  * DESCRIPTION
1486  *
1487  * Unescapes URL encoding in strings (converts all %XX codes to their 8bit
1488  * versions). This function returns a new allocated string or NULL if an error
1489  * occurred.
1490  * Conversion Note: On non-ASCII platforms the ASCII %XX codes are
1491  * converted into the host encoding.
1492  */
1493 CURL_EXTERN char *curl_easy_unescape(CURL *handle,
1494                                      const char *string,
1495                                      int length,
1496                                      int *outlength);
1497
1498 /* the previous version */
1499 CURL_EXTERN char *curl_unescape(const char *string,
1500                                 int length);
1501
1502 /*
1503  * NAME curl_free()
1504  *
1505  * DESCRIPTION
1506  *
1507  * Provided for de-allocation in the same translation unit that did the
1508  * allocation. Added in libcurl 7.10
1509  */
1510 CURL_EXTERN void curl_free(void *p);
1511
1512 /*
1513  * NAME curl_global_init()
1514  *
1515  * DESCRIPTION
1516  *
1517  * curl_global_init() should be invoked exactly once for each application that
1518  * uses libcurl and before any call of other libcurl function.
1519  *
1520  * This function is not thread-safe!
1521  */
1522 CURL_EXTERN CURLcode curl_global_init(long flags);
1523
1524 /*
1525  * NAME curl_global_init_mem()
1526  *
1527  * DESCRIPTION
1528  *
1529  * curl_global_init() or curl_global_init_mem() should be invoked exactly once
1530  * for each application that uses libcurl.  This function can be used to
1531  * initialize libcurl and set user defined memory management callback
1532  * functions.  Users can implement memory management routines to check for
1533  * memory leaks, check for mis-use of the curl library etc.  User registered
1534  * callback routines with be invoked by this library instead of the system
1535  * memory management routines like malloc, free etc.
1536  */
1537 CURL_EXTERN CURLcode curl_global_init_mem(long flags,
1538                                           curl_malloc_callback m,
1539                                           curl_free_callback f,
1540                                           curl_realloc_callback r,
1541                                           curl_strdup_callback s,
1542                                           curl_calloc_callback c);
1543
1544 /*
1545  * NAME curl_global_cleanup()
1546  *
1547  * DESCRIPTION
1548  *
1549  * curl_global_cleanup() should be invoked exactly once for each application
1550  * that uses libcurl
1551  */
1552 CURL_EXTERN void curl_global_cleanup(void);
1553
1554 /* linked-list structure for the CURLOPT_QUOTE option (and other) */
1555 struct curl_slist {
1556   char *data;
1557   struct curl_slist *next;
1558 };
1559
1560 /*
1561  * NAME curl_slist_append()
1562  *
1563  * DESCRIPTION
1564  *
1565  * Appends a string to a linked list. If no list exists, it will be created
1566  * first. Returns the new list, after appending.
1567  */
1568 CURL_EXTERN struct curl_slist *curl_slist_append(struct curl_slist *,
1569                                                  const char *);
1570
1571 /*
1572  * NAME curl_slist_free_all()
1573  *
1574  * DESCRIPTION
1575  *
1576  * free a previously built curl_slist.
1577  */
1578 CURL_EXTERN void curl_slist_free_all(struct curl_slist *);
1579
1580 /*
1581  * NAME curl_getdate()
1582  *
1583  * DESCRIPTION
1584  *
1585  * Returns the time, in seconds since 1 Jan 1970 of the time string given in
1586  * the first argument. The time argument in the second parameter is unused
1587  * and should be set to NULL.
1588  */
1589 CURL_EXTERN time_t curl_getdate(const char *p, const time_t *unused);
1590
1591 /* info about the certificate chain, only for OpenSSL builds. Asked
1592    for with CURLOPT_CERTINFO / CURLINFO_CERTINFO */
1593 struct curl_certinfo {
1594   int num_of_certs;             /* number of certificates with information */
1595   struct curl_slist **certinfo; /* for each index in this array, there's a
1596                                    linked list with textual information in the
1597                                    format "name: value" */
1598 };
1599
1600 #define CURLINFO_STRING   0x100000
1601 #define CURLINFO_LONG     0x200000
1602 #define CURLINFO_DOUBLE   0x300000
1603 #define CURLINFO_SLIST    0x400000
1604 #define CURLINFO_MASK     0x0fffff
1605 #define CURLINFO_TYPEMASK 0xf00000
1606
1607 typedef enum {
1608   CURLINFO_NONE, /* first, never use this */
1609   CURLINFO_EFFECTIVE_URL    = CURLINFO_STRING + 1,
1610   CURLINFO_RESPONSE_CODE    = CURLINFO_LONG   + 2,
1611   CURLINFO_TOTAL_TIME       = CURLINFO_DOUBLE + 3,
1612   CURLINFO_NAMELOOKUP_TIME  = CURLINFO_DOUBLE + 4,
1613   CURLINFO_CONNECT_TIME     = CURLINFO_DOUBLE + 5,
1614   CURLINFO_PRETRANSFER_TIME = CURLINFO_DOUBLE + 6,
1615   CURLINFO_SIZE_UPLOAD      = CURLINFO_DOUBLE + 7,
1616   CURLINFO_SIZE_DOWNLOAD    = CURLINFO_DOUBLE + 8,
1617   CURLINFO_SPEED_DOWNLOAD   = CURLINFO_DOUBLE + 9,
1618   CURLINFO_SPEED_UPLOAD     = CURLINFO_DOUBLE + 10,
1619   CURLINFO_HEADER_SIZE      = CURLINFO_LONG   + 11,
1620   CURLINFO_REQUEST_SIZE     = CURLINFO_LONG   + 12,
1621   CURLINFO_SSL_VERIFYRESULT = CURLINFO_LONG   + 13,
1622   CURLINFO_FILETIME         = CURLINFO_LONG   + 14,
1623   CURLINFO_CONTENT_LENGTH_DOWNLOAD   = CURLINFO_DOUBLE + 15,
1624   CURLINFO_CONTENT_LENGTH_UPLOAD     = CURLINFO_DOUBLE + 16,
1625   CURLINFO_STARTTRANSFER_TIME = CURLINFO_DOUBLE + 17,
1626   CURLINFO_CONTENT_TYPE     = CURLINFO_STRING + 18,
1627   CURLINFO_REDIRECT_TIME    = CURLINFO_DOUBLE + 19,
1628   CURLINFO_REDIRECT_COUNT   = CURLINFO_LONG   + 20,
1629   CURLINFO_PRIVATE          = CURLINFO_STRING + 21,
1630   CURLINFO_HTTP_CONNECTCODE = CURLINFO_LONG   + 22,
1631   CURLINFO_HTTPAUTH_AVAIL   = CURLINFO_LONG   + 23,
1632   CURLINFO_PROXYAUTH_AVAIL  = CURLINFO_LONG   + 24,
1633   CURLINFO_OS_ERRNO         = CURLINFO_LONG   + 25,
1634   CURLINFO_NUM_CONNECTS     = CURLINFO_LONG   + 26,
1635   CURLINFO_SSL_ENGINES      = CURLINFO_SLIST  + 27,
1636   CURLINFO_COOKIELIST       = CURLINFO_SLIST  + 28,
1637   CURLINFO_LASTSOCKET       = CURLINFO_LONG   + 29,
1638   CURLINFO_FTP_ENTRY_PATH   = CURLINFO_STRING + 30,
1639   CURLINFO_REDIRECT_URL     = CURLINFO_STRING + 31,
1640   CURLINFO_PRIMARY_IP       = CURLINFO_STRING + 32,
1641   CURLINFO_APPCONNECT_TIME  = CURLINFO_DOUBLE + 33,
1642   CURLINFO_CERTINFO         = CURLINFO_SLIST  + 34,
1643   CURLINFO_CONDITION_UNMET  = CURLINFO_LONG   + 35,
1644   /* Fill in new entries below here! */
1645
1646   CURLINFO_LASTONE          = 35
1647 } CURLINFO;
1648
1649 /* CURLINFO_RESPONSE_CODE is the new name for the option previously known as
1650    CURLINFO_HTTP_CODE */
1651 #define CURLINFO_HTTP_CODE CURLINFO_RESPONSE_CODE
1652
1653 typedef enum {
1654   CURLCLOSEPOLICY_NONE, /* first, never use this */
1655
1656   CURLCLOSEPOLICY_OLDEST,
1657   CURLCLOSEPOLICY_LEAST_RECENTLY_USED,
1658   CURLCLOSEPOLICY_LEAST_TRAFFIC,
1659   CURLCLOSEPOLICY_SLOWEST,
1660   CURLCLOSEPOLICY_CALLBACK,
1661
1662   CURLCLOSEPOLICY_LAST /* last, never use this */
1663 } curl_closepolicy;
1664
1665 #define CURL_GLOBAL_SSL (1<<0)
1666 #define CURL_GLOBAL_WIN32 (1<<1)
1667 #define CURL_GLOBAL_ALL (CURL_GLOBAL_SSL|CURL_GLOBAL_WIN32)
1668 #define CURL_GLOBAL_NOTHING 0
1669 #define CURL_GLOBAL_DEFAULT CURL_GLOBAL_ALL
1670
1671
1672 /*****************************************************************************
1673  * Setup defines, protos etc for the sharing stuff.
1674  */
1675
1676 /* Different data locks for a single share */
1677 typedef enum {
1678   CURL_LOCK_DATA_NONE = 0,
1679   /*  CURL_LOCK_DATA_SHARE is used internally to say that
1680    *  the locking is just made to change the internal state of the share
1681    *  itself.
1682    */
1683   CURL_LOCK_DATA_SHARE,
1684   CURL_LOCK_DATA_COOKIE,
1685   CURL_LOCK_DATA_DNS,
1686   CURL_LOCK_DATA_SSL_SESSION,
1687   CURL_LOCK_DATA_CONNECT,
1688   CURL_LOCK_DATA_LAST
1689 } curl_lock_data;
1690
1691 /* Different lock access types */
1692 typedef enum {
1693   CURL_LOCK_ACCESS_NONE = 0,   /* unspecified action */
1694   CURL_LOCK_ACCESS_SHARED = 1, /* for read perhaps */
1695   CURL_LOCK_ACCESS_SINGLE = 2, /* for write perhaps */
1696   CURL_LOCK_ACCESS_LAST        /* never use */
1697 } curl_lock_access;
1698
1699 typedef void (*curl_lock_function)(CURL *handle,
1700                                    curl_lock_data data,
1701                                    curl_lock_access locktype,
1702                                    void *userptr);
1703 typedef void (*curl_unlock_function)(CURL *handle,
1704                                      curl_lock_data data,
1705                                      void *userptr);
1706
1707 typedef void CURLSH;
1708
1709 typedef enum {
1710   CURLSHE_OK,  /* all is fine */
1711   CURLSHE_BAD_OPTION, /* 1 */
1712   CURLSHE_IN_USE,     /* 2 */
1713   CURLSHE_INVALID,    /* 3 */
1714   CURLSHE_NOMEM,      /* out of memory */
1715   CURLSHE_LAST /* never use */
1716 } CURLSHcode;
1717
1718 typedef enum {
1719   CURLSHOPT_NONE,  /* don't use */
1720   CURLSHOPT_SHARE,   /* specify a data type to share */
1721   CURLSHOPT_UNSHARE, /* specify which data type to stop sharing */
1722   CURLSHOPT_LOCKFUNC,   /* pass in a 'curl_lock_function' pointer */
1723   CURLSHOPT_UNLOCKFUNC, /* pass in a 'curl_unlock_function' pointer */
1724   CURLSHOPT_USERDATA,   /* pass in a user data pointer used in the lock/unlock
1725                            callback functions */
1726   CURLSHOPT_LAST  /* never use */
1727 } CURLSHoption;
1728
1729 CURL_EXTERN CURLSH *curl_share_init(void);
1730 CURL_EXTERN CURLSHcode curl_share_setopt(CURLSH *, CURLSHoption option, ...);
1731 CURL_EXTERN CURLSHcode curl_share_cleanup(CURLSH *);
1732
1733 /****************************************************************************
1734  * Structures for querying information about the curl library at runtime.
1735  */
1736
1737 typedef enum {
1738   CURLVERSION_FIRST,
1739   CURLVERSION_SECOND,
1740   CURLVERSION_THIRD,
1741   CURLVERSION_FOURTH,
1742   CURLVERSION_LAST /* never actually use this */
1743 } CURLversion;
1744
1745 /* The 'CURLVERSION_NOW' is the symbolic name meant to be used by
1746    basically all programs ever that want to get version information. It is
1747    meant to be a built-in version number for what kind of struct the caller
1748    expects. If the struct ever changes, we redefine the NOW to another enum
1749    from above. */
1750 #define CURLVERSION_NOW CURLVERSION_FOURTH
1751
1752 typedef struct {
1753   CURLversion age;          /* age of the returned struct */
1754   const char *version;      /* LIBCURL_VERSION */
1755   unsigned int version_num; /* LIBCURL_VERSION_NUM */
1756   const char *host;         /* OS/host/cpu/machine when configured */
1757   int features;             /* bitmask, see defines below */
1758   const char *ssl_version;  /* human readable string */
1759   long ssl_version_num;     /* not used anymore, always 0 */
1760   const char *libz_version; /* human readable string */
1761   /* protocols is terminated by an entry with a NULL protoname */
1762   const char * const *protocols;
1763
1764   /* The fields below this were added in CURLVERSION_SECOND */
1765   const char *ares;
1766   int ares_num;
1767
1768   /* This field was added in CURLVERSION_THIRD */
1769   const char *libidn;
1770
1771   /* These field were added in CURLVERSION_FOURTH */
1772
1773   /* Same as '_libiconv_version' if built with HAVE_ICONV */
1774   int iconv_ver_num;
1775
1776   const char *libssh_version; /* human readable string */
1777
1778 } curl_version_info_data;
1779
1780 #define CURL_VERSION_IPV6      (1<<0)  /* IPv6-enabled */
1781 #define CURL_VERSION_KERBEROS4 (1<<1)  /* kerberos auth is supported */
1782 #define CURL_VERSION_SSL       (1<<2)  /* SSL options are present */
1783 #define CURL_VERSION_LIBZ      (1<<3)  /* libz features are present */
1784 #define CURL_VERSION_NTLM      (1<<4)  /* NTLM auth is supported */
1785 #define CURL_VERSION_GSSNEGOTIATE (1<<5) /* Negotiate auth support */
1786 #define CURL_VERSION_DEBUG     (1<<6)  /* built with debug capabilities */
1787 #define CURL_VERSION_ASYNCHDNS (1<<7)  /* asynchronous dns resolves */
1788 #define CURL_VERSION_SPNEGO    (1<<8)  /* SPNEGO auth */
1789 #define CURL_VERSION_LARGEFILE (1<<9)  /* supports files bigger than 2GB */
1790 #define CURL_VERSION_IDN       (1<<10) /* International Domain Names support */
1791 #define CURL_VERSION_SSPI      (1<<11) /* SSPI is supported */
1792 #define CURL_VERSION_CONV      (1<<12) /* character conversions are
1793                                           supported */
1794
1795 /*
1796  * NAME curl_version_info()
1797  *
1798  * DESCRIPTION
1799  *
1800  * This function returns a pointer to a static copy of the version info
1801  * struct. See above.
1802  */
1803 CURL_EXTERN curl_version_info_data *curl_version_info(CURLversion);
1804
1805 /*
1806  * NAME curl_easy_strerror()
1807  *
1808  * DESCRIPTION
1809  *
1810  * The curl_easy_strerror function may be used to turn a CURLcode value
1811  * into the equivalent human readable error string.  This is useful
1812  * for printing meaningful error messages.
1813  */
1814 CURL_EXTERN const char *curl_easy_strerror(CURLcode);
1815
1816 /*
1817  * NAME curl_share_strerror()
1818  *
1819  * DESCRIPTION
1820  *
1821  * The curl_share_strerror function may be used to turn a CURLSHcode value
1822  * into the equivalent human readable error string.  This is useful
1823  * for printing meaningful error messages.
1824  */
1825 CURL_EXTERN const char *curl_share_strerror(CURLSHcode);
1826
1827 /*
1828  * NAME curl_easy_pause()
1829  *
1830  * DESCRIPTION
1831  *
1832  * The curl_easy_pause function pauses or unpauses transfers. Select the new
1833  * state by setting the bitmask, use the convenience defines below.
1834  *
1835  */
1836 CURL_EXTERN CURLcode curl_easy_pause(CURL *handle, int bitmask);
1837
1838 #define CURLPAUSE_RECV      (1<<0)
1839 #define CURLPAUSE_RECV_CONT (0)
1840
1841 #define CURLPAUSE_SEND      (1<<2)
1842 #define CURLPAUSE_SEND_CONT (0)
1843
1844 #define CURLPAUSE_ALL       (CURLPAUSE_RECV|CURLPAUSE_SEND)
1845 #define CURLPAUSE_CONT      (CURLPAUSE_RECV_CONT|CURLPAUSE_SEND_CONT)
1846
1847 #ifdef  __cplusplus
1848 }
1849 #endif
1850
1851 /* unfortunately, the easy.h and multi.h include files need options and info
1852   stuff before they can be included! */
1853 #include "easy.h" /* nothing in curl is fun without the easy stuff */
1854 #include "multi.h"
1855
1856 /* the typechecker doesn't work in C++ (yet) */
1857 #if defined(__GNUC__) && defined(__GNUC_MINOR__) && \
1858     ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) && \
1859     !defined(__cplusplus) && !defined(CURL_DISABLE_TYPECHECK)
1860 #include "typecheck-gcc.h"
1861 #else
1862 #if defined(__STDC__) && (__STDC__ >= 1)
1863 /* This preprocessor magic that replaces a call with the exact same call is
1864    only done to make sure application authors pass exactly three arguments
1865    to these functions. */
1866 #define curl_easy_setopt(handle,opt,param) curl_easy_setopt(handle,opt,param)
1867 #define curl_easy_getinfo(handle,info,arg) curl_easy_getinfo(handle,info,arg)
1868 #define curl_share_setopt(share,opt,param) curl_share_setopt(share,opt,param)
1869 #define curl_multi_setopt(handle,opt,param) curl_multi_setopt(handle,opt,param)
1870 #endif /* __STDC__ >= 1 */
1871 #endif /* gcc >= 4.3 && !__cplusplus */
1872
1873 #endif /* __CURL_CURL_H */