GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
XML::RPC::Fast(3) User Contributed Perl Documentation XML::RPC::Fast(3)

XML::RPC::Fast - Fast and modular implementation for an XML-RPC client and server

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 $/; <STDIN> };
    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(
        'http://your.hostname/rpc/url'
    );
    
    # 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 } );

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

Create XML::RPC::Fast object, server if url is undef, client if url is defined

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

Clientside. Make syncronous call and return results. Croaks on error. Just a simple wrapper around "req"

Clientside. Make syncronous or asyncronous call (depends on UA) and invoke $cb with results. Should not croak. Just a simple wrapper around "req"

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 };
    })

Proxy-method to encoder. See XML::RPC::Enc

Proxy-method to encoder. See XML::RPC::Enc

Below is the options, accepted by new()

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( ... ) )

Client only. Timeout for calls. Passed directly to UA 

    ->new( $url, ua => 'LWP', timeout => 10 )

Client only. Useragent string. Passed directly to UA 

    ->new( $url, ua => 'LWP', useragent => 'YourClient/1.11' )

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( ... ) )

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.

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' )

Get or set client url

Direct access to encoder object

Direct access to useragent object

Returns hash structure, that may be returned by serverside handler, instead of die. Not exported by default

When passing a CODEREF as a value, encoder will simply use the returned hashref as a type => value pair.

When passing SCALARREF as a value, package name will be taken as type and dereference as a value

When passing REFREF as a value, package name will be taken as type and XML::Hash::LX"::hash2xml(deref)" would be used as value

Easily compose SCALARREF based custom type

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 <http://rt.cpan.org> to report and view bugs.

Mons Anderson, "<mons@cpan.org>"

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.

2012-01-25 perl v5.32.1
Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.