XML-RPC规范中文版
本规范说明的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请求的例子：
1. POST /RPC2 HTTP/1.0
2. User-Agent: Frontier/5.1.2 (WinNT)
3. Host: betty.userland.com
4. Content-Type: text/xml
5. Content-length: 181
6.
7.
8. version="1.0"?>
9.
10.
11.
12.
13.
14.
15.
16.
关于请求头
第一行的URI格式不是特定的。可以为空，如果服务器只处理XML-RPC请求甚至可以只是简单的一个斜线。可是，如果服务器除了XML-RPC外还提供其他的HTTP请求，URI可以帮助我们把请求指向特定的XML-RPC服务。
User-Agent和Host项是必须的。
Content-Type的值必须是text/xml.
Content-Length必须指定，而且必须是正确的值。
有效的格式
XML-RPC具有和XML一样的有效格式，并且是一个
例如，methodName可以是一个包含执行request请求的文件的名字，可以是数据表中列的名字，还可以是表示目录和文件结构的路径。
如果远程调用接受参数，
Scalar
Tag |
Type |
Example |
four-byte signed integer |
-12 |
|
0 (false) or 1 (true) |
1 |
|
string |
hello world |
|
double-precision signed floating point number |
-12.214 |
|
date/time |
19980717T14:08:55 |
|
base64-encoded binary |
eW91IGNhbid0IHJlYWQgdGhpcyE= |
如果没有指定类型，默认为字符串。
参数值可以是
每个
如果所示为包含两个值的
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
值可以个
一个
下面是一个有4个值的array：
1.
2.
3.
4.
5.
6.
7.
8.
你可以混合使用上面列出的几种类型。
Response应答样式
下面是一个 XML-RPC请求：
1. HTTP/1.1 200 OK
2. Connection: close
3. Content-Length: 158
4. Content-Type: text/xml
5. Date: Fri, 17 Jul 1998 19:55:08 GMT
6. Server: UserLand Frontier/5.1.2-WinNT
7.
8. version="1.0"?>
9.
10.
11.
12.
13.
14.
15.
Respnse应答格式
除非底层操作出现错，否则总是返回200 OK.
Content-Type是text/xml。必须设置Content-Length，并且必须是正确的值。
应到内容是一个简单的XML，可是是
Fault example
1. HTTP/1.1 200 OK
2. Connection: close
3. Content-Length: 426
4. Content-Type: text/xml
5. Date: Fri, 17 Jul 1998 19:55:02 GMT
6. Server: UserLand Frontier/5.1.2-WinNT
7.
8. version="1.0"?>
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
Strategies/Goals
Firewalls. The goal of this protocol isto lay a compatible foundation across different environments, no new power isprovided beyond the capabilities of the CGI interface. Firewall software canwatch 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 coderto be able to look at a file containing an XML-RPC procedure call, understandwhat it's doing, and be able to modify it and have it work on the first or secondtry.
Easy to implement. We also wanted it tobe an easy to implement protocol that could quickly be adapted to run in otherenvironments or on other operating systems.
Updated 1/21/99 DW
The following questions came up on theUserLand discussion group as XML-RPC was beingimplemented in Python.
The Response Format section says"The body of the response is a single XML structure, a
No you cannot leave it out if theprocedure executed successfully. There are only two options, either a responsecontains a
Is "boolean" a distinct datatype, 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 andone to true, but if you mean true, send a boolean type with the value true, soyour intent can't possibly be misunderstood.
What is the legal syntax (and range) forintegers? How to deal with leading zeros? Is a leading plus sign allowed? Howto 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 numericcharacters. Leading zeros are collapsed. Whitespace is not permitted. Justnumeric characters preceeded by a plus or minus.
What is the legal syntax (and range) forfloating point values (doubles)? How is the exponent represented? How to dealwith whitespace? Can infinity and "not a number" be represented?
There is no representation for infinityor negative infinity or "not a number". At this time, only decimalpoint notation is allowed, a plus or a minus, followed by any number of numericcharacters, followed by a period and any number of numeric characters.Whitespace is not allowed. The range of allowable values isimplementation-dependent, is not specified.
What characters are allowed in strings?Non-printable characters? Null characters? Can a "string" be used tohold an arbitrary chunk of binary data?
Any characters are allowed in a stringexcept < and &, which are encoded as < and &. A stringcan be used to encode binary data.
Does the "struct" element keepthe 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 theorder of the keys. The two structs are equivalent.
Can the
A
There is no global list of fault codes.It is up to the server implementer, or higher-level standards to specify faultcodes.
What timezone should be assumed for thedateTime.iso8601 type? UTC? localtime?
Don't assume a timezone. It should bespecified by the server in its documentation what assumptions it makes abouttimezones.
Additions
Updated 6/30/03 DW
Removed "ASCII" fromdefinition of string.
Changed copyright dates, below, to1999-2003 from 1998-99.
Copyright and disclaimer
? Copyright 1998-2003 UserLand Software.All Rights Reserved.
This document and translations of it maybe copied and furnished to others, and derivative works that comment on orotherwise explain it or assist in its implementation 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 onall such copies and derivative works.
This document may not be modified in anyway, such as by removing the copyright notice or references to UserLand orother organizations. Further, while these copyright restrictions apply to thewritten XML-RPC specification, no claim of ownership is made by UserLand to theprotocol it describes. Any party may, for commercial or non-commercialpurposes, implement this protocol without royalty or license fee to UserLand.The limited permissions granted herein are perpetual and will not be revoked byUserLand or its successors or assigns.
This document and the informationcontained herein is provided on an "AS IS" basis and USERLANDDISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANYWARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS ORANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.