pen22

mongoose API参考

发表于 分类于 阅读次数： Valine：

通用API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
struct http_message {
  struct mg_str message; /* Whole message: request line + headers + body */
  struct mg_str body;    /* Message body. 0-length for requests with no body */
 
  /* HTTP Request line (or HTTP response line) */
  struct mg_str method; /* "GET" */
  struct mg_str uri;    /* "/my_file.html" */
  struct mg_str proto;  /* "HTTP/1.1" -- for both request and response */
 
  /* For responses, code and response status message are set */
  int resp_code;
  struct mg_str resp_status_msg;
 
  /*
   * Query-string part of the URI. For example, for HTTP request
   *    GET /foo/bar?param1=val1&param2=val2
   *    |    uri    |     query_string     |
   *
   * Note that question mark character doesn't belong neither to the uri,
   * nor to the query_string
   */
  struct mg_str query_string;
 
  /* Headers */
  struct mg_str header_names[MG_MAX_HTTP_HEADERS];
  struct mg_str header_values[MG_MAX_HTTP_HEADERS];
};///HTTP消息
struct websocket_message {
  unsigned char *data;
  size_t size;
  unsigned char flags;
};///websocket消息
struct mg_http_multipart_part {
  const char *file_name;
  const char *var_name;
  struct mg_str data;
  int status; /* <0 on error */
  void *user_data;
};///HTTP分包部分
struct mg_ssi_call_ctx {
  struct http_message *req; /* The request being processed. */
  struct mg_str file;       /* Filesystem path of the file being processed. */
  struct mg_str arg; /* The argument passed to the tag: <!-- call arg -->. */
};///SSI调用上下文
void mg_set_protocol_http_websocket(struct mg_connection *nc);
void mg_send_websocket_handshake(struct mg_connection *nc, const char *uri,
                                 const char *extra_headers);
void mg_send_websocket_handshake2(struct mg_connection *nc, const char *path,
                                  const char *host, const char *protocol,
                                  const char *extra_headers);
void mg_send_websocket_handshake3(struct mg_connection *nc, const char *path,
                                  const char *host, const char *protocol,
                                  const char *extra_headers, const char *user,
                                  const char *pass);
void mg_send_websocket_handshake3v(struct mg_connection *nc,
                                   const struct mg_str path,
                                   const struct mg_str host,
                                   const struct mg_str protocol,
                                   const struct mg_str extra_headers,
                                   const struct mg_str user,
                                   const struct mg_str pass);
struct mg_connection *mg_connect_ws(struct mg_mgr *mgr,
                                    MG_CB(mg_event_handler_t event_handler,
                                          void *user_data),
                                    const char *url, const char *protocol,
                                    const char *extra_headers);
struct mg_connection *mg_connect_ws_opt(
    struct mg_mgr *mgr, MG_CB(mg_event_handler_t ev_handler, void *user_data),
    struct mg_connect_opts opts, const char *url, const char *protocol,
    const char *extra_headers);
void mg_send_websocket_frame(struct mg_connection *nc, int op_and_flags,
                             const void *data, size_t data_len);
void mg_send_websocket_framev(struct mg_connection *nc, int op_and_flags,
                              const struct mg_str *strings, int num_strings);
void mg_printf_websocket_frame(struct mg_connection *nc, int op_and_flags,
                               const char *fmt, ...);
int mg_url_decode(const char *src, int src_len, char *dst, int dst_len,
                  int is_form_url_encoded);
extern void mg_hash_md5_v(size_t num_msgs, const uint8_t *msgs[],
                          const size_t *msg_lens, uint8_t *digest);
extern void mg_hash_sha1_v(size_t num_msgs, const uint8_t *msgs[],
                           const size_t *msg_lens, uint8_t *digest);

HTTP Server端API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
int mg_parse_http(const char *s, int n, struct http_message *hm, int is_req);
/**解析http消息，如果is_req=1 此消息是http请求，is_req=0 此消息是http回应
 *返回解析的字节数 如果http消息不完整则返回0 如果解析出错，则返回负数*/
struct mg_str *mg_get_http_header(struct http_message *hm, const char *name);
/**搜索并返回解析后的http消息hm中的表头名称，如果没有找到标头，则返回NULL
 *实例：struct mg_str *host_hdr = mg_get_http_header(hm, "Host");*/
int mg_http_parse_header(struct mg_str *hdr, const char *var_name, char *buf,
                         size_t buf_size);
/**解析http头hdr,查找变量var_name并将其值存储到buf中，如果没有找到变量，返回0否则返回非0。此函数用于解析cookies验证头等。如果成功则返回变量值的长度，如果buf缓冲区不够大，或者没有找到此变量则返回0
char user[20];
struct mg_str *hdr = mg_get_http_header(hm, "Authorization");
mg_http_parse_header(hdr, "username", user, sizeof(user));
*/
int mg_get_http_basic_auth(struct http_message *hm, char *user, size_t user_len,
                           char *pass, size_t pass_len);
/*获取并解析授权，如果没有找到授权头或者mg_parse_http_basic_auth解析结果头失败*/
int mg_parse_http_basic_auth(struct mg_str *hdr, char *user, size_t user_len,
                             char *pass, size_t pass_len);
/*解析授权,如授权类型不是Basic或者出现其他错误(如用于base64编码的用户密码不对)基本头返回-1*/
size_t mg_parse_multipart(const char *buf, size_t buf_len, char *var_name,
                          size_t var_name_len, char *file_name,
                          size_t file_name_len, const char **chunk,
                          size_t *chunk_len);
/*解析包含多部分表单数据库的缓冲区buf,buf_len,将块名存储在var_name,var_name_len缓冲区中。如果块是上传文件，那么file_name,file_name_len将会被一个上传的文件名填充。chunk,chunk_len指向块数据。返回要跳到下一个块的字节数，如果没有更多块则返回0*/
int mg_get_http_var(const struct mg_str *buf, const char *name, char *dst,
                    size_t dst_len);
/*获取Http表单变量。从buf获取变量名，到指定dst指定长度dst_len的缓冲区。目的地址总是0终止，返回获取到的变量的长度，如果没有找到变量，则返回0.buf必须是有效的url编码缓冲区。如果dst长度太小或者发生错误返回负数*/
 
//此结构定义了mg_serve_http()的工作方式，最佳是设置需要的，其余为NULL
struct mg_serve_http_opts {
  const char *document_root;///web根目录路径
  const char *index_files;///索引文件列表，默认是""
  /*
  per_directory_auth_file =NULL表示禁用身份验证
  per_directory_auth_file =".htpasswd" 要使用身份认证来保护目录，然后在任何目录创建使用                                 digest认证的.htpasswd文件。使用mongoose web服务器二进制文件或                             者Apache的htpasswd实例创建/操作密码文件
                             确保auth_domain是一个有效的域
  */
  const char *per_directory_auth_file;
  const char *auth_domain;//授权域。即web服务器的域名
  /*
      global_auth_file = NULL 禁用身份认证
      通常只保护document_root根目录选定的目录。如果对web服务器的所有访问都必须经过身份验证，       不管URI是什么，将此选项设置为密码文件的路径。此文件的格式与.htpasswd的格式一样，并把此        文件放在document_root根目录之外，以防他人获取到此文件
   */
  const char *global_auth_file;
  const char *enable_directory_listing;//设置为"no"禁用目录列表，默认启用
  const char *ssi_pattern;///ssi匹配模式  源码有详细介绍
  const char *ip_acl;///ip_acl=NULL表示所有IP都可链接
#if MG_ENABLE_HTTP_URL_REWRITES
      const char *url_rewrites;/源码有详细介绍
#endif
  const char *dav_document_root;///DAV的根目录,dav_document_root=NULL 则DAV请求失败
  const char *dav_auth_file;//DAV密码文件，dav_auth_file=NULL 则DAV请求失败 dav_auth_file="-" 禁用DAV鉴权
  const char *hidden_file_pattern;///文件隐藏的Glob模式
  const char *cgi_file_pattern;///cgi_file_pattern != NULL 则使能cgi，即此目录下满足 **.cgi$|**.php$"都视为cgi文件
  const char *cgi_interpreter;///如果不是NULL，请忽略CGI脚本hashbang并使用这个解释器
  const char *custom_mime_types;
/*Comma-separated list of Content-Type overrides for path suffixes,".txt=text/plain; charset=utf-8,.c=text/plain"e.g.*/
  const char *extra_headers;///添加到每个http相应的额外的header,要启用CORS，请将此设置为"Access-Control-Allow-Origin: *"。
}
void mg_serve_http(struct mg_connection *nc, struct http_message *hm,
                   struct mg_serve_http_opts opts);
/*根据opts的内容，提供特定的http请求*/
void mg_http_serve_file(struct mg_connection *nc, struct http_message *hm,
                        const char *path, const struct mg_str mime_type,
                        const struct mg_str extra_headers);
/*提供具有给定MIME类型和可选extra_headers头的特定文件*/
typedef struct mg_str (*mg_fu_fname_fn)(struct mg_connection *nc,
                                        struct mg_str fname);///mg_file_upload_handler()的回调函数原型
void mg_file_upload_handler(struct mg_connection *nc, int ev, void *ev_data,
                            mg_fu_fname_fn local_name_fn
                                MG_UD_ARG(void *user_data));
/*文件上传处理程序。这个处理程序可以用最少的代码实现文件上传.此程序处理MG_EV_HTTPPART事件并保存文件数据到本地。local_name_fn将以客户端提供的名字调用并以期望的本地文件名称打开。如果返回NULL将终止文件上传(客户端得到403)，如果返回不是NULL,返回的字符串必须是堆分配的，且调用方需要释放这些字符串。异常情况：返回完全相同的字符串，
*/
void mg_register_http_endpoint(struct mg_connection *nc, const char *uri_path,
                               MG_CB(mg_event_handler_t handler,
                                     void *user_data));
/*为nc注册回调函数，如果注册了回调函数，其会被调用欧冠，而不是调用mg_bind()中提供的回调函数*/
struct mg_http_endpoint_opts {
  void *user_data;
  /*授权域 (realm) */
  const char *auth_domain;
  const char *auth_file;
};
void mg_register_http_endpoint_opt(struct mg_connection *nc,
                                   const char *uri_path,
                                   mg_event_handler_t handler,
                                   struct mg_http_endpoint_opts opts);
int mg_http_check_digest_auth(struct http_message *hm, const char *auth_domain,
                              FILE *fp);
/*根据打开的密码文件验证HTTP请求。如果经过身份验证，返回1，否则返回0*/
int mg_check_digest_auth(struct mg_str method, struct mg_str uri,
                         struct mg_str username, struct mg_str cnonce,
                         struct mg_str response, struct mg_str qop,
                         struct mg_str nc, struct mg_str nonce,
                         struct mg_str auth_domain, FILE *fp);
/*对打开的密码文件验证给定的响应参数。如果经过身份验证，返回1，否则返回0。
由 mg_http_check_digest_auth().调用
*/
void mg_send_http_chunk(struct mg_connection *nc, const char *buf, size_t len);
/*
使用组块HTTP编码向客户端发送大小为len的缓冲区buf.这个函数首先将  发送缓冲区大小(16进制)+换行符+缓冲区+换行符发出。例如，mg_send_http_chunk(nc，“foo”，3)将把 "3\r\nfoo\r\n"字符串追加到nc->send_mbuf输出IO缓冲区
HTTP头“传输编码:块化”应该在使用此函数之前发送
不要忘记在响应结束时发送一个空块，告诉客户端所有内容都已发送
*/
void mg_printf_http_chunk(struct mg_connection *nc, const char *fmt, ...);
/*发送一个printf格式的HTTP块。功能类似于mg_send_http_chunk()。*/
void mg_send_response_line(struct mg_connection *nc, int status_code,
                           const char *extra_headers);
/*发送响应状态行。如果extra_headers不是NULL，那么extra_headers也会在响应行之后发送。extra_headers不能以新行结束*/
void mg_http_send_error(struct mg_connection *nc, int code, const char *reason);
/*发送一个错误的回应。如果原因为空，消息将从错误代码中推断出来(如果支持的话)*/
void mg_http_send_redirect(struct mg_connection *nc, int status_code,
                           const struct mg_str location,
                           const struct mg_str extra_headers);
/*发送一个重定向响应。status_code应该是301或302，位置指向新位置。如果extra_headers不是空的，那么extra_headers也会在响应行之后发送。extra_headers不能以新行结束。*/
void mg_send_head(struct mg_connection *n, int status_code,
                  int64_t content_length, const char *extra_headers);
/*发送响应行和标题。这个函数用status_code发送响应行，并自动发送一个标题:"Content-Length"或 "Transfer-Encoding"。如果content_length为负，则发送“Transfer-Encoding: chunked”报头，否则发送“Content-Length”报头。如果转换编码被分割，那么消息体必须使用mg_send_http_chunk()或mg_printf_http_chunk()函数发送。否则，必须使用mg_send()或mg_printf()。额外的标题可以通过extra_headers设置。注意，extra_headers不能被一个新的行终止*/
void mg_printf_html_escape(struct mg_connection *nc, const char *fmt, ...);
/*发送一个打印格式的HTTP块，转义HTML标记*/
void mg_http_reverse_proxy(struct mg_connection *nc,
                           const struct http_message *hm, struct mg_str mount,
                           struct mg_str upstream);
/*将给定的请求代理给给定的上游http服务器.挂载中的路径前缀将被剥离到上游服务器请求的路径，例如如果挂载为/api，上游为 http://localhost:8001/foo 那么向/api传入的请求将传入到 http://localhost:8001/foo/bar*/

HTTP Client端API

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

struct mg_connection *mg_connect_http(
    struct mg_mgr *mgr,
    MG_CB(mg_event_handler_t event_handler, void *user_data), const char *url,
    const char *extra_headers, const char *post_data);
/*创建出站HTTP连接的助手函数
url是要获取的url。它必须被正确地url编码，例如没有空格，等等.默认情况下，mg_connect_http()发送连接和主机头
extra_headers是一个额外的HTTP头:"User-Agent: my-app\r\n"
如果post_data为空，则创建一个GET请求。否则，将使用指定的POST数据创建POST请求。
注意，如果要提交的数据是表单提交，那么应该相应地设置Content-Type报头(参见下面的示例)。
nc1 = mg_connect_http(mgr, ev_handler_1, "http://www.google.com&quot;, NULL,
                        NULL);
nc2 = mg_connect_http(mgr, ev_handler_1, "https://github.com&quot;, NULL, NULL);
nc3 = mg_connect_http(
      mgr, ev_handler_1, "my_server:8000/form_submit/",
      "Content-Type: application/x-www-form-urlencoded\r\n",
      "var_1=value_1&var_2=value_2");
*/
struct mg_connection *mg_connect_http_opt(
    struct mg_mgr *mgr, MG_CB(mg_event_handler_t ev_handler, void *user_data),
    struct mg_connect_opts opts, const char *url, const char *extra_headers,
    const char *post_data);
/*创建出站HTTP连接的助手函数.与mg_connect_http基本相同，但允许提供额外的参数(例如SSL参数)*/
int mg_http_create_digest_auth_header(char *buf, size_t buf_len,
                                      const char *method, const char *uri,
                                      const char *auth_domain, const char *user,
                                      const char *passwd);
/*为客户机请求创建摘要身份验证头*/