=head1 Ermyth XMLRPC interface The modules/rpc/xmlrpc module provides an L interface to Ermyth. Ermyth does not use L, 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 EservicenameE EcommandnameE [parameters] where the parameters are separated with semicolons. For an example see contrib/perlxmlrpc.pl. =head2 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: -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 -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