声明
size_t header_callback(char *buffer, size_t size, size_t nitems, void *userdata);
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback);
概要
接收头部数据的回调。
详情
传入一个指向你的回调函数的指针,该函数应该匹配上面显示的原型。
只要libcurl一接收到头部数据,它就会调用这个函数。对于每一个头部,该头部回调都会被调用一次,并且只有完整的头部行会传递给回调。使用这个回调来解析头部是非常简单的。buffer
指向的数据的大小是size
乘以nmemb
。不要假设头部行是以0字符结尾的!名为userdata
的指针是你通过CURLOPT_HEADERDATA
选项设置的。回调函数必须返回实际处理的字节数。如果这个数量与传递给你的函数的数量不同,它会标识一个错误给libcurl。这会导致传输终止,并且正在使用的libcurl函数会返回CURLE_WRITE_ERROR
。
一个传递给这个函数的完整HTTP头部可以多达CURL_MAX_HTTP_HEADER
字节。
如果这个选项没有被设置,或者如果它被设置成NULL,但CURLOPT_HEADERDATA
被设置成除了NULL之外的任何东西,那么用来接收响应数据的函数会转而被使用。这意味着是通过CURLOPT_WRITEFUNCTION
指定的函数;假如它也没有被指定或者是NULL,那么就是默认的流式写函数。
很重要的一点是,启动了一个请求之后,对于所有响应中接收到的头部都会调用该回调,而不仅仅是最后的响应。这包括了所有在认证协商过程中出现的响应。如果你只需要操作最后的响应中的头部,你需要在回调中自行记录头部,并且利用如HTTP状态行之类来界定响应的边界。
当服务器传输一个编码的分块时,它可能包含一个尾部。尾部与一个HTTP头部完全一样,并且如果接收到一个这样的尾部,它也会通过这个回调传递给应用程序。有几种方法判断它是一个尾部还是一个普通的头部:1)它在响应体之后到来。2)它在最后的头部行(CR LF)之后到来。3)在普通响应头部中的一个尾部:
格式的头部提及哪些头部会在尾部中出现。
对于像FTP,POP3,IMAP和SMTP这样的非HTTP协议,这个函数会以服务器对libcurl发送的命令的响应被调用。
默认值
无。
适用协议
用于所有有头部或元数据概念的协议:HTTP,FTP,POP3,IMAP,SMTP以及更多。
可用性
总是可用。
返回值
返回CURLE_OK
。