阿西河

所有教程

公众号
🌙
阿西河前端的公众号

我的收藏

    最近访问  (文章)

      教程列表

      抓包专区
      测试专区

      插件 jQuery.xmlrpc 中文API文档

      插件 jQuery.xmlrpc 中文API文档

      源码 & 下载

      插件特点

      这是一个位于jQuery之上的小型库,用于与XML-RPC服务进行通信 - 而不用担心XML-RPC的可怕臃肿。使用此库,您可以将JSON参数传递给库,并以JSON格式接收响应。为您处理编码JSON文档,智能地映射两种语言之间的类型。

      基本用法

      只需在页面中包含jQuery库和此库:

      <script src="jquery-1.8.1.js"></script>
      <script src="jquery.xmlrpc.js"></script>
      

      这是建立在jQuery 1.8.1之上的。它可能适用于旧版本,并可能继续使用新版本。

      该 jQuery.xmlrpc 功能是该库的主要工作原理。

      这样:

      $.xmlrpc({
      	url: '/RPC2',
      	methodName: 'foo',
      	params: ['bar', 1, 4.6, true, [1, 2, 3], {name: 'value'}],
      	success: function(response, status, jqXHR) { /* ... */ },
      	error: function(jqXHR, status, error) { /* ... */ }
      });
      

      它需要所有相同的参数jQuery.ajax,因此请参考更多文档。添加的两个新密钥是:

      methodName

      这是放在 <methodName> XML-RPC元素中的方法。它应该是一个字符串。与之通信的XML-RPC服务将确定您可以调用的有效方法名称。

      params

      要发送的参数数组。如果您不想发送任何参数,请指定一个空数组,或者根本不提供此键。

      有关更多信息,请参阅有关编码和解码XML-RPC文档的文档部分。

      获取数据

      当XML-RPC调用返回时,<params>元素的内容被解析为JSON并success作为第一个参数提供给AJAX调用的回调,就像JSON请求一样。

      错误处理

      如果在传输过程中出现任何HTTP错误,将使用正常的jQuery AJAX错误处理。如果XML-RPC服务成功回复,但回复了<fault>响应,$.xmlrpc.XmlRpcFault则抛出一个。error与其他错误一样,此错误将作为第三个参数发送到AJAX调用的回调。

      类型

      JSON和XML-RPC是两种不相关的标记语言,因此在类型之间进行转换需要对这两种语言有一点了解。幸运的是,大多数类型都有两种语言之间的直接映射。

      编码和解码XML-RPC文档

      使用下表查看XML-RPC类型如何映射到JavaScript类型:

      XML-RPCJavaScript
      < nil>null
      < array>Array
      < struct>Object
      < string>String
      < boolean>Boolean
      < int>Number
      < i4>Number
      < i8>Number
      < i16>Number
      < double>Number
      < dateTime.iso8601>Date
      < base64>ArrayBuffer

      注意:JavaScript没有用于整数和浮点数的单独类型,它只有Number。因此,无法判断4是否真的意味着 <int>4</int><double>4</double>。如果这对您来说是一个问题,请继续阅读。

      强制类型

      有时,从JSON到XML-RPC的自动类型猜测可能对您不起作用。此问题的最常见来源是编码数字。库有时可以将Number编码为<int>而不是<float>,因为没有可靠的方法来确定实际需要的内容。

      要强制类型,请在对$ .xmlrpc.force的调用中包装该值。这些类型以XML-RPC等价物命名,如上表所述。

      要强制将浮点JavaScript 编号 编码为<i8> 并作为参数发送,请使用以下命令:

      var forcedValue = $.xmlrpc.force('i8', 4.5)
      
      $.xmlrpc({
          url: '/RPC2',
          methodName: 'foo',
          params: [forcedValue]
      });
      

      添加和扩展类型

      您可以通过将成员添加到$ .xmlrpc.types并与$ .xmlrpc.makeType函数结合,将您自己的类型添加到XML-RPC 。有关更多信息,请参阅 $ .xmlrpc.makeType()

      API

      如果您需要扩展此库,则会公开以下API。您不必在日常使用库时使用此API。

      $.xmlrpc()

      调用远程过程。这是jQuery.ajax() 的一个小包装器, 因此请参阅相关文档以获取更多信息。它需要以下参数:

      网址

      要调用的服务的URL。可选的。如果未指定,则从选项dict中提取

      选项

      请求的选项。大多数选项直接传递给 jQuery.ajax(),但两个键除外。

      该方法名键必须提供,并且必须是一个字符串。它用作调用的 < methodName>

      该PARAMS键可以用来发送参数。这必须是一个值数组。保留此空白,或提供并清空数组以不发送任何参数。

      有关如何将JavaScript类型转换为XML-RPC类型的更多信息,请参阅类型

      获取数据

      当XML-RPC调用返回时,< params>元素的内容被解析为JSON并作为第一个参数提供给AJAX调用的成功回调,就像JSON请求一样。

      处理错误

      如果在传输过程中出现任何HTTP错误,将使用正常的jQuery AJAX错误处理。如果XML-RPC服务成功回复,但回复<fault>响应,则抛出 $.xmlrpc.XmlRpcFault

      与其他错误一样,此错误将作为第三个参数发送到AJAX调用的错误回调。

      $.xmlrpc.document()

      根据方法名称和一组参数创建XML-RPC文档。它需要以下参数:

      方法名

      这是放在XML-RPC 的<methodName>元素中的方法。它应该是一个字符串。与之通信的XML-RPC服务将确定您可以调用的有效方法名称。

      PARAMS

      要发送的参数数组。如果您不想发送任何参数,请指定一个空数组。

      JavaScript调用:

      $.xmlrpc.document('foo', ['bar, true, [1, 2, 3]]);
      

      生成以下XML文档(没有空格):

      <methodCall>
          <methodName>foo</methodName>
          <params>
              <param>
                  <value><string>bar</string></value>
              </param>
              <param>
                  <value><boolean>1</boolean></value>
              </param>
              <param>
                  <value><array><data>
                      <value><int>1</int></value>
                      <value><int>2</int></value>
                      <value><int>3</int></value>
                  </data></array></value>
              </param>
          </params>
      </methodCall>
      

      $.xmlrpc.toXmlRpc()

      获取值,并将其编码为XML-RPC节点。因为XML节点必须由XML文档自己的createElement创建,所以在调用$ .xmlrpc.document之外不能使用它。它需要以下参数:

      要编码的值

      $XML

      帮助函数,用于在文档上创建XML节点。然后返回,由jQuery包装。

      $.xmlrpc.parseDocument()

      解析XML-RPC文档,并返回其内容。如果文档表示XML-RPC错误,则抛出 $.xmlrpc.XmlRpcFault。它需要以下参数:

      示例

      以下XML文档:

      <?xml version="1.0"?>
      <methodResponse>
          <params>
              <param>
                  <value><string>foo</string></value>
              </param>
              <param>
                  <value><int>3</int></value>
              </param>
              <param>
                  <value><struct>
                      <member>
                          <name>foo</name>
                          <value><i4>1</i4></value>
                      </member>
                      <member>
                          <name>bar</name>
                          <value><i4>2</i4></value>
                      </member>
                  </struct></value>
              </param>
          </params>
      </methodResponse>
      

      解析者:

      $.xmlrpc.parseDocument(doc);
      

      会导致JSON文档:

      [
          'foo',
          3,
          {
              foo: 1,
              bar: 2
          }
      ]
      

      $ .xmlrpc.parseNode()

      获取单个XML元素,并返回其等效的JSON。它需要一个论点:

      节点

      要解码的XML节点。它应该是使用$ .xmlrpc.makeType()注册的类型之一 。如果找不到类型,则抛出错误。

      示例

      XML元素:

      <struct>
          <member>
              <name>foo</name>
              <value><i4>1</i4></value>
          </member>
          <member>
              <name>bar</name>
              <value><i4>2</i4></value>
          </member>
      </struct>
      

      将通过调用解析:

      $.xmlrpc.parseNode(node)
      

      产生JSON:

      {
          foo: 1,
          bar: 2
      }
      

      $ .xmlrpc.makeType()

      将XML-RPC类型添加到库中。然后,库将在返回时知道如何解码此类型的元素。它需要以下参数:

      标签

      此表示的XML-RPC元素的名称。示例:‘boolean’

      简单

      如果元素是简单类型。除之外的所有标准元素都是简单类型。简化类型的解码函数的编码被简化,因为它们仅处理元素的文本内容。

      编码

      获取JavaScript值,并将其编码为XML-RPC元素。接收要编码的值,以及用于在正确文档上创建XML节点的辅助函数 - 此帮助必须用于为子元素创建XML节点。

      简单类型只需要返回节点的文本,创建节点就是为您处理的。

      解码

      获取XML元素,并将其解码为JavaScript表示形式。

      简单类型接收节点的文本而不是节点本身。

      示例

      一个简单的布尔节点:

      // Boolean type. True == '1', False == '0'
      $.xmlrpc.makeType('boolean', true, function(value) {
          return value ? '1' : '0';
      }, function(text) {
          return text == '1';
      });
      

      一个复杂的自定义元素:

      /**
       * Convert
       *     {foo: 1, bar: "hello"}
       * into
       *     <custom><foo>1</foo><bar><string>hello</string></bar></custom>
       * Note the call to `$.xmlrpc.toXmlRpc`` to recursively encode the `bar` element.
       */
      $.xmlrpc.makeType('custom', false, function(value, $xml) {
          return $xml('custom').append([
              $xml('foo').text($.xmlrpc.toXmlRpc(value.foo, $xml)),
              $xml('bar').text($.xmlrpc.toXmlRpc(value.foo, $xml))
          ]);
      }, function(node) {
          return {
              foo: parseInt($(node).find('> foo').text()),
              bar: fromXmlRpc($(node).find('> bar > *').get(0)),
          }
      });
      

      $.xmlrpc.force()

      强制在XML-RPC中将值编码为特定类型。它需要以下参数:

      类型

      强制值的类型。[types documentation] [types]中指定的XML-RPC类型之一,或者使用$ .xmlrpc.makeType添加的自定义类型 之一。

      将被编码为类型的任何值。

      示例

      强制将浮点数编码为i8,作为参数发送:

      var forcedValue = $.xmlrpc.force('i8', 4.5)
      $.xmlrpc({
          url: '/RPC2',
          methodName: 'foo',
          params: [forcedValue]
      });
      
      目录
      目录