四. 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	发送数据的长度。