1,633
edits
UDP API Definition: Difference between revisions
m
no edit summary
mNo edit summary |
|||
| Line 90: | Line 90: | ||
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. | ||
'''Note when behind a [[Wikipedia:Network address translation|NAT]]/masquerading router:'''<br | '''Note when behind a [[Wikipedia:Network address translation|NAT]]/masquerading router:'''<br> | ||
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 within 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 for the connection. The router will normally ''translate'' the port to support several computers on a LAN to share the Internet connection. The public port (as determined by the router and seen by the server) which has been assigned to the connection will only be reserved for as long as it is in use. This means that the router will usually ''deallocate the port after a fixed timeout period'' (i.e. 5, 10 or 15 minutes). Once that happens the client will no longer be able to receive UDP messages from the server (the messages will be discarded as undeliverable by the router) and a new port will be selected once the client tries to send a message to the server (which will result in a new connection session - | 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 within 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 for the connection. The router will normally ''translate'' the port to support several computers on a LAN to share the Internet connection. The public port (as determined by the router and seen by the server) which has been assigned to the connection will only be reserved for as long as it is in use. This means that the router will usually ''deallocate the port after a fixed timeout period'' (i.e. 5, 10 or 15 minutes). Once that happens the client will no longer be able to receive UDP messages from the server (the messages will be discarded as undeliverable by the router) and a new port will be selected once the client tries to send a message to the server (which will result in a new connection session - '''Note:''' This could get you banned!, see above). So in order to keep a session over a NAT router alive, the client has to ping the server within this period to prevent a timeout. | ||
The client can decide whether it is behind a NAT router or not by adding <tt>nat=1</tt> to the AUTH command. This will cause the response to include the ip and port as seen by the server. If the port differs from the port reported by the local socket, the connection subject to NAT and the client should issue PING commands in regular intervals. Please do not send pings more often then once every 5 minutes and only on connections via NAT routers or if the user has explicitly enabled regular keepalive pings via a configuration setting (default setting should be OFF). | The client can decide whether it is behind a NAT router or not by adding <tt>nat=1</tt> to the AUTH command. This will cause the response to include the ip and port as seen by the server. If the port differs from the port reported by the local socket, the connection subject to NAT and the client should issue PING commands in regular intervals. Please do not send pings more often then once every 5 minutes and only on connections via NAT routers or if the user has explicitly enabled regular keepalive pings via a configuration setting (default setting should be OFF). | ||
| Line 201: | Line 201: | ||
: This means a new version of the client is available, however the old version is still supported otherwise a client banned message would have been returned. | : This means a new version of the client is available, however the old version is still supported otherwise a client banned message would have been returned. | ||
* The user should get a pop-up message on 503 and 504 messages telling him to update his client software. | * The user should get a pop-up 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!) | ||
* 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. | * 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 handles ALL possible AUTH return codes before giving out any versions!}} | {{eyecatch|Important|Make sure your client handles ALL possible AUTH return codes before giving out any versions!}} | ||
| Line 224: | Line 224: | ||
'''Info:''' | '''Info:''' | ||
* This command only works if you are already logged in. | * This command only works if you are already logged in. | ||
* A logout should ALWAYS be issued if the client is currently logged in and is either exiting or not expecting to send/receive any | * A logout should ALWAYS be issued if the client is currently logged in and is either exiting or not expecting to send/receive any AniDB API packets for the next >= 30 minutes. | ||
---- | ---- | ||
| Line 554: | Line 554: | ||
* Category fields are separated with ',' and ordered by weight (desc). | * Category fields are separated with ',' and ordered by weight (desc). | ||
* By name: must be perfect match of romaji/kanji/english/other/synonym/short name. | * By name: must be perfect match of romaji/kanji/english/other/synonym/short name. | ||
* | * '''Note:''' The category list is the first data to be truncated if needed. And then: synonym list, short name list. This applies to the FILE command too. | ||
* Selecting an 'unused' or 'reserved' bit will return an "illegal input" (505) response. | * Selecting an 'unused' or 'reserved' bit will return an "illegal input" (505) response. | ||
| Line 850: | Line 850: | ||
* Multiple calls to ANIMEDESC may be necessary to retrieve the complete text, retrieving separate 1400 byte parts with each call | * Multiple calls to ANIMEDESC may be necessary to retrieve the complete text, retrieving separate 1400 byte parts with each call | ||
* ''part'' is zero-based | * ''part'' is zero-based | ||
* Note: No support, at present, for retrieving descriptions by title. ''aid'' only | * '''Note:''' No support, at present, for retrieving descriptions by title. ''aid'' only | ||
| Line 918: | Line 918: | ||
<pre> | <pre> | ||
bit / int value meaning | bit / int value meaning | ||
1 / 1 FILE_CRCOK: file matched official CRC (displayed with green background in | 1 / 1 FILE_CRCOK: file matched official CRC (displayed with green background in AniDB) | ||
2 / 2 FILE_CRCERR: file DID NOT match official CRC (displayed with red background in | 2 / 2 FILE_CRCERR: file DID NOT match official CRC (displayed with red background in AniDB) | ||
3 / 4 FILE_ISV2: file is version 2 | 3 / 4 FILE_ISV2: file is version 2 | ||
4 / 8 FILE_ISV3: file is version 3 | 4 / 8 FILE_ISV3: file is version 3 | ||
| Line 1,403: | Line 1,403: | ||
* ''state'' values: 1=ongoing, 2=stalled, 3=complete, 4=dropped, 5=finished, 6=specials_only | * ''state'' values: 1=ongoing, 2=stalled, 3=complete, 4=dropped, 5=finished, 6=specials_only | ||
== | == MyList Commands == | ||
=== MYLIST: Retrieve | === MYLIST: Retrieve MyList Data === | ||
'''Command String:'''<br> | '''Command String:'''<br> | ||
by lid: (mylist id) | by lid: (mylist id) | ||
| Line 1,436: | Line 1,436: | ||
3 - deleted - the file has been deleted or is not available for other reasons (i.e. reencoded) | 3 - deleted - the file has been deleted or is not available for other reasons (i.e. reencoded) | ||
'''Filestates:''' (for normal files, | '''Filestates:''' (for normal files, i.e. not generic) | ||
0 => normal/original | 0 => normal/original | ||
1 => corrupted version/invalid crc | 1 => corrupted version/invalid crc | ||
| Line 1,454: | Line 1,454: | ||
---- | ---- | ||
=== MYLISTADD: Add file to | === MYLISTADD: Add file to MyList === | ||
The command string for MYLISTADD is made of up two blocks: a 'fileinfo' block, which limits the command to a specific file, or an 'animeinfo'/'groupinfo'/'episodeinfo' block, which can be used to specify a range of files, including generics. Additionally, a number of optional parameters can be included with either set. | The command string for MYLISTADD is made of up two blocks: a 'fileinfo' block, which limits the command to a specific file, or an 'animeinfo'/'groupinfo'/'episodeinfo' block, which can be used to specify a range of files, including generics. Additionally, a number of optional parameters can be included with either set. | ||
| Line 1,522: | Line 1,522: | ||
---- | ---- | ||
=== MYLISTDEL: Remove file from | === MYLISTDEL: Remove file from MyList === | ||
'''Command String:'''<br> | '''Command String:'''<br> | ||
by lid: (mylist id) | by lid: (mylist id) | ||
| Line 1,545: | Line 1,545: | ||
---- | ---- | ||
=== MYLISTSTATS : Retrieve | === MYLISTSTATS : Retrieve MyList stats === | ||
'''Command String:''' | '''Command String:''' | ||
* MYLISTSTATS | * MYLISTSTATS | ||
| Line 1,711: | Line 1,711: | ||
---- | ---- | ||
=== STATS [ | === STATS [{{colour|red|disabled}}] === | ||
'''Command String:''' | '''Command String:''' | ||
* STATS | * STATS | ||
| Line 1,720: | Line 1,720: | ||
---- | ---- | ||
=== TOP [ | === TOP [{{colour|red|disabled}}] === | ||
'''Command String:''' | '''Command String:''' | ||
* TOP | * TOP | ||
| Line 1,756: | Line 1,756: | ||
== Return Codes == | == Return Codes == | ||
Note | {{eyecatch|Note|The names below do '''not''' necessarily reflect the actual code strings returned by the server.}} | ||
<pre> | <pre> | ||
// POSITIVE 2XX | // POSITIVE 2XX | ||