nsIMsgDBHdr

The nsIMsgDBHdr interface describes headers for mail messages.

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.