四. SECS/GEM封装库RapidSecs开发手记-基础库开发-2

5.命名空间

5.1 空间结构

四. SECS/GEM封装库RapidSecs开发手记-基础库开发-2_第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服务创建失败(bindlisten)。

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

连接有效。

连接处于HSMSconnected状态。

注:可能是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 messagefunction为偶数)。

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 messagefunction为奇数)。

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

发送数据的长度。

你可能感兴趣的:(SECS/GEM实战)