[ViewVC] Contents of: cvs/ermyth/doc/XMLRPC

Atheme XMLRPC interface
-----------------------

The modules/xmlrpc/* modules provide an XMLRPC interface to Atheme.

Atheme does not use HTTP authentication, instead using its own system with
authentication cookies.

All parameters are strings.

Methods from modules/xmlrpc/main:

/*
 * atheme.login
 *
 * XML Inputs:
 *       account name, password, source ip (optional)
 *
 * XML Outputs:
 *       fault 1 - insufficient parameters
 *       fault 3 - account is not registered
 *       fault 5 - invalid username and password
 *       fault 6 - account is frozen
 *       default - success (authcookie)
 *
 * Side Effects:
 *       an authcookie ticket is created for the myuser_t.
 *       the user's lastlogin is updated
 */

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

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 Atheme shuts down.

/*
 * atheme.logout
 *
 * XML inputs:
 *       authcookie, and account name.
 *
 * XML outputs:
 *       fault 1 - insufficient parameters
 *       fault 3 - unknown user
 *       fault 5 - validation failed
 *       default - success message
 *
 * Side Effects:
 *       an authcookie ticket is destroyed.
 */

/*
 * atheme.command
 *
 * XML inputs:
 *       authcookie, account name, source ip, service name, command name,
 *       parameters.
 *
 * XML outputs:
 *       depends on command
 *
 * Side Effects:
 *       command is executed
 */

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 <servicename> <commandname> [parameters] where the
parameters are separated with semicolons.

For an example see contrib/perlxmlrpc.pl.

Other methods:

See the source code, modules/xmlrpc/*.c.

Fault codes:

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

Negative fault codes are from the XMLRPC library, see also doc/XMLRPCLIB:
-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.2
Committed:	Thu Jul 19 12:35:04 2007 UTC (16 years, 10 months ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+0 -0 lines
State:	*FILE REMOVED*
Log Message:	convert documentation to POD and use this for the website
#	Content
1	Atheme XMLRPC interface
2	-----------------------
3
4	The modules/xmlrpc/* modules provide an XMLRPC interface to Atheme.
5
6	Atheme does not use HTTP authentication, instead using its own system with
7	authentication cookies.
8
9	All parameters are strings.
10
11	Methods from modules/xmlrpc/main:
12
13	/*
14	* atheme.login
15	*
16	* XML Inputs:
17	* account name, password, source ip (optional)
18	*
19	* XML Outputs:
20	* fault 1 - insufficient parameters
21	* fault 3 - account is not registered
22	* fault 5 - invalid username and password
23	* fault 6 - account is frozen
24	* default - success (authcookie)
25	*
26	* Side Effects:
27	* an authcookie ticket is created for the myuser_t.
28	* the user's lastlogin is updated
29	*/
30
31	Source ip is logged with the request, it does not need to be an IP address.
32
33	For web interfaces, the resulting authcookie can be stored in a HTTP cookie,
34	avoiding password storage.
35
36	The authcookie will be valid for one hour or until Atheme shuts down.
37
38	/*
39	* atheme.logout
40	*
41	* XML inputs:
42	* authcookie, and account name.
43	*
44	* XML outputs:
45	* fault 1 - insufficient parameters
46	* fault 3 - unknown user
47	* fault 5 - validation failed
48	* default - success message
49	*
50	* Side Effects:
51	* an authcookie ticket is destroyed.
52	*/
53
54	/*
55	* atheme.command
56	*
57	* XML inputs:
58	* authcookie, account name, source ip, service name, command name,
59	* parameters.
60	*
61	* XML outputs:
62	* depends on command
63	*
64	* Side Effects:
65	* command is executed
66	*/
67
68	Authcookie and account name specify authentication for the command; authcookie
69	can be specified as '.' to execute a command without a login.
70	Source ip is logged with the request, it does not need to be an IP address.
71	Service name is the nick of the service.
72	Command name is the command to be executed. Subcommand names are parameters.
73	Parameters are specified in the same order as on IRC with mostly one distinct
74	entity per parameter. Exceptions to this are for example operserv akill (two
75	parameters), operserv rwatch (one parameter) and nickserv set property (two
76	parameters in all cases).
77
78	Failed commands return an appropriate fault code with the first descriptive
79	string that would be returned on IRC. Most successful commands return all
80	descriptive text that would be returned on IRC; some, such as chanserv getkey,
81	return only a result string.
82
83	For experimenting with parameters and results you can use contrib/os_testcmd.
84	Usage is /os testcmd <servicename> <commandname> [parameters] where the
85	parameters are separated with semicolons.
86
87	For an example see contrib/perlxmlrpc.pl.
88
89	Other methods:
90
91	See the source code, modules/xmlrpc/*.c.
92
93	Fault codes:
94
95	1 : fault_needmoreparams. Not enough parameters
96	2 : fault_badparams. Parameters invalid somehow
97	3 : fault_nosuch_source. Source account does not exist
98	4 : fault_nosuch_target. Target does not exist
99	5 : fault_authfail. Bad password or authcookie
100	6 : fault_noprivs. Permission denied (various, but not bad password/authcookie)
101	7 : fault_nosuch_key. Requested element on target does not exist
102	8 : fault_alreadyexists. Something conflicting already exists
103	9 : fault_toomany. Too many of something
104	10 : fault_emailfail. Sending email failed
105	11 : fault_notverified. Account not verified
106	12 : fault_nochange. Object is already in requested state
107	13 : fault_already_authed. Already logged in
108	14 : fault_unimplemented. Function not implemented
109
110	Negative fault codes are from the XMLRPC library, see also doc/XMLRPCLIB:
111	-1 : xmlrpc_process() was passed a NULL buffer
112	-2 : xmlrpc_parse() returned NULL, likely not a XML document
113	-3 : xmlrpc_method() returned NULL, likely XML document did not contain <methodname>
114	-4 : findXMLRPCCommand() returned NULL, able to find the method
115	-6 : method has no registered function
116	-7 : function returned XMLRPC_STOP
117	-8 : xmlrpc_set_buffer() was passed a NULL variable