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) 

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

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.