358
edits
UDP API Definition: Difference between revisions
no edit summary
Epoximator (talk | contribs) |
No edit summary |
||
| Line 249: | Line 249: | ||
* The encryption key is md5(api_password_of_user+''salt''). | * The encryption key is md5(api_password_of_user+''salt''). | ||
* Padding of the message needs to be done according to the PKCS5Padding scheme. | * Padding of the message needs to be done according to the PKCS5Padding scheme. | ||
== Notify Commands == | == Notify Commands == | ||
=== Introduction === | |||
Broadly speaking, notifications provide an indication to the client that some event has occurred within the AniDB database. | |||
There are three types: | |||
* New file [[Notifications|notification]]. (Only anime type supported.) | * New file [[Notifications|notification]]. (Only anime type supported.) | ||
* New private message notification. | * New private message notification. | ||
* New buddy event notification. | * New buddy event notification. | ||
''' | Note that, while a user can subscribe to multiple 'new file' events (see [[Notifications|notifications]]), at present, the UDP API only supports notifications of new files by anime. New files by group, or new files by producer, are NOT presently supported. Just the same, keeping in mind that the API is designed to potentially support such notifications in the future will help in understanding why some of the commands are structured the way they are. | ||
The word "notification" is also used a bit inconsistently in this document. An AniDB notification is originally a "new file [[Notifications|notification]]". It might be more correct to use the term "event" for the original "happening" and then "notification" as the means to notify the user (client). New-file, new-message, buddy-* and going-down are all events that results in notifications. Only the first two type of events are persistent, though, meaning they exist and remain in the same state until some user action affects them. | |||
=== Getting Notifications === | |||
Clients that wish to receive notifications have two routes available to them. They are by no means mutually exclusive and selecting one does not imply a client is unable to use commands from another. | |||
'''Method One: Polling''' | |||
With this method, the client contacts the server at some interval (no more than once every 20 minutes) to see if there are new file notifications waiting. If there are, the client can the get further details of the files in question. This is analogous to checking an email server every half hour to see if new email has arrived. | |||
Its principal advantage is that it is easy to design and code. Blocking sockets are sufficient as the client can expect the reply received to correspond with the command sent. | |||
The disadvantage of this approach is that it introduces a delay and some uncertainty in receiving notifications. If, for example, the user clears the notification on the website before the client collects it, the client will not learn of the new file. Similarly, if the user does not dismiss notifications via the site, the client will have an increasing amount of stale data to work though. Finally, notifications cleared by the client also clears them from the website, so users will need to be made aware of what is going on. | |||
A polling HOWTO: | |||
* Use NOTIFY (no more than once every 20 minutes) to get the number of pending notifications | |||
* IF there are new notifications pending, use NOTIFYLIST to get a list of notification types and associated IDs. | |||
* Use NOTIFYGET to receive a notification, suppling the ID provided by NOTIFYLIST | |||
* Use NOTIFYACK to acknowledge a notification, suppling the ID provided by NOTIFYLIST (if desired) | |||
{{eyecatch|NOTE|The ID supplied by NOTIFYLIST will be the ID of the affected notification type. Since, at present, only the anime type is supported, this value is always an aid. In the future, it may represent a group or producer ID. In these cases, the str '''type''' value will indicate what entity the ID represents.}} | |||
'''Method Two: Server PUSH''' | |||
With this method, the server takes the active role in advising the client that a new file has arrived. The client must register with the server to receive these advisements, and will be responsible for keeping the login session from timing out, and any NAT router ports open. The UDP packet is sent to the ip and port from which the AUTH command was recieved. | |||
This method compensates for the disadvantages of the polling method, but is more difficult to code. Blocking sockets are no longer an option, nor can a client make any assumptions that an incoming packet will necessarily be a reply to the last command sent. The tag option may be helpful here. | |||
A PUSH HOWTO: | |||
* PUSH to register your client session. | * PUSH to register your client session. | ||
* Listen for 271-274 NOTIFICATIONs ('''not 290'''). | * Listen for 271-274 NOTIFICATIONs ('''not 290'''). | ||
* PUSHACK the | * Use PUSHACK to to acknowledge the notification using the nid supplied with NOTIFICATION | ||
* Use | * Use NOTIFYGET to receive a notification, suppling the relid provided by NOTIFICATION (NOT the packet ID) | ||
* Use | * Use NOTIFYACK to acknowledge a notification, suppling the relid provided by NOTIFICATION (if desired) | ||
* Use | * Use UPTIME (with an interval between 30 and 35 minutes) to keep login session valid | ||
It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will '''never''' have tags. | It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will '''never''' have tags. | ||
=== PUSH: UDP Notification Registration === | === PUSH: UDP Notification Registration === | ||
Register your client as an observer for anidb notification events for the current user. If you are registered for one or more event types the anidb server will send an UDP packet (format see below) on each change which affects the current user. | |||
'''Command String:''' | '''Command String:''' | ||