# 成块消息管理

成块消息可以在多个线程之间传输消息，成块消息缓冲区与环形缓冲区的管理方式有些区别，其主要的区别在于成块消息管理在保证消息完整性上做了相应的处理，保证完整性的处理分为两个部分，分别是写消息时的处理与读消息时的处理。

1. 写消息：用户在向成块消息缓冲区写入一段消息时，成块消息写函数会在保存消息之前先保存消息的长度，再保存写入的消息。
2. 读消息：用户读成块消息时，成块消息读函数会先比较保存的消息长度与用户传入的消息长度之间的大小，如果保存的长度大于用户传入的消息长度则返回失败，否则就执行读取流程。

与环形缓冲区一样，在多个进程使用一块成块消息缓冲区时，也要做进程间的互斥操作。

LW_BMSG 是成块消息缓冲区结构体，其详细描述如下：

#include <SylixOS.h>
typedef struct {
PUCHAR          BM_pucBuffer;                                                 
size_t          BM_stSize;                                                    
size_t          BM_stLeft;                                                    
PUCHAR          BM_pucPut;                                                    
PUCHAR          BM_pucGet;                                                    
} LW_BMSG;

• BM_pucBuffer：缓冲区首地址。
• BM_stSize：为缓冲区大小。
• BM_stLeft：为剩余空间大小。
• BM_pucPut：为写入指针 。
• BM_pucGet：为读出指针。

说明：
用户在管理成块消息缓冲区结构体中的相关成员时，请使用系统提供的管理接口，以便驱动可以向后兼容。

# 创建成块消息缓冲区

函数 _bmsgCreate 的功能是创建一个成块消息缓冲区，用户需要提供的参数是需要的缓冲区的长度。其详细描述如下：

#include <SylixOS.h>
PLW_BMSG  _bmsgCreate  (size_t  stSize);

函数 _bmsgCreate 的原型分析：

• 函数成功返回消息缓冲区结构指针，失败返回 LW_NULL 。
• stSize 参数是申请的缓冲区的长度。

# 删除成块消息缓冲区

函数 _bmsgDelete 的功能是删除一个已创建的成块消息缓冲区，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
VOID _bmsgDelete (PLW_BMSG  pbmsg);

函数 _bmsgDelete 的原型分析：

• 参数 pbmsg 为消息缓冲区指针。

# 成块消息缓冲区读写函数

函数 _bmsgGet 的功能是读成块消息缓冲区，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针、读出的消息存放位置的首地址和需要读出的消息长度。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgGet (PLW_BMSG  pbmsg, CPVOID  pvMsg, size_t  stSize)

函数 _bmsgGet 的原型分析：

• 函数的返回值为写入的字节数。
• pbmsg 参数是消息缓冲区结构体的指针。
• pvMsg 参数是读出的消息存放位置的地址。
• stSize 参数是要接收消息的长度。

函数 _bmsgPut 的功能是写成块消息缓冲区，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针、写入的消息存放位置的首地址和需要写入的消息长度。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgPut (PLW_BMSG  pbmsg, CPVOID  pvMsg,  size_t  stSize);

函数 _bmsgPut 的原型分析：

• 函数的返回值为写入的字符数。
• pbmsg 参数是消息缓冲区结构体的指针。
• pvMsg 参数是需要写入的消息存放位置的首地址。
• stSize 参数是消息的长度。

# 成块消息缓冲区管理函数

函数 _bmsgFlush 的功能是清空成块消息缓冲区，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
VOID _bmsgFlush  (PLW_BMSG  pbmsg);

函数 _bmsgFlush 的原型分析：

• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgIsEmpty 的功能是判断缓冲区是否为空，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgIsEmpty (PLW_BMSG  pbmsg);

函数 _bmsgIsEmpty 的原型分析：

• 函数成功时返回 LW_TRUE ，失败时返回 LW_FALSE 。
• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgIsFull 的功能是判断缓冲区是否已满，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgIsFull (PLW_BMSG  pbmsg)

函数 _bmsgIsFull 的原型分析：

• 函数成功时返回 LW_TRUE ，失败时返回 LW_FALSE 。
• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgSizeGet 的功能是获取缓冲区大小，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgSizeGet(PLW_BMSG  pbmsg)

函数 _bmsgSizeGet 的原型分析：

• 函数的返回值为缓冲区大小。
• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgFreeByte 的功能是获取缓冲区剩余空间的大小，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgFreeByte (PLW_BMSG  pbmsg)

函数 _bmsgFreeByte 的原型分析：

• 函数的返回值为缓冲区剩余空间大小。
• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgNBytes 的功能是获取缓冲区已经使用的字节数，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgNBytes(PLW_BMSG  pbmsg)

函数 _bmsgNBytes 的原型分析：

• 函数的返回值为缓冲区已经使用的字节数。
• pbmsg 参数是消息缓冲区结构体的指针。

函数 _bmsgNBytesNext 的功能是获取缓冲区下一条信息字节长度，用户需要提供的参数是已创建的成块消息缓冲区的结构体指针。其详细描述如下：

#include <SylixOS.h>
INT  _bmsgFreeByte (PLW_BMSG  pbmsg)

函数 msgNBytesNext 的原型分析：

• 函数的返回值为缓冲区下一条信息的字节长度。
• pbmsg 参数是息缓冲区结构体的指针。

网络事件管理网络消息文件使用了成块消息管理，网络事件函数接口在“libsylixos/net/lwip/lwip_netevent.c”文件中。