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