软件包介绍

WebClient 软件包是 RT-Thread 自主研发的，基于 HTTP 协议的客户端的实现，它提供设备与 HTTP Server 的通讯的基本功能。

软件包目录结构

WebClient 软件包目录结构如下所示：

  1. webclient
  2. +---docs 
  3. │   +---figures                     // 文档使用图片
  4. │   │   api.md                      // API 使用说明
  5. │   │   introduction.md             // 介绍文档
  6. │   │   principle.md                // 实现原理
  7. │   │   README.md                   // 文档结构说明
  8. │   │   samples.md                  // 软件包示例
  9. │   │   user-guide.md               // 使用说明
  10. │   +---version.md                  // 版本
  11. +---inc                             // 头文件
  12. +---src                             // 源文件
  13. +---samples                         // 示例代码
  14. │   │   webclient_get_sample        // GET 请求示例代码
  15. │   +---webclient_post_sample       // POST 请求示例代码
  16. │   LICENSE                         // 软件包许可证
  17. │   README.md                       // 软件包使用说明
  18. +---SConscript                      // RT-Thread 默认的构建脚本

软件包功能特点

WebClient 软件包功能特点：

  • 支持 IPV4/IPV6 地址

WebClient 软件包会自动根据传入的 URI 地址的格式判断是 IPV4 地址或 IPV6 地址，并且从其中解析出连接服务器需要的信息，提高代码兼容性。

  • 支持 GET/POST 请求方法

HTTP 有多种请求方法（GET、POST、PUT、DELETE等），目前 WebClient 软件包支持 GET 和 POST 请求方法，这也是嵌入式设备最常用到的两个命令类型，满足设备开发需求。

  • 支持文件的上传和下载功能

WebClient 软件包提供文件上传和下载的接口函数，方便用户直接通过 GET/POST 请求方法上传本地文件到服务器或者下载服务器文件到本地，文件操作需要文件系统支持，使用前需开启并完成文件系统的移植。

  • 支持 HTTPS 加密传输

HTTPS 协议（HyperText Transfer Protocol over Secure Socket Layer）和 HTTP 协议一样是基于 TCP 实现的，实际上是在原有的 HTTP 数据外部添加一层 TLS 加密的封装，从而达到加密传输数据的目的。HTTPS 协议地址区别于 HTTP 地址，是以 https 开头的。WebClient 软件包中的 TLS 加密方式依赖 mbedtls 软件包 实现。

  • 完善的头部数据添加和处理方式

HTTP 头部信息用于确定当前请求或响应的数据和状态信息，在发送 GET/POST 请求时头部的拼接成为用户操作的一大难题，正常的做法是手动逐行输入或使用字符串拼接方式，WebClient 软件包中提供简单的添加发送请求头部信息的方式，方便用户使用。对于请求返回的头部信息，往往用户需要获取头部字段数据，WebClient 软件包同样提供了 通过字段名获取字段数据的方式，方便获取需要的数据。

HTTP 协议介绍

HTTP 协议简述

HTTP （Hypertext Transfer Protocol）协议， 即超文本传输协议，是互联网上应用最为广泛的一种网络协议，由于其简捷、快速的方式，适用于分布式和合作式超媒体信息系统。HTTP 协议是基于 TCP/IP 协议的网络应用层协议。默认端口为 80 端口。协议最新版本是 HTTP 2.0，目前是用最广泛的是 HTTP 1.1。

HTTP 协议是一种请求/响应式的协议。一个客户端与服务器建立连接之后，发送一个请求给服务器。服务器接收到请求之后，通过接收到的信息判断响应方式，并且给予客户端相应的响应，完成整个 HTTP 数据交互流程。

浏览器网页是 HTTP 的主要应用方式，但这不代表 HTTP 只能应用于网页，实际上只要通信的双方遵循 HTTP 协议数据传输合适就可以进行数据交互，比如嵌入式领域设备通过 HTTP 协议与服务器连接。

HTTP 协议特点

  • 无状态协议

HTTP 协议是无状态协议。无状态是指协议对于事件的处理没有记忆能力。这意味着如果后续处理需要前面的信息，则必须重传，这可能导致每次连接传送的数据量增大。这样的好处在于，在服务器不需要先前信息时它的应答就较快。

  • 灵活的数据传输

HTTP 允许传输任意类型的数据对象，传输的数据类型由 Content-Type 加以标记区分。

  • 简单快速

客户端向服务器发送请求时，只需要传送请求方式和路径。由于HTTP协议简单，使得HTTP服务器的程序规模小，因而通信速度很快。

  • 支持 B/S 和 C/S 模式

C/S 结构，即 Client/Server (客户机/服务器)结构。B/S 结构，即 Browser/Server (浏览器/服务器)结构。

HTTP 协议请求信息 Request

客户端发送一个HTTP请求到服务器的请求消息包括： 请求行、请求头部、空行和请求数据四个部分组成。

  • 请求行：用于说明请求类型，用来说明请求类型,要访问的资源以及所使用的HTTP版本；

  • 请求头部：紧接着请求行（即第一行）之后的部分，用来说明服务器要使用的附加信息；

  • 空行：请求头部后面的空行是必须的，区分头部和请求数据；

  • 请求数据：请求数据也叫主体，可以添加任意的其他数据。

如下图是一个 POST 请求的信息：

HTTP 协议请求信息

HTTP 协议响应信息 Response

一般情况下，服务器接收并处理客户端发过来的请求后会返回一个HTTP的响应消息。HTTP响应也由四个部分组成，分别是：状态行、消息报头、空行和响应数据。

  • 状态行：由 HTTP 协议号（HTTP 1.1），响应状态码（200），状态信息（OK）三部分组成；

  • 消息报头：用来说明客户端要使用的一些附加信息（日期，数据长度等）；

  • 空行：消息报头后面的空行是必须的，用于区分消息报头和响应数据；

  • 响应数据：服务器返回给客户端的文本信息。

如下图是一个 POST 请求的响应的信息：

HTTP 协议响应信息

HTTP 协议状态码

HTTP 协议中通过返回的状态码信息，判断当前响应状态，WebClient 软件包中也有对状态的获取和判断方式，这里主要介绍常见的状态码的意义。

状态代码有三位数字组成，第一个数字定义了响应的类别，共分五种类别:

  • 1xx：指示信息—表示请求已接收，继续处理

  • 2xx：成功—表示请求已被成功接收、理解、接受

  • 3xx：重定向—要完成请求必须进行更进一步的操作

  • 4xx：客户端错误—请求有语法错误或请求无法实现

  • 5xx：服务器端错误—服务器未能实现合法的请求

常见的状态码有以下几种：

  1. 200 OK                        //客户端请求成功
  2. 206 Partial Content           //服务器已经成功处理了部分 GET 请求
  3. 400 Bad Request               //客户端请求有语法错误，不能被服务器所理解
  4. 403 Forbidden                 //服务器收到请求，但是拒绝提供服务
  5. 404 Not Found                 //请求资源不存在，eg：输入了错误的URL
  6. 500 Internal Server Error     //服务器发生不可预期的错误
  7. 503 Server Unavailable        //服务器当前不能处理客户端的请求

原文: https://www.rt-thread.org/document/site/submodules/webclient/docs/introduction/