118 lines
4.8 KiB
Plaintext
118 lines
4.8 KiB
Plaintext
_ _ _ _
|
|
| (_) |__ ___ _ _ _ __| |
|
|
| | | '_ \ / __| | | | '__| |
|
|
| | | |_) | (__| |_| | | | |
|
|
|_|_|_.__/ \___|\__,_|_| |_|
|
|
|
|
How To Use Libcurl In Your C/C++ Program
|
|
|
|
[ libcurl can be used directly from within your Java, PHP, Perl, Ruby or Tcl
|
|
programs as well, look elsewhere for documentation on this ]
|
|
|
|
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 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 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.
|
|
|
|
Linking with libcurl
|
|
|
|
Staring with 7.7.2 (on unix-like machines), there's a tool named curl-config
|
|
that gets installed with the rest of the curl stuff when 'make install' is
|
|
performed.
|
|
|
|
curl-config is added to make it easier for applications to link with
|
|
libcurl and developers to learn about libcurl and how to use it.
|
|
|
|
Run 'curl-config --libs' to get the (additional) linker options you need to
|
|
link with the particular version of libcurl you've installed.
|
|
|
|
For details, see the curl-config.1 man page.
|
|
|
|
libcurl symbol names
|
|
|
|
All public functions in the libcurl interface are prefixed with 'curl_' (with
|
|
a lowercase c). You can find other functions in the library source code, but
|
|
other prefixes indicate the functions are private and may change without
|
|
further notice in the next release.
|
|
|
|
Only use documented functions and functionality!
|
|
|
|
Portability
|
|
|
|
libcurl works *exactly* the same, on any of the platforms it compiles and
|
|
builds on.
|
|
|
|
There's only one caution, and that is the win32 platform that may(*) require
|
|
you to init the winsock stuff before you use the libcurl functions. Details
|
|
on this are noted on the curl_easy_init() man page.
|
|
|
|
(*) = it appears as if users of the cygwin environment get this done
|
|
automatically.
|
|
|
|
Threads
|
|
|
|
Never *ever* call curl-functions simultaneously using the same handle from
|
|
several threads. libcurl is thread-safe and can be used in any number of
|
|
threads, but you must use separate curl handles if you want to use libcurl in
|
|
more than one thread simultaneously.
|
|
|
|
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.
|
|
|