aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--include/curl/curl.h252
1 files changed, 181 insertions, 71 deletions
diff --git a/include/curl/curl.h b/include/curl/curl.h
index 7ae5560c2..00074d561 100644
--- a/include/curl/curl.h
+++ b/include/curl/curl.h
@@ -23,6 +23,30 @@
* $Id$
***************************************************************************/
+/* If you have problems, all libcurl docs and details are found here:
+ http://curl.haxx.se/libcurl/
+*/
+
+/* This is the version number of the libcurl package from which this header
+ file origins: */
+#define LIBCURL_VERSION "7.10.6-pre3"
+
+/* This is the numeric version of the libcurl version number, meant for easier
+ parsing and comparions by programs. The LIBCURL_VERSION_NUM define will
+ always follow this syntax:
+
+ 0xXXYYZZ
+
+ Where XX, YY and ZZ are the main version, release and patch numbers in
+ hexadecimal. All three numbers are always represented using two digits. 1.2
+ would appear as "0x010200" while version 9.11.7 appears as "0x090b07".
+
+ This 6-digit hexadecimal number does not show pre-release number, and it is
+ always a greater number in a more recent release. It makes comparisons with
+ greater than and less than work.
+*/
+#define LIBCURL_VERSION_NUM 0x070a06
+
#include <stdio.h>
/* The include stuff here is mainly for time_t! */
#ifdef vms
@@ -51,39 +75,36 @@
extern "C" {
#endif
-/* stupid #define trick to preserve functionality with older code, but
- making it use our name space for the future */
+/* silly trick to preserve functionality with older code, but making it use
+ our name space for the future */
#define HttpPost curl_httppost
struct curl_httppost {
- struct curl_httppost *next; /* next entry in the list */
- char *name; /* pointer to allocated name */
- long namelength; /* length of name length */
- char *contents; /* pointer to allocated data contents */
- long contentslength; /* length of contents field */
-
- /* CMC: Added support for buffer uploads */
- char *buffer; /* pointer to allocated buffer contents */
- long bufferlength; /* length of buffer field */
-
- char *contenttype; /* Content-Type */
+ struct curl_httppost *next; /* next entry in the list */
+ char *name; /* pointer to allocated name */
+ long namelength; /* length of name length */
+ char *contents; /* pointer to allocated data contents */
+ long contentslength; /* length of contents field */
+ char *buffer; /* pointer to allocated buffer contents */
+ long bufferlength; /* length of buffer field */
+ char *contenttype; /* Content-Type */
struct curl_slist* contentheader; /* list of extra headers for this form */
- struct curl_httppost *more; /* if one field name has more than one file, this
- link should link to following files */
- long flags; /* as defined below */
-#define HTTPPOST_FILENAME (1<<0) /* specified content is a file name */
-#define HTTPPOST_READFILE (1<<1) /* specified content is a file name */
-#define HTTPPOST_PTRNAME (1<<2) /* name is only stored pointer
- do not free in formfree */
+ struct curl_httppost *more; /* if one field name has more than one
+ file, this link should link to following
+ files */
+ long flags; /* as defined below */
+#define HTTPPOST_FILENAME (1<<0) /* specified content is a file name */
+#define HTTPPOST_READFILE (1<<1) /* specified content is a file name */
+#define HTTPPOST_PTRNAME (1<<2) /* name is only stored pointer
+ do not free in formfree */
#define HTTPPOST_PTRCONTENTS (1<<3) /* contents is only stored pointer
do not free in formfree */
+#define HTTPPOST_BUFFER (1<<4) /* upload file from buffer */
+#define HTTPPOST_PTRBUFFER (1<<5) /* upload file from pointer contents */
-/* CMC: Added support for buffer uploads */
-#define HTTPPOST_BUFFER (1<<4) /* upload file from buffer */
-#define HTTPPOST_PTRBUFFER (1<<5) /* upload file from pointer contents */
-
- char *showfilename; /* The file name to show. If not set, the actual
- file name will be used (if this is a file part) */
+ char *showfilename; /* The file name to show. If not set, the
+ actual file name will be used (if this
+ is a file part) */
};
typedef int (*curl_progress_callback)(void *clientp,
@@ -213,13 +234,13 @@ typedef enum {
CURLPROXY_SOCKS5 = 5
} curl_proxytype;
-typedef enum {
- CURLAUTH_BASIC = 0, /* default */
- CURLAUTH_DIGEST = 1, /* Digest */
- CURLAUTH_GSSNEGOTIATE = 2, /* GSS-Negotiate */
- CURLAUTH_NTLM = 3, /* NTLM */
- CURLAUTH_LASTKNOWN /* never to be used */
-} curl_httpauth;
+#define CURLAUTH_NONE 0 /* nothing */
+#define CURLAUTH_BASIC (1<<0) /* Basic (default) */
+#define CURLAUTH_DIGEST (1<<1) /* Digest */
+#define CURLAUTH_GSSNEGOTIATE (1<<2) /* GSS-Negotiate */
+#define CURLAUTH_NTLM (1<<3) /* NTLM */
+#define CURLAUTH_ANY ~0 /* all types set */
+#define CURLAUTH_ANYSAFE (~CURLAUTH_BASIC)
/* this was the error code 50 in 7.7.3 and a few earlier versions, this
is no longer used by libcurl but is instead #defined here only to not
@@ -270,6 +291,12 @@ typedef enum {
#define CINIT(name,type,number) CURLOPT_/**/name = type + number
#endif
+/*
+ * This macro-mania below setups the CURLOPT_[what] enum, to be used with
+ * curl_easy_setopt(). The first argument in the CINIT() macro is the [what]
+ * word.
+ */
+
typedef enum {
CINIT(NOTHING, LONG, 0), /********* the first one is unused ************/
@@ -279,24 +306,19 @@ typedef enum {
/* The full URL to get/put */
CINIT(URL, OBJECTPOINT, 2),
- /* Port number to connect to, if other than default. Specify the CONF_PORT
- flag in the CURLOPT_FLAGS to activate this */
+ /* Port number to connect to, if other than default. */
CINIT(PORT, LONG, 3),
- /* Name of proxy to use. Specify the CONF_PROXY flag in the CURLOPT_FLAGS to
- activate this */
+ /* Name of proxy to use. */
CINIT(PROXY, OBJECTPOINT, 4),
- /* Name and password to use when fetching. Specify the CONF_USERPWD flag in
- the CURLOPT_FLAGS to activate this */
+ /* "name:password" to use when fetching. */
CINIT(USERPWD, OBJECTPOINT, 5),
- /* Name and password to use with Proxy. Specify the CONF_PROXYUSERPWD
- flag in the CURLOPT_FLAGS to activate this */
+ /* "name:password" to use with proxy. */
CINIT(PROXYUSERPWD, OBJECTPOINT, 6),
- /* Range to get, specified as an ASCII string. Specify the CONF_RANGE flag
- in the CURLOPT_FLAGS to activate this */
+ /* Range to get, specified as an ASCII string. */
CINIT(RANGE, OBJECTPOINT, 7),
/* not used */
@@ -417,7 +439,6 @@ typedef enum {
as described elsewhere. */
CINIT(WRITEINFO, OBJECTPOINT, 40),
- /* Previous FLAG bits */
CINIT(VERBOSE, LONG, 41), /* talk a lot */
CINIT(HEADER, LONG, 42), /* throw the header out too */
CINIT(NOPROGRESS, LONG, 43), /* shut off the progress meter */
@@ -633,8 +654,9 @@ typedef enum {
attempted before the good old traditional PORT command. */
CINIT(FTP_USE_EPRT, LONG, 106),
- /* Set this to a curl_httpauth value to enable that particular authentication
- method. Use this in combination with CURLOPT_USERPWD. */
+ /* Set this to a bitmask value to enable the particular authentications
+ methods you like. Use this in combination with CURLOPT_USERPWD.
+ Note that setting multiple bits may cause extra network round-trips. */
CINIT(HTTPAUTH, LONG, 107),
CURLOPT_LASTENTRY /* the last unused */
@@ -705,9 +727,9 @@ typedef enum {
#endif
-/* These functions are in the libcurl, they're here for portable reasons and
- they are used by the 'curl' client. They really should be moved to some kind
- of "portability library" since it has nothing to do with file transfers and
+/* These functions are in libcurl, they're here for portable reasons and they
+ are used by the 'curl' client. They really should be moved to some kind of
+ "portability library" since it has nothing to do with file transfers and
might be usable to other programs...
NOTE: they return TRUE if the strings match *case insensitively*.
@@ -715,9 +737,12 @@ typedef enum {
extern int (curl_strequal)(const char *s1, const char *s2);
extern int (curl_strnequal)(const char *s1, const char *s2, size_t n);
-/* DEPRECATED function to build formdata */
+#ifdef CURL_OLDSTYLE
+/* DEPRECATED function to build formdata. Stop using this, it will cease
+ to exist. */
int curl_formparse(char *, struct curl_httppost **,
struct curl_httppost **_post);
+#endif
/* name is uppercase CURLFORM_<name> */
#ifdef CFINIT
@@ -796,47 +821,122 @@ typedef enum {
CURL_FORMADD_LAST /* last */
} CURLFORMcode;
+/*
+ * NAME curl_formadd()
+ *
+ * DESCRIPTION
+ *
+ * Pretty advanved function for building multi-part formposts. Each invoke
+ * adds one part that together construct a full post. Then use
+ * CURLOPT_HTTPPOST to send it off to libcurl.
+ */
CURLFORMcode curl_formadd(struct curl_httppost **httppost,
- struct curl_httppost **last_post,
- ...);
+ struct curl_httppost **last_post,
+ ...);
-/* cleanup a form: */
+/*
+ * NAME curl_formfree()
+ *
+ * DESCRIPTION
+ *
+ * Free a multipart formpost previously built with curl_formadd().
+ */
void curl_formfree(struct curl_httppost *form);
-/* Unix and Win32 getenv function call, this returns a malloc()'ed string that
- MUST be free()ed after usage is complete. */
+/*
+ * NAME curl_getenv()
+ *
+ * DESCRIPTION
+ *
+ * Returns a malloc()'ed string that MUST be curl_free()ed after usage is
+ * complete.
+ */
char *curl_getenv(const char *variable);
-/* Returns a static ascii string of the libcurl version. */
+/*
+ * NAME curl_version()
+ *
+ * DESCRIPTION
+ *
+ * Returns a static ascii string of the libcurl version.
+ */
char *curl_version(void);
-/* Escape and unescape URL encoding in strings. The functions return a new
- * allocated string or NULL if an error occurred. */
+/*
+ * NAME curl_escape()
+ *
+ * DESCRIPTION
+ *
+ * Escapes URL strings (converts all letters consider illegal in URLs to their
+ * %XX versions). This function returns a new allocated string or NULL if an
+ * error occurred.
+ */
char *curl_escape(const char *string, int length);
+
+/*
+ * NAME curl_unescape()
+ *
+ * DESCRIPTION
+ *
+ * Unescapes URL encoding in strings (converts all %XX codes to their 8bit
+ * versions). This function returns a new allocated string or NULL if an error
+ * occurred.
+ */
char *curl_unescape(const char *string, int length);
-/* 20020912 WJM. Provide for a de-allocation in the same translation unit
- that did the allocation. Added in libcurl 7.10 */
+
+/*
+ * NAME curl_free()
+ *
+ * DESCRIPTION
+ *
+ * Provided for de-allocation in the same translation unit that did the
+ * allocation. Added in libcurl 7.10
+ */
void curl_free(void *p);
-/* curl_global_init() should be invoked exactly once for each application that
- uses libcurl */
+/*
+ * NAME curl_global_init()
+ *
+ * DESCRIPTION
+ *
+ * curl_global_init() should be invoked exactly once for each application that
+ * uses libcurl
+ */
CURLcode curl_global_init(long flags);
-/* curl_global_cleanup() should be invoked exactly once for each application
- that uses libcurl */
+/*
+ * NAME curl_global_cleanup()
+ *
+ * DESCRIPTION
+ *
+ * curl_global_cleanup() should be invoked exactly once for each application
+ * that uses libcurl
+ */
void curl_global_cleanup(void);
-/* This is the version number */
-#define LIBCURL_VERSION "7.10.6-pre1"
-#define LIBCURL_VERSION_NUM 0x070a06
-
/* linked-list structure for the CURLOPT_QUOTE option (and other) */
struct curl_slist {
- char *data;
- struct curl_slist *next;
+ char *data;
+ struct curl_slist *next;
};
+/*
+ * NAME curl_slist_append()
+ *
+ * DESCRIPTION
+ *
+ * Appends a string to a linked list. If no list exists, it will be created
+ * first. Returns the new list, after appending.
+ */
struct curl_slist *curl_slist_append(struct curl_slist *, const char *);
+
+/*
+ * NAME curl_slist_free_all()
+ *
+ * DESCRIPTION
+ *
+ * free a previously built curl_slist.
+ */
void curl_slist_free_all(struct curl_slist *);
/*
@@ -1004,8 +1104,18 @@ typedef struct {
#define CURL_VERSION_KERBEROS4 (1<<1)
#define CURL_VERSION_SSL (1<<2)
#define CURL_VERSION_LIBZ (1<<3)
+#define CURL_VERSION_NTLM (1<<4)
+#define CURL_VERSION_GSSNEGOTIATE (1<<5)
+#define CURL_VERSION_DEBUG (1<<6) /* built with debug capabilities */
-/* returns a pointer to a static copy of the version info struct */
+/*
+ * NAME curl_version_info()
+ *
+ * DESCRIPTION
+ *
+ * This function returns a pointer to a static copy of the version info
+ * struct. See above.
+ */
curl_version_info_data *curl_version_info(CURLversion);
#ifdef __cplusplus