doc/poddoc/xmlrpc.pod

=head1 Ermyth XMLRPC interface

The modules/rpc/xmlrpc module provides an L<XMLRPC|http://www.xmlrpc.com/spec> interface to Ermyth.

Ermyth does not use L<HTTP authentication|http://www.ietf.org/rfc/rfc2617.txt>,
instead using its own system with authentication cookies.

All parameters are strings.

Methods from modules/rpc/xmlrpc:

=head2 ermyth.login

XML Inputs:

=over

=item account name

=item password

=item source ip (optional)

Source ip is logged with the request, it does not need to be an IP address.

=back

XML Outputs

=over

=item fault 1

insufficient parameters

=item fault 3

account is not registered

=item fault 5

invalid username and password

=item fault 6

account is frozen

=item default

success (authcookie)

=back

Side Effects:

=over

=item - an authcookie ticket is created for the myuser_t.

=item - the user's lastlogin is updated

=back

For web interfaces, the resulting authcookie can be stored in a HTTP cookie,
avoiding password storage.

The authcookie will be valid for one hour or until Ermyth shuts down.


=head2 ermyth.logout

XML inputs:

=over

=item authcookie

=item and account name

=back

XML outputs:

=over

=item fault 1

insufficient parameters

=item fault 3

unknown user

=item fault 5

validation failed

=item default

success message

=back

Side Effects:

=over

=item - an authcookie ticket is destroyed.

=back


=head2 ermyth.command

XML inputs:

=over

=item authcookie

=item account name

=item source ip

=item service name

=item command name

=item parameters

=back

XML output depends on command

Side Effects:

=over

=item - command is executed

=back

Authcookie and account name specify authentication for the command; authcookie
can be specified as '.' to execute a command without a login.
Source ip is logged with the request, it does not need to be an IP address.
Service name is the nick of the service.
Command name is the command to be executed. Subcommand names are parameters.
Parameters are specified in the same order as on IRC with mostly one distinct
entity per parameter. Exceptions to this are for example operserv akill (two
parameters), operserv rwatch (one parameter) and nickserv set property (two
parameters in all cases).

Failed commands return an appropriate fault code with the first descriptive
string that would be returned on IRC. Most successful commands return all
descriptive text that would be returned on IRC; some, such as chanserv getkey,
return only a result string.

For experimenting with parameters and results you can use contrib/os_testcmd.
Usage is /os testcmd E<lt>servicenameE<gt> E<lt>commandnameE<gt> [parameters] where the
parameters are separated with semicolons.

For an example see contrib/perlxmlrpc.pl.

=head2 Fault codes:

   0    fault::ok                Operation succeeded. Not used in RPC but internally in Ermyth.
   1    fault::needmoreparams    Not enough parameters
   2    fault::badparams         Parameters invalid somehow
   3    fault::nosuch_source     Source account does not exist
   4    fault::nosuch_target     Target does not exist
   5    fault::authfail          Bad password or authcookie
   6    fault::noprivs           Permission denied (various, but not bad password/authcookie)
   7    fault::nosuch_key        Requested element on target does not exist
   8    fault::alreadyexists     Something conflicting already exists
   9    fault::toomany           Too many of something
   10   fault::emailfail         Sending email failed
   11   fault::notverified       Account not verified
   12   fault::nochange          Object is already in requested state
   13   fault::already_authed    Already logged in
   14   fault::unimplemented     Function not implemented
   15   fault::failed            Other failure.

Negative fault codes are from the XMLRPC library:

   -1   xmlrpc_process() was passed a NULL buffer
   -2   xmlrpc_parse() returned NULL, likely not a XML document
   -3   xmlrpc_method() returned NULL, likely XML document did not contain <methodname>
   -4   findXMLRPCCommand() returned NULL, able to find the method
   -6   method has no registered function
   -7   function returned XMLRPC_STOP
   -8   xmlrpc_set_buffer() was passed a NULL variable
Revision:	1.3
Committed:	Thu Aug 30 19:56:18 2007 UTC (19 years, 1 month ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.2:	+16 -16 lines
Log Message:	- put faultcodes into their own namespace - removed old files - limited header garbage in atheme.h - macros to inline bools for connection_t::is_* - put some connection_t functions into the connection_t class
#	User	Rev	Content
1	pippijn	1.1	=head1 Ermyth XMLRPC interface
2
3			The modules/rpc/xmlrpc module provides an L<XMLRPC\|http://www.xmlrpc.com/spec> interface to Ermyth.
4
5			Ermyth does not use L<HTTP authentication\|http://www.ietf.org/rfc/rfc2617.txt>,
6			instead using its own system with authentication cookies.
7
8			All parameters are strings.
9
10			Methods from modules/rpc/xmlrpc:
11
12			=head2 ermyth.login
13
14			XML Inputs:
15
16			=over
17
18			=item account name
19
20			=item password
21
22			=item source ip (optional)
23
24			Source ip is logged with the request, it does not need to be an IP address.
25
26			=back
27
28			XML Outputs
29
30			=over
31
32			=item fault 1
33
34			insufficient parameters
35
36			=item fault 3
37
38			account is not registered
39
40			=item fault 5
41
42			invalid username and password
43
44			=item fault 6
45
46			account is frozen
47
48			=item default
49
50			success (authcookie)
51
52			=back
53
54			Side Effects:
55
56			=over
57
58			=item - an authcookie ticket is created for the myuser_t.
59
60			=item - the user's lastlogin is updated
61
62			=back
63
64			For web interfaces, the resulting authcookie can be stored in a HTTP cookie,
65			avoiding password storage.
66
67			The authcookie will be valid for one hour or until Ermyth shuts down.
68
69
70			=head2 ermyth.logout
71
72			XML inputs:
73
74			=over
75
76			=item authcookie
77
78			=item and account name
79
80			=back
81
82			XML outputs:
83
84			=over
85
86			=item fault 1
87
88			insufficient parameters
89
90			=item fault 3
91
92			unknown user
93
94			=item fault 5
95
96			validation failed
97
98			=item default
99
100			success message
101
102			=back
103
104			Side Effects:
105
106			=over
107
108			=item - an authcookie ticket is destroyed.
109
110			=back
111
112
113			=head2 ermyth.command
114
115			XML inputs:
116
117			=over
118
119			=item authcookie
120
121			=item account name
122
123			=item source ip
124
125			=item service name
126
127			=item command name
128
129			=item parameters
130
131			=back
132
133			XML output depends on command
134
135			Side Effects:
136
137			=over
138
139			=item - command is executed
140
141			=back
142
143			Authcookie and account name specify authentication for the command; authcookie
144			can be specified as '.' to execute a command without a login.
145			Source ip is logged with the request, it does not need to be an IP address.
146			Service name is the nick of the service.
147			Command name is the command to be executed. Subcommand names are parameters.
148			Parameters are specified in the same order as on IRC with mostly one distinct
149			entity per parameter. Exceptions to this are for example operserv akill (two
150			parameters), operserv rwatch (one parameter) and nickserv set property (two
151			parameters in all cases).
152
153			Failed commands return an appropriate fault code with the first descriptive
154			string that would be returned on IRC. Most successful commands return all
155			descriptive text that would be returned on IRC; some, such as chanserv getkey,
156			return only a result string.
157
158			For experimenting with parameters and results you can use contrib/os_testcmd.
159			Usage is /os testcmd E<lt>servicenameE<gt> E<lt>commandnameE<gt> [parameters] where the
160			parameters are separated with semicolons.
161
162			For an example see contrib/perlxmlrpc.pl.
163
164			=head2 Fault codes:
165
166	pippijn	1.3	0 fault::ok Operation succeeded. Not used in RPC but internally in Ermyth.
167			1 fault::needmoreparams Not enough parameters
168			2 fault::badparams Parameters invalid somehow
169			3 fault::nosuch_source Source account does not exist
170			4 fault::nosuch_target Target does not exist
171			5 fault::authfail Bad password or authcookie
172			6 fault::noprivs Permission denied (various, but not bad password/authcookie)
173			7 fault::nosuch_key Requested element on target does not exist
174			8 fault::alreadyexists Something conflicting already exists
175			9 fault::toomany Too many of something
176			10 fault::emailfail Sending email failed
177			11 fault::notverified Account not verified
178			12 fault::nochange Object is already in requested state
179			13 fault::already_authed Already logged in
180			14 fault::unimplemented Function not implemented
181			15 fault::failed Other failure.
182	pippijn	1.1
183			Negative fault codes are from the XMLRPC library:
184
185			-1 xmlrpc_process() was passed a NULL buffer
186			-2 xmlrpc_parse() returned NULL, likely not a XML document
187			-3 xmlrpc_method() returned NULL, likely XML document did not contain <methodname>
188			-4 findXMLRPCCommand() returned NULL, able to find the method
189			-6 method has no registered function
190			-7 function returned XMLRPC_STOP
191			-8 xmlrpc_set_buffer() was passed a NULL variable