1.引言    

本文描述了第三方系统如何与用户上下线消息服务接口对接，并提供可能遇到问题的解决方法。具体文档可到RTR系统下载或致电4008111000索要。

本文的大致结构如下：

1.  第一章引言。

2.  第二章介绍了用户上下线消息协议。

3.  第三章介绍了与用户上下线消息服务对接的开发Demo。

1.1.    编写目的

本手册用于指导第三方开发人员利用在线用户上下线消息对接接口(TCP-SOCKET)接收在线用户上下消息，并基于在线用户上下线消息进行二次开发。

本手册的阅读对象为需要采用在线用户上下线消息对接接口(TCP-SOCKET)，完成二次开发的设计人员与编码人员。

1.2.    背景说明

本手册适用产品：RG-SMP_专业版/RG-ESS

1.3.    术语定义

名词

解释

备注

TLV

一种可变格式，TLV的意思就是：Type类型， Length长度，Value值。

       

SOCKET

1.   Socket通常也称作"套接字"，应用程序通常通过"套接字"向网络发出请求或者应答网络请求。

2.         套接字之间的连接过程可以分为三个步骤：服务器监听，客户端请求，连接确认。

3.         流式是一种面向连接的Socket，针对于面向连接的TCP服务应用。（也就是下面的TCP-SOCKET）

       

Hello机制

一种保活机制，通过定期发送Hello消息来保持通信双方的通信连接。

       

1.4.    概述

基于TCP-SOCKET的在线用户上下线消息对接接口，可以很好的解决开发人员在开发接收在线用户上下线消息时受编程语言约束的问题。开发人员可以自由选择编程语言来实现TCP-SOCKET来实现对接。

   

2.用户上下线消息协议    

2.1.    消息报文定义

Length

Attribute(TLV)

....

l      Length：4个字节，TCP报文总长度，包括：Length、所有Attribute内容

l      Attribute：每个Attribute都是一个TLV根式的数据，其中：T(Type)为数据类型，L(Length)表示整个属性内容的长度包括Type/Length，长度为1字节。V(Value)表示为数据内容，数据内容全部为UTF-8编码的字符串。

l      一个消息报文可以包含多个Attribute，但是至少需要包含一个表示消息类型(Type=0)的Attribute

例如：Hello消息报文内容：00000007000301，其中Length=00000007，为整个报文的长度7个字节，包括Length与Attribute的长度，000301为一个TLV，表示类型=00，属性长度=03，属性值=01。

2.1.1.   Hello消息

Hello消息包含的属性列表：

Type

Length

是否必填

说明

0

1字节

是

消息类型，值取0x01，表示Hello消息

2.1.2.   上下线消息

Type

Length

是否必填        

说明

 

0

1字节

是

消息类型

0x02，表示上线消息

0x03，表示下线消息

 

1

可变长度

是

用户名

 

 

2

可变长度

是

用户姓名

 

3

可变长度

是

用户组

 

4

可变长度

否

用户IP

 

5

可变长度

否

用户MAC

 

6

可变长度

是

设备IP

 

7

可变长度

否

设备端口

 

8

可变长度

否

VLAN ID

 

9

可变长度

否

网关IP

 

10

可变长度

否

固定电话

 

11

可变长度

否

移动电话

 

12

可变长度

否

证件类型

 

13

可变长度

否

证件号码

 

14

可变长度

否

住址

 

15

可变长度

是

上线时间，1970年开始的毫秒数(上线消息才有)

 

16

可变长度

是

下线时间，1970年开始的毫秒数(下线消息才有)

 

17

1字节

否

用户安全状态，只在上线通知中存在

0表示失败

1表示成功

 

18

1字节

是

用户对应的接入方式

1：有线1X接入

2：有线WebPortal接入

3：无线1X接入

4：无线WebPortal接入

5：VPN拨号接入

 

19

可变长度

否

无线AP的MAC

 

20

可变长度

否

无线SSID










2.2.    报文交互过程

2.2.1.   通信方式及通信端口

在线用户上下线消息服务与第三方系统之间是通过TCP报文进行交互的。

在线用户上下线消息服务的默认端口：10001（可配置）。

第三方系统通过与RG-SMP/RG-ESS服务器的TCP端口(10001)建立TCP连接，来接收在线用户上下线消息。当有在线用户上下线时，RG-SMP/RG-ESS通过该TCP连接向第三方系统发送上下线消息。

2.2.2.   定时Hello机制

第三方系统与RG-SMP/RG-ESS服务器建立TCP连接后，RG-SMP/RG-ESS服务器会定时(默认5分钟，可配置)发送Hello消息给第三方系统，而第三方系统在收到Hello消息后必须给RG-SMP/RG-ESS服务器发送Hello消息来应答。通过这种机制来保持第三方系统与RG-SMP/RG-ESS服务器之间的TCP连接。如果超过连续3次RG-SMP/RG-ESS服务器发送Hello消息，但没有接收到第三方系统响应的Hello报文，RG-SMP/RG-ESS服务器认为TCP连接超时，则会主动关闭TCP连接。因此，第三方系统自身也需要有检测服务端是否与自己断开了连接。

2.2.3.   交互过程

   

1.    RG-SMP/RG-ESS在线用户上下线消息服务开启。端口默认绑定10001端口，Hello检测周期为5分钟(默认的周期时间)。

2.    RG-SMP/RG-ESS在线用户上下消息服务监听10001端口，等待第三方系统的连接。

3.    第三方系统通过TCP-SOCKET连接RG-SMP/RG-ESS在线用户上下线消息服务。

4.    RG-SMP/RG-ESS在线用户上下线消息服务向第三方系统发送Hello消息报文。第三方系统收到Hello消息报文后，要向RG-SMP/RG-ESS响应 Hello消息报文。

5.    用户上线，RG-SMP/RG-ESS在线用户上下线消息服务向第三方系统发送用户上线消息报文。

6.    用户下线，RG-SMP/RG-ESS在线用户上下线消息服务向第三方系统发送用户下线消息报文。

   

3.   对接上下线消息服务的Demo    

运用JAVA语言开发的Demo参见附件在线用户上下线消息-DEMO.zip