{ "mode": "perldoc", "parameter": "RPC::XML::Client", "section": "", "url": "https://www.chedong.com/phpMan.php/perldoc/RPC%3A%3AXML%3A%3AClient/json", "generated": "2026-06-13T11:21:38Z", "synopsis": "require RPC::XML;\nrequire RPC::XML::Client;\n$cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');\n$resp = $cli->sendrequest('system.listMethods');\nprint ref $resp ? join(', ', @{$resp->value}) : \"Error: $resp\";", "sections": { "NAME": { "content": "RPC::XML::Client - An XML-RPC client class\n", "subsections": [] }, "SYNOPSIS": { "content": "require RPC::XML;\nrequire RPC::XML::Client;\n\n$cli = RPC::XML::Client->new('http://www.localhost.net/RPCSERV');\n$resp = $cli->sendrequest('system.listMethods');\n\nprint ref $resp ? join(', ', @{$resp->value}) : \"Error: $resp\";\n", "subsections": [] }, "DESCRIPTION": { "content": "This is an XML-RPC client built upon the RPC::XML data classes, and using LWP::UserAgent and\nHTTP::Request for the communication layer. This client supports the full XML-RPC specification.\n", "subsections": [] }, "SUBROUTINES/METHODS": { "content": "The following methods are available:\n\nnew (URI [, ARGS])\nCreates a new client object that will route its requests to the URL provided. The\nconstructor creates a HTTP::Request object and a LWP::UserAgent object, which are stored on\nthe client object. When requests are made, these objects are ready to go, with the headers\nset appropriately. The return value of this method is a reference to the new object. The\n\"URI\" argument may be a string or an object from the URI class from CPAN.\n\nAny additional arguments are treated as key-value pairs. Most are attached to the object\nitself without change. The following are recognized by \"new\" and treated specially:\n\nparser\nIf this parameter is passed, the value following it is expected to be an array\nreference. The contents of that array are passed to the new method of the\nRPC::XML::ParserFactory-generated object that the client object caches for its use. See\nthe RPC::XML::ParserFactory manual page for a list of recognized parameters to the\nconstructor.\n\nuseragent\nThis is similar to the \"parser\" argument above, and also expects an array reference to\nfollow it. The contents are passed to the constructor of the LWP::UserAgent class when\ncreating that component of the client object. See the manual page for LWP::UserAgent for\nsupported values.\n\nerrorhandler\nIf passed, the value must be a code reference that will be invoked when a request\nresults in a transport-level error. The closure will receive a single argument, the text\nof the error message from the failed communication attempt. It is expected to return a\nsingle value (assuming it returns at all).\n\nfaulthandler\nIf passed, the value must be a code reference. This one is invoked when a request\nresults in a fault response from the server. The closure will receive a single argument,\na RPC::XML::fault instance that can be used to retrieve the code and text-string of the\nfault. It is expected to return a single value (if it returns at all).\n\ncombinedhandler\nIf this parameter is specified, it too must have a code reference as a value. It is\ninstalled as the handler for both faults and errors. Should either of the other\nparameters be passed in addition to this one, they will take precedence over this\n(more-specific wins out over less). As a combined handler, the closure will get a string\n(non-reference) in cases of errors, and an instance of RPC::XML::fault in cases of\nfaults. This allows the developer to install a simple default handler, while later\nproviding a more specific one by means of the methods listed below.\n\nmessagefilethresh\nIf this key is passed, the value associated with it is assumed to be a numerical limit\nto the size of in-memory messages. Any out-bound request that would be larger than this\nwhen stringified is instead written to an anonynous temporary file, and spooled from\nthere instead. This is useful for cases in which the request includes RPC::XML::base64\nobjects that are themselves spooled from file-handles. This test is independent of\ncompression, so even if compression of a request would drop it below this threshold, it\nwill be spooled anyway. The file itself is created via File::Temp with UNLINK=>1, so\nonce it is freed the disk space is immediately freed.\n\nmessagetempdir\nIf a message is to be spooled to a temporary file, this key can define a specific\ndirectory in which to open those files. If this is not given, then the \"tmpdir\" method\nfrom the File::Spec package is used, instead.\n\nrequestasstring\nFor aiding in debugging, you can pass this key with a non-false value to enable a step\nin each request cycle that saves a stringified version of the request XML as a private\nkey on the client object. The request will be saved to the key\n\"xmlrpcrequestasstring\", and will endure until the next request is made by the\nclient object.\n\nSee the section on the effects of callbacks on return values, below.\n\nuri ([URI])\nReturns the URI that the invoking object is set to communicate with for requests. If a\nstring or \"URI\" class object is passed as an argument, then the URI is set to the new value.\nIn either case, the pre-existing value is returned.\n\nuseragent\nReturns the LWP::UserAgent object instance stored on the client object. It is not possible\nto assign a new such object, though direct access to it should allow for any header\nmodifications or other needed operations.\n\nrequest\nReturns the HTTP::Request object. As with the above, it is not allowed to assign a new\nobject, but access to this value should allow for any needed operations.\n\nsimplerequest (ARGS)\nThis is a somewhat friendlier wrapper around the next routine (\"sendrequest\") that returns\nPerl-level data rather than an object reference. The arguments may be the same as one would\npass to the RPC::XML::request constructor, or there may be a single request object as an\nargument. The return value will be a native Perl value. If the return value is \"undef\", an\nerror has occurred and \"simplerequest\" has placed the error message in the global variable\n$RPC::XML::ERROR.\n\nsendrequest (ARGS)\nSends a request to the server and attempts to parse the returned data. The argument may be\nan object of the RPC::XML::request class, or it may be the arguments to the constructor for\nthe request class. The return value will be either an error string or a data-type object. If\nthe error encountered was a run-time error within the RPC request itself, then the call will\nreturn a \"RPC::XML::fault\" value rather than an error string.\n\nIf the return value from \"sendrequest\" is not a reference, then it can only mean an error\non the client-side (a local problem with the arguments and/or syntax, or a transport\nproblem). All data-type classes now support a method called \"isfault\" that may be easily\nused to determine if the \"successful\" return value is actually a \"RPC::XML::fault\" without\nthe need to use \"UNIVERSAL::ISA\".\n\nerrorhandler ([CODEREF])\nfaulthandler ([CODEREF])\ncombinedhandler ([CODEREF])\nThese accessor methods get (and possibly set, if CODEREF is passed) the specified\ncallback/handler. The return value is always the current handler, even when setting a new\none (allowing for later restoration, if desired).\n\ncredentials (REALM, USERNAME, PASSWORD)\nThis sets the username and password for a given authentication realm at the location\nassociated with the current request URL. Needed if the RPC location is protected by Basic\nAuthentication. Note that changing the target URL of the client object to a different\n(protected) location would require calling this with new credentials for the new realm (even\nif the value of $realm is identical at both locations).\n\ntimeout ([INTEGER])\nGet or set the current time-out value on the underlying LWP::UserAgent object that this\nobject uses for sending requests. This is just a proxy through to the method of the same\nname in the LWP::UserAgent class. The return value is the current time-out value (prior to\nchange, if a new value is given).\n\nmessagefilethresh\nmessagetempdir\nThese methods may be used to retrieve or alter the values of the given keys as defined\nearlier for the \"new\" method.\n", "subsections": [ { "name": "Support for Content Compression", "content": "The RPC::XML::Server class supports compression of requests and responses via the Compress::Zlib\nmodule available from CPAN. Accordingly, this class also supports compression. The methods used\nfor communicating compression support should be compatible with the server and client classes\nfrom the XMLRPC::Lite class that is a part of the SOAP::Lite package (also available from CPAN).\n\nCompression support is enabled (or not) behind the scenes; if the Perl installation has\nCompress::Zlib, then RPC::XML::Client can deal with compressed responses. However, since\noutgoing messages are sent before a client generally has the chance to see if a server supports\ncompression, these are not compressed by default.\n" }, { "name": "compress_requests", "content": "If a client is communicating with a server that is known to support compressed messages,\nthis method can be used to tell the client object to compress any outgoing messages that are\nlonger than the threshold setting in bytes.\n" }, { "name": "compress_thresh", "content": "With no arguments, returns the current compression threshold; messages smaller than this\nnumber of bytes will not be compressed, regardless of the above method setting. If a number\nis passed, this is set to the new lower-limit. The default value is 4096 (4k).\n" }, { "name": "Callbacks and Return Values", "content": "If a callback is installed for errors or faults, it will be called before either of\n\"sendrequest\" or \"simplerequest\" return. If the callback calls die or otherwise interrupts\nexecution, then there is no need to worry about the effect on return values. Otherwise, the\nreturn value of the callback becomes the return value of the original method (\"sendrequest\" or\n\"simplerequest\"). Thus, all callbacks are expected, if they return at all, to return exactly\none value. It is recommended that any callback return values conform to the expected return\nvalues. That is, an error callback would return a string, a fault callback would return the\nfault object.\n" } ] }, "DIAGNOSTICS": { "content": "All methods return some type of reference on success, or an error string on failure.\nNon-reference return values should always be interpreted as errors, except in the case of\n\"simplerequest\".\n", "subsections": [] }, "CAVEATS": { "content": "This began as a reference implementation in which clarity of process and readability of the code\ntook precedence over general efficiency. It is now being maintained as production code, but may\nstill have parts that could be written more efficiently.\n", "subsections": [] }, "BUGS": { "content": "Please report any bugs or feature requests to \"bug-rpc-xml at rt.cpan.org\", or through the web\ninterface at . I will be notified, and\nthen you'll automatically be notified of progress on your bug as I make changes.\n", "subsections": [] }, "SUPPORT": { "content": "* RT: CPAN's request tracker\n\n\n\n* AnnoCPAN: Annotated CPAN documentation\n\n\n\n* CPAN Ratings\n\n\n\n* Search CPAN\n\n\n\n* MetaCPAN\n\n\n\n* Source code on GitHub\n\n\n", "subsections": [] }, "LICENSE AND COPYRIGHT": { "content": "This file and the code within are copyright (c) 2011 by Randy J. Ray.\n\nCopying and distribution are permitted under the terms of the Artistic License 2.0\n() or the GNU LGPL 2.1\n().\n", "subsections": [] }, "CREDITS": { "content": "The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software, Inc. See\n for more information about the XML-RPC specification.\n", "subsections": [] }, "SEE ALSO": { "content": "RPC::XML, RPC::XML::Server\n", "subsections": [] }, "AUTHOR": { "content": "Randy J. Ray \"\"\n", "subsections": [] } }, "summary": "RPC::XML::Client - An XML-RPC client class", "flags": [], "examples": [], "see_also": [] }