un 15, 1999; by Dave Winer. （翻譯:滴水 最後修改時間:2005-3-15 後續完善）
更新 6/30/03 DW
更新 10/16/99 DW
更新 1/21/99 DW
本規范說明的XML-RPC協議實現UserLand FrontIEr 5.1。
關於非技術性說明，請訪問XML-RPC for NewbIEs。
文檔提供了實現XML-RPC所需要的所有信息。
前言
XML-RPC是一種基於Internet的遠程函數調用協議。
XML-RPC消息都是HTTP-POST請求。請求的主要部分的XML。服務器端執行後的返回結果同樣也是XML格式。
函數調用的參數可以是scalars, numbers, strings, dates等等；也可以是混合型的記錄和結構體。
Request請求樣式
下面是一個XML-RPC請求的例子：
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>
關於請求頭
第一行的URI格式不是特定的。可以為空，如果服務器只處理XML-RPC請求甚至可以只是簡單的一個斜線。可是，如果服務器除了XML-RPC外還提供其他的HTTP請求，URI可以幫助我們把請求指向特定的XML-RPC服務。
User-Agent和Host項是必須的。
Content-Type的值必須是text/XML.
Content-Length必須指定，而且必須是正確的值。
有效的格式
XML-RPC具有和XML一樣的有效格式，並且是一個<methodCall>結構。
<methodCall>必須包含一個值為字符型的<methodName>子元素，用來表明被調用的方法。這個字符必須符合以下規定：大小寫字母、數字0-9、下劃線、點、冒號和斜線。至於怎麼解釋這個字符串將有服務器端來決定。
例如，methodName可以是一個包含執行request請求的文件的名字，可以是數據表中列的名字，還可以是表示目錄和文件結構的路徑。
如果遠程調用接受參數，<methodCall>就必須包含<params>子元素。<params>可以包含任意個<param>元素，每個<param>包含一個<value>子元素。
Scalar <value>s <value>
<value>值被嵌入類型標簽中，支持的類型如下表:
Tag Type Example
<i4> or <int> four-byte signed integer -12
<boolean> 0 (false) or 1 (true) 1
<string> string hello world
<double> double-precision signed floating point number -12.214
<dateTime.iso8601> date/time 19980717T14:08:55
<base64> base64-encoded binary eW91IGNhbid0IHJlYWQgdGhpcyE=
如果沒有指定類型，默認為字符串。
<struct>s
參數值可以是<struct>。
每個<struct>包含若干<member>，每個<member>包含一個<name>和一個<value>.
如果所示為包含兩個值的<struct>
<struct>
<member>
<name>lowerBound</name>
<value><i4>18</i4></value>
</member>
<member>
<name>upperBound</name>
<value><i4>139</i4></value>
</member>
</struct>
<struct>是可以遞歸使用的，任何<value>都裡還可以<struct>或其他任何類型，包括後面將要說明的<array>。
<array>s
值可以個<array>
一個<array>簡單的有一個<data>元素。<data>可以是任何合法類型。
下面是一個有4個值的array：
<array>
<data>
<value><i4>12</i4></value>
<value><string>Egypt</string></value>
<value><boolean>0</boolean></value>
<value><i4>-31</i4></value>
</data>
</array>
<array> elements do not have names.
<array> 元素沒有名字。
你可以混合使用上面列出的幾種類型。
<arrays>可以遞歸使用，其值可以是<array>或其他類型，包括上面說明的<strut>。
Response應答樣式
下面是一個 XML-RPC請求：
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>
Respnse應答格式
除非底層操作出現錯，否則總是返回200 OK.
Content-Type是text/XML。必須設置Content-Length，並且必須是正確的值。
應到內容是一個簡單的XML，可是是<methodResponse>包含一個<params>,<params>包含一個<param>,<param>包含一個<value>。
<methodResponse>可能含有一個<fault>標簽。<fault>的值為<struct>類型,<struct>有兩個元素，值為<int>的<faultCode>和值為<string>的<faultString>。
<methodResponse>不能既有<fault>又有<params>。
Fault example
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>
StrategIEs/Goals
Firewalls. The goal of this protocol is to lay a compatible foundation across different environments, no new power is provided beyond the capabilitIEs of the CGI interface. Firewall software can watch for POSTs whose Content-Type is text/XML.
Discoverability. We wanted a clean, extensible format that@#s very simple. It should be possible for an Html coder to be able to look at a file containing an XML-RPC procedure call, understand what it@#s doing, and be able to modify it and have it work on the first or second try.
Easy to implement. We also wanted it to be an easy to implement protocol that could quickly be adapted to run in other environments or on other Operating systems.
Updated 1/21/99 DW
The following questions came up on the UserLand discussion group as XML-RPC was being implemented in Python.
The Response Format section says "The body of the response is a single XML structure, a <methodResponse>, which can contain a single <params>..." This is confusing. Can we leave out the <params>?
No you cannot leave it out if the procedure executed successfully. There are only two options, either a response contains a <params> structure or it contains a <fault> structure. That@#s why we used the Word "can" in that sentence.
Is "boolean" a distinct data type, or can boolean values be interchanged with integers (e.g. zero=false, non-zero=true)?
Yes, boolean is a distinct data type. Some languages/environments allow for an easy coercion from zero to false and one to true, but if you mean true, send a boolean type with the value true, so your intent can@#t possibly be misunderstood.
What is the legal syntax (and range) for integers? How to deal with leading zeros? Is a leading plus sign allowed? How to deal with whitespace?
An integer is a 32-bit signed number. You can include a plus or minus at the beginning of a string of numeric characters. Leading zeros are collapsed. Whitespace is not permitted. Just numeric characters preceeded by a plus or minus.
What is the legal syntax (and range) for floating point values (doubles)? How is the exponent represented? How to deal with whitespace? Can infinity and "not a number" be represented?
There is no representation for infinity or negative infinity or "not a number". At this time, only decimal point notation is allowed, a plus or a minus, followed by any number of numeric characters, followed by a period and any number of numeric characters. Whitespace is not allowed. The range of allowable values is implementation-dependent, is not specifIEd.
What characters are allowed in strings? Non-printable characters? Null characters? Can a "string" be used to hold an arbitrary chunk of binary data?
Any characters are allowed in a string except < and &, which are encoded as < and &. A string can be used to encode binary data.
Does the "struct" element keep the order of keys. Or in other Words, is the struct "foo=1, bar=2" equivalent to "bar=2, foo=1" or not?
The struct element does not preserve the order of the keys. The two structs are equivalent.
Can the <fault> struct contain other members than <faultCode> and <faultString>? Is there a global list of faultCodes? (so they can be mapped to distinct exceptions for languages like Python and Java)?
A <fault> struct may not contain members other than those specified. This is true for all other structures. We believe the specification is flexible enough so that all reasonable data-transfer needs can be accomodated within the specified structures. If you belIEve strongly that this is not true, please post a message on the discussion group.
There is no global list of fault codes. It is up to the server implementer, or higher-level standards to specify fault codes.
What timezone should be assumed for the dateTime.iso8601 type? UTC? localtime?
Don@#t assume a timezone. It should be specifIEd by the server in its documentation what assumptions it makes about timezones.
Additions
<base64> type. 1/21/99 DW.
Updated 6/30/03 DW
Removed "ASCII" from definition of string.
Changed copyright dates, below, to 1999-2003 from 1998-99.
Copyright and disclaimer
? Copyright 1998-2003 UserLand Software. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its im plementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and these paragraphs are included on all such copIEs and derivative works.
This document may not be modifIEd in any way, such as by removing the copyright notice or references to UserLand or other organizations. Further, while these copyright restrictions apply to the written XML-RPC specification, no claim of ownership is made by UserLand to the protocol it describes. Any party may, for commercial or non-commercial purposes, implement this protocol without royalty or license fee to UserLand. The limited permissions granted herein are perpetual and will not be revoked by UserLand or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and USERLAND DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.