.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RPC::pClient 3pm"
.TH RPC::pClient 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RPC::pClient \- Perl extension for writing pRPC clients
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use RPC::pClient;
\&
\&  $sock = IO::Socket::INET\->new(\*(AqPeerAddr\*(Aq => \*(Aqjoes.host.de\*(Aq,
\&                                \*(AqPeerPort\*(Aq => 2570,
\&                                \*(AqProto\*(Aq => \*(Aqtcp\*(Aq);
\&
\&  $connection = new RPC::pClient(\*(Aqsock\*(Aq => $sock,
\&                                 \*(Aqapplication\*(Aq => \*(AqMy App\*(Aq,
\&                                 \*(Aqversion\*(Aq => \*(Aq1.0\*(Aq,
\&                                 \*(Aquser\*(Aq => \*(Aqjoe\*(Aq,
\&                                 \*(Aqpassword\*(Aq => \*(Aqhello!\*(Aq);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
pRPC (Perl \s-1RPC\s0) is a package that simplifies the writing of
Perl based client/server applications. RPC::pServer is the
package used on the server side, and you guess what RPC::pClient
is for. See \fBRPC::pClient\fR\|(3) for this part.
.PP
pRPC works by defining a set of of functions that may be
executed by the client. For example, the server might offer
a function \*(L"multiply\*(R" to the client. Now a function call
.PP
.Vb 1
\&    @result = $con\->Call(\*(Aqmultiply\*(Aq, $a, $b);
.Ve
.PP
on the client will be mapped to a corresponding call
.PP
.Vb 1
\&    multiply($con, $data, $a, $b);
.Ve
.PP
on the server. (See the \fIfuncTable\fR description below for
\&\f(CW$data\fR.) The function calls result will be returned to the
client and stored in the array \f(CW@result\fR. Simple, eh? :\-)
.SS "Client methods"
.IX Subsection "Client methods"
.IP "new" 4
.IX Item "new"
The client constructor. Returns a client object or an error string,
thus you typically use it like this:
.Sp
.Vb 7
\&    $client = RPC::pClient\->new ( ... );
\&    if (!ref($client)) {
\&        print STDERR "Error while creating client object: $client\en";
\&    } else {
\&        # Do real stuff
\&        ...
\&    }
.Ve
.IP "Call" 4
.IX Item "Call"
calls a function on the server; the arguments are a function name,
followed by function arguments. It returns the function results,
if successful. After executing \fBCall()\fR you should always check
the \fIerror\fR attribute: An empty string indicates success. Thus
the equivalent to
.Sp
.Vb 3
\&    $c = Add($a, $b)
\&    # Use $c
\&    ...
.Ve
.Sp
is
.Sp
.Vb 8
\&    $c = $client\->Call("Add", $a, $b);
\&    if ($client\->error) {
\&        # Do something in case of error
\&        ...
\&    } else {
\&        # Use $c
\&        ...
\&    }
.Ve
.IP "CallInt" 4
.IX Item "CallInt"
Similar to and internally used by \fICall\fR. Receives the same
arguments, but the result is prepended by a status value: If this
status value is \s-1TRUE,\s0 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:
.Sp
.Vb 8
\&    my($status, @result) = $client\->CallInt("Add", $a, $b);
\&    if (!$status) {
\&        #  Do something in case of error
\&        my $errmsg = shift @result  ||  "Unknown error";
\&        ...
\&    } else {
\&        ...
\&    }
.Ve
.IP "Encrypt" 4
.IX Item "Encrypt"
This method can be used to get or set the \fIcipher\fR 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:
.Sp
.Vb 2
\&    # Get the current encryption mode
\&    $mode = $server\->Encrypt();
\&
\&    # Currently disable encryption
\&    $server\->Encrypt(undef);
\&
\&    # Switch back to the old mode
\&    $server\->Encrypt($mode);
.Ve
.SS "Client attributes"
.IX Subsection "Client attributes"
Client attributes will typically be supplied with the \f(CW\*(C`new\*(C'\fR
constructor.
.IP "sock" 4
.IX Item "sock"
An object of type IO::Socket, which should be connected to the
server.
.IP "cipher" 4
.IX 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 \s-1API.\s0 The
attribute is an object supporting the methods \fIblocksize\fR, \fIencrypt\fR
and \fIdecrypt\fR. For example, the modules Crypt::DES and Crypt::IDEA
support such an interface.
.Sp
Note that you can set or remove encryption on the fly (putting \f(CW\*(C`undef\*(C'\fR
as attribute value will stop encryption), but you have to be sure,
that both sides change the encryption mode.
.Sp
Do \fBnot\fR modify this attribute directly, use the \fIencrypt\fR method
instead! However, it is legal to pass the attribute to the constructor.
.Sp
Example:
.Sp
.Vb 3
\&    use Crypt::DES;
\&    $crypt = DES\->new(pack("H*", "0123456789abcdef"));
\&    $client\->Encrypt($crypt);
\&
\&    # or, to stop encryption
\&    $client\->Encrypt(undef);
.Ve
.IP "application" 4
.IX Item "application"
.PD 0
.IP "version" 4
.IX Item "version"
.IP "user" 4
.IX Item "user"
.IP "password" 4
.IX Item "password"
.PD
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.
.IP "io" 4
.IX 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 \fBStorable::Encrypt()\fR. See
\&\fBStorable\fR\|(3).
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 3
\&    #!/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(\*(AqPeerAddr\*(Aq => \*(Aqjoes.host.de\*(Aq,
\&                                     \*(AqPeerPort\*(Aq => 5000,
\&                                     \*(AqProto\*(Aq => \*(Aqtcp\*(Aq);
\&    if (!defined($sock)) {
\&        die "Cannot connect: $!\en";
\&    }
\&
\&    # Login procedure
\&    my $client = RPC::pClient\->new(\*(Aqsock\*(Aq => $sock,
\&                                   \*(Aqapplication\*(Aq => $MY_APPLICATION,
\&                                   \*(Aqversion\*(Aq => $MY_VERSION,
\&                                   \*(Aquser\*(Aq => $MY_USER,
\&                                   \*(Aqpassword\*(Aq => $MY_PASSWORD);
\&    if (!ref($client)) {
\&        die "Cannot create client: $client\en";
\&    }
\&
\&    # Call multiply function
\&    my $a = $client\->Call("multiply", 3, 4);
\&    if ($client\->error) {
\&        die "An error occurred while multiplying: $a\en";
\&    }
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Jochen Wiedmann, wiedmann@neckar\-alb.de
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBpRPC::Server\fR\|(3), \fBStorable\fR\|(3), \fBSys::Syslog\fR\|(3)
.PP
For an example application, see \fBDBD::pNET\fR\|(3).