view release on metacpan or  search on metacpan

lib/RPC/PlClient.pm  view on Meta::CPAN

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:

=over 8

=item peeraddr

=item peerport

=item socket_proto

=item socket_type

=item timeout

These correspond to the attributes I<PeerAddr>, I<PeerPort>, I<Proto>,
I<Type> and I<Timeout> of IO::Socket::INET. The server connection will be
established by passing them to IO::Socket::INET->new().

=item socket

After a connection was established, the IO::Socket instance will be stored
in this attribute. If you prefer establishing the connection on your own,
you may as well create an own instance of IO::Socket and pass it as attribute
I<socket> to the new method. The above attributes will be ignored in that
case.

=item application

=item version

=item user

=item 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 I<Application>, I<Version>
and I<User> methods.

=item compression

Set this to off (default, no compression) or gzip (requires the
Compress::Zlib module).

=item 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 I<blocksize>, I<encrypt>
and I<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 C<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,
				...);

=item 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.

=item debug

Enhances logging level by emitting debugging messages.

=item 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 I<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, ...);

=back

=item @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: $@\n";
      exit 0;
  }

=item $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);