From c0520dd1aa194a60a6e629557aa8ba7a9f586ad1 Mon Sep 17 00:00:00 2001 From: yangjie Date: Fri, 11 Jan 2019 11:09:57 +0800 Subject: [PATCH] =?UTF-8?q?=E3=80=90=E4=BF=AE=E8=AE=A2=E3=80=91=E4=BF=AE?= =?UTF-8?q?=E6=94=B9=E4=BB=A3=E7=A0=81=E6=A0=BC=E5=BC=8F=EF=BC=8C=E5=8F=8A?= =?UTF-8?q?=E5=85=B6=E4=BB=96=E7=BB=86=E8=8A=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api.md | 64 +++++++++++++++++++++++++++++++++----------- docs/introduction.md | 3 ++- docs/samples.md | 9 ++++--- docs/user-guide.md | 12 ++++----- 4 files changed, 61 insertions(+), 27 deletions(-) diff --git a/docs/api.md b/docs/api.md index 5592cd1..b2cb5a8 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,7 +2,9 @@ ## 创建会话 -> struct webclient_session *webclient_session_create(size_t header_sz); +```c +struct webclient_session *webclient_session_create(size_t header_sz); +``` 创建客户端会话结构体。 @@ -15,7 +17,9 @@ ## 关闭会话连接 -> int webclient_close(struct webclient_session *session); +```c +int webclient_close(struct webclient_session *session); +``` 关闭传入的客户端会话连接，并释放内存。 @@ -28,7 +32,9 @@ ## 发送 GET 请求 -> int webclient_get(struct webclient_session *session, const char *URI); +```c +int webclient_get(struct webclient_session *session, const char *URI); +``` 发送 HTTP GET 请求命令。 @@ -42,7 +48,9 @@ ## 发送获取部分数据的 GET 请求 -> int webclient_get_position(struct webclient_session *session, const char *URI, int position); +```c +int webclient_get_position(struct webclient_session *session, const char *URI, int position); +``` 发送带有 Range 头信息的 HTTP GET 请求命令，多用于完成断点续传功能。 @@ -57,7 +65,9 @@ ## 发送 POST 请求 -> int webclient_post(struct webclient_session *session, const char *URI, const char *post_data); +```c +int webclient_post(struct webclient_session *session, const char *URI, const char *post_data); +``` 发送 HTTP POST 请求命令，上传数据到 HTTP 服务器。 @@ -72,7 +82,9 @@ ## 发送数据 -> int webclient_write(struct webclient_session *session, const unsigned char *buffer, size_t size); +```c +int webclient_write(struct webclient_session *session, const unsigned char *buffer, size_t size); +``` 发送数据到连接的服务器。 @@ -88,7 +100,9 @@ ## 接收数据 -> int webclient_read(struct webclient_session *session, unsigned char *buffer, size_t size); +```c +int webclient_read(struct webclient_session *session, unsigned char *buffer, size_t size); +``` 从连接的服务器接收数据。 @@ -105,7 +119,9 @@ ## 设置接收和发送数据超时时间 -> int webclient_set_timeout(struct webclient_session *session, int millisecond); +```c +int webclient_set_timeout(struct webclient_session *session, int millisecond); +``` 设置连接的接收和发送数据超时时间。 @@ -118,7 +134,9 @@ ## 在请求头中添加字段数据 -> int webclient_header_fields_add(struct webclient_session *session, const char *fmt, ...); +```c +int webclient_header_fields_add(struct webclient_session *session, const char *fmt, ...); +``` 该函数用于创建会话之后和发送 GET 或 POST 请求之前，用于添加请求头字段数据。 @@ -133,7 +151,9 @@ ## 通过字段名获取字段值数据 -> const char *webclient_header_fields_get(struct webclient_session *session, const char *fields); +```c +const char *webclient_header_fields_get(struct webclient_session *session, const char *fields); +``` 该函数用于发送 GET 或 POST 请求之后，可以通过传入的字段名称获取对应的字段数据。 @@ -148,7 +168,9 @@ ## 接收响应数据到指定地址 -> int webclient_response(struct webclient_session *session, unsigned char **response); +```c +int webclient_response(struct webclient_session *session, unsigned char **response); +``` 该函数用于发送 GET 或 POST 请求之后， 可以接收响应数据到指定地址。 @@ -162,7 +184,9 @@ ## 发送 GET/POST 请求并接收响应数据 -> int webclient_request(const char *URI, const char *header, const char *post_data, unsigned char **response); +```c +int webclient_request(const char *URI, const char *header, const char *post_data, unsigned char **response); +``` | 参数 | 描述 | |:------------------|:-----------------------------------| @@ -181,7 +205,9 @@ ## 获取 HTTP 响应状态码 -> int webclient_resp_status_get(struct webclient_session *session); +```c +int webclient_resp_status_get(struct webclient_session *session); +``` 该函数用于发送 GET 或 POST 请求之后，用于获取返回的响应状态码。 @@ -193,7 +219,9 @@ ## 获取 Content-Length 字段数据 -> int webclient_content_length_get(struct webclient_session *session); +```c +int webclient_content_length_get(struct webclient_session *session); +``` 该函数用于发送 GET 或 POST 请求之后，用于获取返回的 Content-Length 字段数据。 @@ -206,7 +234,9 @@ ## 下载文件到本地 -> int webclient_get_file(const char *URI, const char *filename); +```c +int webclient_get_file(const char *URI, const char *filename); +``` 从 HTTP 服务器下载文件并存放到本地。 @@ -220,7 +250,9 @@ ## 上传文件到服务器 -> int webclient_post_file(const char *URI, const char *filename, const char *form_data); +```c +int webclient_post_file(const char *URI, const char *filename, const char *form_data); +``` 从 HTTP 服务器下载文件并存放到本地。 diff --git a/docs/introduction.md b/docs/introduction.md index 203eaf6..d978b13 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -128,7 +128,8 @@ HTTP 协议中通过返回的状态码信息，判断当前响应状态，WebCli - 5xx：服务器端错误--服务器未能实现合法的请求 常见的状态码有以下几种： -``` + +```c 200 OK //客户端请求成功 206 Partial Content //服务器已经成功处理了部分 GET 请求 400 Bad Request //客户端请求有语法错误，不能被服务器所理解 diff --git a/docs/samples.md b/docs/samples.md index ac91321..0fe508c 100644 --- a/docs/samples.md +++ b/docs/samples.md @@ -22,10 +22,10 @@ WebClient 软件包提供两个 HTTP Client 示例程序, 分别用于演示软 ```shell RT-Thread online packages IoT - internet of things ---> - [*] WebClient: A HTTP/HTTPS Client for RT-Thread - [ ] Enable support tls protocol - [*] Enable webclient GET/POST samples # 开启 WebClient 测试例程 - Version (latest) ---> # 开启使用最新版本软件包 + [*] WebClient: A HTTP/HTTPS Client for RT-Thread + [ ] Enable support tls protocol + [*] Enable webclient GET/POST samples # 开启 WebClient 测试例程 + Version (latest) ---> # 开启使用最新版本软件包 ``` - 使用 `pkgs --update` 命令下载软件包 @@ -83,4 +83,5 @@ webclient POST request response data : RT-Thread is an open source IoT operating system from China! msh /> ``` + - 在 MSH 中使用命令 `web_post_test [URI]` 格式命令执行 POST 请求示例程序，其中 URI 为用户自定义的支持 POST 请求的地址。 \ No newline at end of file diff --git a/docs/user-guide.md b/docs/user-guide.md index 176cf75..02c10c1 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -39,7 +39,7 @@ RT-Thread online packages 使用 WebClient 软件包发送 GET/POST 请求一般需要完成如下基本流程： -1. **创建客户端会话结构体** +（1） **创建客户端会话结构体** ```c struct webclient_header @@ -64,7 +64,7 @@ struct webclient_session int content_length; //当前接收数据长度（非 chunk 模式） size_t content_remainder; //当前剩余接收数据长度 - + rt_bool_t is_tls; //当前连接是否是 HTTPS 连接 #ifdef WEBCLIENT_USING_MBED_TLS MbedTLSSession *tls_session; // HTTPS 协议相关会话结构体 @@ -86,7 +86,7 @@ if (session == RT_NULL) } ``` -2. **拼接头部数据** +（2） **拼接头部数据** WebClient 软件包提供两种请求头部发送方式： @@ -107,7 +107,7 @@ webclient_header_fields_add(session, "Content-Length: %d\r\n", strlen(post_data) webclient_header_fields_add(session, "Content-Type: application/octet-stream\r\n"); ``` -3. **发送 GET/POST 请求** +（3） **发送 GET/POST 请求** 头部信息添加完成之后，就可以调用 `webclient_get` 函数或者 `webclient_post` 函数发送 GET/POST 请求命令了，函数中主要操作如下： @@ -133,7 +133,7 @@ if ((resp_status = webclient_get(session, URI)) != 200) } ``` -4. **接收响应的数据** +（4） **接收响应的数据** 发送 GET/POST 请求之后，可以使用 `webclient_read` 函数接收响应的实际数据。因为响应的实际数据可能比较长，所以往往我们需要循环接收响应数据，指导数据接收完毕。 @@ -163,7 +163,7 @@ do } while (content_pos < content_length); ``` -5. 关闭并释放客户端会话结构体 +（5） **关闭并释放客户端会话结构体** 请求发送并接收完成之后，需要使用 `webclient_close` 函数关闭并释放客户端会话结构体，完成整个 HTTP 数据交互流程。