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 (16 years, 9 months 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
#	Content
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	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
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