== Class documentation
-[[xmlrpcval]]
-
-=== xmlrpcval
-
-This is where a lot of the hard work gets done. This class enables
- the creation and encapsulation of values for XML-RPC.
-
-Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7]
- before reading on as it will make things clearer.
-
-The xmlrpcval class can store arbitrarily
- complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++
- ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on
- what each of these types mean.
==== Notes on types
[[xmlrpcval-creation]]
-==== Creation
+==== Xmlrpcval creation
The constructor is the normal way to create an
xmlrpcval. The constructor can take these
See the file ++vardemo.php++ in this distribution
for more examples.
-[[xmlrpcval-methods]]
-
-==== Methods
-
-===== addScalar
-
-int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty
- xmlrpcval this method makes it a scalar
- value, and sets that value.
-
-If $val is already a scalar value, then
- no more scalars can be added and ++0++ is
- returned.
-
-If $val is an xmlrpcval of type array,
- the php value $scalarval is added as its last
- element.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addArray
-
-intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The
- elements of the array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into an
- array with contents as specified by
- $arrayVal.
-
-If $val is an xmlrpcval of type array,
- the elements of $arrayVal are appended to the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addStruct
-
-int addStructarray$assocArrayValThe argument is an associative array. The elements of the
- array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into a
- struct with contents as specified by
- $assocArrayVal.
-
-If $val is an xmlrpcval of type struct,
- the elements of $arrayVal are merged with the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== kindOf
-
-string kindOf Returns a string containing "struct", "array" or "scalar"
- describing the base type of the value. If it returns "undef" it
- means that the value hasn't been initialised.
-
-===== serialize
-
-string serialize Returns a string containing the XML-RPC representation of this
- value.
-
-
-===== scalarVal
-
-mixed scalarVal If $val->kindOf() == "scalar", this
- method returns the actual PHP-language value of the scalar (base 64
- decoding is automatically handled here).
-
-===== scalarTyp
-
-string scalarTyp If $val->kindOf() == "scalar", this
- method returns a string denoting the type of the scalar. As
- mentioned before, ++i4++ is always coerced to
- ++int++.
-
-===== arrayMem
-
-xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns
- the $nth element in the array represented by
- the value $val. The value returned is an
- xmlrpcval object.
-
-[source, php]
-----
-
-// iterating over values of an array object
-for ($i = 0; $i < $val->arraySize(); $i++)
-{
- $v = $val->arrayMem($i);
- echo "Element $i of the array is of type ".$v->kindOf();
-}
-
-----
-
-===== arraySize
-
-int arraySize If $val is an
- array, returns the number of elements in that
- array.
-
-===== structMem
-
-xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns
- the element called $memberName from the
- struct represented by the value $val. The
- value returned is an xmlrpcval object.
-
-===== structEach
-
-array structEach Returns the next (key, value) pair from the struct, when
- $val is a struct.
- $value is an xmlrpcval itself. See also <<structreset>>.
-
-[source, php]
-----
-
-// iterating over all values of a struct object
-$val->structreset();
-while (list($key, $v) = $val->structEach())
-{
- echo "Element $key of the struct is of type ".$v->kindOf();
-}
-
-----
-
-[[structreset]]
-
-===== structReset
-
-void structReset Resets the internal pointer for
- structEach() to the beginning of the struct,
- where $val is a struct.
-
-[[structmemexists]]
-
-===== structMemExists
-
-bool structMemExsists string $memberName Returns TRUE or
- FALSE depending on whether a member of the
- given name exists in the struct.
-
-[[xmlrpcmsg]]
-
-=== xmlrpcmsg
-
-This class provides a representation for a request to an XML-RPC
- server. A client sends an xmlrpcmsg to a server,
- and receives back an xmlrpcresp (see <<xmlrpc-client-send>>).
-
-==== Creation
-
-The constructor takes the following forms:
-
-xmlrpcmsgnew
- xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating
- the name of the method you wish to invoke, and
- parameterArray is a simple php
- Array of xmlrpcval
- objects. Here's an example message to the __US state name__ server:
-
-[source, php]
-----
-
-$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-
-----
-
-This example requests the name of state number 23. For more
- information on xmlrpcval objects, see <<xmlrpcval>>.
-
-Note that the parameterArray parameter is
- optional and can be omitted for methods that take no input parameters
- or if you plan to add parameters one by one.
-
-==== Methods
-
-
-===== addParam
-
-bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
- xmlrpcVal to the parameter list for this
- method call. Returns TRUE or FALSE on error.
-
-===== getNumParams
-
-int getNumParams Returns the number of parameters attached to this
- message.
-
-===== getParam
-
-xmlrpcval getParam int $n Gets the nth parameter in the message
- (with the index zero-based). Use this method in server
- implementations to retrieve the values sent by the client.
-
-===== method
-
-string method string method string $methNameGets or sets the method contained in the XML-RPC
- message.
-
-===== parseResponse
-
-xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the
- string $xmlString, this method constructs an
- xmlrpcresp response object and returns it,
- setting error codes as appropriate (see <<xmlrpc-client-send>>).
-
-This method processes any HTTP/MIME headers it finds.
-
-===== parseResponseFile
-
-xmlrpcresp parseResponseFile file handle
- resource$fileHandleGiven an incoming XML-RPC server response on the open file
- handle fileHandle, this method reads all the
- data it finds and passes it to
- parseResponse.
-
-This method is useful to construct responses from pre-prepared
- files (see files ++demo1.xml, demo2.xml, demo3.xml++
- in this distribution). It processes any HTTP headers it finds, and
- does not close the file handle.
-
-===== serialize
-
-string
- serializeReturns the an XML string representing the XML-RPC
- message.
-
[[xmlrpc-client]]
-=== xmlrpc_client
-
-This is the basic class used to represent a client of an XML-RPC
- server.
-
-==== Creation
+==== Xmlrpc-client creation
The constructor accepts one of two possible syntaxes:
meaning of the different values.
-==== Methods
-
-This class supports the following methods.
-
-[[xmlrpc-client-send]]
-
-===== send
-
-This method takes the forms:
-
-xmlrpcresp send xmlrpcmsg $xmlrpc_message int $timeout string $transport array sendarray $xmlrpc_messages int $timeout string $transportxmlrpcrespsendstring$xml_payloadint$timeoutstring$transportWhere xmlrpc_message is an instance of
- xmlrpcmsg (see <<xmlrpcmsg>>),
- and response is an instance of
- xmlrpcresp (see <<xmlrpcresp>>).
-
-If xmlrpc_messages is an array of
- message instances, ++responses++ will be an array of
- response instances. The client will try to make use of a single
- ++system.multicall++ xml-rpc method call to forward to the
- server all the messages in a single HTTP round trip, unless
- ++$$$client->no_multicall$$++ has been previously set to
- ++TRUE++ (see the multicall method below), in which case
- many consecutive xmlrpc requests will be sent.
-
-The third syntax allows to build by hand (or any other means)
- a complete xmlrpc request message, and send it to the server.
- xml_payload should be a string containing the
- complete xml representation of the request. It is e.g. useful when,
- for maximal speed of execution, the request is serialized into a
- string using the native php xmlrpc functions (see link:$$http://www.php.net/xmlrpc$$[the php manual on xmlrpc]).
-
-The timeout is optional, and will be
- set to ++0++ (wait for platform-specific predefined
- timeout) if omitted. This timeout value is passed to
- fsockopen(). It is also used for detecting
- server timeouts during communication (i.e. if the server does not
- send anything to the client for timeout
- seconds, the connection will be closed).
-
-The transport parameter is optional,
- and if omitted will default to the transport set using instance
- creator or 'http' if omitted. The only other valid values are
- 'https', which will use an SSL HTTP connection to connect to the
- remote server, and 'http11'. Note that your PHP must have the "curl"
- extension compiled in order to use both these features. Note that
- when using SSL you should normally set your port number to 443,
- unless the SSL server you are contacting runs at any other
- port.
-
-In addition to low-level errors, the XML-RPC server you were
- querying may return an error in the
- xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these
- errors.
-
-[[multicall]]
-
-===== multiCall
-
-This method takes the form:
-
-array multiCall array $messages int $timeout string $transport bool $fallback This method is used to boxcar many method calls in a single
- xml-rpc request. It will try first to make use of the
- ++system.multicall++ xml-rpc method call, and fall back to
- executing many separate requests if the server returns any
- error.
-
-msgs is an array of
- xmlrpcmsg objects (see <<xmlrpcmsg>>), and response is an
- array of xmlrpcresp objects (see <<xmlrpcresp>>).
-
-The timeout and
- transport parameters are optional, and behave
- as in the send method above.
-
-The fallback parameter is optional, and
- defaults to TRUE. When set to
- FALSE it will prevent the client to try using
- many single method calls in case of failure of the first multicall
- request. It should be set only when the server is known to support
- the multicall extension.
-
-===== setAcceptedCompression
-
-void setAcceptedCompression string $compressionmethod This method defines whether the client will accept compressed
- xml payload forming the bodies of the xmlrpc responses received from
- servers. Note that enabling reception of compressed responses merely
- adds some standard http headers to xmlrpc requests. It is up to the
- xmlrpc server to return compressed responses when receiving such
- requests. Allowed values for
- compressionmethod are: 'gzip', 'deflate',
- 'any' or null (with any meaning either gzip or deflate).
-
-This requires the "zlib" extension to be enabled in your php
- install. If it is, by default xmlrpc_client
- instances will enable reception of compressed content.
-
-===== setCaCertificate
-
-voidsetCaCertificatestring$certificatebool$is_dirThis method sets an optional certificate to be used in
- SSL-enabled communication to validate a remote server with (when the
- server_method is set to 'https' in the
- client's construction or in the send method and
- SetSSLVerifypeer has been set to
- TRUE).
-
-The certificate parameter must be the
- filename of a PEM formatted certificate, or a directory containing
- multiple certificate files. The is_dir
- parameter defaults to FALSE, set it to
- TRUE to specify that
- certificate indicates a directory instead of
- a single file.
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-
-===== setCertificate
-
-voidsetCertificatestring$certificatestring$passphraseThis method sets the optional certificate and passphrase used
- in SSL-enabled communication with a remote server (when the
- server_method is set to 'https' in the
- client's construction or in the send method).
-
-The certificate parameter must be the
- filename of a PEM formatted certificate. The
- passphrase parameter must contain the
- password required to use the certificate.
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-Note: to retrieve information about the client certificate on
- the server side, you will need to look into the environment
- variables which are set up by the webserver. Different webservers
- will typically set up different variables.
-
-===== setCookie
-
-void setCookiestring $name string $value string $path string $domain int $portThis method sets a cookie that will be sent to the xmlrpc
- server along with every further request (useful e.g. for keeping
- session info outside of the xml-rpc payload).
-
-$value is optional, and defaults to
- null.
-
-$path, $domain and $port are optional,
- and will be omitted from the cookie header if unspecified. Note that
- setting any of these values will turn the cookie into a 'version 1'
- cookie, that might not be fully supported by the server (see RFC2965
- for more details).
-
-===== setCredentials
-
-voidsetCredentialsstring$usernamestring$passwordint$authtypeThis method sets the username and password for authorizing the
- client to a server. With the default (HTTP) transport, this
- information is used for HTTP Basic authorization. Note that username
- and password can also be set using the class constructor. With HTTP
- 1.1 and HTTPS transport, NTLM and Digest authentication protocols
- are also supported. To enable them use the constants
- CURLAUTH_DIGEST and
- CURLAUTH_NTLM as values for the authtype
- parameter.
-
-
-===== setCurlOptions
-
-voidsetCurlOptionsarray$optionsThis method allows to directly set any desired
- option to manipulate the usage of the cURL client (when in cURL
- mode). It can be used eg. to explicitly bind to an outgoing ip
- address when the server is multihomed
-
-
-===== setDebug
-
-void setDebugint$debugLvldebugLvl is either ++0, 1++ or 2 depending on whether you require the client to
- print debugging information to the browser. The default is not to
- output this information (0).
-
-The debugging information at level 1includes the raw data
- returned from the XML-RPC server it was querying (including bot HTTP
- headers and the full XML payload), and the PHP value the client
- attempts to create to represent the value returned by the server. At
- level2, the complete payload of the xmlrpc request is also printed,
- before being sent t the server.
-
-This option can be very useful when debugging servers as it
- allows you to see exactly what the client sends and the server
- returns.
-
-
-===== setKey
-
-voidsetKeyint$keyint$keypassThis method sets the optional certificate key and passphrase
- used in SSL-enabled communication with a remote server (when the
- transport is set to 'https' in the client's
- construction or in the send method).
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-
-===== setProxy
-
-voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis method enables calling servers via an HTTP proxy. The
- proxyusername,
- proxypassword and authtype
- parameters are optional. Authtype defaults to
- CURLAUTH_BASIC (Basic authentication protocol);
- the only other valid value is the constant
- CURLAUTH_NTLM, and has effect only when the
- client uses the HTTP 1.1 protocol.
-
-NB: CURL versions before 7.11.10 cannot use a proxy to
- communicate with https servers.
-
-
-===== setRequestCompression
-
-voidsetRequestCompressionstring$compressionmethodThis method defines whether the xml payload forming the
- request body will be sent to the server in compressed format, as per
- the HTTP specification. This is particularly useful for large
- request parameters and over slow network connections. Allowed values
- for compressionmethod are: 'gzip', 'deflate',
- 'any' or null (with any meaning either gzip or deflate). Note that
- there is no automatic fallback mechanism in place for errors due to
- servers not supporting receiving compressed request bodies, so make
- sure that the particular server you are querying does accept
- compressed requests before turning it on.
-
-This requires the "zlib" extension to be enabled in your php
- install.
-
-
-===== setSSLVerifyHost
-
-voidsetSSLVerifyHostint$iThis method defines whether connections made to XML-RPC
- backends via HTTPS should verify the remote host's SSL certificate's
- common name (CN). By default, only the existence of a CN is checked.
- $i should be an
- integer value; 0 to not check the CN at all, 1 to merely check for
- its existence, and 2 to check that the CN on the certificate matches
- the hostname that is being connected to.
-
-
-===== setSSLVerifyPeer
-
-voidsetSSLVerifyPeerbool$iThis method defines whether connections made to XML-RPC
- backends via HTTPS should verify the remote host's SSL certificate,
- and cause the connection to fail if the cert verification fails.
- $i should be a boolean
- value. Default value: TRUE. To specify custom
- SSL certificates to validate the server with, use the
- setCaCertificate method.
-
-
-===== setUserAgent
-
-voidUseragentstring$useragentThis method sets a custom user-agent that will be
- used by the client in the http headers sent with the request. The
- default value is built using the library name and version
- constants.
-
-
-==== Variables
-
-NB: direct manipulation of these variables is only recommended
- for advanced users.
-
-
-===== no_multicall
-
-This member variable determines whether the multicall() method
- will try to take advantage of the system.multicall xmlrpc method to
- dispatch to the server an array of requests in a single http
- roundtrip or simply execute many consecutive http calls. Defaults to
- FALSE, but it will be enabled automatically on the first failure of
- execution of system.multicall.
-
-
-===== request_charset_encoding
-
-This is the charset encoding that will be used for serializing
- request sent by the client.
-
-If defaults to NULL, which means using US-ASCII and encoding
- all characters outside of the ASCII range using their xml character
- entity representation (this has the benefit that line end characters
- will not be mangled in the transfer, a CR-LF will be preserved as
- well as a singe LF).
-
-Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'
-
-[[return-type]]
-
-===== return_type
-
-This member variable determines whether the value returned
- inside an xmlrpcresp object as results of calls to the send() and
- multicall() methods will be an xmlrpcval object, a plain php value
- or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
- 'phpvals' and 'xml'. To allow the user to differentiate between a
- correct and a faulty response, fault responses will be returned as
- xmlrpcresp objects in any case. Note that the 'phpvals' setting will
- yield faster execution times, but some of the information from the
- original response will be lost. It will be e.g. impossible to tell
- whether a particular php string value was sent by the server as an
- xmlrpc string or base64 value.
-
-Example usage:
-
-
-[source, php]
-----
-
-$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
-$client->return_type = 'phpvals';
-$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-$resp = $client->send($message);
-if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
-
-----
-
-For more details about usage of the 'xml' value, see Appendix
- A.
-
-[[xmlrpcresp]]
-
-=== xmlrpcresp
-
-This class is used to contain responses to XML-RPC requests. A
- server method handler will construct an
- xmlrpcresp and pass it as a return value. This
- same value will be returned by the result of an invocation of the
- send method of the
- xmlrpc_client class.
-
-
-==== Creation
-
-xmlrpcrespnew
- xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
- xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without
- difficulty: $xmlrpcval is an
- xmlrpcval value with the result of the method
- execution contained in it. Alternatively it can be a string containing
- the xml serialization of the single xml-rpc value result of method
- execution.
-
-The second type of constructor is used in case of failure.
- errcode and err_string
- are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error
- codes.
-
-
-==== Methods
-
-
-===== faultCode
-
-intfaultCodeReturns the integer fault code return from the XML-RPC
- response. A zero value indicates success, any other value indicates
- a failure response.
-
-
-===== faultString
-
-stringfaultStringReturns the human readable explanation of the fault indicated
- by $resp->faultCode().
-
-
-===== value
-
-xmlrpcvalvalueReturns an xmlrpcval object containing
- the return value sent by the server. If the response's
- faultCode is non-zero then the value returned
- by this method should not be used (it may not even be an
- object).
-
-Note: if the xmlrpcresp instance in question has been created
- by an xmlrpc_client object whose
- return_type was set to 'phpvals', then a plain
- php value will be returned instead of an
- xmlrpcval object. If the
- return_type was set to 'xml', an xml string will
- be returned (see the return_type member var above for more
- details).
-
-
-===== serialize
-
-stringserializeReturns an XML string representation of the response (xml
- prologue not included).
-
[[xmlrpc-server]]
=== xmlrpc_server
git://git.onelab.eu / plcapi.git / blobdiff