中国电信qchat业务终端参数配置接口要求系统和用户数据分册

1、中国电信中国电信 qchatqchat 业务终端参数配置接口技术要求业务终端参数配置接口技术要求 系统和用户数据分册系统和用户数据分册 （征求意见稿）（征求意见稿） 中国电信股份有限公司广州研究院中国电信股份有限公司广州研究院 二零壹零年三月二零壹零年三月 目录目录 1 1范围范围.3 1.1文档更改历史.3 2缩略语缩略语.4 3管理终端数据配置文档的管理终端数据配置文档的 xcapxcap 服务服务.5 3.1终端数据配置文档.5 3.2支持的 http 方法.5 3.3支持的 http 头.5 3.3.1适用于所有操作的头.5 3.3.2put 必须携带的头.5 3.3.3用于条件操作

2、http 头.6 3.4终端数据配置服务器 xcap 请求 url.7 3.5终端数据配置服务器器后向兼容对客户端 xml 解析的要求.8 4终端数据配置服务器终端数据配置服务器 xcapxcap 接口规范接口规范.9 4.1概述.9 4.2正常响应.9 4.2.1正常响应描述.9 4.3错误响应.9 4.3.1错误响应描述.10 4.4操作终端数据配置文档.14 4.4.1data schema.14 4.4.2使用场景.17 5终端数据配置服务器短消息（终端数据配置服务器短消息（sms）接口规范）接口规范.26 5.1tdcs 通知的短消息负荷.26 5.2收到通知后如何产生获取用户配置文

3、档更新的 url.27 6终端数据配置服务器客户端的配置信息终端数据配置服务器客户端的配置信息.28 6.1配置信息.28 6.2主副地址切换建议.28 7对手机终端和用户管理平台群组操作能力的建议对手机终端和用户管理平台群组操作能力的建议.29 1 1范围范围 终端数据配置服务器(terminal data configuraiton server: tdcs) 是用户终端配置数 据管理和下发的 xml 文档管理服务器.文档的管理操作包括新建/读取/修改. 这些操作是 通过 xcap 接口完成的。终端数据配置服务器(tdcs) 还提供数据下发给终端的能力。下发 通知是通过短信实现的。 本文定

4、义终端与终端数据配置服务器(tdcs)进行通信时的接口规范。 本文用 tdcs 表示终端数据配置服务器。 1.1文档更改历史文档更改历史 时间时间说明说明 2009.2.12 以下为更改的主要内容： : 增加 content-type application/xcap-el+xml 3.4 : 增加对 fqdn 使用的解释 4.4.2: 修改示例消息中的几处错误。 .2: 增加使用 cr order 的注意事项. 5.1 : 短消息负荷更改 5.2 : 终端获取 xui 的方法更改 6.1 : 服务器故障转移定时参数取值修改 6.2 : 增加了主副地址切换的方法建议

5、 7 : 增加了手机 uim 卡更换的考虑 另外修改了一些文字错误。 2009.3.2 : 响应消息改为 201 created. 并在 .1 中加入对已 有 call restriction 替换的注释。 2009.7.14 5.1：修改 tdcs 采用 smgp 协议要求及流程说明。 2009.8.5 5.1：修改 tdcs 发送的为，以及针对 的样例“qchat”修改为“ptt”。 2009.8.5 修改配置信息更新流程图。 2009.8.31 14.4.1 的 data schema 中加入 xs:any 元素以备将来扩展 2. 文档 uri 示例中 改为

6、3. 文档示例中用户域名改为 2009.11.18 更正图 5-1 中的协议标识。 2009.11.23 修改文档中所有“”为 “”。 2010.3.1 修改文档中所有“”为“”。 2010.3.25 修改文档中所有“”为 “sh.glms.vnet.mobi:9445”。 2缩略语缩略语 term/acrony mdefinition 3gpp3rd generation partnership project auidapplication usage id fqdnfully qualified domain name tdcsterminal data configuration se

7、rver httphypertext transfer protocol ietfinternet engineering task force omaopen mobile alliance smppshort message peer-to-peer protocol smscshort message service center uri uniform resource identifier urluniform resource locator xcapxml configuration access protocol xdmxml document management xdmcx

8、ml document management client xdmsxml document management server xmlextensible markup language xuixcap user identity 3管理终端数据配置文档管理终端数据配置文档的的 xcapxcap 服务服务 3.1终端数据配置文档终端数据配置文档 在 tdcs 中，存在用户终端配置文档，即适用于某一用户的终端配置文档。该文档包含该 用户的终端进行 ptt 适用的配置信息。 3.2支持的支持的 httphttp 方法方法 tdcs 支持以下 http/xcap 操作: http get （获取用

9、户配置文档信息） http put (新建或修改用户配置文档) http delete （修改用户配置文档中某些信息） 3.33.3支持的支持的 httphttp 头头 3.3.1适用于所有操作的头 用于认证的头: clientid “clientid” 在每个http请求中都必须携带. “clientid” 可以被 wap 网关或用户群组管理平台加入，并随请求消息送到 tdcs。clientid 应该携带明文的用户 id 信息。tdcs 信任“clientid”所包含的用户 id 就是请求发起者的 用户 id。 注意：运营商也可以选用其它的 http 头作为用于认证的头，如：p

10、-asserted-identity. 但所有的发送到 tdcs 的请求必须使用相同的头。 用于识别客户端协议版本的头: glmsclientversion “glmsclientversion” 在每个http请求中都必须携带. tdcs 客户端用“glmsclientversion”表示它所实现的 tdcs 协议版本。对应于本规范，版本 号应为“11.01” 注意：运营商也可以选用其它的 http 头作为用于版本标识的头，如：glms-group- version. 但所有的发送到 tdcs 的请求必须使用相同的头。 3.3.2 put 必须携带的头 对 xcap put 操

11、作 , 下列 http 头必须携带：“content type” 和 “content length”. content type content-type 头域指定所包含的消息体的媒体类型。其格式为: content-type = content-type : media-type tdcs 中有效的 content type 为: content-type: application/user-config+xml content-type: application/xcap-el+xml 在不同场景下的具体使用参见第 4 章。 content length co

12、ntent-length 头域指定消息体的长度 （8 位字节数）。其格式为： content-length = content-length : 1*digit 例如: content-length: 3495 3.3.3用于条件操作 http 头 http 定义了几个可以被客户端用来做条件请求的头域：if-none-match 和 if-match。 客户 端可以根据所请求资源的实体标签（entity tag）来做条件请求. 这些条件请求的头域在请 求消息里是可选用的. 条件请求的头域可以解决并发请求的冲突问题。 if-match if-match 请求头域被 http 方法(

13、put/delete)用来做有条件操作. 对一个或多个从 群组服务器获得的实体，xds 客户端可以在请求的if-match头中包含某个实体的 entity tag 以确认它所具有的那个实体是最新的. if-match 头可以被用在以下场景中: 条件 put xdm 客户端想增加或修改服务器 xdm 文档中的某个元素（element），并且希望服务器所 具有的文档版本和客户端当前所具有的那个文档相同时才能修改。客户端可以在请求中包 含 if-match 头, 并将客户端所具有的实体标签（entity tag）值写在里面. 如果文档已经改变，群组服务器会拒绝这个请求返回 412 （条件失败）. 在

14、这种情况下， 客户端需要重新用 get 请求从服务器获取这个文档并保存服务器在 200 ok 中返回的新的 实体标签（entity tag）。 客户端可以把新的实体标签（entity tag）放在 if-matc 头中重新 请求修改文档。 如果操作成功， 响应消息的 etag 头会包含刚被修改过的资源的新的实体标签（entity tag）。 条件 delete xdm 客户端也可以在 delete 请求中包含 if-match 头来做条件删除. delete 请求的 200 ok 响应会包含一个 etag 头域, 带有所删除元素所在的整个文档的实体标签（entity tag） i

15、f-none-match if-none-match 请求头域可以和 get 请求方法一起使用做条件请求. if-none-match 头中可 以包含客户端以前从服务器所获取的资源实体的实体标签（entity tag）。 if-none-match 头可以被用在以下场景中: 条件 get 当 xdm 客户端本地存有一个文档的版本，它可以做条件 get 来判断服务器对统一文档是 否有更新。如果本地文档仍然是最新的，客户端就不会重新下载文档，以此节省网络的使 用。为了达到这个目的，客户端在 get 请求中携带 if-none-match 头域，其中包含客户端 当前文档的实体标签（entity ta

16、g）. 终端数据配置服务器如果发现服务器文档标签和客户端 不同，会响应 200 ok. 如果服务器文档标签和客户端相同, 服务器会响应 304 not modified. 3.43.4终端数据配置服务器终端数据配置服务器 xcap 请求请求 urlurl 1. xcap 根节点 （xcap root） xcap 根定义了所有可被请求的资源所在的位置. xcap 根用 http uri 表示, 被称为 xcap 根 rui。对终端数据配置服务器 xcap 根 被定义为/tdcs fqdn/tdcs-services/. 注：在具体构造 http 请求时，tdcs fqdn 应该为 tdcs 服务

17、器的地址，并且在发出 http 请求时放在 host http 头中，而不是 request-uri 中。另外，由于 tdcs 有主副 地址，tdcs fqdn 可能是两个。（关于主副地址，请参见第 6 章） 2. 文档选择器 （document selector） 在文档根节点下的每一个 xml 文档使用文档选择器作为唯一标识，文档选择器类似于由 多个路径标识符组成的一个完整路径，使用“/”作为路径分隔符. 第一个路径部分必须是 xcap auid。终端数据配置服务器支持以下 xcap auid: user-config: 用来进行群组的操作用来进行群组的操作 在每个 auid 下有两个子

18、xcap 分支. 一个称为 “用户树”（“user”tree）, 保存某个用 户的终端配置文档“index”。 另一个分支是“全局树”（“global”tree）, 保存适用于所 有用户的终端配置文档“index”. auid 之后的路径部分必须是global 或 users. 每个用 户对服务器而言都有一个用户名，被称为 xcap 用户标识符（xcap user identifier: xui). 文档选择器余下的部分 (global 或 xui 以后的路径)指向具体的文档名. 终端数据配置文件名为“index”，并被保存在 users 树下。 3. 节点选择器 （node selector

19、） 节点选择器指定 xml 文档中具体被操作的节点. 节点选择器指向 xml 元素或元素属性. 4. 产生 tdcs 请求 url 访问终端数据配置服务器的某个用户的 xml 文档, 使用以下的 url 格式: http:/fqdn of tdcs server/service name/auid/users/xui of user/index 访问 tdcs 文档的 xml 元素，使用以下的 url 格式: document selector/node selector 3.5终端数据配置服务器器后向兼容对客户端终端数据配置服务器器后向兼容对客户端 xmlxml 解析的要求解析的要求 这里的

20、终端数据配置服务器客户端指所有与 tdcs 进行 http/xcap 通信客户端应用程序。 tdcs 会不断加入新的功能. 群组管理的 xml schema 在将来可能会被扩展。tdcs 升级到 新的版本而客户端有可能仍然是旧的版本。为了使tdcs 后向兼容，tdcs 客户端的实现必 须要遵循以下建议: otdcs 客户端必须忽略服务器返回的合法的 xml 文档中不能识别的 xml 元素 或 属性，而不是报错退出对文档的处理. 4终端数据配置服务器终端数据配置服务器 xcapxcap 接口规范接口规范 4.1概述概述 tdcs 为客户端应用提供 xcap 接口来管理服务器存储的终端配置 xml

21、 文档. 客户端应用 可以 新建/读取 xml 文档及其 xml 元素和属性. 本章给出终端数据配置服务器 xcap 接口规范。 4.2正常响应正常响应 如果客户端的请求被成功处理，tdcs支持成功的 2xx 状态码： 状态码状态码描述描述 200ok 201created 4.2.1正常响应描述正常响应描述 200 (ok) 响应 当 xcap get/put/delete 请求被成功处理时返回. 示例消息: http/1.1 200 ok etag: bcbcbc content-length: 0 . . . 201 (created) 响应 当 xcap p

22、ut 请求被执行并其请求的 resrouce 已经产生. 示例消息: http/1.1 201 created etag: ababab . . . content-length: 0 4.3错误错误响应响应 xcap 使用与http协议相同定义的错误响应状态码。tdcs支持3类错误状态码：3xx, 4xx, 和 5xx. 3xx 是重定向状态码，指示客户端为满足请求去采取其它的行动。4xx 是客户端错 误码，指出客户端请求可能包含的错误. 5xx 是服务器错误码，指示服务器知道自己遇到问 题而不能处理当前的请求。 状态码状态码描述描述 304not modified 400bad reque

23、st 403forbidden 404not found 405method not allowed 409conflict 412precondition failed 415unsupported media type 500internal server error 503service unavailable error 4.3.1错误响应描述错误响应描述 304 (not modified) 响应 在条件 get 中使用. 客户端在 if-none-match 头中包含的 etag 与服务器所具有的该文档 etag 相同 响应消息示例: http/1.1 304 not

24、 modified content-type: text/plain; charset=iso-8859-1 content-length: 0 403 (forbidden) 响应 可以对 xcap get/put/delete 操作响应. tdcs 不能处理该请求，尽管理解该请求。 tdcs 可能携带请求被拒绝的原因在 403 响应的“reason-phrase”中。 响应消息示例: http/1.1 403 forbidden. the request is not allowed since the associated feature is locked. conten

25、t-type: text/plain; charset=iso-8859-1 content-length: 0 400 (bad request) 响应 可以对 xcap get/put/delete 操作响应。由于语法错误 tdcs 不能理解该请求. 响应消息示例: http/1.1 400 bad request content-type: text/plain; charset=iso-8859-1 content-length: 0 404 (not found) 响应 可以对 xcap get/put/delete 操作响应. tdcs 不能找到被请求的

26、资源。 响应消息示例: http/1.1 404 not found content-type: text/plain; charset=iso-8859-1 content-length: 0 405 (method not allowed) 响应 可以对 xcap 请求响应. tdcs 理解请求的方法但是不支持该操作 响应消息示例: http/1.1 405 method not allowed content-type: text/plain; charset=iso-8859-1 content-length: 0 409 (conflict) 响应 可以对

27、 xcap get/put/delete 操作响应。请求因对当前资源的冲突而不能完成。 409 响应可携带 xml 消息体来指定冲突的具体原因。 以下是 409 响应中所包含的“xcap-error” data schema. “xcap-error” 可以用来给出具体冲突原因。 客户端应该支持以下 schema： 响应消息示例: http/1.1 409 conflict content-type: application/xcap-error+xml content-length: xxxxx 412 (precondition failed) 响应 可以对 xcap get

28、/put/delete 操作响应。 客户端可以携带 if-match 头域来包含客户端 所具有的 etag. 如果文档在服务器中已改变，412 就会被返回. 响应消息示例: http/1.1 412 precondition failed content-type: text/plain; charset=iso-8859-1 content-length: 0 415 (unsupported media type) 响应 可以对 xcap get/put/delete 操作响应。 终端数据配置服务器不接受请求消息中的内 容编码。 响应消息示例: http/1.1 415 un

29、supported media type content-type: text/plain; charset=iso-8859-1 content-length: 0 500 (internal server error) 响应 可以对 xcap get/put/delete 操作响应. 终端数据配置服务器遇到不可预料的情况不能 完成请求. 响应消息示例: http/1.1 500 internal server error content-type: text/plain; charset=iso-8859-1 content-length: 0 0503 (se

30、rvice unavailable) 响应 可以对 xcap get/put/delete 操作响应. 终端数据配置服务器因过载或维护等原因暂时 不能处理请求. 响应消息示例: http/1.1 503 service unavailable content-type: text/plain; charset=iso-8859-1 content-length: 0 4.4操作终端数据配置文档操作终端数据配置文档 4.4.1data schema tdcs 支持以下终端数据配置文档 schema。 4.4.2使用场景使用场景 场景总结 创建/替换用户终端数据配置文档 查询用户终端

31、数据配置文档 增加 call restriction 删除 call restriction 查询和更新用户其它配置参数 创建创建/ /替换用户终端数据配置文档替换用户终端数据配置文档 .1.概述 该操作用来创建/替换适用于某用户的终端数据配置文档. 只有系统管理员可以创建/替换用户的终端配置文档。 成功的 xcap put 操作会返回 201 created 响应（创建文档）或 200 ok 响应 （替换文档） . 失败的操作会返回 403 (forbidden), 404 (not found) , 409 (conflict) 或 412 (precondit

32、ion failed)。 .2.用例 admintdcs 1. xcap put 2.a 201 created 2.b 403/404/409/412 图 4-1 管理员创建用户终端书记配置文档 1.管理员创建一个用户终端数据配置文档。它发起一个 xcap put 请求 请求消息: put http:/fqdn of tdcs server/service name/user-config/users/xui of user/index http/1.1 . . . clientid: requestors xui content-type: application/user-

33、config+xml content-length: xxxxx document content 请求消息示例: 创建不含 call restrictions 的配置文件 put http:/sh.glms.vnet.mobi:9445/tdcs-services/user- config/users/4600013311111111111ptt http/1.1 . . . clientid: systemadmptt content-type: application/user-config+xml content-length: xxxxxtt 0280 tr

34、ue false 请求消息示例: 创建含 call restrictions 的配置文件 put http:/sh.glms.vnet.mobi:9445/tdcs-services/user- config/users/4600013311111111111ptt http/1.1 . . . clientid: systemadmptt content-type: application/user-config+xml content-length: xxxxxtttt 0 1 1 1 1 0 0280 true false 2.a td

35、cs 接受请求返回 201 created. 2.b tdcs 拒绝请求返回 403/404/409/412 错误响应，并包含详细的错误信息 响应消息: http/1.1 201 created . . . etag: etag number content-length: 0 响应消息示例: http/1.1 201 created . . . etag: ababab content-length: 0 查询用户终端数据配置文档查询用户终端数据配置文档 .1.概述 该操作用来从“用户树”下获取用户终端数据配置文档. xcap get 请求的响应消息包含 详细的文

36、档信息. 某用户可以获取自己的用户终端配置文档。系统管理员可以获取所有用户的终端配置文档。 终端也要利用该操作获取创建或更新的配置信息。 成功的 xcap get 操作会返回 200 ok 响应，并包含群组信息. 失败的操作会返回 304 (not modified ), 403 (forbidden) 或 404 (not found)等。 .2.用例 admintdcs 1. xcap get 2.a 200 ok 2.b 304/403/404 图 4-2 管理员得到一个终端数据配置文档 1.管理员要得到一个用户的终端配置文档。它发起 xcap get 请求 请求消息: g

37、et http:/fqdn of tdcs server/service name/user-config/users/xui of user/index http/1.1 . . . if-none-match: etag number clientid: requestors xui content-length: 0 请求消息示例: get http:/sh.glms.vnet.mobi:9445/tdcs-services/user- config/users/4600013311111111111ptt http/1.1 . . . if-none-match: ababab cli

38、entid: systemadmptt content-length: 0 2.a tdcs 接受 xcap get 请求返回 200 ok 响应，并包含配置信息 2.b tdcs 拒绝请求返回 304/403/404 错误响应，并包含详细的错误信息 响应消息: http/1.1 200 ok etag: etag number content-type: application/user-config+xml content-length: xxxxx . . . document content 响应消息示例: http/1.1 200 ok etag: bcbcbc content-ty

39、pe: application/vnd.oma.poc.groups+xml content-length: xxxxxtttt 0 1 1 1 1 0 0280 true false 增加增加 callcall restrictionrestriction .1.概述 该操作可以用来修改终端数据配置文档增加 call restriction。xcap put 被使用。请求 消息中携带新的 call restriction。 只有系统管理员可以发起此操作。 成功的 xcap put 操作返回 201 created

40、 响应. 失败的操作会返回 403 (forbidden), 404 (not found)，409 (conflict)和 412 (precondition failed)。 注：增加的 call restriction 是由 cr-order 来唯一标识的。如果新加的 call restriction 的 cr- order 在文档中已经存在，本操作会变成对已有 call restriction 的替换，如果成功会返回 200 ok. .2.用例 admintdcs 1. xcap put 2.a 201 2.b 403/404/409/412 图 4-3 管理员增加某一用

41、户的 call restrictions 配置信息 1.管理员想增加某一用户的 call restriction 配置信息，发起一个 xcap put 请求 注意：发起的请求 uri 中，必须指定新的 call restriction 的 cr-order. cr-order 表示该 call restriction 的顺序，它必须与已有 call restriction 的 cr-order 不同。否则，tdcs 认为这是对已有 call restriction 的替换。 请求消息： put http:/fqdn of tdcs server/service name/user-config

42、/users/xui of user/index/user- config/carrier-level-call-restrictions/call-restrictioncr-order=”cr order attribute value” http/1.1 . . . if-match: etag number clientid: requestors xui content-type: application/xcap-el+xml content-length: xxxxx document content 请求消息示例: put http:/sh.glms.vnet.mobi:944

43、5/tdcs-services/user- config/users/4600013311111111111ptt restrictioncr-order=”3” http/1.1 . . . if-match: abcde clientid: systemadmptt content-type: application/xcap-el+xml content-length: xxxxx * 1 1 0 2.a tdcs 接受请求返回 201 created. 2.b tdcs 拒绝请求返回 403/404/409/412 错误响应，并包含详细的错误信息 响应消息： http/1.1 201

44、created . . . etag: etag number content-length: 0 响应消息示例: http/1.1 201 created . . . etag: ababab content-length: 0 删除删除 callcall restrictionrestriction .1.概述 该操作可以用来修改终端数据配置文档删除 call restriction。xcap delete 被使用。 只有系统管理员可以发起此操作。 成功的 xcap delete 操作返回 200 ok 响应. 失败的操作会返回 403 (forbidden),

45、 404 (not found)或者 412(precondition failed)。 .2.用例 admintdcs 1. xcap delete 2.a 200 2.b 403/404/409/412 图 4-4 管理员删除某一用户的 call restriction 配置信息 1.管理员想删除某一用户的 call restriction 配置信息，发起一个 xcap delete 请求 请求消息： delete http:/fqdn of tdcs server/service name/user-config/users/xui of user/index/user-

46、config/carrier-level-call-restrictions/call-restrictioncr-order=”cr order attribute value” http/1.1 . . . if-match: etag number clientid: requestors xui content-length: 0 请求消息示例: put http:/sh.glms.vnet.mobi:9445/tdcs-services/user- config/users/4600013311111111111ptt restrictioncr-order=”3” http/1.1

47、 . . . if-match: abcde clientid: systemadmptt content-length: xxxxx 2.a tdcs 接受请求返回 200 ok. 2.b tdcs 拒绝请求返回 403/404/409 错误响应，并包含详细的错误信息 响应消息： http/1.1 200 ok . . . etag: etag number content-length: 0 响应消息示例: http/1.1 200 ok . . . etag: ababab content-length: 0 查询和更新用户其它配置参数查询和更新用户其它配置参数 4.4.2

48、.6.1.概述 该操作可以用来修改终端数据配置文档中 user capability 所包含的参数。user capability 包括 call-type-capability，add-mem-disable-privilege，talk-group-permission 等参数。xcap put 被使用。 只有系统管理员可以发起此操作。 成功的 xcap put 操作返回 200 ok 响应. 失败的操作会返回 403 (forbidden), 404 (not found)，409 (conflict) and 412 (precondition failed)。 .2.用

49、例 admintdcs 3. xcap put 4.a 200 4.b 403/404/409/412 1. xcap get 2. 200 图 4-5 管理员更新某一用户的 user capability 参数 1， 2：管理员想更新某一用户的 user capability 中包含的某一参数，首先发起一个 xcap get 请求获取整个文档中的已有参数 详细消息参见“查询用户终端数据配置文档” 3， 4：管理员更改该用户的 user capability 参数，发起一个 xcap put 请求放回更改过 的文档 详细消息参见“创建/替换用户终端数据配置文档” 5

50、终端数据配置服务器短消息（终端数据配置服务器短消息（sms）接口规范）接口规范 从 tdcs 的角度看，短消息是从 tdcs 服务器发送给 smgw，而 smsc 负责把短消息发 送给手机。 短信发送流程如下图： 图 5-1短信发送流程 步骤说明如下： 1. tdcs 服务器与业务网关之间的连接采用 smgp 协议，其 mserviceid=ptt； 2. 业务网关收到 mserviceid 为“ptt”的短消息后，将 mserviceid=ptt 透传到 smpp 协 议的 servicetype 字段，然后将 smpp 消息发送到短信中心； 3. 短信中心根据 servicetype=ptt，将下发到手机的 teleserviceid 填为 65010。 本章定义 tdcs 和短信中心发出的短消息负荷的格式。 5.1tdcs 通知的短消息通知的短消息负荷负荷 tdcs 短消息接口用来给用户终端发送有关配置信息更新的通知。 当用户的终端数据配置文档