view release on metacpan or  search on metacpan

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

    if ($client->error) {
        # Do something in case of error
        ...
    } else {
        # Use $c
        ...
    }

=item CallInt

Similar to and internally used by I<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 {
        ...
    }

=item Encrypt

This method can be used to get or set the I<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);

=back

=head2 Client attributes

Client attributes will typically be supplied with the C<new>
constructor.

=over 4

=item sock

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

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

Do B<not> modify this attribute directly, use the I<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);

=item application

=item version

=item user

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

=item 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
L<Storable(3)>.

=back

=head1 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";