LaminasXmlRpcClient
class. Its major features include:LaminasXmlRpcClient
receives the URL of the remote XML-RPCserver endpoint as its first parameter. The new instance returned may be used tocall any number of remote methods at that endpoint.call()
instance method. The code sample below uses a demonstration XML-RPCserver from Advogato. You can use it for testing orexploring the LaminasXmlRpc
components.call()
method receives the name of the remotemethod to call. If the remote method requires any parameters, these can be sentby supplying a second, optional parameter to call()
with an array
of valuesto pass to the remote method:[]
passed to it. The array of parameters forthe remote method can contain native PHP types, LaminasXmlRpcValue
objects, ora mix of each.call()
method will automatically convert the XML-RPC response and returnits equivalent PHP native type. A LaminasXmlRpcResponse
object for the returnvalue will also be available by calling the getLastResponse()
method after thecall.call()
method of LaminasXmlRpcClient
as an array in the second parameter. Eachparameter may be given as either a native PHP type which will be automaticallyconverted, or as an object representing a specific XML-RPC type (one of theLaminasXmlRpcValue
objects).call()
as native PHP variables, meaning as a string
, integer
,float
, boolean
, array
, or an object
. In this case, each PHP native type will beauto-detected and converted into one of the XML-RPC types according to this table:PHP Native Type | XML-RPC Type |
---|---|
integer | int |
LaminasMathBigIntegerBigInteger | i8 |
double | double |
boolean | boolean |
string | string |
null | nil |
array | array |
associative array | struct |
object | array |
DateTime | dateTime.iso8601 |
DateTime | dateTime.iso8601 |
LaminasXmlRpcClient
detects suchconditions and makes a request to the server's system.methodSignature
methodto determine the appropriate XML-RPC type to cast to.system.methodSignature
will log failed requests, andLaminasXmlRpcClient
will resort to casting the value to an XML-RPC arraytype. Additionally, this means that any call with array arguments will resultin an additional call to the remote server.setSkipSystemLookup()
method prior to making your XML-RPC call:LaminasXmlRpcValue
instances to specify anexact XML-RPC type. The primary reasons for doing this are:base64
or dateTime.iso8601
type (which doesn't exists as a PHP native type)LaminasXmlRpcValue
object: instantiate one of theLaminasXmlRpcValue
subclasses directly, or use the static factory methodLaminasXmlRpcAbstractValue::getXmlRpcValue()
.XML-RPC Type | LaminasXmlRpcAbstractValue Constant | LaminasXmlRpcValue Object |
---|---|---|
int | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_INTEGER | LaminasXmlRpcValueInteger |
i4 | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_I4 | LaminasXmlRpcValueInteger |
i8 | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_I8 | LaminasXmlRpcValueBigInteger or LaminasXmlRpcValueInteger if machine is 64-bit |
ex:i8 | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_APACHEI8 | LaminasXmlRpcValueBigInteger or LaminasXmlRpcValueInteger if machine is 64-bit |
double | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_DOUBLE | LaminasXmlRpcValueDouble |
boolean | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_BOOLEAN | LaminasXmlRpcValueBoolean |
string | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_STRING | LaminasXmlRpcValueText |
nil | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_NIL | LaminasXmlRpcValueNil |
ex:nil | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_APACHENIL | LaminasXmlRpcValueNil |
base64 | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_BASE64 | LaminasXmlRpcValueBase64 |
dateTime.iso8601 | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_DATETIME | LaminasXmlRpcValueDateTime |
array | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_ARRAY | LaminasXmlRpcValueArray |
struct | LaminasXmlRpcAbstractValue::XMLRPC_TYPE_STRUCT | LaminasXmlRpcValueStruct |
LaminasXmlRpcValue
object, its value is set by a PHPtype. The PHP type will be converted to the specified type using PHP casting.For example, if a string is given as a value to theLaminasXmlRpcValueInteger
object, it will be converted using (int) $value
.getProxy()
instance method ofLaminasXmlRpcClient
. This will return an instance of LaminasXmlRpcClientServerProxy
.Any method call on the server proxy object will be forwarded to the remote, andparameters may be passed like any other PHP method.getProxy()
method receives an optional argument specifying which namespace of the remoteserver to proxy. If it does not receive a namespace, the default namespace will be proxied. In thenext example, the 'test' namespace will be proxied:test.foo.bar()
, it could be called as $test->foo->bar()
.LaminasXmlRpcClient
recognizes each and provides the abilityto detect and trap them independently.LaminasXmlRpcClientExceptionHttpException
will be thrown.LaminasXmlRpcClientExceptionHttpException
will be thrown whenever an HTTP error occurs.LaminasXmlRpcClient
is used.call()
method or the server proxy object is used, an XML-RPC faultwill result in a LaminasXmlRpcClientExceptionFaultException
being thrown. Thecode and message of the exception will map directly to their respective valuesin the original XML-RPC fault response.call()
method is used to make the request, theLaminasXmlRpcClientExceptionFaultException
will be thrown on fault. ALaminasXmlRpcResponse
object containing the fault will also be available bycalling getLastResponse()
.doRequest()
method is used to make the request, it will not throw theexception. Instead, it will return a LaminasXmlRpcResponse
object that, onerror, contains the fault. This can be checked with isFault()
instance methodof LaminasXmlRpcResponse
.system.
namespace. LaminasXmlRpcClient
provides special support forservers with these capabilities.LaminasXmlRpcClientServerIntrospection
instance may be retrieved by callingthe getIntrospector()
method of LaminasXmlRpcClient
. It can then be used toperform introspection operations on the server.getSignatureForEachMethod
: Returns the signature for each method on the server.getSignatureForEachMethodByMulticall($methods=null)
: Attempt to get the method signatures in one request via system.multicall
. Optionally pass an array of method names.getSignatureForEachMethodByLooping($methods=null)
: Get the method signatures for every method by successively calling system.methodSignature
. Optionally pass an array of method namesgetMethodSignature($method)
: Get the method's signature for $method
.listMethods
: List all methods on the server.call()
instance method of LaminasXmlRpcClient
builds arequest object (LaminasXmlRpcRequest
) and sends it to another method,doRequest()
, that returns a response object (LaminasXmlRpcResponse
).doRequest()
method is also available for use directly.call()
method, doRequest()
method, or server proxy — thelast request object and its resultant response object will always be availablethrough the methods getLastRequest()
and getLastResponse()
respectively.LaminasHttpClient
will be created with its defaultoptions and used by LaminasXmlRpcClient
automatically.getHttpClient()
method.For most cases, the default HTTP client will be sufficient. However, thesetHttpClient()
method allows for a different HTTP client instance to beinjected.setHttpClient()
is particularly useful for unit testing. When combinedwith LaminasHttpClientAdapterTest
, remote services can be mocked out fortesting. See the unit tests for LaminasXmlRpcClient
for examples of how to dothis.xmlrpc.client
module is not secure against maliciouslyconstructed data. If you need to parse untrusted or unauthenticated data seeXML vulnerabilities.xmlrpc.client
now performs all the necessarycertificate and hostname checks by default.xmlrpc.client.
ServerProxy
(uri, transport=None, encoding=None, verbose=False, allow_none=False, use_datetime=False, use_builtin_types=False, *, headers=(), context=None)¶ServerProxy
instance is an object that manages communication with aremote XML-RPC server. The required first argument is a URI (Uniform ResourceIndicator), and will normally be the URL of the server. The optional secondargument is a transport factory instance; by default it is an internalSafeTransport
instance for https: URLs and an internal HTTPTransport
instance otherwise. The optional third argument is anencoding, by default UTF-8. The optional fourth argument is a debugging flag.None
will be translated intoXML; the default behaviour is for None
to raise a TypeError
. This isa commonly-used extension to the XML-RPC specification, but isn’t supported byall clients and servers; see http://ontosys.com/xml-rpc/extensions.phpfor a description.The use_builtin_types flag can be used to cause date/time valuesto be presented as datetime.datetime
objects and binary data to bepresented as bytes
objects; this flag is false by default.datetime.datetime
, bytes
and bytearray
objectsmay be passed to calls.The headers parameter is an optional sequence of HTTP headers to send witheach request, expressed as a sequence of 2-tuples representing the headername and value. (e.g. [(‘Header-Name’, ‘value’)]).The obsolete use_datetime flag is similar to use_builtin_types but itapplies only to date/time values.http://user:pass@host:port/path
. The user:pass
portion will be base64-encoded as an HTTP ‘Authorization’ header, and sent tothe remote server as part of the connection process when invoking an XML-RPCmethod. You only need to use this if the remote server requires a BasicAuthentication user and password. If an HTTPS URL is provided, context maybe ssl.SSLContext
and configures the SSL settings of the underlyingHTTPS connection.XML-RPC type | Python type |
---|---|
boolean | |
int , i1 ,i2 , i4 ,i8 orbiginteger | int in range from -2147483648 to 2147483647.Values get the <int> tag. |
double orfloat | float . Values get the <double> tag. |
string | |
array | list or tuple containingconformable elements. Arrays are returned aslists . |
struct | dict . Keys must be strings, values may beany conformable type. Objects of user-definedclasses can be passed in; only their__dict__ attribute is transmitted. |
dateTime.iso8601 | DateTime or datetime.datetime .Returned type depends on values ofuse_builtin_types and use_datetime flags. |
base64 | Binary , bytes orbytearray . Returned type depends on thevalue of the use_builtin_types flag. |
nil | The None constant. Passing is allowed only ifallow_none is true. |
bigdecimal | decimal.Decimal . Returned type only. |
Fault
instance, used to signal XML-RPC server errors, orProtocolError
used to signal an error in the HTTP/HTTPS transport layer.Both Fault
and ProtocolError
derive from a base class calledError
. Note that the xmlrpc client module currently does not marshalinstances of subclasses of built-in types.<
, >
, and &
will be automatically escaped. However, it’s the caller’s responsibility toensure that the string is free of characters that aren’t allowed in XML, such asthe control characters with ASCII values between 0 and 31 (except, of course,tab, newline and carriage return); failing to do this will result in an XML-RPCrequest that isn’t well-formed XML. If you have to pass arbitrary bytesvia XML-RPC, use bytes
or bytearray
classes or theBinary
wrapper class described below.Server
is retained as an alias for ServerProxy
for backwardscompatibility. New code should use ServerProxy
.ex:nil
).Added support of unmarshalling additional types used by Apache XML-RPCimplementation for numerics: i1
, i2
, i8
, biginteger
,float
and bigdecimal
.See http://ws.apache.org/xmlrpc/types.html for a description.ServerProxy
instance has a method corresponding to each remoteprocedure call accepted by the XML-RPC server. Calling the method performs anRPC, dispatched by both name and argument signature (e.g. the same method namecan be overloaded with multiple argument signatures). The RPC finishes byreturning a value, which may be either returned data in a conformant type or aFault
or ProtocolError
object indicating an error.system
attribute:ServerProxy.system.
listMethods
()¶ServerProxy.system.
methodSignature
(name)¶ServerProxy.system.
methodHelp
(name)¶ServerProxy
support the context manager protocolfor closing the underlying transport.xmlrpc.client.
DateTime
¶datetime.datetime
instance. It has the following methods, supported mainly for internaluse by the marshalling/unmarshalling code:decode
(string)¶encode
(out)¶DateTime
item to the out streamobject.__repr__()
methods.xmlrpc.client.
Binary
¶Binary
object is provided by anattribute:data
¶Binary
instance. The data isprovided as a bytes
object.Binary
objects have the following methods, supported mainly forinternal use by the marshalling/unmarshalling code:decode
(bytes)¶bytes
object and decode it as the instance’s new data.encode
(out)¶__eq__()
and __ne__()
methods.xmlrpc.client.
Fault
¶Fault
object encapsulates the content of an XML-RPC fault tag. Faultobjects have the following attributes:faultCode
¶faultString
¶Fault
byreturning a complex type object. The server code:xmlrpc.client.
ProtocolError
¶ProtocolError
object describes a protocol error in the underlyingtransport layer (such as a 404 ‘not found’ error if the server named by the URIdoes not exist). It has the following attributes:url
¶errcode
¶errmsg
¶headers
¶ProtocolError
by providing an invalid URI:MultiCall
object provides a way to encapsulate multiple calls to aremote server into a single request 1.xmlrpc.client.
MultiCall
(server)¶None
, and only store the call name and parameters in theMultiCall
object. Calling the object itself causes all stored calls tobe transmitted as a single system.multicall
request. The result of this callis a generator; iterating over this generator yields the individualresults.xmlrpc.client.
dumps
(params, methodname=None, methodresponse=None, encoding=None, allow_none=False)¶Fault
exception class. Desktop shelves pictures. If methodresponse is true, only a single valuecan be returned, meaning that params must be of length 1. encoding, ifsupplied, is the encoding to use in the generated XML; the default is UTF-8.Python’s None
value cannot be used in standard XML-RPC; to allow usingit via an extension, provide a true value for allow_none.xmlrpc.client.
loads
(data, use_datetime=False, use_builtin_types=False)¶(params,methodname)
. params is a tuple of argument; methodname is a string, orNone
if no method name is present in the packet. If the XML-RPC packetrepresents a fault condition, this function will raise a Fault
exception.The use_builtin_types flag can be used to cause date/time values to bepresented as datetime.datetime
objects and binary data to bepresented as bytes
objects; this flag is false by default.