NAME

Event::RPC::Client - Client API to connect to Event::RPC Servers

SYNOPSIS

use Event::RPC::Client;

my $rpc_client = Event::RPC::Client->new (
  #-- Required arguments
  host => "localhost",
  port => 5555,
  
  #-- Optional arguments
  classes => [ "Event::RPC::Test" ],

  ssl     => 1,

  auth_user => "fred",
  auth_pass => Event::RPC->crypt("fred",$password),

  error_cb => sub {
    my ($client, $error) = @_;
    print "An RPC error occured: $error\n";
    $client->disconnect;
    exit;
  },
);

$rpc_client->connect;

#-- And now use classes and methods the server
#-- allows to access via RPC, here My::TestModule
#-- from the Event::RPC::Server manpage SYNPOSIS.
my $obj = My::TestModule->new( data => "foobar" );
print "obj says hello: ".$obj->hello."\n";
$obj->set_data("new foobar");
print "updated data: ".$obj->get_data."\n";

$rpc_client->disconnect;

DESCRIPTION

Use this module to write clients accessing objects and methods exported by a Event::RPC driven server.

Just connect to the server over the network, optionally with SSL and user authentication, and then simply use the exported classes and methods like having them locally in the client.

General information about the architecture of Event::RPC driven applications is collected in the Event::RPC manpage.

The following documentation describes the client connection options in detail.

CONFIGURATION OPTIONS

You need to specify at least the server hostname and TCP port to connect a Event::RPC server instance. If the server requires a SSL connection or user authentication you need to supply the corresponding options as well, otherwise connecting will fail.

All options described here may be passed to the new() constructor of Event::RPC::Client. As well you may set or modify them using set_OPTION style mutators, but not after connect() was called! All options may be read using get_OPTION style accessors.

REQUIRED OPTIONS

These are necessary to connect the server:

server

This is the hostname of the server running Event::RPC::Server. Use a IP address or DNS name here.

port

This is the TCP port the server is listening to.

CLASS IMPORT OPTION

classes

This is reference to a list of classes which should be imported into the client. You get a warning if you request a class which is not exported by the server.

By default all server classes are imported. Use this feature if your server exports a huge list of classes, but your client doesn't need all of them. This saves memory in the client and connect performance increases.

SSL OPTION

If the server accepts only SSL connections you need to enable ssl here in the client as well:

ssl

Set this option to 1 to encrypt the network connection using SSL.

AUTHENTICATION OPTIONS

If the server requires user authentication you need to set the following options:

auth_user

A valid username.

auth_pass

The corresponding password, encrypted using Perl's crypt() function, using the username as the salt.

Event::RPC has a convenience function for generating such a crypted password, although it's currently just a wrapper around Perl's builtin crypt() function, but probably this changes someday, so better use this method:

$crypted_pass = Event::RPC->crypt($user, $pass);

If the passed credentials are invalid the Event::RPC::Client->connect() method throws a correspondent exception.

METHODS

$rpc_client->connect

This establishes the configured connection to the server. An exception is thrown if something goes wrong, e.g. server not available, credentials are invalid or something like this.

$rpc_client->disconnect

Closes the connection to the server. You may omit explicit disconnecting since it's done automatically once the Event::RPC::Client object gets destroyed.

READY ONLY ATTRIBUTES

$rpc_client->get_server_version

Returns the Event::RPC version number of the server after connecting.

$rpc_client->get_server_protocol

Returns the Event::RPC protocol number of the server after connecting.

$rpc_client->get_client_version

Returns the Event::RPC version number of the client.

$rpc_client->get_client_protocol

Returns the Event::RPC protocol number of the client.

AUTHORS

Jörn Reder <joern at zyn dot de>

COPYRIGHT AND LICENSE

Copyright 2002-2005 by Jörn Reder.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU Library General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307 USA.

cpanm Event::RPC

perl -MCPAN -e shell
install Event::RPC