include/curl/curl.h

   1 #ifndef __CURL_CURL_H
   2 #define __CURL_CURL_H
   3 /*****************************************************************************
   4  *                                  _   _ ____  _
   5  *  Project                     ___| | | |  _ \| |
   6  *                             / __| | | | |_) | |
   7  *                            | (__| |_| |  _ <| |___
   8  *                             \___|\___/|_| \_\_____|
   9  *
  10  *  The contents of this file are subject to the Mozilla Public License
  11  *  Version 1.0 (the "License"); you may not use this file except in
  12  *  compliance with the License. You may obtain a copy of the License at
  13  *  http://www.mozilla.org/MPL/
  14  *
  15  *  Software distributed under the License is distributed on an "AS IS"
  16  *  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the
  17  *  License for the specific language governing rights and limitations
  18  *  under the License.
  19  *
  20  *  The Original Code is Curl.
  21  *
  22  *  The Initial Developer of the Original Code is Daniel Stenberg.
  23  *
  24  *  Portions created by the Initial Developer are Copyright (C) 1998.
  25  *  All Rights Reserved.
  26  *
  27  * ------------------------------------------------------------
  28  * Main author:
  29  * - Daniel Stenberg <Daniel.Stenberg@haxx.nu>
  30  *
  31  *      http://curl.haxx.nu
  32  *
  33  * $Source$
  34  * $Revision$
  35  * $Date$
  36  * $Author$
  37  * $State$
  38  * $Locker$
  39  *
  40  * ------------------------------------------------------------
  41  ****************************************************************************/
  42
  43 /* The include stuff here is mainly for time_t! */
  44 #ifdef vms
  45 # include <types.h>
  46 # include <time.h>
  47 #else
  48 # include <sys/types.h>
  49 # if TIME_WITH_SYS_TIME
  50 #  include <sys/time.h>
  51 #  include <time.h>
  52 # else
  53 #  if HAVE_SYS_TIME_H
  54 #   include <sys/time.h>
  55 #  else
  56 #   include <time.h>
  57 #  endif
  58 # endif
  59 #endif /* defined (vms) */
  60
  61 #ifndef TRUE
  62 #define TRUE 1
  63 #endif
  64 #ifndef FALSE
  65 #define FALSE 0
  66 #endif
  67
  68 #include <curl/types.h>
  69
  70
  71 struct HttpHeader {
  72   struct HttpHeader *next; /* next entry in the list */
  73   char *header; /* pointer to allocated line without newline */
  74 };
  75
  76 struct HttpPost {
  77   struct HttpPost *next; /* next entry in the list */
  78   char *name;     /* pointer to allocated name */
  79   char *contents; /* pointer to allocated data contents */
  80   char *contenttype; /* Content-Type */
  81   struct HttpPost *more; /* if one field name has more than one file, this
  82                             link should link to following files */
  83   long flags;     /* as defined below */
  84 #define HTTPPOST_FILENAME (1<<0) /* specified content is a file name */
  85 };
  86
  87 /* All possible error codes from this version of urlget(). Future versions
  88    may return other values, stay prepared. */
  89
  90 typedef enum {
  91   CURLE_OK = 0,
  92   CURLE_UNSUPPORTED_PROTOCOL,
  93   CURLE_FAILED_INIT,
  94   CURLE_URL_MALFORMAT,
  95   CURLE_URL_MALFORMAT_USER,
  96   CURLE_COULDNT_RESOLVE_PROXY,
  97   CURLE_COULDNT_RESOLVE_HOST,
  98   CURLE_COULDNT_CONNECT,
  99   CURLE_FTP_WEIRD_SERVER_REPLY,
 100   CURLE_FTP_ACCESS_DENIED,
 101   CURLE_FTP_USER_PASSWORD_INCORRECT,
 102   CURLE_FTP_WEIRD_PASS_REPLY,
 103   CURLE_FTP_WEIRD_USER_REPLY,
 104   CURLE_FTP_WEIRD_PASV_REPLY,
 105   CURLE_FTP_WEIRD_227_FORMAT,
 106   CURLE_FTP_CANT_GET_HOST,
 107   CURLE_FTP_CANT_RECONNECT,
 108   CURLE_FTP_COULDNT_SET_BINARY,
 109   CURLE_PARTIAL_FILE,
 110   CURLE_FTP_COULDNT_RETR_FILE,
 111   CURLE_FTP_WRITE_ERROR,
 112   CURLE_FTP_QUOTE_ERROR,
 113   CURLE_HTTP_NOT_FOUND,
 114   CURLE_WRITE_ERROR,
 115
 116   CURLE_MALFORMAT_USER, /* the user name is illegally specified */
 117   CURLE_FTP_COULDNT_STOR_FILE, /* failed FTP upload */
 118   CURLE_READ_ERROR, /* could open/read from file */
 119
 120   CURLE_OUT_OF_MEMORY,
 121   CURLE_OPERATION_TIMEOUTED, /* the timeout time was reached */
 122   CURLE_FTP_COULDNT_SET_ASCII, /* TYPE A failed */
 123
 124   CURLE_FTP_PORT_FAILED, /* FTP PORT operation failed */
 125
 126   CURLE_FTP_COULDNT_USE_REST, /* the REST command failed */
 127   CURLE_FTP_COULDNT_GET_SIZE, /* the SIZE command failed */
 128
 129   CURLE_HTTP_RANGE_ERROR, /* The RANGE "command" didn't seem to work */
 130
 131   CURLE_HTTP_POST_ERROR,
 132
 133   CURLE_SSL_CONNECT_ERROR, /* something was wrong when connecting with SSL */
 134
 135   CURLE_FTP_BAD_DOWNLOAD_RESUME, /* couldn't resume download */
 136
 137   CURLE_FILE_COULDNT_READ_FILE,
 138
 139   CURLE_LDAP_CANNOT_BIND,
 140   CURLE_LDAP_SEARCH_FAILED,
 141   CURLE_LIBRARY_NOT_FOUND,
 142   CURLE_FUNCTION_NOT_FOUND,
 143
 144   CURLE_ABORTED_BY_CALLBACK,
 145
 146   CURLE_BAD_FUNCTION_ARGUMENT,
 147   CURLE_BAD_CALLING_ORDER,
 148
 149   CURL_LAST
 150 } CURLcode;
 151
 152 /* This is just to make older programs not break: */
 153 #define CURLE_FTP_PARTIAL_FILE CURLE_PARTIAL_FILE
 154
 155 #define URLGET_ERROR_SIZE 256
 156
 157 /* maximum URL length we deal with */
 158 #define URL_MAX_LENGTH 4096
 159 #define URL_MAX_LENGTH_TXT "4095"
 160
 161 /* name is uppercase CURLOPT_<name>,
 162    type is one of the defined CURLOPTTYPE_<type>
 163    number is unique identifier */
 164 #define T(name,type,number) CURLOPT_ ## name = CURLOPTTYPE_ ## type + number
 165
 166 /* long may be 32 or 64 bits, but we should never depend on anything else
 167    but 32 */
 168 #define CURLOPTTYPE_LONG          0
 169 #define CURLOPTTYPE_OBJECTPOINT   10000
 170 #define CURLOPTTYPE_FUNCTIONPOINT 20000
 171
 172 typedef enum {
 173   T(NOTHING, LONG, 0), /********* the first one is unused ************/
 174
 175   /* This is the FILE * the regular output should be written to. */
 176   T(FILE, OBJECTPOINT, 1),
 177
 178   /* The full URL to get/put */
 179   T(URL,  OBJECTPOINT, 2),
 180
 181   /* Port number to connect to, if other than default. Specify the CONF_PORT
 182      flag in the CURLOPT_FLAGS to activate this */
 183   T(PORT, LONG, 3),
 184
 185   /* Name of proxy to use. Specify the CONF_PROXY flag in the CURLOPT_FLAGS to
 186      activate this */
 187   T(PROXY, OBJECTPOINT, 4),
 188
 189   /* Name and password to use when fetching. Specify the CONF_USERPWD flag in
 190      the CURLOPT_FLAGS to activate this */
 191   T(USERPWD, OBJECTPOINT, 5),
 192
 193   /* Name and password to use with Proxy. Specify the CONF_PROXYUSERPWD
 194      flag in the CURLOPT_FLAGS to activate this */
 195   T(PROXYUSERPWD, OBJECTPOINT, 6),
 196
 197   /* Range to get, specified as an ASCII string. Specify the CONF_RANGE flag
 198      in the CURLOPT_FLAGS to activate this */
 199   T(RANGE, OBJECTPOINT, 7),
 200
 201 #if 0
 202   /* Configuration flags */
 203   T(FLAGS, LONG, 8),
 204 #endif
 205   /* Specified file stream to upload from (use as input): */
 206   T(INFILE, OBJECTPOINT, 9),
 207
 208   /* Buffer to receive error messages in, must be at least URLGET_ERROR_SIZE
 209      bytes big. If this is not used, error messages go to stderr instead: */
 210   T(ERRORBUFFER, OBJECTPOINT, 10),
 211
 212   /* Function that will be called to store the output (instead of fwrite). The
 213      parameters will use fwrite() syntax, make sure to follow them. */
 214   T(WRITEFUNCTION, FUNCTIONPOINT, 11),
 215
 216   /* Function that will be called to read the input (instead of fread). The
 217      parameters will use fread() syntax, make sure to follow them. */
 218   T(READFUNCTION, FUNCTIONPOINT, 12),
 219
 220   /* Time-out the read operation after this amount of seconds */
 221   T(TIMEOUT, LONG, 13),
 222
 223   /* If the CURLOPT_INFILE is used, this can be used to inform urlget about how
 224      large the file being sent really is. That allows better error checking
 225      and better verifies that the upload was succcessful. -1 means unknown
 226      size. */
 227   T(INFILESIZE, LONG, 14),
 228
 229   /* POST input fields. */
 230   T(POSTFIELDS, OBJECTPOINT, 15),
 231
 232   /* Set the referer page (needed by some CGIs) */
 233   T(REFERER, OBJECTPOINT, 16),
 234
 235   /* Set the FTP PORT string (interface name, named or numerical IP address)
 236      Use i.e '-' to use default address. */
 237   T(FTPPORT, OBJECTPOINT, 17),
 238
 239   /* Set the User-Agent string (examined by some CGIs) */
 240   T(USERAGENT, OBJECTPOINT, 18),
 241
 242   /* If the download receives less than "low speed limit" bytes/second
 243    * during "low speed time" seconds, the operations is aborted.
 244    * You could i.e if you have a pretty high speed connection, abort if
 245    * it is less than 2000 bytes/sec during 20 seconds.
 246    */
 247
 248   /* Set the "low speed limit" */
 249   T(LOW_SPEED_LIMIT, LONG , 19),
 250
 251   /* Set the "low speed time" */
 252   T(LOW_SPEED_TIME, LONG, 20),
 253
 254   /* Set the continuation offset */
 255   T(RESUME_FROM, LONG, 21),
 256
 257   /* Set cookie in request: */
 258   T(COOKIE, OBJECTPOINT, 22),
 259
 260   /* This points to a linked list of headers, struct HttpHeader kind */
 261   T(HTTPHEADER, OBJECTPOINT, 23),
 262
 263   /* This points to a linked list of post entries, struct HttpPost */
 264   T(HTTPPOST, OBJECTPOINT, 24),
 265
 266   /* name of the file keeping your private SSL-certificate */
 267   T(SSLCERT, OBJECTPOINT, 25),
 268
 269   /* password for the SSL-certificate */
 270   T(SSLCERTPASSWD, OBJECTPOINT, 26),
 271
 272   /* send TYPE parameter? */
 273   T(CRLF, LONG, 27),
 274
 275   /* send linked-list of QUOTE commands */
 276   T(QUOTE, OBJECTPOINT, 28),
 277
 278   /* send FILE * to store headers to */
 279   T(WRITEHEADER, OBJECTPOINT, 29),
 280
 281 #ifdef MULTIDOC
 282   /* send linked list of MoreDoc structs */
 283   T(MOREDOCS, OBJECTPOINT, 30),
 284 #endif
 285
 286   /* point to a file to read the initial cookies from, also enables
 287      "cookie awareness" */
 288   T(COOKIEFILE, OBJECTPOINT, 31),
 289
 290   /* What version to specifly try to use.
 291      3 = SSLv3, 2 = SSLv2, all else makes it try v3 first then v2 */
 292   T(SSLVERSION, LONG, 32),
 293
 294   /* What kind of HTTP time condition to use, see defines */
 295   T(TIMECONDITION, LONG, 33),
 296
 297   /* Time to use with the above condition. Specified in number of seconds
 298      since 1 Jan 1970 */
 299   T(TIMEVALUE, LONG, 34),
 300
 301   /* HTTP request, for odd commands like DELETE, TRACE and others */
 302   /* OBSOLETE DEFINE, left for tradition only */
 303   T(HTTPREQUEST, OBJECTPOINT, 35),
 304
 305   /* Custom request, for customizing the get command like
 306      HTTP: DELETE, TRACE and others
 307      FTP: to use a different list command
 308      */
 309   T(CUSTOMREQUEST, OBJECTPOINT, 36),
 310
 311   /* HTTP request, for odd commands like DELETE, TRACE and others */
 312   T(STDERR, OBJECTPOINT, 37),
 313
 314   /* Progress mode sets alternative progress mode displays, the only
 315      one defined today is 1 which makes the #-style progress bar. */
 316   T(PROGRESSMODE, LONG, 38),
 317
 318   /* send linked-list of post-transfer QUOTE commands */
 319   T(POSTQUOTE, OBJECTPOINT, 39),
 320
 321   /* Pass a pointer to string of the output using full variable-replacement
 322      as described elsewhere. */
 323   T(WRITEINFO, OBJECTPOINT, 40),
 324
 325   /* Previous FLAG bits */
 326   T(VERBOSE, LONG, 41),      /* talk a lot */
 327   T(HEADER, LONG, 42),       /* throw the header out too */
 328   T(NOPROGRESS, LONG, 43),   /* shut off the progress meter */
 329   T(NOBODY, LONG, 44),       /* use HEAD to get http document */
 330   T(FAILONERROR, LONG, 45),  /* no output on http error codes >= 300 */
 331   T(UPLOAD, LONG, 46),       /* this is an upload */
 332   T(POST, LONG, 47),         /* HTTP POST method */
 333   T(FTPLISTONLY, LONG, 48),  /* Use NLST when listing ftp dir */
 334
 335   T(FTPAPPEND, LONG, 50),    /* Append instead of overwrite on upload! */
 336   T(NETRC, LONG, 51),        /* read user+password from .netrc */
 337   T(FOLLOWLOCATION, LONG, 52),  /* use Location: Luke! */
 338   T(FTPASCII, LONG, 53),     /* use TYPE A for transfer */
 339   T(PUT, LONG, 54),          /* PUT the input file */
 340   T(MUTE, LONG, 55),         /* force NOPROGRESS */
 341
 342   CURLOPT_LASTENTRY /* the last unusued */
 343 } CURLoption;
 344
 345 #define CURL_PROGRESS_STATS 0 /* default progress display */
 346 #define CURL_PROGRESS_BAR   1
 347
 348 typedef enum {
 349   TIMECOND_NONE,
 350
 351   TIMECOND_IFMODSINCE,
 352   TIMECOND_IFUNMODSINCE,
 353   TIMECOND_LASTMOD,
 354
 355   TIMECOND_LAST
 356 } TimeCond;
 357
 358 #ifdef __BEOS__
 359 #include <support/SupportDefs.h>
 360 #else
 361 #ifndef __cplusplus        /* (rabe) */
 362 typedef char bool;
 363 #endif                     /* (rabe) */
 364 #endif
 365
 366 #if 0
 367 /* At last, I stand here in front of you today and can officially proclaim
 368    this function prototype as history... 17th of May, 2000 */
 369 UrgError curl_urlget(UrgTag, ...);
 370 #endif
 371
 372 /* external form function */
 373 int curl_FormParse(char *string,
 374                    struct HttpPost **httppost,
 375                    struct HttpPost **last_post);
 376
 377 /* Unix and Win32 getenv function call */
 378 char *curl_GetEnv(char *variable);
 379
 380 /* returns ascii string of the libcurl version */
 381 char *curl_version(void);
 382
 383 /* This is the version number */
 384 #define LIBCURL_VERSION "7.0beta"
 385 #define LIBCURL_VERSION_NUM 0x070000
 386
 387 /* linked-list structure for the CURLOPT_QUOTE option */
 388 struct curl_slist {
 389         char                    *data;
 390         struct curl_slist       *next;
 391 };
 392
 393 struct curl_slist *curl_slist_append(struct curl_slist *list, char *data);
 394 void curl_slist_free_all(struct curl_slist *list);
 395
 396 /*
 397  * NAME curl_init()
 398  *
 399  * DESCRIPTION
 400  *
 401  * Inits libcurl globally. This must be used before any libcurl calls can
 402  * be used. This may install global plug-ins or whatever. (This does not
 403  * do winsock inits in Windows.)
 404  *
 405  * EXAMPLE
 406  *
 407  * curl_init();
 408  *
 409  */
 410 CURLcode curl_init(void);
 411
 412 /*
 413  * NAME curl_init()
 414  *
 415  * DESCRIPTION
 416  *
 417  * Frees libcurl globally. This must be used after all libcurl calls have
 418  * been used. This may remove global plug-ins or whatever. (This does not
 419  * do winsock cleanups in Windows.)
 420  *
 421  * EXAMPLE
 422  *
 423  * curl_free(curl);
 424  *
 425  */
 426 void curl_free(void);
 427
 428 /*
 429  * NAME curl_open()
 430  *
 431  * DESCRIPTION
 432  *
 433  * Opens a general curl session. It does not try to connect or do anything
 434  * on the network because of this call. The specified URL is only required
 435  * to enable curl to figure out what protocol to "activate".
 436  *
 437  * A session should be looked upon as a series of requests to a single host.  A
 438  * session interacts with one host only, using one single protocol.
 439  *
 440  * The URL is not required. If set to "" or NULL, it can still be set later
 441  * using the curl_setopt() function. If the curl_connect() function is called
 442  * without the URL being known, it will return error.
 443  *
 444  * EXAMPLE
 445  *
 446  * CURLcode result;
 447  * CURL *curl;
 448  * result = curl_open(&curl, "http://curl.haxx.nu/libcurl/");
 449  * if(result != CURL_OK) {
 450  *   return result;
 451  * }
 452  * */
 453 CURLcode curl_open(CURL **curl, char *url);
 454
 455 /*
 456  * NAME curl_setopt()
 457  *
 458  * DESCRIPTION
 459  *
 460  * Sets a particular option to the specified value.
 461  *
 462  * EXAMPLE
 463  *
 464  * CURL curl;
 465  * curl_setopt(curl, CURL_HTTP_FOLLOW_LOCATION, TRUE);
 466  */
 467 CURLcode curl_setopt(CURL *handle, CURLoption option, ...);
 468
 469 /*
 470  * NAME curl_close()
 471  *
 472  * DESCRIPTION
 473  *
 474  * Closes a session previously opened with curl_open()
 475  *
 476  * EXAMPLE
 477  *
 478  * CURL *curl;
 479  * CURLcode result;
 480  *
 481  * result = curl_close(curl);
 482  */
 483 CURLcode curl_close(CURL *curl); /* the opposite of curl_open() */
 484
 485 CURLcode curl_read(CURLconnect *c_conn, char *buf, size_t buffersize,
 486                    size_t *n);
 487 CURLcode curl_write(CURLconnect *c_conn, char *buf, size_t amount,
 488                     size_t *n);
 489
 490 /*
 491  * NAME curl_connect()
 492  *
 493  * DESCRIPTION
 494  *
 495  * Connects to the peer server and performs the initial setup. This function
 496  * writes a connect handle to its second argument that is a unique handle for
 497  * this connect. This allows multiple connects from the same handle returned
 498  * by curl_open().
 499  *
 500  * EXAMPLE
 501  *
 502  * CURLCode result;
 503  * CURL curl;
 504  * CURLconnect connect;
 505  * result = curl_connect(curl, &connect);
 506  */
 507
 508 CURLcode curl_connect(CURL *curl, CURLconnect **in_connect);
 509
 510 /*
 511  * NAME curl_do()
 512  *
 513  * DESCRIPTION
 514  *
 515  * (Note: May 3rd 2000: this function does not currently allow you to
 516  * specify a document, it will use the one set previously)
 517  *
 518  * This function asks for the particular document, file or resource that
 519  * resides on the server we have connected to. You may specify a full URL,
 520  * just an absolute path or even a relative path. That means, if you're just
 521  * getting one file from the remote site, you can use the same URL as input
 522  * for both curl_open() as well as for this function.
 523  *
 524  * In the even there is a host name, port number, user name or password parts
 525  * in the URL, you can use the 'flags' argument to ignore them completely, or
 526  * at your choice, make the function fail if you're trying to get a URL from
 527  * different host than you connected to with curl_connect().
 528  *
 529  * You can only get one document at a time using the same connection. When one
 530  * document has been received you can although request again.
 531  *
 532  * When the transfer is done, curl_done() MUST be called.
 533  *
 534  * EXAMPLE
 535  *
 536  * CURLCode result;
 537  * char *url;
 538  * CURLconnect *connect;
 539  * result = curl_do(connect, url, CURL_DO_NONE); */
 540 CURLcode curl_do(CURLconnect *in_conn);
 541
 542 /*
 543  * NAME curl_done()
 544  *
 545  * DESCRIPTION
 546  *
 547  * When the transfer following a curl_do() call is done, this function should
 548  * get called.
 549  *
 550  * EXAMPLE
 551  *
 552  * CURLCode result;
 553  * char *url;
 554  * CURLconnect *connect;
 555  * result = curl_done(connect); */
 556 CURLcode curl_done(CURLconnect *connect);
 557
 558 /*
 559  * NAME curl_disconnect()
 560  *
 561  * DESCRIPTION
 562  *
 563  * Disconnects from the peer server and performs connection cleanup.
 564  *
 565  * EXAMPLE
 566  *
 567  * CURLcode result;
 568  * CURLconnect *connect;
 569  * result = curl_disconnect(connect); */
 570 CURLcode curl_disconnect(CURLconnect *connect);
 571
 572 /*
 573  * NAME curl_getdate()
 574  *
 575  * DESCRIPTION
 576  *
 577  * Returns the time, in seconds since 1 Jan 1970 of the time string given in
 578  * the first argument. The time argument in the second parameter is for cases
 579  * where the specified time is relative now, like 'two weeks' or 'tomorrow'
 580  * etc.
 581  */
 582 time_t curl_getdate(const char *p, const time_t *now);
 583
 584 #endif /* __CURL_CURL_H */