User:Ommina

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 notification. (Only anime type supported.)
• New private message notification.
• New buddy event notification.

Note that, while a user can subscribe to multiple 'new file' events (see 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.

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.

It's 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.

Two HOWTOs...

These commands offer a way to receive different types of notifications:

Simple HOWTO:

• PUSH to register your client session.
• Listen for 271-274 NOTIFICATIONs (not 290).
• PUSHACK the NOTIFICATIONs received (with the supplied id [nid]).
• Use NOTIFY to get number of notifications / NOTIFYLIST to get a list of the notifications (with ids [not nid]).
• Use NOTIFYGET to receive a notification.
• Use NOTIFYACK to acknowledge a notification (from NOTIFYLIST).

It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will never have tags.

NOTE

The word "notification" is used a bit inconsistently in this document. An AniDB notification is originally a "new file 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.

PUSH: UDP Notification Registration

With this command you can 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. The UDP packet is sent to the ip and port from which the AUTH command was recieved.