.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 "XML::RPC::Fast 3pm"
.TH XML::RPC::Fast 3pm "2022-06-28" "perl v5.34.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"
XML::RPC::Fast \- Fast and modular implementation for an XML\-RPC client and server
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Generic usage
.PP
.Vb 1
\&    use XML::RPC::Fast;
\&    
\&    my $server = XML::RPC::Fast\->new( undef, %args );
\&    my $client = XML::RPC::Fast\->new( $uri,  %args );
.Ve
.PP
Create a simple XML-RPC service:
.PP
.Vb 1
\&    use XML::RPC::Fast;
\&    
\&    my $rpc = XML::RPC::Fast\->new(
\&        undef,                         # the url is not required by server
\&        external_encoding => \*(Aqkoi8\-r\*(Aq, # any encoding, accepted by Encode
\&        #internal_encoding => \*(Aqkoi8\-r\*(Aq, # not supported for now
\&    );
\&    my $xml = do { local $/; <STDIN> };
\&    length($xml) == $ENV{CONTENT_LENGTH} or warn "Content\-Length differs from actually received";
\&    
\&    print "Content\-type: text/xml; charset=$rpc\->{external_encoding}\en\en";
\&    print $rpc\->receive( $xml, sub {
\&        my ( $methodname, @params ) = @_;
\&        return { you_called => $methodname, with_params => \e@params };
\&    } );
.Ve
.PP
Make a call to an XML-RPC service:
.PP
.Vb 1
\&    use XML::RPC::Fast;
\&    
\&    my $rpc = XML::RPC::Fast\->new(
\&        \*(Aqhttp://your.hostname/rpc/url\*(Aq
\&    );
\&    
\&    # Syncronous call
\&    my @result = $rpc\->req(
\&        call => [ \*(Aqexamples.getStateStruct\*(Aq, { state1 => 12, state2 => 28 } ],
\&        url => \*(Aqhttp://...\*(Aq,
\&    );
\&    
\&    # Syncronous call (compatibility method)
\&    my @result = $rpc\->call( \*(Aqexamples.getStateStruct\*(Aq, { state1 => 12, state2 => 28 } );
\&    
\&    # Syncronous or asyncronous call
\&    $rpc\->req(
\&        call => [\*(Aqexamples.getStateStruct\*(Aq, { state1 => 12, state2 => 28 }],
\&        cb   => sub {
\&            my @result = @_;
\&        },
\&    );
\&    
\&    # Syncronous or asyncronous call (compatibility method)
\&    $rpc\->call( sub {
\&        my @result = @_;
\&        
\&    }, \*(Aqexamples.getStateStruct\*(Aq, { state1 => 12, state2 => 28 } );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
XML::RPC::Fast is format-compatible with \s-1XML::RPC,\s0 but may use different encoders to parse/compose xml.
Curerntly included encoder uses XML::LibXML, and is 3 times faster than \s-1XML::RPC\s0 and 75% faster, than XML::Parser implementation
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new ($url, %args)"
.el .SS "new ($url, \f(CW%args\fP)"
.IX Subsection "new ($url, %args)"
Create XML::RPC::Fast object, server if url is undef, client if url is defined
.ie n .SS "req( %ARGS )"
.el .SS "req( \f(CW%ARGS\fP )"
.IX Subsection "req( %ARGS )"
Clientside. Make syncronous or asyncronous call (depends on \s-1UA\s0).
.PP
If have cb, will invoke \f(CW$cb\fR with results and should not croak
.PP
If have no cb, will return results and croak on error (only syncronous \s-1UA\s0)
.PP
Arguments are
.ie n .IP "call => [ methodName => @args ]" 4
.el .IP "call => [ methodName => \f(CW@args\fR ]" 4
.IX Item "call => [ methodName => @args ]"
array ref of call arguments. Required
.ie n .IP "cb => $cb\->(@results)" 4
.el .IP "cb => \f(CW$cb\fR\->(@results)" 4
.IX Item "cb => $cb->(@results)"
Invocation callback. Optional for syncronous \s-1UA.\s0 Behaviour is same as in call with \f(CW$cb\fR and without
.ie n .IP "url => $request_url" 4
.el .IP "url => \f(CW$request_url\fR" 4
.IX Item "url => $request_url"
Alternative invocation \s-1URL.\s0 Optional. By default will be used defined from constructor
.IP "headers => { http-headers hashref }" 4
.IX Item "headers => { http-headers hashref }"
Additional http headers to request
.IP "external_encoding => '...," 4
.IX Item "external_encoding => '...,"
Specify the encoding, used inside \s-1XML\s0 container just for this request. Passed to encoder
.ie n .SS "call( 'method_name', @arguments ) : @results"
.el .SS "call( 'method_name', \f(CW@arguments\fP ) : \f(CW@results\fP"
.IX Subsection "call( 'method_name', @arguments ) : @results"
Clientside. Make syncronous call and return results. Croaks on error. Just a simple wrapper around \f(CW\*(C`req\*(C'\fR
.ie n .SS "call( $cb\->(@res), 'method_name', @arguments ): void"
.el .SS "call( \f(CW$cb\fP\->(@res), 'method_name', \f(CW@arguments\fP ): void"
.IX Subsection "call( $cb->(@res), 'method_name', @arguments ): void"
Clientside. Make syncronous or asyncronous call (depends on \s-1UA\s0) and invoke \f(CW$cb\fR with results. Should not croak. Just a simple wrapper around \f(CW\*(C`req\*(C'\fR
.ie n .SS "receive ( $xml, $handler\->($methodName,@args) ) : xml byte-stream"
.el .SS "receive ( \f(CW$xml\fP, \f(CW$handler\fP\->($methodName,@args) ) : xml byte-stream"
.IX Subsection "receive ( $xml, $handler->($methodName,@args) ) : xml byte-stream"
Serverside. Process received \s-1XML\s0 and invoke \f(CW$handler\fR with parameters \f(CW$methodName\fR and \f(CW@args\fR and returns response \s-1XML\s0
.PP
On error conditions \f(CW$handler\fR could set \f(CW$XML::RPC::Fast::faultCode\fR and die, or return \f(CW\*(C`rpcfault($faultCode,$faultString)\*(C'\fR
.PP
.Vb 4
\&    \->receive( $xml, sub {
\&        # ...
\&        return rpcfault( 3, "Some error" ) if $error_condition
\&        $XML::RPC::Fast::faultCode = 4 and die "Another error" if $another_error_condition;
\&
\&        return { call => $methodname, params => \e@params };
\&    })
.Ve
.SS "registerType"
.IX Subsection "registerType"
Proxy-method to encoder. See XML::RPC::Enc
.SS "registerClass"
.IX Subsection "registerClass"
Proxy-method to encoder. See XML::RPC::Enc
.SH "OPTIONS"
.IX Header "OPTIONS"
Below is the options, accepted by \fBnew()\fR
.SS "ua"
.IX Subsection "ua"
Client only. Useragent object, or package name
.PP
.Vb 7
\&    \->new( $url, ua => \*(AqLWP\*(Aq ) # same as XML::RPC::UA::LWP
\&    # or 
\&    \->new( $url, ua => \*(AqXML::RPC::UA::LWP\*(Aq )
\&    # or 
\&    \->new( $url, ua => XML::RPC::UA::LWP\->new( ... ) )
\&    # or 
\&    \->new( $url, ua => XML::RPC::UA::Curl\->new( ... ) )
.Ve
.SS "timeout"
.IX Subsection "timeout"
Client only. Timeout for calls. Passed directly to \s-1UA\s0
.PP
.Vb 1
\&    \->new( $url, ua => \*(AqLWP\*(Aq, timeout => 10 )
.Ve
.SS "useragent"
.IX Subsection "useragent"
Client only. Useragent string. Passed directly to \s-1UA\s0
.PP
.Vb 1
\&    \->new( $url, ua => \*(AqLWP\*(Aq, useragent => \*(AqYourClient/1.11\*(Aq )
.Ve
.SS "encoder"
.IX Subsection "encoder"
Client and server. Encoder object or package name
.PP
.Vb 5
\&    \->new( $url, encoder => \*(AqLibXML\*(Aq )
\&    # or 
\&    \->new( $url, encoder => \*(AqXML::RPC::Enc::LibXML\*(Aq )
\&    # or 
\&    \->new( $url, encoder => XML::RPC::Enc::LibXML\->new( ... ) )
.Ve
.SS "internal_encoding \fB\s-1NOT IMPLEMENTED YET\s0\fP"
.IX Subsection "internal_encoding NOT IMPLEMENTED YET"
Specify the encoding you are using in your code. By default option is undef, which means flagged utf\-8
For translations is used Encode, so the list of accepted encodings fully derived from it.
.SS "external_encoding"
.IX Subsection "external_encoding"
Specify the encoding, used inside \s-1XML\s0 container. By default it's utf\-8. Passed directly to encoder
.PP
.Vb 1
\&    \->new( $url, encoder => \*(AqLibXML\*(Aq, external_encoding => \*(Aqkoi8\-r\*(Aq )
.Ve
.SH "ACCESSORS"
.IX Header "ACCESSORS"
.SS "url"
.IX Subsection "url"
Get or set client url
.SS "encoder"
.IX Subsection "encoder"
Direct access to encoder object
.SS "ua"
.IX Subsection "ua"
Direct access to useragent object
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "rpcfault(faultCode, faultString)"
.IX Subsection "rpcfault(faultCode, faultString)"
Returns hash structure, that may be returned by serverside handler, instead of die. Not exported by default
.SH "CUSTOM TYPES"
.IX Header "CUSTOM TYPES"
.SS "sub {{ 'base64' => encode_base64($data) }}"
.IX Subsection "sub {{ 'base64' => encode_base64($data) }}"
When passing a \s-1CODEREF\s0 as a value, encoder will simply use the returned hashref as a type => value pair.
.ie n .SS "bless( do{\e(my $o = encode_base64('test') )}, 'base64' )"
.el .SS "bless( do{\e(my \f(CW$o\fP = encode_base64('test') )}, 'base64' )"
.IX Subsection "bless( do{ $o = encode_base64('test') )}, 'base64' )"
When passing \s-1SCALARREF\s0 as a value, package name will be taken as type and dereference as a value
.ie n .SS "bless( do{\e(my $o = { something =>'complex' } )}, 'base64' )"
.el .SS "bless( do{\e(my \f(CW$o\fP = { something =>'complex' } )}, 'base64' )"
.IX Subsection "bless( do{ $o = { something =>'complex' } )}, 'base64' )"
When passing \s-1REFREF\s0 as a value, package name will be taken as type and XML::Hash::LX\f(CW\*(C`::hash2xml(deref)\*(C'\fR would be used as value
.ie n .SS "customtype( $type, $data )"
.el .SS "customtype( \f(CW$type\fP, \f(CW$data\fP )"
.IX Subsection "customtype( $type, $data )"
Easily compose \s-1SCALARREF\s0 based custom type
.SH "BUGS & SUPPORT"
.IX Header "BUGS & SUPPORT"
Bugs reports and testcases are welcome.
.PP
It you write your own Enc or \s-1UA, I\s0 may include it into distribution
.PP
If you have propositions for default custom types (see Enc), send me patches
.PP
See <http://rt.cpan.org> to report and view bugs.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mons Anderson, \f(CW\*(C`<mons@cpan.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 2008\-2009 Mons Anderson.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.