Dedimania Server Help Page

Site & Statistics:

Usage:

How to send a query ?

The query is a standard http text/xml call, with the xml message as the http body. This form is the standard xmlrpc calling form, and the reply will have that form too, and should be preferred.

The query can also be a standard http text/html call, with the attribute 'xmlrpc'. This was added to permit easy requests using a standard html GET or POST query:

The value for the 'xmlrpc' attribute is just a xmlrpc text, urlsafe base64 encoded.
The method can be either GET or POST.
The reply is just plain xmlrpc.

A real (GET) call would look like this:
http://dedimania.net/RPC4/server.php?xmlrpc=<urlsafe_base64_encoded_xmlrpc_text>
In the case of a GET query, the xmlrpc value has to be base64 encoded, but be cautious: it has to use the url-safe base64 RFC 3548 ('+' replaced by '-' and '/' replaced by '_'), and the URI size can be limited.

In all cases, the query and the reply can be compressed (gzip or deflate), using the standard http headers.
The form of xmlrpc queries and replies

The xmlrpc query and result fully respect the xml-rpc specification.
It is better if client support cookies and keep-alive connections, avoiding to make a new connection for each request, which is better both for server and client. The server support long keep-alive (more than 5min), so the client really should support it too, to help reduce the server load !

What kind of records does Dedimania support ?

Rounds: round final time. And for a multilap challenge only if the number of laps is the main number of laps of the map, and not a different number forced using RoundForcedLaps !
Time attack: attempt final time.
Laps: lap time (ie best lap time). Is merged with Time Attack records.
Stunts: attempt final score (actually not supported).
Cup: round final time. Is merged with Rounds records.

What kind of records does Dedimania not support ?

Rounds: multilap challenge with the number of laps different than the main number of laps of the map (mainly using RoundForcedLaps) is not supported ! (eventually the script can send best lap as a Laps record)
Laps: more than one lap is not supported.
Stunts: actually not supported.

Sending xmlrpc request methods

It is mandatory to put the 'dedimania.Authenticate' in your query before any other method which is indicated as 'Only if authenticated.'. Because of this, you have to use system.multicall in most cases.
In dedimania.Authenticate you can send the community code of the server login, instead of the password. After the first successful authentication with Nadeo masters, an MD5 of the password is stored, to make further authentications faster.
Mainly, the standard usage of requests methods for a script using Dedimania records is:
dedimania.CurrentChallenge at beginning of map (to indicate the current map, players, and get current records),
dedimania.UpdateServerPlayers every 4 minutes after the beginning of the map (to keep up to date server and players infos),
dedimania.ChallengeRaceTimes at the end of map (sending all players best time -new records or not-, and get the new records list),
dedimania.PlayerArrive when a player connects,
dedimania.PlayerLeave when a player disconnects.
dedimania.CheckConnection and dedimania.GetVersion can be used to verify that your script requests are received correctly and understood by the Dedimania server, and that your script receives and understands the reply.
dedimania.WarningsAndTTR can be used as last method of the request, to get warnings/errors (and some other infos) about previous methods.

Raw query/reply examples (without http compression)

Dedimania protocol raw examples

Note:
If you make a client script support, please notify it to Slig. First because I may open a new url port for your script, and also because some changes should come to increase the reliability of records, and I need a way to contact you if needed. Thanks.

Available methods:

dedimania.CheckConnection

boolean dedimania.CheckConnection()
Just reply true.

dedimania.GetVersion

struct dedimania.GetVersion()
Reply a struct {'Version': int, 'MaxRecords': int}.

dedimania.Authenticate

boolean dedimania.Authenticate(struct)
Allow user authentication by specifying a struct {'Game': string, 'Login': string, 'Password': string, 'Tool': string, 'Version': string, [Optionals: 'Packmask': string, 'Nation': string, 'ServerIP': string, 'ServerPort': int, 'XmlrpcPort': int]}. Game can be 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'. Nation can be 3 letters nation or TMF Path.

dedimania.ValidateAccount

struct dedimania.ValidateAccount()
Reply a struct {'Status': boolean, 'Messages': array of struct {'Date': string, 'Text': string} }. Status is always true, else you get a not authenticated error.
Only if authenticated.

dedimania.PlayerArrive

struct dedimania.PlayerArrive(string, string, string, string, string, int, boolean, boolean)
Announce that a new player has arrived. Arguments are (Game, Login, Nickname, Nation, TeamName, LadderRanking, IsSpec, IsOff). Game can be 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'.
Reply a struct {'Login': string, 'TeamName': string, 'Nation': string, 'Options': array of struct {'Option': string, 'Value': string, 'Tool': string}, 'Aliases': array of struct {'Alias': string, 'Text': string, 'Tool': string} }.
Only if authenticated.

dedimania.PlayerLeave

struct dedimania.PlayerLeave(string, string)
Announce that a player has left. Arguments are (Game,Login). Game can be 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'.
Reply a struct {'Login': string}.
Only if authenticated.

dedimania.CurrentChallenge

struct dedimania.CurrentChallenge(string, string, string, string, string, int, struct, int, array)
Set current challenge info and get records. Arguments are (Uid, Name, Environment, Author, Game, Mode, SrvInfo, MaxGetTimes, Players). Game is currently 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'. SrvInfo is a struct {'SrvName': string, 'Comment': string, 'Private': boolean, 'SrvIP': string, 'SrvPort': int, 'XmlrpcPort': int, 'NumPlayers': int, 'MaxPlayers': int, 'NumSpecs': int, 'MaxSpecs': int, 'LadderMode': int, 'NextFiveUID': string of next five uid separated with '/'}. Players is an array of struct {'Login': string, 'Nation': string, 'TeamName': string, 'TeamId': int, 'IsSpec': boolean, 'Ranking': int, 'IsOff': boolean}.
Reply a struct {'Uid': string, 'TotalRaces': int, 'TotalPlayers': int, 'TimeAttackRaces': int, 'TimeAttackPlayers': int, 'NumberOfChecks': int, 'ServerMaxRecords': int, 'Records': array of struct {'Login': string, 'NickName': string, 'Best': int, 'Rank': int, 'Checks': array of int, 'Vote': int} }, NumberOfChecks per lap is 0 if unknown, Checks are the bestchecks of the associated record, Vote is 0 to 100 value, or -1 if player did not vote for the map.
Only if authenticated.

dedimania.ChallengeRaceTimes

struct dedimania.ChallengeRaceTimes(string, string, string, string, string, int, int, int, array)
Set current challenge info and players' best times, and get the updated records. Arguments are (Uid, Name, Environment, Author, Game, Mode, NumberOfChecks, MaxGetTimes, Times). Game is currently 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'. Times is a sorted (by 'Best') array of struct {'Login': string, 'Best': int, 'Checks': array of int}. Checks are BestCheckpoints array of the best time of player.
Reply a struct {'Uid': string, 'TotalRaces': int, 'TotalPlayers': int, 'TimeAttackRaces': int, 'TimeAttackPlayers': int, 'NumberOfChecks': int, 'ServerMaxRecords': int, 'Records': array of struct {'Login': string, 'NickName': string, 'Best': int, 'Rank': int, 'Checks': array of int, 'NewBest': boolean} }, NumberOfChecks per lap is 0 if unknown.
Only if authenticated.

dedimania.UpdateServerPlayers

boolean dedimania.UpdateServerPlayers(string, int, struct, array)
Set current challenge and players info. Arguments are (Game, Mode, SrvInfo, Players). Game is currently 'TMF', 'TMUF', 'TMNF', 'TMU', 'TMO', 'TMS' or 'TMN'. SrvInfo is a struct {'SrvName': string, 'Comment': string, 'Private': boolean, 'SrvIP': string, 'SrvPort': int, 'XmlrpcPort': int, 'NumPlayers': int, 'MaxPlayers': int, 'NumSpecs': int, 'MaxSpecs': int, 'LadderMode': boolean, 'NextFiveUID': string of next five uid separated with '/'}. Players is an array of struct {'Login': string, 'Nation': string, 'TeamName': string, 'TeamId': int, 'IsSpec': boolean, 'Ranking': int, 'IsOff': boolean}.
Reply true. Should be used every 4 minutes if no 'dedimania.CurrentChallenge' or 'dedimania.ChallengeRaceTimes' has been called, to keep the server and players 'On'.
Only if authenticated.

dedimania.WarningsAndTTR

struct dedimania.WarningsAndTTR()
Get warnings messages and TimeToRespond for all previous methods.
Reply a struct {'globalTTR': int, 'methods': array of struct {'methodName': string, 'errors': string, 'TTR': int}}.

system.listMethods

array system.listMethods()
This method lists all the methods that the XML-RPC server knows how to dispatch.

system.methodHelp

string system.methodHelp(string)
Returns help text if defined for the method passed, otherwise returns an empty string.

system.methodSignature

array system.methodSignature(string)
Returns an array of known signatures (an array of arrays) for the method name passed. If no signatures are known, returns a none-array (test for type != array to detect missing signature).

system.multicall

array system.multicall(array)
Boxcar multiple RPC calls in one request. See http://www.xmlrpc.com/discuss/msgReader$1208 and raw examples for details. Each array entry is a struct {'methodCall':string, 'params':array}.