.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Event::RPC::Client 3pm" .TH Event::RPC::Client 3pm "2014-01-28" "perl v5.18.2" "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" Event::RPC::Client \- Client API to connect to Event::RPC Servers .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Event::RPC::Client; \& \& my $rpc_client = Event::RPC::Client\->new ( \& #\-\- Required arguments \& host => "localhost", \& port => 5555, \& \& #\-\- Optional arguments \& classes => [ "Event::RPC::Test" ], \& class_map => { "Event::RPC::Test" => "My::Event::RPC::Test" }, \& \& ssl => 1, \& ssl_ca_file => "some/ca.crt", \& ssl_ca_path => "some/ca/dir", \& \& timeout => 10, \& \& auth_user => "fred", \& auth_pass => Event::RPC\->crypt("fred",$password), \& \& error_cb => sub { \& my ($client, $error) = @_; \& print "An RPC error occured: $error\en"; \& $client\->disconnect; \& exit; \& }, \& ); \& \& $rpc_client\->set_max_packet_size(2*1024*1024*1024); \& $rpc_client\->connect; \& \& #\-\- And now use classes and methods to which the \& #\-\- server allows 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."\en"; \& $obj\->set_data("new foobar"); \& print "updated data: ".$obj\->get_data."\en"; \& \& $rpc_client\->disconnect; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Use this module to write clients accessing objects and methods exported by a Event::RPC driven server. .PP Just connect to the server over the network, optionally with \&\s-1SSL\s0 and user authentication, and then simply use the exported classes and methods like having them locally in the client. .PP General information about the architecture of Event::RPC driven applications is collected in the Event::RPC manpage. .PP The following documentation describes the client connection options in detail. .SH "CONFIGURATION OPTIONS" .IX Header "CONFIGURATION OPTIONS" You need to specify at least the server hostname and \s-1TCP\s0 port to connect a Event::RPC server instance. If the server requires a \s-1SSL\s0 connection or user authentication you need to supply the corresponding options as well, otherwise connecting will fail. .PP All options described here may be passed to the \fInew()\fR constructor of Event::RPC::Client. As well you may set or modify them using set_OPTION style mutators, but not after \fIconnect()\fR was called! All options may be read using get_OPTION style accessors. .SS "\s-1REQUIRED OPTIONS\s0" .IX Subsection "REQUIRED OPTIONS" These are necessary to connect the server: .IP "\fBserver\fR" 4 .IX Item "server" This is the hostname of the server running Event::RPC::Server. Use a \s-1IP\s0 address or \s-1DNS\s0 name here. .IP "\fBport\fR" 4 .IX Item "port" This is the \s-1TCP\s0 port the server is listening to. .SS "\s-1NETWORK OPTIONS\s0" .IX Subsection "NETWORK OPTIONS" .IP "\fBtimeout\fR" 4 .IX Item "timeout" Specify a timeout (in seconds), which is applied when connecting the server. .SS "\s-1CLASS IMPORT OPTION\s0" .IX Subsection "CLASS IMPORT OPTION" .IP "\fBclasses\fR" 4 .IX Item "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. .Sp 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. .IP "\fBclass_map\fR" 4 .IX Item "class_map" Optionally you can map the class names from the server to a different name on the local client using the \fBclass_map\fR hash. .Sp This is necessary if you like to use the same classes locally and remotely. Imported classes from the server are by default registered under the same name on the client, so this conflicts with local classes named identically. .Sp On the client you access the remote classes under the name assigned in the class map. For example with this map .Sp .Vb 1 \& class_map => { "Event::ExecFlow::Job" => "_srv::Event::ExecFlow::Job" } .Ve .Sp you need to write this on the client, if you like to create an object remotely on the server: .Sp .Vb 1 \& my $server_job = _srv::Event::ExecFlow::Job\->new ( ... ); .Ve .Sp and this to create an object on the client: .Sp .Vb 1 \& my $client_job = Event::ExecFlow::Job\->new ( ... ); .Ve .Sp The server knows nothing of the renaming on client side, so you still write this on the server to create objects there: .Sp .Vb 1 \& my $job = Event::ExecFlow::Job\->new ( ... ); .Ve .SS "\s-1SSL OPTIONS\s0" .IX Subsection "SSL OPTIONS" If the server accepts only \s-1SSL\s0 connections you need to enable ssl here in the client as well. By default the \s-1SSL\s0 connection will be established without any peer verification, which makes Man-in-the-Middle attacks possible. If you want to prevent that, you need to set either \fBssl_ca_file\fR or \fBssl_ca_path\fR option. .IP "\fBssl\fR" 4 .IX Item "ssl" Set this option to 1 to encrypt the network connection using \s-1SSL.\s0 .IP "\fBssl_ca_file\fR" 4 .IX Item "ssl_ca_file" Path to the the Certificate Authority's certificate file (ca.crt), your server key was signed with. .IP "\fBssl_ca_path\fR" 4 .IX Item "ssl_ca_path" Path of a directory containing several trusted certificates with a proper index. Please refer to the OpenSSL documentation for details about setting up such a directory. .SS "\s-1AUTHENTICATION OPTIONS\s0" .IX Subsection "AUTHENTICATION OPTIONS" If the server requires user authentication you need to set the following options: .IP "\fBauth_user\fR" 4 .IX Item "auth_user" A valid username. .IP "\fBauth_pass\fR" 4 .IX Item "auth_pass" The corresponding password, encrypted using Perl's \fIcrypt()\fR function, using the username as the salt. .Sp Event::RPC has a convenience function for generating such a crypted password, although it's currently just a wrapper around Perl's builtin \fIcrypt()\fR function, but probably this changes someday, so better use this method: .Sp .Vb 1 \& $crypted_pass = Event::RPC\->crypt($user, $pass); .Ve .PP If the passed credentials are invalid the Event::RPC::Client\->\fIconnect()\fR method throws a correspondent exception. .SS "\s-1ERROR HANDLING\s0" .IX Subsection "ERROR HANDLING" Any exceptions thrown on the server during execution of a remote method will result in a corresponding exception on the client. So you can use normal exception handling with eval {} when executing remote methods. .PP But besides this the network connection between your client and the server may break at any time. This raises an exception as well, but you can override this behaviour with the following attribute: .IP "\fBerror_cb\fR" 4 .IX Item "error_cb" This subroutine is called if any error occurs in the network communication between the client and the server. The actual Event::RPC::Client object and an error string are passed as arguments. .Sp This is \fBno\fR generic exception handler for exceptions thrown from the executed methods on the server! If you like to catch such exceptions you need to put an eval {} around your method calls, as you would do for local method calls. .Sp If you don't specify an \fBerror_cb\fR an exception is thrown instead. .SH "METHODS" .IX Header "METHODS" .ie n .IP "$rpc_client\->\fBconnect\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBconnect\fR" 4 .IX Item "$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. .ie n .IP "$rpc_client\->\fBdisconnect\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBdisconnect\fR" 4 .IX Item "$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. .ie n .IP "$rpc_client\->\fBset_max_packet_size\fR ( $bytes )" 4 .el .IP "\f(CW$rpc_client\fR\->\fBset_max_packet_size\fR ( \f(CW$bytes\fR )" 4 .IX Item "$rpc_client->set_max_packet_size ( $bytes )" By default Event::RPC does not handle network packages which exceed 2 \s-1GB\s0 in size (was 4 \s-1MB\s0 with version 1.04 and earlier). .Sp You can change this value using this method at any time, but 4 \s-1GB\s0 is the maximum. An attempt of the server to send a bigger packet will be aborted and reported as an exception on the client and logged as an error message on the server. .Sp Note: you have to set the same value on client and server side! .ie n .IP "$rpc_client\->\fBget_max_packet_size\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBget_max_packet_size\fR" 4 .IX Item "$rpc_client->get_max_packet_size" Returns the currently active max packet size. .SH "READY ONLY ATTRIBUTES" .IX Header "READY ONLY ATTRIBUTES" .ie n .IP "$rpc_client\->\fBget_server_version\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBget_server_version\fR" 4 .IX Item "$rpc_client->get_server_version" Returns the Event::RPC version number of the server after connecting. .ie n .IP "$rpc_client\->\fBget_server_protocol\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBget_server_protocol\fR" 4 .IX Item "$rpc_client->get_server_protocol" Returns the Event::RPC protocol number of the server after connecting. .ie n .IP "$rpc_client\->\fBget_client_version\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBget_client_version\fR" 4 .IX Item "$rpc_client->get_client_version" Returns the Event::RPC version number of the client. .ie n .IP "$rpc_client\->\fBget_client_protocol\fR" 4 .el .IP "\f(CW$rpc_client\fR\->\fBget_client_protocol\fR" 4 .IX Item "$rpc_client->get_client_protocol" Returns the Event::RPC protocol number of the client. .SH "AUTHORS" .IX Header "AUTHORS" .Vb 1 \& Jo\*:rn Reder .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2002\-2006 by Joern Reder, All Rights Reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.