1.API 說明

1.1創建會話

struct webclient_session *webclient_session_create(size_t header_sz);

創建客戶端會話結構體。

參數	描述
header_sz	最大支持的頭部長度
返回	描述
!= NULL	webclient 會話結構體指針
= NULL	創建失敗

1.2關閉會話連接

int webclient_close(struct webclient_session *session);

關閉傳入的客戶端會話連接，並釋放內存。

參數	描述
session	當前連接會話結構體指針
返回	描述
=0	成功

1.3發送 GET 請求

int webclient_get(struct webclient_session *session, const char *URI);

發送 HTTP GET 請求命令。

參數	描述
session	當前連接會話結構體指針
URI	連接的 HTTP 服務器地址
返回	描述
`>0`	HTTP 響應狀態碼
<0	發送請求失敗

1.4發送獲取部分數據的 GET 請求

int webclient_get_position(struct webclient_session *session, const char *URI, int position);

發送帶有 Range 頭信息的 HTTP GET 請求命令，多用於完成斷點續傳功能。

參數	描述
session	當前連接會話結構體指針
URI	連接的 HTTP 服務器地址
position	數據偏移量
返回	描述
`>0`	HTTP 響應狀態碼
<0	發送請求失敗

1.5發送 POST 請求

int webclient_post(struct webclient_session *session, const char *URI, const void *post_data, size_t data_len);

發送 HTTP POST 請求命令，上傳數據到 HTTP 服務器。

參數	描述
session	當前連接會話結構體指針
URI	連接的 HTTP 服務器地址
post_data	需要上傳的數據地址
data_len	需要上傳數據的長度
返回	描述
`>0`	HTTP 響應狀態碼
<0	發送請求失敗

1.6發送數據

int webclient_write(struct webclient_session *session, const void *buffer, size_t size);

發送數據到連接的服務器。

參數	描述
session	當前連接會話結構體指針
buffer	發送數據的地址
size	發送數據的長度
返回	描述
`>0`	成功發送數據的長度
=0	連接關閉
<0	發送數據失敗

1.7接收數據

int webclient_read(struct webclient_session *session, void *buffer, size_t size);

從連接的服務器接收數據。

參數	描述
session	當前連接會話結構體指針
buffer	接收數據的存放地址
size	最大接收數據的長度
返回	描述
`>0`	成功接收數據的長度
=0	連接關閉
<0	接收數據失敗

1.8設置接收和發送數據超時時間

int webclient_set_timeout(struct webclient_session *session, int millisecond);

設置連接的接收和發送數據超時時間。

參數	描述
session	當前連接會話結構體指針
millisecond	設置的超時時間，單位毫秒
返回	描述
=0	設置超時成功

1.9在請求頭中添加字段數據

int webclient_header_fields_add(struct webclient_session *session, const char *fmt, ...);

該函數用於創建會話之後和發送 GET 或 POST 請求之前，用於添加請求頭字段數據。

參數	描述
session	當前連接會話結構體指針
fmt	添加字段數據的表達式
…	添加的字段數據，爲可變參數
返回	描述
`>0`	成功添加的字段數據的長度
<=0	添加失敗或者頭部數據長度超出

1.10通過字段名獲取字段值數據

const char *webclient_header_fields_get(struct webclient_session *session, const char *fields);

該函數用於發送 GET 或 POST 請求之後，可以通過傳入的字段名稱獲取對應的字段數據。

參數	描述
session	當前連接會話結構體指針
fields	HTTP 字段名稱
返回	描述
= NULL	獲取數據失敗
!= NULL	成功獲取的字段數據

1.11接收響應數據到指定地址

int webclient_response(struct webclient_session *session, void **response, size_t *resp_len);

該函數用於發送 GET 或 POST 請求之後，可以接收響應數據到指定地址。

參數	描述
session	當前連接會話結構體指針
response	存放接收數據的字符串地址
resp_len	接收數據的長度的指針
返回	描述
`>0`	成功接收數據的長度
<=0	接收數據失敗

1.12發送 GET/POST 請求並接收響應數據

int webclient_request(const char *URI, const char *header, const void *post_data, size_t data_len, void **response, size_t *resp_len);

參數	描述
URI	連接的 HTTP 服務器地址
header	需要發送的頭部數據
	= NULL，發送默認頭數據信息，可用於發送 GET/POST請求
	!= NULL，發送指定頭數據信息，可用於發送 GET/POST請求
post_data	發送到服務器的數據
	= NULL，該發送請求爲 GET 請求
	!= NULL，該發送請求爲 POST 請求
data_len	發送數據的長度
response	存放接收數據的字符串地址
resp_len	接收數據長度的指針
返回	描述
`>0`	成功接收數據的長度
<=0	接收數據失敗

1.13拼接請求頭部數據

int webclient_request_header_add(char **request_header, const char *fmt, ...);

該函數適用於 webclient_request 函數發送請求之前，頭部數據的拼接和添加。

參數	描述
request_header	請求頭部數據緩衝區地址
fmt	添加字段數據的表達式
…	添加的字段數據，爲可變參數
返回	描述
`>0`	成功添加的字段數據的長度
<=0	頭部數據添加失敗或內存不足

1.14獲取 HTTP 響應狀態碼

int webclient_resp_status_get(struct webclient_session *session);

該函數用於發送 GET 或 POST 請求之後，用於獲取返回的響應狀態碼。

參數	描述
session	當前連接會話結構體指針
返回	描述
`>0`	HTTP 響應狀態碼

1.15獲取 Content-Length 字段數據

int webclient_content_length_get(struct webclient_session *session);

該函數用於發送 GET 或 POST 請求之後，用於獲取返回的 Content-Length 字段數據。

參數	描述
session	當前連接會話結構體指針
返回	描述
`>0`	Content-Length 字段數據
<0	獲取失敗

1.16下載文件到本地

int webclient_get_file(const char *URI, const char *filename);

從 HTTP 服務器下載文件並存放到本地。

參數	描述
URI	連接的 HTTP 服務器地址
filename	存放文件位置、名稱
返回	描述
=0	下載文件成功
<0	下載文件失敗

1.17上傳文件到服務器

int webclient_post_file(const char *URI, const char *filename, const char *form_data);