| 1 |
NAME |
| 2 |
XML::RPC::Fast - Fast and modular implementation for an XML-RPC client |
| 3 |
and server |
| 4 |
|
| 5 |
SYNOPSIS |
| 6 |
Generic usage |
| 7 |
|
| 8 |
use XML::RPC::Fast; |
| 9 |
|
| 10 |
my $server = XML::RPC::Fast->new( undef, %args ); |
| 11 |
my $client = XML::RPC::Fast->new( $uri, %args ); |
| 12 |
|
| 13 |
Create a simple XML-RPC service: |
| 14 |
|
| 15 |
use XML::RPC::Fast; |
| 16 |
|
| 17 |
my $rpc = XML::RPC::Fast->new( |
| 18 |
undef, # the url is not required by server |
| 19 |
external_encoding => 'koi8-r', # any encoding, accepted by Encode |
| 20 |
#internal_encoding => 'koi8-r', # not supported for now |
| 21 |
); |
| 22 |
my $xml = do { local $/; <STDIN> }; |
| 23 |
length($xml) == $ENV{CONTENT_LENGTH} or warn "Content-Length differs from actually received"; |
| 24 |
|
| 25 |
print "Content-type: text/xml; charset=$rpc->{external_encoding}\n\n"; |
| 26 |
print $rpc->receive( $xml, sub { |
| 27 |
my ( $methodname, @params ) = @_; |
| 28 |
return { you_called => $methodname, with_params => \@params }; |
| 29 |
} ); |
| 30 |
|
| 31 |
Make a call to an XML-RPC service: |
| 32 |
|
| 33 |
use XML::RPC::Fast; |
| 34 |
|
| 35 |
my $rpc = XML::RPC::Fast->new( |
| 36 |
'http://your.hostname/rpc/url' |
| 37 |
); |
| 38 |
|
| 39 |
# Syncronous call |
| 40 |
my @result = $rpc->req( |
| 41 |
call => [ 'examples.getStateStruct', { state1 => 12, state2 => 28 } ], |
| 42 |
url => 'http://...', |
| 43 |
); |
| 44 |
|
| 45 |
# Syncronous call (compatibility method) |
| 46 |
my @result = $rpc->call( 'examples.getStateStruct', { state1 => 12, state2 => 28 } ); |
| 47 |
|
| 48 |
# Syncronous or asyncronous call |
| 49 |
$rpc->req( |
| 50 |
call => ['examples.getStateStruct', { state1 => 12, state2 => 28 }], |
| 51 |
cb => sub { |
| 52 |
my @result = @_; |
| 53 |
}, |
| 54 |
); |
| 55 |
|
| 56 |
# Syncronous or asyncronous call (compatibility method) |
| 57 |
$rpc->call( sub { |
| 58 |
my @result = @_; |
| 59 |
|
| 60 |
}, 'examples.getStateStruct', { state1 => 12, state2 => 28 } ); |
| 61 |
|
| 62 |
DESCRIPTION |
| 63 |
XML::RPC::Fast is format-compatible with XML::RPC, but may use different |
| 64 |
encoders to parse/compose xml. Curerntly included encoder uses |
| 65 |
XML::LibXML, and is 3 times faster than XML::RPC and 75% faster, than |
| 66 |
XML::Parser implementation |
| 67 |
|
| 68 |
METHODS |
| 69 |
new ($url, %args) |
| 70 |
Create XML::RPC::Fast object, server if url is undef, client if url is |
| 71 |
defined |
| 72 |
|
| 73 |
req( %ARGS ) |
| 74 |
Clientside. Make syncronous or asyncronous call (depends on UA). |
| 75 |
|
| 76 |
If have cb, will invoke $cb with results and should not croak |
| 77 |
|
| 78 |
If have no cb, will return results and croak on error (only syncronous |
| 79 |
UA) |
| 80 |
|
| 81 |
Arguments are |
| 82 |
|
| 83 |
call => [ methodName => @args ] |
| 84 |
array ref of call arguments. Required |
| 85 |
|
| 86 |
cb => $cb->(@results) |
| 87 |
Invocation callback. Optional for syncronous UA. Behaviour is same |
| 88 |
as in call with $cb and without |
| 89 |
|
| 90 |
url => $request_url |
| 91 |
Alternative invocation URL. Optional. By default will be used |
| 92 |
defined from constructor |
| 93 |
|
| 94 |
headers => { http-headers hashref } |
| 95 |
Additional http headers to request |
| 96 |
|
| 97 |
external_encoding => '..., |
| 98 |
Specify the encoding, used inside XML container just for this |
| 99 |
request. Passed to encoder |
| 100 |
|
| 101 |
call( 'method_name', @arguments ) : @results |
| 102 |
Clientside. Make syncronous call and return results. Croaks on error. |
| 103 |
Just a simple wrapper around "req" |
| 104 |
|
| 105 |
call( $cb->(@res), 'method_name', @arguments ): void |
| 106 |
Clientside. Make syncronous or asyncronous call (depends on UA) and |
| 107 |
invoke $cb with results. Should not croak. Just a simple wrapper around |
| 108 |
"req" |
| 109 |
|
| 110 |
receive ( $xml, $handler->($methodName,@args) ) : xml byte-stream |
| 111 |
Serverside. Process received XML and invoke $handler with parameters |
| 112 |
$methodName and @args and returns response XML |
| 113 |
|
| 114 |
On error conditions $handler could set $XML::RPC::Fast::faultCode and |
| 115 |
die, or return "rpcfault($faultCode,$faultString)" |
| 116 |
|
| 117 |
->receive( $xml, sub { |
| 118 |
# ... |
| 119 |
return rpcfault( 3, "Some error" ) if $error_condition |
| 120 |
$XML::RPC::Fast::faultCode = 4 and die "Another error" if $another_error_condition; |
| 121 |
|
| 122 |
return { call => $methodname, params => \@params }; |
| 123 |
}) |
| 124 |
|
| 125 |
registerType |
| 126 |
Proxy-method to encoder. See XML::RPC::Enc |
| 127 |
|
| 128 |
registerClass |
| 129 |
Proxy-method to encoder. See XML::RPC::Enc |
| 130 |
|
| 131 |
OPTIONS |
| 132 |
Below is the options, accepted by new() |
| 133 |
|
| 134 |
ua |
| 135 |
Client only. Useragent object, or package name |
| 136 |
|
| 137 |
->new( $url, ua => 'LWP' ) # same as XML::RPC::UA::LWP |
| 138 |
# or |
| 139 |
->new( $url, ua => 'XML::RPC::UA::LWP' ) |
| 140 |
# or |
| 141 |
->new( $url, ua => XML::RPC::UA::LWP->new( ... ) ) |
| 142 |
# or |
| 143 |
->new( $url, ua => XML::RPC::UA::Curl->new( ... ) ) |
| 144 |
|
| 145 |
timeout |
| 146 |
Client only. Timeout for calls. Passed directly to UA |
| 147 |
|
| 148 |
->new( $url, ua => 'LWP', timeout => 10 ) |
| 149 |
|
| 150 |
useragent |
| 151 |
Client only. Useragent string. Passed directly to UA |
| 152 |
|
| 153 |
->new( $url, ua => 'LWP', useragent => 'YourClient/1.11' ) |
| 154 |
|
| 155 |
encoder |
| 156 |
Client and server. Encoder object or package name |
| 157 |
|
| 158 |
->new( $url, encoder => 'LibXML' ) |
| 159 |
# or |
| 160 |
->new( $url, encoder => 'XML::RPC::Enc::LibXML' ) |
| 161 |
# or |
| 162 |
->new( $url, encoder => XML::RPC::Enc::LibXML->new( ... ) ) |
| 163 |
|
| 164 |
internal_encoding NOT IMPLEMENTED YET |
| 165 |
Specify the encoding you are using in your code. By default option is |
| 166 |
undef, which means flagged utf-8 For translations is used Encode, so the |
| 167 |
list of accepted encodings fully derived from it. |
| 168 |
|
| 169 |
external_encoding |
| 170 |
Specify the encoding, used inside XML container. By default it's utf-8. |
| 171 |
Passed directly to encoder |
| 172 |
|
| 173 |
->new( $url, encoder => 'LibXML', external_encoding => 'koi8-r' ) |
| 174 |
|
| 175 |
ACCESSORS |
| 176 |
url |
| 177 |
Get or set client url |
| 178 |
|
| 179 |
encoder |
| 180 |
Direct access to encoder object |
| 181 |
|
| 182 |
ua |
| 183 |
Direct access to useragent object |
| 184 |
|
| 185 |
FUNCTIONS |
| 186 |
rpcfault(faultCode, faultString) |
| 187 |
Returns hash structure, that may be returned by serverside handler, |
| 188 |
instead of die. Not exported by default |
| 189 |
|
| 190 |
CUSTOM TYPES |
| 191 |
sub {{ 'base64' => encode_base64($data) }} |
| 192 |
When passing a CODEREF as a value, encoder will simply use the returned |
| 193 |
hashref as a type => value pair. |
| 194 |
|
| 195 |
bless( do{\(my $o = encode_base64('test') )}, 'base64' ) |
| 196 |
When passing SCALARREF as a value, package name will be taken as type |
| 197 |
and dereference as a value |
| 198 |
|
| 199 |
bless( do{\(my $o = { something =>'complex' } )}, 'base64' ) |
| 200 |
When passing REFREF as a value, package name will be taken as type and |
| 201 |
XML::Hash::LX"::hash2xml(deref)" would be used as value |
| 202 |
|
| 203 |
customtype( $type, $data ) |
| 204 |
Easily compose SCALARREF based custom type |
| 205 |
|
| 206 |
BUGS & SUPPORT |
| 207 |
Bugs reports and testcases are welcome. |
| 208 |
|
| 209 |
It you write your own Enc or UA, I may include it into distribution |
| 210 |
|
| 211 |
If you have propositions for default custom types (see Enc), send me |
| 212 |
patches |
| 213 |
|
| 214 |
See <http://rt.cpan.org> to report and view bugs. |
| 215 |
|
| 216 |
AUTHOR |
| 217 |
Mons Anderson, "<[email protected]>" |
| 218 |
|
| 219 |
COPYRIGHT & LICENSE |
| 220 |
Copyright (c) 2008-2009 Mons Anderson. |
| 221 |
|
| 222 |
This program is free software; you can redistribute it and/or modify it |
| 223 |
under the same terms as Perl itself. |
| 224 |
|