.\" You can view this file with:
.\" nroff -man [file]
.\" $Id: libcurl-client.3,v 1.4 2004/05/05 06:11:57 bagder Exp $
.\"
.TH libcurl 3 "04 Dec 2005" "libcurl 7.10.7" "libcurl client object"
.SH NAME
libcurl-client \- client object overview
.SH DESCRIPTION
A libcurl session (a session is what an easy handle represents) belongs
to a libcurl client.  A typical program has one libcurl client that owns
all libcurl sessions, but you can have as many as you want.

The easiest way to use libcurl is to use the built in global client object.
You initialize that with \fIcurl_global_init()\fP and create easy handles
for it with \fIcurl_easy_init()\fP.

But you can also explicitly create a client with
\fIcurl_client_init()\fP, which returns you a client handle.  You then
create easy handles for that client with \fIcurl_easy_init_c()\fP,
which takes the client handle as an argument.

The main advantage of making your own client today is that you control
explicitly what parts of your program's global environment it uses and
manipulates, and thereby can make a program module that is more modular
or at least handle the non-modularity in a cleaner, more obvious way.

In the future, it will be possible for clients to have their own private
environment to take the place of global environment and make your module
even more modular.

This tricky global environment issue is explained in detail in the 
\fIlibcurl(3)\fP man page, in the "ENVIRONMENT" section.

As an example of how your own client object addresses the issue,
consider the OpenSSL library.  If you want your libcurl session to do
an HTTPS (SSL) transaction, something somewhere in your program must
have called \fISSL_load_error_strings()\fP.  When you use Libcurl's global
client, your call to \fIcurl_global_init()\fP calls it.  The problem
with this is that it affects any other user of OpenSSL in your
program, including other users of libcurl.  To make it worse, a) you
(and people maintaining your code) may not realize that this is
happening under the covers; and b) even if you don't require the ability
to do HTTPS connections, this global manipulation still takes place.

But use your own libcurl client, and it's different.  Because you
don't call \fIcurl_global_init()\fP, libcurl will never call
\fISSL_load_error_strings()\fP.  By default, libcurl sessions you
create for this client will not be able to use HTTPS (any attempt to
do so will fail with a clear indication that the program doesn't
provide for HTTPS).  If you want HTTPS capability, you call
\fISSL_load_error_strings()\fP in your own code, then create the
client object with the CURL_GLIENT_GLOBAL_OPENSSL flag so it knows
that you have set up the OpenSSL environment and it is OK for the
client's sessions to use it.

That's a small improvement to the maintainability of your code, but in
the future, the advantage will be much greater: There will presumably
be an OpenSSL library that is modular itself, and has a private
version of \fISSL_load_error_strings()\fP.  When there is, libcurl
will call that as part of creating your libcurl client, and your
libcurl sessions will use HTTPS without affecting any other user of
OpenSSL in your program.


.SH HOW TO USE PRIVATE CLIENTS

You refer to a libcurl client object with a client handle, which has
type CURLC *.

You create a private client (as opposed to the \fIglobal\fP client
that always exists) with \fIcurl_client_init()\fP.

Create a libcurl session (easy handle) that uses your client with
\fIcurl_easy_init_c()\fP.  (In contrast, \fIcurl_easy_init()\fP uses
the global client).

Destroy such a libcurl session with \fIcurl_easy_cleanup()\fP (same as
with the global client).

When you're done with a client (and no easy handles that use it
exist), destroy it with \fIcurl_client_cleanup()\fP.

By default, libcurl will not use various global facilties -- it won't
modify them and won't assume that they're in a usable state already --
in connection with sessions that belong to a private client.  And
since libcurl doesn't have any way other than such global facilities
to do some things (e.g. on a Windows system, libcurl can't even send a
network packet without using the global Winsock facility), such a
session may be totally useless (i.e. any operation you attempt with it
will fail).

To tell libcurl that it is OK to use a global facility, and that you
have done whatever setup is necessary to make it work, include the
appropriate flags in the argument of \fIcurl_client_init()\fP.

.SH "SEE ALSO"
.BR curl_client_init "(3), " curl_client_cleanup "(3), "
.BR curl_easy_init_c "(3), "
.BR libcurl "(3)"