NAME

RPC::Xmlrpc_c::Client - XML-RPC For C/C++ client

SYNOPSIS

use RPC::Xmlrpc_c::Client;
use RPC::Xmlrpc_c::Client::Curl;

RPC::Xmlrpc_c::Client::Curl->createObject(TRANSPORT      => \$transport,
                                          TRANSPORTPARMS => {});

RPC::Xmlrpc_c::Client->createObject(TRANSPORT => $transport,
                                    CLIENT    => \$client,
                                    ERROR     => \$error);

$addend1 = RPC::Xmlrpc_c::Value->newInt(5);
$addend2 = RPC::Xmlrpc_c::Value->newInt(7);

$client->call(CARRIAGEPARM  => {
                  SERVERURL => 'http://localhost:8080/RPC2'
                              },
              METHOD        => 'sample.add',
              PARAMS        => [ $addend1, $addend2 ],
              RESULT_XMLRPC => \$result,
              ERROR         => \$error);
                      
print("Sum of 5 and 7 is $result->value()\n");

RPC::Xmlrpc_c::Client::callXml(METHOD => 'sample.add',
                               PARAMS => [ $addend1, $addend2 ],
                               XML    => \$xml,
                               ERROR  => \$error);

print("XML for call is: $xml\n");

DESCRIPTION

This module performs XML-RPC client functions, via the executable libraries of XML-RPC For C/C++. I.e. you can write an XML-RPC client program using this.

This differs from another, older facility, RPC::XML, in that RPC::XML is Perl all the way down to the operating system. Its modules call other Perl modules that provide HTTP and XML services, and those call other Perl modules, etc. By contrast, RPC::Xmlrpc_c::Client calls executable (machine language) libraries which are part of XML-RPC For C/C++. It requires much less CPU time.

An alternative that requires a little less code and understanding is RPC::Xmlrpc_c::ClientSimple. It's less flexible, though.

RPC::Xmlrpc_c::Client->createObject

RPC::Xmlrpc_c::Client->createObject(TRANSPORT => $transport,
                                    CLIENT    => \$client,
                                    ERROR     => \$error);

This creates a RPC::Xmlrpc_c::Client object, which you can use to perform XML-RPC RPCs.

Arguments:

TRANSPORT

This is the XML transport object the client will use to transport XML to and from the server. The only XML transport class included in the RPC-Xmlrpc_c package is RPC::Xmlrpc_c::Curl, which transports the XML via HTTP using the popular Curl HTTP library. But in theory, there can be other transport classes, and they don't even have to use HTTP (But if they don't, then it's not actually XML-RPC).

This argument is mandatory.

CLIENT

This is a reference to a scalar variable that the method sets to the handle of the new object.

If you do not specify this option, you don't get a handle for the object, and as no reference is created to the object, it gets destroyed as soon as it is created. This is not very useful.

If the method fails to create the object, it sets the variable arbitrarily. See ERROR.

ERROR

This is a reference to a scalar variable that the method sets to a text description of why it is unable to create the object. If it is able to create the object, it sets it to undef.

If you do not specify this option and creation fails, the method croaks.

RPC::Xmlrpc_c::call

$addend1 = RPC::Xmlrpc_c::Value->newInt(5);
$addend2 = RPC::Xmlrpc_c::Value->newInt(7);

$client->call(CARRIAGEPARM  => {
                  SERVERURL => 'http://localhost:8080/RPC2'
                              },
              METHOD        => 'sample.add',
              PARAMS        => [ $addend1, $addend2 ],
              RESULT_XMLRPC => \$result,
              ERROR         => \$error);
                      
print("Sum of 5 and 7 is $result->value()\n");

$client->call(CARRIAGEPARM  => {
                  SERVERURL => 'http://localhost:8080/RPC2'
                              },
              METHOD        => 'system.methodHelp',
              PARAMS        => [ 'sample.add' ],
              RESULT        => \$result,
              ERROR         => \$error);
                      
print("Help string for sample.add: $result\n");

This method performs an XML-RPC RPC. It makes the call, waits for the response, then returns the result.

Arguments:

CARRIAGEPARM

This is the carriage parameter that tells the XML transport how to transport the XML for this call. Its form and meaning depend on the transport class. You chose the transport class when you created the RPC::Xmlrpc_c::Client object. See the transport documentation (e.g. RPC::Xmlrpc_c::Client::Curl) for an explanation of this value.

The most typical thing for the carriage parameter to tell is the URL of the server.

METHOD

This is the name of the XML-RPC method you are invoking. An XML-RPC server offers various methods, identified by textual names.

PARAMS

This is a reference to an array of parameters for the RPC. An XML-RPC has an arbitrary number of ordered parameters. The meaning of the parameters depends upon the XML-RPC method.

The correspondence between each item in the array and the XML-RPC value which is the parameter is that documented for RPC::Xmlrpc_c::newSimple(). For example, 'hello' would signify the XML-RPC string value "hello", while [1, 2, 3] would signify an XML-RPC array value with 3 items, being respectively XML-RPC string values '1', '2', and '3'.

If you need more precise control over the XML-RPC types and values, use objects of class XML::Xmlrpc_c::Value. Example:

PARAMS => [ XML::Xmlrpc_c::Value(5),
            XML::Xmlrpc_c::Value(7) ]

If you do not specify PARAMS, there are no XML-RPC parameters.

RESULT

This is a reference to a scalar variable. call sets this variable to the XML-RPC result of the RPC.

The value set is of a basic Perl type. The correspondence between the XML-RPC value which is the result and the value of this variable is that you would get from RPC::Xmlrpc_c::Value::ValueSimple().

If the RPC fails or the client is unable to execute the RPC (see ERROR), call() croaks.

If you need more precise analysis of the result, use RESULT_XMLRPC instead.

You can specify both RESULT and RESULT_XMLRPC to get the same result in two forms.

If you specify neither RESULT nor RESULT_XMLRPC, you can't know the result of the RPC.

RESULT_XMLRPC

This is like RESULT except that call sets the referenced variable to a RPC::Xmlrpc_c::Value object, which means you have more detail about the result.

But you also need more code to use it.

tem ERROR

This is a reference to a scalar variable that the method sets to a text description of why it is unable to execute the RPC or why the RPC, though fully executed, failed. (The only way to distinguish the two is in the English interpretation of the text).

If the RPC completed with success, the method sets this variable to undef.

If you do not specify this option and call is unable to execute the RPC or the RPC fails, you can't tell.

When call sets the ERROR variable to a defined value, it makes the RESULT and RESULT_XMLRPC variables undefined.

RPC::Xmlrpc_c::Client::callXml

RPC::Xmlrpc_c::Client::callXml(METHOD => 'sample.add',
                               PARAMS => [ $addend1, $addend2 ],
                               XML    => \$xml,
                               ERROR  => \$error);

print("XML for call is: $xml\n");

This computes the XML for the described XML-RPC call. You could send this to an XML-RPC server, and get back the XML-RPC response XML, to effect an XML-RPC RPC.

Arguments:

METHOD

This is the name of the XML-RPC method you are invoking.

It is analogous to the same-named parameter of RPC::Xmlrpc_c::Client::call.

PARAMS

This is a reference to an array of parameters for the RPC.

It is analogous to the same-named parameter of RPC::Xmlrpc_c::Client::call.

XML

This is a reference to a scalar variable. callXml sets this variable to the XML for the call.

ERROR

This is a reference to a scalar variable that the method sets to a text description of why it is unable to generate the XML. If it is able to create the object, it sets it to undef.

If you do not specify this option and creation fails, the method croaks.