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