Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::RPC::Fast(3)     User Contributed Perl Documentation    XML::RPC::Fast(3)

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

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

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

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.

perl v5.32.0			  2012-01-25		     XML::RPC::Fast(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | OPTIONS | ACCESSORS | FUNCTIONS | CUSTOM TYPES | BUGS & SUPPORT | AUTHOR | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::RPC::Fast&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help