TR-069协议学习--Soap报文、事件、RPC方法

一、SOAP报文

SOAP（Simple Object Access Protocol，简单对象访问协议）是一种基于XML的协议，用于在网络上交换结构化信息。SOAP报文是SOAP协议中用于传输数据的XML文档，它定义了消息的格式和传输规则，并被广泛用于Web服务之间的通信。

· SOAP报文的特点

基于XML：SOAP报文是一个XML文档，使用XML格式来编码消息内容，这使得SOAP具有良好的可读性和可扩展性。
传输协议独立：SOAP消息可以通过多种传输协议进行传输，如HTTP、SMTP、TCP等。这种传输协议独立性使得SOAP可以在不同的网络环境和应用场景中广泛应用。
可扩展性：SOAP协议设计为可扩展的，允许在消息中添加自定义的头部信息（Header），用于实现各种功能，如认证、事务处理、加密等。

· SOAP报文的组成部分

一个SOAP报文通常包含以下部分：

Envelope（信封）：SOAP报文的根元素，用于标识这是一个SOAP消息，并包含其他所有部分。
Header（头部）：可选部分，用于添加扩展信息，如认证信息、事务信息等。
Body（主体）：必需部分，包含实际的请求或响应信息。

Fault（错误）：可选部分，用于描述在处理消息过程中发生的错误。

示例：

<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">CPE</cwmp:ID><cwmp:HoldRequests SOAP-ENV:mustUnderstand="1">0</cwmp:HoldRequests></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:InformResponse><MaxEnvelopes xsi:type="xsd:unsignedInt">1</MaxEnvelopes></cwmp:InformResponse></SOAP-ENV:Body>
</SOAP-ENV:Envelope>

二、事件

TR069协议定义了一系列的事件类型，用于描述和管理用户设备（CPE）的状态和行为。每种事件类型都有一个对应的事件代码，以下是一些常见的TR069事件类型：

0 BOOTSTRAP：指出由于CPE第一次安装或是ACS的URL改变而引起会话建立。
1 BOOT：当给电或是复位时引起的会话建立，包括初始系统启动或是由于其他原因的再启动。
2 PERIODIC：在周期通知间隔时会话建立，用作心跳包时间。
3 SCHEDULED：由于调用ScheduleInform方法会话建立。
4 VALUE CHANGE：指出从上次成功的Inform后，具有Passive和Active通知属性的一个或多个参数的值发生了非ACS配置而产生的改变。
5 KICKED：指出会话建立的目的是网页验证，并且Kicked方法会在这个会话中调用一次或多次。
6 CONNECTION REQUEST：由于ACS发送了连接请求而使会话建立。
7 TRANSFER COMPLETE：由于先前请求的下载或上传完成而引起会话建立。
8 DIAGNOSTICS COMPLETE：当完成了一个或多个由ACS启动的诊断，CPE会用该事件码重新建立起一个连接。

事件通过RPC方法Inform携带，由CPE通知向ACS，下面为2 PERIODIC事件上报soap报文示例：

<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">CPE</cwmp:ID></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:Inform><DeviceId><Manufacturer xsi:type="xsd:string"></Manufacturer><OUI xsi:type="xsd:string"></OUI><ProductClass xsi:type="xsd:string"></ProductClass><SerialNumber xsi:type="xsd:string"></SerialNumber></DeviceId><Event SOAP-ENC:arrayType="cwmp:EventStruct[1]"><EventStruct><EventCode xsi:type="xsd:string">2 PERIODIC</EventCode><CommandKey xsi:type="xsd:string"></CommandKey></EventStruct></Event><MaxEnvelopes xsi:type="xsd:unsignedInt">1</MaxEnvelopes><CurrentTime xsi:type="xsd:dateTime"></CurrentTime><RetryCount xsi:type="xsd:unsignedInt">0</RetryCount><ParameterList SOAP-ENC:arrayType="cwmp:ParameterValueStruct[*]"><ParameterValueStruct>　<Name></Name><Value xsi:type="xsd:string"></Value></ParameterValueStruct></ParameterList></cwmp:Inform></SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">CPE</cwmp:ID><cwmp:HoldRequests SOAP-ENV:mustUnderstand="1">0</cwmp:HoldRequests></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:InformResponse><MaxEnvelopes xsi:type="xsd:unsignedInt">1</MaxEnvelopes></cwmp:InformResponse></SOAP-ENV:Body>
</SOAP-ENV:Envelope>

三、RPC方法

RPC（Remote Procedure Call，远程过程调用）方法是用于ACS（Auto Configuration Server，自动配置服务器）与CPE（Customer Premises Equipment，客户端设备）之间进行通信和管理的一组标准方法。以下是TR069中定义的一些主要RPC方法及其功能：

ACS到CPE的RPC方法

GetParameterValues：获取设备上一个或多个参数的当前值。可以用于查询设备的配置信息或状态信息，携带ParameterNames。
SetParameterValues：设置设备上一个或多个参数的值。用于远程配置设备的参数，待配置参数列表ParameterList 中携带Name、Value。
GetParameterNames：获取设备上某个对象的所有参数名称。用于了解设备的参数结构;携带ParameterPath、NextLevel，如果nextlevel为1，则获取父节点下一层节点参数信息。
GetParameterAttributes：获取参数的属性信息，如是否可写、是否可订阅等，携带ParameterNames。
SetParameterAttributes：设置参数的属性信息；携带Name路径名，NotificationChange，如果为true，Notification的值将替换该参数或参数组的当前notification的设置，如果是false，则不作任何notification设置的改动；Notification为1被动上报，CPE发起一个到ACS的会话时携带变更参数信息，为2主动上报，立即创建会话上报。AccessListChange如果为true，AccessList的值会替换该参数或参数组的当前access list值，如果为false，access list不作改动。AccessList表示零个或多个实体的数组，该实体对指定的参数有写权限。如果数组中不包含条目，则只允许ACS有写权限。
GetRPCMethods：获取设备支持的RPC方法列表。用于了解设备的能力和功能。
AddObject：在设备上添加一个新的对象实例，携带objectName、ParameterKey。
DeleteObject：删除设备上已存在的对象实例，携带objectName、ParameterKey。
Reboot：触发设备重启。用于远程重启设备以应用配置更改或解决设备问题。
Download：请求设备下载文件，通常用于固件升级或配置文件下载。
Upload：请求设备上传文件，通常用于配置文件上传、日志文件上传。
FactoryReset：将设备恢复到出厂设置。用于清除所有用户配置并恢复设备的初始状态.

CPE到ACS的RPC方法

Inform：CPE向ACS报告其状态信息，如设备启动、参数值变化等。任何时刻要建立与ACS的连接，CPE必须调用Inform方法。这是CPE主动向ACS发送信息的主要方法；需要携带DeviceID、Event、MaxEnvelopes、CurrentTime、RetryCount、ParameterList信息；其中参数列表通常需要支持上报InternetGatewayDevice.DeviceInfo.SpecVersion
InternetGatewayDevice.DeviceInfo.HardwareVersion
InternetGatewayDevice.DeviceInfo.SoftwareVersion
InternetGatewayDevice.DeviceInfo.ProvisioningCode
InternetGatewayDevice.ManagementServer.ConnectionRequestURL
InternetGatewayDevice.ManagementServer.ParameterKey
InternetGatewayDevice.WANDevice.*.WANConnectionDevice.*.WANIPConnection.*.ExternalIPAddress；还需要携带CommandKey，有助于ACS匹配通知上报结果。
TransferComplete：在完成文件下载或上传后，CPE向ACS报告传输结果; 需要携带FaultStruct包含FaultCode和FaultString，StartTime、CompleteTime、CommandKey。该方法的错误码定义为9001，9002，9010，9011，9012。
GetParameterValuesResponse: 响应ParameterList，如果错误返回Fault报文，该方法的错误码定义为9001-9005。
SetParameterValuesResponse: 响应Status，如果错误返回Fault报文，该方法的错误码定义为9001-9008。
GetParameterAttributesResponse: 响应ParameterList，包含Name、Notification、AccessList，如果错误返回Fault报文，该方法的错误码定义为9001-9005。
SetParameterAttributesResponse: 响应无应答参数，如果错误返回Fault报文，该方法的错误码定义为9001-9005、9009。
AddObjectResponse: 响应新增实例号InstanceNumber、Status，如果错误返回Fault报文，该方法的错误码定义为9001-9005.
DeleteObjectResponse: 响应Status，如果错误返回Fault报文，该方法的错误码定义为9001、9002、9003、9005.
DownloadResponse: 响应Status、StartTime、CompleteTime，如果错误返回Fault报文，该方法的错误码定义为9000-9003、9010、9012、9013.
UploadResponse: 响应Status、StartTime、CompleteTime，如果错误返回Fault报文，该方法的错误码定义为9000-9003、9011-9013.

Download方法soap报文示例：

<SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">192.168.1.100:8080</cwmp:ID></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:Download><CommandKey></CommandKey><FileType>1 Firmware Upgrade Image</FileType><URL>http://192.168.1.100/version</URL><Username></Username><Password></Password><FileSize>0</FileSize><TargetFileName></TargetFileName><DelaySeconds>2</DelaySeconds><SuccessURL>success.html</SuccessURL><FailureURL>fail.html</FailureURL></cwmp:Download></SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">192.168.1.100:8080</cwmp:ID></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:DownloadResponse><Status>1</Status><StartTime>0001-01-01T00:00:00Z</StartTime><CompleteTime>0001-01-01T00:00:00Z</CompleteTime></cwmp:DownloadResponse></SOAP-ENV:Body>
</SOAP-ENV:Envelope><SOAP-ENV:Envelopexmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"xmlns:cwmp="urn:dslforum-org:cwmp-1-0"><SOAP-ENV:Header><cwmp:ID SOAP-ENV:mustUnderstand="1">1</cwmp:ID></SOAP-ENV:Header><SOAP-ENV:Body><cwmp:TransferComplete><CommandKey></CommandKey><FaultStruct><FaultCode>9018</FaultCode><FaultString>File transfer failure: file corrupted or otherwise unusable</FaultString></FaultStruct><StartTime>0001-01-01T00:00:00Z</StartTime><CompleteTime>0001-01-01T00:00:00Z</CompleteTime></cwmp:TransferComplete></SOAP-ENV:Body>
</SOAP-ENV:Envelope>