📄 libcurl-tutorial.html
字号:
<html><head><title>libcurl-tutorial man page</title><meta name="generator" content="roffit 0.7"><STYLE type="text/css">P.level0 { padding-left: 2em;}P.level1 { padding-left: 4em;}P.level2 { padding-left: 6em;}span.emphasis { font-style: italic;}span.bold { font-weight: bold;}span.manpage { font-weight: bold;}h2.nroffsh { background-color: #e0e0e0;}span.nroffip { font-weight: bold; font-size: 120%; font-family: monospace;}p.roffit { text-align: center; font-size: 80%;}</STYLE></head><body><p class="level0"><a name="NAME"></a><h2 class="nroffsh">NAME</h2><p class="level0">libcurl-tutorial - libcurl programming tutorial <a name="Objective"></a><h2 class="nroffsh">Objective</h2><p class="level0">This document attempts to describe the general principles and some basic approaches to consider when programming with libcurl. The text will focus mainly on the C interface but might apply fairly well on other interfaces as well as they usually follow the C one pretty closely. <p class="level0">This document will refer to 'the user' as the person writing the source code that uses libcurl. That would probably be you or someone in your position. What will be generally referred to as 'the program' will be the collected source code that you write that is using libcurl for transfers. The program is outside libcurl and libcurl is outside of the program. <p class="level0">To get the more details on all options and functions described herein, please refer to their respective man pages. <p class="level0"><a name="Building"></a><h2 class="nroffsh">Building</h2><p class="level0">There are many different ways to build C programs. This chapter will assume a unix-style build process. If you use a different build system, you can still read this to get general information that may apply to your environment as well. <p class="level0"><a name="Compiling"></a><span class="nroffip">Compiling the Program</span> <p class="level1">Your compiler needs to know where the libcurl headers are located. Therefore you must set your compiler's include path to point to the directory where you installed them. The 'curl-config'[3] tool can be used to get this information: <p class="level1">$ curl-config --cflags <p class="level1"><p class="level0"><a name="Linking"></a><span class="nroffip">Linking the Program with libcurl</span> <p class="level1">When having compiled the program, you need to link your object files to create a single executable. For that to succeed, you need to link with libcurl and possibly also with other libraries that libcurl itself depends on. Like the OpenSSL libraries, but even some standard OS libraries may be needed on the command line. To figure out which flags to use, once again the 'curl-config' tool comes to the rescue: <p class="level1">$ curl-config --libs <p class="level1"><p class="level0"><a name="SSL"></a><span class="nroffip">SSL or Not</span> <p class="level1">libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL-based transfers, like HTTPS and FTPS. If OpenSSL was detected properly at build-time, libcurl will be built with SSL support. To figure out if an installed libcurl has been built with SSL support enabled, use 'curl-config' like this: <p class="level1">$ curl-config --feature <p class="level1">And if SSL is supported, the keyword 'SSL' will be written to stdout, possibly together with a few other features that can be on and off on different libcurls. <p class="level1">See also the "Features libcurl Provides" further down. <p class="level0"><a name="autoconf"></a><span class="nroffip">autoconf macro</span> <p class="level1">When you write your configure script to detect libcurl and setup variables accordingly, we offer a prewritten macro that probably does everything you need in this area. See docs/libcurl/libcurl.m4 file - it includes docs on how to use it. <p class="level1"><a name="Portable"></a><h2 class="nroffsh">Portable Code in a Portable World</h2><p class="level0">The people behind libcurl have put a considerable effort to make libcurl work on a large amount of different operating systems and environments. <p class="level0">You program libcurl the same way on all platforms that libcurl runs on. There are only very few minor considerations that differs. If you just make sure to write your code portable enough, you may very well create yourself a very portable program. libcurl shouldn't stop you from that. <p class="level0"><a name="Global"></a><h2 class="nroffsh">Global Preparation</h2><p class="level0">The program must initialize some of the libcurl functionality globally. That means it should be done exactly once, no matter how many times you intend to use the library. Once for your program's entire life time. This is done using <p class="level0"> curl_global_init() <p class="level0">and it takes one parameter which is a bit pattern that tells libcurl what to initialize. Using <span Class="emphasis">CURL_GLOBAL_ALL</span> will make it initialize all known internal sub modules, and might be a good default option. The current two bits that are specified are: <p class="level1"><p class="level0"><a name="CURLGLOBALWIN32"></a><span class="nroffip">CURL_GLOBAL_WIN32</span> <p class="level1">which only does anything on Windows machines. When used on a Windows machine, it'll make libcurl initialize the win32 socket stuff. Without having that initialized properly, your program cannot use sockets properly. You should only do this once for each application, so if your program already does this or of another library in use does it, you should not tell libcurl to do this as well. <p class="level0"><a name="CURLGLOBALSSL"></a><span class="nroffip">CURL_GLOBAL_SSL</span> <p class="level1">which only does anything on libcurls compiled and built SSL-enabled. On these systems, this will make libcurl initialize OpenSSL properly for this application. This is only needed to do once for each application so if your program or another library already does this, this bit should not be needed. <p class="level0"><p class="level0">libcurl has a default protection mechanism that detects if <a class="emphasis" href="./curl_global_init.html">curl_global_init(3)</a> hasn't been called by the time <a class="emphasis" href="./curl_easy_perform.html">curl_easy_perform(3)</a> is called and if that is the case, libcurl runs the function itself with a guessed bit pattern. Please note that depending solely on this is not considered nice nor very good. <p class="level0">When the program no longer uses libcurl, it should call <a class="emphasis" href="./curl_global_cleanup.html">curl_global_cleanup(3)</a>, which is the opposite of the init call. It will then do the reversed operations to cleanup the resources the <a class="emphasis" href="./curl_global_init.html">curl_global_init(3)</a> call initialized. <p class="level0">Repeated calls to <a class="emphasis" href="./curl_global_init.html">curl_global_init(3)</a> and <a class="emphasis" href="./curl_global_cleanup.html">curl_global_cleanup(3)</a> should be avoided. They should only be called once each. <p class="level0"><a name="Features"></a><h2 class="nroffsh">Features libcurl Provides</h2><p class="level0">It is considered best-practice to determine libcurl features at run-time rather than at build-time (if possible of course). By calling <a class="emphasis" href="./curl_version_info.html">curl_version_info(3)</a> and checking out the details of the returned struct, your program can figure out exactly what the currently running libcurl supports. <p class="level0"><a name="Handle"></a><h2 class="nroffsh">Handle the Easy libcurl</h2><p class="level0">libcurl first introduced the so called easy interface. All operations in the easy interface are prefixed with 'curl_easy'. <p class="level0">Recent libcurl versions also offer the multi interface. More about that interface, what it is targeted for and how to use it is detailed in a separate chapter further down. You still need to understand the easy interface first, so please continue reading for better understanding. <p class="level0">To use the easy interface, you must first create yourself an easy handle. You need one handle for each easy session you want to perform. Basically, you should use one handle for every thread you plan to use for transferring. You must never share the same handle in multiple threads. <p class="level0">Get an easy handle with <p class="level0"> easyhandle = curl_easy_init(); <p class="level0">It returns an easy handle. Using that you proceed to the next step: setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers. <p class="level0">You set properties and options for this handle using <a class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt(3)</a>. They control how the subsequent transfer or transfers will be made. Options remain set in the handle until set again to something different. Alas, multiple requests using the same handle will use the same options. <p class="level0">Many of the options you set in libcurl are "strings", pointers to data terminated with a zero byte. Keep in mind that when you set strings with <a class="emphasis" href="./curl_easy_setopt.html">curl_easy_setopt(3)</a>, libcurl will not copy the data. It will merely point to the data. You MUST make sure that the data remains available for libcurl to use until finished or until you use the same option again to point to something else. <p class="level0">One of the most basic properties to set in the handle is the URL. You set your preferred URL to transfer with CURLOPT_URL in a manner similar to: <p class="level0"><pre><p class="level0"> curl_easy_setopt(handle, CURLOPT_URL, "<a href="http://domain.com/">http://domain.com/</a>"); <p class="level0">Let's assume for a while that you want to receive data as the URL identifies a remote resource you want to get here. Since you write a sort of application that needs this transfer, I assume that you would like to get the data passed to you directly instead of simply getting it passed to stdout. So, you write your own function that matches this prototype: <p class="level0"> size_t write_data(void *buffer, size_t size, size_t nmemb, void *userp); <p class="level0">You tell libcurl to pass all data to this function by issuing a function similar to this: <p class="level0"> curl_easy_setopt(easyhandle, CURLOPT_WRITEFUNCTION, write_data); <p class="level0">You can control what data your function get in the forth argument by setting another property: <p class="level0"> curl_easy_setopt(easyhandle, CURLOPT_WRITEDATA, &internal_struct); <p class="level0">Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself won't touch the data you pass with <span Class="emphasis">CURLOPT_WRITEDATA</span>. <p class="level0">libcurl offers its own default internal callback that'll take care of the data if you don't set the callback with <span Class="emphasis">CURLOPT_WRITEFUNCTION</span>. It will then⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -