#include <http_request.hpp>

类 acl::http_request 继承关系图:

acl::http_request 的协作图:

Public 成员函数
	http_request (socket_stream *client, int conn_timeout=60, bool unzip=true, bool stream_fixed=true)

	http_request (const char *addr, int conn_timeout=60, int rw_timeout=60, bool unzip=true)

virtual	~http_request (void)

http_request &	set_unzip (bool on)

http_request &	set_ssl (sslbase_conf *conf)

http_header &	request_header (void)

http_request &	set_local_charset (const char *local_charset)

bool	request (const void *data, size_t len)

bool	write_head ()

bool	write_body (const void *data, size_t len)

int	http_status () const

long long int	body_length (void) const

bool	keep_alive (void) const

const char *	header_value (const char *name) const

bool	body_finish () const

bool	get_body (xml &out, const char *to_charset=NULL)

bool	get_body (json &out, const char *to_charset=NULL)

bool	get_body (string &out, const char *to_charset=NULL)

int	read_body (char *buf, size_t size)

int	read_body (string &out, bool clean=false, int *real_size=NULL)

bool	body_gets (string &out, bool nonl=true, size_t *size=NULL)

bool	support_range (void) const

long long int	get_range_from (void) const

long long int	get_range_to (void) const

long long int	get_range_max (void) const

const std::vector< HttpCookie * > *	get_cookies (void) const

const HttpCookie *	get_cookie (const char *name, bool case_insensitive=true) const

http_client *	get_client (void) const

void	reset (void)

Public 成员函数继承自 acl::connect_client
	connect_client (void)

virtual	~connect_client ()

time_t	get_when ()

void	set_when (time_t when)

connect_pool *	get_pool () const

virtual void	set_timeout (int conn_timeout, int rw_timeout)

Protected 成员函数
virtual bool	open ()

Protected 成员函数继承自 acl::connect_client
void	set_pool (connect_pool *pool)

Protected 成员函数继承自 acl::acl::noncopyable
	noncopyable ()

	~noncopyable ()

额外继承的成员函数
Protected 属性继承自 acl::connect_client
int	conn_timeout_

int	rw_timeout_

time_t	when_

connect_pool *	pool_

详细描述

HTTP 客户端请求类，该类对象支持长连接，同时当连接断时会自动重试

在文件 http_request.hpp 第 20 行定义.

构造及析构函数说明

◆ http_request() [1/2]

acl::http_request::http_request	(	socket_stream *	client,
		int	conn_timeout = `60`,
		bool	unzip = `true`,
		bool	stream_fixed = `true`
	)

构造函数：通过该构造函数传入的 socket_stream 流对象并不会被关闭，需要调用者自己关闭

参数

client	{socket_stream*} HTTP 连接流对象，可以是请求端的流，也可以是响应端的流；当本对象被销毁时，client 对象是否会被自动销毁，取决于参数 stream_fixed 的值
conn_timeout	{int} 如果传入的流关闭，则内部会自动重试，此时需要该值表示连接服务器的超时时间(秒)，至于重连流的 IO 读写超时时间是从输入的流中继承的
unzip	{bool} 是否对服务器响应的数据自动进行解压注：当该类实例被多次使用时，用户应该在每次调用前调用 request_header::http_header::reset()
stream_fixed	{bool} 当该值为 true 时，则当 http_client 对象被销毁时，传入的 client 流对象不会被销毁，需应用自行销毁；如果该值为 false 时，则当本对象销毁时，client 流对象也将被销毁

◆ http_request() [2/2]

acl::http_request::http_request	(	const char *	addr,
		int	conn_timeout = `60`,
		int	rw_timeout = `60`,
		bool	unzip = `true`
	)

构造函数：该构造函数内部创建的 socket_stream 流会自行关闭

参数

addr	{const char*} WEB 服务器地址，地址格式：domain\|port，如：www.baidu.com\|80
conn_timeout	{int} 远程连接服务器超时时间(秒)
rw_timeout	{int} IO 读写超时时间(秒)
unzip	{bool} 是否对服务器响应的数据自动进行解压

◆ ~http_request()

virtual acl::http_request::~http_request ( void )

virtual

成员函数说明

◆ body_finish()

bool acl::http_request::body_finish ( ) const

是否读完了数据体

返回: {bool}

◆ body_gets()

bool acl::http_request::body_gets	(	string &	out,
		bool	nonl = `true`,
		size_t *	size = `NULL`
	)

调用 request 成功后调用本函数来从 HTTP 服务端读一行数据，可循环调用本函数，直到返回 false 或 body_finish() 返回 true 为止；内部自动对压缩数据解压，如果在调用本函数之前调用 set_charset 设置了本地字符集，则还同时对数据进行字符集转码操作

参数

out	{string&} 存储结果数据
nonl	{bool} 读到的一行数据是否自动去掉尾部的 "\r\n" 或 "\n"
size	{size_t*} 该指针非空时存放读到的数据长度

返回: {bool} 是否读到一行数据：返回 true 时表示读到了一行数据，可以通过 body_finish() 是否为 true 来判断是否读数据体已经结束，当读到一个空行且 nonl = true 时，则 *size = 0；当返回 false 时表示未读完整行且读完毕， *size 中存放着读到的数据长度

◆ body_length()

long long int acl::http_request::body_length ( void ) const

获得 HTTP 响应的数据体长度

返回: {int64) 返回值若为 -1 则表明 HTTP 头不存在或没有长度字段

◆ get_body() [1/3]

bool acl::http_request::get_body	(	xml &	out,
		const char *	to_charset = `NULL`
	)

当调用 request 成功后调用本函数，读取服务器响应体数据并将结果存储于规定的 xml 对象中

参数

out	{xml&} HTTP 响应体数据存储于该 xml 对象中
to_charset	{const char*} 当该项非空，内部自动将数据转成该字符集存储于 xml 对象中

返回: {bool} 读数据是否成功注：当响应数据体特别大时不应用此函数，以免内存耗光

◆ get_body() [2/3]

bool acl::http_request::get_body	(	json &	out,
		const char *	to_charset = `NULL`
	)

当调用 request 成功后调用本函数，读取服务器响应体数据并将结果存储于规定的 json 对象中

参数

out	{json&} HTTP 响应体数据存储于该 json 对象中
to_charset	{const char*} 当该项非空，内部自动将数据转成该字符集存储于 json 对象中

返回: {bool} 读数据是否成功注：当响应数据体特别大时不应用此函数，以免内存耗光

◆ get_body() [3/3]

bool acl::http_request::get_body	(	string &	out,
		const char *	to_charset = `NULL`
	)

当调用 request 成功后调用本函数，读取服务器全部响应数据存储于输入的缓冲区中

参数

out	{string&} 存储响应数据体
to_charset	{const char*} 当该项非空，内部自动将数据转成该字符集存储于 out 对象中注：当响应数据体特别大时不应用此函数，以免内存耗光

◆ get_client()

http_client* acl::http_request::get_client ( void ) const

获得 http_client HTTP 连接流，可以通过返回的对象获得服务器响应的头部分数据，参考：http_client 类

返回: {http_client*} 当返回空时表示流出错了

◆ get_cookie()

const HttpCookie* acl::http_request::get_cookie	(	const char *	name,
		bool	case_insensitive = `true`
	)		const

获得服务器返回的 Set-Cookie 设置的某个 cookie 对象

参数

name	{const char*} cookie 名
case_insensitive	{bool} 是否区分大小写，true 表示不区分大小写

返回: {const HttpCookie*} 返回 NULL 表示不存在

◆ get_cookies()

const std::vector<HttpCookie*>* acl::http_request::get_cookies ( void ) const

获得服务器返回的 Set-Cookie 的集合

返回: {const std::vector<HttpCookie*>*} 返回空表示没有 cookie 对象或连接流为空

◆ get_range_from()

long long int acl::http_request::get_range_from ( void ) const

◆ get_range_max()

long long int acl::http_request::get_range_max ( void ) const

◆ get_range_to()

long long int acl::http_request::get_range_to ( void ) const

◆ header_value()

const char* acl::http_request::header_value ( const char * name ) const

获得 HTTP 响应头中某个字段名的字段值

参数

name	{const char*} 字段名

返回: {const char*} 字段值，为空时表示不存在

◆ http_status()

int acl::http_request::http_status ( ) const

当发送完请求数据后，内部会自动调用读 HTTP 响应头过程，可以通过此函数获得服务端响应的 HTTP 状态字(2xx, 3xx, 4xx, 5xx)；其实该函数内部只是调用了 http_client::response_status 方法

返回: {int}

◆ keep_alive()

bool acl::http_request::keep_alive ( void ) const

HTTP 数据流(响应流是否允许保持长连接)

返回: {bool}

◆ open()

virtual bool acl::http_request::open ( )

protectedvirtual

基类 connect_client 纯虚函数，显式调用本函数用来打开与服务端的连接

返回: {bool} 连接是否成功

实现了 acl::connect_client.

◆ read_body() [1/2]

int acl::http_request::read_body	(	char *	buf,
		size_t	size
	)

当调用 request 成功后调用本函数，读取服务器响应数据并存储于输入的缓冲区中，可以循环调用本函数，直至数据读完了，

参数

buf	{char*} 存储部分响应数据体
size	{size_t} buf 缓冲区大小

返回: {int} 返回值 == 0 表示正常读完毕，< 0 表示服务器关闭连接，> 0 表示已经读到的数据，用户应该一直读数据直到返回值 <= 0 为止注：该函数读到的是原始 HTTP 数据体数据，不做解压和字符集解码，用户自己根据需要进行处理

◆ read_body() [2/2]

int acl::http_request::read_body	(	string &	out,
		bool	clean = `false`,
		int *	real_size = `NULL`
	)

当调用 request 成功后调用本函数读 HTTP 响应数据体，可以循环调用本函数，本函数内部自动对压缩数据进行解压，如果在调用本函数之前调用 set_charset 设置了本地字符集，则还同时对数据进行字符集转码操作

参数

out	{string&} 存储结果数据
clean	{bool} 每次调用本函数时，是否要求先自动将缓冲区 out 的数据清空
real_size	{int*} 当该指针非空时，存储解压前读到的真正数据长度，如果在构造函数中指定了非自动解压模式且读到的数据 > 0，则该值存储的长度值应该与本函数返回值相同；当读出错或未读到任何数据时，该值存储的长度值为 0

返回: {int} == 0 表示读完毕，可能连接并未关闭；>0 表示本次读操作读到的数据长度(当为解压后的数据时，则表示为解压之后的数据长度，与真实读到的数据不同，真实读到的数据长度应该通过参数 real_size 来获得); < 0 表示数据流关闭，此时若 real_size 非空，则 real_size 存储的值应该为 0 当返回 0 时，可调用 body_finish 函数判断是否读完了所有数据体

◆ request()

bool acl::http_request::request	(	const void *	data,
		size_t	len
	)

向 HTTP 服务器发送 HTTP 请求头及 HTTP 请求体，同时从 HTTP 服务器读取 HTTP 响应头，对于长连接，当连接中断时会再重试一次，在调用下面的几个 get_body 函数前必须先调用本函数(或调用 write_head/write_body)；正常情况下，该函数在发送完请求数据后会读 HTTP 响应头，所以用户在本函数返回 true 后可以调用：get_body() 或 http_request::get_clinet()->read_body(char*, size_t) 继续读 HTTP 响应的数据体

参数

data	{const void*} 发送的数据体地址，非空时自动按 POST 方法发送，否则按 GET 方法发送
len	{size_} data 非空时指定 data 数据长度

返回: {bool} 发送请求数据及读 HTTP 响应头数据是否成功

◆ request_header()

http_header& acl::http_request::request_header ( void )

获得 HTTP 请求头对象，然后在返回的 HTTP 请求头对象中添加自己的请求头字段或 http_header::reset()重置请求头状态，参考：http_header 类

返回: {http_header&}

◆ reset()

void acl::http_request::reset ( void )

重置请求状态，在同一个连接的多次请求时会调用此函数

◆ set_local_charset()

http_request& acl::http_request::set_local_charset ( const char * local_charset )

设置本地字符集，当本地字符集非空时，则边接收数据边进行字符集转换

参数

local_charset {const char*} 本地字符集

返回: {http_header&}

◆ set_ssl()

http_request& acl::http_request::set_ssl ( sslbase_conf * conf )

设置客户端 SSL 通信方式，内部缺省为非 SSL 通信方式

参数

conf	{sslbase_conf*} 客户端 SSL 配置对象

返回: {http_request&}

◆ set_unzip()

http_request& acl::http_request::set_unzip ( bool on )

设置在读取服务响应数据时是否针对压缩数据进行解压

参数

on {bool}

返回: {http_request&}

◆ support_range()

bool acl::http_request::support_range ( void ) const

当通过 http_request::request_header().set_range() 设置了 range 的请求时，此函数检查服务器返回的数据是否支持 range

返回: {bool}

◆ write_body()

bool acl::http_request::write_body	(	const void *	data,
		size_t	len
	)

当采用流式写数据时，在调用 write_head 后，可以循环调用本函数发送 HTTP 请求体数据；当输入的两个参数为空值时则表示数据写完；当发送完数据后，该函数内部会自动读取 HTTP 响应头数据，用户可继续调用 get_body/read_body 获取 HTTP 响应体数据

参数

data	{const void*} 数据地址指针，当该值为空指针时表示数据发送完毕
len	{size_t} data 非空指针时表示数据长度

返回: {bool} 发送数据体是否成功注：当应用发送完数据后，必须再调用一次本函数，同时将两个参数都赋空

◆ write_head()

bool acl::http_request::write_head ( )

当采用流式写数据时，需要首先调用本函数发送 HTTP 请求头

返回: {bool} 是否成功，如果成功才可以继续调用 write_body

该类的文档由以下文件生成:

include/acl_cpp/http/http_request.hpp

Public 成员函数

Protected 成员函数

额外继承的成员函数

详细描述

构造及析构函数说明

◆ http_request() [1/2]

◆ http_request() [2/2]

◆ ~http_request()

成员函数说明

◆ body_finish()

◆ body_gets()

◆ body_length()

◆ get_body() [1/3]

◆ get_body() [2/3]

◆ get_body() [3/3]

◆ get_client()

◆ get_cookie()

◆ get_cookies()

◆ get_range_from()

◆ get_range_max()

◆ get_range_to()

◆ header_value()

◆ http_status()

◆ keep_alive()

◆ open()

◆ read_body() [1/2]

◆ read_body() [2/2]

◆ request()

◆ request_header()

◆ reset()

◆ set_local_charset()

◆ set_ssl()

◆ set_unzip()

◆ support_range()

◆ write_body()

◆ write_head()