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