Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Linux 2.6 - man page for rpc::plclient (linux section 3pm)

RPC::PlClient(3pm)	       User Contributed Perl Documentation	       RPC::PlClient(3pm)

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.10.0				    2007-06-17			       RPC::PlClient(3pm)


All times are GMT -4. The time now is 08:45 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password