aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2001-03-05 15:38:06 +0000
committerDaniel Stenberg <daniel@haxx.se>2001-03-05 15:38:06 +0000
commit1e8e90a2203042559a9e895333fb52f07188090c (patch)
treeb98a9cfab2cf63d295630a21df5a7c544d39a698
parentfe95c7dc34e00ad39b53b147c6a6391a2146beae (diff)
mucho updated with new 7.7 concepts
-rw-r--r--docs/LIBCURL105
1 files changed, 58 insertions, 47 deletions
diff --git a/docs/LIBCURL b/docs/LIBCURL
index f9564fa5a..3e1610283 100644
--- a/docs/LIBCURL
+++ b/docs/LIBCURL
@@ -4,58 +4,69 @@
| | | |_) | (__| |_| | | | |
|_|_|_.__/ \___|\__,_|_| |_|
-
How To Use Libcurl In Your Program
-Interfaces
-
- libcurl currently offers two different interfaces to the URL transfer
- engine. They can be seen as one low-level and one high-level, in the sense
- that the low-level one will allow you to deal with a lot more details but on
- the other hand not offer as many fancy features (such as Location:
- following). The high-level interface is supposed to be a built-in
- implementation of the low-level interface. You will not be able to mix
- function calls from the different layers.
-
- As we currently ONLY support the high-level interface, the so called easy
- interface, I will not attempt to describe any low-level functions at this
- point.
-
-Function descriptions
-
- The interface is meant to be very simple for very simple
- implementations. Thus, we have minimized the number of entries.
+ The interface is meant to be very simple for applictions/programmers, hence
+ the name "easy". We have therefore minimized the number of entries.
The Easy Interface
- When using the easy interface, you init your easy-session and get a handle,
- which you use as input to the following interface functions you use.
+ When using the easy interface, you init your session and get a handle, which
+ you use as input to the following interface functions you use. Use
+ curl_easy_init() to get the handle.
You continue by setting all the options you want in the upcoming transfer,
- most important among them is the URL itself. You might want to set some
- callbacks as well that will be called from the library when data is available
- etc.
-
- When all is setup, you tell libcurl to perform the transfer. It will then do
- the entire operation and won't return until it is done or failed.
-
- After the transfer has been made, you cleanup the easy-session's handle and
- libcurl is entirely off the hook!
-
- curl_easy_init()
- curl_easy_setopt()
- curl_easy_perform()
- curl_easy_cleanup()
-
- While the above four functions are the main functions to use in the easy
- interface, there is a series of helpful functions to use. They are:
-
- curl_version() - displays the libcurl version
- curl_getdate() - converts a date string to time_t
- curl_getenv() - portable environment variable reader
- curl_formparse() - helps building a HTTP form POST
- curl_slist_append() - builds a linked list
- curl_slist_free_all() - frees a whole curl_slist
-
- Read the separate man pages for these functions for details!
+ most important among them is the URL itself (you can't transfer anything
+ without a specified URL as you may have figured out yourself). You might want
+ to set some callbacks as well that will be called from the library when data
+ is available etc. curl_easy_setopt() is there for this.
+
+ When all is setup, you tell libcurl to perform the transfer using
+ curl_easy_perform(). It will then do the entire operation and won't return
+ until it is done or failed.
+
+ After the transfer has been made, you cleanup the session with
+ curl_easy_cleanup() and libcurl is entirely off the hook! If you want
+ persistant connections, you don't cleanup immediately, but instead run ahead
+ and perform other transfers. See the chapter below for Persistant
+ Connections.
+
+ While the above mentioned four functions are the main functions to use in the
+ easy interface, there is a series of other helpful functions to use. They
+ are:
+
+ curl_version() - displays the libcurl version
+ curl_getdate() - converts a date string to time_t
+ curl_getenv() - portable environment variable reader
+ curl_easy_getinfo() - get information about a performed transfer
+ curl_formparse() - helps building a HTTP form POST
+ curl_formfree() - free a list built with curl_formparse()
+ curl_slist_append() - builds a linked list
+ curl_slist_free_all() - frees a whole curl_slist
+
+ For details on these, read the separate man pages.
+
+Persistant Connections
+
+ With libcurl 7.7, persistant connections were added. Persistant connections
+ means that libcurl can re-use the same connection for several transfers, if
+ the conditions are right.
+
+ libcurl will *always* attempt to use persistant connections. Whenever you use
+ curl_easy_perform(), libcurl will attempt to use an existing connection to do
+ the transfer, and if none exists it'll open a new one that will be subject
+ for re-use on a possible following call to curl_easy_perform().
+
+ To allow libcurl to take full advantage of persistant connections, you should
+ do as many of your file transfers as possible using the same curl
+ handle. When you call curl_easy_cleanup(), all the possibly open connections
+ held by libcurl will be closed and forgotten.
+
+ Note that the options set with curl_easy_setopt() will be used in on every
+ repeat curl_easy_perform() call
+
+Compatibility with older libcurls
+
+ Repeated curl_easy_perform() calls on the same handle were not supported in
+ pre-7.7 versions, and caused confusion and defined behaviour.