1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: libcurl-tutorial 5Section: 3 6Source: libcurl 7See-also: 8 - libcurl-easy (3) 9 - libcurl-errors (3) 10 - libcurl-multi (3) 11 - libcurl-url (3) 12Protocol: 13 - All 14--- 15 16# NAME 17 18libcurl-tutorial - libcurl programming tutorial 19 20# Objective 21 22This document attempts to describe the general principles and some basic 23approaches to consider when programming with libcurl. The text focuses on the 24C interface but should apply fairly well on other language bindings as well as 25they usually follow the C API pretty closely. 26 27This document refers to 'the user' as the person writing the source code that 28uses libcurl. That would probably be you or someone in your position. What is 29generally referred to as 'the program' is the collected source code that you 30write that is using libcurl for transfers. The program is outside libcurl and 31libcurl is outside of the program. 32 33To get more details on all options and functions described herein, please 34refer to their respective man pages. 35 36# Building 37 38There are many different ways to build C programs. This chapter assumes a Unix 39style build process. If you use a different build system, you can still read 40this to get general information that may apply to your environment as well. 41 42## Compiling the Program 43 44Your compiler needs to know where the libcurl headers are located. Therefore 45you must set your compiler's include path to point to the directory where you 46installed them. The 'curl-config'[3] tool can be used to get this information: 47~~~c 48 $ curl-config --cflags 49~~~ 50 51## Linking the Program with libcurl 52 53When having compiled the program, you need to link your object files to create 54a single executable. For that to succeed, you need to link with libcurl and 55possibly also with other libraries that libcurl itself depends on. Like the 56OpenSSL libraries, but even some standard OS libraries may be needed on the 57command line. To figure out which flags to use, once again the 'curl-config' 58tool comes to the rescue: 59~~~c 60 $ curl-config --libs 61~~~ 62 63## SSL or Not 64 65libcurl can be built and customized in many ways. One of the things that 66varies from different libraries and builds is the support for SSL-based 67transfers, like HTTPS and FTPS. If a supported SSL library was detected 68properly at build-time, libcurl is built with SSL support. To figure out if an 69installed libcurl has been built with SSL support enabled, use *curl-config* 70like this: 71 72~~~c 73 $ curl-config --feature 74~~~ 75 76If SSL is supported, the keyword *SSL* is written to stdout, possibly together 77with a other features that could be either on or off on for different 78libcurls. 79 80See also the "Features libcurl Provides" further down. 81 82## autoconf macro 83 84When you write your configure script to detect libcurl and setup variables 85accordingly, we offer a macro that probably does everything you need in this 86area. See docs/libcurl/libcurl.m4 file - it includes docs on how to use it. 87 88# Portable Code in a Portable World 89 90The people behind libcurl have put a considerable effort to make libcurl work 91on a large amount of different operating systems and environments. 92 93You program libcurl the same way on all platforms that libcurl runs on. There 94are only a few minor details that differ. If you just make sure to write your 95code portable enough, you can create a portable program. libcurl should not 96stop you from that. 97 98# Global Preparation 99 100The program must initialize some of the libcurl functionality globally. That 101means it should be done exactly once, no matter how many times you intend to 102use the library. Once for your program's entire life time. This is done using 103~~~c 104 curl_global_init() 105~~~ 106and it takes one parameter which is a bit pattern that tells libcurl what to 107initialize. Using *CURL_GLOBAL_ALL* makes it initialize all known internal 108sub modules, and might be a good default option. The current two bits that are 109specified are: 110 111## CURL_GLOBAL_WIN32 112 113which only does anything on Windows machines. When used on a Windows machine, 114it makes libcurl initialize the win32 socket stuff. Without having that 115initialized properly, your program cannot use sockets properly. You should 116only do this once for each application, so if your program already does this 117or of another library in use does it, you should not tell libcurl to do this 118as well. 119 120## CURL_GLOBAL_SSL 121 122which only does anything on libcurls compiled and built SSL-enabled. On these 123systems, this makes libcurl initialize the SSL library properly for this 124application. This only needs to be done once for each application so if your 125program or another library already does this, this bit should not be needed. 126 127libcurl has a default protection mechanism that detects if 128curl_global_init(3) has not been called by the time 129curl_easy_perform(3) is called and if that is the case, libcurl runs the 130function itself with a guessed bit pattern. Please note that depending solely 131on this is not considered nice nor good. 132 133When the program no longer uses libcurl, it should call 134curl_global_cleanup(3), which is the opposite of the init call. It 135performs the reversed operations to cleanup the resources the 136curl_global_init(3) call initialized. 137 138Repeated calls to curl_global_init(3) and curl_global_cleanup(3) 139should be avoided. They should only be called once each. 140 141# Features libcurl Provides 142 143It is considered best-practice to determine libcurl features at runtime rather 144than at build-time (if possible of course). By calling 145curl_version_info(3) and checking out the details of the returned 146struct, your program can figure out exactly what the currently running libcurl 147supports. 148 149# Two Interfaces 150 151libcurl first introduced the so called easy interface. All operations in the 152easy interface are prefixed with 'curl_easy'. The easy interface lets you do 153single transfers with a synchronous and blocking function call. 154 155libcurl also offers another interface that allows multiple simultaneous 156transfers in a single thread, the so called multi interface. More about that 157interface is detailed in a separate chapter further down. You still need to 158understand the easy interface first, so please continue reading for better 159understanding. 160 161# Handle the Easy libcurl 162 163To use the easy interface, you must first create yourself an easy handle. You 164need one handle for each easy session you want to perform. Basically, you 165should use one handle for every thread you plan to use for transferring. You 166must never share the same handle in multiple threads. 167 168Get an easy handle with 169~~~c 170 handle = curl_easy_init(); 171~~~ 172It returns an easy handle. Using that you proceed to the next step: setting 173up your preferred actions. A handle is just a logic entity for the upcoming 174transfer or series of transfers. 175 176You set properties and options for this handle using 177curl_easy_setopt(3). They control how the subsequent transfer or 178transfers using this handle are made. Options remain set in the handle until 179set again to something different. They are sticky. Multiple requests using the 180same handle use the same options. 181 182If you at any point would like to blank all previously set options for a 183single easy handle, you can call curl_easy_reset(3) and you can also 184make a clone of an easy handle (with all its set options) using 185curl_easy_duphandle(3). 186 187Many of the options you set in libcurl are "strings", pointers to data 188terminated with a zero byte. When you set strings with 189curl_easy_setopt(3), libcurl makes its own copy so that they do not need 190to be kept around in your application after being set[4]. 191 192One of the most basic properties to set in the handle is the URL. You set your 193preferred URL to transfer with CURLOPT_URL(3) in a manner similar to: 194 195~~~c 196 curl_easy_setopt(handle, CURLOPT_URL, "http://domain.com/"); 197~~~ 198 199Let's assume for a while that you want to receive data as the URL identifies a 200remote resource you want to get here. Since you write a sort of application 201that needs this transfer, I assume that you would like to get the data passed 202to you directly instead of simply getting it passed to stdout. So, you write 203your own function that matches this prototype: 204~~~c 205 size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); 206~~~ 207You tell libcurl to pass all data to this function by issuing a function 208similar to this: 209~~~c 210 curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data); 211~~~ 212You can control what data your callback function gets in the fourth argument 213by setting another property: 214~~~c 215 curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct); 216~~~ 217Using that property, you can easily pass local data between your application 218and the function that gets invoked by libcurl. libcurl itself does not touch 219the data you pass with CURLOPT_WRITEDATA(3). 220 221libcurl offers its own default internal callback that takes care of the data 222if you do not set the callback with CURLOPT_WRITEFUNCTION(3). It simply 223outputs the received data to stdout. You can have the default callback write 224the data to a different file handle by passing a 'FILE *' to a file opened for 225writing with the CURLOPT_WRITEDATA(3) option. 226 227Now, we need to take a step back and take a deep breath. Here is one of those 228rare platform-dependent nitpicks. Did you spot it? On some platforms[2], 229libcurl is not able to operate on file handles opened by the 230program. Therefore, if you use the default callback and pass in an open file 231handle with CURLOPT_WRITEDATA(3), libcurl crashes. You should avoid this 232to make your program run fine virtually everywhere. 233 234(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both names still 235work and do the same thing). 236 237If you are using libcurl as a win32 DLL, you MUST use the 238CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or experience 239crashes. 240 241There are of course many more options you can set, and we get back to a few of 242them later. Let's instead continue to the actual transfer: 243 244~~~c 245 success = curl_easy_perform(handle); 246~~~ 247 248curl_easy_perform(3) connects to the remote site, does the necessary commands 249and performs the transfer. Whenever it receives data, it calls the callback 250function we previously set. The function may get one byte at a time, or it may 251get many kilobytes at once. libcurl delivers as much as possible as often as 252possible. Your callback function should return the number of bytes it "took 253care of". If that is not the same amount of bytes that was passed to it, 254libcurl aborts the operation and returns with an error code. 255 256When the transfer is complete, the function returns a return code that informs 257you if it succeeded in its mission or not. If a return code is not enough for 258you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer of 259yours where it stores a human readable error message as well. 260 261If you then want to transfer another file, the handle is ready to be used 262again. It is even preferred and encouraged that you reuse an existing handle 263if you intend to make another transfer. libcurl then attempts to reuse a 264previous connection. 265 266For some protocols, downloading a file can involve a complicated process of 267logging in, setting the transfer mode, changing the current directory and 268finally transferring the file data. libcurl takes care of all that 269complication for you. Given simply the URL to a file, libcurl takes care of 270all the details needed to get the file moved from one machine to another. 271 272# Multi-threading Issues 273 274libcurl is thread safe but there are a few exceptions. Refer to 275libcurl-thread(3) for more information. 276 277# When It does not Work 278 279There are times when the transfer fails for some reason. You might have set 280the wrong libcurl option or misunderstood what the libcurl option actually 281does, or the remote server might return non-standard replies that confuse the 282library which then confuses your program. 283 284There is one golden rule when these things occur: set the 285CURLOPT_VERBOSE(3) option to 1. it causes the library to spew out the 286entire protocol details it sends, some internal info and some received 287protocol data as well (especially when using FTP). If you are using HTTP, 288adding the headers in the received output to study is also a clever way to get 289a better understanding why the server behaves the way it does. Include headers 290in the normal body output with CURLOPT_HEADER(3) set 1. 291 292Of course, there are bugs left. We need to know about them to be able to fix 293them, so we are quite dependent on your bug reports. When you do report 294suspected bugs in libcurl, please include as many details as you possibly can: 295a protocol dump that CURLOPT_VERBOSE(3) produces, library version, as 296much as possible of your code that uses libcurl, operating system name and 297version, compiler name and version etc. 298 299If CURLOPT_VERBOSE(3) is not enough, you increase the level of debug 300data your application receive by using the CURLOPT_DEBUGFUNCTION(3). 301 302Getting some in-depth knowledge about the protocols involved is never wrong, 303and if you are trying to do funny things, you might understand libcurl and how 304to use it better if you study the appropriate RFC documents at least briefly. 305 306# Upload Data to a Remote Site 307 308libcurl tries to keep a protocol independent approach to most transfers, thus 309uploading to a remote FTP site is similar to uploading data to an HTTP server 310with a PUT request. 311 312Of course, first you either create an easy handle or you reuse one existing 313one. Then you set the URL to operate on just like before. This is the remote 314URL, that we now upload. 315 316Since we write an application, we most likely want libcurl to get the upload 317data by asking us for it. To make it do that, we set the read callback and the 318custom pointer libcurl passes to our read callback. The read callback should 319have a prototype similar to: 320~~~c 321 size_t function(char *bufptr, size_t size, size_t nitems, void *userp); 322~~~ 323Where *bufptr* is the pointer to a buffer we fill in with data to upload 324and *size*nitems* is the size of the buffer and therefore also the maximum 325amount of data we can return to libcurl in this call. The *userp* pointer 326is the custom pointer we set to point to a struct of ours to pass private data 327between the application and the callback. 328~~~c 329 curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function); 330 331 curl_easy_setopt(handle, CURLOPT_READDATA, &filedata); 332~~~ 333Tell libcurl that we want to upload: 334~~~c 335 curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); 336~~~ 337A few protocols do not behave properly when uploads are done without any prior 338knowledge of the expected file size. So, set the upload file size using the 339CURLOPT_INFILESIZE_LARGE(3) for all known file sizes like this[1]: 340 341~~~c 342 /* in this example, file_size must be an curl_off_t variable */ 343 curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size); 344~~~ 345 346When you call curl_easy_perform(3) this time, it performs all the 347necessary operations and when it has invoked the upload it calls your supplied 348callback to get the data to upload. The program should return as much data as 349possible in every invoke, as that is likely to make the upload perform as fast 350as possible. The callback should return the number of bytes it wrote in the 351buffer. Returning 0 signals the end of the upload. 352 353# Passwords 354 355Many protocols use or even require that username and password are provided 356to be able to download or upload the data of your choice. libcurl offers 357several ways to specify them. 358 359Most protocols support that you specify the name and password in the URL 360itself. libcurl detects this and use them accordingly. This is written like 361this: 362~~~c 363 protocol://user:password@example.com/path/ 364~~~ 365If you need any odd letters in your username or password, you should enter 366them URL encoded, as %XX where XX is a two-digit hexadecimal number. 367 368libcurl also provides options to set various passwords. The username and 369password as shown embedded in the URL can instead get set with the 370CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a 371char * to a string in the format "user:password". In a manner like this: 372 373~~~c 374 curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); 375~~~ 376 377Another case where name and password might be needed at times, is for those 378users who need to authenticate themselves to a proxy they use. libcurl offers 379another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite similar 380to the CURLOPT_USERPWD(3) option like this: 381 382~~~c 383 curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); 384~~~ 385 386There is a long time Unix "standard" way of storing FTP usernames and 387passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks 388the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries 389"_netrc" as name). The file should be made private so that only the user may 390read it (see also the "Security Considerations" chapter), as it might contain 391the password in plain text. libcurl has the ability to use this file to figure 392out what set of username and password to use for a particular host. As an 393extension to the normal functionality, libcurl also supports this file for 394non-FTP protocols such as HTTP. To make curl use this file, use the 395CURLOPT_NETRC(3) option: 396 397~~~c 398 curl_easy_setopt(handle, CURLOPT_NETRC, 1L); 399~~~ 400 401A basic example of how such a .netrc file may look like: 402 403~~~c 404 machine myhost.mydomain.com 405 login userlogin 406 password secretword 407~~~ 408 409All these examples have been cases where the password has been optional, or 410at least you could leave it out and have libcurl attempt to do its job 411without it. There are times when the password is not optional, like when 412you are using an SSL private key for secure transfers. 413 414To pass the known private key password to libcurl: 415~~~c 416 curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword"); 417~~~ 418 419# HTTP Authentication 420 421The previous chapter showed how to set username and password for getting URLs 422that require authentication. When using the HTTP protocol, there are many 423different ways a client can provide those credentials to the server and you 424can control which way libcurl uses them. The default HTTP authentication 425method is called 'Basic', which is sending the name and password in clear-text 426in the HTTP request, base64-encoded. This is insecure. 427 428At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, 429Negotiate (SPNEGO). You can tell libcurl which one to use with 430CURLOPT_HTTPAUTH(3) as in: 431 432~~~c 433 curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); 434 435~~~ 436 437When you send authentication to a proxy, you can also set authentication type 438the same way but instead with CURLOPT_PROXYAUTH(3): 439 440~~~c 441 curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); 442~~~ 443 444Both these options allow you to set multiple types (by ORing them together), 445to make libcurl pick the most secure one out of the types the server/proxy 446claims to support. This method does however add a round-trip since libcurl 447must first ask the server what it supports: 448 449~~~c 450 curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC); 451~~~ 452 453For convenience, you can use the *CURLAUTH_ANY* define (instead of a list with 454specific types) which allows libcurl to use whatever method it wants. 455 456When asking for multiple types, libcurl picks the available one it considers 457"best" in its own internal order of preference. 458 459# HTTP POSTing 460 461We get many questions regarding how to issue HTTP POSTs with libcurl the 462proper way. This chapter thus includes examples using both different versions 463of HTTP POST that libcurl supports. 464 465The first version is the simple POST, the most common version, that most HTML 466pages using the \<form\> tag uses. We provide a pointer to the data and tell 467libcurl to post it all to the remote site: 468 469~~~c 470 char *data="name=daniel&project=curl"; 471 curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data); 472 curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/"); 473 474 curl_easy_perform(handle); /* post away! */ 475~~~ 476 477Simple enough, huh? Since you set the POST options with the 478CURLOPT_POSTFIELDS(3), this automatically switches the handle to use 479POST in the upcoming request. 480 481What if you want to post binary data that also requires you to set the 482Content-Type: header of the post? Well, binary posts prevent libcurl from being 483able to do strlen() on the data to figure out the size, so therefore we must 484tell libcurl the size of the post data. Setting headers in libcurl requests are 485done in a generic way, by building a list of our own headers and then passing 486that list to libcurl. 487 488~~~c 489 struct curl_slist *headers=NULL; 490 headers = curl_slist_append(headers, "Content-Type: text/xml"); 491 492 /* post binary data */ 493 curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr); 494 495 /* set the size of the postfields data */ 496 curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L); 497 498 /* pass our list of custom made headers */ 499 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); 500 501 curl_easy_perform(handle); /* post away! */ 502 503 curl_slist_free_all(headers); /* free the header list */ 504~~~ 505 506While the simple examples above cover the majority of all cases where HTTP 507POST operations are required, they do not do multi-part formposts. Multi-part 508formposts were introduced as a better way to post (possibly large) binary data 509and were first documented in the RFC 1867 (updated in RFC 2388). They are 510called multi-part because they are built by a chain of parts, each part being 511a single unit of data. Each part has its own name and contents. You can in 512fact create and post a multi-part formpost with the regular libcurl POST 513support described above, but that would require that you build a formpost 514yourself and provide to libcurl. 515 516To make that easier, libcurl provides a MIME API consisting in several 517functions: using those, you can create and fill a multi-part form. Function 518curl_mime_init(3) creates a multi-part body; you can then append new parts 519to a multi-part body using curl_mime_addpart(3). 520 521There are three possible data sources for a part: memory using 522curl_mime_data(3), file using curl_mime_filedata(3) and user-defined data 523read callback using curl_mime_data_cb(3). curl_mime_name(3) sets a part's 524(i.e.: form field) name, while curl_mime_filename(3) fills in the remote 525filename. With curl_mime_type(3), you can tell the MIME type of a part, 526curl_mime_headers(3) allows defining the part's headers. When a multi-part 527body is no longer needed, you can destroy it using curl_mime_free(3). 528 529The following example sets two simple text parts with plain textual contents, 530and then a file with binary contents and uploads the whole thing. 531 532~~~c 533 curl_mime *multipart = curl_mime_init(handle); 534 curl_mimepart *part = curl_mime_addpart(multipart); 535 curl_mime_name(part, "name"); 536 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); 537 part = curl_mime_addpart(multipart); 538 curl_mime_name(part, "project"); 539 curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); 540 part = curl_mime_addpart(multipart); 541 curl_mime_name(part, "logotype-image"); 542 curl_mime_filedata(part, "curl.png"); 543 544 /* Set the form info */ 545 curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart); 546 547 curl_easy_perform(handle); /* post away! */ 548 549 /* free the post data again */ 550 curl_mime_free(multipart); 551~~~ 552 553To post multiple files for a single form field, you must supply each file in 554a separate part, all with the same field name. Although function 555curl_mime_subparts(3) implements nested multi-parts, this way of 556multiple files posting is deprecated by RFC 7578, chapter 4.3. 557 558To set the data source from an already opened FILE pointer, use: 559 560~~~c 561 curl_mime_data_cb(part, filesize, (curl_read_callback) fread, 562 (curl_seek_callback) fseek, NULL, filepointer); 563~~~ 564 565A deprecated curl_formadd(3) function is still supported in libcurl. 566It should however not be used anymore for new designs and programs using it 567ought to be converted to the MIME API. It is however described here as an 568aid to conversion. 569 570Using *curl_formadd*, you add parts to the form. When you are done adding 571parts, you post the whole form. 572 573The MIME API example above is expressed as follows using this function: 574 575~~~c 576 struct curl_httppost *post=NULL; 577 struct curl_httppost *last=NULL; 578 curl_formadd(&post, &last, 579 CURLFORM_COPYNAME, "name", 580 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); 581 curl_formadd(&post, &last, 582 CURLFORM_COPYNAME, "project", 583 CURLFORM_COPYCONTENTS, "curl", CURLFORM_END); 584 curl_formadd(&post, &last, 585 CURLFORM_COPYNAME, "logotype-image", 586 CURLFORM_FILECONTENT, "curl.png", CURLFORM_END); 587 588 /* Set the form info */ 589 curl_easy_setopt(handle, CURLOPT_HTTPPOST, post); 590 591 curl_easy_perform(handle); /* post away! */ 592 593 /* free the post data again */ 594 curl_formfree(post); 595~~~ 596 597Multipart formposts are chains of parts using MIME-style separators and 598headers. It means that each one of these separate parts get a few headers set 599that describe the individual content-type, size etc. To enable your 600application to handicraft this formpost even more, libcurl allows you to 601supply your own set of custom headers to such an individual form part. You can 602of course supply headers to as many parts as you like, but this little example 603shows how you set headers to one specific part when you add that to the post 604handle: 605 606~~~c 607 struct curl_slist *headers=NULL; 608 headers = curl_slist_append(headers, "Content-Type: text/xml"); 609 610 curl_formadd(&post, &last, 611 CURLFORM_COPYNAME, "logotype-image", 612 CURLFORM_FILECONTENT, "curl.xml", 613 CURLFORM_CONTENTHEADER, headers, 614 CURLFORM_END); 615 616 curl_easy_perform(handle); /* post away! */ 617 618 curl_formfree(post); /* free post */ 619 curl_slist_free_all(headers); /* free custom header list */ 620~~~ 621 622Since all options on an easy handle are "sticky", they remain the same until 623changed even if you do call curl_easy_perform(3), you may need to tell 624curl to go back to a plain GET request if you intend to do one as your next 625request. You force an easy handle to go back to GET by using the 626CURLOPT_HTTPGET(3) option: 627~~~c 628 curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L); 629~~~ 630Just setting CURLOPT_POSTFIELDS(3) to "" or NULL does *not* stop libcurl 631from doing a POST. It just makes it POST without any data to send! 632 633# Converting from deprecated form API to MIME API 634 635Four rules have to be respected in building the multi-part: 636 637- The easy handle must be created before building the multi-part. 638 639- The multi-part is always created by a call to curl_mime_init(handle). 640 641- Each part is created by a call to curl_mime_addpart(multipart). 642 643- When complete, the multi-part must be bound to the easy handle using 644CURLOPT_MIMEPOST(3) instead of CURLOPT_HTTPPOST(3). 645 646Here are some example of *curl_formadd* calls to MIME API sequences: 647 648~~~c 649 curl_formadd(&post, &last, 650 CURLFORM_COPYNAME, "id", 651 CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); 652 CURLFORM_CONTENTHEADER, headers, 653 CURLFORM_END); 654~~~ 655becomes: 656~~~c 657 part = curl_mime_addpart(multipart); 658 curl_mime_name(part, "id"); 659 curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); 660 curl_mime_headers(part, headers, FALSE); 661~~~ 662 663Setting the last curl_mime_headers(3) argument to TRUE would have caused 664the headers to be automatically released upon destroyed the multi-part, thus 665saving a clean-up call to curl_slist_free_all(3). 666 667~~~c 668 curl_formadd(&post, &last, 669 CURLFORM_PTRNAME, "logotype-image", 670 CURLFORM_FILECONTENT, "-", 671 CURLFORM_END); 672~~~ 673becomes: 674~~~c 675 part = curl_mime_addpart(multipart); 676 curl_mime_name(part, "logotype-image"); 677 curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin); 678~~~ 679 680curl_mime_name(3) always copies the field name. The special filename "-" is 681not supported by curl_mime_filename(3): to read an open file, use a callback 682source using fread(). The transfer is be chunk-encoded since the data size is 683unknown. 684 685~~~c 686 curl_formadd(&post, &last, 687 CURLFORM_COPYNAME, "datafile[]", 688 CURLFORM_FILE, "file1", 689 CURLFORM_FILE, "file2", 690 CURLFORM_END); 691~~~ 692becomes: 693~~~c 694 part = curl_mime_addpart(multipart); 695 curl_mime_name(part, "datafile[]"); 696 curl_mime_filedata(part, "file1"); 697 part = curl_mime_addpart(multipart); 698 curl_mime_name(part, "datafile[]"); 699 curl_mime_filedata(part, "file2"); 700~~~ 701 702The deprecated multipart/mixed implementation of multiple files field is 703translated to two distinct parts with the same name. 704 705~~~c 706 curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc); 707 curl_formadd(&post, &last, 708 CURLFORM_COPYNAME, "stream", 709 CURLFORM_STREAM, arg, 710 CURLFORM_CONTENTLEN, (curl_off_t) datasize, 711 CURLFORM_FILENAME, "archive.zip", 712 CURLFORM_CONTENTTYPE, "application/zip", 713 CURLFORM_END); 714~~~ 715becomes: 716~~~c 717 part = curl_mime_addpart(multipart); 718 curl_mime_name(part, "stream"); 719 curl_mime_data_cb(part, (curl_off_t) datasize, 720 myreadfunc, NULL, NULL, arg); 721 curl_mime_filename(part, "archive.zip"); 722 curl_mime_type(part, "application/zip"); 723~~~ 724 725CURLOPT_READFUNCTION(3) callback is not used: it is replace by directly 726setting the part source data from the callback read function. 727 728~~~c 729 curl_formadd(&post, &last, 730 CURLFORM_COPYNAME, "memfile", 731 CURLFORM_BUFFER, "memfile.bin", 732 CURLFORM_BUFFERPTR, databuffer, 733 CURLFORM_BUFFERLENGTH, (long) sizeof databuffer, 734 CURLFORM_END); 735~~~ 736becomes: 737~~~c 738 part = curl_mime_addpart(multipart); 739 curl_mime_name(part, "memfile"); 740 curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer); 741 curl_mime_filename(part, "memfile.bin"); 742~~~ 743 744curl_mime_data(3) always copies the initial data: data buffer is thus 745free for immediate reuse. 746 747~~~c 748 curl_formadd(&post, &last, 749 CURLFORM_COPYNAME, "message", 750 CURLFORM_FILECONTENT, "msg.txt", 751 CURLFORM_END); 752~~~ 753becomes: 754~~~c 755 part = curl_mime_addpart(multipart); 756 curl_mime_name(part, "message"); 757 curl_mime_filedata(part, "msg.txt"); 758 curl_mime_filename(part, NULL); 759~~~ 760 761Use of curl_mime_filedata(3) sets the remote filename as a side effect: it is 762therefore necessary to clear it for *CURLFORM_FILECONTENT* emulation. 763 764# Showing Progress 765 766For historical and traditional reasons, libcurl has a built-in progress meter 767that can be switched on and then makes it present a progress meter in your 768terminal. 769 770Switch on the progress meter by, oddly enough, setting 771CURLOPT_NOPROGRESS(3) to zero. This option is set to 1 by default. 772 773For most applications however, the built-in progress meter is useless and what 774instead is interesting is the ability to specify a progress callback. The 775function pointer you pass to libcurl is then called on irregular intervals 776with information about the current transfer. 777 778Set the progress callback by using CURLOPT_PROGRESSFUNCTION(3). Pass a pointer 779to a function that matches this prototype: 780 781~~~c 782 int progress_callback(void *clientp, 783 double dltotal, 784 double dlnow, 785 double ultotal, 786 double ulnow); 787~~~ 788 789If any of the input arguments is unknown, a 0 is provided. The first argument, 790the 'clientp' is the pointer you pass to libcurl with 791CURLOPT_PROGRESSDATA(3). libcurl does not touch it. 792 793# libcurl with C++ 794 795There is basically only one thing to keep in mind when using C++ instead of C 796when interfacing libcurl: 797 798The callbacks CANNOT be non-static class member functions 799 800Example C++ code: 801 802~~~c 803class AClass { 804 static size_t write_data(void *ptr, size_t size, size_t nmemb, 805 void *ourpointer) 806 { 807 /* do what you want with the data */ 808 } 809 } 810~~~ 811 812# Proxies 813 814What "proxy" means according to Merriam-Webster: "a person authorized to act 815for another" but also "the agency, function, or office of a deputy who acts as 816a substitute for another". 817 818Proxies are exceedingly common these days. Companies often only offer Internet 819access to employees through their proxies. Network clients or user-agents ask 820the proxy for documents, the proxy does the actual request and then it returns 821them. 822 823libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl 824asks the proxy for it instead of trying to connect to the actual remote host 825identified in the URL. 826 827If you are using a SOCKS proxy, you may find that libcurl does not quite support 828all operations through it. 829 830For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain 831restrictions on what can actually happen. A requested URL that might not be a 832HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens 833transparently, and an application may not need to know. I say "may", because 834at times it is important to understand that all operations over an HTTP proxy 835use the HTTP protocol. For example, you cannot invoke your own custom FTP 836commands or even proper FTP directory listings. 837 838## Proxy Options 839 840To tell libcurl to use a proxy at a given port number: 841~~~c 842 curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080"); 843~~~ 844Some proxies require user authentication before allowing a request, and you 845pass that information similar to this: 846~~~c 847 curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password"); 848~~~ 849If you want to, you can specify the hostname only in the 850CURLOPT_PROXY(3) option, and set the port number separately with 851CURLOPT_PROXYPORT(3). 852 853Tell libcurl what kind of proxy it is with CURLOPT_PROXYTYPE(3) (if not, 854it defaults to assuming an HTTP proxy): 855~~~c 856 curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); 857~~~ 858 859## Environment Variables 860 861libcurl automatically checks and uses a set of environment variables to know 862what proxies to use for certain protocols. The names of the variables are 863following an old tradition and are built up as "[protocol]_proxy" (note the 864lower casing). Which makes the variable 'http_proxy' checked for a name of a 865proxy to use when the input URL is HTTP. Following the same rule, the variable 866named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP 867proxies, the different names of the variables simply allows different HTTP 868proxies to be used. 869 870The proxy environment variable contents should be in the format 871"[protocol://][user:password@]machine[:port]". Where the protocol:// part 872specifies which type of proxy it is, and the optional port number specifies on 873which port the proxy operates. If not specified, the internal default port 874number is used and that is most likely not the one you would like it to be. 875 876There are two special environment variables. 'all_proxy' is what sets proxy 877for any URL in case the protocol specific variable was not set, and 'no_proxy' 878defines a list of hosts that should not use a proxy even though a variable may 879say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts. 880 881To explicitly disable libcurl's checking for and using the proxy environment 882variables, set the proxy name to "" - an empty string - with 883CURLOPT_PROXY(3). 884 885## SSL and Proxies 886 887SSL is for secure point-to-point connections. This involves strong encryption 888and similar things, which effectively makes it impossible for a proxy to 889operate as a "man in between" which the proxy's task is, as previously 890discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask 891the proxy to tunnel everything through without being able to check or fiddle 892with the traffic. 893 894Opening an SSL connection over an HTTP proxy is therefore a matter of asking the 895proxy for a straight connection to the target host on a specified port. This 896is made with the HTTP request CONNECT. ("please dear proxy, connect me to that 897remote host"). 898 899Because of the nature of this operation, where the proxy has no idea what kind 900of data that is passed in and out through this tunnel, this breaks some of the 901few advantages that come from using a proxy, such as caching. Many 902organizations prevent this kind of tunneling to other destination port numbers 903than 443 (which is the default HTTPS port number). 904 905## Tunneling Through Proxy 906 907As explained above, tunneling is required for SSL to work and often even 908restricted to the operation intended for SSL; HTTPS. 909 910This is however not the only time proxy-tunneling might offer benefits to 911you or your application. 912 913As tunneling opens a direct connection from your application to the remote 914machine, it suddenly also re-introduces the ability to do non-HTTP 915operations over an HTTP proxy. You can in fact use things such as FTP 916upload or FTP custom commands this way. 917 918Again, this is often prevented by the administrators of proxies and is 919rarely allowed. 920 921Tell libcurl to use proxy tunneling like this: 922~~~c 923 curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L); 924~~~ 925In fact, there might even be times when you want to do plain HTTP operations 926using a tunnel like this, as it then enables you to operate on the remote 927server instead of asking the proxy to do so. libcurl does not stand in the way 928for such innovative actions either! 929 930## Proxy Auto-Config 931 932Netscape first came up with this. It is basically a webpage (usually using a 933.pac extension) with a JavaScript that when executed by the browser with the 934requested URL as input, returns information to the browser on how to connect 935to the URL. The returned information might be "DIRECT" (which means no proxy 936should be used), "PROXY host:port" (to tell the browser where the proxy for 937this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS 938proxy). 939 940libcurl has no means to interpret or evaluate JavaScript and thus it does not 941support this. If you get yourself in a position where you face this nasty 942invention, the following advice have been mentioned and used in the past: 943 944- Depending on the JavaScript complexity, write up a script that translates it 945to another language and execute that. 946 947- Read the JavaScript code and rewrite the same logic in another language. 948 949- Implement a JavaScript interpreter; people have successfully used the 950Mozilla JavaScript engine in the past. 951 952- Ask your admins to stop this, for a static proxy setup or similar. 953 954# Persistence Is The Way to Happiness 955 956Re-cycling the same easy handle several times when doing multiple requests is 957the way to go. 958 959After each single curl_easy_perform(3) operation, libcurl keeps the 960connection alive and open. A subsequent request using the same easy handle to 961the same host might just be able to use the already open connection! This 962reduces network impact a lot. 963 964Even if the connection is dropped, all connections involving SSL to the same 965host again, benefit from libcurl's session ID cache that drastically reduces 966re-connection time. 967 968FTP connections that are kept alive save a lot of time, as the command- 969response round-trips are skipped, and also you do not risk getting blocked 970without permission to login again like on many FTP servers only allowing N 971persons to be logged in at the same time. 972 973libcurl caches DNS name resolving results, to make lookups of a previously 974looked up name a lot faster. 975 976Other interesting details that improve performance for subsequent requests 977may also be added in the future. 978 979Each easy handle attempts to keep the last few connections alive for a while 980in case they are to be used again. You can set the size of this "cache" with 981the CURLOPT_MAXCONNECTS(3) option. Default is 5. There is rarely any 982point in changing this value, and if you think of changing this it is often 983just a matter of thinking again. 984 985To force your upcoming request to not use an already existing connection, you 986can do that by setting CURLOPT_FRESH_CONNECT(3) to 1. In a similar 987spirit, you can also forbid the upcoming request to be "lying" around and 988possibly get reused after the request by setting 989CURLOPT_FORBID_REUSE(3) to 1. 990 991# HTTP Headers Used by libcurl 992 993When you use libcurl to do HTTP requests, it passes along a series of headers 994automatically. It might be good for you to know and understand these. You can 995replace or remove them by using the CURLOPT_HTTPHEADER(3) option. 996 997## Host 998 999This header is required by HTTP 1.1 and even many 1.0 servers and should be 1000the name of the server we want to talk to. This includes the port number if 1001anything but default. 1002 1003## Accept 1004 1005"*/*" 1006 1007## Expect 1008 1009When doing POST requests, libcurl sets this header to "100-continue" to ask 1010the server for an "OK" message before it proceeds with sending the data part 1011of the post. If the posted data amount is deemed "small", libcurl does not use 1012this header. 1013 1014# Customizing Operations 1015 1016There is an ongoing development today where more and more protocols are built 1017upon HTTP for transport. This has obvious benefits as HTTP is a tested and 1018reliable protocol that is widely deployed and has excellent proxy-support. 1019 1020When you use one of these protocols, and even when doing other kinds of 1021programming you may need to change the traditional HTTP (or FTP or...) 1022manners. You may need to change words, headers or various data. 1023 1024libcurl is your friend here too. 1025 1026## CURLOPT_CUSTOMREQUEST 1027 1028If just changing the actual HTTP request keyword is what you want, like when 1029GET, HEAD or POST is not good enough for you, CURLOPT_CUSTOMREQUEST(3) 1030is there for you. It is simple to use: 1031 1032~~~c 1033curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); 1034~~~ 1035 1036When using the custom request, you change the request keyword of the actual 1037request you are performing. Thus, by default you make a GET request but you 1038can also make a POST operation (as described before) and then replace the POST 1039keyword if you want to. You are the boss. 1040 1041## Modify Headers 1042 1043HTTP-like protocols pass a series of headers to the server when doing the 1044request, and you are free to pass any amount of extra headers that you 1045think fit. Adding headers is this easy: 1046 1047~~~c 1048struct curl_slist *headers=NULL; /* init to NULL is important */ 1049 1050headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); 1051headers = curl_slist_append(headers, "X-silly-content: yes"); 1052 1053/* pass our list of custom made headers */ 1054curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); 1055 1056curl_easy_perform(handle); /* transfer http */ 1057 1058curl_slist_free_all(headers); /* free the header list */ 1059~~~ 1060 1061... and if you think some of the internally generated headers, such as Accept: 1062or Host: do not contain the data you want them to contain, you can replace 1063them by simply setting them too: 1064 1065~~~c 1066headers = curl_slist_append(headers, "Accept: Agent-007"); 1067headers = curl_slist_append(headers, "Host: munged.host.line"); 1068~~~ 1069 1070## Delete Headers 1071 1072If you replace an existing header with one with no contents, you prevent the 1073header from being sent. For instance, if you want to completely prevent the 1074"Accept:" header from being sent, you can disable it with code similar to 1075this: 1076 1077 headers = curl_slist_append(headers, "Accept:"); 1078 1079Both replacing and canceling internal headers should be done with careful 1080consideration and you should be aware that you may violate the HTTP protocol 1081when doing so. 1082 1083## Enforcing chunked transfer-encoding 1084 1085By making sure a request uses the custom header "Transfer-Encoding: chunked" 1086when doing a non-GET HTTP operation, libcurl switches over to "chunked" 1087upload, even though the size of the data to upload might be known. By default, 1088libcurl usually switches over to chunked upload automatically if the upload 1089data size is unknown. 1090 1091## HTTP Version 1092 1093All HTTP requests includes the version number to tell the server which version 1094we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like 1095getting 1.1-requests and when dealing with stubborn old things like that, you 1096can tell libcurl to use 1.0 instead by doing something like this: 1097 1098 curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); 1099 1100## FTP Custom Commands 1101 1102Not all protocols are HTTP-like, and thus the above may not help you when 1103you want to make, for example, your FTP transfers to behave differently. 1104 1105Sending custom commands to an FTP server means that you need to send the 1106commands exactly as the FTP server expects them (RFC 959 is a good guide 1107here), and you can only use commands that work on the control-connection 1108alone. All kinds of commands that require data interchange and thus need a 1109data-connection must be left to libcurl's own judgment. Also be aware that 1110libcurl does its best to change directory to the target directory before doing 1111any transfer, so if you change directory (with CWD or similar) you might 1112confuse libcurl and then it might not attempt to transfer the file in the 1113correct remote directory. 1114 1115A little example that deletes a given file before an operation: 1116 1117~~~c 1118 headers = curl_slist_append(headers, "DELE file-to-remove"); 1119 1120 /* pass the list of custom commands to the handle */ 1121 curl_easy_setopt(handle, CURLOPT_QUOTE, headers); 1122 1123 curl_easy_perform(handle); /* transfer ftp data! */ 1124 1125 curl_slist_free_all(headers); /* free the header list */ 1126~~~ 1127 1128If you would instead want this operation (or chain of operations) to happen 1129_after_ the data transfer took place the option to curl_easy_setopt(3) 1130would instead be called CURLOPT_POSTQUOTE(3) and used the exact same 1131way. 1132 1133The custom FTP commands are issued to the server in the same order they are 1134added to the list, and if a command gets an error code returned back from the 1135server, no more commands are issued and libcurl bails out with an error code 1136(CURLE_QUOTE_ERROR). Note that if you use CURLOPT_QUOTE(3) to send 1137commands before a transfer, no transfer actually takes place when a quote 1138command has failed. 1139 1140If you set the CURLOPT_HEADER(3) to 1, you tell libcurl to get 1141information about the target file and output "headers" about it. The headers 1142are in "HTTP-style", looking like they do in HTTP. 1143 1144The option to enable headers or to run custom FTP commands may be useful to 1145combine with CURLOPT_NOBODY(3). If this option is set, no actual file 1146content transfer is performed. 1147 1148## FTP Custom CURLOPT_CUSTOMREQUEST 1149 1150If you do want to list the contents of an FTP directory using your own defined 1151FTP command, CURLOPT_CUSTOMREQUEST(3) does just that. "NLST" is the default 1152one for listing directories but you are free to pass in your idea of a good 1153alternative. 1154 1155# Cookies Without Chocolate Chips 1156 1157In the HTTP sense, a cookie is a name with an associated value. A server sends 1158the name and value to the client, and expects it to get sent back on every 1159subsequent request to the server that matches the particular conditions set. 1160The conditions include that the domain name and path match and that the cookie 1161has not become too old. 1162 1163In real-world cases, servers send new cookies to replace existing ones to 1164update them. Server use cookies to "track" users and to keep "sessions". 1165 1166Cookies are sent from server to clients with the header Set-Cookie: and 1167they are sent from clients to servers with the Cookie: header. 1168 1169To just send whatever cookie you want to a server, you can use 1170CURLOPT_COOKIE(3) to set a cookie string like this: 1171 1172~~~c 1173 curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); 1174~~~ 1175 1176In many cases, that is not enough. You might want to dynamically save whatever 1177cookies the remote server passes to you, and make sure those cookies are then 1178used accordingly on later requests. 1179 1180One way to do this, is to save all headers you receive in a plain file and 1181when you make a request, you tell libcurl to read the previous headers to 1182figure out which cookies to use. Set the header file to read cookies from with 1183CURLOPT_COOKIEFILE(3). 1184 1185The CURLOPT_COOKIEFILE(3) option also automatically enables the cookie 1186parser in libcurl. Until the cookie parser is enabled, libcurl does not parse 1187or understand incoming cookies and they are just be ignored. However, when the 1188parser is enabled the cookies are understood and the cookies are kept in 1189memory and used properly in subsequent requests when the same handle is 1190used. Many times this is enough, and you may not have to save the cookies to 1191disk at all. Note that the file you specify to CURLOPT_COOKIEFILE(3) 1192does not have to exist to enable the parser, so a common way to just enable 1193the parser and not read any cookies is to use the name of a file you know does 1194not exist. 1195 1196If you would rather use existing cookies that you have previously received 1197with your Netscape or Mozilla browsers, you can make libcurl use that cookie 1198file as input. The CURLOPT_COOKIEFILE(3) is used for that too, as 1199libcurl automatically finds out what kind of file it is and acts accordingly. 1200 1201Perhaps the most advanced cookie operation libcurl offers, is saving the 1202entire internal cookie state back into a Netscape/Mozilla formatted cookie 1203file. We call that the cookie-jar. When you set a filename with 1204CURLOPT_COOKIEJAR(3), that filename is created and all received cookies get 1205stored in it when curl_easy_cleanup(3) is called. This enables cookies to get 1206passed on properly between multiple handles without any information getting 1207lost. 1208 1209# FTP Peculiarities We Need 1210 1211FTP transfers use a second TCP/IP connection for the data transfer. This is 1212usually a fact you can forget and ignore but at times this detail comes back 1213to haunt you. libcurl offers several different ways to customize how the 1214second connection is being made. 1215 1216libcurl can either connect to the server a second time or tell the server to 1217connect back to it. The first option is the default and it is also what works 1218best for all the people behind firewalls, NATs or IP-masquerading setups. 1219libcurl then tells the server to open up a new port and wait for a second 1220connection. This is by default attempted with EPSV first, and if that does not 1221work it tries PASV instead. (EPSV is an extension to the original FTP spec 1222and does not exist nor work on all FTP servers.) 1223 1224You can prevent libcurl from first trying the EPSV command by setting 1225CURLOPT_FTP_USE_EPSV(3) to zero. 1226 1227In some cases, you want to have the server connect back to you for the second 1228connection. This might be when the server is perhaps behind a firewall or 1229something and only allows connections on a single port. libcurl then informs 1230the remote server which IP address and port number to connect to. This is made 1231with the CURLOPT_FTPPORT(3) option. If you set it to "-", libcurl uses your 1232system's "default IP address". If you want to use a particular IP, you can set 1233the full IP address, a hostname to resolve to an IP address or even a local 1234network interface name that libcurl gets the IP address from. 1235 1236When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT 1237before trying PORT, as they work with more protocols. You can disable this 1238behavior by setting CURLOPT_FTP_USE_EPRT(3) to zero. 1239 1240# MIME API revisited for SMTP and IMAP 1241 1242In addition to support HTTP multi-part form fields, the MIME API can be used 1243to build structured email messages and send them via SMTP or append such 1244messages to IMAP directories. 1245 1246A structured email message may contain several parts: some are displayed 1247inline by the MUA, some are attachments. Parts can also be structured as 1248multi-part, for example to include another email message or to offer several 1249text formats alternatives. This can be nested to any level. 1250 1251To build such a message, you prepare the nth-level multi-part and then include 1252it as a source to the parent multi-part using function 1253curl_mime_subparts(3). Once it has been 1254bound to its parent multi-part, a nth-level multi-part belongs to it and 1255should not be freed explicitly. 1256 1257Email messages data is not supposed to be non-ascii and line length is 1258limited: fortunately, some transfer encodings are defined by the standards to 1259support the transmission of such incompatible data. Function 1260curl_mime_encoder(3) tells a part that its source data must be encoded 1261before being sent. It also generates the corresponding header for that part. 1262If the part data you want to send is already encoded in such a scheme, do not 1263use this function (this would over-encode it), but explicitly set the 1264corresponding part header. 1265 1266Upon sending such a message, libcurl prepends it with the header list 1267set with CURLOPT_HTTPHEADER(3), as zero level mime part headers. 1268 1269Here is an example building an email message with an inline plain/html text 1270alternative and a file attachment encoded in base64: 1271 1272~~~c 1273 curl_mime *message = curl_mime_init(handle); 1274 1275 /* The inline part is an alternative proposing the html and the text 1276 versions of the email. */ 1277 curl_mime *alt = curl_mime_init(handle); 1278 1279 /* HTML message. */ 1280 curl_mimepart *part = curl_mime_addpart(alt); 1281 curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>", 1282 CURL_ZERO_TERMINATED); 1283 curl_mime_type(part, "text/html"); 1284 1285 /* Text message. */ 1286 part = curl_mime_addpart(alt); 1287 curl_mime_data(part, "This is plain text message", 1288 CURL_ZERO_TERMINATED); 1289 1290 /* Create the inline part. */ 1291 part = curl_mime_addpart(message); 1292 curl_mime_subparts(part, alt); 1293 curl_mime_type(part, "multipart/alternative"); 1294 struct curl_slist *headers = curl_slist_append(NULL, 1295 "Content-Disposition: inline"); 1296 curl_mime_headers(part, headers, TRUE); 1297 1298 /* Add the attachment. */ 1299 part = curl_mime_addpart(message); 1300 curl_mime_filedata(part, "manual.pdf"); 1301 curl_mime_encoder(part, "base64"); 1302 1303 /* Build the mail headers. */ 1304 headers = curl_slist_append(NULL, "From: me@example.com"); 1305 headers = curl_slist_append(headers, "To: you@example.com"); 1306 1307 /* Set these into the easy handle. */ 1308 curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); 1309 curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime); 1310~~~ 1311 1312It should be noted that appending a message to an IMAP directory requires 1313the message size to be known prior upload. It is therefore not possible to 1314include parts with unknown data size in this context. 1315 1316# Headers Equal Fun 1317 1318Some protocols provide "headers", meta-data separated from the normal 1319data. These headers are by default not included in the normal data stream, but 1320you can make them appear in the data stream by setting CURLOPT_HEADER(3) 1321to 1. 1322 1323What might be even more useful, is libcurl's ability to separate the headers 1324from the data and thus make the callbacks differ. You can for example set a 1325different pointer to pass to the ordinary write callback by setting 1326CURLOPT_HEADERDATA(3). 1327 1328Or, you can set an entirely separate function to receive the headers, by using 1329CURLOPT_HEADERFUNCTION(3). 1330 1331The headers are passed to the callback function one by one, and you can 1332depend on that fact. It makes it easier for you to add custom header parsers 1333etc. 1334 1335"Headers" for FTP transfers equal all the FTP server responses. They are not 1336actually true headers, but in this case we pretend they are! ;-) 1337 1338# Post Transfer Information 1339 1340See curl_easy_getinfo(3). 1341 1342# The multi Interface 1343 1344The easy interface as described in detail in this document is a synchronous 1345interface that transfers one file at a time and does not return until it is 1346done. 1347 1348The multi interface, on the other hand, allows your program to transfer 1349multiple files in both directions at the same time, without forcing you to use 1350multiple threads. The name might make it seem that the multi interface is for 1351multi-threaded programs, but the truth is almost the reverse. The multi 1352interface allows a single-threaded application to perform the same kinds of 1353multiple, simultaneous transfers that multi-threaded programs can perform. It 1354allows many of the benefits of multi-threaded transfers without the complexity 1355of managing and synchronizing many threads. 1356 1357To complicate matters somewhat more, there are even two versions of the multi 1358interface. The event based one, also called multi_socket and the "normal one" 1359designed for using with select(). See the libcurl-multi.3 man page for details 1360on the multi_socket event based API, this description here is for the select() 1361oriented one. 1362 1363To use this interface, you are better off if you first understand the basics 1364of how to use the easy interface. The multi interface is simply a way to make 1365multiple transfers at the same time by adding up multiple easy handles into 1366a "multi stack". 1367 1368You create the easy handles you want, one for each concurrent transfer, and 1369you set all the options just like you learned above, and then you create a 1370multi handle with curl_multi_init(3) and add all those easy handles to 1371that multi handle with curl_multi_add_handle(3). 1372 1373When you have added the handles you have for the moment (you can still add new 1374ones at any time), you start the transfers by calling 1375curl_multi_perform(3). 1376 1377curl_multi_perform(3) is asynchronous. It only performs what can be done 1378now and then return control to your program. It is designed to never 1379block. You need to keep calling the function until all transfers are 1380completed. 1381 1382The best usage of this interface is when you do a select() on all possible 1383file descriptors or sockets to know when to call libcurl again. This also 1384makes it easy for you to wait and respond to actions on your own application's 1385sockets/handles. You figure out what to select() for by using 1386curl_multi_fdset(3), that fills in a set of *fd_set* variables for 1387you with the particular file descriptors libcurl uses for the moment. 1388 1389When you then call select(), it returns when one of the file handles signal 1390action and you then call curl_multi_perform(3) to allow libcurl to do 1391what it wants to do. Take note that libcurl does also feature some time-out 1392code so we advise you to never use long timeouts on select() before you call 1393curl_multi_perform(3) again. curl_multi_timeout(3) is provided to 1394help you get a suitable timeout period. 1395 1396Another precaution you should use: always call curl_multi_fdset(3) 1397immediately before the select() call since the current set of file descriptors 1398may change in any curl function invoke. 1399 1400If you want to stop the transfer of one of the easy handles in the stack, you 1401can use curl_multi_remove_handle(3) to remove individual easy 1402handles. Remember that easy handles should be curl_easy_cleanup(3)ed. 1403 1404When a transfer within the multi stack has finished, the counter of running 1405transfers (as filled in by curl_multi_perform(3)) decreases. When the 1406number reaches zero, all transfers are done. 1407 1408curl_multi_info_read(3) can be used to get information about completed 1409transfers. It then returns the CURLcode for each easy transfer, to allow you 1410to figure out success on each individual transfer. 1411 1412# SSL, Certificates and Other Tricks 1413 1414 [ seeding, passwords, keys, certificates, ENGINE, ca certs ] 1415 1416# Sharing Data Between Easy Handles 1417 1418You can share some data between easy handles when the easy interface is used, 1419and some data is share automatically when you use the multi interface. 1420 1421When you add easy handles to a multi handle, these easy handles automatically 1422share a lot of the data that otherwise would be kept on a per-easy handle 1423basis when the easy interface is used. 1424 1425The DNS cache is shared between handles within a multi handle, making 1426subsequent name resolving faster, and the connection pool that is kept to 1427better allow persistent connections and connection reuse is also shared. If 1428you are using the easy interface, you can still share these between specific 1429easy handles by using the share interface, see libcurl-share(3). 1430 1431Some things are never shared automatically, not within multi handles, like for 1432example cookies so the only way to share that is with the share interface. 1433 1434# Footnotes 1435 1436## [1] 1437 1438libcurl 7.10.3 and later have the ability to switch over to chunked 1439Transfer-Encoding in cases where HTTP uploads are done with data of an unknown 1440size. 1441 1442## [2] 1443 1444This happens on Windows machines when libcurl is built and used as a 1445DLL. However, you can still do this on Windows if you link with a static 1446library. 1447 1448## [3] 1449 1450The curl-config tool is generated at build-time (on Unix-like systems) and 1451should be installed with the 'make install' or similar instruction that 1452installs the library, header files, man pages etc. 1453 1454## [4] 1455 1456This behavior was different in versions before 7.17.0, where strings had to 1457remain valid past the end of the curl_easy_setopt(3) call. 1458