nsIMsgHeaderParser

Defined in comm-central/ mailnews/ mime/ public/ nsIMsgHeaderParser.idl

To create an instance, use:

var msgHeaderParser = Components.classes["@mozilla.org/messenger/headerparser;1"]
                      .createInstance(Components.interfaces.nsIMsgHeaderParser);

Method overview

Methods

extractHeaderAddressMailboxes()

Given a string which contains a list of Header addresses, returns a comma-separated list of just the 'user name' portions. If any of the addresses doesn't have a name, then the mailbox is used instead.

AUTF8String extractHeaderAddressMailboxes(
  in string line
);

Parameters

line

The header line to parse.

Return value

A comma-separated list of just the mailbox parts of the addresses.

Exceptions thrown

Missing Exception

Missing Description

Given a string which contains a list of Header addresses, returns a comma-separated list of just the 'user name' portions.  If any of the addresses doesn't have a name, then the mailbox is used instead.

AUTF8String extractHeaderAddressNames(
  in string line
);

Parameters

line

The header line to parse.

Return value

A comma-separated list of just the name parts of the addresses.

Exceptions thrown

Missing Exception

Missing Description

Like extractHeaderAddressNames(), but only returns the first name in the list, if there is more than one.

AUTF8String extractHeaderAddressName(
  in string line
);

Parameters

line

The header line to parse.

Return value

The first name found in the list

Exceptions thrown

Missing Exception

Missing Description

makeFullAddress()

Given an e-mail address and a person's name, concatenates them together into a single string, doing all the necessary quoting.

AString makeFullAddress(
  in AString aName,
  in AString aAddress
);

Parameters

aName

The name of the sender. This should be in UTF-8.

aAddress

The address of the sender. This should be in UTF-8.

Return value

A string of the form name <address>.

Exceptions thrown

Missing Exception

Missing Description

Given an e-mail address and a person's name, cons them together into a single string, doing all the necessary quoting (const char* version).

string makeFullAddressString(
  in string aName,
  in string aAddress
);

Parameters

aName

The name of the sender. This should be in UTF-8.

aAddress

The address of the sender. This should be in UTF-8.

Return value

A string of the form name <address>.

Exceptions thrown

Missing Exception

Missing Description

wstring makeFullAddressWString(
  in wstring name,
  in wstring addr
);

Parameters

name

The name of the sender. This should be in UTF-8.

addr

The address of the sender. This should be in UTF-8.

Return value

A string of the form name <address>.

Exceptions thrown

Missing Exception

Missing Description

Given a string which contains a list of Header addresses, parses it into their component names and mailboxes.

The returned value is the number of addresses, or a negative error code; the names and addresses are returned into the provided pointers as consecutive null-terminated strings.  It is up to the caller to free them. Note that some of the strings may be zero-length.

The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

Either of the provided pointers may be NULL if the caller is not interested in those components.

void parseHeaderAddresses(
  in string line,
  out string names,
  out string addresses,
  out PRUint32 numAddresses
);

Parameters

line

The header line to parse.

names

A string of the names in the header line. The names are separated by null-terminators. This param may be null if the caller does not want this part of the result.

addresses

A string of the addresses in the header line. The addresses are separated by null-terminators. This param may be null if the caller does not want this part of the result.

numAddresses

The number of addresses in the header. If this is negative, there has been an error parsing the header.

Exceptions thrown

Missing Exception

Missing Description

parseHeadersWithArray()

void parseHeadersWithArray(
  in wstring aLine,
  [array, size_is(count)] out wstring aEmailAddresses,
  [array, size_is(count)] out wstring aNames,
  [array, size_is(count)] out wstring aFullNames,
  [retval] out unsigned long count
);

Parameters

aLine

The header line to parse.

aEmailAddresses

Missing Description

aNames

Missing Description

aFullNames

Missing Description

count

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Given a string which contains a list of Header addresses, returns a new string with the same data, but inserts missing commas, parses and reformats it, and wraps long lines with newline-tab.

string reformatHeaderAddresses(
  in string line
);

Parameters

line

The header line to parse.

Return value

The reformatted header line.

Exceptions thrown

Missing Exception

Missing Description

reformatUnquotedAddresses()

Given a string, will make it safe to use by adding missing quote and escaping needed quote

wstring reformatUnquotedAddresses(
  in wstring line
);

Parameters

line

The header line to parse.

Return value

Safe Addresses (?)

Exceptions thrown

Missing Exception

Missing Description

Returns a copy of ADDRS which may have had some addresses removed. Addresses are removed if they are already in either ADDRS or OTHER_ADDRS. (If OTHER_ADDRS contain addresses which are not in ADDRS, they are not added.  That argument is for passing in addresses that were already mentioned in other header fields.)

Addresses are considered to be the same if they contain the same mailbox part (case-insensitive.)  Real names and other comments are not compared.

removeAliasesToMe allows the address parser to use the preference which contains regular expressions which also mean 'me' for the purpose of stripping the user's email address(es) out of addrs

string removeDuplicateAddresses(
  in string addrs,
  in string other_addrs,
  in PRBool removeAliasesToMe
);

Parameters

addrs

The addresses to remove duplicates from.

other_addrs

Other addresses that the duplicate removal process also checks for duplicates against. Addresses in this list will not be added to the result.

Return value

A string based on the original without the duplicate addresses.

Exceptions thrown

Missing Exception

Missing Description

This function removes the quoting if you want to show the names to users. e.g. summary file, address book. If preserveIntegrity is set to true, quote will not be removed in case the name part of the email contains a comma.

string unquotePhraseOrAddr(
  in string line,
  in boolean preserveIntegrity
);

Parameters

line

The header line to parse.

preserveIntegrity

Set to true, quote will not be removed

Return value

User friendly names

Exceptions thrown

Missing Exception

Missing Description

unquotePhraseOrAddrWString()

This function removes the quoting if you want to show the names to users. e.g. summary file, address book. If preserveIntegrity is set to true, quote will not be removed in case the name part of the email contains a comma.

wstring unquotePhraseOrAddrWString(
  in wstring line,
  in boolean preserveIntegrity
);

Parameters

line

The header line to parse.

preserveIntegrity

Missing Description

Return value

Missing Description

Exceptions thrown

Missing Exception

Missing Description

Remarks

I think some of the charset parameters might be obsolete... So this page is still W.I.P.

See also