Lines Matching full:to

20 This document attempts to describe the general principles and some basic
21 approaches to consider when programming with libcurl. The text focuses on the
25 This document refers to 'the user' as the person writing the source code that
27 generally referred to as 'the program' is the collected source code that you
31 To get more details on all options and functions described herein, please
32 refer to their respective man pages.
36 There are many different ways to build C programs. This chapter assumes a Unix
38 this to get general information that may apply to your environment as well.
42 Your compiler needs to know where the libcurl headers are located. Therefore
43 you must set your compiler's include path to point to the directory where you
44 installed them. The 'curl-config'[3] tool can be used to get this information:
51 When having compiled the program, you need to link your object files to create
52 a single executable. For that to succeed, you need to link with libcurl and
55 command line. To figure out which flags to use, once again the 'curl-config'
56 tool comes to the rescue:
66 properly at build-time, libcurl is built with SSL support. To figure out if an
74 If SSL is supported, the keyword *SSL* is written to stdout, possibly together
82 When you write your configure script to detect libcurl and setup variables
84 area. See docs/libcurl/libcurl.m4 file - it includes docs on how to use it.
88 The people behind libcurl have put a considerable effort to make libcurl work
92 are only a few minor details that differ. If you just make sure to write your
99 means it should be done exactly once, no matter how many times you intend to
104 and it takes one parameter which is a bit pattern that tells libcurl what to
115 or of another library in use does it, you should not tell libcurl to do this
122 application. This only needs to be done once for each application so if your
133 performs the reversed operations to cleanup the resources the
136 Repeated calls to curl_global_init(3) and curl_global_cleanup(3)
141 It is considered best-practice to determine libcurl features at runtime rather
155 interface is detailed in a separate chapter further down. You still need to
161 To use the easy interface, you must first create yourself an easy handle. You
162 need one handle for each easy session you want to perform. Basically, you
163 should use one handle for every thread you plan to use for transferring. You
170 It returns an easy handle. Using that you proceed to the next step: setting
177 set again to something different. They are sticky. Multiple requests using the
180 If you at any point would like to blank all previously set options for a
185 Many of the options you set in libcurl are "strings", pointers to data
188 to be kept around in your application after being set[4].
190 One of the most basic properties to set in the handle is the URL. You set your
191 preferred URL to transfer with CURLOPT_URL(3) in a manner similar to:
197 Let's assume for a while that you want to receive data as the URL identifies a
198 remote resource you want to get here. Since you write a sort of application
199 that needs this transfer, I assume that you would like to get the data passed
200 to you directly instead of simply getting it passed to stdout. So, you write
205 You tell libcurl to pass all data to this function by issuing a function
206 similar to this:
221 outputs the received data to stdout. You can have the default callback write
222 the data to a different file handle by passing a 'FILE *' to a file opened for
225 Now, we need to take a step back and take a deep breath. Here is one of those
227 libcurl is not able to operate on file handles opened by the
230 to make your program run fine virtually everywhere.
239 There are of course many more options you can set, and we get back to a few of
240 them later. Let's instead continue to the actual transfer:
246 curl_easy_perform(3) connects to the remote site, does the necessary commands
251 care of". If that is not the same amount of bytes that was passed to it,
256 you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer of
259 If you then want to transfer another file, the handle is ready to be used
261 if you intend to make another transfer. libcurl then attempts to reuse a
267 complication for you. Given simply the URL to a file, libcurl takes care of
268 all the details needed to get the file moved from one machine to another.
272 libcurl is thread safe but there are a few exceptions. Refer to
283 CURLOPT_VERBOSE(3) option to 1. it causes the library to spew out the
286 adding the headers in the received output to study is also a clever way to get
290 Of course, there are bugs left. We need to know about them to be able to fix
301 and if you are trying to do funny things, you might understand libcurl and how
302 to use it better if you study the appropriate RFC documents at least briefly.
304 # Upload Data to a Remote Site
306 libcurl tries to keep a protocol independent approach to most transfers, thus
307 uploading to a remote FTP site is similar to uploading data to an HTTP server
311 one. Then you set the URL to operate on just like before. This is the remote
314 Since we write an application, we most likely want libcurl to get the upload
315 data by asking us for it. To make it do that, we set the read callback and the
316 custom pointer libcurl passes to our read callback. The read callback should
317 have a prototype similar to:
321 Where *bufptr* is the pointer to a buffer we fill in with data to upload
323 amount of data we can return to libcurl in this call. The *userp* pointer
324 is the custom pointer we set to point to a struct of ours to pass private data
331 Tell libcurl that we want to upload:
346 callback to get the data to upload. The program should return as much data as
347 possible in every invoke, as that is likely to make the upload perform as fast
354 to be able to download or upload the data of your choice. libcurl offers
355 several ways to specify them.
366 libcurl also provides options to set various passwords. The user name and
368 CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a
369 char * to a string in the format "user:password". In a manner like this:
376 users who need to authenticate themselves to a proxy they use. libcurl offers
378 to the CURLOPT_USERPWD(3) option like this:
389 the password in plain text. libcurl has the ability to use this file to figure
390 out what set of user name and password to use for a particular host. As an
391 extension to the normal functionality, libcurl also supports this file for
392 non-FTP protocols such as HTTP. To make curl use this file, use the
408 at least you could leave it out and have libcurl attempt to do its job
412 To pass the known private key password to libcurl:
419 The previous chapter showed how to set user name and password for getting URLs
421 different ways a client can provide those credentials to the server and you
426 At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM,
427 Negotiate (SPNEGO). You can tell libcurl which one to use with
435 When you send authentication to a proxy, you can also set authentication type
442 Both these options allow you to set multiple types (by ORing them together),
443 to make libcurl pick the most secure one out of the types the server/proxy
444 claims to support. This method does however add a round-trip since libcurl
452 specific types) which allows libcurl to use whatever method it wants.
459 We get many questions regarding how to issue HTTP POSTs with libcurl the
464 pages using the <form> tag uses. We provide a pointer to the data and tell
465 libcurl to post it all to the remote site:
476 CURLOPT_POSTFIELDS(3), this automatically switches the handle to use
479 What if you want to post binary data that also requires you to set the
481 able to do strlen() on the data to figure out the size, so therefore we must
484 that list to libcurl.
506 formposts were introduced as a better way to post (possibly large) binary data
512 yourself and provide to libcurl.
514 To make that easier, libcurl provides a MIME API consisting in several
517 to a multi-part body using curl_mime_addpart(3).
551 To post multiple files for a single form field, you must supply each file in
556 To set the data source from an already opened FILE pointer, use:
565 ought to be converted to the MIME API. It is however described here as an
566 aid to conversion.
568 Using *curl_formadd*, you add parts to the form. When you are done adding
597 that describe the individual content-type, size etc. To enable your
598 application to handicraft this formpost even more, libcurl allows you to
599 supply your own set of custom headers to such an individual form part. You can
600 of course supply headers to as many parts as you like, but this little example
601 shows how you set headers to one specific part when you add that to the post
621 changed even if you do call curl_easy_perform(3), you may need to tell
622 curl to go back to a plain GET request if you intend to do one as your next
623 request. You force an easy handle to go back to GET by using the
628 Just setting CURLOPT_POSTFIELDS(3) to "" or NULL does *not* stop libcurl
629 from doing a POST. It just makes it POST without any data to send!
631 # Converting from deprecated form API to MIME API
633 Four rules have to be respected in building the multi-part:
637 - The multi-part is always created by a call to curl_mime_init(handle).
639 - Each part is created by a call to curl_mime_addpart(multipart).
641 - When complete, the multi-part must be bound to the easy handle using
644 Here are some example of *curl_formadd* calls to MIME API sequences:
661 Setting the last curl_mime_headers(3) argument to TRUE would have caused
662 the headers to be automatically released upon destroyed the multi-part, thus
663 saving a clean-up call to curl_slist_free_all(3).
679 "-" is not supported by curl_mime_filename(3): to read an open file, use
701 translated to two distinct parts with the same name.
760 therefore necessary to clear it for *CURLFORM_FILECONTENT* emulation.
769 CURLOPT_NOPROGRESS(3) to zero. This option is set to 1 by default.
772 instead is interesting is the ability to specify a progress callback. The
773 function pointer you pass to libcurl is then called on irregular intervals
777 to a function that matches this prototype:
788 the 'clientp' is the pointer you pass to libcurl with
793 There is basically only one thing to keep in mind when using C++ instead of C
812 What "proxy" means according to Merriam-Webster: "a person authorized to act
817 access to employees through their proxies. Network clients or user-agents ask
822 asks the proxy for it instead of trying to connect to the actual remote host
830 HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens
831 transparently, and an application may not need to know. I say "may", because
832 at times it is important to understand that all operations over an HTTP proxy
838 To tell libcurl to use a proxy at a given port number:
843 pass that information similar to this:
847 If you want to, you can specify the hostname only in the
852 it defaults to assuming an HTTP proxy):
859 libcurl automatically checks and uses a set of environment variables to know
860 what proxies to use for certain protocols. The names of the variables are
863 proxy to use when the input URL is HTTP. Following the same rule, the variable
866 proxies to be used.
872 number is used and that is most likely not the one you would like it to be.
879 To explicitly disable libcurl's checking for and using the proxy environment
880 variables, set the proxy name to "" - an empty string - with
885 SSL is for secure point-to-point connections. This involves strong encryption
886 and similar things, which effectively makes it impossible for a proxy to
888 discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask
889 the proxy to tunnel everything through without being able to check or fiddle
893 proxy for a straight connection to the target host on a specified port. This
894 is made with the HTTP request CONNECT. ("please dear proxy, connect me to that
900 organizations prevent this kind of tunneling to other destination port numbers
905 As explained above, tunneling is required for SSL to work and often even
906 restricted to the operation intended for SSL; HTTPS.
908 This is however not the only time proxy-tunneling might offer benefits to
911 As tunneling opens a direct connection from your application to the remote
912 machine, it suddenly also re-introduces the ability to do non-HTTP
919 Tell libcurl to use proxy tunneling like this:
923 In fact, there might even be times when you want to do plain HTTP operations
924 using a tunnel like this, as it then enables you to operate on the remote
925 server instead of asking the proxy to do so. libcurl does not stand in the way
932 requested URL as input, returns information to the browser on how to connect
933 to the URL. The returned information might be "DIRECT" (which means no proxy
934 should be used), "PROXY host:port" (to tell the browser where the proxy for
935 this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS
938 libcurl has no means to interpret or evaluate JavaScript and thus it does not
943 to another language and execute that.
950 - Ask your admins to stop this, for a static proxy setup or similar.
952 # Persistence Is The Way to Happiness
955 the way to go.
958 connection alive and open. A subsequent request using the same easy handle to
959 the same host might just be able to use the already open connection! This
962 Even if the connection is dropped, all connections involving SSL to the same
968 without permission to login again like on many FTP servers only allowing N
969 persons to be logged in at the same time.
971 libcurl caches DNS name resolving results, to make lookups of a previously
977 Each easy handle attempts to keep the last few connections alive for a while
978 in case they are to be used again. You can set the size of this "cache" with
983 To force your upcoming request to not use an already existing connection, you
984 can do that by setting CURLOPT_FRESH_CONNECT(3) to 1. In a similar
985 spirit, you can also forbid the upcoming request to be "lying" around and
987 CURLOPT_FORBID_REUSE(3) to 1.
991 When you use libcurl to do HTTP requests, it passes along a series of headers
992 automatically. It might be good for you to know and understand these. You can
998 the name of the server we want to talk to. This includes the port number if
1007 When doing POST requests, libcurl sets this header to "100-continue" to ask
1019 programming you may need to change the traditional HTTP (or FTP or...)
1020 manners. You may need to change words, headers or various data.
1028 is there for you. It is simple to use:
1035 keyword if you want to. You are the boss.
1039 HTTP-like protocols pass a series of headers to the server when doing the
1040 request, and you are free to pass any amount of extra headers that you
1044 struct curl_slist *headers=NULL; /* init to NULL is important */
1058 or Host: do not contain the data you want them to contain, you can replace
1069 header from being sent. For instance, if you want to completely prevent the
1070 "Accept:" header from being sent, you can disable it with code similar to
1082 when doing a non-GET HTTP operation, libcurl switches over to "chunked"
1083 upload, even though the size of the data to upload might be known. By default,
1084 libcurl usually switches over to chunked upload automatically if the upload
1089 All HTTP requests includes the version number to tell the server which version
1092 can tell libcurl to use 1.0 instead by doing something like this:
1099 you want to make, for example, your FTP transfers to behave differently.
1101 Sending custom commands to an FTP server means that you need to send the
1105 data-connection must be left to libcurl's own judgment. Also be aware that
1106 libcurl does its best to change directory to the target directory before doing
1108 confuse libcurl and then it might not attempt to transfer the file in the
1114  headers = curl_slist_append(headers, "DELE file-to-remove");
1116  /* pass the list of custom commands to the handle */
1124 If you would instead want this operation (or chain of operations) to happen
1125 _after_ the data transfer took place the option to curl_easy_setopt(3)
1129 The custom FTP commands are issued to the server in the same order they are
1130 added to the list, and if a command gets an error code returned back from the
1132 (CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE(3) to send
1136 If you set the CURLOPT_HEADER(3) to 1, you tell libcurl to get
1140 The option to enable headers or to run custom FTP commands may be useful to
1146 If you do want to list the contents of an FTP directory using your own defined
1148 default one for listing directories but you are free to pass in your idea of a
1154 the name and value to the client, and expects it to get sent back on every
1155 subsequent request to the server that matches the particular conditions
1159 In real-world cases, servers send new cookies to replace existing ones to
1160 update them. Server use cookies to "track" users and to keep "sessions".
1162 Cookies are sent from server to clients with the header Set-Cookie: and
1163 they are sent from clients to servers with the Cookie: header.
1165 To just send whatever cookie you want to a server, you can use
1166 CURLOPT_COOKIE(3) to set a cookie string like this:
1170 In many cases, that is not enough. You might want to dynamically save
1171 whatever cookies the remote server passes to you, and make sure those cookies
1174 One way to do this, is to save all headers you receive in a plain file and
1175 when you make a request, you tell libcurl to read the previous headers to
1176 figure out which cookies to use. Set the header file to read cookies from with
1184 used. Many times this is enough, and you may not have to save the cookies to
1185 disk at all. Note that the file you specify to CURLOPT_COOKIEFILE(3)
1186 does not have to exist to enable the parser, so a common way to just enable
1187 the parser and not read any cookies is to use the name of a file you know does
1199 stored in it when curl_easy_cleanup(3) is called. This enables cookies to get
1207 to haunt you. libcurl offers several different ways to customize how the
1210 libcurl can either connect to the server a second time or tell the server to
1211 connect back to it. The first option is the default and it is also what works
1213 libcurl then tells the server to open up a new port and wait for a second
1215 work it tries PASV instead. (EPSV is an extension to the original FTP spec
1219 CURLOPT_FTP_USE_EPSV(3) to zero.
1221 In some cases, you want to have the server connect back to you for the second
1224 the remote server which IP address and port number to connect to. This is made
1225 with the CURLOPT_FTPPORT(3) option. If you set it to "-", libcurl uses your
1226 system's "default IP address". If you want to use a particular IP, you can set
1227 the full IP address, a hostname to resolve to an IP address or even a local
1230 When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT
1232 behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero.
1236 In addition to support HTTP multi-part form fields, the MIME API can be used
1237 to build structured email messages and send them via SMTP or append such
1238 messages to IMAP directories.
1242 multi-part, for example to include another email message or to offer several
1243 text formats alternatives. This can be nested to any level.
1245 To build such a message, you prepare the nth-level multi-part and then include
1246 it as a source to the parent multi-part using function
1248 bound to its parent multi-part, a nth-level multi-part belongs to it and
1251 Email messages data is not supposed to be non-ascii and line length is
1252 limited: fortunately, some transfer encodings are defined by the standards to
1256 If the part data you want to send is already encoded in such a scheme, do not
1299  headers = curl_slist_append(headers, "To: you@example.com");
1306 It should be noted that appending a message to an IMAP directory requires
1307 the message size to be known prior upload. It is therefore not possible to
1315 to 1.
1317 What might be even more useful, is libcurl's ability to separate the headers
1319 different pointer to pass to the ordinary write callback by setting
1322 Or, you can set an entirely separate function to receive the headers, by using
1325 The headers are passed to the callback function one by one, and you can
1326 depend on that fact. It makes it easier for you to add custom header parsers
1342 The multi interface, on the other hand, allows your program to transfer
1343 multiple files in both directions at the same time, without forcing you to use
1346 interface allows a single-threaded application to perform the same kinds of
1351 To complicate matters somewhat more, there are even two versions of the multi
1357 To use this interface, you are better off if you first understand the basics
1358 of how to use the easy interface. The multi interface is simply a way to make
1364 multi handle with curl_multi_init(3) and add all those easy handles to
1372 now and then return control to your program. It is designed to never
1373 block. You need to keep calling the function until all transfers are
1377 file descriptors or sockets to know when to call libcurl again. This also
1378 makes it easy for you to wait and respond to actions on your own application's
1379 sockets/handles. You figure out what to select() for by using
1384 action and you then call curl_multi_perform(3) to allow libcurl to do
1385 what it wants to do. Take note that libcurl does also feature some time-out
1386 code so we advise you to never use long timeouts on select() before you call
1387 curl_multi_perform(3) again. curl_multi_timeout(3) is provided to
1394 If you want to stop the transfer of one of the easy handles in the stack, you
1395 can use curl_multi_remove_handle(3) to remove individual easy
1402 curl_multi_info_read(3) can be used to get information about completed
1403 transfers. It then returns the CURLcode for each easy transfer, to allow you
1404 to figure out success on each individual transfer.
1415 When you add easy handles to a multi handle, these easy handles automatically
1420 subsequent name resolving faster, and the connection pool that is kept to
1426 example cookies so the only way to share that is with the share interface.
1432 libcurl 7.10.3 and later have the ability to switch over to chunked
1450 This behavior was different in versions before 7.17.0, where strings had to