PHP自带的核心库支持SOAP以及XML-RPC,但是官方文档却写的十分简略,看了跟没看一样,最后找到Epinions.com的实现及文档,才明白每个接口的原型说明。完整的函数原型说明如下:
these functions are used to convert between php native data types and the xml vocabulary in either direction. these, plus a network request function, are all that are required for a simple xmlrpc client
string xmlrpc_encode_request(string method, mixed params [, array output_options])
generate xml for a method call or responsereturns: generated xml string or false on failure
args:
method: method to call on remote server. if null, generated xml is a response
params: argument data of any type. should match remote method signature
output_options: see output_options
string xmlrpc_decode_request(string method, string& method [, encoding])
decode xml into native php types. also returns methodnamereturns: a single value of any type. usually an array.
args:
xml: raw xml to decode
method: variable to store method name in. (pass by ref). unchanged if not a method call
encoding: input encoding to translate to. defaults to iso-8859-1
string xmlrpc_encode(mixed value)
generate xml for a value, sansreturns: generated xml string or false on failure
args:
value: php value to be serialized
mixed xmlrpc_decode(string xml [,string encoding])
decode xml into native php typesreturns: a single value of any type. usually an array.
args:
xml: raw xml to decode
encoding: input encoding to translate to. defaults to iso-8859-1
these functions are provided to enable easy creation of an xmlrpc server. basically, a server, once created, will register user methods and then process requests. the requests are in the form of raw xml data that can be passed directly to xmlrpc_server_call_method, which will call a previously registered user method and return the result.
handle xmlrpc_server_create()
create an xml serverreturns: a handle to a newly created server or false on failure
void xmlrpc_server_destroy(handle server)
destroy server resources. it is good practice to call this function however if you do not, the server will be destroyed at the end of the request regardless.returns: void
args:
handle: handle to a server created with xmlrpc_server_create
int xmlrpc_server_register_method(handle server, string method_name, string function)
register a php function to handle method matching method_namereturns: true, or false on failure
args:
handle: handle to a server created with xmlrpc_server_create
method_name: public (xmlrpc) method name
function: name of application (php) function that will implement the method
mixed xmlrpc_server_call_method(handle server, string xml, mixed user_data [, array output_options])
parse xml request and call methodreturns: result of method call. this will either be a php value, or an xml encoded representation of that value, depending on output_options
args:
handle: handle to a server created with xmlrpc_server_create
xml: raw xml request string
user_data: any data the application needs to pass to the method handler function
output_options: see output_options
int xmlrpc_server_set_method_description(handle server, string method, struct description)
set method description for a methodreturns: 1 if success. 0 otherwise
args:
handle: handle to a server created with xmlrpc_server_create
method: name of method being described
description: a method description, as defined by the system.describeMethods spec
it is important to have good documentation for any public API. the introspection functions enable server developers to generate highly descriptive documentation describing methods and their parameter types using a simple XML vocabulary. further, a callback mechanism is provided because documentation generation can be expensive and thus should only be done on demand, particularly in php's interpreted per request environment.
int xmlrpc_server_register_introspection_callback(handle server, string function)
register a php function to generate documentation when it is requested (lazy evaluation). this is more efficient and should be used in preference to the parse/add methods. the user function simply needs to return xml conforming to the introspection spec, and it will automatically be parsed, registered with the server and returned to the client as appropriatereturns: true, or false on failure
args:
handle: handle to a server created with xmlrpc_server_create
function: name of application (php) function that will implement the method. function signature is:
string func(mixed user_data)
array xmlrpc_parse_method_descriptions(string xml)
parse xml into a method description. See the introspection spec for a description of the xml vocabularyreturns: an array suitable for use with xmlrpc_server_add_introspection_data, or null if failure
args:
xml: xml conforming to introspection spec
bool xmlrpc_server_add_introspection_data(handle server, array desc)
adds introspection data to a server for future usereturns: bool. true if successful
args:
handle: handle to a server created with xmlrpc_server_create
desc: a description created with xmlrpc_parse_method_description
these functions are provided because of the unique implementation of the base64 and datetime data types. neither of these types are native to php, so it is necessary to store and retrieve that meta information somehow. This second implementation achievesthis by converting the value to a php object and storing type information in a member
bool xmlrpc_set_type(string &value, string type)
set xmlrpc type, base64 or datetime, for a php string value. if successful, the string will be converted to an object. the object will have a member 'xmlrpc_type', which contains the new type, and a member 'scalar', which contains the actual valuereturns: true, or false on failure
args:
value: a reference to a string. typically containing either base64 or an iso 8601 conforming date.
type: a string. one of the allowed types
string xmlrpc_get_type(mixed value)
get xmlrpc type for a php value. especially useful for base64 and datetime strings which do not have php type equivalents.returns: a string indicating the value's xmlrpc type. see types
args:
value: value to determine type of
type: defines
values:none: not a value
empty: value created but not set, or null.
base64: base64 encoded string, usually for sending binary data
boolean: true or false
datetime: iso 8601 encoded date/time string
double: floating point value
int: integer
string: a string
array: an array
struct: a struct
type: hashed array值得一提的是如何在XML-RPC中使用中文,在xmlrpc_encode_request等编解码函数中,都有一个默认参数,即上面提到的output_option,其为一个关联数组,数组中encoding的值对应了采用了字符集编码方式,因此如何需要使用中文,则最好采用utf-8的编码方式,并且escaping需要去掉默认的"non-ascii"和"non-print"。
sets xml generation options. any values not set will use defaults
values:output_type: return data as either php native data types or xml encoded. if php is used, then the other values are ignored. default = xml
verbosity: determine compactness of generated xml. options are no_white_space, newlines_only, and pretty. default = pretty
escaping: determine how/whether to escape certain characters. 1 or more values are allowed. If multiple, they need to be specified as a sub-array. options are: cdata, non-ascii, non-print, and markup.default = non-ascii, non-print, markup
version: version of xml vocabulary to use. currently, three are supported: xmlrpc, soap 1.1, and simple. The keyword auto is also recognized to mean respond in whichever version the request came in. default = auto (when applicable), xmlrpc
encoding: the encoding that the data is in. Since PHP defaults to iso-8859-1 you will usually want to use that. Change it if you know what you are doing. default= iso-8859-1
example usage
$output_options = array( "output_type" => "xml", "verbosity" => "pretty", "escaping" => array("markup", "non-ascii", "non-print"), "version" => "xmlrpc", "encoding" => "utf-8" );<br /><span id="_xhe_temp" width="0" height="0"><br /></span>