libcurl 使用方法简介

  • 背景
  • 简介
  • 使用方法
    • 1、easy interface使用方法
    • 2、multi interface使用方法

背景

最近想做一个简单的HLS拉流程序,HTTP的下载部分觉得采用libcurl来进行比较合适及方便,所以先介绍libcurl的基本用法,然后使用libcurl完成一个简单的下载小程序。

简介

libcurl是一个跨平台的开源网络协议库,支持http, https, rtsp等多种协议 。libcurl同样支持HTTPS证书授权,HTTP POST, HTTP PUT, FTP 上传, HTTP基本表单上传,代理,cookies,和用户认证。
所以,使用libcurl,可以很简单的完成HTTP的下载工作,为HLS模块的拉流部分提供简单有效的HTTP请求方法。
想要知道更多关于libcurl的介绍,可以到官网 上去了解,在这里不再详述。(官网地址 http://curl.haxx.se/)

libcurl主要提供了两种发送HTTP请求的方式,分别是easy interface方式和multi interface方式,前者是采用阻塞的方式发送单条请求,后者采用组合的方式可以一次性发送多条请求数据,且多个下载请求是异步进行的。

使用方法

1、easy interface使用方法

easy interface主要方法如下:

1)初始化,这个函数必须是调用的第一个函数,并且它返回一个easy interface
的handle,使用该handle作为easy接口中其他函数的输入。

 CURL *curl_easy_init( );

2)当操作完成时,此调用必须有相应的调用curl_easy_cleanup() 来释放handle。

void curl_easy_cleanup(CURL * handle );

3)设置此次传输的一些基本参数,如url地址、http头、cookie信息、发送超时时间等,其中,CURLOPT_URL是必设的选项。
该函数是整个模块的核心,使用该函数,我们可以设置很多相关操作,正是由于该函数的存在,才另libcurl变的简单且具备多种可操作性。
curl_easy_setopt一些经常使用的方式,会在后面补充

 CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parametr);

4)在上述准备工作已经完成后,可以调用curl_easy_perform函数,则会开始HTTP的请求工作。该接口是一个阻塞的接口。

 CURLcode curl_easy_perform(CURL * easy_handle );

5)请求过程中,可以使用下面函数,获取HTTP该次请求的相关信息,包括response
code,下载的URL,下载速度等。该函数对于一次请求不是必须的。

  CURLcode curl_easy_getinfo(CURL *curl, CURLINFO info, ... ); 

第 2 个参数有众多选项,每个选项都有其相应的含义,第3个参数根据参数2,会有不同类型。常用的info如下:

1、CURLINFO_RESPONSE_CODE 取得response code,要求第 3 个参数是个 long
型的指针。如果TCP就连接不上,值为0。 CURLINFO_EFFECTIVE_URL
取得本最终生效的URL,也即是如果有多次重定向,获取的值为最后一次URL,要求第 3 个参数是个 char 型的指针。
2、CURLINFO_SIZE_DOWNLOAD 获取下载字节数,要求第 3 个参数是个 double
型的指针。注意,这个字节数只能反映最近一次的下载。
3、CURLINFO_SPEED_DOWNLOAD 获取平均下载数据,该选项要求传递一个
double 型参数指针,这个速度不是即时速度,而是下载完成后的速度,单位是 字节/秒
4、CURLINFO_TOTAL_TIME
获取传输总耗时,要求传递一个 double 指针到函数中,这个总的时间里包括了域名解析,以及 TCP 连接过程中所需要的时间。
5、CURLINFO_CONTENT_TYPE 该选项获得 HTTP 中从服务器端收到的头部中的 Content-Type 信息。
6、CURLINFO_CONTENT_LENGTH_DOWNLOAD 获取头部content-length,要求第 3 个参数是个 double
型的指针。如果文件大小无法获取,那么函数返回值为 -1 。

使用上面的几个函数,我们就可以完成一个简单的HTTP下载程序:

CURL *curl = curl_easy_init();
if(curl) {
  CURLcode res;
  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
  res = curl_easy_perform(curl);
  curl_easy_cleanup(curl);
}

curl_easy_setop简介:
函数原型:

CURLcode curl_easy_setopt(CURL *handle, CURLoption option, parameter);

描述:
这个函数几乎所有的curl 程序都要频繁的使用它,它告诉curl库程序将有如何的行为。 (这个函数有些像ioctl函数)
参数:
1 CURL类型的指针
2 各种CURLoption类型的选项.。这个参数的取值很多,具体的可以查看man手册。
3 parameter 这个参数 既可以是个函数的指针,也可以是某个对象的指针,也可以是个long型的变量。它用什么这取决于第二个参数。

下面介绍几个常用的参数及使用方法:

  1. CURLOPT_URL 这个选项必须要有,设置请求的URL ,如果URL参数不写上协议头(如 “http://” 或者 "ftp:// 等等),那么函数会自己进行猜解所给的主机上用的是哪一种服务协议。
    假如给的这个地址是一个不被支持的协议,那么在其后执行curl_easy_perform() 函数或 curl_multi_perform() 函数时,libcurl将返回错误(CURLE_UNSUPPORTED_PROTOCOL)。 这个选项是唯一一个在 curl_easy_perform()调用之前就一定要设置的选项。
  1. CURLOPT_WRITEFUNCTION,CURLOPT_WRITEDATA
    1)CURLOPT_WRITEFUNCTION选项用于设置接收数据回调函数,回调函数原型为: size_t function(void *ptr, size_t size, size_t nmemb, void *stream); 函数将在libcurl接收到数据后被调用,因此函数多做数据保存的功能,如处理下载文件。
    2) CURLOPT_WRITEDATA选项用于指定CURLOPT_WRITEFUNCTION函数中的stream指针的来源。
    3)如果没有通过CURLOPT_WRITEFUNCTION属性给easy handle设置回调函数,libcurl会提供一个默认的回调函数,它只是简单的将接收到的数据打印到标准输出。也可以通过CURLOPT_WRITEDATA属性给默认回调函数传递一个已经打开的文件指针,用于将数据输出到文件里。
  1. CURLOPT_HEADERFUNCTION,CURLOPT_HEADERDATA
    1)CURLOPT_HEADERFUNCTION设置接收到http头的回调函数,原型为: size_t function(void *ptr,size_t size,size_t nmemb, void *stream); libcurl一旦接收到http 头部数据后将调用该函数。
    2)CURLOPT_HEADERDATA传递指针给libcurl,该指针表明CURLOPT_HEADERFUNCTION函数的stream指针的来源。

和上面两组类似的,这样对应的回调选项还有很多,使用方法也类似,如: CURLOPT_READFUNCTION/ CURLOPT_READDATA;

  1. CURLOPT_HTTPHEADER
    libcurl有自己默认的请求头,如果不符合我们的要求,可以使用该选项自定义请求头。可以使用curl_slist_append进行自定义,重设,如果设置请求参数为空,则相当于删除该请求头。
  1. CURLOPT_USERAGENT
    该选项要求传递一个以 ‘\0’ 结尾的字符串指针,这个字符串用来在向服务器请求时发送 HTTP 头部中的 User-Agent 信息,有些服务器是需要检测这个信息的,如果没有设置User-Agent,那么服务器拒绝请求。设置后,可以骗过服务器对此的检查。
  1. CURLOPT_VERBOSE
    在使用该选项且第 3 个参数为 1 时,curl 库会显示详细的操作信息。这对程序的调试具有极大的帮助。
  1. CURLOPT_NOPROGRESS,CURLOPT_PROGRESSFUNCTION,CURLOPT_PROGRESSDATA
    这三个选项和跟数据传输进度相关。
    1)CURLOPT_PROGRESSFUNCTION设置回调函数,函数原型: int progress_callback(void *clientp, double dltotal, double dlnow, double ultotal, double ulnow); progress_callback正常情况下每秒被libcurl调用一次。
    2)CURLOPT_NOPROGRESS必须被设置为false才会启用该功能,
    3)CURLOPT_PROGRESSDATA指定的参数将作为CURLOPT_PROGRESSFUNCTION指定函数的第一个参数。
  1. CURLOPT_TIMEOUT,CURLOPT_CONNECTIONTIMEOUT
    超时相关设置,时间单位为s
    1)CURLOPT_TIMEOUT设置整个libcurl传输超时时间。
    2)CURLOPT_CONNECTIONTIMEOUT
    设置连接等待时间。设置为0,则无限等待。
  1. CURLOPT_FOLLOWLOCATION,CURLOPT_MAXREDIRS
    重定向相关设置
    1)CURLOPT_FOLLOWLOCATION 设置为非0,响应头信息Location,即curl会自己处理302等重定向
    2)CURLOPT_MAXREDIRS指定HTTP重定向的最大次数
  1. CURLOPT_RANGE ,CURLOPT_RESUME_FROM/ CURLOPT_RESUME_FROM_LARGE 断点续传相关设置。
    1)CURLOPT_RANGE 指定char *参数传递给libcurl,用于指明http请求的range
    2)CURLOPT_RESUME_FROM传递一个long参数作为偏移量给libcurl,指定开始进行传输的位置。CURLOPT_RESUME_FROM大小限制为2G,超过可以使用CURLOPT_RESUME_FROM_LARGE
  1. CURLOPT_POSTFIELDS,CURLOPT_POSTFIELDSIZE
    1)CURLOPT_POSTFIELDS 传递一个作为HTTP “POST”操作的所有数据的字符串。
    2)CURLOPT_POSTFIELDSIZE 设置POST 字节大小。
  1. CURLOPT_NOBODY
    设置该属性即可告诉libcurl我想发起一个HEAD请求 有时候你想查询服务器某种资源的状态,比如某个文件的属性:修改时间,大小等等,但是并不需要具体得到该文件,这时我们仅需要HEAD请求。
  1. CURLOPT_ACCEPT_ENCODING
    设置libcurl对特定压缩方式自动解码,支持的方式有: “br, gzip, deflate”. 第3个参数为指定的压缩方式,如果设置为 " ",则表明三种都支持。
  1. CURLOPT_MAX_RECV_SPEED_LARGE,CURLOPT_MAX_SEND_SPEED_LARGE
    限速相关设置
    1)CURLOPT_MAX_RECV_SPEED_LARGE,指定下载过程中最大速度,单位bytes/s。
    2)CURLOPT_MAX_SEND_SPEED_LARG,指定上传过程中最大速度,单位bytes/s。
  1. CURLOPT_FORBID_REUSE ,CURLOPT_FRESH_CONNEC
    如果不使用长连接,需要设置这两个属性
    1)CURLOPT_FORBID_REUSE 设置为1,在完成交互以后强迫断开连接,不重用。
    2)CURLOPT_FRESH_CONNECT设置为1,强制获取一个新的连接,替代缓存中的连接。
  1. CURLOPT_NOSIGNAL
    当多个线程都使用超时处理的时候,同时主线程中有sleep或是wait等操作。如果不设置这个选项,libcurl将会发信号打断这个wait从而可能导致程序crash。 在多线程处理场景下使用超时选项时,会忽略signals对应的处理函数。
  1. CURLOPT_BUFFERSIZE
    指定libcurl中接收缓冲区的首选大小(以字节为单位),但是不保证接收数据时每次数据量都能达到这个值。此缓冲区大小默认为CURL_MAX_WRITE_SIZE(16kB)。允许设置的最大缓冲区大小为CURL_MAX_READ_SIZE(512kB)。 允许设置的最小缓冲区大小为1024。

DNS相关选项:

  1. CURLOPT_IPRESOLVE
    指定libcurl 域名解析模式。支持的选项有:
    1)CURL_IPRESOLVE_WHATEVER:默认值,相当于PF_UNSPEC,支持IPv4/v6,具体以哪个优先需要看libc底层实现,Android中默认以IPv6优先,当IPv6栈无法使用时,libcurl会用IPv4。
    2)CURL_IPRESOLVE_V4:.仅请求A记录,即只解析为IPv4地址。
    3)CURL_IPRESOLVE_V6:.仅请求AAAA记录,即只解析为IPv6地址。
    注意:该功能生效的前提是libcurl支持IPv6,需要在curl/lib/curl_config.h配置#define ENABLE_IPV6 1
  1. CURLOPT_DNS_CACHE_TIMEOUT
    设置libcurl DNS缓存超时时间,默认为60秒,即每60秒清一次libcurl自身保存的DNS缓存。
    如果设置为0,则不适用DNS缓存,设置为-1,则永远不清缓存。
  1. CURLOPT_DNS_USE_GLOBAL_CACHE
    让libcurl使用系统DNS缓存,默认情况下,libcurl使用本身的DNS缓存。

这几个是较常用的选项,当然,libcurl远远不止这几个选项,更详细的使用方法可以参考官网。

最后使用easy interface完成下载的简单代码:

#include 
#include 
#include 
#include 

//#define CURL_DEBUG 1
#define CURL_WAIT_TIMEOUT_MSECS 60000 //60s
#define CURL_MULIT_MAX_NUM 5

static size_t recive_data_fun( void *ptr, size_t size, size_t nmemb, void *stream){
    return fwrite(ptr,size,nmemb,(FILE*)stream);
}

static size_t read_head_fun( void *ptr, size_t size, size_t nmemb, void *stream){
    char head[2048] = {0};
    memcpy(head,ptr,size*nmemb+1);
    printf(" %s \n",head);
    return size*nmemb;
}

int main(int argc, char **argv)
{
    if(argc < 3){
        printf("arg1 is url; arg2 is out file\n");
        return -1;
    }    
    char* url = strdup( argv[1]);
    char* filename= strdup(argv[2]);
    CURL* curl_handle;
    CURLcode res;
    
    //int
    FILE* save_file = fopen(filename,"w");
    if(save_file == NULL){
        printf("open save file fail!\n");
        return -1;
    }

    curl_handle = curl_easy_init();
    if(curl_handle){
        curl_easy_setopt(curl_handle, CURLOPT_URL, url);//set down load url
        curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, save_file);//set download file
        curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, recive_data_fun);//set call back fun
        curl_easy_setopt(curl_handle, CURLOPT_HEADERFUNCTION, read_head_fun);//set call back fun
#ifdef CURL_DEBUG
        curl_easy_setopt(curl_handle, CURLOPT_VERBOSE, 1);
#endif 

    //start down load
        res = curl_easy_perform(curl_handle);
        printf("curl fetch code %d\n",res);
    }
    
    //release
    if(save_file){
        fclose(save_file);
        save_file = NULL;
    }
    if(curl_handle){
        curl_easy_cleanup(curl_handle);
    }
    if(url){
        free(url);
    }

    return 0;
}

2、multi interface使用方法

multi interface的使用是在easy interface的基础之上,将多个easy handler加入到一个stack中,同时发送请求。与easy interface不同,它是一种异步,非阻塞的传输方式。

在掌握easy interface的基础上,multi interface的使用也很简单:
1)curl_multi _init初始化一个multi handler对象,
2)初始化多个easy handler对象,使用curl_easy_setopt进行相关设置,
3)调用curl_multi _add_handle把easy handler添加到multi curl对象中
4)添加完毕后执行curl_multi_perform方法进行并发的访问,
5)访问结束后curl_multi_remove_handle移除相关easy curl对象,先用curl_easy_cleanup清除easy handler对象,最后curl_multi_cleanup清除multi handler对象。

multi interface一些函数说明:
1)和easy interface类似,multi 的初始化和清除函数如下:

 CURLM *curl_multi_init( );
 CURLMcode curl_multi_cleanup( CURLM*multi_handle );

2)

CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
CURLMcode curl_multi_remove_handle(CURLM *multi_handle, CURL *easy_handle);

当设置好easy模式并准备传输的时候,可以使用curl_multi_add_handle替代curl_easy_perform,这样easy handler则会加入multi栈中。我们能在任何时候增加一个esay handler给multi模式,即使easy已经在执行传输操作了。
也可以在任何时候使用curl_multi_remove_handle将esay handler从multi栈中移出,一旦移出可以再次使用curl_easy_perform来进行传输任务。

3)

CURLMcode curl_multi_perform(CURLM *multi_handle, int *running_handles);

添加easy handler到multi并不马上开始执行,由curl_multi_perform启动执行。
启动后将执行所有multi stack中的收发事件。如果栈上是空的直接返回。函数参数running_handles会返回当前还未结束的easy handler个数。

4)等待及超时

CURLMcode curl_multi_fdset(CURLM *multi_handle,
                           fd_set *read_fd_set,
                           fd_set *write_fd_set,
                           fd_set *exc_fd_set,
                           int *max_fd);
                           
CURLMcode curl_multi_wait(CURLM *multi_handle,
                          struct curl_waitfd extra_fds[],
                          unsigned int extra_nfds,
                          int timeout_ms,
                          int *numfds);                           

libcurl中,旧的API使用curl_multi_fdset设置 select或者poll模型触发。
我们看下官网给的example:

#ifdef _WIN32
#define SHORT_SLEEP Sleep(100)
#else
#define SHORT_SLEEP usleep(100000)
#endif
 
fd_set fdread;
fd_set fdwrite;
fd_set fdexcep;
int maxfd = -1;
 
long curl_timeo;
 
curl_multi_timeout(multi_handle, &curl_timeo);
if(curl_timeo < 0)
  curl_timeo = 1000;
 
timeout.tv_sec = curl_timeo / 1000;
timeout.tv_usec = (curl_timeo % 1000) * 1000;
 
FD_ZERO(&fdread);
FD_ZERO(&fdwrite);
FD_ZERO(&fdexcep);
 
/* get file descriptors from the transfers */
mc = curl_multi_fdset(multi_handle, &fdread, &fdwrite, &fdexcep, &maxfd);
 
if(maxfd == -1) {
  SHORT_SLEEP;
  rc = 0;
}
else
  rc = select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
 
switch(rc) {
case -1:
  /* select error */
  break;
case 0:
default:
  /* timeout or readable/writable sockets */
  curl_multi_perform(multi_handle, &still_running);
  break;
}
 
/* if there are still transfers, loop! */

新的API中,官网更推荐使用curl_multi_wait的方式来实现,实现方便,同时也可以避免select中file descriptors不能大于1024的问题。curl_multi_wait会轮询multi上的所有easy句柄,一直阻塞直到至少有一个被触发或者超时。
如果multi句柄正因为网络延时而挂起,会有一个更短更精确的时间来代替我们自己设置的超时时间timeout_ms。
curl_waitfd参数添加需要监听的socket。
wait返回后,numfds返回被触发的事件数量,若为0表示超时或者没有事件等待。numfds的值包括multi栈上的和extra_fds新加的之和。

看下官网的example:

CURL *easy_handle;
CURLM *multi_handle;
 
/* add the individual easy handle */
curl_multi_add_handle(multi_handle, easy_handle);
 
do {
  CURLMcode mc;
  int numfds;
 
  mc = curl_multi_perform(multi_handle, &still_running);
 
  if(mc == CURLM_OK ) {
    /* wait for activity, timeout or "nothing" */
    mc = curl_multi_wait(multi_handle, NULL, 0, 1000, &numfds);
  }
 
  if(mc != CURLM_OK) {
    fprintf(stderr, "curl_multi failed, code %d.n", mc);
    break;
  }
 
  /* 'numfds' being zero means either a timeout or no file descriptors to
     wait for. Try timeout on first occurrence, then assume no file
     descriptors and no file descriptors to wait for means wait for 100
     milliseconds. */
 
  if(!numfds) {
    repeats++; /* count number of repeated zero numfds */
    if(repeats > 1) {
      WAITMS(100); /* sleep 100 milliseconds */
    }
  }
  else
    repeats = 0;
 
} while(still_running);
 
curl_multi_remove_handle(multi_handle, easy_handle);

对于select和curl_multi_wait两种方式,都可以使用curl_multi_timeout获取一个合适的超时时间,当然,超时时间也可以我们自己设置。

5)

CURLMsg *curl_multi_info_read( CURLM *multi_handle,   int *msgs_in_queue);

我们可以调用curl_multi_info_read获取每一个执行完成的操作信息。在完成后即将其移除multi stack。

/* call curl_multi_perform or curl_multi_socket_action first, then loop
   through and check if there are any transfers that have completed */
struct CURLMsg *m;
do {
  int msgq = 0;
  m = curl_multi_info_read(multi_handle, &msgq);
  if(m && (m->msg == CURLMSG_DONE)) {
    CURL *e = m->easy_handle;
    transfers--;
    curl_multi_remove_handle(multi_handle, e);
    curl_easy_cleanup(e);
  }
} while(m);

最后使用multi interface完成并发下载的简单代码:

#include  
#include  
#include  
#include  
 
//#define CURL_DEBUG 1 
#define CURL_WAIT_TIMEOUT_MSECS 1000 //1s 
#define CURL_MULIT_MAX_NUM 5 
 
typedef struct curl_obj{ 
    CURL* curl_handle; 
    FILE* save_file; 
    char* fetch_url; 
    size_t (*recive_data_fun)( void *ptr, size_t size, size_t nmemb, void *stream); 
    size_t (*read_head_fun)( void *ptr, size_t size, size_t nmemb, void *stream); 
}curl_obj; 
 
static size_t recive_data_fun( void *ptr, size_t size, size_t nmemb, void *stream){ 
    return fwrite(ptr,size,nmemb,(FILE*)stream); 
} 
 
static size_t read_head_fun( void *ptr, size_t size, size_t nmemb, void *stream){ 
    char head[2048] = {0}; 
    memcpy(head,ptr,size*nmemb+1); 
    printf(" %s \n",head); 
    return size*nmemb; 
} 
 
int main(int argc, char **argv) 
{ 
    if(argc < 3){ 
        printf("ERROR----arg1 is url; arg2 is out file\n"); 
        return -1; 
    } 
 
    char* outfile_name[CURL_MULIT_MAX_NUM] = {0}; 
    curl_obj obj[CURL_MULIT_MAX_NUM]; 
    int mulit_h_num = ((argc -1) < CURL_MULIT_MAX_NUM)? (argc -1):CURL_MULIT_MAX_NUM; 
     
    CURLM *multi_handle = curl_multi_init();     
    for(int i=0;i 60){
                printf("ERROR----timeout break!!! \n");           
                break;
            }else{
                usleep(10*1000);  /* sleep 10 milliseconds */
                continue;
            }
        }
        else{
            repeats = 0;
        }
          
        retcode = curl_multi_perform(multi_handle, &still_running); 
        if (retcode != CURLM_OK) { 
            printf("ERROR----curl_multi_perform  errorcode[%d]\n",retcode); 
            break; 
        } 
        //printf("still_running[%d]\tnumfds[%d]\n",still_running,numfds );

        int msgs_left = 0; 
        CURLMsg *msg = NULL; 
        while ((msg = curl_multi_info_read(multi_handle, &msgs_left)) != NULL){ 
            if (msg->msg == CURLMSG_DONE) { 
                long http_response_code = -1; 
                char* http_url = NULL; 
                curl_easy_getinfo(msg->easy_handle, CURLINFO_RESPONSE_CODE, &http_response_code); 
                curl_easy_getinfo(msg->easy_handle, CURLINFO_EFFECTIVE_URL, &http_url);
                printf("[%s]fetch done, response[%d]\n",http_url,http_response_code ); 
            } 
        } 
    } while (still_running); 
    
release:  
     printf("release\n"); 
     for(int i=0;i

你可能感兴趣的:(流媒体)