nsIDBChangeListener

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

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.