Dedimania forum

FAQ about old (ie TMO/TMS/TMN/TMF) Dedimania API

Replying to some questions, i thought that it could make a good start for a FAQ, so here it is ! 

about any 2 minutes it makes an UpdateServerPlayers and on launch of the next race the next CurrentChallenge...

4 minutes is enough, 3 minutes is ok, less is unusefull and increase the number of requests (remember that there are nearly 2000 servers/scripts connected actually). The tmstats page consider > 300s (ie 5 min) before showing the server as off.

1) packmask: same settings than in orig serverconfig? are things like "Stadium,Rally,Island" allowed or empty if more than 1?

No, you should send the GetServerPackMask value 

2) CurrentChallenge
In the CurrentChallenge-part there is the Field "NextFiveUID".

Do your best, or leave it blank. It was asked by Vegeta who made the main dedimania site at beginning. Personnally i don't really care.

3) Nearly any send is followed by a WarningsAndTTR at moment for debugging - should i remove them for performance later or arent they a problem?

Keep it, there is no performance issue on dedimania side with it, and it is very small (except when there is a problem ^^).
It can help users to understand problems if they have it in your script log.

4) PlayerArrive
ON scriptstart - should the script make a playerarrive for any player in that moment or is it ok to make it at ChallengeRaceTimes?

You can skip PlayerArrive call, all datas are also in dedimania.CurrentChallenge and dedimania.UpdateServerPlayers. You can also group several of them one query rather than making a request for each player individually.

In the future (soon), perhaps that the api changes will add some more infos returned by this method, then it's possible that you will have more interest to use it.

5) Playerleave
Dont think that there are limitations for u - but: if a player drives a time, and leaves the server than before trackend (playerleave is sendet) should that time be submitted also? atm it is skipped

You can send its time after he has leaved, it's not a problem at all.
You can skip Playerleave call, it's not a problem.

6) Empty Server
What to do if Server is empty - no players at all? i'm skipping ChallengeRaceTimes atm if no useable time is collected, but CurrentChallenge? If no Player is there it makes errors, if a clear player is inserted also, skip it also? but thought it is needed on your side? (Warning in method_helper.php(830): update failed for player TMU: : not found) -> i know that its wrong but what to do in that moment? skip it? or should i deactivate dedimaniamodul till a player arrives? but then its something like "offline" on your side?

You can skip ChallengeRaceTimes. Personally i send UpdateServerPlayers every 3 minutes after CurrentChallenge, so CurrentChallenge is not really more than a UpdateServerPlayers for an empty server.
You should continue to send it, so your server is visible alive on tmstats.

About the error with an empty player list, it is strange. You give an empty array ?  Btw i will check it, it should not make an error.

7) warnings
WarningsAndTTR is delivering different answers very often - maybe
Warning in method_helper.php(1160): Number of checkpoints for map xxxxx set to : 7
Error: Warning in method_helper.php(1070): Ignore record for noram : checkpoints times are mandatory for TMUF/TMNF servers !
both are clear and only for example now - but can i say if there is no "Error" at begin that its accepted? i know the first isnt an "error" like this than more an info...

sadly xmlrpc give no nice way to handle other thing that pure error (without returning any other thing). I did not add warning/info levels, so yes infos, warnings and errors are melt  :?
I will try to put a 'INFO:' at begining of info messages...

8 ) replays
havent done anything in that way till now - but if i understand right u arent finish in that part also? or are there examples or something available?

new api should come soon (most will stay the same, some args added, some responses completed)

9) encoding - my only real problem atm
Most infos i have from http://dedimania.com/RPC4/server.php, some things from forums and soon... maybe its easiest to give u an example-send:

Code:

POST /Dedimania HTTP/1.1
User-Agent: TM-DeReCo-RPC TM-DeReCo
Host: dedimania.net:8004
Accept-Charset: UTF-8,ISO-8859-1,US-ASCII
Content-Type: text/xml; charset=UTF-8
Content-Length: 2445
Keep-Alive: timeout=600, max=2000
Connection: Keep-Alive

<?xml version="1.0" encoding="UTF-8" ?><methodCall><methodName>system.multicall</methodName><params><param><value><array><data><value><struct>
<member><name>methodName</name><value><string>dedimania.Authenticate</string></value>
</member><member><name>params</name><value><array><data>
<value><struct>
<member><name>Game</name><value><string>TMUF</string></value>
</member><member><name>Login</name><value><string>Havoc-Server2</string></value>
</member><member><name>Password</name><value><int>xxxxxxxx</int></value>
</member><member><name>Tool</name><value><string>TM-DeReCo</string></value>
</member><member><name>Version</name><value><string>1.1c</string></value>
</member><member><name>Packmask</name><value><string>Island</string></value>
</member><member><name>Nation</name><value><string>World|Germany|North Rhine-Westphalia|Dortmund</string></value>
</member><member><name>ServerIP</name><value><string>xxxxxxxx</string></value>
</member><member><name>ServerPort</name><value><int>xxxxxxxx</int></value>
</member><member><name>XmlrpcPort</name><value><int>xxxxxxxx</int></value>
</member></struct></value>
</data></array></value>
</member></struct></value>
<value><struct>
<member><name>methodName</name><value><string>dedimania.ChallengeRaceTimes</string></value>
</member><member><name>params</name><value><array><data>
<value><string>HOL6jglqA5NBP0nldmrXd9735Lg</string></value>
<value><string>Sun is Raceing</string></value>
<value><string>Island</string></value>
<value><string>stadler</string></value>
<value><string>TMUF</string></value>
<value><int>1</int></value>
<value><int>8</int></value>
<value><int>30</int></value>
<value><array><data>
<value><struct>
<member><name>Login</name><value><string>speedy64</string></value>
</member><member><name>Best</name><value><int>62720</int></value>
</member><member><name>Checks</name><value><array><data>
<value><int>13920</int></value>
<value><int>18630</int></value>
<value><int>26160</int></value>
<value><int>34990</int></value>
<value><int>41550</int></value>
<value><int>47900</int></value>
<value><int>50250</int></value>
<value><int>62720</int></value>
</data></array></value>
</member></struct></value>
</data></array></value>
</data></array></value>
</member></struct></value>
<value><struct>
<member><name>methodName</name><value><string>dedimania.WarningsAndTTR</string></value>
</member></struct></value>
</data></array></value></param></params></methodCall>

(In newest version i have changed checks to a string like <member><name>Checks</name><value><string>5420,8490,11790,26080,29790,45760,49380</string></value></member> as seen in forum that its accepted also )

This is a ChallengeRaceTimes without any errors at end with 2 players (1 with score). (password cleared here)
On that Track it isnt a Problem - but sometimes there are (off course) "bad" tracknames,... which encoding should be used?

Most time it is because "many" nicknames and mapnames have bad utf8 in it (which can also be a problem with manialinks).
If you use a real utf8 filter on names, you should not have problems any more.

dedimania use the parse() method of a new IXR_Message (from GbxRemote.inc.php), so if it fails to decode the sent xmlrpc, i can't do anything with the data...

10) in your RPC4/server.php u write "The value for the 'xmlrpc' attribute is just a xmlrpc text, urlsafe base64 encoded." didnt understand it clearly

You are using a real http/xmlrpc request, so you don't care about this.
It was an alternative to permit to use standard html GET or POST.

11) one track i know that makes trouble is for example "On & On" by Kev_Fan, the "&" is in plaintext a problem, but which encoding should be used and for what parts of the sending?  all or only the strings for it own or ...?

If you are using a xmlrpc encoder (like the one included in GbxRemote.inc.php), then you don't have to care about it.  If you build it yourself then yes, of course, all datas must be xml compliant, and so strings have to be encoded using htmlspecialchars() or equivalent.

12) what about requests/responses compression ?

Dedimania handle standards http compressions : deflate and gzip, and it's responses http headers indicate them.
Both deflate and gzip are accepted to receive and send datas.

Compression should really be use !  xmlrpc use lot of clear text, and such text is dramatically reduced in size using compression. So using compression really save lot of bandwidth !

13) what about http keepalive ?

It is highly recommended to handle correctly the http keepalive (with long timeout) on the client side, especially if your script is widely used !   It avoid to make a new connection for each request, which use less resources on server side, and avoid connection timeouts on the client script side.

14) what about http cookies ?

It is better if your client support cookies, btw it is actually not a real problem to not support it.

15) what url/ports should be used by scripts to send requests to Dedimania ?

You have to use the url/ports indicated for your script (or script family) in this post. For those which can use several ports, choose one randomly at startup of the script, then continue on it. If you use keepalive then of course the idea to change the url/port should not come in your mind as you keep the same connection opened...

http://dedimania.net/RPC4/server.php should not be used except eventually for the initial dedimania.Authenticate, when the login/pass is unsure.

16) dedimania.Authenticate login

Only the real login of the dedicated on which the client script is connected should be used. You can authentify using the password or the community code, both should work.

Note: please, make your script disable its calls to Dedimania if the login/pass has not be configured, ie if they are the default ones that you have set in your default config. Testing stupid wrong login/pass for nothing make dedimania loose time and resources for nothing.

17) Dedimania and UTF-8

Dedimania accept the same utf-8 chars as the dedicated server. See this post.
In many cases the xmlrpc decoder will fail if the client send wrong utf-8 chars, ie if the builtin php5 xml_parser_create('UTF-8') fail to parse the received data (this parser is used by GbxRemote, which is used by Dedimania to decode xmlrpc requests and encode xmlrpc responses).