mozilla

nsIDBChangeListener

The nsIDBChangeListener interface is used by components wanting to receive notification when the current database changes somehow.

 
 - 1 - Interface Name 
 - 2 - Source Location relative to @topsrc@/mozilla/ 
 - 3 - FROZEN/unfrozen/UNDER_REVIEW/EXPERIMENTAL 
 - 4 - Since [date/milestone] (in unfrozen case, last-changed-in) 
 - 5 - Scriptable? (yes/no) 

See MDC:Writing interface reference documentation for an elaborate guide on documenting interfaces on MDC.

web.html($0) is defined in wiki.template('tbsource', mediawiki.args([$1])). It is wiki.template(mediawiki.path('InterfaceStatus:Scriptable_' + $4, "en")) and wiki.template(mediawiki.path('InterfaceStatus:' + $2, "en"), mediawiki.args([$3])).

Example

Here is an example implementation of the listener (that does nothing):

var myListener = {
  onHdrFlagsChanged: function(aHdrChanged, aOldFlags, aNewFlags, aInstigator) {},
  onHdrDeleted: function(aHdrChanged, aParentKey, aFlags, aInstigator) {},
  onHdrAdded: function(aHdrChanged, aParentKey, aFlags, aInstigator) {},
  onParentChanged: function(aKeyChanged, oldParent, newParent, aInstigator) {},
  onAnnouncerGoingAway: function(aInstigator) {},
  onReadChanged: function(aInstigator) {},
  onJunkScoreChanged: function(aInstigator) {},
  onHdrPropertyChanged: function(aHdrToChange, aPreChange, aStatus, aInstigator) {},
  onEvent: function(aDB, aEvent) {},

  QueryInterface: function(aIID) {
    if (!aIID.equals(Components.interfaces.nsIDBChangeListener) &&    
        !aIID.equals(Components.interfaces.nsISupports))
      throw Components.results.NS_ERROR_NO_INTERFACE;
    return this;
  }
};

and to attach it in Thunderbird, we must call AddListener on a nsIDBChangeAnnouncer, typically through a nsIMsgDatabase. There are a couple of ways to access the message database: if you have a nsIMsgFolder, you can do this like so:

 someFolder.msgDatabase.AddListener(myListener);

Alternately, you can access the message database through the nsIMsgDbView like so:

 gFolderDisplay.view.dbView.db.AddListener(myListener);

Method overview

void onHdrFlagsChanged(in nsIMsgDBHdr aHdrChanged, in unsigned long aOldFlags, in unsigned long aNewFlags, in nsIDBChangeListener aInstigator);
void onHdrDeleted(in nsIMsgDBHdr aHdrChanged, in nsMsgKey aParentKey, in long aFlags, in nsIDBChangeListener aInstigator);
void onHdrAdded(in nsIMsgDBHdr aHdrChanged, in nsMsgKey aParentKey, in long aFlags, in nsIDBChangeListener aInstigator);
void onParentChanged(in nsMsgKey aKeyChanged, in nsMsgKey oldParent, in nsMsgKey newParent, in nsIDBChangeListener aInstigator);
void onAnnouncerGoingAway(in nsIDBChangeAnnouncer instigator);
void onReadChanged(in nsIDBChangeListener aInstigator);
void onJunkScoreChanged(in nsIDBChangeListener aInstigator);
void onHdrPropertyChanged(in nsIMsgDBHdr aHdrToChange, in unsigned long aOldFlags, in PRBool aPreChange, inout PRUint32 aStatus, in nsIDBChangeListener aInstigator);
void onEvent(in nsIMsgDatabase aDB, in string aEvent);

Methods

onHdrFlagsChanged()

Called when a message's flags change.

 void onHdrFlagsChanged(in nsIMsgDBHdr aHdrChanged,
                        in unsigned long aOldFlags,
                        in unsigned long aNewFlags, 
                        in nsIDBChangeListener aInstigator);
Parameters
aHdrChanged
The nsIMsgDBHdr of the message that changed.
aOldFlags
The original flags on the message. Can be used to figure out what changed. Flags are defined in nsMsgMessageFlags.
aNewFlags
The new flags on the message. Can be used to figure out what changed. Flags are defined in nsMsgMessageFlags.
aInstigator
The caller who changed the header. This can be used to filter out events that you yourself started. aInstigator may also be null.

onHdrDeleted()

Called when a header is deleted from the database.

 void onHdrDeleted(in nsIMsgDBHdr aHdrChanged,
                   in nsMsgKey aParentKey,
                   in long aFlags, 
                   in nsIDBChangeListener aInstigator);
Parameters
aHdrChanged
The nsIMsgDBHdr of the message that was removed.
aParentKey
The key of the parent folder for deleted header. The typedef of nsMsgKey is given in MailNewsTypes2.idl.
aFlags
The flags on the message. Flags are defined in nsMsgMessageFlags.
aInstigator
The caller who deleted the header. This can be used to filter out events that you yourself started. aInstigator may also be null.

onHdrAdded()

Called when a header is added to the database.

 void onHdrAdded(in nsIMsgDBHdr aHdrChanged,
                 in nsMsgKey aParentKey,
                 in long aFlags, 
                 in nsIDBChangeListener aInstigator);
Parameters
aHdrChanged
The nsIMsgDBHdr of the message that was added.
aParentKey
The key of the parent folder for new header. The typedef of nsMsgKey is given in MailNewsTypes2.idl.
aFlags
The flags on the message. Flags are defined in nsMsgMessageFlags.
aInstigator
The caller who added the header. This can be used to filter out events that you yourself started. aInstigator may also be null.

onParentChanged()

Called when a message's parent is changing (i.e. most likely it is being moved).

 void onParentChanged(in nsMsgKey aKeyChanged,
                      in nsMsgKey oldParent,
                      in nsMsgKey newParent,
                      in nsIDBChangeListener aInstigator);
Parameters
aKeyChanged
The key of the message that changed. The typedef of nsMsgKey is given in MailNewsTypes2.idl.
oldParent
The key of the old parent folder for the header. The typedef of nsMsgKey is given in MailNewsTypes2.idl.
newParent
The key of the new parent folder for the header. The typedef of nsMsgKey is given in MailNewsTypes2.idl.
aInstigator
The caller who changed the parent. This can be used to filter out events that you yourself started. aInstigator may also be null.

onAnnouncerGoingAway()

Called when an announcer is being deleted.

 void onAnnouncerGoingAway(in nsIDBChangeAnnouncer aInstigator);
Parameters
aInstigator
The nsIDBChangeAnnouncer that is being removed.

onReadChanged()

Called when the read state of news messages changes. Only used by nsINewsDatabase databases. Others use the onHdrFlagsChanged() method.

 void onReadChanged(in nsIDBChangeListener aInstigator);
Parameters
aInstigator
The caller who changed the read state. This can be used to filter out events that you yourself started. aInstigator may also be null.

onJunkScoreChanged()

Called when the junk score of a message has changed.

 void onJunkScoreChanged(in nsIDBChangeListener aInstigator);
Parameters
aInstigator
The caller who changed the junk score. This can be used to filter out events that you yourself started. aInstigator may also be null.

onHdrPropertyChanged()

Called in the general case where any field may have changed. OnHdrPropertyChanged is called twice per change. On the first call, aPreChange is true, and aStatus is undefined. OnHdrPropertyChanged saves any required status in aStatus (such as a filter match). The calling function stores the value of aStatus, changes the header aHdrToChange, then calls OnHdrPropertyChanged again with aPreChange false. On this second call, the stored value of aStatus is provided, so that any changes may be noted.

 void onHdrPropertyChanged(in nsIMsgDBHdr aHdrToChange,
                           in PRBool aPreChange,
                           inout PRUint32 aStatus,
                           in nsIDBChangeListener aInstigator);
Parameters
aHdrToChange
The nsIMsgDBHdr of the message that is changing.
aPreChange
True on first call before change, false on second call after change.
aStatus
The storage location provided by calling routine for status.
aInstigator
The caller who added the header. This can be used to filter out events that you yourself started. aInstigator may also be null.

onEvent()

Generic notification for extensibility. Common events should be documented here so we have a hope of keeping the documentation up to date. Current events are:

DBOpened
When a pending listener becomes real. This can happen when the existing db is force closed and a new one opened. Only registered pending listeners are notified.

 

 void onEvent(in nsIMsgDatabase aDB,
              in string aEvent);
Parameters
aDB
The nsIMsgDatabase that is changing.
aString
The type of event.

Document Tags and Contributors

Contributors to this page: Sheppy, Wjjohnst, squib
Last updated by: Sheppy,