README
1 $Id: README,v 1.11 2002/08/02 14:54:50 kmacleod Exp $
2
3 Frontier::RPC
4
5 A Perl 5 module for performing Remote Procedure
6 Calls using Extensible Markup Language
7
8
9 Ken MacLeod
10 ken@bitsko.slc.ut.us
11
12 With contributions from
13 Nick Bauman, Laurent Bossavit, Sean Brown, Jon Frisby,
14 Ed Hill, Joe Johnston, Skip Montanaro, Tim Peoples, John Posner,
15 Aaron Ross, Bas Schulte, Marc Singer, and Terry Triplett
16
17INTRODUCTION
18
19 Frontier::RPC implements UserLand Software's XML RPC (Remote
20 Procedure Calls using Extensible Markup Language). Frontier::RPC
21 includes both a client module for making requests to a server and
22 several server modules for implementing servers using CGI, Apache,
23 and standalone with HTTP::Daemon.
24
25 See the file Changes for user-visible changes. See the `examples'
26 directory for an example of using Frontier::RPC. See the
27 ``XML RPC: Home Page'' for more information on XML RPC.
28
29<http://www.xmlrpc.com/>
30
31 Newer versions of this module can be found on CPAN or at
32 <http://perl-xml.sourceforge.net/xml-rpc/>. Questions can be
33 directed to the discussion board on XML-RPC.com or to the XML-RPC
34 mailing list. To join the XML-RPC mailing list visit
35 <http://yahoogroups.com/group/xml-rpc/>.
36
37 Copyright (C) 1998-2002 Ken MacLeod
38 Frontier::RPC is distributed under the same terms as Perl.
39
40OVERVIEW
41
42 RPC client connections are made by creating instances of
43 Frontier::Client objects that record the server name, and then
44 issuing `call' requests that send a method name and parameters to
45 the server.
46
47 RPC daemons are mini-HTTP servers (using HTTP::Daemon from the
48 `libwww' Perl module). Daemons are created by first defining the
49 procedures you want to make available to RPC and then passing a
50 list of those procedures as you create the Frontier::Daemon
51 object.
52
53 The Frontier::RPC2 module implements the encoding and decoding of
54 XML RPC requests using the XML::Parser Perl module.
55
56 Apache::XMLRPC serves XML-RPC requests from Apache's mod_perl.
57 Frontier::Responder serves XML-RPC requests as a CGI script.
58
59QUICK USAGE GUIDE
60
61 Frontier::RPC converts between XML-RPC <struct>s and Perl hashes,
62 <array>s and Perl arrays, and all others XML-RPC types to Perl
63 scalars.
64
65 To call an RPC server, use Frontier::Client:
66
67 use Frontier::Client;
68
69 $server = Frontier::Client->new(url => $url);
70
71 $result = $server->call($method, @args);
72
73 $url is the URL of the XML-RPC server, like
74 `http://betty.userland.com/RPC2', $method is the XML-RPC procedure
75 name to call, and @args is a list of hashes, arrays, or scalars to
76 pass to the procedure. See `examples/states-client.pl' for an
77 example of an XML-RPC client.
78
79 To create an XML-RPC server, use Frontier::Daemon.
80 Frontier::Daemon is a subclass of HTTP::Daemon, so takes all the
81 options that HTTP::Daemon takes for setting up a server, such as
82 the port number. In addition, Frontier::Daemon takes a `methods'
83 option that is a hash containing the RPC procedure names and
84 references to Perl subroutines:
85
86 use Frontier::Daemon;
87
88 Frontier::Daemon->new(methods => {
89 'rpcName' => &sub_name,
90 });
91
92 The subroutines get called with the XML-RPC parameters as hashes,
93 arrays, and scalars. See `examples/states-daemon.pl' for an
94 example of an XML-RPC server.
95
96INSTALLATION
97
98 Frontier::RPC requires the following Perl modules from CPAN, if
99 not already included in your installed Perl:
100
101<http://www.perl.com/CPAN/modules/by-module/>
102
103 Data-Dumper (in the Data directory)
104 MIME-Base64 (in the MIME directory)
105 MD5 (in the MD5 directory)
106 HTML-Tagset (in the HTML directory)
107 HTML-Parser (in the HTML directory)
108 URI (in the URI directory)
109 libnet (in the Net directory)
110 libwww-perl (in the HTTP directory)
111 XML-Parser (in the XML directory)
112
113 Frontier::RPC installs as a standard Perl module
114
115 perl Makefile.PL
116 make
117 make test
118 make install
119