Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RPC::PlClient(3)      User Contributed Perl Documentation     RPC::PlClient(3)

NAME
       RPC::PlClient - Perl extension for writing PlRPC	clients

SYNOPSIS
	 require RPC::PlClient;

	 # Create a client object and connect it to the	server
	 my $client = RPC::PlClient->new('peeraddr' => 'joes.host.de',
					 'peerport' => 2570,
					 'application' => 'My App',
					 'version' => '1.0',
					 'user'	=> 'joe',
					 'password' => 'hello!');

	 # Create an instance of $class	on the server by calling $class->new()
	 # and an associated instance on the client.
	 my $object = $client->Call('NewHandle', $class, 'new',	@args);

	 # Call	a method on $object, effectively calling the same method
	 # on the associated server instance.
	 my $result = $object->do_method(@args);

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

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

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

       on the client will be mapped to a corresponding call

	   $server->multiply($a, $b);

       on the server. The function calls result	will be	transferred to the
       client and returned as result of	the clients method. Simple, eh?	:-)

   Client methods
       $client = new(%attr);
	   (Class method) The client constructor. Returns a client object,
	   connected 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:

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

	   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 socket to the new method. The above attributes
		   will	be ignored in that case.

	   application
	   version
	   user
	   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 Application,	Version	and User methods.

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

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

		   Example:

		       use Crypt::DES;
		       $cipher = Crypt::DES->new(pack("H*", "0123456789abcdef"));
		       $client = RPC::PlClient->new('cipher' =>	$cipher,
						   ...);

	   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.

	   debug   Enhances logging level by emitting debugging	messages.

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

       @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;
	     }

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

	   on the server and the results returned to you without any
	   additional programming. Here's how you create $cobj,	an instance of
	   RPC::PlClient::Object:

	     my	$cobj =	$client->ClientObject($class, 'new', @args);

	   This	will trigger a call

	     my	$sobj =	$class->new(@args);

	   on the server for you. Note that the	server has the ability to
	   restrict access to both certain classes and methods by setting
	   $server->{'methods'}	appropriately.

EXAMPLE
       We'll create a simple example application, an MD5 client. The server
       will have installed the MD5 module and create digests for us. We
       present the client part only, the server	example	is part	of the
       RPC::PlServer man page. See RPC::PlServer(3).

	   #!/usr/local/bin/perl

	   use strict;		     # Always a	good choice.

	   require RPC::PlClient;

	   # Constants
	   my $MY_APPLICATION =	"MD5_Server";
	   my $MY_VERSION = 1.0;
	   my $MY_USER = "";	       # The server doesn't require user
	   my $MY_PASSWORD = "";       # authentication.

	   my $hexdigest = eval	{
	       my $client = RPC::PlClient->new
		   ('peeraddr'	  => '127.0.0.1',
		    'peerport'	  => 2000,
		    'application' => $MY_APPLICATION,
		    'version'	  => $MY_VERSION,
		    'user'	  => $MY_USER,
		    'password'	  => $MY_PASSWORD);

	       # Create	an MD5 object on the server and	an associated
	       # client	object.	Executes a
	       #     $context =	MD5->new()
	       # on the	server.
	       my $context = $client->ClientObject('MD5', 'new');

	       # Let the server	calculate a digest for us. Executes a
	       #     $context->add("This is a silly string!");
	       #     $context->hexdigest();
	       # on the	server.
	       $context->add("This is a	silly string!");
	       $context->hexdigest();
	   };
	   if ($@) {
	       die "An error occurred: $@";
	   }

	   print "Got digest $hexdigest\n";

AUTHOR AND COPYRIGHT
       The PlRPC-modules are

	 Copyright (C) 1998, Jochen Wiedmann
			     Email: jochen.wiedmann at freenet.de

	 All rights reserved.

       You may distribute this package under the terms of either the GNU
       General Public License or the Artistic License, as specified in the
       Perl README file.

SEE ALSO
       PlRPC::Server(3), Net::Daemon(3), Storable(3), Sys::Syslog(3),
       Win32::EventLog

       An example application is the DBI Proxy client:

       DBD::Proxy(3).

perl v5.32.1			  2007-06-17		      RPC::PlClient(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHOR AND COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=RPC::PlClient&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help