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 successfull. 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
SEE ALSO¶
pRPC::Server(3),
Storable(3),
Sys::Syslog(3)
For an example application, see
DBD::pNET(3).