电信移动终端需求-4g数据终端接口协议分册

1、等 级： 5 年中国电信公司企业标准Q/CTX-20132013-08-发布2013-08-实施中国电信公司发 布中国电信移动终端需求规范4G 数据终端接口协议分册（V2013）Requirement Specifications for Mobile Terminal of China-4G Daerminal Protocol Fascicule（Ver2013）YD/T 2013目录前言41适用范围42参考资料53缩略语54总体技术要求64.1 协议.24.1.3RESTFul 简介6安全验证7接口格式介绍74.2 驱动要求84.3URI 规则84.4 异常/错误处理9

2、4.5 字段命名规则114.6 不支持字段处理114.7 字段类型说明125具体接口描述12 12查询 Pin 码状态12开启 Pin 码13禁用 Pin 码13修改 Pin 码14Pin 码14PUK 码.. 状态监测.2查询网络状态信息15查询新消息185.3 设备功能..45.3.5查询 device information18恢复出厂设置20固件升级检查20固件升级启动接口20固件升级状态接口202YD/T 20135.4 网络.2连接网

3、络21断开网络225.5 NET 功能.......9查询 Network22设置 Network22获取 PLMN 列表23获取当前网络信息24获取自动和手动设置自动和手动网络24网络25（可选）25设置未读为已读25查询查询数量26列表26 29发送状态29 30 30配置31配置32获取删除查询设置6详细更新历史323YD/T 2013本标准按照GB/T 1.1-2009给出的规则起草。标准电信移动终端需求体系的系列规范标准之一，中国电信移动终端

4、需求规范标准体系主要包括但不限于以下分册：1)2)3)4)5)6)7)8)9)10)11)12)13)14)15)16)17)18)19)20)中国电信移动终端需求规范-基本技术要求分册中国电信移动终端需求规范-SMS 分册中国电信移动终端需求规范-MMS 分册中国电信移动终端需求规范-浏览器分册中国电信移动终端需求规范-CDMA_GSM 双模终端分册中国电信移动终端需求规范-现网分册中国电信移动终端需求规范-LBS 分册中国电信移动终端需求规范-流分册中国电信移动终端需求规范-DM 分册中国电信移动终端需求规范-分册中国电信移动终端需求规范-CDMA+WiFi 分册中国电信移动终端需求规范-

5、QChat 分册中国电信移动终端需求规范-QChat 业务 UI 分册中国电信移动终端需求规范-PSVT 分册中国电信移动终端需求规范-Rev.A 数据终端技术要求分册中国电信移动终端需求规范-Java 分册中国电信移动终端需求规范-BREW 分册中国电信移动终端需求规范-1xEVDO RevB 技术要求分册中国电信移动终端需求规范-UI 分册中国电信移动终端需求规范-4G 接口协议分册该系列规范标准主要依据中国电信企业标准中的相关规定和中国电信移动终端需求，并结合3GPP2、3GPP、CDG国际标准，以及CCSA行业标准编写，对的要求。X等方面提出了具体本由中国电信公司提出并归口。本标准起草

6、：本标准由中国电信起草。公司公众客户事业部组织制定，中国电信标准主要起草人：艾水根、本标准于 2013 年 XX 月首次发布。、。1 适用范围电信（简称中国电信）4G 数据终端客户端采用的 Web Service 接口协议提出规定，中国电信和厂商共同使用，用于在业务及设备开发上为公司和省公司提供技术依据；适用于以数据卡形式的移4前言YD/T 2013动终端产品。2 参考资料下列标准所包含的条文，通过在中而为的条文。凡是注日期的标准，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于，若其被修订，使用的各方应探讨使用其版本的可能性。凡是不注日期的标准，其版本适用于。1.ETSI GSM07

7、.072.ETSI GSM07.073.TIA-EIA-IS-707-A.34.ITU-TmendationV.25ter143缩略语5Abbreviations缩略语Full spelling 英文全名Chiexplanation 中文解释3GPPThird Generation Partnership Project第三代伙伴计划BERBit error rate误码率CDMACode DiviMultiple Acs码分多址CLIPCall Line Identifier presenion呼叫号码显示DCEDircuit Equipment数据电路设备Doding scheme数据编码

8、方案DTEDaerminal Equipment数据终端设备EVDOEvolution Data Only演进版本，仅支持数据GPRSGeneral Packet Radio Service通用分组无线系统GSMGlobal System for Mobile Communications全球移动通信IMEIernational Mobile Equipment Identity国际移动设备标识ITU-Ternationalmunicationmunication Standardization Sector国际电信-电信标准部YD/T20134总体技术要求4.1 协议为了便于推广，此接口遵循

9、业界 Web Service 主流接口风格 RESTful。全文所有协议接口数据使用 UTF-8 编码。4.1.1 RESTFul简介REST 从资源的角度来观察整个网络，分布在各处的资源由 URI 确定，而客户端的应用通过 URI 来获取资源的表形。获得这些表形致使这些应用程序转变了其状态。随着不断获取资源的表形，客户端应用不断地在转变着其状态，所谓表形化的状态转变（Represenional Se Transfer）。需要注意的是，REST 是一种设计风格而不是一个标准。REST 通常基于使用6Abbreviations缩略语Full spelling 英文全名Chiexplanation

10、 中文解释IWFerworking Function网络互通功能单元MTMobile Terminal移动终端PDPPacket Data Protocol包交换协议PINal Identity Number个人识别码PLMNPublic land mobile network公用陆地移动网络PUKal Identity Number个人标识码RPLMNRegistered PLMNPLMNRSSIReceive signal strength indicator接收信号强度指示SCASevice Center Address服务中心号码SIMGSM Subscriber Identity M

11、odule用户标识组件SMShort messageTETerminal Equipment终端设备，这里指在 PC 上运行的统一终端客户端UIMUser Identity Module用户标识模块URCUnsolicited result code主动上报结果码，如上报、上报、状态改变上报等。USIMUniversal Subscriber Identity Module用户业务标识组件WCDMAWideband CDMA宽带码分多址YD/T 2013HTTP，URI，和 XML 以及 HTML 这些现有的广泛流行的协议和标准。资源是由 URI 来指定。对资源的操作包括获取、创建、修改和删除

12、资源，这些操作正好对应 HTTP协议提供的 GET、T、PUT 和 DELETE 方法。通过操作资源的表形来操作资源。资源的表现形式则是 XML 或者 HTML，取决于读者是机器还是人，是消费 web服务的客户还是 web 浏览器。当然也可以是任何其他的格式。4.1.2 安全验证客户端约定增加终端标志，标志为：CWCnt在 HTTP 请求的 HEADER 中增加 2 个字段，分别为 sign 和 time，sign 按照以下规则组合：将组合字段拼接后 MD5 加密，产生的值作为 sign 键的值。例如：time 为 1377166687，所以 sign 值为：CWCnt&1377166687

13、组合后进行MD5 加密，产生键值 sign 内容为 00b8309dcc3692dad0f786668dc15b75,然后将time 和 sign 加入 HTTP 请求 HEADER 中，所增加的 HTTP 头：time=“1377166687”sign=“00b8309dcc3692dad0f786668dc15b75”。WebServer 收到请求后使用约定的关键字 CWCnt+&+HTTP 头所带的 time进行 MD5 加密，如果加密后的数据与 HTTP 头中的 sign 相同则认为是合法的请求，需要正常响应，否则不作响应。4.1.3 接口格式介绍例 1：查询 PIN 码状态，根据 R

14、estful 风格，可以认为是获取 PIN 码状态这个资源：HTTP 方法：GETURI：api/pin/satus资源的表现形式：XML7组合字段客户端标志&time约定值CWCnt&timeYD/T 2013所以查询 PIN 码状态请求的报文如下：GET api/pin/sus HTTP/1.1查询 PIN 码状态响应的报文如下：例 2：模式切换，根据 Restful 风格，可以认为是设置设备模式这个资源：HTTP 方法：TURI：aevicemode资源的表现形式：XML模式切换请求的报文如下：模式切换响应的报文如下：4.2 驱动要求数据卡需要支持 XP 以上系统免驱动安装，数据卡，系统

15、能自动识别并安装驱动，驱动安装后可使用客户端进行使用。驱动支持 Mac OSX 10.6 以上系统。数据卡后，需要自动识别检测是否有安装 PC 客户端，如果有安装就自动启动 PC 客户端，如果没有安装则提示用户安装。客户端要求实现固件升级功能，调用设备接口实现。4.3URI 规则URI 是网络上用户可和使用的各种资源的标识。终端设备的 Pin 码、运8 0接口地址规定：T a evicemode HTTP/1.11ErrorCode 正确不需要返回，如果错误返回YD/T 2013营商信息、模式、等都可以认为是终端设备上可供用户和使用的资源，这些资源都用唯一的 URI 进行标识，规则如下：Web

16、 Service 接口，按照下面的形式提供：api/category/function/sub_function/用“/”来标识资源之间的层次关系，如“/aaa/bbb”，表示“aaa”是“bbb”的上层资源，通常有“aaa”包含“bbb”的关系。Api：在该文档中所有的资源都在包含在“api”这个节点内，即所有的资源都以“api”开头。Category：资源按功能进行分类，如 pin 码相关功能对应 api/pin，状态监测相关功能对应 api/monitoring，模式切换功能对应 aevicemode 等；function：function 是 category 标识的功能分类下的一个子

17、节点，如 pin功能分类里的 pin 码状态这个子节点，URI 为 api/pin/sus，特殊功能组里的特殊条数则是 api/spelsms/count；function 下还有可以有多层sub_function。URI 全用小写字母，可用“-”来增强可读性。如 restore-factory-settings，表示恢复出厂设置。4.4 异常/错误处理所有请求，如果在 web server 端执行出现异常或错误，返回错误码，用于网页进行错误处理和错误信息提示。Error Code 表9ErrorCodeError CodeCategoryDescription0成功100001通用错误未知e

18、rror类型。100002不支持该请求。100003系统忙，暂时无法处理该请求100004请求格式错误。字段名类型长度说明responseeger6ErrorCode错误码见error code表。YD/T201310Error CodeCategoryDescription100005参数错误100006保存配置文件错误100007通用错取配置文件节点错误101001Pin码1、没有2、了无效的101002检测到Pin码锁定101003检测到puk码锁定101004检测到不可用101005启用Pin码失败101006禁用Pin码失败101007Pin码失败101008pin码校验失败1010

19、09修改pin码失败101010puk码校验失败102001状态监测获取网络类型失败102002获取服务状态失败102003获取漫游状态失败102004获取连接状态失败103001DIALUP(可选)获取连接配置文件设置错误103002设置连接配置文件设置错误103004拨号管理错误103005增加Profile错误103006修改Profile错误103007删除Profile错误103008设置默认Profile错误103009获得Profile列表错误103010获得auto APN匹配错误103011设置auto APN匹配错误104001NET拨号情况下设置网络模式或频段失败1040

20、02拨号情况下设置搜网模式失败104003网络模式和频段设置失败104004设置搜网模式失败104005网络失败104006网络接入次序不匹配104007当前设置的网络制式不支持104008当前不在准备好的状态104009内存分配失败105001SMS（可选）入参为空/数据105002超时105003查询索引列表错误105004设置中心号码失败105005删除失败YD/T 20134.5 字段命名规则字段名采用驼峰命名法，每个单词以大写字母开始，单词之间不间隔。如，Nessword。表示数组的字段后加 S 表示复数，如，Filters。4.6 不支持字段处理不支持的字段可以有两种方式处理。节点

21、保留，只需要节点内容为空。客户端和 WebServer 端对为空的字段不进行处理。如 A 产品支持 Pin 码查询请求，但不支持获取剩余输入 pin 码次数，则该字段内容为空即可。见下：发送报文：GET api/pin/sus HTTP/1.1返回报文：整个节点不保留。PC 客户端和 WebServer 端不出现的字段不进行处理。如 A产品支持 Pin 码查询请求，但不支持获取剩余输入 pin 码次数，则该字段不出现。见下：发送报文：GET api/pin/sus HTTP/1.1返回报文：112572583Error CodeCategoryDescription105006SMS（可选）保

22、存配置文件错误105007本地空间105008号码超长105009PB（可选）入参为空/数据105010超时105011调用系统函数出错105012文件写入失败105013文件失败105014本地本已满YD/T20134.7 字段类型说明字段类型说明如下：根据目前的需求，仅仅eger 和 string 两个类型就可以满足要求，但为了后续的扩展性，也定义了二进制和结构体类型进行约定。5 具体接口描述 查询Pin码状态请求：GET api/pin/sus HTTP/1.1响应：12字段名类型长度说明M/OSimSeeger1状态。0:no sim card or invalid c

23、ard 1:SIM ready2:PIN required 3:PUK requiredMSimPimeseger1剩余输入Pin码次数。 0-3MSimPukTimeseger2剩余输入PUK码次数。 0-10M字段类型类型说明eger十进制整型数string字符串binary由byte组成的字符串，由于XML不能直接承载二进制数据，所以对该类型的数据采用BASE64 编码；_scheme结构体类型2572583YD/T20135.1.2 开启Pin码请求：响应：5.1.3 禁用Pin码请求：响应：r13字段名类型长度说明M/Oesponseeger6ErrorCodeM ErrorCode

24、字段名类型长度说明M/OCurrentPinString8输入的Pin码，4-8 位数字。MT api/pin/disable HTTP/1.1123456字段名类型长度说明M/Oresponseeger6ErrorCodeM ErrorCode字段名类型长度说明M/OCurrentPinstring8输入的Pin码，4-8 位数字。MT api/pin/enable HTTP/1.11234561310YD/T20135.1.4 修改Pin码请求：响应：5.1.5Pin码请求：响应：5.1.6PUK码请求：14字段名类型长度说明M/OPukNumberstring8输入PUK码，8 位数字。

25、MNewPinString8输入新的PIN码，4-8 位数字MT api/pin/entuk HTTP/1.1字段名类型长度说明M/Oresponseeger6ErrorCodeMErrorCode字段名类型长度说明M/OCurrentPinstring8输入旧的Pin码，4-8 位数字。MT api/pin/entin HTTP/1.1123456字段名类型长度说明M/Oresponse6ErrorCodeM ErrorCode字段名类型长度说明M/OCurrentPinString8输入旧的Pin码，4-8 位数字。MNewPinString8输入新的Pin码，4-8 位数字。MT api

26、/p odify HTTP/1.1123456654321YD/T2013响应：5.2 状态监测5.2.1 查询网络状态信息请求：GET api/monitoring/sus HTTP/1.1响应：15字段名类型长度说明M/OConnectionSuseger4当前连接状态。取值范围：0,999(待确认)2: IMSI unknown in HLR 3: Illega5: Illegal ME7: GPRS servinot allowed 8: Operator Determined Barring9: MS identity cannot be derived by the network

27、10: Implicitly detached 11: PLMN not allowed12: Location Area not allowed13: Roaming not allowedhis location area14: GPRS servinot allowedhis PLMN15: No Suitable Cells In Location Area 16: MSC temporarily not reachable17: Network failure20: MAC failure21: Synch failure22: Congestion23: GSM authentic

28、ation unacceptable 25: LLC or SNDCP failure(GSM only)M字段名类型长度说明M/Oresponsestring6ErrorCodeMErrorCode12345678654321YD/T20131626: Insufficient resour 27: Missing or unknown APN28: Unknown PDP address or PDP type 29: User Authentication failed30: Activation rejected by GGSN31: Activation rejected, unsp

29、ecified 32: Service option not supported33: Requested service option not subscribed34: Service option temporarily out of order35: NSAPI already used (not) 36: Regular deactivation37: QoS not accepted 38: Network failure39: Reactivation required 40: Feature not supported41: Semerrorhe TFT operation 4

30、2: Syntactical errorhe TFT operation43: Unknown PDP context44: Semerrors in packet filter(s) 45: Syntactical errors in packet filter(s)46: PDP context without TFT already activated48:retry upon entryo a new cell (4863)81: Invalid tranion identifier value95: Semally incorrect message 96: Invalid mand

31、atory information 97: Message type non-existent or not implemented98: Message type not compatible with the protocol se99: Information element non-existent or not implemented100: Conditionaerror101: Message not compatible with the protocol se111: Protocol error, unspecified 900：连接中901：已连接YD/T20131790

32、2：已断开903：断开中904：连接失败以上连接状态的描述不直接作为给用户的提示。RoamingSuseger1漫游状态。0,1（0 非漫游，1 国内漫游）MWanIPAddressstring16网关ip地址。取值范围：如 OWanIPv6Addressstring128网关ipv6 地址。取值范围：如:x 或者 0OPrimaryDnsstring16主dns的IP地址。取值范围：如MPrimaryIPv6Dnsstring128主dns的IPv6 地址。取值范围：如:x 或者 0, 0 表示没有使用 IPv6OSecondaryDnsstring16次dns的IP地址。取值范围：OSec

33、ondaryIPv6Dnsstring128次dns的IPv6 地址。取值范围：:x 或者 0，0 表示没有使用 IPv6OServiuseger1系统服务状态0：无服务1：有限务2：服务有效M901754231-1275055334425522551232900YD/T 20135.2.2 查询新消息请求：GET api/monitoring/checknews HTTP/1.1该命令提供给PC 客户端定时查询是否有新消息需要即时处理,如果sms 模块有新消息来, PC 客户端需要另外调用 restful 接口去获取未读条数，并在页面上提示用户有未读条数。响应：5.3 设备功能5.3.1 查

34、询deviceinformation请求：GET aevice/information HTTP/1.1响应：18字段名类型长度说明M/ODeviceNamestring32产品型号。MSerialNumberstring32序列号。MImeistring32IMEI号MImsistring32IMSI号M字段名类型长度说明NewsTypeString4【1000 - 1999】:SMS 1001 新1002满1003 设备满1000200140YD/T201319Iccidstring32唯一标识MMsisdnstring32本机号码OHardwareVerstring32硬件版本MSoft

35、wareVerstring32版本MMacAddress1string32MAC地址MClassifystring32设备终端类型1、 常规数据卡；2、 具有WiFi功能的数据卡；3、MiFi终端；4、 cpe 表示 CPE 产品类型;OMeidstring32MEID号OPrlVerstring32PRL版本号Osupportmodestring32当前的设备支持的制式取值为下面中的一项或多项组合：八位组定义M87654321GS MWC DM ACD MAFD DTD Dworkmodestring32当前工作的模式取值为下面中的某一项：参照supportmodeME5830SA00000

36、0000035010000000000460080000000241131313131313WLAGCPU996.11.00.01.1001.300:1E:10:0E:22:3300:1E:10:0E:22:44WCDMAhilink80761abda5870900000000033071supportm TE|WCDMAworkmTEYD/T 20135.3.2 恢复出厂设置请求：GET aevice/ restore-factory-settings HTTP/1.1响应：5.3.3 固件升级检查请求：GET aevice/updatecheck HTTP/1.1响应：5.3.4固件升级启

37、动接口请求：T aevice/update HTTP/1.1响应：5.3.5固件升级状态接口请求：GET aevice/updatese HTTP/1.1响应：20字段名类型长度说明M/OSeeger4状态编码【30003999】: online-updateM字段名类型长度说明M/Oresponseeger6ErrorCodeMErrorCode字段名类型长度说明M/OUpdateSeeger4Update se 0 无新版本1 有新版本MVerString32verM字段名类型长度说明M/Oresponsestring6ErrorCodeMErrorCodeYD/T20135.4 网络数据

38、卡需要有客户端才能进行连接，数据卡本身不作自动连接处理5.4.1连接网络请求:响应：21ErrorCode字段名类型长度说明M/Oresponseeger6ErrorCodeM字段名类型长度说明M/Otring32Apn nameMUserNameString64User nameMPasswordString64passwordMT aialup/dial HTTP/1.13010:状态，无操作；3011：正在连接服务器3012 连接成功3013 连接失败3014：正在升级包3015：失败3016：完成3017 升级包校验失败3018 升级包校验成功3019 升级成功3020 升级失败302

39、1：临时状态。表示重启后发现上次未完成，需用户确认。一旦用户确认，立即切换到Downlorogressing状态YD/T 20135.4.2 断开网络请求：T aialup/hangup HTTP/1.1响应：5.5 Net 功能5.5.1 查询Network请求：GET api/net/network HTTP/1.1响应：5.5.2设置Network请求：字段名类型长度说明M/ONetworkModestring1网络模式：重定义0：Auto(4G Pre，TDD优先)M1：2G2：3Gonlyonly3：4G only(TDD优先)NetworkNumberstring846003MCC

40、MNCMT api/net/network HTTP/1.122ErrorCode字段名类型长度说明M/ONetworkModestring32网络模式： 0：Auto(4G Pre) 1：2G only 2：3G only 3：4G onlyMSignalBarstring40,5O05字段名类型长度说明M/Oresponseeger6ErrorCodeMYD/T 201346003响应：5.5.3 获取PLMN列表请求：GET api/net/plmn-list HTTP/1.1响应：23字段名类型长度说明M/OIndexeger4网络索引MSeeger4网络的状态标识：0：未知的1：可用

41、的2：当前3：MFullNamestring128运营商全名(该字段有可能为空)MShortNamestring128运营商短名(该字段有可能为空)MNumericstring16网络的数字名，当前为 5-7 位数字字符串MRateger1无线接入技术：0：2G1：3G2：4GM10china mobilechina mobile46009220china mobilechina mobile460090字段名类型长度说明M/Oresponseeger6ErrorCodeMErrorCode0YD/T 20135.5.4 获取当前网络信息请求：GET api/net/current-plmn

42、HTTP/1.1响应：5.5.5获取自动和手动网络请求：24GET api/net/register HTTP/1.1字段名类型长度说明M/OModeeger4网络选择模式0：自动搜网1：手动搜网MPlmnstring16运营商数字名，需要携带PLMNORateger4无线接入技术：0：2G1：3G2：4GO字段名类型长度说明M/OSeeger4网络选择模式：0：自动搜网1：手动搜网2：去网络3：仅读命令设置返回运营商格式4：手动搜网与自动搜网的联合，如果手动搜网失败，则自动转入自动搜网MFullNamestring128运营商全名(该字段有可能为空)MShortNamestring128运营

43、商短名(该字段有可能为空)MNumericstring16网络的数字名，为 5-7 位数字字符串MRateger1无线接入技术：0：2G1：3G2：4GM0460012YD/T2013响应：5.5.6 设置自动和手动网络请求（字段表参考获取自动和手动网络）：响应：5.6（可选）5.6.1设置未读为已读请求：响应：25字段名类型长度说明M/Oresponseeger6ErrorCodeMErrorCode字段名类型长度说明M/OIndexeger8索引，和本地Index不重复MT api/sms/set-read HTTP/1.140001400024000340004字段名类型长度说明M/Or

44、esponseeger6ErrorCodeMErrorCodeT api/net/register HTTP/1.104600920460092YD/T 20135.6.2 查询数量请求：GET api/sms/sms-count HTTP/1.1响应：备注：字段表示，每次查询时（目前为 3 秒），新到来的数量。UI 定时查询，如果此字段值大于 0，说明在这 3 秒查询内，有新到达，那么就应该下发 sms-list报文获取列表。由于该字段每次查询之后会被清 0，所以如果另外一个 UI 页面（或应用程序）再次下发该接口查询时，该字段返回值为 0。5.6.3 查询列表请求：263405000520

45、20500205003字段名类型长度说明M/OPageIndexeger4当前页面索引，索引从 1 开始。500 条，则索引应该在1-50之间MReadCounteger4每页的数量，目前过 50 条MBoxTypeeger20：设备M字段名类型长度说明M/OLocareadeger4设备未读条数。MLocalInboxeger4设备收件箱条数。MSimUnreadeger4未读条数。MSimInboxeger4收件箱条数。MLocalMaxeger4设备普通最大量。最小 500，最大不限MSimMaxeger4最大量。MYD/T2013响应：27字段名类型长度说明M/OCounteger4数

46、量MSmseger1类型0：未读1：已读2：未发3：已发4：发送失败（类型 2，3，4 可选）MIndexeger8索引MPhonestring32对方号码，多个号码用英文逗号隔开MContentstring1024内容MDatestring40接收/发送该的时间，格式为：yyyy-mm-dd hh:mm:ss（如不支持发送时间则返回 0）MScastring16中心号码MSaveTypeeger1消息类型提供给界面显示并回复SC已收到，但不存储到NV中，若满了到OT api/sms/sms-list HTTP/1.111010101:。SortTypeeger1排序字段：0：按时间1：按号码2：按不支持的排序字段则按时间排序。目前不支持按排序。OAscendingeger1升序降序：0：降序1：升序OUnrereferredeger1排序时是否考虑未读优先0：不考虑1：考虑OYD/T20132810140001o world2011-