http相关函数

// 用于读取请求详细信息的字符串类型。字符指针不为空
struct http_string_s {
  char const * buf;
  int len；
};

struct http_server_s;
struct http_request_s;
struct http_response_s;

// 返回服务器正在运行的事件循环 ID。这将是一个
// 在 Linux 上运行时 epoll fd 或在 BSD 上运行 kqueue。这可以用来
// 监听套接字等的活动。唯一需要注意的是用户数据
// 必须设置为一个结构体，其中第一个成员是指向的函数指针
// 将处理事件的回调。 IE：
//
//
// struct  foo {
// void (*handler)(struct kevent*);
// ...
// }
//
// // 注册事件时将 ev.udata 设置为 foo 指针。
//
// for epoll：
//
// struct foo {
// void (*handler)(struct epoll_event*);
// ...
// }
//
// // 注册事件时将 ev.data.ptr 设置为 foo 指针。
int http_server_loop(struct http_server_s* server);

// 分配并初始化 http 服务器。接受一个端口和一个函数被调用来处理请求的指针。
struct http_server_s* http_server_init(int port, void (*handler)(struct http_request_s*));

// 存储一个指针以备将来检索。程序员使用的。
void http_server_set_userdata(struct http_server_s* server, void* data);

// 启动事件循环和服务器监听。在正常操作期间，这函数不会返回。返回值是服务器失败时的错误代码
// 默认情况下，它将侦听所有接口。
// 对于第二个变体提供要侦听的接口的 IP 地址，或者为任何提供 NULL。
int http_server_listen(struct http_server_s* server);
int http_server_listen_addr(struct http_server_s* server, const char* ipaddr);

// 当你想集成时，使用这个监听调用代替上面的调用
// 将 http 服务器连接到已有循环的现有应用程序中，并且改用轮询功能。
// 这适用于应用程序，例如具有恒定更新循环的游戏。默认情况下它会监听所有接口。
// 对于第二个变体，请提供以下 IP 地址要监听的接口，或者任何接口都为 NULL。
int http_server_listen_poll(struct http_server_s* server);
int http_server_listen_addr_poll(struct http_server_s* server, const char* ipaddr);

// 在更新循环中调用此函数。它将触发请求处理程序一次，如果有一个请求准备好了。
// 如果请求被处理，则返回 1，返回 0
// 如果没有请求被处理。它应该在循环中调用，直到它返回0。
int http_server_poll(struct http_server_s* server);

// 如果设置了标志，则返回 1，否则返回 false。可以的标志查询的列在下面
int http_request_has_flag(struct http_request_s* request, int flag);

// 当请求正文被分块或正文太多时将设置此标志大到适合内存是一次。
// 这意味着 http_request_read_chunk必须使用函数逐个读取主体。
#define HTTP_FLG_STREAMED 0x1

// 返回从 HTTP 请求行读取的请求方法。
struct http_string_s http_request_method(struct http_request_s* request);

// 返回从 HTTP 请求中读取的完整请求目标 (url)线。
struct http_string_s http_request_target(struct http_request_s* request);

// 返回请求体。如果没有发送请求体的 buf 和 len字符串将被设置为 0。
struct http_string_s http_request_body(struct http_request_s* request);

// 返回给定标头键的请求标头值。关键是case不敏感。
struct http_string_s http_request_header(struct http_request_s* request, char const * key);

// 用于迭代所有请求头的过程。 iter 应该是在调用之前初始化为零。
// 每次调用都会将 key 和 val 设置为下一个标题的键和值。当没有更多标头时返回 0。
int http_request_iterate_headers(
  struct http_request_s* request，
  struct http_string_s* key，
  struct http_string_s* val，
  int* iter
);

// 检索使用 http_request_set_userdata 设置的不透明数据指针。
void* http_request_userdata(struct http_request_s* request);

// 检索使用 http_server_set_userdata 设置的不透明数据指针。
void* http_request_server_userdata(struct http_request_s* request);

// 存储一个指针以备将来检索。这由程序员自己调用库中不使用
void http_request_set_userdata(struct http_request_s* request, void* data);

#define HTTP_KEEP_ALIVE 1
#define HTTP_CLOSE 0

// 默认情况下，服务器将检查连接头和 HTTP 确定连接是否应该保持活动的版本。
// 使用此函数覆盖该行为以强制连接到
// 即p-alive 或通过传入 HTTP_KEEP_ALIVE 或 HTTP_CLOSE 关闭
// 指令分别。这可能会提供较小的性能改进
// 如果您控制客户端和服务器并希望始终关闭或
// 保持连接活跃。
void http_request_connection(struct http_request_s* request, int 指令);

// 当读入 HTTP 请求时，服务器分配一个缓冲区来存储
// 请求的详细信息，例如 headers、method、body 等。
// 默认情况下 this调用 http_respond 时将释放内存。
// 有需要很长时间才能完成的请求，并且您不需要请求数据。
//在此调用后访问任何 http_string_s 都将无效。
void http_request_free_buffer(struct http_request_s* request);

// 分配一个 http 响应。当 http_respond 为时，此内存将被释放调用。
结构 http_response_s* http_response_init();

// 设置响应状态。接受 100 到 599 之间的值。任何其他值将映射到 500。
void http_response_status(struct http_response_s* response, int status);

// 设置响应头。采用两个空终止字符串。
void http_response_header(struct http_response_s* response, char const * key, char const * value);

//设置响应体。调用者负责释放任何内存，http_respond会调用。
void http_response_body(struct http_response_s* response, char const * body, int length);

// 开始将响应写入客户端。为响应正文或响应头在此调用后可以安全释放。
void http_respond(struct http_request_s* request, struct http_response_s* response);

// 向客户端写入一个块。 notify_done 回调将在以下情况下被调用
// 写入完成。这个调用会被响应，所以一个新的响应需要为每个块初始化。
// request 将是 http_respond_chunk 时设置的响应状态第一次调用。
// 为第一次调用设置的任何标头都将作为响应头。为后续调用设置的标头将被忽略。
void http_respond_chunk(
  struct http_request_s* request，
  struct http_response_s* response，
  void (*notify_done)(struct http_request_s*)
);

// 结束分块响应。在此调用之前设置的任何标头都将包含在内
void http_respond_chunk_end(struct http_request_s* request, struct http_response_s* response);

// 如果请求具有 Transfer-Encoding: chunked 或主体太大而无法放入,您无法以典型方式读取正文。
// 相反你需要调用此函数一次读取一个块。要检查是否 request 需要这种类型的读取你可以
// 调用http_request_has_flag检查是否设置了 HTTP_FLG_STREAMED 标志的函数。
// 读取流式正文,传递一个回调，当块准备好时将调用该回调。什么时候回调被调用，
// 你可以使用`http_request_chunk` 来获取当前块。完成该块后，再次调用此函数以请求
// 下一个块。如果块的大小为 0，则请求正文已完全
void http_request_read_chunk(
  struct http_request_s* request，
  void (*chunk_cb)(struct http_request_s*)
);

// 返回请求正文的当前块。该块仅在下一次调用 `http_request_read_chunk`。
struct http_string_s http_request_chunk(struct http_request_s* request);

#define http_request_read_body http_request_read_chunk