XML-RPC Introduction

發表於 |

在談 RPC 之前，先來說說什麼是 Procedure。

Procedure 就是一段特定目的程式碼，能傳入參數，執行完後能傳回結果，可以是大型應用的一段程式碼，或是某隻小程式的 main function。

Procedure 也可以被叫做 subroutine、function 、method……，在某些語言（Pascal, Fortan, Ada….）裡對 Function 跟 Procedure 有比較明確的定義，像 Function 必須有明確的回傳，Procedure 則沒有。

RPC（Remote Procedure Call）就是一個 Procedure Call 延伸的想法，在兩個 Procedure 之間建立一個連線，可以彼此溝通，彼此之間可以是不同的 Application 、不同的機器，提供一種跨平台的溝通方式。

既然兩邊要溝通，那就必須制定一個讓雙方都了解的表達方式。就像如果兩個人要溝通如果一個說中文，一個說英文這樣講起來就牛頭不對馬嘴無法溝通。

XML-RPC 就是利用 XML 來做為訊息表達的方式，並使用 HTTP 協定來作為傳送機制的 RPC 協定。

Request example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
<?xml version="1.0"?>
<methodCall>
   <methodName>examples.getStateName</methodName>
   <params>
      <param>
         <value><i4>41</i4></value>
     </param>
  </params>
</methodCall>

Request 的訊息由單一個 <methodCall> 標籤所包覆，其中 <methodName> 必需的而 <params> 是可選的。

在 <mothodName> 裡的值必須是下列允許的字串：大小寫A-Z、0 - 9、底線（_）、點（.）、冒號（:）及斜線（/）。

在 <params> 裡可以包含多組 <param> 且每一組 <param> 需包含一個 <value> 。

以下是 <value> 所能包含的資料型態

Tag Type Example
<i4> or <int> 4 bytes (32 bits) 有號整數 8, -12
<boolean> 布林值 0 (false) or 1 (true) 0, 1
<string> 字串（若遇到 < 或 & 必須要以 ＆lt; 跟 ＆amp;） Hi
<double> 8 bytes（64 bits）有號浮點數 -12.214
<dateTime.iso8601> 日期及時間 19980717T14:08:55
<base64> base64 編碼 eW91IGNhbid0IHJlYWQgdGhpcyE=

若沒有指定型態的標籤，會以 String 型態去做處理。

除了上面幾種資料型態，還有兩個特別的型態 <struct> 及 <array>

<struct> 標籤可以用來結構化傳入的資料，像是用來表示物件資料

1
2
3
4
5
6
7
8
9
10
<struct>
   <member>
      <name>lowerBound</name>
      <value><i4>18</i4></value>
   </member>
   <member>
      <name>upperBound</name>
      <value><i4>139</i4></value>
    </member>
</struct>

<array> 陣列標籤必須包含單一個 <data> 標籤，在 <value> 標籤裡的值也可以包含一個 <array> 或是 <struct>，做巢狀的表示。

1
2
3
4
5
6
7
8
<array>
   <data>
      <value><i4>12</i4></value>
      <value><string>Egypt</string></value>
      <value><boolean>0</boolean></value>
      <value><i4>-31</i4></value>
   </data>
 </array>

Response example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200 OK
Connection: close
Content-Length: 158
Content-Type: text/xml
Date: Fri, 17 Jul 1998 19:55:08 GMT
Server: UserLand Frontier/5.1.2-WinNT
<?xml version="1.0"?>
<methodResponse>
   <params>
      <param>
         <value><string>South Dakota</string></value>
     </param>
  </params>
</methodResponse>

Response 的訊息由單一個 <methodResponse> 標籤結構所表示，裡面需包含 <params> 標籤或 <falut> 標籤（表示錯誤）

以下是 MethodResponse 回傳錯誤的範例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
HTTP/1.1 200 OK
Connection: close
Content-Length: 426
Content-Type: text/xml
Date: Fri, 17 Jul 1998 19:55:02 GMT
Server: UserLand Frontier/5.1.2-WinNT
<?xml version="1.0"?>
<methodResponse>
   <fault>
      <value>
         <struct>
            <member>
               <name>faultCode</name>
               <value><int>4</int></value>
            </member>
            <member>
               <name>faultString</name>
               <value><string>Too many parameters.</string></value>
            </member>
         </struct>
      </value>
   </fault>
</methodResponse>

在 <fault> 標籤裡的 <value> 值是一個 <struct> 結構標籤，存在兩個 member：faultCode 跟 faultString ，用來表示錯誤代碼跟錯誤訊息。

References

XML-RPC Specification