546
edits
UDP API Definition: Difference between revisions
nat and minor stuff
Epoximator (talk | contribs) (nat and minor stuff) |
|||
| Line 1: | Line 1: | ||
{{TOCright}} | {{TOCright}} | ||
'''Author:''' [[User:Exp|Exp]]<br> | '''Author:''' [[User:Exp|Exp]] & [[User:Epoximator|Epoximator]]<br> | ||
'''Version:''' 0.03 - 13.01.2006 <br> | '''Version:''' 0.03 - 13.01.2006 <br> | ||
'''Version number used for protover parameter:''' "3" | '''Version number used for protover parameter:''' "3" | ||
| Line 6: | Line 6: | ||
'''IMPORTANT NOTICE FOR DEVELOPERS:''' | '''IMPORTANT NOTICE FOR DEVELOPERS:''' | ||
* Register _your_ client [http://anidb.info/perl-bin/animedb.pl?show=client here] and post relevant information [[UDP_Clients|here]] '''RIGHT NOW'''. Thanks! | * Register _your_ client [http://anidb.info/perl-bin/animedb.pl?show=client here] and post relevant information [[UDP_Clients|here]] '''RIGHT NOW'''. Thanks! | ||
* If you want to recieve a notification mail every time a new version of the API Specs is released | * If you want to recieve a notification mail every time a new version of the API Specs is released send an email to anidb.udp.api-request@freelists.org with 'subscribe' in the subject field. | ||
* If you have suggestions for improvements or new features use [[UDP_API_DEV]]. | * If you have suggestions for improvements or new features use [[UDP_API_DEV]]. | ||
| Line 30: | Line 30: | ||
=== General === | === General === | ||
The network communication is packet and line based. Each ANIDB API command is exactly one UDP packet containing one line. Results are send as one packet but may consist out of multiple lines. A return value always starts with a 3 byte result code followed by a human redable version of the result code. Be aware that important data fields may be returned directly after the return code (see: 230 code). | |||
The meaning for all result codes can be found in this document. If there is more than one entry returned, it's one entry per line. Lines are terminated by a \n (no dos linefeed \r). The elements of a format string are seperated by a "|" character. | |||
'''Important notes:''' | |||
* All commands except PING requires login, meaning session tag must be set (s=xxxxx). | * All commands except PING requires login, meaning session tag must be set (s=xxxxx). | ||
* Possible return codes for all commands: | * Possible return codes for all commands: | ||
| Line 38: | Line 42: | ||
* Additional return codes for all commands that require login: | * Additional return codes for all commands that require login: | ||
:* 501 LOGIN FIRST | :* 501 LOGIN FIRST | ||
:* 502 ACCESS DENIED | |||
:* 506 INVALID SESSION | :* 506 INVALID SESSION | ||
| Line 87: | Line 92: | ||
=== Local Port === | === Local Port === | ||
A client should select a fixed local port >1024 at install time and reuse it for local UDP Sockets. | A client should select a fixed local port >1024 at install time and reuse it for local UDP Sockets. If the API sees too many different UDP Ports from one IP within ~1 hour it will ban the IP. (So make sure you're reusing your UDP ports also for testing/debuging!) | ||
If the API sees too many different UDP Ports from one IP within ~1 hour it will ban the IP. | |||
(So make sure you're reusing your UDP ports also for testing/debuging!) | |||
The local port may be hardcoded, however, an option to manually specify another port should be offered. | The local port may be hardcoded, however, an option to manually specify another port should be offered. The servername and port should not be hardcoded into a frontend but should be read from a configuration file. | ||
Note when behind a [http://en.wikipedia.org/wiki/Network_address_translation nat] router: | |||
A session between the server and a client is identified by the ip and port used by the client. So when the port (or ip) changes under a session the client has to authenticate again. If a client is behind a nat router it can’t actually control the local port used. The router will normally translate the port to support several computers on a lan. The public port (as seen by the server and set by the router) will change from time to time, usually after a fixed timeout period (like 5 minutes). So if the client wants to keep a session alive it has to ping the server within this period. | |||
The client can decide whether it is behind a router or not by adding ‘nat=1’ to the AUTH command. (This will cause the response to include used ip and port.) | |||
A | |||
If | |||
The | |||
| Line 167: | Line 164: | ||
=== AUTH: Authing to the AnimeDB === | === AUTH: Authing to the AnimeDB === | ||
'''Command String:''' | '''Command String:''' | ||
* AUTH user={str username}&pass={str password}&protover={int4 apiversion}&client={str clientname}&clientver={int4 clientversion} | * AUTH user={str username}&pass={str password}&protover={int4 apiversion}&client={str clientname}&clientver={int4 clientversion}[&nat=1] | ||
'''Possible Replies:''' | '''Possible Replies:''' | ||
| Line 177: | Line 174: | ||
* 505 ILLEGAL INPUT OR ACCESS DENIED | * 505 ILLEGAL INPUT OR ACCESS DENIED | ||
* 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | * 601 ANIDB OUT OF SERVICE - TRY AGAIN LATER | ||
when nat=1 | |||
* 200 {str session_key} {str ip}:{int2 port} LOGIN ACCEPTED | |||
* | * 201 {str session_key} {str ip}:{int2 port} LOGIN ACCEPTED - NEW VERSION AVAILABLE | ||
'''Info:''' | '''Info:''' | ||
| Line 213: | Line 208: | ||
* The user should get a popup message on 503 and 504 messages telling him to update his client software. | * The user should get a popup message on 503 and 504 messages telling him to update his client software. | ||
: (NOTE: 504 means that this version of the client is banned, not the user!) | : (NOTE: 504 means that this version of the client is banned, not the user!) | ||
* The 'nat' option makes the client able to detect whether it is behind a nat router or not. When the client is behind a nat router it should keep the "connection" alive with the PING command. | |||
{{eyecatch|IMPORTANT:| Make sure your client handels ALL possible AUTH return codes before giving out any versions!}} | {{eyecatch|IMPORTANT:| Make sure your client handels ALL possible AUTH return codes before giving out any versions!}} | ||
| Line 643: | Line 639: | ||
* MYLISTADD size={int4 size}&ed2k={str ed2khash}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1] | * MYLISTADD size={int4 size}&ed2k={str ed2khash}[&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1] | ||
by anime + group + epno | by anime + group + epno | ||
* MYLISTADD aname={str anime name}[&gname={str group name}&epno={int4 episode number}][&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1] | * MYLISTADD aname={str anime name}[&gname={str group name}&epno={int4 episode number}][&state={int2 state}&viewed={boolean viewed}&source={str source}&storage={str storage}&other={str other}][&edit=1] | ||
* MYLISTADD aname={str anime name}[&gid={int4 group id}&epno={int4 episode number}][...] | * MYLISTADD aname={str anime name}[&gid={int4 group id}&epno={int4 episode number}][...] | ||
* MYLISTADD aid={int4 anime id}[&gname={str group name}&epno={int4 episode number}][...] | * MYLISTADD aid={int4 anime id}[&gname={str group name}&epno={int4 episode number}][...] | ||