四. SECS/GEM封装库RapidSecs开发手记-基础库开发-2
5.命名空间
5.1 空间结构
5.2 HSMS
此命名空间中的类主要处理和HSMS协议相关的操作。
5.2.1 类HsmsClient
从Socket类派生，HSMS的被动模式使用的类。主要接口如下：
| 主要接口 |
接口功能 |
| Accept |
接受连接 |
| Connect |
建立连接 |
| Send |
发送数据 |
| OnRecv |
接收数据 |
| OnTimer |
超时处理 |
| OnClose |
关闭连接 |
| 主要成员 |
|
| m_pHs |
HsmsServer对象指针 |
| m_sSet |
RAPID_SECS_CFG对象 |
5.2.2类HsmsServer
从Socket类派生，HSMS的主动模式使用的类。主要接口如下：
| 主要接口 |
接口功能 |
| StartupServer |
开始服务 |
| CloseServer |
关闭服务 |
| 主要成员 |
|
| m_bRuning |
服务是否运行 |
| m_sSet |
RAPID_SECS_CFG对象 |
5.2.3类HsmsFun
处理Hsms的每一次会话消息内容，包括：消息头（10字节）+数据（N字节）。主要用于解析消息头中的各个字段。主要接口如下：
| 主要接口 |
接口功能 |
| DevId |
获取设备ID |
| MsgId |
获取消息ID |
| Str |
获取Stream代码 |
| Fun |
获取Function代码 |
| PType |
获取PType |
| SType |
获取SType |
| IsNeedReply |
判断是否需要响应 |
| Buffer |
消息缓冲区 |
| Length |
消息长度 |
| Data |
数据缓冲区 |
| Size |
数据长度 |
| 主要成员 |
|
| m_pMsgBuf |
LPHSMS_DATA_BUFFER消息缓冲区 |
5.2.4 类SessionManager
用于管理主机和设备间的会话连接。主要接口如下：
| 主要接口 |
接口功能 |
| RegisterSession |
开始服务 |
| UnregisterSession |
关闭服务 |
| FindSessionHolder |
|
| 主要成员 |
|
| m_map_sessions |
MAP_SESSION_HOLDER对象，会话映射表。 |
5.3 SECS
此命名空间中的类主要处理和SECS-II协议相关的操作。
5.3.1 类SecsClient
此类从HsmsClient派生，用于被动模式下的必要的进一步处理SECS消息的接收和应答。主要接口如下：
| 主要接口 |
接口功能 |
| GetRemoteIpAddr |
获取目标主机IP地址 |
| GetRemotePort |
获取目标主机端口号 |
| SendRequest |
发送命令请求 |
| SendReply |
发送响应命令 |
| OnRecv |
接收数据 |
5.3.2 类SecsServer
此类从HsmsServer派生，用于主动模式下的SECS消息的进一步处理。主要接口如下：
| 主要接口 |
接口功能 |
| GetLocalIpAddr |
获取本地IP地址 |
| GetLocalPort |
获取本地端口号 |
| GetMode |
获取当前模式（Active/Passive） |
5.4 sml
SECS消息语言，用于描述SECS-II消息内容的符号语言。主要用于打印消息时使用，便于查看具体的消息内容。
此部分主要定义的是一些全局的API接口函数，主要接口如下：
| 主要接口 |
接口功能 |
| EncodeSML |
将数据编码成SML格式 |
| DecodeSML |
将SML格式数据解码 |
5.5 os_utils
此命名空间中定义的是一些公用的类、接口、对象。只介绍2个比较重要的。
5.5.1 类Socket
对socket相关API的封装类，用于处理socket通讯。主要接口如下：
| 主要接口 |
接口功能 |
| Accept |
接受连接 |
| Connect |
建立连接 |
| Listen |
监听连接 |
| Send |
发送数据 |
| __AcceptProc |
接受连接线程 |
| _RecvProc |
接收数据线程 |
| 主要成员 |
|
| m_sock |
SOCKET对象 |
5.5.2 类Timer
此类用于HSMS协议中规定的几种超时的管理。主要接口如下：
| 主要接口 |
接口功能 |
| SetTimer |
设置定时器 |
| KillTimer |
移除特定定时器 |
| ClearTimer |
清除所有定时器 |
5.6 全局接口函数
5.6.1 通信管理函数
1.rapid_create_secs
创建SECS连接对象。
输入参数包括IP地址、端口号、超时控制、回调函数指针等。
语法：
| RAPID_SECS_API RSECSH rapid_create_secs( RAPID_SECS_CFG* cfg_info ); |
参数：
cfg_info
[in] SECS对象的配置信息。
返回值：
| 值 |
描述 |
| > 0 |
新创建的SECS对象句柄. |
| NULL |
创建失败。 可能原因：运行许可缺失。 |
2.rapid_destroy_secs
释放SECS连接对象。
语法：
| RAPID_SECS_API VOID rapid_destroy_secs( RSECSH session_h ); |
参数：
session_h
[in] 要释放的连接对象句柄。
返回值：
| 值 |
描述 |
| 无。 |
|
3.rapid_secs_startup_server
启动HSMS服务。（PASSIVE MODE）
语法：
| RAPID_SECS_API BOOL rapid_secs_startup_server( RSECSH session_h ); |
参数：
session_h
[in] 之前通过rapid_create_secs创建的HSMS连接对象句柄。必须为HSMS_PASSIVE模式。
返回值：
| 值 |
描述 |
| TRUE |
HSMS服务启动成功。 |
| FALSE |
HSMS服务启动失败。 可能原因： 无效的连接句柄。 TCP服务创建失败（bind或listen）。 |
4.rapid_secs_close_server
停止HSMS服务。仅对HSMS_PASSIVE模式有效。
语法：
| RAPID_SECS_API VOID rapid_secs_close_server( RSECSH session_h ); |
参数：
session_h
[in] 要停止的HSMS服务对象句柄。
返回值：
| 值 |
描述 |
| 无。 |
|
5.rapid_secs_connect
在主动模式（Active Mode）下，开始HSMS连接。
调用此函数后，RapidSecs库会自动维持该HSMS通信对象的连接。即，当连接异常断开发生后，会自动尝试重新连接，直到调用rapid_secs_disconnect之后为止。重新连接的时间间隔为T5（Seperation Timeout，E37-1109, 4.1.29）。
语法：
| RAPID_SECS_API BOOL rapid_secs_connect( RSECSH session_h ); |
参数：
session_h
[in] 要连接的HSMS连接对象句柄。之前通过rapid_create_secs创建，必须为HSMS_ACTIVE模式。
返回值：
| 值 |
描述 |
| TRUE |
连接成功。 |
| FALSE |
连接失败。可能原因： 无效的连接对象句柄。 连接已经建立。 TCP连接失败。（connect返回错误） |
6.rapid_secs_disconnect
断开HSMS连接。
语法：
| RAPID_SECS_API void rapid_secs_disconnect( RSECSH session_h ); |
参数：
session_h
[in] 要断开的HSMS连接对象句柄。仅对HSMS_ACTIVE模式有效。
返回值：
| 值 |
描述 |
| 无。 |
|
7.rapid_if_secs_connect
判断连接状态。
语法：
| RAPID_SECS_API BOOL rapid_if_secs_connect( RSECSH session_h ); |
参数：
session_h
[in] HSMS连接对象句柄。
返回值：
| 值 |
描述 |
| TRUE |
连接有效。 连接处于HSMS的connected状态。 注：可能是not selected。 |
| FALSE |
连接已断开。 |
5.6.2 消息发送函数
1.rapid_secs_send_msg_item
消息发送接口。
语法：
| RAPID_SECS_API unsigned long rapid_secs_send_msg_item( RSECSH session_h, unsigned char stream, unsigned char function, RAPID_SECS_ITEM* ptr_item, unsigned long flags ); |
参数：
session_h
[in] HSMS连接对象句柄。
stream
[in] 要发送的消息stream。
function
[in] 要发送的消息function。
ptr_item
[in] 消息对象指针。
flags
[in] 需要对方回复时，设为RAPID_SECS_FLAGS_NEED_REPLY；不需回复时，设为0。
返回值：
| 值 |
描述 |
| > 0 |
发送成功。返回值为已发送消息的id。 |
| 0 |
发送错误。可能原因： HSMS句柄无效。 Stream无效（大于127）。 发送的消息不是primary message（function为偶数）。 socket send调用失败。 |
2.apid_secs_reply_msg_item
响应消息发送接口。
语法：
| RAPID_SECS_API unsigned long rapid_secs_reply_msg_item( RSECSH session_h, unsigned char stream, unsigned char function, RAPID_SECS_ITEM* ptr_item, unsigned long flags, unsigned long msg_id ); |
参数：
session_h
[in] HSMS连接对象句柄。
stream
[in] 要发送的消息stream。
function
[in] 要发送的消息function。
ptr_item
[in] 消息对象指针。
flags
[in] 此参数需设为0。
msg_id
[in] 对应的primary消息id。
返回值：
| 值 |
描述 |
|
| > 0 |
发送成功。返回值为已发送消息的id。 |
|
| 0 |
发送错误。可能原因： HSMS句柄无效。 Stream无效（大于127）。 发送的消息不是secondary message（function为奇数）。 socket send调用失败。 |
|
5.6.3 消息处理函数
1.rapid_secs_create_item_list
创建列表类型消息。
注：list_size仅表示预分配的列表长度，以后向列表添加元素时不受此长度限制。超出长度时会自动分配空间。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_list( int list_size ); |
参数：
list_size
[in] 预分配的列表长度。
返回值：
| 值 |
描述 |
| > 0 |
列表类型消息对象指针。 |
2.rapid_secs_create_item_binary
创建二进制类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_binary( const char* data, int data_len ); |
参数：
data
[in] 指向二进制消息内容的指针。
data_len
[in] 二进制消息数据长度（字节）。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
3.rapid_secs_create_item_boolean
创建布尔类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_boolean( bool data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
4.rapid_secs_create_item_ascii
创建ASCII类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_ascii( const char* data ); |
参数：
data
[in] 消息对象初始值，应为以 ’\0’ 结尾的ASCII字符串。
注：如ASCII字符串长度为0，此参数应为””，不可传递空值NULL。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
5.rapid_secs_create_item_jis8
创建JIS8类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_jis8( const char* data, int data_len ); |
参数：
data
[in] 消息对象初始值。
data_len
[in] 数据长度。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
6.rapid_secs_create_item_2bytes
创建双字节字符(串)类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_2bytes( const char* data, int data_len ); |
参数：
data
[in] 消息对象初始值。
data_len
[in] 数据长度（应为字节数，并非双字节字符数）。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
7.rapid_secs_create_item_i1
创建1字节有符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_i1( char data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
8.rapid_secs_create_item_i2
创建2字节有符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_i2 ( short data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
9.rapid_secs_create_item_i4
创建4字节有符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_i4 ( int data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
10.rapid_secs_create_item_i8
创建8字节有符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_i8 ( __int64 data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
11.rapid_secs_create_item_u1
创建1字节无符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_u1 ( unsigned char data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
12.rapid_secs_create_item_u2
创建2字节无符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_u2 ( unsigned short data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
13.rapid_secs_create_item_u4
创建4字节无符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_u4 ( unsigned int data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
14.rapid_secs_create_item_u8
创建8字节无符号整数类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_u8 ( unsigned __int64 data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
15.rapid_secs_create_item_f4
创建4字节单精度浮点类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_f4 ( float data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
16.rapid_secs_create_item_f8
创建8字节双精度浮点类型消息。
语法：
| RAPID_SECS_API RAPID_SECS_ITEM* rapid_secs_create_item_f8 ( double data ); |
参数：
data
[in] 消息对象初始值。
返回值：
| 值 |
描述 |
| > 0 |
消息对象指针。 |
17.rapid_secs_list_item_append
在列表类型消息对象中添加元素。
语法：
| RAPID_SECS_API BOOL rapid_secs_list_item_append( RAPID_SECS_ITEM* ptr_list_item, RAPID_SECS_ITEM* ptr_sub_item ); |
参数：
ptr_list_item
[in] 列表对象指针。
ptr_sub_item
[in] 要添加到列表中的消息对象指针。
返回值：
| 值 |
描述 |
| TRUE |
添加成功。 |
| FALSE |
添加失败。可能原因： 向非列表对象添加元素。 |
18.rapid_secs_del_item
删除消息对象。
所有用rapid_secs_create_xxx函数创建的消息对象，在不需要继续使用时，都必须调用rapid_secs_del_item删除该对象，以释放相关资源。
语法：
| RAPID_SECS_API void rapid_secs_del_item( RAPID_SECS_ITEM* ptr_secs_item ); |
参数：
ptr_secs_item
[in] 要删除的消息对象指针。
返回值：
| 值 |
描述 |
| 无。 |
|
19.rapid_secs_send_msg_buf
发送消息缓冲区数据，主要用于C#库封装时使用。
由于apid_secs_create_xxx函数接口都包含有C++的数据结构在C#封装时调用很不方便，因此提供此接口函数将缓冲区数据发送到C#中进行处理。用户在实际使用中不需要进行调用。
5.6.4 回调接口函数
回调接口函数，用于触发用户自定义的处理机制。包括接收消息、连接建立、断开、接收消息超时等。
1.rapid_secs_on_connect
连接建立事件回调函数。
PASSIVE模式下，当有新的连接进入时，触发此回调。
ACTIVE模式下，rapid_secs_connect函数连接成功，或者是后来的重连成功时，都会触发此回调。
语法：
| typedef BOOL (__stdcall *rapid_secs_on_connect)( RSECSH server_h, RSECSH session_h, unsigned short device_id ); |
参数：
server_h
[in] PASSIVE模式下，为HSMS服务句柄。ACTIVE模式下，为NULL。
session_h
[in] 新创建的HSMS连接句柄。后续的消息收发都基于此句柄进行。
device_id
[in] 设备id。
返回值：
| 值 |
描述 |
| TRUE |
表示接受此连接。 |
| FALSE |
拒绝连接，此连接将断开。 |
注：ACTIVE模式下，将忽略此返回值。
2.rapid_secs_on_close
连接断开事件回调函数。
PASSIVE和ACTIVE模式下的连接断开，都会触发此回调。
语法：
| typedef VOID (__stdcall *rapid_secs_on_close)( RSECSH session_h ); |
参数：
session_h
[in] 已断开的HSMS连接句柄。
返回值：
| 值 |
描述 |
| 无。 |
|
3.rapid_secs_on_recv_msg
接收到消息后触发的回调。用户可在此进行相关处理，比如回应消息、执行操作等。
语法：
| typedef DWORD (__stdcall *rapid_secs_on_recv_msg)( RSECSH session_h, unsigned long message_id, unsigned char stream, unsigned char function, RAPID_SECS_ITEM* ptr_secs_item ); |
参数：
session_h
[in] HSMS连接对象句柄。
message_id
[in] 接收到的消息id。
stream
[in] 接收到的消息stream。
function
[in] 接收到的消息function。
ptr_ secs_item
[in] 接收到的消息对象指针。
返回值：
| 值 |
描述 |
| RAPID_SECS_SUCCESS |
表示消息处理成功。 |
| RAPID_SECS _ERROR_USN |
不支持此消息的stream。返回此值后，RapidSecs库将自动发送S9,F3消息给对方。 |
| RAPID_SECS _ERROR_UFN |
不支持此消息的function。返回此值后，RapidSecs库将自动发送S9,F5消息给对方。 |
| RAPID_SECS _ERROR_IDN |
消息数据错误。返回此值后，RapidSecs库将自动发送S9,F7消息给对方。 |
4.rapid_secs_on_msg_reply_timeout
当之前发送的消息在T3时间内没收到回应时，RapidSecs库触发此回调。
语法：
| typedef void (__stdcall *rapid_secs_on_msg_reply_timeout)( RSECSH session_h, unsigned long message_id); |
参数：
session_h
[in] HSMS连接对象句柄。
message_id
[in] 回应超时的消息id。
返回值：
| 值 |
描述 |
| 无。 |
|
5.5.5 其它接口函数
1.rapid_secs_send_msg_buf
数据发送缓冲区，此接口函数用于C#封装时使用。
语法：
| RAPID_SECS_API unsigned long rapid_secs_send_msg_buf(RSECSH session_h, unsigned char stream, unsigned char function, const char* ptr_data, int data_length, unsigned long flags, unsigned long msg_id); |
参数：
session_h
[in] HSMS连接对象句柄。
stream
[in] Sx。
function
[in] Fx。
ptr_data
[in] 要发送的数据指针。
data_length
[in] 要发送的数据长度。
flags
[in] 标识是否需要响应。
msg_id
[in] 消息id。
返回值：
| 值 |
描述 |
| >0 |
发送数据的长度。 |