UDP API Definition: Difference between revisions

Jump to navigation Jump to search

UDP API Definition (view source)

Revision as of 13:30, 2 January 2008

700 bytes added ,  2 January 2008
→‎Notify Commands: some cleaning
(→‎Notify Commands: some cleaning)
Line 251: Line 251:
== Notify Commands ==
== Notify Commands ==
These commands offer a way to receive different types of notifications:
These commands offer a way to receive different types of notifications:
* New file [[Notifications|notification]]. (Only anime type are currently 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.


'''Simple HOWTO:'''
'''Simple HOWTO:'''
* PUSH to register.
* PUSH to register your client session.
* Listen for 271/272 NOTIFICATIONs (not 290).
* Listen for 271-274 NOTIFICATIONs ('''not 290''').
* PUSHACK the NOTIFICATIONs received (with the supplied ids [nid]).
* 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 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 NOTIFYGET to receive a notification.
* Use NOTIFYACK to remove a notification (from NOTIFYLIST).
* 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.
It is probably a good idea to use tags to separate NOTIFICATIONs from the other communication. NOTIFICATIONs will '''never''' have tags.
{{eyecatch|NOTE|The word "notification" is 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.}}


=== PUSH: UDP Notification Registration ===
=== 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.
'''Command String:'''
'''Command String:'''
* PUSH notify={bool push_file_added_notifications}&msg={bool push_msg_added_notifications}[&buddy={bool push_buddy_event_notifications}]
* PUSH notify={bool on_new_file}&msg={bool on_new_private_message}[&buddy={bool on_buddy_event}]


'''Possible Replies:'''
'''Possible Replies:'''
* 270 NOTIFICATION ENABLED
* 270 NOTIFICATION ENABLED
OR (if both values are 0)
OR (if both values are 0)
* 370 NOTIFICATION DISABLED
* 370 NOTIFICATION DISABLED


'''Note:'''
'''Info:'''
* This command only works if you are logged in.
* A client which has registered to recieve UDP notification packets must:
* With this command you can register your client as an observer for anidb notification and message events for the current user. If you are registered for one or both events 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.
** Issue a PUSHACK command for each notification received with ''notify_packet_id'' provided in the notification packet.
* UDP packets are resend 3 times, if the client does not acknowlege them. After that the client is logged out and no further notifies will be sent.
* On recieving any of the above packets the client has to issue a PUSHACK command with the notify_packet_id provided in the notification packet.
* A client which has registered to recieve UDP notification packets should:
** Use PING to keep the connection alive (< 30 min).
** Use PING to keep the connection alive (< 30 min).
** Use UPTIME to ensure that the session is OK (>= 30 min).
** Use UPTIME to ensure that the session is OK (>= 30 min).
* Every notification generated is resent 3 times unless acknowleged. After that the client is logged out.


====Notification Packet Format====
====Notification Packet Format====
'''File Added Notify:'''
'''New File Notify:'''


   271 {int4 notify_packet_id} NOTIFICATION
   271 {int4 notify_packet_id} NOTIFICATION
   {int4 aid}|{int4 date}|{int4 count}|{str animetitle}
   {int4 relid}|{int4 date}|{int4 count}|{str relname}|{int2 reltype}|{int2 priority}


* aid is the id of the affected anime
* relid is the id of the related entry (anime, group)
* date is the time of the event (in seconds since 1.1.1970)
* date is the time of the event (in seconds since 1.1.1970)
* count is the number of events pending for this anime
* count is the number of events pending for type
* animetitle is the name of the affected anime
* relname is the name of the related entry
* reltype is: 1 = anime, 2 = group, 3 = producer
* priority is: 0 = low, 1 = medium, 2 = high


'''Message Added Notify:'''
{{eyecatch|NOTE| Group (and producer) related file notifications are not implemented yet.}}
 
'''New Private Message Notify:'''


   272 {int4 notify_packet_id} NOTIFICATION
   272 {int4 notify_packet_id} NOTIFICATION
   {int2 type}|{int4 date}|{int4 senderuid}|{str sendername}|{str subject}|{str body}|{int mid}
   {int2 type}|{int4 date}|{int4 sent_by_uid}|{str sent_by_name}|{str subject}|{str body}|{int mid}


* type is the type of the message (0=normal msg, 1=annonymous, 2=system msg, 3=mod msg)
* type is the type of the message (0=normal msg, 1=annonymous, 2=system msg, 3=mod msg)
Line 325: Line 331:


=== PUSHACK: UDP Notification Acknowledge ===
=== PUSHACK: UDP Notification Acknowledge ===
Used to acknowledge notification packets (271-274). A client must be prepared to issue this command before using '''PUSH'''.
'''Command String:'''
'''Command String:'''
* PUSHACK nid={int4 notify_packet_id}
* PUSHACK nid={int4 notify_packet_id}
Line 333: Line 341:


'''Info:'''
'''Info:'''
* This command only works if you are logged in.
* See: '''PUSH'''
*see: '''PUSH'''


----
----
=== NOTIFY: Notifications ===
=== NOTIFY: Notifications ===
Get number of pending notifications (and number of online buddies).
'''Command String:'''
'''Command String:'''
* NOTIFY [buddy=1]
* NOTIFY [buddy=1]
Line 343: Line 352:
'''Possible Replies:'''
'''Possible Replies:'''
* 290 NOTIFICATION
* 290 NOTIFICATION
: {int4 pending_notifies}|{int4 pending_msgs}
: {int4 pending_file_notifications}|{int4 number_of_unread_messages}
when ''buddy=1''
when ''buddy=1''
* 290 NOTIFICATION
* 290 NOTIFICATION
: {int4 pending_notifies}|{int4 pending_msgs}|{int4 number_of_online_buddys}
: {int4 pending_file_notifications}|{int4 number_of_unread_messages}|{int4 number_of_online_buddies}


'''Info:'''
'''Info:'''
* This command only works if you are logged in.
* ''pending_notifies'' is the number of animes which have pending notifications for this user.
* ''pending_msgs'' is the number of unread anidb messages for this user.
* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then recieving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out because it did not respond to a PUSH Notification packet.
* If the client did send a NOTIFY within the last 35 minutes and it was confirmed by AniDB then recieving a 501 LOGIN FIRST message for the next NOTIFY command shows that AniDB logged the client out because it did not respond to a PUSH Notification packet.
* There is no command to retrieve missed PUSH Notifications.
* There is no command to retrieve missed PUSH Notifications.
{{eyecatch|NOTE:| This command MUST NOT be issued more than once every 20 minutes.}}
{{eyecatch|NOTE| This command MUST NOT be issued more than once every 20 minutes.}}


----
----


=== NOTIFYLIST: List Notification/Message IDs ===
=== NOTIFYLIST: List Notification/Message IDs ===
List id of all pending (not acknowledged) ''new private message'' and ''new file'' notifications. Buddy events are not acknowledgeable.
'''Command String:'''
'''Command String:'''
* NOTIFYLIST
* NOTIFYLIST
Line 369: Line 377:


'''Info:'''
'''Info:'''
* This command only works if you are logged in.
* type is:
* type is:
: M for message entries
: M for message entries
: N for notification entries
: N for notification entries
*id is the identifier for the notification/message as required by NOTIFYGET.
* id is the identifier for the notification/message as required by NOTIFYGET.
* NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.
* NOTIFYLIST returns one line per entry, if no entries are available only the first line of the reply is returned.
{{eyecatch|NOTE:| This command MUST NOT be issued regulary but should only be triggered by either a push message recieved by the client or a reply to a NOTIFY command which tells you that there are messages/notifications waiting.}}
{{eyecatch|NOTE| This command MUST NOT be issued regulary but should only be triggered by either a push message recieved by the client or a reply to a NOTIFY command which tells you that there are messages/notifications waiting.}}


----
----
=== NOTIFYGET: Get Notification/Message ===
=== NOTIFYGET: Get Notification/Message ===
Receive private message or file notification.
'''Command String:'''
'''Command String:'''
* NOTIFYGET type={str type}&id={int4 id}
* NOTIFYGET type={str type}&id={int4 id}
Line 393: Line 402:


'''Info:'''
'''Info:'''
* This command only works if you are logged in.
* type is:
* type is:
: M for message entries
: M for message entries
Line 410: Line 418:


=== NOTIFYACK: Acknowledge Notification/Message ===
=== NOTIFYACK: Acknowledge Notification/Message ===
This command will mark a message read or clear a ''new file'' notification. Buddy events are not acknowledgeable.
'''Command String:'''
'''Command String:'''
* NOTIFYACK type={str type}&id={int4 id}
* NOTIFYACK type={str type}&id={int4 id}
Line 422: Line 432:


'''Info:'''
'''Info:'''
* This command only works if you are logged in.
* This command will mark a message read or clear a notification.
* type is:
* type is:
: M for message entries
: M for message entries
Epoximator
546

edits

Retrieved from "https://wiki.anidb.net/Special:MobileDiff/8743"

Navigation menu

MediaWiki spam blocked by CleanTalk.
MediaWiki spam blocked by CleanTalk.