rpc::plclient(3)

NAME

RPC::PlClient - Perl extension for writing PlRPC clients

SYNOPSIS

require RPC::PlClient;
# Create a client object and connect it to the server
my   $client    =    RPC::PlClient->new('peeraddr'    =>
'joes.host.de',
                                'peerport' => 2570,
                                'application'   =>   'My
App',
                                'version' => '1.0',
                                'user' => 'joe',
                                'password' => 'hello!');
#  Create an instance of $class on the server by calling
$class->new()
# and an associated instance on the client.
my $object = $client->Call('NewHandle',  $class,  'new',
@args);
# Call a method on $object, effectively calling the same
method
# on the associated server instance.
my $result = $object->do_method(@args);

DESCRIPTION

PlRPC (Perl RPC) is a package that simplifies the writing
of Perl based client/server applications. RPC::PlServer is
the package used on the server side, and you guess what
RPC::PlClient is for. See RPC::PlServer(3) for this part.

PlRPC works by defining a set of methods that may be exe cuted by the client. For example, the server might offer a method "multiply" to the client. Now a function call: @result = $client->Call('multiply', $a, $b);
on the client will be mapped to a corresponding call: $server->multiply($a, $b);
on the server. The function calls result will be trans ferred to the client and returned as result of the clients method. Simple, eh? :-)
Client methods
$client = new(%attr);: (Class method) The client constructor. Returns a
client object, connected to the server. A Perl excep
tion is thrown in case of errors, thus you typically
use it like this:

$client = eval { RPC::PlClient->new ( ... ) };
if ($@) {
print STDERR "Cannot create client object:

$@0;
exit 0;

}; The method accepts a list of key/value pairs as argu
ments. Known arguments are:; peeraddr
peerport
socket_proto
socket_type
timeout These correspond to the attributes PeerAddr,
PeerPort, Proto, Type and Timeout of IO::Socket::INET. The server connection will
be established by passing them to
IO::Socket::INET->new().
socket After a connection was established, the: IO::Socket instance will be stored in this
attribute. If you prefer establishing the con
nection on your own, you may as well create an
own instance of IO::Socket and pass it as
attribute socket to the new method. The above
attributes will be ignored in that case.
application version user password: it is part of the PlRPC authorization process,
that the client must obeye a login procedure
where he will pass an application name, a pro
tocol version and optionally a user name and
password. These arguments are handled by the
servers Application, Version and User methods.
compression: Set this to off (default, no compression) or
gzip (requires the Compress::Zlib module).
cipher This attribute can be used to add encryption: quite easily. PlRPC is not bound to a certain
encryption method, but to a block encryption
API. The attribute is an object supporting the
methods blocksize, encrypt and decrypt. For example, the modules Crypt::DES and
Crypt::IDEA support such an interface.; Note that you can set or remove encryption on
the fly (putting "undef" as attribute value
will stop encryption), but you have to be
sure, that both sides change the encryption
mode.; Example:

use Crypt::DES;
$cipher = Crypt::DES->new(pack("H*",

"0123456789abcdef"));
$client = RPC::PlClient->new('cipher' =>

$cipher,
...);
maxmessage: The size of messages exchanged between client
and server is restricted, in order to omit
denial of service attacks. By default the
limit is 65536 bytes.
debug Enhances logging level by emitting debugging: messages.
logfile By default the client is logging to syslog: (Unix) or the event log (Windows). If neither
is available or you pass a TRUE value as log_
file, then logging will happen to the given
file handle, an instance of IO::Handle. If the
value is scalar, then logging will occur to
stderr.; Examples:

# Logging to stderr:
my $client = RPC::PlClient->new('logfile' =>

1, ...);

# Logging to 'my.log':
my $file = IO::File->new('my.log', 'a')
|| die "Cannot create log file 'my.log':

$!";

my $client = RPC::PlClient->new('logfile' =>

$file, ...);
@result = $client->Call($method, @args);: (Instance method) Calls a method on the server; the
arguments are a method name of the server class and
the method call arguments. It returns the method
results, if successfull, otherwise a Perl exception is
thrown.; Example:

@results = eval { $client->Call($method, @args };
if ($@) {
print STDERR "An error occurred while executing

$method: $@0;
exit 0;

}; $cobj = $client->ClientObject($class, $method, @args)
(Instance method) A set of predefined methods is
available that make dealing with client side objects
incredibly easy: In short the client creates a repre
sentation of the server object for you. Say we have an
object $sobj on the server and an associated object
$cobj on the client: Then a call

@results = $cobj->my_method(@args);

will be immediately mapped to a call

@results = $sobj->my_method(@args);

on the server and the results returned to you without
any additional programming. Here's how you create
$cobj, an instance of RPC::PlClient::Object:

my $cobj = $client->ClientObject($class, 'new',

@args);

This will trigger a call

my $sobj = $class->new(@args);

on the server for you. Note that the server has the
ability to restrict access to both certain classes and
methods by setting $server->{'methods'} appropriately.

EXAMPLE

We'll create a simple example application, an MD5 client. The server will have installed the MD5 module and create digests for us. We present the client part only, the server example is part of the RPC::PlServer man page. See RPC::PlServer(3).: #!/usr/local/bin/perl; use strict; # Always a good choice.; require RPC::PlClient;; # Constants
my $MY_APPLICATION = "MD5_Server";
my $MY_VERSION = 1.0;
my $MY_USER = ""; # The server doesn't re; quire user
my $MY_PASSWORD = ""; # authentication.; my $hexdigest = eval {
my $client = RPC::PlClient->new
('peeraddr' => '127.0.0.1',
'peerport' => 2000,
'application' => $MY_APPLICATION,
'version' => $MY_VERSION,
'user' => $MY_USER,
'password' => $MY_PASSWORD);

# Create an MD5 object on the server and an asso

ciated
# client object. Executes a
# $context = MD5->new()
# on the server.
my $context = $client->ClientObject('MD5', 'new');

# Let the server calculate a digest for us. Exe

cutes a
# $context->add("This is a silly string!");
# $context->hexdigest();
# on the server.
$context->add("This is a silly string!");
$context->hexdigest();

};
if ($@) {

die "An error occurred: $@";

}

print "Got digest $hexdigest0;

AUTHOR AND COPYRIGHT

The PlRPC-modules are: Copyright (C) 1998, Jochen Wiedmann
Am Eisteich 9
72555 Metzingen
Germany

Phone: +49 7123 14887
Email: joe@ispsoft.de
You may distribute this package under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

docs.sk

comprehensive documentation repository

In section