-==== 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).
-
git://git.onelab.eu / plcapi.git / commitdiff