协议编程基础知识模板.docx

TR069协议编程需掌握知识
TR069
1、 TR069协议是由DSL所开发技术规范, 它提供了对网络设备进行管理配置通用框架和协议, 用于从网络侧对网关、 FEMTO、 路由器等设备进行远程管理。目前在统一网管实现过程中需要处理TR069协议包数据, 为了能够正确处理设备请求响应, 就必需对TR069协议包数据内容有所了解。
协议组成
2、 协议组成以下图

层描述:

3、 我们所关心层关键是RPC Methods层、 SOAP层以及HTTP层。下面具体介绍RPC Methods层内容, 首先我们需要知道ACS和CPE建立连接方法。
这里列出封装RPC方法SOAP信息格式。了解它们有利于组包解包。

ACS与CPE连接建立
4、 ACS和CPE连接建立:
ACS与CPE建立连接方法, 按连接提议方划分能够分为两种方法: CPE提议连接、 ACS主动建立连接
CPE提议连接有以下多个情况:
（1） CPE第一次建立网络连接, 对应RPC命令INFORM +"0 BOOTSTRAP";
（2） 加电或者重置, 对应RPC命令INFORM +"1 BOOT"
（3） 每个周期上报时间, 对应RPC命令INFORM +"2 PERIODIC"
（4） 可选Schedule Inform方法被要求, 对应RPC命令是是INFORM+"3 SCHEDULED"
（5） CPE接收到来自ACS有效连接请求, 对应RPC命令INFORM +"6 CONNECTION REQUEST"
（6） ACSURL发生改变, 对应RPC命令是对应RPC命令INFORM +"0 BOOTSTRAP"
（7） CPE参数发生更改, 如CPEIP地址;
（8） CPE参数值发生改变, 而且这个改变不是由ACS引发, 对应对应RPC命令是INFORM +"4 VALUE CHANGE"
CPE与ACS连接示意图以下:

ACS提议连接:
ACS向CPE提议连接经过HTTP GET请求;
（1）需要注意是连接使用必需是HTTP请求而不是HTTPS
（2）而且GET通告中不需要包含其它数据, 即使有数据也会被CPE忽略。
（3）CPE接到GET请求后与ACS建立连接, 并在成功建立连接后发送一条INFORM报文。
连接建立示意图

ACS与CPE之间结束会话:
ACS与CPE之间会话假如要正常结束需要以下条件:
（1）CPE不再有请求发给ACS
（2）ACS也没有请求发给CPE
（3）CPE已经发送完成ACS请求响应
（4）ACS已经发送完成CPE请求响应

RPC方法
方法列表

方法介绍
1、 Inform信息: 由CPE传送到网管, CPE事件经过绑定Inform信息进行上报; 事件EVENT_CODE有
（1）"0 BOOTSTRAP",表示会话提议原因是CPE首次安装或者是ACSURL发生改变。网管接收到后要实施注册步骤
（2）"1 BOOT",表示会话提议原因是CPE通电开启或者是重置, 包含系统首次开启, 以及任何原因引发重启, 或者是事件"M Reboot"引发;
（3）"2 PERIODIC",表示会话提议原因是因为定时Inform策略引发。
（4）"3 SCHEDULED", 表示会话提议原因是因为CPE定时调用了ScheduleInform方法引发。该EVENT_CODE必需位于"M ScheduleInform"中。
（5）"4 VALUE CHANGE",表示会话提议原因是CPE一个或者多个参数值发生改变。
（6）"5 KICKED",表示会话提议原因是为了Web标识管理（ ？）
（7）"6 CONNECTION REQUEST",表示会话提议原因是源自ACSConnection Request Notification
（8）"7 TRANSFER COMPLETE",表示会话提议原因是上传或者下载成功（不管是否真成功）
（9）"8 DIAGNOSTICS COMPLETE",当完成由ACS要求诊疗测试后, 重新与ACS建立连接时用
（10）"9 REQUEST DOWNLOAD",表示会话提议原因是CPE要求调用RequestDownload方法
（11） "10 AUTONOMOUS TRANSFER COMPLETE",表示会话提议原因是由CPE主动上传或者下载成功, 而不是ACS请求
（11）"M Reboot", "M ScheduleInform", "M Download","M Upload", 带有“M“字符说明这个是实施ACS请求方法结果, 里面通常含有其它EVENT_CODE; 如: "M Reboot"含有"1 BOOT", "M ScheduleInform"含有"3 SCHEDULED"
（12）"X_CU_ALARM","X_DISCOVER"厂商自定以规范前者表示告警信息, 后者表示发觉信息
2、 GetParameterNames: 由ACS提议, 用于发觉CPE上可访问参数。
包含到数据表有
命令请求操作处理: CO_RTU,CO_PROTOCOL, CO_CHANEL; 回应信息处理: CO_PARAM_LIST, CO_NE_PARAM,CO_CWMP_PARAM_LIST
3、 GetParameterValues : 由ACS提议, 用于查找CPE上一个或者多个参数值。
4、 SetParameterAttributes: 由ACS提议, 用于修改CPE上一个或者多个参数属性。
5、 SetParameterValues: 由ACS提议, 用于修改CPE上一个或者多个参数值。
6、 AddObject: 由ACS提议, 用于对一个特定多实例对象创建一个新实例。
7、 DeleteObject: 由ACS提议, 用于删除一个对象特定实例
8、 Reboot: 由ACS提议, 用于重启指定CPE终端
9、 DownLoad: 由ACS提议, 用于要求CPE终端在指定位置下载指定文件
10、 Upload: 由ACS提议, 用于要求CPE终端向指定位置上传某一特定文件
11、 FactoryReset: 由ACS提议, 用于要求特定CPE终端恢复出厂设置。
12、 GetRpcMethods由CPE或者是ACS提议, 用于发觉另一方所支持方法集。
方法参数详解
1 INFORM参数
内容见下表:
参数
类型
描述
DeviceID
DeviceIdStruct
Manufactucer,OUI,ProductClass(用于标识产品或者产品类型),SerialNumber
Event
EventStruct
说明引发会话建立一个或者多个事件
MaxEnvelope
Unsignedint
CPE能够从ACS接收一个HTTP回复中最大SOAP信包数目。若为0则说明没有限制
CurrentTime
dateTime
CPE目前日期时间
RetryCount
Unsignedint
在完成对inform方法调用前, 进行进行了多少次调用尝试, 在每次非成功尝试后增加1。非成功尝试包含发送Inform报文以及与ACS建立连接, 或每次对Inform报文不成功调用, 如: 接收到错误应答或没有接收应答。在已经发送了Inform报文并成功得到应答后该值被重置为0
ParameterList
ParameterValueStruct
CPE在Inform请求中包含参数信息表, 每次上报必需包含部分参数: 硬件版本、 软件版本、 ManagementServer.ConnectionRequestURL、 CommandKey等
2 GetRpcMethods参数
内容见下表
参数
类型
描述

该方法没有调用参数

3 GetRpcMethodsResponse参数
参数
类型
描述
MethodList
String()[]
字符串数组, 包含支持每一个RPC名称。比如: CPE返回方法列表给ACS:
“GetRPCMethods”
“SetParameterValues”
“GetParameterValues”
“SetParameterNames”
“GetParameterNames”
“AddObject”
“DeleteObject”
“Reboot”

4 SetParameterValues参数
参数
类型
描述
ParameterList
ParamterValueStruct[]
一个Name-Value键值对数组。对每个Name-Value CPE会将对应参数到值设为指定值
ParameterKey
String(32)
设置ParameterKey参数值。该值能够用于acs, 来识别参数更新, 或者让其为空
5 SetParameterValuesResponse参数
参数
类型
描述
Status
int[0:1]
对该方法成功应答返回一个整数型枚举值定义以下:
0 = 参数改动已经验证并应用。
1 = 参数改动已经验证并提交, 只是还未应用（比如, 在新参数值应用前需要进行重新开启）。

6 ParameterValueStruct定义
参数
类型
描述
Name
string(256)
参数名称。
Value
任意类型
需要设置值
7 GetParameterNames 参数
参数
类型
描述
ParameterPath
string(256)
包含一个完整参数名或部分路径名字符串, 代表名称层次一个子集。空字符串代表名称空间顶层。部分路径名必需在层次中最终一个节点名称后面以“.”（点）结尾。
下面是完整参数名例子:
InternetGatewayDevice.DeviceInfo.SerialNumber
下面是部分路径名一个例子:
InternetGatewayDevice.DeviceInfo.
NextLevel
boolean
假如值为false, 则CPE响应将列出全部以ParameterPath参数指定字符串开始参数完整路径名。
假如值为true, 则CPE响应只列出指定ParameterPath下一层部分路径名。比如, 假如ParameterPath是“InternetGatewayDevice.LANDevice.”, 响应可能列出“InternetGatewayDevice.LANDevice.1. ”和“InternetGatewayDevice.LANDevice.2. ”, 而不会列出在该层次下面全部参数。
8 GetParameterNamesResponse参数
参数
类型
描述
ParameterList
ParameterInfoStruct[]
结构数组, 每个包含一个参数名称和其它信息, 见下表定义。当NextLevel是false时, 这一方法返回全部名称以ParameterPath参数指定字符串开头全部可访问参数及其信息。假如ParameterPath参数是一个空字符串, 则将返回该CPE上全部可访问参数名称。当NextLevel是true时, 这一列表包含以ParameterPath指明路径下一层全部部分路径名。
9 ParameterInfoStruct参数
参数
类型
描述
Name
string(256)
这是参数名称或部分路径名。
Writable
boolean
是否该参数值能够用SetParameterValues方法来覆盖。
假如因NextLevel值为true, 该名称是一个部分路径名, 则表明是否AddObject和DeleteObject能够被用于该层次来移除该实例或增加其它实例。
10 SetParameterAttributes参数
参数
类型
描述
ParameterList
SetParameterAttributesStruct[]
列出用于更改一组参数属性改动值。该数组中每项条目是一个SetParameterAttributesStruct结构, 在下表中定义。
11 SetParameterAttributesStruct参数
参数
类型
描述
Name
string(256)
这是应用新属性参数名称。另一个方法是, 该名称能够是一个部分路径名, 表明新属性应该应用于命名层次中该节点下全部参数。部分路径名必需在层次中最终一个节点名称后面以“.”（点）结尾。空字符串代表名称空间顶层。
NotificationChange
boolean
假如为true, Notification值将替换该参数或参数组目前notification设置。
假如是false, 则不作任何notification设置改动。
Notification
int[0:2]
指定是否CPE应该将指定该（或多个）参数改变值放到其Inform报文中, 以及是否当指定参数值发生改变时, CPE应该提议一个到ACS会话。值定义以下:
0 = Notification关闭。 CPE无须经过ACS指定参数改变。
1 = 被动式Notification。当指定参数值改变时, CPE必需在下一次建立与ACS会话时, 将这一新值包含在Inform报文ParameterList中。
2 = 主动式Notification。一旦指定参数值发生改变, CPE必需提议与ACS会话, 将新值包含在对应Inform报文ParameterList中。
因非零Notification设置引发发送Inform报文中参数发生改变, 事件代码“4 VALUE CHANGE”必需包含在事件列表中。
假如试图给一个不适合设置notification值参数（比如一个连续改变统计值）设置notification值, CPE能够返回一个“notification request rejected”错误。
AccessListChange
boolean
假如为true, AccessList值会替换该参数或参数组目前access list值。假如为false, access list不作改动。
AccessList
String(64)[]
零个或多个实体数组, 该实体对指定参数有写权限。假如数组中不包含条目, 则只许可ACS有写权限。现在, 只定义了一类实体能够包含在该列表中:
“Subscriber” 指明由LAN上Subscriber控制设备拥有写权限。比如经过LAN端DSL CPE配置协议或经过UPnP。
默认情况下, 在ACS对access list作改动前, 上述全部实体应该被给予写访问权。
12 SetParameterAttributesResponse参数
参数
类型
描述
-
void
该方法应答没有参数。
13 GetParameterAttributes参数
参数
类型
描述
ParameterNames
string(256)[]
字符串数组, 每一条对应所请求参数名称。
假如参数名是以部分路径名方法出现, 则该请求需被解释为请求返回命名层次中共用相同前缀该分支全部参数。部分路径名必需在层次最终一个节点名称后面以“.”（点）结尾。空字符串代表整个层次名称顶部。
下面是完整参数名称例子:
InternetGatewayDevice.DeviceInfo.SerialNumber
下面是部分路径名称例子:
InternetGatewayDevice.DeviceInfo.
14 GetParameterAttributesResponse参数
参数
类型
描述
ParameterList
ParameterAttributeStruct[]
列示指定参数集access control信息。该数组中每一条目是一个ParameterAcessStruct结构, 在下表中定义。
15 ParameterAttributesStruct参数
参数
类型
描述
Name
string(256)
这是给出属性值参数名称。
Notification
int[0:2]
指定是否CPE应该将指定该（或多个）参数改变值放到其Inform报文中, 以及是否当指定参数值发生改变时, CPE应该提议一个到ACS会话。值定义以下:
0 = Notification关闭。 CPE无须经过ACS指定参数改变。
1 = 被动式Notification。当指定参数值改变时, CPE必需在下一次建立与ACS会话时, 将这一新值包含在Inform报文ParameterList中。
2 = 主动式Notification。一旦指定参数值发生改变, CPE必需提议与ACS会话, 将新值包含在对应Inform报文ParameterList中。
AccessList
string(64)[]
零个或多个实体数组, 该实体对指定参数有写权限。假如数组中不包含条目, 则只许可ACS有写权限。现在, 只定义了一类实体能够包含在该列表中:
“Subscriber” 指明由LAN上Subscriber控制设备拥有写权限。比如经过LAN端DSL CPE配置协议或经过UPnP。
16 AddObject参数
参数
类型
描述
objectName
string(256)
要建立新实例对象集合路径名称。路径名必需在该对象层次名称最终节点后加上“.”（点）结尾。
ParameterKey
string(32)
需要设置ParameterKey参数值。该参数由服务器决定, 并能够为空。
17 AddObjectResponse参数
参数
类型
描述
InstanceNumber
unsignedInt[1:]
新建对象实例号码。在对象建立后, 能够在路径名中使用该实例号码来引用该对象参数或子对象。由CPE指定实例号码是任意, 而且与后续AddObject调用分配号码无需连续。
CPE不应该将曾经分配出去现已删除对象使用过号码再分配给新实例。CPE应该在耗尽某指定对象整个整数值空间后再重用实例号码。
Status
int[0:1]
对该方法成功应答返回一个整数型枚举值定义以下:
0 = 对象已经建立。
1 = 对象建立已经验证并提交, 只是还未应用（比如, 增加新对象前需要进行重新开启）。
18 DeleteObject参数
参数
类型
描述
objectName
string(256)
欲删除对象实例路径名。路径名必需以对象实例号码后加“.”（点）来结尾。
ParameterKey
string(32)
需要设置ParameterKey参数值。该参数由服务器决定, 并能够为空。
19 DeleteObjectResponse参数
参数
类型
描述
Status
int[0:1]
对该方法成功应答返回一个整数型枚举值定义以下:
0 = 对象已经建立。
·1 = 对象建立已经验证并提交, 只是还未应用（比如, 增加新对象前需要进行重新开启）。
20 DownLoad 参数
参数
类型
描述
CommandKey
string(32)
CPE用来指向特定下载字符串。该参数在方法TransferComplete和GetQueuedTransfers中引用。
FileType
string(64)
一个整数, 其后是一个空格, 再其后是一个文件类型说明。现在FileType参数仅定义了以下值:
"1 Firmware Upgrade Image"
"2 Web Content"
"3 Vendor Configuration File"
下列格式用于定义唯一厂商自定义文件类型:
"X <OUI> <Vendor-specific identifier>"
其中, <OUI>用6位十六进制数字OUI（组织唯一标识）替换, 其中全部字母用大写, 包含全部前置零。
URL
string(256)
URL说明源文件位置。必需支持HTTP传输。能够支持其它可选传输方法, 如节定义。
Username
string(256)
CPE用于认证文件服务器用户名。假如不需要认证, 则该字符串设置为空串。
Password
string(256)
CPE用于认证文件服务器密码。假如不需要认证, 则该字符串设置为空串。
FileSize
unsignedInt
以字节为单位要传输文件大小。
TargetFileName
string(256)
在目标文件系统中应使用文件名。
DelaySeconds
unsignedInt
从本方法被调用到CPE被要求开始下载之间时间间隔。假如值为零表明不需要延迟。假如是非零值, 则下载不应该使用与该请求相同事务会话。
SuccessURL
string(256)
在能应用情况下, 本参数包含在下载成功完成后, CPE应该将用户浏览器重定向到哪一URL。在不需要这么URL情况下, 这一参数应该为空。
FailureURL
string(256)
在能应用情况下, 本参数包含在下载未成功完成后, CPE应该将用户浏览器重定向到哪一URL。在不需要这么URL情况下, 这一参数应该为空。
Staus
int[0:1]
对该方法成功应答返回一个整数型枚举值定义以下:
0 = 下载已结束并已应用。
1 = 下载还没有结束（比如, CPE需要重新开启后才能实施文件下载）。
假如该参数值非零, 则CPE必需在本会话后续时间, 或者在其后会话中, 调用TransferComplete方法来说明此次下载完成状态（成功或者失败）。
StartTime
dateTime
下载开始日期和时间（UTC）。只有在下载结束后该值才需要填写。
CompleteTime
dateTime
下载完全结束并应用时日期和时间（UTC）。只有在下载结束后该值才需要填写。
21 Reboot参数
参数
类型
描述
CommandKey
string(32)
当CPE重新开启并调用Inform方法时, 将在InfromStructCommandKey元素中返回该元素值。
22 RebootResponse参数
参数
类型
描述
-
void
该响应方法无参数。
23 CPE错误码
参数
描述
9000
方法不支持
9001
拒绝请求（未说明原因）
9002
内部错误
9003
无效参数
9004
资源超限（当用于SetParameterValues关联时, 它不得用来指示参数错误）
9005
无效参数名（与Set/GetParameterValues, GetParameterNames, Set/GetParameterAttributes相关）
9006
无效参数类型（与SetParameterValues相关）
9007
无效参数值（与SetParameterValues相关）
9008
试图设置不可写参数（与SetParameterValues相关）
9009
Notification请求被拒（与SetParameterAttributes方法相关）
9010
下载失败（与Download或TransferComplete方法相关）
9011
上载失败（与Upload或TransferComplete方法相关）
9012
文件传输服务器认证失败（与Upload, Download, 或TransferComplete方法相关）
9013
文件传输协议不支持（与Upload和Download方法相关）
9800 – 9899
厂约定义错误代码
24 ACS错误码
参数
描述
8000
方法不支持
8001
拒绝请求（未指明原因）
8002
内部错误
8003
无效参数
8004
资源超限
8005
重试请求
8800 - 8899
厂商自定义错误代码