Ubuntu Manpage: RPC::pClient - Perl extension for writing pRPC clients

NAME

       RPC::pClient - Perl extension for writing pRPC clients

SYNOPSIS

         use RPC::pClient;

         $sock = IO::Socket::INET->new('PeerAddr' => 'joes.host.de',
                                       'PeerPort' => 2570,
                                       'Proto' => 'tcp');

         $connection = new RPC::pClient('sock' => $sock,
                                        'application' => 'My App',
                                        'version' => '1.0',
                                        'user' => 'joe',
                                        'password' => 'hello!');

DESCRIPTION

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

       pRPC works by defining a set of of functions that may be executed by the client. For example, the server
       might offer a function "multiply" to the client. Now a function call

           @result = $con->Call('multiply', $a, $b);

       on the client will be mapped to a corresponding call

           multiply($con, $data, $a, $b);

       on the server. (See the funcTable description below for $data.) The function calls result will be
       returned to the client and stored in the array @result. Simple, eh? :-)

   Client methods
       new The  client  constructor.  Returns a client object or an error string, thus you typically use it like
           this:

               $client = RPC::pClient->new ( ... );
               if (!ref($client)) {
                   print STDERR "Error while creating client object: $client\n";
               } else {
                   # Do real stuff
                   ...
               }

       Call
           calls a function on the server; the arguments are a function name, followed by function arguments. It
           returns the function results, if successful. After executing Call() you should always check the error
           attribute: An empty string indicates success. Thus the equivalent to

               $c = Add($a, $b)
               # Use $c
               ...

           is

               $c = $client->Call("Add", $a, $b);
               if ($client->error) {
                   # Do something in case of error
                   ...
               } else {
                   # Use $c
                   ...
               }

       CallInt
           Similar to and internally used by Call. Receives the same arguments, but the result is prepended by a
           status value: If this status value is TRUE, then all went fine and  the  following  result  array  is
           valid.  Otherwise  an error occurred and the error message follows immediately after the status code.
           Example:

               my($status, @result) = $client->CallInt("Add", $a, $b);
               if (!$status) {
                   #  Do something in case of error
                   my $errmsg = shift @result  ||  "Unknown error";
                   ...
               } else {
                   ...
               }

       Encrypt
           This method can be used to get or set the cipher attribute, thus the encryption mode. If  the  method
           is  passed  an  argument,  the  argument  will  be  used  as the new encryption mode. ('undef' for no
           encryption.)  In either case the current encryption mode will be returned. Example:

               # Get the current encryption mode
               $mode = $server->Encrypt();

               # Currently disable encryption
               $server->Encrypt(undef);

               # Switch back to the old mode
               $server->Encrypt($mode);

   Client attributes
       Client attributes will typically be supplied with the "new" constructor.

       sock
           An object of type IO::Socket, which should be connected to the server.

       cipher
           This attribute can be used to add encryption quite easily. pRPC 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.

           Do  not  modify this attribute directly, use the encrypt method instead! However, it is legal to pass
           the attribute to the constructor.

           Example:

               use Crypt::DES;
               $crypt = DES->new(pack("H*", "0123456789abcdef"));
               $client->Encrypt($crypt);

               # or, to stop encryption
               $client->Encrypt(undef);

       application
       version
       user
       password
           it is part of the pRPC 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.  You do
           not care for that (except passing the right values, of course :-), this is  done  within  the  client
           constructor.

       io  this  attribute  is  the Storable object created for communication with the server. You may use this,
           for example, when you want to change the encryption mode with Storable::Encrypt(). See Storable(3).

EXAMPLE

           #!/usr/local/bin/perl -T
           use 5.0004;               # Yes, this really *is* required.
           use strict;               # Always a good choice.

           use IO::Socket();
           use RPC::pClient;

           # Constants
           my $MY_APPLICATION = "Test Application";
           my $MY_VERSION = 1.0;
           my $MY_USER = "foo";
           my $MY_PASSWORD = "bar";

           # Connect to the server
           my $sock = IO::Socket::INET->new('PeerAddr' => 'joes.host.de',
                                            'PeerPort' => 5000,
                                            'Proto' => 'tcp');
           if (!defined($sock)) {
               die "Cannot connect: $!\n";
           }

           # Login procedure
           my $client = RPC::pClient->new('sock' => $sock,
                                          'application' => $MY_APPLICATION,
                                          'version' => $MY_VERSION,
                                          'user' => $MY_USER,
                                          'password' => $MY_PASSWORD);
           if (!ref($client)) {
               die "Cannot create client: $client\n";
           }

           # Call multiply function
           my $a = $client->Call("multiply", 3, 4);
           if ($client->error) {
               die "An error occurred while multiplying: $a\n";
           }

AUTHOR

       Jochen Wiedmann, wiedmann@neckar-alb.de

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

AUTHOR

SEE ALSO