Mongoose6.11官方手册原版_翻译

https://cesanta.com/docs/overview/intro.html

 

源码下载地址:https://github.com/cesanta/mongoose 

 

概述

介绍

Mongoose是用C语言写的一个网络库,它是嵌入式程序开发的瑞士军刀。它实现了TCP、UDP、HTTP、WebSocket、CoAP、MQTT客户端和和服务器APIs的非阻塞事件-驱动模式。功能包括:

  • 交叉平台:工作在Linux/UNIX,MacOS,QNX,eCos,Windows,Android,iphone,FreeRTOS
  • 原生态支持PicoTCP embedded TCP/IP stack,LWIP embedded TCP/IP stack
  • 工作在多种嵌入式的主板:TI CC3200,TI MSP430,STM32, ESP8266;比如Raspberry PI, BeagleBone, 等基于Linux的主板
  • 基于事件的单线程,异步,非阻塞的内核的API。
  • 编译如下协议:

简单的TCP,简单UDP,SSL/TLS(一种或者两种方法),客户端和服务器

HTTP客户端和服务器

WebSocket 客户端和服务器

MQTT客户端和服务器

CoAP客户端和服务器

DNS客户端和服务器

异步DNS的解决者

  • 微小的静态和运行时footprint
  • 源代码符合ISO C和ISO C++标准
  • 非常易于集成:只需要复制mongoose.c和mongoose.h 到你的工程中。

概念

设计概念

Mongoose有这些基本的数据结构:

  • struct mg_mgr:事件管理器,他容纳了所有的有效连接
  • struct mg_connection:描述了一个连接
  • struct mbuf:数据缓冲区(接收数据或者发送数据)

连接可以是监听(Listening),外联(outbound),连进来(inbound)的任意一种。连出连接(outboud connection)用mg_connect()建立。监听连接(Listening connections)用mg_bind()建立。联入连接(inbound connections)通过listening connection接受.每个连接都是通过结构struct mg_connection来描述的。这个结构有类似sokcet,事件句柄,发送和接收缓冲区,标志。等等字段。

一个用Mongoose开发的程序应该遵循一个标准事件-驱动模式。

  1. 定义和初始化事件管理器(even manager):

strcut mg_mgr  mgr;

mg_mgr_init(&mgr,NULL);

     2.建立连接:例如一个服务程序应该建立一个监听连接(listening connetcions)

struct mg_connection *c=mg_bind(&mgr,"80",ev_handler_function);

mg_set_protocol_http_websocket(c);

      3.在一个循环中通过mg_mgr_pool()建立一个事件循环。

for(;;)

{

      mg_mgr_pool(&mg,1000);

}

mg_mgr_pool()迭代所有的sockets,接受新的连接,发送和接收数据,关闭连接,调用指定的事件的回调函数。更详细的例子,请看 Usage Example,实现了TCP echo服务端。

内存缓冲区

每个连接(connection)都分别有一个发送和接收缓冲区,struct mg_connection::send_mbuf和strcut mg_connection::recv_mbuf,当数据到达后,Mongoose追加接收到的数据到recv_mbuf并且触发MG_EV_RECV事件。用户可以通过其中一个输出函数发送应答数据,比如:mg_send()或者mg_printf().输出函数追加数据到send_mbuf,.当Mongoose成功写数据到socket,mongoose从struct mg_connection::send_mbuf清除数据,并且发送MG_EV_SEND事件。当连接关闭后,MG_EV_CLOSE事件被发送。 

                    Mongoose6.11官方手册原版_翻译_第1张图片

事件句柄函数

每个连接(connection)都有要给关联的事件句柄函数(even handler function),用户必须自己实现在这个函数。事件函数是Mongoose程序的钥匙元素,因为他定义了程序的行为。如下是一个事件函数的样子(even handler function):

static void ev_handler(sturct mg_connection* nc,int ev,void* ev_data)

{

switch(ev)

{

/*定义这个连接的事件句柄函数的行为*/

}

}

struct mg_connection* nc:已经收到事件的连接(connection)

int ev:事件代码,在mongoose.h中定义,例如:连入连接的数据到达:ev是MG_EV_RECV

void* ev_data:这个指针指向事件特定的数据,并且不同的事件代码表示不同的意思。例如对于MG_EV_RECV事件,ev_data是一个int*指针,执向的内容是从远端发来的数据,并且已经保存到接收缓冲区的字节数量。ev_data准确的意思是根据具体的事件确定。每个协议指定的事件通常ev_data指针指向要给结构,该结构容纳协议指定的信息。

注意:struct mg_connection 有一个void* user_data ,他是一个程序指定数据的空间,Mongoose不能用这个指针。事件句柄能在这里存储任何他感兴趣的信息。

事件

Mongoose接受连接进来的连接,为每个连接执行读数据,写数据和调用指定的事件句柄。合适的事件序列如下:

  • 对于客户端连接(outbound):MG_EV_CONNECT->(MG_EV_RECV,MG_EV_SEND,MG_EV_POLL...)->MG_EV_CLOSE
  • 对于服务器(inbound)连接:MG_EV_ACCEPT->(MG_EV_RECV,MG_EV_SNED,MG_EV_POLL...)->MG_EV_CLOSE

以下是被Mongoose出发的核心事件列表(请注意,除了核心事件之外,每个协议都会触发特定于协议的事件)

  • MG_EV_ACCEPT:当一个新的服务连接被监听连接接受的时候发送。void* ev_data 是远端你客户端的socket_address.
  • MG_EV_CONNECT:当一个新的outbound连接通过mg_connect()被建立,失败和 成功都会发送。void* ev_data是int* sucess.如果成功是0,然后这个连接被建立。 否则,他(void* ev_data)包含一个错误代码。去看函数mg_connect_opt(),具体的错误代码。
  • MG_EV_RECV:新的数据被接收并且被添加到recv_mbuf缓冲区的尾部的时候发送。void* ev_data 是int* num_received_bytes.通常,事件句柄应该在nc->recv_mbuf中检查接收到的数据。使用mbuf_remove()清除处理过的数据,如果有必要,设置连接flags nc->flags(去看 struct mg_connection)和通过输出函数比如mg_send()写数据到远端伙伴(peer).

      警告:Mongoose使用realloc()去扩大接收缓冲区,用户有责任从接收缓冲区开始处丢弃处理过的数据,注意,                              mbuf_remove()调用在上面的例子里。

  • MG_EV_SEND:Mongoose已经写数据到远端伙伴,并且已经从mg_connection::send_mbuf中丢弃了被写的数据。void* ev_data 是int* num_sent_bytes.

         NOTE:Mongoose输出函数 仅仅是追加数据到mg_connection::send_mbuf.他不会再对socket进行任何写操作。真正的IO完          成是在mg_mgr_poll()中检测.一个MG_EV_SEND事件被触发,当IO操作完成。

  • MG_EV_POLL:每执行一次mg_mgr_poll(),都会发送给所有connections.这个事件能被用来做任何的家务管理。例如:检查是否确定超时,关闭连接,或者发送心跳消息等。

MG_EV_TIMER:如果调用mg_set_timer()将发送改事件给改连接。

连接标志(Connection flags) 

每个连接都有个一个 标志位字段。一些标志位有mongoose改写。例如,如果用户建立了一个外联UDP连接,用udp://1.2.3.4:5678,Mongoose会为这个连接设置MG_F_UDP标志。其他标志只应由用户事件处理程序设置.下面列举了由事件处理程序设置的connection flags的列表:

  • MG_F_FINISHED_SENDING_DATA:告诉Mongoose 所有的数据已经被追加到send_mbuf.一旦Mongoose发送这个标志到socket,这个连接将被关闭。
  • MG_F_BUFFER_BUT_DONT_SEND:告诉Mongoose去 追加数据到send_mbuf,但是(hold on sending it)依然在发送中,因为这个数据稍后将会被编辑,并且将被发送通过清除MG_F_BUFFER_BUT_DONT_SEND标志。(注:这个标志数据放到send_mbuf中。但是还没有被发送。当清除了MG_F_BUFFER_BUT_DONT_SEND后,就开始去发送了)
  • MG_F_CLOSE_IMMEDIATELY:通常在一个错误发生 去告诉之后,去告诉Mongoose立刻关闭指定连接。
  • MG_F_USER_1,MG_F_USER_2,MG_F_USER_3,MG_F_USER_4.能被开发者使用去存储程序指定的状态。

下面的标志是由Mongoose设置的:

  • MG_F_SSL_HANDSHAKE_DONE:只对SSL,当SSL握手完成后设置
  • MG_F_CONNECTING:当mg_connect()调用。连接进行中,但是连接还没完成的时候设置。
  • MG_F_LISTENING:所有监听连接
  • MG_F_UDP:如果 连接是udp的时候设置。
  • MG_F_IS_WEBSOCKET:如果这个连接是websocket的时候设置
  • MG_F_WEBSOCKET_NO_DEFRAG:如果用户希望关闭自动WebSocket框架碎片整理,则应由用户设置。

你可能感兴趣的:(Mongoose)