中国电信qchat业务终端参数配置接口技术要求-群组数据分册

中国电信 Qchat 业务终端参数配置接口技术要求 群组 数据分册 （征求意见稿） 中国电信股份有限公司广州研究院 二零 壹 零年 三 月 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 2 页 目录 目录 .2 1 范围 .4 1.1 文档更改历史 .4 2 缩略语 .6 3 群组管理服务器 HTTP 服务 .7 3.1 支持的 HTTP 方法 .7 3.2 支持的 HTTP 头 .7 3.2.1 适用于所有操作的头 .7 3.2.2 PUT 和 POST 必须携带的头 .7 3.2.3 GET 多播群组 GSK 必须携带的头： Q-CNONCE .8 3.2.4 用于条件操作 HTTP 头 .8 3.3 群组管理服务器 XCAP 请求 URL . 10 3.4 群组管理服务器器后向兼容对客户端 XML 解析的要求 . 11 4 群组管理服务器 HTTP 接口规范 . 12 4.1 概述 . 12 4.2 正常响应 . 12 4.2.1 正常响应描述 . 12 4.3 错误响应 . 13 4.3.1 错误响应描述 . 13 4.4 操作共享群组（ SHARED GROUP）文档 . 17 4.4.1 Data Schema . 17 4.4.2 使用场景 . 26 4.5 多播共享群组的多播信息（ MULTICAST INFORMATION）管理 . 54 4.5.1 Data Schema . 54 4.5.2 使用场景 . 56 4.6 组关联（ GROUP ASSOCIATION） 管理 . 67 4.6.1 Data Schema . 68 4.6.2 使用场景 . 69 4.7 组查询接口 . 72 4.7.1 Data Schema . 72 4.7.2 使用场景 . 72 5 群组管理服务器 短消息（ SMS）接口规范 . 76 5.1 GLMS 不同类型通知的短消息负荷 . 76 5.1.1 组关联更新通知 . 76 5.1.2 给组主管理人的 “自动退出” 通知 . 78 6 典 型的端到端用例 . 79 6.1.1 向共享群组里加组成员 . 79 7 群组服务器客户端的配置信息 . 82 7.1 配置信息 . 82 7.2 主副地址切换建议 . 82 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 3 页 8 对手机端和用户管理平台群组操作能力的建议 . 83 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 4 页 1 范围 群组管理服务器 (GLMS) 是基于 OMA XDMS 的体系要求实现的群组管理和 XML 文档管理服务器 . 它提供对用户的 XML 文档如共享群组文档的管理 . 文档的管理操作包括读取 /增加 /修改 /删除 . 这些操作是通过 XCAP 接口完成的。 群组管理服务器 (GLMS) 还提供群组的搜索能力。客户端可以提供诸如组主管理人，组成员等信息来搜索对应的共享群组。 本文定义与 群组管理服务器 (GLMS)进行通信时的接口规范。 本文用 GLMS表示群组管理服务器。 1.1 文档更改历史 时间 说明 2009.2.16 以下为更改的主要内容： 3.3 : 增加对 FQDN 使用的解释 5.1 : 短消息负荷更改 5.1.1 : 终端获取 XUI 的方法更改 7.1 : 服务器故障转移定时 参数取值修改 7.2 : 增加了主副地址切换的方法建议 另外更改了一些拼写错误。 2009.3.2 3.2.3 : 定义 Q-CNONCE 携带的 cnonce 格式 3.2.3, , 6.1.1: 增加 GLMS 在响应消息中返回 Q-CNONCE的内容和示例，去掉 GSK Time 需要加密的内容 4.6.1, .2, 6.1.1, 组关联中增加可选的 premium-flag 指示该用户是否为特别用户 4.5.1 Data Schema 中 gsk-old, gsk-new 改为 256 bit， gsk-time 改为32 bit. 并据此改动 , 6.1.1 中相应数据的格式 2009.6.25 4.4.1 Data Schema 中的 修改为 4.5.1 Data Schema 中的 修改为 2009.7.14 5.1、 5.1.1、 5.1.2： 修改 GLMS 采用 SMGP 协议要求及流程说明 。 2009.8.5 5.1、 5.1.1、 5.1.2：修改 GLMS 发送的 为，以及针对 的样例“ QCHAT”修改 为“ PTT” 。 2009.8.5 修改组关联更新流程图。 2009.8.5 修改组成员退出提示要求。 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 5 页 时间 说明 2009.8.31 1回退 2009.6.25 在 4.4.1 和 4.5.1 中做的对 schema 的修改。即schema 中“ conference-id”仍然保持为 minOccurs=0 2 4.6.1 中 group-association 的 data schema 中加入 “ conference-id”元素。 3 4.6.1 中 group-association 的 data schema 中加入 “ xs:any”元素以备将来扩展别的元素 4 .2 和 6.1.1 中查询用户组关联的返回消息示例中，加入conference-id”元素。 5文档 URI 示例中 改为 6. 文档示例中用户域名和群组域名改为 , 和 2009.11.18 更正图 5-1 中的协议标识。 2009.11.23 修改文档中所有“ ”为“ ”。 2010.3.1 修改文档中所有“ ”为“ ”。 2010.3.25 修改文档中所有“ ”为“ sh.glms.vnet.mobi:9444”。 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 6 页 2 缩略语 缩略语 定义 3GPP 3rd Generation Partnership Project AUID Application Usage ID FQDN Fully Qualified Domain Name GLMS Group and List Management Server HTTP Hypertext Transfer Protocol IETF Internet Engineering Task Force OMA Open Mobile Alliance SMPP Short Message Peer-to-peer Protocol SMSC Short Message Service Center URI Uniform Resource Identifier URL Uniform Resource Locator XCAP XML Configuration Access Protocol XDM XML Document Management XDMC XML Document Management Client XDMS XML Document Management Server XML Extensible Markup Language XUI XCAP User Identity 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 7 页 3 群组管理服务器 HTTP 服务 3.1 支持的 HTTP 方法 GLMS支持以下 HTTP操作 : HTTP GET （获取群组信息） HTTP PUT (根据不同的上下文， PUT 操作支持增加或修改群组内容 ) HTTP DELETE （删除群组信息） HTTP POST （搜索群组信息） 3.2 支持的 HTTP 头 3.2.1 适 用于 所有操作的头 用于认证的头 : ClientID “ClientID” 在每个 HTTP请求中都必须携带 . “ClientID” 可以被 WAP 网关或用户群组管理平台加入，并随请求消息送到 GLMS。 ClientID应该 携带明文的用户 ID 信息。 GLMS 信任“ ClientID”所包含的用户 ID 就是请求发起者的用户 ID。 注意：运营商也可以选用其它的 HTTP 头作为用于认证的头，如： 3GPP-Accerted-Identify. 但所有的发送到 GLMS 的请求必须使用相同的头。 用于识别客户端协议版本的头 : GLMSClientVersion “GLMSClientVersion” 在每个 HTTP请求中都必须携带 . GLMS 客户端用 “GLMSClientVersion”表示它所实现的 GLMS 协议版本。对应于本规范，版本号应为 “ 11.01” 注意：运营商也可以选用其它的 HTTP 头作为用于版本标识的头，如： GLMS-Group-Version. 但所有的发送到 GLMS 的请求必须使用相同的头。 3.2.2 PUT 和 POST 必须携带的头 对 XCAP PUT 操作 , 下列 HTTP 头必须携带： “Content Type” 和 “Content Length”. Content Type Content-Type 头域指定所包含的消息体的媒体类型。其格式为 : Content-Type = Content-Type : media-type 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 8 页 GLMS 中有效的 content type 为 : Content-Type: text/plain Content-Type: application/xcap-error+xml Content-Type: application/vnd.oma.poc.groups+xml Content-Type: application/xcap-el+xml Content-Type: application/xcap-att+xml Content-Type: application/group-association+xml Content-Type: application/vnd.oma.search+xml 参见接口定义确定在何种情况下使用何种 content type. Content Length Content-Length 头域指定消息体的长度 （ 8 位字节数）。其格式为： Content-Length = Content-Length : 1*DIGIT 例如 : Content-Length: 3495 3.2.3 GET 多播群组 GSK 必须携带的头： Q-CNONCE 当客户端想要 发送 XCAP GET 请求来获取多播群组的包括 GSK 在内的多播信息时，必须携带 Q-CNONCE 头。该 HTTP 头包含 PTT 客户端产生的 cnonce 值。 GLMS 会利用该 cnonce 产生用于加密GSK 的密钥： PEK。返回的 GSK 是加密后的格式。 Q-CNONCE 中携带的 cnonce 必须是 128 bit, 以 16 进制格式传送（ 0-9， A-E 为有效字符），如： Q-CNONCE: 102E3A4D516B7085910A1E2C3D40526A 在返回的响应消息中， GLMS 会将请求中携带的 cononce 用 Q-CNONCE 头带回，以备终端使用。 具体参见 。 3.2.4 用于条件操作 HTTP 头 HTTP 定义了几个可以被客户端用来做条件请求的头域： If-None-Match 和 If-Match。 客户端可以根据所请求资源的实体标签（ entity tag）来做条件请求 . 这些条件请求的头域在请求消息里是可选用的 . 条件请求的头域可以解决并发请求的冲突问题。 If-Match 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 9 页 If-Match 请求头域被 HTTP 方法 (PUT/DELETE)用来做有条件操作 . 对一个或多个从群组服务器获得的实体， XDS 客户端可以在请求的 If-Match 头中包含某个实体的entity tag 以 确认它所具有的那个实体是最新的 . If-Match 头可以被用在以下场景中 : 条件 PUT XDM 客户端想增加或修改服务器 XDM 文档中的某个元素（ element），并且希望服务器所具有的文档版本和客户端当前所具有的那个文档相同时才能修改。客户端可以在请求中包含 If-Match 头 , 并将客户端所具有的实体标签（ entity tag）值写在里面 . 如果文档已经改变，群组服务器会拒绝这个请求返 回 412 （条件失败） . 在这种情况下，客户端需要重新用 GET 请求从服务器获取这个文档并保存服务器在 200 OK 中返回的新的实体标签（ entity tag）。 客户端可以把新的 实体标签（ entity tag）放在 If-Matc 头中 重新请求修改文档。 如果操作成功， 响应消息的 etag 头会包含刚被修改过的资源的新的实体标签（ entity tag）。 条件 DELETE XDM 客户端也可以在 DELETE 请求中包含 If-Match 头来做条件删除 . DELETE 请求的 200 OK 响应会包含一个 etag 头域 , 带有所删除元素所在的整个文档的实体标签（ entity tag） If-None-Match If-None-Match请求头域可以和 GET请求方法一起使用做条件请求 . If-None-Match头中 可以包含客户端以前从服务器所获取的资源实体的 实体标签（ entity tag） 。 If-None-Match 头可以被用在以下场景中 : 条件 GET 当 XDM 客户端本地存有一个文档的版本，它可以做条件 GET 来判断服务器对统一文档是否有更新。如果本地文档仍然是最新的，客户端就不会重新下载文档，以此 节省网络的使用。为了达到这个目的，客户端在 GET 请求中携带 If-None-Match 头域，其中包含客户端当前文档的 实体标签（ entity tag） . 群组服务器如果发现服务器文档标签和客户端不同，会响应 200 OK. 如果服务器文档标签和客户端相同 , 服务器会响应 304. 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 10 页 3.3 群组管理服务器 XCAP 请求 URL 1. XCAP 根节点 （ XCAP root） XCAP 根定义了所有可被请求的资源所在的位置 . XCAP 根用 HTTP URI 表示 , 被称为XCAP 根 RUI。对群组服务 XCAP 根 被定义为 /GLMS FQDN/glms-services. 注：在具体构造 HTTP 请求时， GLMS FQDN 应该为 GLMS 服务器的地址，并且在发出HTTP 请求时放在 HOST HTTP 头中，而不是在 Request-URI 中。另外，由于 GLMS 有主副地址， GLMS FQDN 可能是两个。（关于主副地址，请参见第 7 章） 2. 文档选择器 （ Document Selector） 在文档根节点下的每一个 XML 文档使用文档选择器唯一标识，文档选择器类似于由多 个路径标识符组成的一个完整路径，使用“ /”作为路径分隔符 . 第一个路径部分必须是XCAP AUID。对群组服务器而言，有以下 三 种 XCAP AUID: ORG.OPENMOBILEALLIANCE.GROUPS: 用来进行群组的操作 MULTICAST-INFO: 用来操作群组的多播信息 GROUP-ASSOCIATION：用来获取个人所在的群组信息 在每个 AUID 下有两个子 XCAP 分支 . 一个成为 “用户树”（“ user” tree） , 保存某个用户的所有文档。 另一个分支是“全局树”（“ global” tree） , 保存适用于所有用户的文档 . AUID 之后的路径部分必须是 global 或 users. 在“用户树”下是零个或多个子树，每个子树包含某个用户的文档。每个用户对服务器而言都有一个用户名，被称为 XCAP 用户表示（ XCAP User Identifier: XUI). 文档选择器余下的部分 (global 或 XUI 以后的路径指向具体的文档名 . 3. 节点选择器 （ Node selector） 节点选择器指定 XML 文档中具体被操作的节点 . 节点选择器指向 XML 元素或元素属性 . 4. 产生 GLMS 请求 URL 访问群组管理服务器的某个用户的 XML 文档 , 使用以下的 URL 格式 : http:/FQDN of GLMS server/service name/AUID/users/XUI of user/group document name 访问 GLMS 的全局的 XML 文档 , 使用以下的 URL 格式 : http:/FQDN of GLMS server/service name/AUID/global/index 访问 GLMS 文档的 XML 元素，使用以 下的 URL 格式 : document selector/node selector 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 11 页 文档选择器（ Document selector） 部分可以是用户特定的文档或全局文档。节点选择器（ node selector ）部分是 XML 文档中的元素 . 更多详情参见本规范的具体例子 . 3.4 群组管理服务器器后向兼容对客户端 XML 解析的要求 这里的群组管理服务器客户端指所有与 GLMS 进行 HTTP/XCAP 通信客户端应用程序。GLMS 会不断加入新的功能 . 群组管理的 XML schema 在将来可能会扩展。 GLMS 升级到新的版本而客户端有可能仍然是旧的版本。为了使 GLMS 后向兼容， GLMS 客户端的实现必须要遵循以下建议 : o GLMS 客户端必须忽略服务器返回的合法的 XML 文档中不能识别的 XML 元素 或属性，而不是报错退出对文档的处理 . 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 12 页 4 群组管理服务器 HTTP 接口 规范 4.1 概述 GLMS 为客户端应用提供 XCAP 接口来管理服务器存储的群组 XML 文档 . 客户端应用可以 读取 /更新 /删除 XML 文档及其 XML 元素和属性 . 本章给出群组管理服务器 XCAP 接口规范。 4.2 正常响应 如果客户端的请求被成功处理， GLMS支持成功的 2xx 状态码： 状态码 描述 200 OK 201 Created 202 Accepted 4.2.1 正常响应描述 200 (OK) 响应 当 XCAP GET/PUT/DELETE 请求被成功处理时返回 . 示例消息 : HTTP/1.1 200 OK etag: bcbcbc Content-Length: 0 . . . 201 (Created) 响应 当 XCAP PUT 请求被执行并其请求的 resrouce 已经产生 . 示例消息 : HTTP/1.1 201 Created etag: ababab . . . Content-Length: 0 202 (Accepted) 响应 当 XCAP PUT 请求正在执行但处理并没有全部完成 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 13 页 示例消息 : HTTP/1.1 202 Accepted . . . Content-Length: 0 4.3 错误响应 XCAP 使用与 HTTP协议相同定义的错误响应状态码。 GLMS支持 3类错误状态码： 3xx, 4xx, 和 5xx. 3xx 是重定向状态码，指示客户端为满足请求去采取其它的行动。 4xx 是客户端错误码，指出客户端请求可能包 含的错误 . 5xx 是服务器错误码，指示服务器知道自己遇到问题而不能处理当前的请求。 状态码 描述 304 Not Modified 400 Bad Request 403 Forbidden 404 Not Found 405 Method Not Allowed 409 Conflict 412 Precondition Failed 415 Unsupported Media Type 500 Internal Server Error 503 Service Unavailable Error 4.3.1 错误响应描述 304 (Not Modified) 响应 在条件 GET 中使用 . 客户端在 If-None-Match 头中包含的 etag 与服务器所具有的该文档 etag相同 响应消息示例 : HTTP/1.1 304 Not Modified Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 403 (Forbidden) 响应 可以对 XCAP GET/PUT/DELETE 操作响应 . GLMS 不能处理该请求 ， 尽管 理解该请求。 GLMS 可能携带请求被拒绝的原因在 403 响应 的“ reason-phrase” 中。 响应消息示例 : HTTP/1.1 403 Forbidden. The request is not allowed since the associated feature is locked. Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 14 页 400 (Bad Request) 响应 可以对 XCAP GET/PUT/DELETE 操 作响应。由于语法错误 GLMS 不能理解该请求 . 响应消息示例 : HTTP/1.1 400 Bad Request Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 404 (Not Found) 响应 可以对 XCAP GET/PUT/DELETE 操作响应 . GLMS 不能找到被请求的资源。 响应消息示例 : HTTP/1.1 404 Not Found Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 405 (Method Not Allowed) 响应 可以对 XCAP GET/PUT/DELETE 和 HTTP POST 操作响应 . GLMS 理解请求的方法但是不支持该操作 响应消息示例 : HTTP/1.1 405 Method Not Allowed Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 409 (Conflict) 响应 可以对 XCAP GET/PUT/DELETE 操作响应。请求因对当前资源的冲突而不能完成。 409 响应可携带 XML 消息体来指定冲突的具体原因。 以下是 409 响应中所包含的 “xcap-error” data schema. “xcap-error” 可以用来给出具体冲突原因。客户端应该支持以下 schema： 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 15 页 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 16 页 响应消息示例 : HTTP/1.1 409 Conflict Content-Type: application/xcap-error+xml Content-Length: xxxxx 412 (Precondition Failed) 响应 可以对 XCAP GET/PUT/DELETE 操作响应。 客户端可以携带 If-Match 头域来包含客户端所具有的 etag. 如果文档在服务器中已改变， 412 就会被返回 . 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 17 页 响应消息示例 : 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 Unsupported 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 0 503 (Service Unavailable) 响应 可以对 XCAP GET/PUT/DELETE 操作响应 . 群组服务器因过载或维护等原因暂时不能处理请求 . 响应消息示例 : HTTP/1.1 503 Service Unavailable Content-Type: text/plain; charset=ISO-8859-1 Content-Length: 0 4.4 操作 共享 群组 （ Shared Group）文档 4.4.1 Data Schema GLMS 扩展了 共享群组 （ Shared Group） schema 以支持 QChat 群组。 . 1. shared group schema 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 19 页 2. shared-group-lucent.xsd 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 20 页 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 21 页 3. resource-lists.xsd 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 22 页 中国电信 qchat 业务终端参数配置接口技术要求 -群组数据分册 第 23 页 4. xml.xsd See /XML/1998/namespace.html and /TR/REC-xml for information about this namespace. This schema document describes the XML namespace, in a form suitable for import by other schema documents. Note that local names in this namespace are intended to be defined only by the World Wide Web Consortium or its subgroups. The following names are currently defined in this namespace and should not be used with conflicting semantics by any Working Group, specification, or document instance: base (as an attribute name): denotes an attribute whose value provides a URI to be used as the base for interpreting any relative URIs in the scope of the element on which it appears; its value is inherited. This name is reserved by virtue of its definition in the XML Base specification. id (as an attribute name): denotes an attribute whose value should be interpreted as if declared to be of type ID. The xml:id specification is not yet a W3C Recommendation, but this attribute is included here to facilitate experimentation with the mechanisms it proposes. Note that it is _not_ included in the specialAttrs attribute group. lang (as an attribute name): denotes an attribute whose value is a language code for the natural language of the content of any element; its value is inherited. This name is reserved by virtue of its definition in the XML specification. space (as an attribute name): denotes an attribute whose value is a keyword indicating what whitespace processing discipline is intended for the content of the element; its value is inherited. This na