You are looking at the HTML representation of the XML format.
HTML is good for debugging, but probably is not suitable for your application.
See complete documentation, or
API help for more information.
<?xml version="1.0"?>
<api>
<query-continue>
<allpages gapfrom="XEP-0016" />
</query-continue>
<query>
<pages>
<page pageid="759" ns="0" title="Tigase:用GUI安装包安装">
<revisions>
<rev xml:space="preserve">[[Category:XMPP服务器文档]]
[[Category:已翻译]]
'''本文的英文原文来自 http://www.tigase.org/content/installation-using-gui-installer '''
如果你不想使用手动方式来安装Tigase, 你可以使用GUI安装包. 它不只拷贝服务器文件到首选的位置, 而且辅助配置大部分参数和数据库设置. 所以它安装Tigase的首选方式.
==前提条件==
在你能够启动GUI安装包之前，你将需要一个Java工作环境. 尽管安装包只要求 '''JRE''' (Java运行时环境), 服务器需要 '''JDK''' (Java开发包). 请注意目前 '''Tigase可以运行的的最低JDK版本是1.6''' . 如果你还没有安装JDK，现在该装上它了. 访问 [http://java.sun.com/javase/downloads/index.jsp Java下载网站], 从可用的包列表中选择最新的JDK版本(如果你没有使用J2EE的特别需求，那么选择一个不带它的包). 在配置了JDK之后你可以下载 Tigase GUI安装包并开始服务器安装过程. 把 '''JAVA_HOME''' 环境设置正确也是非常重要的.
==下载安装包==
你总是能在[http://www.tigase.org/content/tigase-downloads?fid=1624 下载章节]找到最新的Tigase包. 当你进入该页面, 你将看到一个可选的文件列表. 开始你可能很疑惑有太多选择, 但是你不需要担心. 所有Tigase二进制包都有约定的名称, 这帮助你很容易地区分它们. 它们的格式是 '''tigase-server-x.y.z-bv.ext''' ，这里 'x', 'y', 'z' 和 'v' 是版本号并且它们的变更是从每一次发布. Ext 是文件扩展名，这里我们的GUI安装包程序是 '''.jar''' . 我们推荐你下载该服务器的最新版本(最高的版本号)，因为它包含了最新的功能和提升.
==运行jar文件==
在大部分系统中安装了JRE或JDK之后会创建缺省的文件关联以允许运行 '''.jar''' 文件，通过 点击/双击 它. 无论如何如果当你点的时候什么都没发生你可以手工执行它. 按顺序执行以下步骤:
1. 如果你在Windows系统上你可以使用命令行提示方式来使用java命令直接运行安装包.
:# 点击 '''开始''' 菜单并选择 '''运行''' 操作(你也可以使用 '''Win''' + '''R''' 快捷方式).
:# 你将看到一个对话框，这里你可以输入一条命令. 键入 '''"cmd"''' (或 "command" ，在某些2000之前的老的windows版本中) 并提交该窗口.
:如果你在Linux系统, 你可以使用一个终端. 在这个平台上它是一个标准工具并且很容易找. 找到并运行它.
2. 命令提示 / 终端 将出现. 你将能检查是否你的Java环境在正常工作. 键入以下命令然后回车.
<source lang="bash">
java -version
</source>
:如果返回的消息说无法识别该命令那么你的 '''Java''' 安装可能是错误的或配置不正确. 为了正确设置 '''JRE/JDK''' 包括设定 '''JAVA_HOME''' 环境变量，请检查JDK下载网站提供的文档. 如果命令成功了请检查列出来的版本号码满足Tigase的要求. 当一台机器上装了多个版本的 '''JDK/JRE''' ，'''java''' 命令将需要使用它所在的全路径来调用.
3. 当你毫无疑问你能运行正确的java命令, 你可以启动该安装包. 即被下载到 '''c:\download''' 目录的文件 '''tigase-server-4.1.0-b1315.jar''' ， 键入以下命令:
<source lang="bash">
java -jar c:\download\tigase-server-4.1.0-b1315.jar
</source>
:这个命令应该启动该安装包或列出一个错误消息来解释出现了什么问题.
==开始安装==
请注意本教程只涉及基本的安装模式. 一些屏幕被忽略了，因为它们包含在简单安装模式中没有的高级选项. 另一方面其他比如文件拷贝过程和总结信息等自解释的过程也没有描述.
===JDK选择===
http://www.tigase.org/files/image/gui-install/winInstall2Mini.gif
这个屏幕只在JDK没有被自动选择的时候出现. 当你的 JAVA_HOME path 正确的设置了, 它将被自动探测到以节省你的配置时间. 如果你读到这一步而仍然未安装JDK, 那么返回[[Tigase:用安装包安装#前提条件|前提条件]]， 那里你能找到一些关于如何为Tigase安装准备你的系统的信息. 有时你的系统将被配置成阻止探测JDK路径. 这经常发生你在安装了JDK之后再安装JRE的情况下. 你将不得不自己去找JDK目录. 它的缺省安装位置在你的系统驱动盘的 '''Program Files\Java''' 目录.
===安装类型选择===
http://www.tigase.org/files/image/gui-install/winInstall3Mini.gif
推荐的实践是同时选择安装和配置服务器，因为手动配置服务器比较复杂，耗时且易于出错.
===介绍服务器===
http://www.tigase.org/files/image/gui-install/winInstall4Mini.gif
这个屏幕显示一些关于Tigase的信息，帮助你理解它是什么以及如何帮你获得XMPP协议的好处. 阅读安装包上出现的所有信息是很重要的, 因为它们包含了有价值的建议和大部分最近的信息.
===选择程序根目录===
http://www.tigase.org/files/image/gui-install/winInstall6Mini.gif
在这个点你选择你希望你的服务器装到哪. 推荐的路径应该不包含空格, 因为它可能导致一些未知的路径问题. 在Windows的安装场景下它应该被安装到一个短路径，因为路径长度有限制. 也要注意在Windows Vista下安装到 Program Files 目录可能会使得服务器的工作发生一些问题, 和UAC机制相关的工作, 所以最好不要安装到那. 如果你拿不定主意想把服务器装到哪, 你总是可以留着缺省值.
===包选择===
http://www.tigase.org/files/image/gui-install/winInstall7Mini.gif
下一个重要步骤是包选择. 一些选择是灰的并且你不能选择它们，因为它们是最基本的. 所有其他的包都是可选的. 它包括 文档, 数据库驱动, 服务器源码 和一些附属项. 当你选择一个条目, 你将看到关于它的内容的简短描述.
我们推荐你安装文档. 它包含了有价值的资源，非常有助于服务器的管理和常规使用.
如果你有一个工作着的数据库平台，你想用它来存储所有重要用户信息, 就选择适当的db驱动. 如果你没有一个数据库引擎, 你可以使用内置的derby，它的驱动也已经内置了.
如果你是一个开发者并且你想能检查该服务器如何工作或你想帮助开发, 你也可以安装被包含的源码.
===基本的服务器配置===
http://www.tigase.org/files/image/gui-install/winInstall13Mini(3).gif
在这个屏幕你将找到重要的基本配置选项. 本指南只涉及非高级的设置 - 禁止高级配置选项.
你可以选择安装哪些组件. 对于大部分安装来说缺省的选择是最适合的. 你可以展开这个列表来检查是否有任何其他选项更加满足你的需要.
对你来说在这正确地输入你的域名是非常重要的.
:* 在类 '''Linux''' 系统中你可以使用 '''hostname''' 命令并从输出结果中提取出域部分. 如果你使用 '''-f''' 参数，那么你将获得完整的合格域名.
:* 在 '''Windows''' 中使用标准 '''系统''' 控制台applet. 你将在 '''电脑名''' tab找到你的域名(电脑名).
另一方面如果你想使用Tigase的虚拟域支持，你要正确地配置你的 '''DNS''' 系统, 接着你可以在这里放你的虚拟域列表. 就用逗号把它们分开. 例如如果你的服务器从外部看是 '''veloci.tigase.org, mammoth.tigase.org''' 和 '''tigase.org''' ,然后你可以如同有三个分开的实例那样使用Tigase实例. 实际上它是一台服务器, 无论如何 '''admin@veloci.tigase.org''' 和 '''admin@tigase.org''' 将是不同的用户. 这个特性允许使用一个服务器用于分开的用户群体, 例如不同的组织.
现在你要把域名填到 域 文本框里. 下一个参数是服务器管理员的JID. 标准做法是给把它的名字设为 '''admin''' , 无论如何你可以选择任何你喜欢的名字. 例如对于域 '''tigase.org''' 完整的 admin 名称将是 '''admin@tigase.org''' . 把你选择的名称和域名连在一起，使用 @ 符号做分隔符.
从这个版本开始你的 XMPP admin 将被自动添加到数据库, 所以在安装之后你可以不用手工注册admin就登陆到服务器了.
你也应该选择一个数据库用于存储你的用户信息. 缺省的是 '''Derby''' 数据库, 如果你不需要任何特别的东西就保持那个配置. 选择一个新密码，因为缺省的密码可能很容易被黑客猜到.
'''重要通知: Tigase安装包不包含实际的数据库, 只有允许db访问的驱动. 一个例外是Derby数据库, 它被包含在JDK中. 这是由安装包自动配置的, 在使用其他数据库的情况下你将需要自己配置它们''' .
===数据库连接检查和执行DB任务===
http://www.tigase.org/files/image/gui-install/winInstall20Mini(1).gif
当你切换到这个屏幕的时候将启动一个数据库配置的自动测试. 它包括几个顺序执行的步骤. 在测试连接和配置schema之后, admin 用户将被添加.
如果测试失败该干什么?
:* 如果你决定使用你自己的数据库, 检查是否你输入了正确的密码和是否你的数据库在运行中.
:* 如果你使用内置的 '''Derby''' 数据库，那么可能你的问题更加复杂. 安装包的一个错误可能指出一个bug. 你可以把它汇报给Tigase开发者之一.
如果在解决了数据库问题之后你还不能度过这一步，你可以尝试手工安装模式.
==完成安装==
当你执行了所有那些步骤包括选择开始菜单位置以及其他基本动作，你将被通知安装过程已经完成了. 现在你可以使用你的Tigase服务器了. 可能有一些安装之后的动作你想去做. 它们主要如下所示.
==运行服务器==
安装过程的一部分是Tigase根目录的选择. 在这里你能找到所有重要的服务器文件. 安装包将在 '''开始''' 菜单创建一些可配置的快捷方式. 你可以在菜单中浏览并使用它来启动服务器. 如果要手工运行服务器:
:* 在一个 '''Linux''' 系统你可以使用Tigase服务器根目录下的 '''scripts''' 子目录里的 '''tigase.sh''' 文件启动服务器. 在根服务器目录输入以下命令:
<source lang="bash">
./scripts/tigase.sh start etc/tigase.conf
</source>
:* 当然如果你有定制的配置文件，那么可以适当修改上一个命令.
:* 在一个 '''Windows''' 平台你可以使用一个 '''bat''' 文件来运行服务器. 在Tigase根目录有一个 '''run.bat''' 文件. 只要在 '''文件浏览器'''双击它或从命令行运行它来启动服务器. 一个服务器日志输出的窗口将弹出来.
http://www.tigase.org/files/image/gui-install/winRunMini.gif
==安装成一个服务==
在 '''Windows''' 下你可以把Tigase安装成一个服务. 要做到这一点，使用在服务器根目录找到的 '''InstallTigaseService.bat''' 批处理文件.
在这个模式下服务将被运行在后台并且将可以从 '''服务''' 管理控制台来控制. 要打开这个工具，右击桌面上 '''我的电脑''' 图标. 选择 '''管理''' 动作. 这将运行 '''计算机管理''' 图形化配置程序. 在左边选择 '''服务''' 条目. 你将看大一个服务列表. 这里你可以找到Tigase服务，如果它已经装好的话.
要卸载Tigase服务，使用Tigase服务器根目录的 '''UninstallTigaseService.bat''' .
==如何检查服务器是否正在运行==
检查服务器是否正在运行是很容易的. 只要使用可用的XMPP客户端之一尝试连接它就可以了.</rev>
</revisions>
</page>
<page pageid="41" ns="0" title="XEP-0004">
<revisions>
<rev xml:space="preserve">[[Category:XMPP扩展]]
[[Category:已翻译]]
'''本文的英文原文来自[http://xmpp.org/extensions/xep-0004.html XEP-0004]'''
'''XEP-0004: 数据表单'''
摘要: 本文定义了一个XMPP扩展协议用于数据表单，可以用于worklows如服务配置以及特定应用的数据描述和报告。这个协议包括表单处理的轻量级语义(如请求,响应,提交和取消),定义了几种常见的字段类型(布尔、单个或多个选择的列表选项、单行或多行的文本,单个或多个JabberID、隐藏字段,等等),为以后的数据类型提供扩展性,可以用在广泛的应用中。该协议并不是要提供完整的表格处理功能（由W3C XForms技术提供），而是提供这种功能的基本子集给XMPP使用。
作者: Ryan Eatmon, Joe Hildebrand, Jeremie Miller, Thomas Muldowney, Peter Saint-Andre
XMPP扩展协议的版权(1999-2008)归XMPP标准化基金会(XSF)所有
版权: © 1999 - 2010 XMPP标准化基金会(XSF). 参见[[XEP-0004#法律通告|法律通告]].
状态: 最终
类型: 标准跟踪
版本: 2.9
最后更新日期: 2007-08-13
注意: 这里定义的协议是XMPP标准化基金会的一个最终标准.对于实现和布署来说可以被认为是一个稳定技术.
==绪论==
几个现有的Jabber/XMPP的协议包含用户和应用程序之间的结构数据交换，为常用的任务，如注册（[http://xmpp.org/extensions/xep-0077.html In-Band Registration][[XEP-0004#附录G:备注|1]]）和搜索（[http://xmpp.org/extensions/xep-0055.html Jabber Search] [[XEP-0004#附录G:备注|2]]）。不幸的是，这些早期的协议是“硬编码”，因此很大的限制了可交换信息的范围。此外，其他协议(如，[http://xmpp.org/extensions/xep-0045.html Multi-User Chat] [[XEP-0004#附录G:备注|3]])可能需要以交换数据为目的，例如配置，但是配置选项可能根据具体实施或部署不同。最后，开发人员可能要以灵活的方式扩展其他协议(如, [http://xmpp.org/extensions/xep-0030.html Service Discovery][[XEP-0004#附录G:备注|4]])，以提供在基本协议没有定义的信息。在所有这些情况下，这将有助于使用一个通用的数据描述格式，可以用于动态表单生成和各种情况下的数据“建模”。
一个例子可能会有帮助。试想一下，当用户创建一个文本会议服务的多用户聊天室，该服务允许用户以各种方式配置房间。虽然大多数实现可能提供了一个较为常见的可配置功能集（讨论记录，房间拥有者的最大数量，等等）。还会有一些分歧：也许一个实现允许把房间日志以各种文件类型（XML，HTML，PDF等格式）和各种时间周期（每小时，每天，每周等）保存。而另一个实现，可能只存在登录的开/关选择一种格式（如，在HTML保存每日日志）。很明显，第一个实现比第二个实现有更多的配置选项。而不像“硬编码”每个选项通过不同的XML元素（如，<room_logging_period/>），一个好的设计应该包含更多灵活的格式。
此处所描述的'jabber:x:data'协议为Jabber/XMPP实体的使用定义了灵活的格式，控制在“名称值”对的简单和[http://www.w3.org/TR/xforms/ XForms 1.0] [[XEP-0004#附录G:备注|5]]（当这个协议被设计时才开始发展的）的复杂之间。在很多方面，'jabber:x:data' 与[http://www.w3.org/TR/xhtml1/ XHTML 1.0][[XEP-0004#附录G:备注|6]]的表单模块类似。但它提供一些Jabber特有的数据类型，允许应用程序请求数据字段，更自然地集成到IQ节的“workflow”语义中。而且它可以作为现有的Jabber/XMPP协议的扩展，而当这个协议被开发出来时，XHTML的表单模块却不能（尤其是当时并没有[http://www.w3.org/TR/2004/WD-xhtml-modularization-20040218/ Modularization of XHTML] [[XEP-0004#附录G:备注|7]]）。
==需求==
本文档涉及下列需求:
# '''数据收集''' -- 该协议应允许表单处理实体（通常是一个服务器，服务，或bot）从表单提交实体（通常是一个由用户控制的客户端）收集数据。应该是通过不同的数据字段来做，每个都可以是不同的数据“类型”，而且允许自由格式的输入或多个选项的选择（就像HTML表单一样）。
# '''数据报告''' -- 该协议应允许表单处理的实体向表单提交的实体报告数据，再通过不同的数据字段。
# '''可移植性''' -- 协议应该尽量只定义普通数据格式和基本的数据类型。提示应该在相关的用户界面提供，但应该仅仅是提示，而不是严格的要求。
# '''简单''' -- 协议在客户端的实施应该简单，并且大多数复杂的工作（如，数据有效性和处理）应由服务器和组件去完成，而不是客户端。
# '''灵活性''' -- 协议应该具有灵活性和可扩展性，而不像“硬编码”。
# '''兼容性''' -- 协议应该为已有的Jabber/XMPP协议定义一个扩展，而且不破坏已有的实现，除非绝对必要。
==协议==
'jabber:x:data' 命名空间的基本语法如下（正式的描述可以在下面的XML节中找到）:
<source lang="xml">
<x xmlns='jabber:x:data'
type='{form-type}'>
<title/>
<instructions/>
<field var='field-name'
type='{field-type}'
label='description'>
<desc/>
<required/>
<value>field-value</value>
<option label='option-label'><value>option-value</value></option>
<option label='option-label'><value>option-value</value></option>
</field>
</x>
</source>
受'jabber:x:data' 命名空间限制的<x/>元素，应该包括直接作为<message/>节第一级子元素或作为<iq/> 节（其中第一级子元素是由一个"wrapper"命名空间限制的）的第二级子节。参见下文列举的限制。
可选项<title/>和<instructions/>元素，允许表单处理实体把表单标记为一个整体并指定自然语言指令，后面跟着表单提交实体。这些元素的XML字符数据不应包含换行符（\n和\r字符），而任何换行符操作（如，在用户界面显示）在这里不是特指的。但<instructions/>元素的多个实体可以被包括在内。
===表单类型===
'jabber:x:data'表单中数据的收集或提供可以位于不同的上下文。例子包括一个需要填写的空表单，填好的表单，一个提交结果，一个搜索结果，或仅仅是用'jabber:x:data'命名空间封装的一组数据。完整的数据上下文由3个条件提供：
# "wrapper"协议（即，以<iq/>节直接子元素为根元素的命名空间和受'jabber:x:data' 命名空间限制的<x/>元素的父元素）。
# 一个包含事务（如，一个IQ "set"或"result"）或会话结构（如，一个消息<thread/>）的表单的位置。
# 表单中<x/>根元素的类型属性
前面2件上下文信息有其他协议提供，而表单类型见下表描述。
:'''表1：表单类型'''
{|border="1" cellspacing="0"
! 类型 !! 描述
|-
|表单 || 表单处理实体请求表单提交实体去完成表单。
|-
|提交 || 表单提交实体提交数据给表单处理实体。提交信息可以包含不是空表单提供的字段，但表单处理实体必须忽略任何无法识别的字段。
|-
|取消 || 表单提交实体取消给表单处理实体提交的数据。
|-
|结果 || 单处理实体返回数据（如查询结果）给表单提交实体，或数据是一个通用的数据集。
|}
为了维护表单类型中获取的数据的上下文，必须遵守以下规则:
:* 对于<iq/>节，受"wrapper" 命名空间限制的根元素，以"form" 或"submit"的一种形式，必须以一种"result"形式的表单返回。受'jabber:x:data'命名空间限制的<x/>元素，必须是"wrapper"命名空间根元素的子元素。根据[http://tools.ietf.org/html/rfc3920 XMPP Core] [[XEP-0004#附录G:备注|8]]所定义， 'id' 属性必须在IQ结果中被复制。对于表单类型为"form" 或 "result",<iq/>节应该是"result"类型。对于表单类型为"submit" 或"cancel"， <iq/>节应该是"set"类型。
:* 对于<message/>节，如果提供的话，<thread/>应该在回复中被复制。受'jabber:x:data'命名空间限制的<x/>元素，必须是<message/>节的子元素。
===字段元素===
一个"form"，"submit"，或 "result"类型的数据表单应该包含至少一个<field/>元素。一个"cancel"类型的表单，不应该包含任何<field/>元素。
<field/>元素可以包含以下任何子元素:
:'''<desc/>'''
:该元素的XML字符数据提供了该字段一个自然语言的描述，为了在用户代理中介绍（如，作为一个"tool-tip"，帮助按钮，或在字段附近的文本标记）。<desc/>元素不应包含换行符（\n和\r字符），因为布局负责用户代理，任何换行的处理（如，在用户界面演示）在这里是未指明的。（注意：提供一个字段的描述，使用<desc/>元素是被推荐的，而不是一个单独的"fixed"类型的<field/>元素。）
:'''<required/>'''
:该元素必须为空，标记所需的字段，为了被表单识别为有效字段。
:'''<value/>'''
:该元素的XML字符数据定义了在"form"类型数据表单中的字段（根据表单处理实体）的默认值，在"submit"类型数据表单中由表单提交实体提供的数据，或在"result"类型数据表单中的数据结果。在"form"类型数据表单中，如果表单处理实体通过<value/>元素提供了一个默认值，表单提交实体就不应该尝试去执行一个不同的默认值。
:'''<option/>'''
:在"list-single"或"list-multi"字段类型中的一个选项。<value/>子元素的XML字符定义了选项的值，而且标签属性为选项定义了一个人们易读的名称。<option/>元素必须且只能包含一个<value/>子元素。如果字段类型不是"list-single"或"list-multi"，就一定不能包含<option/>元素。
如果<field/>元素类型是其他的而不是“fixed”（见下文），它必须拥有一个'var'属性在表单中唯一标识字段（如果是“fixed”，可以拥有一个'var'属性）。<field/>元素可以拥有一个标签属性，为字段定义一个人们易读的名称。对于“form”类型的数据表单，每个<field/>元素应该拥有'type'属性，它定义了字段数据的数据 "type"（如果没有'type'被指定，则默认为"text-single"）。在其他表单类型的上下文中提供的字段，也可以拥有一个'type'属性。对于"submit"类型的数据表单，'type'中包含的属性是可选的，因为表单处理实体被假定知道它处理的表单的数据类型。
如果字段出现在用户页面上（如，问卷中的项或表单结果），在XML中的字段元素的顺序，应该决定出现在用户处的项目的顺序。
===字段类型===
以下字段类型代表Jabber/XMPP实体之间通用的数据类型。这些字段并打算像数据类型一样被广泛定义，如[http://www.w3.org/TR/xmlschema-2/ XML Schema Part 2] [[XEP-0004#附录G:备注|9]], 也没有定义用户界面元素。
:'''表2:字段类型'''
{|border="1" cellspacing="0"
! 类型 !! 描述
|-
|布尔型 || 该字段允许一个实体收集或提供一个在两个选项中只能二选一的选择。默认值为"false"。[[XEP-0004#附录G:备注|10]]
|-
|固定 || 该字段是用于数据的描述（如，人们易读的"section"头信息）而不是数据的收集或提供。<value/>子元素不应该包含换行符（\n和\r字符）；然而一个应用应该生成多个固定的字段，每个都包含<value/>子元素。
|-
|隐藏 || 该字段未展现给表单提交实体，但是和表单一起返回。表单提交实体不能修改隐藏字段的值，但如果这种行为被定义为是“使用协议”时可以这样做。
|-
|多jid || 该字段允许一个实体收集或提供多个Jabber ID。每个提供的JID应该是唯一的（比较确定的，包括Nodeprep的应用、Nameprep和Resourceprep profiles of Stringprep，按XMPP Core中说明的），而重复的JID一定会被忽略。*
|-
|单jid || 该字段允许一个实体收集或提供单个的Jabber ID。
|-
|多选项列表 || 该字段允许一个实体从很多选项中收集或提供一个或多个选项。表单提交实体从表单处理实体提交的选项中选择一个或多个项，而且不能插入新的选项。表单处理实体不能修改从表单处理实体处获取的项目的顺序，因为项目的顺序可能很重要。**
|-
|单选项列表|| 该字段允许一个实体从很多选项中收集或提供一个选项。表单提交实体从表单处理实体提交的选项中选择一个项，而且不能插入新的选项。**
|-
|多文本|| 该字段允许一个实体收集或提供多行的文本。***
|-
|私有文本|| 该字段允许一个实体收集或提供一行或一个词的文本，其应该在界面上遮蔽。（如，星号显示的多个实体）
|-
|单文本|| 该字段允许一个实体收集或提供一行或一个词的文本，其应该在界面上显示。这个字段类型是缺省的而且必须假定，当一个表单提交实体收到一个不知道的字段类型时。
|}
注意：为字段类型"jid-single"或"jid-multi"提供的数据必须包含一个或一个以上的有效Jabber ID，有效性是由XMPP Core（参看后面章节的Data Validation）定义的寻址规则决定的。
注意：在list-multi和list-single中的<option/>元素必须是唯一的，唯一性是由‘label’属性的值和<value/>元素中的XML字符数据决定的。（即，2个都必须是唯一的）
注意：为字段类型"text-multi"提供的数据不应该包含任何换行符（\n和\r字符）。而应用程序应该把数据分为多个字符串（基于平台插入的换行符），然后用不同的<value/>元素中的XML字符数据指定每一个字符串。同样的，以"text-multi"字段类型接收了多个<value/>元素的应用程序，应该把value元素中的XML字符数据合并成一个文本块以提交给用户。每一个字符串为平台适时的通过换行符分开。
===表单结果中的多个项目===
在某些情况下（如，查询请求的结果），传达多个项目是必须的。因此，一个"result"类型的数据表单可能包含2个上面基本语法没有描述的子元素:
#只有一个<reported/>元素，可以理解为一个“表头”描述数据去遵循。
#零个或更多<item/>元素，可以理解为包含符合请求的数据（如果有的话）的"table cells"。
其语法如下：
<source lang="xml">
<x xmlns='jabber:x:data'
type='result'>
<reported>
<field var='field-name' label='description' type='{field-type}'/>
</reported>
<item>
<field var='field-name'>
<value>field-value</value>
</field>
</item>
<item>
<field var='field-name'>
<value>field-value</value>
</field>
</item>
.
.
.
</x>
</source>
这些元素每个都必须包含一个或多个<field/>子元素。<reported/>元素为结果项定义数据格式，通过为每个项目指定所期望的字段。为此，除了'var'属性，<field/>元素还应该有'type'属性'label'属性；而且不能包含<value/>元素。在结果集中，每个<item/>元素定义一个项目，而且必须包含在<reported/>元素（虽然<value/>元素中的XML字符数据可能为空）中指定的字段。
==数据有效性==
数据有效性是表单处理实体（通常是一个服务器，服务，或bot）的责任，而不是表单提交实体（通常是一个由用户控制的客户端）。这有助于满足保持客户端实现简单的要求。如果表单处理实体确定提供的数据是无效的，它应该返回一个“不接受”的错误。选择在XMPP <text/>元素中提供文字说明，或识别问题的特殊应用子元素（参考[http://xmpp.org/extensions/xep-0086.html Error Condition Mappings] [[XEP-0004#附录G:备注|11]]中的映射和格式）。
==例子==
对于下面的例子，我们假设存在一个bot hosting服务在Jabber network上，位于<botster.shakespeare.lit>。这个服务允许注册用户创建和配置新的bots，对已经存在的bots查找和交互，等等。我们假定这些交互的发生使用的Ad-Hoc Commands [12]协议，协议被用作表单的"wrapper"协议，受'jabber:x:data'命名空间限制。下面章节中的例子，体现了前文中描述的数据表单协议的大部分特性。
注意：额外的例子可以通过各种“使用协议”的说明书中找到。如XEP-0045:Multi-User Chat和XEP-0055:Jabber Search。
===配置===
:第一步是为用户在主机上创建一个新的bot。我们假设这是通过发送一个“创建”命令给期望的bot来实现的:
:'''例1.用户请求Bot创建'''
<source lang="xml">
<iq from='romeo@montague.net/home'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='create1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
action='execute'/>
</iq>
</source>
:然后主服务返回一个数据表单个用户:
:'''例2.服务返回一个Bot创建表单'''
<source lang="xml">
<iq from='joogle@botster.shakespeare.lit'
to='romeo@montague.net/home'
type='result'
xml:lang='en'
id='create1'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Bot Configuration</title>
<instructions>Fill out this form to configure your new bot!</instructions>
<field type='hidden'
var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='fixed'><value>Section 1: Bot Info</value></field>
<field type='text-single'
label='The name of your bot'
var='botname'/>
<field type='text-multi'
label='Helpful description of your bot'
var='description'/>
<field type='boolean'
label='Public bot?'
var='public'>
<required/>
</field>
<field type='text-private'
label='Password for special access'
var='password'/>
<field type='fixed'><value>Section 2: Features</value></field>
<field type='list-multi'
label='What features will the bot support?'
var='features'>
<option label='Contests'><value>contests</value></option>
<option label='News'><value>news</value></option>
<option label='Polls'><value>polls</value></option>
<option label='Reminders'><value>reminders</value></option>
<option label='Search'><value>search</value></option>
<value>news</value>
<value>search</value>
</field>
<field type='fixed'><value>Section 3: Subscriber List</value></field>
<field type='list-single'
label='Maximum number of subscribers'
var='maxsubs'>
<value>20</value>
<option label='10'><value>10</value></option>
<option label='20'><value>20</value></option>
<option label='30'><value>30</value></option>
<option label='50'><value>50</value></option>
<option label='100'><value>100</value></option>
<option label='None'><value>none</value></option>
</field>
<field type='fixed'><value>Section 4: Invitations</value></field>
<field type='jid-multi'
label='People to invite'
var='invitelist'>
<desc>Tell all your friends about your new bot!</desc>
</field>
</x>
</command>
</iq>
</source>
:然后用户提交配置表单:
:'''例3.用户提交bot创建表单'''
<source lang="xml">
<iq from='romeo@montague.net/home'
to='joogle@botster.shakespeare.lit'
type='set'
xml:lang='en'
id='create2'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='text-single' var='botname'>
<value>The Jabber Google Bot</value>
</field>
<field type='text-multi' var='description'>
<value>This bot enables you to send requests to</value>
<value>Google and receive the search results right</value>
<value>in your Jabber client. It&apos; really cool!</value>
<value>It even supports Google News!</value>
</field>
<field type='boolean' var='public'>
<value>0</value>
</field>
<field type='text-private' var='password'>
<value>v3r0na</value>
</field>
<field type='list-multi' var='features'>
<value>news</value>
<value>search</value>
</field>
<field type='list-single' var='maxsubs'>
<value>50</value>
</field>
<field type='jid-multi' var='invitelist'>
<value>juliet@capulet.com</value>
<value>benvolio@montague.net</value>
</field>
</x>
</command>
</iq>
</source>
:然后服务返回结果给用户:
:'''例4.服务返回bot创建的结果'''
<source lang="xml">
<iq from='joogle@botster.shakespeare.lit'
to='romeo@montague.net/home'
type='result'
xml:lang='en'
id='create2'>
<command xmlns='http://jabber.org/protocol/commands'
node='create'
sessionid='create:20040408T0128Z'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>jabber:bot</value>
</field>
<field type='text-single' var='botname'>
<value>The Jabber Google Bot</value>
</field>
<field type='boolean' var='public'>
<value>0</value>
</field>
<field type='text-private' var='password'>
<value>v3r0na</value>
</field>
<field type='list-multi' var='features'>
<value>news</value>
<value>search</value>
</field>
<field type='list-single' var='maxsubs'>
<value>50</value>
</field>
<field type='jid-multi' var='invitelist'>
<value>juliet@capulet.com</value>
<value>benvolio@montague.net</value>
</field>
</x>
</command>
</iq>
</source>
===搜索===
既然用户已经创建了这个搜索bot,我们假设他所邀请的好友中的一个，决定通过发送一个搜索请求来试一试:
:'''例5.用户请求搜索表单'''
<source lang="xml">
<iq from='juliet@capulet.com/chamber'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='search1'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
action='execute'/>
</iq>
</source>
:'''例6.服务返回搜索表单'''
<source lang="xml">
<iq from='joogle@botster.shakespeare.lit'
to='juliet@capulet.com/chamber'
type='result'
xml:lang='en'
id='search1'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Joogle Search</title>
<instructions>Fill out this form to search for information!</instructions>
<field type='text-single'
var='search_request'>
<required/>
</field>
</x>
</command>
</iq>
</source>
:'''例7.用户提交搜索表单'''
<source lang="xml">
<iq from='juliet@capulet.com/chamber'
to='joogle@botster.shakespeare.lit'
type='get'
xml:lang='en'
id='search2'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'>
<x xmlns='jabber:x:data' type='submit'>
<field type='text-single' var='search_request'>
<value>verona</value>
</field>
</x>
</command>
</iq>
</source>
:'''例8.服务返回搜索结果'''
<source lang="xml">
<iq from='joogle@botster.shakespeare.lit'
to='juliet@capulet.com/chamber'
type='result'
xml:lang='en'
id='search2'>
<command xmlns='http://jabber.org/protocol/commands'
node='search'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<title>Joogle Search: verona</title>
<reported>
<field var='name'/>
<field var='url'/>
</reported>
<item>
<field var='name'>
<value>Comune di Verona - Benvenuti nel sito ufficiale</value>
</field>
<field var='url'>
<value>http://www.comune.verona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>benvenuto!</value>
</field>
<field var='url'>
<value>http://www.hellasverona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Universita degli Studi di Verona - Home Page</value>
</field>
<field var='url'>
<value>http://www.univr.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Aeroporti del Garda</value>
</field>
<field var='url'>
<value>http://www.aeroportoverona.it/</value>
</field>
</item>
<item>
<field var='name'>
<value>Veronafiere - fiera di Verona</value>
</field>
<field var='url'>
<value>http://www.veronafiere.it/</value>
</field>
</item>
</x>
</command>
</iq>
</source>
==服务发现==
如果一个实体支持包含受'jabber:x:data'命名空间限制的<x/>元素作为<message/>节直接子元素，它必须报告支持包含一个"jabber:x:data"（参看Protocol Namespaces中关于一个或多个永久命名空间的发行）的服务搜索特征，去响应服务搜索信息请求:
:'''例9.服务搜索信息请求'''
<source lang="xml">
<iq type='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
</source>
:'''例10.服务搜索信息响应'''
<source lang="xml">
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='jabber:x:data'/>
...
</query>
</iq>
</source>
如果实体支持数据表单，间接的通过在wrapper命名空间中包含数据表单，它不能为'jabber:x:data'命名空间通知支持，因为在wrapper协助中的支持是隐性的。
==安全性考虑==
没有安全问题与上述的规范和XMPP Core中相关章节的描述有关。
==IANA考虑==
这份文档与[http://www.iana.org/ Internet Assigned Numbers Authority (IANA)] [[XEP-0004#附录G:备注|13]]无关。
==XMPP注册考虑==
===协议命名空间===
[http://xmpp.org/registrar/ XMPP Registrar] [[XEP-0004#附录G:备注|14]]在它注册的协议命名空间中包含'jabber:x:data'命名空间。
===参数值===
XMPP注册员维持着一个与'jabber:x:data'命名空间相关的注册参数值。具体定义在[http://xmpp.org/extensions/xep-0068.html Field Standardization for Data Forms] [[XEP-0004#附录G:备注|15]]。注册的地方是<http://xmpp.org/registrar/formtypes.html>。
==XML 架构==
该架构是描述性的，不是规范的。
<source lang="xml">
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='jabber:x:data'
xmlns='jabber:x:data'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-0004: http://www.xmpp.org/extensions/xep-0004.html
</xs:documentation>
</xs:annotation>
<xs:element name='x'>
<xs:complexType>
<xs:sequence>
<xs:element name='instructions'
minOccurs='0'
maxOccurs='unbounded'
type='xs:string'/>
<xs:element name='title' minOccurs='0' type='xs:string'/>
<xs:element ref='field' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='reported' minOccurs='0' maxOccurs='1'/>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='type' use='required'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='cancel'/>
<xs:enumeration value='form'/>
<xs:enumeration value='result'/>
<xs:enumeration value='submit'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
</xs:complexType>
</xs:element>
<xs:element name='field'>
<xs:complexType>
<xs:sequence>
<xs:element name='desc' minOccurs='0' type='xs:string'/>
<xs:element name='required' minOccurs='0' type='empty'/>
<xs:element ref='value' minOccurs='0' maxOccurs='unbounded'/>
<xs:element ref='option' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='label' type='xs:string' use='optional'/>
<xs:attribute name='type' use='optional'>
<xs:simpleType>
<xs:restriction base='xs:NCName'>
<xs:enumeration value='boolean'/>
<xs:enumeration value='fixed'/>
<xs:enumeration value='hidden'/>
<xs:enumeration value='jid-multi'/>
<xs:enumeration value='jid-single'/>
<xs:enumeration value='list-multi'/>
<xs:enumeration value='list-single'/>
<xs:enumeration value='text-multi'/>
<xs:enumeration value='text-private'/>
<xs:enumeration value='text-single'/>
</xs:restriction>
</xs:simpleType>
</xs:attribute>
<xs:attribute name='var' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='option'>
<xs:complexType>
<xs:sequence>
<xs:element ref='value'/>
</xs:sequence>
<xs:attribute name='label' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='value' type='xs:string'/>
<xs:element name='reported'>
<xs:annotation>
<xs:documentation>
When contained in a "reported" element, the "field" element
SHOULD NOT contain a "value" child.
</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:sequence>
<xs:element ref='field' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:sequence>
<xs:element ref='field' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:simpleType name='empty'>
<xs:restriction base='xs:string'>
<xs:enumeration value=''/>
</xs:restriction>
</xs:simpleType>
</xs:schema>
</source>
==最终状态的修改==
当本规范已经是最终状态时，下面的实体协议已经做了修改：
* 指定的'var'属性是所有字段类型所必须的，除了"fixed", 因为'var'属性是可选的。
* 通过服务搜索指定何时去通知支持。
* 移除引用<presence/>节。
==草稿状态的修改==
当本规范在草稿状态时，下面的实体协议已经做了修改：
* <x/>元素可能直接包含在<message/>和<presence/>节中。
* <x/>元素可能包含一个<title/>子元素，在表单或结果中。
* <x/>元素必须拥有一个‘类型’属性。
* <field/>元素可能是类型='jid-single'。
* 结果可能以<item/>标签的方式返回报告。
* 结果可能包含一个<reported/>元素的结果集。
* <reported/>字段可能拥有一个‘类型’属性，提供如何与数据交互的提示（类型='jid-single'是最有用的）。
==附录==
===附录A:文档信息===
系列：[http://xmpp.org/extensions/ XEP]
序号：0004
发布者：[http://xmpp.org/xsf/ XMPP标准基金会]
状态：[http://www.xmpp.org/extensions/xep-0001.html#states-Final 终结版]
类型：[http://www.xmpp.org/extensions/xep-0001.html#types-Standards%20Track 标准跟踪]
版本：2.9
最后更新：2007-07-13
批准机构：[http://xmpp.org/council/ XMPP理事会]
依赖标准：[[RFC3920|XMPP Core]]
替代标准：无
被替代标准：无
缩略名：x-data
XML架构:<http://www.xmpp.org/schemas/x-data.xsd>
原文控制： [http://svn.xmpp.org:18080/browse/XMPP/trunk/extensions/xep-0004.xml HTML] [http://svn.xmpp.org:18080//changelog/~rss/XMPP/trunk/extensions/xep-0004.xml/rss.xml RSS]
本文的其它格式： [http://xmpp.org/extensions/xep-0004.xml XML] [http://xmpp.org/extensions/xep-0004.pdf PDF]
===附录B:作者信息===
'''Ryan Eatmon'''
Email: [mailto:reatmon@jabber.org reatmon@jabber.org]
JabberID: reatmon@jabber.org
'''Joe Hildebrand'''
Email: [mailto:jhildebr@cisco.com jhildebr@cisco.com]
JabberID: hildjj@jabber.org
'''Jeremie Miller'''
Email: [mailto:jer@jabber.org jer@jabber.org]
JabberID: jer@jabber.org
'''Thomas Muldowney'''
Email: [mailto:temas@jabber.org temas@jabber.org]
JabberID: temas@jabber.org
'''Peter Saint-Andre'''
Email: [mailto:stpeter@jabber.org stpeter@jabber.org]
JabberID: stpeter@jabber.org
URI: https://stpeter.im/
{{Template:XEP附录CDEF}}
===附录G:备注===
#XEP-0077: In-Band Registration <http://xmpp.org/extensions/xep-0077.html>.
#XEP-0055: Jabber Search <http://xmpp.org/extensions/xep-0055.html>.
#XEP-0045: Multi-User Chat <http://xmpp.org/extensions/xep-0045.html>.
#XEP-0030: Service Discovery <http://xmpp.org/extensions/xep-0030.html>.
#XForms 1.0 <http://www.w3.org/TR/xforms>.
#XHTML 1.0 <http://www.w3.org/TR/xhtml1>.
#Modularization of XHTML <http://www.w3.org/TR/2004/WD-xhtml-modularization-20040218/>.
#RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://tools.ietf.org/html/rfc3920>.
#XML Schema Part 2: Datatypes <http://www.w3.org/TR/xmlschema-2/>.
#In accordance with Section 3.2.2.1 of XML Schema Part 2: Datatypes, the allowable lexical representations for the xs:boolean datatype are the strings "0" and "false" for the concept 'false' and the strings "1" and "true" for the concept 'true'; implementations MUST support both styles of lexical representation.
#XEP-0086: Error Condition Mappings <http://xmpp.org/extensions/xep-0086.html>.
#XEP-0050: Ad-Hoc Commands <http://xmpp.org/extensions/xep-0050.html>.
#The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
#The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.
#XEP-0068: Field Data Standardization for Data Forms <http://xmpp.org/extensions/xep-0068.html>.
===附录H:修订历史===
注意:
'''版本 2.9 (2007-08-13)'''
Clarified the definition and handling of the list-multi and list-single field types; specified that hidden field values should not be modified unless such behavior is defined for the using protocol; specified that a submission should include all fields provided in the empty form and may include additional fields, but that additional fields must be ignored if not understood by the form-processing entity.
(psa)
'''版本 2.8 (2007-05-21)'''
Removed mentions of presence stanzas; added section on discovering support; added section on substantive changes in Final state.
(psa)
'''版本 2.7 (2006-01-25)'''
Incorporated errata: (1) clarified rules regarding inclusion of option and value elements depending on field type; (2) clarified handling of default values; (3) added value elements to list-multi field in Example 2; (4) harmonized spelling of form-processing entity and form-submitting entity.
(psa)
Version 2.6 (2004-10-13)
Incorporated errata: (1) corrected syntax of <reported/> element (<field/> element should not contain a <value/> child); (2) corrected Example 8.
(psa)
Version 2.5 (2004-05-07)
Clarified terminology regarding form-processing entities and form-submitting entities; corrected several small errors in the schema.
(psa)
Version 2.4 (2004-05-04)
Per discussion by the authors and Jabber Council, specified that the 'var' attribute is required for all field types except "fixed", for which the 'var' attribute is optional.
(psa)
Version 2.3 (2004-03-31)
Formalization and further editorial revisions.
(psa)
Version 2.2 (2004-01-22)
Editorial revisions.
(psa)
Version 2.1 (2003-02-16)
Added schema.
(psa)
Version 2.0 (2002-12-09)
Per a vote of the Jabber Council, changed status to Final.
(psa)
Version 1.1 (2002-10-15)
Call for Experience changes (see Changes in Draft State section). This version voted to Final on 2002-12-09.
(rwe)
Version 1.0 (2002-04-24)
Per a vote of the Jabber Council, changed status to Draft.
(psa)
Version 0.6 (2002-03-15)
Protocol tweaks based on Standards list discussion.
(rwe)
Version 0.5 (2002-02-06)
Protocol tweaks based on implementation and discussion.
(rwe)
Version 0.4 (2001-11-16)
Major redesign to attempt to clarify the scope of this document and limit what it is trying to solve.
(rwe)
Version 0.3 (2001-07-23)
Protocol update
(rwe)
Version 0.2 (2001-06-29)
Protocol update and DocBook version
(rwe)
Version 0.1 (2001-01-25)
Initial release
(rwe)</rev>
</revisions>
</page>
</pages>
</query>
</api>