unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

RPC::PlClient(3pm)    User Contributed Perl Documentation   RPC::PlClient(3pm)



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 executed 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 transferred 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 exception 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: $@\n";
                   exit 0;
               }

           The method accepts a list of key/value pairs as arguments. 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 establish-
                   ing the connection 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 protocol 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 encryp-
                   tion 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 logfile, 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 excep-
           tion is thrown.

           Example:

             @results = eval { $client->Call($method, @args };
             if ($@) {
                 print STDERR "An error occurred while executing $method: $@\n";
                 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 representation 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 addi-
           tional 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 require 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 associated
               # client object. Executes a
               #     $context = MD5->new()
               # on the server.
               my $context = $client->ClientObject('MD5', 'new');

               # Let the server calculate a digest for us. Executes 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 $hexdigest\n";

AUTHOR AND COPYRIGHT
       The PlRPC-modules are

         Copyright (C) 1998, Jochen Wiedmann
                             Am Eisteich 9
                             72555 Metzingen
                             Germany

                             Phone: +49 7123 14887
                             Email: joeATispsoft.de

         All rights reserved.

       You may distribute this package under the terms of either the GNU Gen-
       eral Public License or the Artistic License, as specified in the Perl
       README file.

SEE ALSO
       PlRPC::Server(3), Net::Daemon(3), Storable(3), Sys::Syslog(3),
       Win32::EventLog

       An example application is the DBI Proxy client:

       DBD::Proxy(3).



perl v5.8.8                       2003-05-31                RPC::PlClient(3pm)