TR069协议编程基础知识

TR069

TR069协议编程需掌握知识

1、 TR069协议是由DSL所开发的技术规范，它提供了对网络设备进行管理配置的通用框架

和协议，用于从网络侧对网关、FEMTO、路由器等设备进行远程管理。当前在统一网管的实现过程中需要处理TR069协议包数据，为了能够正确的处理设备的请求响应，就必须对TR069协议包数据内容有所了解。

协议组成

2、 协议组成如下图

层描述：

3、 我们所关心的层主要是RPC Methods层、SOAP层以及HTTP层。下面具体介绍RPC

Methods层的内容，首先我们需要知道ACS和CPE建立连接的方式。 这里列出封装RPC方法的SOAP信息的格式。理解它们有助于组包解包。

SOAPMessageSOAPPartSOAPEnvelopeSOAPHeader(OPTIONAL)HEADERSOAPBodyXMLContentSOAPFault(optional)

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） ACS的URL发生变化，对应的RPC命令是对应RPC命令INFORM +\"0 BOOTSTRAP\" （7） CPE的参数发生更改，如CPE的IP地址；

（8） CPE的参数值发生变化，并且这个变化不是由ACS引起的，对应对应的RPC命

令是INFORM +\"4 VALUE CHANGE\"

CPE与ACS连接示意图如下：

CPEINFORMACS401 unauthorizedInform200 OKPOST EMPTY204 NO CONTENT消息1关闭连接

ACS发起连接：

ACS向CPE发起连接通过HTTP GET请求;

（1）需要注意的是连接使用的必须是HTTP请求而不是HTTPS

（2）并且GET通告中不需要包含其它数据，即使有数据也会被CPE忽略。

（3）CPE接到GET请求后与ACS建立连接，并在成功建立连接后发送一条INFORM报文。

连接建立示意图

CPEACSHTTP GET(CONNCTION REQUEST NOTIFICATION)INFORM “6 CONNECTION REQUEST”401 unauthorizedInform200 OKPOST EMPTY204 NO CONTENT关闭连接

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首次安装或者是ACS的URL发生变化。

网管接收到后要执行注册流程

（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\表示会话发起的原因是源自ACS的Connection 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“字符说明

这个是执行ACS请求方法的结果，里面一般含有其它的EVENT_CODE；如：\"M Reboot\"含有\"1 BOOT\"，\"M ScheduleInform\"含有\"3 SCHEDULED\"

（12）\"X_CU_ALARM\厂商自定以规范前者表示告警信息，后者表示发现

信息

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 MaxEnvelope EventStruct Unsignedint 说明引发会话建立的一个或者多个事件 CPE能够从ACS接受的一个HTTP回复中的最大SOAP信包数目。若为0则说明没有 CurrentTime RetryCount dateTime Unsignedint CPE当前日期时间 在完成对inform方法的调用前，进行进行了多少次调用尝试，在每次非成功的尝试后增加1。非成功的尝试包括发送Inform报文以及与ACS建立连接，或每次对Inform的报文的不成功调用，如：接收到错误应答或没有接收应答。在已经发送了Inform报文并成功得到应答后该值被重置为0 ParameterList ParameterValueStruct CPE在Inform请求中包含的参数信息表，每次上报必须包含一些参数：硬件版本、软件版本、ManagementServer.ConnectionRequestURLCommandKey等 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 Value 类型 string(256) 任意类型 描述 参数的名称。 需要设置的值 7 GetParameterNames 参数

参数 类型 描述 包括一个完整参数名或部分路径名的字符串，代表名称层次的一个子集。空字符串代表名称空间的顶层。部分路径名必须在层次中的最后一个节点名称后面以“.”（点）结尾。 下面是完整参数名的例子： InternetGatewayDevice.DeviceInfo.SerialNumber 下面是部分路径名的一个例子： InternetGatewayDevice.DeviceInfo. NextLevel boolean 如果值为false，则CPE响应将列出所有以ParameterPath参数指定字符串开始的参数的完整路径名。 如果值为true，则CPE响应只列出指定的ParameterPath下一层的部分路径名。例如，如果ParameterPath是ParameterPath string(256) “InternetGatewayDevice.LANDevice.”，响应可能列出“InternetGatewayDevice.LANDevice.1. ”和“InternetGatewayDevice.LANDevice.2. ”，而不会列出在该层次下面的所有参数。 8 GetParameterNamesResponse参数

参数 类型 描述 ParameterList ParameterInfoStruct[] 结构数组，每个包含一个参数的名称和其它信息，见下表的定义。当NextLevel是false时，这一方法返回所有名称以ParameterPath参数指定的字符串开头的所有可访问的参数及其信息。如果ParameterPath参数是一个空字符串，则将返回该CPE上所有可访问的参数名称。当NextLevel是true时，这一列表包括以ParameterPath指明路径的下一层的所有部分路径名。 9 ParameterInfoStruct参数

参数 Name Writable 类型 string(256) 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()[] 零个或多个实体的数组，该实体对指定的参数有写权限。如果数组中不包含条目，则只允许ACS有写权限。目前，只定义了一类实体可以包含在该列表中： “Subscriber” 指明由LAN上的Subscriber控制的设备拥有写权限。比如通过LAN端的DSL CPE配置协议或通过UPnP。 默认情况下，在ACS对access list作改动前，上述的所有实体应当被赋予写访问权。 12 SetParameterAttributesResponse参数

参数 - 类型 void 描述 该方法的应答没有参数。 13 GetParameterAttributes参数

参数 类型 描述 字符串数组，每一条对应所请求的参数的名称。 如果参数名是以部分路径名的方式出现，则该请求需被解释为请求返回命名层次用相同前缀的该分支的所有参数。部分路径名必须在层次的最后一个节点名称后面以“.”（点）结尾。空字符串代表整个层次名称的顶部。 下面是完整参数名称的例子： InternetGatewayDevice.DeviceInfo.SerialNumber 下面是部分路径名称的例子： InternetGatewayDevice.DeviceInfo. 14 GetParameterAttributesResponse参数

参数 类型 描述 ParameterNames string(256)[] ParameterList ParameterAttributeStruct[] 列示指定的参数集的access control信息。该数组中的每一条目是一个ParameterAcessStruct结构，在下表中定义。 15 ParameterAttributesStruct参数

参数 Name Notification 类型 string(256) 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()[] 零个或多个实体的数组，该实体对指定的参数有写权限。如果数组中不包含条目，则只允许ACS有写权限。目前，只定义了一类实体可以包含在该列表中： “Subscriber” 指明由LAN上的Subscriber控制的设备拥有写权限。比如通过LAN端的DSL CPE配置协议或通过UPnP。 16 AddObject参数

参数 类型 描述 objectName string(256) 要建立新实例的对象集合的路径名称。路径名必须在该对象的层次名称的最后节点后加上“.”（点）结尾。 ParameterKey string(32) 需要设置的ParameterKey参数的值。该参数由服务器决定，并可以为空。 17 AddObjectResponse参数

参数 类型 描述 新建对象的实例号码。在对象建立后，可以在路径名中使用该实例号码来引用该对象的参数或子对象。由CPE指定的实例号码是任意的，并且与后续的AddObject调用分配的号码无需连续。 CPE不应当将曾经分配出去的现已删除的对象使用过的号码再分配给新的实例。CPE应当在耗尽某指定对象的整个整数值空间后再重用实例号码。 Status int[0:1] 对该方法的成功应答返回一个整数型的枚举值定义如下： 0 = 对象已经建立。 1 = 对象的建立已经验证并提交，只是尚未应用（比如，增加新对象前需要进行重新启动）。 18 DeleteObject参数

参数 objectName 类型 string(256) 描述 欲删除的对象实例的路径名。路径名必须以对象的实例号码后加“.”（点）来结尾。 ParameterKey string(32) 需要设置的ParameterKey参数的值。该参数由服务器决定，并可以为空。 19 DeleteObjectResponse参数

InstanceNumber unsignedInt[1:] 参数 Status 类型 int[0:1] 描述 对该方法的成功应答返回一个整数型的枚举值定义如下： 0 = 对象已经建立。 ·1 = 对象的建立已经验证并提交，只是尚未应用（比如，增加新对象前需要进行重新启动）。 20 DownLoad 参数 参数 类型 描述 CommandKey string(32) CPE用来指向特定下载的字符串。该参数在方法TransferComplete和GetQueuedTransfers中引用。 FileType string() 一个整数，其后是一个空格，再其后是一个文件类型说明。目前FileType参数仅定义了以下值： \"1 Firmware Upgrade Image\" \"2 Web Content\" \"3 Vendor Configuration File\" 下列格式用于定义唯一的厂商自定义文件类型： \"X \" 其中，用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方法时，将在InfromStruct的CommandKey元素中返回该元素值。 22 RebootResponse参数

参数 - 23 CPE的错误码

类型 void 描述 该响应方法无参数。 参数 9000 9001 9002 9003 9004 描述 方法不支持 拒绝请求（未说明原因） 内部错误 无效参数 资源超限（当用于SetParameterValues的关联时，它不得用来指示参数错误） 9005 无效参数名（与Set/GetParameterValues，GetParameterNames，Set/GetParameterAttributes相关） 9006 9007 9008 9009 9010 9011 9012 无效参数类型（与SetParameterValues相关） 无效参数值（与SetParameterValues相关） 试图设置不可写的参数（与SetParameterValues相关） Notification请求被拒（与SetParameterAttributes方法相关） 下载失败（与Download或TransferComplete方法相关） 上载失败（与Upload或TransferComplete方法相关） 文件传输服务器认证失败（与Upload，Download，或TransferComplete方法相关） 9013 文件传输的协议不支持（与Upload和Download方法相关） 9800 – 99 厂商定义的错误代码 24 ACS错误码 参数 8000 8001 8002 8003 描述 方法不支持 拒绝请求（未指明原因） 内部错误 无效参数 8004 8005 8800 -

资源超限 重试请求 厂商自定义错误代码