nsIMsgDBHdr

The nsIMsgDBHdr interface describes headers for mail messages.

 
 - 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])).

Inherits from: nsISupports

This interface is usually given to you in return to a query from the message database. There are utility functions that also return it though. For instance, msgHdrForCurrentMessage() will return the currently selected message's header.

Headers are backed by the database: a call to these functions directly modifies the state of the database, although it is not saved until the database is committed. In clear, if you want to do a persistent change to a message header, such as marking it as read, or replied to, or whatever, you MUST do it through its corresponding nsIMsgFolder (msgHdr.folder) or nsIMsgDatabase (msgHdr.folder.msgDatabase). It is also mandatory to set msgHdr.folder.msgDatabase = null after performing this kind of operations to prevent leaking. Don't even think about using OrFlags and/or AndFlags.

Method overview

AString getProperty(in string propertyName);
void setProperty(in string propertyName, in AString propertyStr);
void setStringProperty(in string propertyName, in string propertyValue);
string getStringProperty(in string propertyName);
unsigned long getUint32Property(in string propertyName);
void setUint32Property(in string propertyName, in unsigned long propertyVal);
void markRead(in boolean read);
void markFlagged(in boolean flagged);
void markHasAttachments(in boolean hasAttachments);
void setPriorityString(in string priority);
unsigned long OrFlags(in unsigned long flags);
unsigned long AndFlags(in unsigned long flags);
void setReferences(in string references);
ACString getStringReference(in long refNum);
void setRecipientsArray(in string names, in string addresses,in unsigned long numAddresses);
void setCCListArray(in string names, in string addresses,in unsigned long numAddresses);
void setBCCListArray(in string names, in string addresses,in unsigned long numAddresses);New in Thunderbird 3.1
[noscript] void getAuthorCollationKey(out octetPtr key, out unsigned long len);
[noscript] void getSubjectCollationKey(out octetPtr key, out unsigned long len);
[noscript] void getRecipientsCollationKey(out octetPtr key, out unsigned long len);

Attributes

Attribute Type Description
isRead boolean Readonly: Indicates whether or not the message is read.
isFlagged boolean Readonly: Indicates whether or not the message is starred in the UI.
isKilled boolean Readonly: Indicates whether or not this message belongs to a subthread that has been ignored in the UI. If you want to know whether the message is the root of an ignored subthread then you should check for the Ignored flag. Any children of the ignored message will be marked as read when added to the database.
priority nsMsgPriorityValue Indicates the priority of this message.
flags unsigned long Indicates the flags of the message. See nsMsgMessageFlags for a list of what may or may not be set on this message. Note that the elided flag should not be set on messages, as it is a flag strictly dealing with the database view.
threadId nsMsgKey Indicates the ID of the thread to which this message belongs. This property does not change the state of any thread objects, so only internal database code should set this attribute.
messageKey nsMsgKey Indicates the database key for this message. Setting this property will probably result in an inconsistent database representation, so only internal database code should set this attribute.
threadParent nsMsgKey Indicates the parent of this message in its thread. If this is the root of the thread, it will return nsMsgKey_None.
messageSize unsigned long Indicates the size of this message in bytes.
lineCount unsigned long Indicates the size of the message body in number of lines.
statusOffset unsigned long Indicates the offset within the message of the X-Mozilla-Status header.
messageOffset unsigned long Indicates the position of the offline copy of an IMAP or news messages within the offline store.
offlineMessageSize unsigned long Indicates the size of the offline copy of an IMAP or news message.
date PRTime Indicates the date of this message; the equivalent header is the Date: header.
dateInSeconds unsigned long Readonly: Indicates the date of this message as a Unix timestamp.
messageId string Indicates the message ID of this message, without angle brackets. If setting this value, outer angle brackets will be stripped if present.
ccList string Indicates the Cc list of this message; the equivalent header is the Cc: header.
bccList string [new in .31] Indicates the Bcc list of this message; the equivalent header is the Bcc: header.
author string Indicates the author of this message; the equivalent header is the From: header. The value here will effectively be the unparsed version of the header.
subject string Indicates the subject of this message; the equivalent header is the Subject: header. The value here will effectively be the unparsed header content, so it will contain full MIME-encoded syntax.
recipients string Indicates the recipients of the message. This is the first non-empty value of the To: header, Cc: header, or Newsgroup: header. The value here will effectively be the unparsed header content; it may be easier to set this using setRecipientsArray.
numReferences unsigned short Readonly: Indicates the number of references this header has.
mime2DecodedAuthor AString Readonly: Indicates the author of this message. The value here will have been decoded by the mime converter service.
mime2DecodedSubject AString Readonly: Indicates the subject of this message. The value here will have been decoded by the mime converter service.
mime2DecodedRecipients AString Readonly: Indicates the recipients of this message. The value here will have been decoded by the mime converter service.
Charset string Indicates the character set of this message. This value is extracted from the Content-Type header.
label nsMsgLabelValue Indicates one of the old 5 label values used by old versions. New code should use keywords instead.
accountKey string Indicates the account that was originally used to fetch the message. May be blank if the message has not been moved or copied.
folder nsIMsgFolder Readonly: Indicates the folder in which this message is stored.
propertyEnumerator nsIUTF8StringEnumerator Readonly: Enumerator for names of all database properties in the header. (new in 3.1?)

Methods

getProperty()

 AString getProperty(in string propertyName);
Parameters
propertyName
The name of the property to retrieve.
Return Value

The value of the property.

setProperty()

Sets a property on the header. For the currently selected message, Thunderbird provides a utility function: setMsgHdrPropertyAndReload(aProperty, aValue); which duplicates this functionality without requiring you to grab the current header.

 void setProperty(in string propertyName,
                  in AString propertyStr);
Parameters
propertyName
The name of the property to set.
propertyStr
The value of the property.

setStringProperty()

 void setStringProperty(in string propertyName,
                        in string propertyValue);
Parameters
propertyName
The name of the property to set.
propertyValue
The value of the property.

getStringProperty()

 string getStringProperty(in string propertyName);
Parameters
propertyName
The name of the property to retrieve.
Return Value

The value of the property.

getUint32Property()

Get an integer property. Usually you would use this to store your own properties.

 unsigned long getUint32Property(in string propertyName);
Parameters
propertyName
The name of the property to retrieve. Thunderbird stored Uint32 properties (not a complete list):
indexed
Used for Spotlight integration on OSX.
notAPhishMessage
Indicates whether phisihing filters have been run on a message yet.

 

Return Value

The value of the property.

setUint32Property()

 void setUint32Property(in string propertyName,
                        in unsigned long propertyVal);
Parameters
propertyName
The name of the property to set.
propertyVal
The value of the property.

markRead()

Marks this header as read. Thunderbird provides a utility function which performs this for the currently selected message: MarkCurrentMessageAsRead().

 void markRead(in boolean read);
Parameters
read
If true, mark as read. If false mark as undread.

markFlagged()

 void markFlagged(in boolean flagged);
Parameters
flagged
If true, mark as flagged. If false remove flag.

markHasAttachments()

 void markHasAttachments(in boolean hasAttachments);
Parameters
hasAttachments
If true, mark as having attachments. If false mark as not having attachments.

setPriorityString()

 void setPriorityString(in string priority);
Parameters
priority
String describing the priority.

OrFlags()

 unsigned long OrFlags(in unsigned long flags);
Parameters
flags
Flags to be added to the current message flags.

AndFlags()

 unsigned long AndFlags(in unsigned long flags);
Parameters
flags
Flags to be retained on the current message flags. All other flags are cleared.

setReferences()

 void setReferences(in string references);
Parameters
references
Sets the list of references for a news message.

getStringReference()

Returns one of the references in the list of references.

 ACString getStringReference(in long refNum);
Parameters
refNum
The index of the reference to return. Must be less than the total number of references.

setRecipientsArray()

Uses the header parser to recreate the recipients header from an array of names and addresses.

 void setRecipientsArray(in string names,
                         in string addresses,
                         in unsigned long numAddresses);
Parameters
names
A null-delimited list of recipient names.
addresses
A null-delimited list of recipient addresses.
numAddresses
The number of recipients.

setCCListArray()

Users the header parser to recreate the Cc header from an array of names and addresses.

 void setCCListArray(in string names,
                     in string addresses,
                     in unsigned long numAddresses);
Parameters
names
A null-delimited list of Cc names.
addresses
A null-delimited list of Cc addresses.
numAddresses
The number of Ccs.

getAuthorCollationKey()

Decodes and parses the message author and creates a collation key that can be used to efficiently sort authors case insensitively.

 [noscript] void getAuthorCollationKey(out octetPtr key,
                                       out unsigned long len);
Parameters
key
The returned collation key for the author.
len
The length of the returned collation key.

getSubjectCollationKey()

Decodes and parses the message subject and creates a collation key that can be used to efficiently sort subjects case insensitively.

 [noscript] void getSubjectCollationKey(out octetPtr key,
                                        out unsigned long len);
Parameters
key
The returned collation key for the subject.
len
The length of the returned collation key.

getRecipientsCollationKey()

Decodes and parses the message recipients and creates a collation key that can be used to efficiently sort recipients case insensitively.

 [noscript] void getRecipientsCollationKey(out octetPtr key,
                                           out unsigned long len);
Parameters
key
The returned collation key for the recipients.
len
The length of the returned collation key.

Document Tags and Contributors

Tags: 
 Contributors to this page: Oeekker, Sheppy, realraven, Neil, squib, bienvenu, mozjonathan, Jcranmer, Clarkbw, ericpp, Sevenspade, Wjjohnst
 Last updated by: Oeekker,