RPC::PlClient(3pm)

1RPC::PlClient(3)      User Contributed Perl Documentation     RPC::PlClient(3)
2
3
4

NAME

6       RPC::PlClient - Perl extension for writing PlRPC clients
7

SYNOPSIS

9         require RPC::PlClient;
10
11         # Create a client object and connect it to the server
12         my $client = RPC::PlClient->new('peeraddr' => 'joes.host.de',
13                                         'peerport' => 2570,
14                                         'application' => 'My App',
15                                         'version' => '1.0',
16                                         'user' => 'joe',
17                                         'password' => 'hello!');
18
19         # Create an instance of $class on the server by calling $class->new()
20         # and an associated instance on the client.
21         my $object = $client->Call('NewHandle', $class, 'new', @args);
22
23
24         # Call a method on $object, effectively calling the same method
25         # on the associated server instance.
26         my $result = $object->do_method(@args);
27

DESCRIPTION

29       PlRPC (Perl RPC) is a package that simplifies the writing of Perl based
30       client/server applications. RPC::PlServer is the package used on the
31       server side, and you guess what RPC::PlClient is for. See
32       RPC::PlServer(3) for this part.
33
34       PlRPC works by defining a set of methods that may be executed by the
35       client.  For example, the server might offer a method "multiply" to the
36       client. Now a function call
37
38           @result = $client->Call('multiply', $a, $b);
39
40       on the client will be mapped to a corresponding call
41
42           $server->multiply($a, $b);
43
44       on the server. The function calls result will be transferred to the
45       client and returned as result of the clients method. Simple, eh? :-)
46
47   Client methods
48       $client = new(%attr);
49           (Class method) The client constructor. Returns a client object,
50           connected to the server. A Perl exception is thrown in case of
51           errors, thus you typically use it like this:
52
53               $client = eval { RPC::PlClient->new ( ... ) };
54               if ($@) {
55                   print STDERR "Cannot create client object: $@\n";
56                   exit 0;
57               }
58
59           The method accepts a list of key/value pairs as arguments. Known
60           arguments are:
61
62           peeraddr
63           peerport
64           socket_proto
65           socket_type
66           timeout These correspond to the attributes PeerAddr, PeerPort,
67                   Proto, Type and Timeout of IO::Socket::INET. The server
68                   connection will be established by passing them to
69                   IO::Socket::INET->new().
70
71           socket  After a connection was established, the IO::Socket instance
72                   will be stored in this attribute. If you prefer
73                   establishing the connection on your own, you may as well
74                   create an own instance of IO::Socket and pass it as
75                   attribute socket to the new method. The above attributes
76                   will be ignored in that case.
77
78           application
79           version
80           user
81           password
82                   it is part of the PlRPC authorization process, that the
83                   client must obeye a login procedure where he will pass an
84                   application name, a protocol version and optionally a user
85                   name and password.  These arguments are handled by the
86                   servers Application, Version and User methods.
87
88           compression
89                   Set this to off (default, no compression) or gzip (requires
90                   the Compress::Zlib module).
91
92           cipher  This attribute can be used to add encryption quite easily.
93                   PlRPC is not bound to a certain encryption method, but to a
94                   block encryption API. The attribute is an object supporting
95                   the methods blocksize, encrypt and decrypt. For example,
96                   the modules Crypt::DES and Crypt::IDEA support such an
97                   interface.
98
99                   Note that you can set or remove encryption on the fly
100                   (putting "undef" as attribute value will stop encryption),
101                   but you have to be sure, that both sides change the
102                   encryption mode.
103
104                   Example:
105
106                       use Crypt::DES;
107                       $cipher = Crypt::DES->new(pack("H*", "0123456789abcdef"));
108                       $client = RPC::PlClient->new('cipher' => $cipher,
109                                                   ...);
110
111           maxmessage
112                   The size of messages exchanged between client and server is
113                   restricted, in order to omit denial of service attacks. By
114                   default the limit is 65536 bytes.
115
116           debug   Enhances logging level by emitting debugging messages.
117
118           logfile By default the client is logging to syslog (Unix) or the
119                   event log (Windows).  If neither is available or you pass a
120                   TRUE value as logfile, then logging will happen to the
121                   given file handle, an instance of IO::Handle. If the value
122                   is scalar, then logging will occur to stderr.
123
124                   Examples:
125
126                     # Logging to stderr:
127                     my $client = RPC::PlClient->new('logfile' => 1, ...);
128
129                     # Logging to 'my.log':
130                     my $file = IO::File->new('my.log', 'a')
131                         || die "Cannot create log file 'my.log': $!";
132                     my $client = RPC::PlClient->new('logfile' => $file, ...);
133
134       @result = $client->Call($method, @args);
135           (Instance method) Calls a method on the server; the arguments are a
136           method name of the server class and the method call arguments. It
137           returns the method results, if successfull, otherwise a Perl
138           exception is thrown.
139
140           Example:
141
142             @results = eval { $client->Call($method, @args };
143             if ($@) {
144                 print STDERR "An error occurred while executing $method: $@\n";
145                 exit 0;
146             }
147
148       $cobj = $client->ClientObject($class, $method, @args)
149           (Instance method) A set of predefined methods is available that
150           make dealing with client side objects incredibly easy: In short the
151           client creates a representation of the server object for you. Say
152           we have an object $sobj on the server and an associated object
153           $cobj on the client: Then a call
154
155             @results = $cobj->my_method(@args);
156
157           will be immediately mapped to a call
158
159             @results = $sobj->my_method(@args);
160
161           on the server and the results returned to you without any
162           additional programming. Here's how you create $cobj, an instance of
163           RPC::PlClient::Object:
164
165             my $cobj = $client->ClientObject($class, 'new', @args);
166
167           This will trigger a call
168
169             my $sobj = $class->new(@args);
170
171           on the server for you. Note that the server has the ability to
172           restrict access to both certain classes and methods by setting
173           $server->{'methods'} appropriately.
174

EXAMPLE

176       We'll create a simple example application, an MD5 client. The server
177       will have installed the MD5 module and create digests for us. We
178       present the client part only, the server example is part of the
179       RPC::PlServer man page. See RPC::PlServer(3).
180
181           #!/usr/local/bin/perl
182
183           use strict;               # Always a good choice.
184
185           require RPC::PlClient;
186
187           # Constants
188           my $MY_APPLICATION = "MD5_Server";
189           my $MY_VERSION = 1.0;
190           my $MY_USER = "";           # The server doesn't require user
191           my $MY_PASSWORD = "";       # authentication.
192
193           my $hexdigest = eval {
194               my $client = RPC::PlClient->new
195                   ('peeraddr'    => '127.0.0.1',
196                    'peerport'    => 2000,
197                    'application' => $MY_APPLICATION,
198                    'version'     => $MY_VERSION,
199                    'user'        => $MY_USER,
200                    'password'    => $MY_PASSWORD);
201
202               # Create an MD5 object on the server and an associated
203               # client object. Executes a
204               #     $context = MD5->new()
205               # on the server.
206               my $context = $client->ClientObject('MD5', 'new');
207
208               # Let the server calculate a digest for us. Executes a
209               #     $context->add("This is a silly string!");
210               #     $context->hexdigest();
211               # on the server.
212               $context->add("This is a silly string!");
213               $context->hexdigest();
214           };
215           if ($@) {
216               die "An error occurred: $@";
217           }
218
219           print "Got digest $hexdigest\n";
220

AUTHOR AND COPYRIGHT

222       The PlRPC-modules are
223
224         Copyright (C) 1998, Jochen Wiedmann
225                             Email: jochen.wiedmann at freenet.de
226
227         All rights reserved.
228
229       You may distribute this package under the terms of either the GNU
230       General Public License or the Artistic License, as specified in the
231       Perl README file.
232

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

AUTHOR AND COPYRIGHT

SEE ALSO