| _ _ _ _ |
| | (_) |__ ___ _ _ _ __| | |
| | | | '_ \ / __| | | | '__| | |
| | | | |_) | (__| |_| | | | | |
| |_|_|_.__/ \___|\__,_|_| |_| |
| |
| How To Use Libcurl In Your C/C++ Program |
| |
| [ libcurl can be used directly from within your PHP or Perl 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. |
| |
| 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. |
| |