X-Git-Url: http://git.onelab.eu/?p=plcapi.git;a=blobdiff_plain;f=doc%2Fmanual%2Fphpxmlrpc_manual.adoc;h=0e8f2c44329f256cf3049bd07c2ac97e1beb2a6f;hp=0a78d0c728bcdcb74910fa30b566ca4d8354ce6b;hb=f4978078febfc4289bb4f45db6ca3f9e6c8c4f94;hpb=448067b0570d853d290c9378838cc20f99f436c8 diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc index 0a78d0c..0e8f2c4 100644 --- a/doc/manual/phpxmlrpc_manual.adoc +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -215,20 +215,6 @@ If you've benefited from the effort that has been put into writing this software == 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 @@ -276,7 +262,7 @@ There is no support for encoding ++null++ [[xmlrpcval-creation]] -==== Creation +==== Xmlrpcval creation The constructor is the normal way to create an xmlrpcval. The constructor can take these @@ -353,248 +339,9 @@ $myStruct = new xmlrpcval( 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 <>. - -[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 <>). - -==== 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 <>. - -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 <>). - -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: @@ -640,403 +387,6 @@ The transport parameter is optional, and 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 <>), - and response is an instance of - xmlrpcresp (see <>). - -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 <> 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 <>), and response is an - array of xmlrpcresp objects (see <>). - -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 <> 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