7.2.2 HTTP 协议

📚 本节导读

学习时长：约 25 分钟
难度级别：⭐⭐⭐☆☆
前置知识：HTTP 协议基础、JSON 格式、第 7.2.1 节 Socket 基础

🎯 学习目标

• 掌握 OneOS HTTP 客户端的使用方法
• 掌握 GET / POST / PUT / DELETE 请求的发送
• 掌握自定义请求头的设置
• 了解 HTTP 常见状态码
• 能够使用 HTTP 客户端与 RESTful API 交互

---

一、概述

OneOS HTTP 客户端位于 components/net/protocols/http/httpclient-v1.1.0/，是一个轻量级的 HTTP/HTTPS 客户端库，专为嵌入式设备设计。它支持 GET、POST、PUT、DELETE、HEAD 等常用 HTTP 方法，并支持自定义请求头和 TLS 加密传输。

二、核心数据结构

/* HTTP 请求方法枚举 */
typedef enum {
    HTTP_GET,
    HTTP_POST,
    HTTP_PUT,
    HTTP_DELETE,
    HTTP_HEAD,
} HTTP_REQUEST_TYPE;

/* HTTP 响应头节点 */
typedef struct http_header {
    char *name;                /* 头部字段名 */
    char *value;               /* 头部字段值 */
    struct http_header *next;  /* 链表下一个节点 */
} http_header_t;

/* HTTP 客户端结构体 */
typedef struct http_client {
    int socket;                /* 底层 Socket 描述符 */
    char *host;                /* 服务器主机名 */
    int port;                  /* 服务器端口 */
    char *req_buf;             /* 请求缓冲区 */
    size_t req_buf_size;       /* 请求缓冲区大小 */
    char *resp_buf;            /* 响应缓冲区 */
    size_t resp_buf_size;      /* 响应缓冲区大小 */
    int resp_status;           /* HTTP 响应状态码 */
    struct http_header *header; /* 响应头链表 */
    void *tls;                 /* TLS 上下文（HTTPS） */
    int timeout_ms;            /* 超时时间（毫秒） */
} http_client_t;

三、核心 API 参考

/* 初始化 HTTP 客户端 */
int http_client_init(http_client_t *client);

/* 设置请求头 */
int http_client_set_header(http_client_t *client, const char *name, const char *value);

/* 发送 HTTP 请求 */
int http_client_request(http_client_t *client, HTTP_REQUEST_TYPE type,
                        const char *url, const char *body);

/* 获取 HTTP 响应状态码 */
int http_client_get_status_code(http_client_t *client);

/* 获取指定响应头 */
const char *http_client_get_header(http_client_t *client, const char *name);

/* 获取响应体 */
const char *http_client_get_body(http_client_t *client, size_t *len);

/* 清理 HTTP 客户端资源 */
void http_client_cleanup(http_client_t *client);

四、HTTP GET 请求示例

#include <http_client.h>
#include <oneos/os_kernel.h>

void http_get_example(void)
{
    http_client_t client;
    int ret;

    ret = http_client_init(&client);
    if (ret != 0) {
        os_kprintf("[HTTP GET] init failed, ret=%d\r\n", ret);
        return;
    }

    os_kprintf("[HTTP GET] sending request...\r\n");
    ret = http_client_request(&client, HTTP_GET,
                              "http://httpbin.org/get", NULL);
    if (ret != 0) {
        os_kprintf("[HTTP GET] request failed, ret=%d\r\n", ret);
        http_client_cleanup(&client);
        return;
    }

    int status = http_client_get_status_code(&client);
    os_kprintf("[HTTP GET] status: %d\r\n", status);

    size_t body_len;
    const char *body = http_client_get_body(&client, &body_len);
    if (body && body_len > 0) {
        os_kprintf("[HTTP GET] body (%d bytes):\r\n%.*s\r\n",
                   (int)body_len, (int)body_len, body);
    }

    const char *content_type = http_client_get_header(&client, "Content-Type");
    if (content_type) {
        os_kprintf("[HTTP GET] Content-Type: %s\r\n", content_type);
    }

    http_client_cleanup(&client);
    os_kprintf("[HTTP GET] done\r\n");
}

五、HTTP POST 请求示例

#include <http_client.h>
#include <oneos/os_kernel.h>

void http_post_example(void)
{
    http_client_t client;
    int ret;

    http_client_init(&client);

    http_client_set_header(&client, "Content-Type", "application/json");
    http_client_set_header(&client, "Accept", "application/json");

    const char *json_body = "{"
        "\"device\": \"OneOS-device-001\","
        "\"sensor\": \"temperature\","
        "\"value\": 25.5,"
        "\"unit\": \"celsius\","
        "\"timestamp\": 1752739200"
    "}";

    os_kprintf("[HTTP POST] sending data...\r\n");
    ret = http_client_request(&client, HTTP_POST,
                              "http://httpbin.org/post", json_body);
    if (ret != 0) {
        os_kprintf("[HTTP POST] request failed, ret=%d\r\n", ret);
        http_client_cleanup(&client);
        return;
    }

    os_kprintf("[HTTP POST] status: %d\r\n",
               http_client_get_status_code(&client));

    size_t len;
    const char *body = http_client_get_body(&client, &len);
    if (body) {
        os_kprintf("[HTTP POST] response: %.*s\r\n", (int)len, body);
    }

    http_client_cleanup(&client);
    os_kprintf("[HTTP POST] done\r\n");
}

六、HTTP PUT 与 DELETE 请求示例

/* HTTP PUT 请求 */
void http_put_example(void)
{
    http_client_t client;
    http_client_init(&client);

    http_client_set_header(&client, "Content-Type", "text/plain");

    const char *data = "Updated content from OneOS";
    http_client_request(&client, HTTP_PUT,
                        "http://httpbin.org/put", data);

    os_kprintf("[HTTP PUT] status: %d\r\n",
               http_client_get_status_code(&client));

    http_client_cleanup(&client);
}

/* HTTP DELETE 请求 */
void http_delete_example(void)
{
    http_client_t client;
    http_client_init(&client);

    http_client_request(&client, HTTP_DELETE,
                        "http://httpbin.org/delete", NULL);

    os_kprintf("[HTTP DELETE] status: %d\r\n",
               http_client_get_status_code(&client));

    http_client_cleanup(&client);
}

七、HTTP 常见状态码

状态码	含义	说明
200	OK	请求成功
201	Created	资源创建成功（POST / PUT）
204	No Content	请求成功但无返回内容（DELETE）
301	Moved Permanently	资源永久重定向
302	Found	资源临时重定向
400	Bad Request	请求格式错误
401	Unauthorized	需要认证
403	Forbidden	禁止访问
404	Not Found	资源不存在
500	Internal Server Error	服务器内部错误
502	Bad Gateway	网关错误
503	Service Unavailable	服务不可用

---

📝 本节小结

本节介绍了 OneOS HTTP 客户端的使用方法。HTTP 客户端支持 GET、POST、PUT、DELETE、HEAD 等常用方法，可自定义请求头，适用于与 RESTful API 交互、OTA 固件下载等场景。

核心要点回顾：

1. HTTP 客户端通过 http_client_init 初始化，http_client_request 发送请求
2. 支持自定义请求头（http_client_set_header）
3. 可通过 http_client_get_status_code / http_client_get_body 获取响应
4. 使用完毕后需调用 http_client_cleanup 释放资源

🔗 相关链接

• 7.2.1 Socket 基础网络编程
• 7.2.3 MQTT 协议
• 7.2 网络协议栈（总览）
• 第7章 README