nsIMsgHeaderParser

nsIMsgHeaderParser

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

??? Add brief description of Interface ???
Inherits from: nsISupports Last changed in Gecko 1.9 (Firefox 3)

To create an instance, use:

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

Method overview

string extractHeaderAddressMailboxes(in string line);
void extractHeaderAddressName(in string line, out string name);
void extractHeaderAddressNames(in string line, out string userNames);
AString makeFullAddress(in AString aName, in AString aAddress);
string makeFullAddressString(in string aName, in string aAddress);
wstring makeFullAddressWString(in wstring name, in wstring addr); Obsolete since Gecko 1.9
void parseHeaderAddresses(in string line, out string names, out string addresses, out PRUint32 numAddresses);
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);
void reformatHeaderAddresses(in string line, out string reformattedAddress);
wstring reformatUnquotedAddresses(in wstring line);
void removeDuplicateAddresses(in string addrs, in string other_addrs, in PRBool removeAliasesToMe, out string newAddress);
string unquotePhraseOrAddr(in string line, in boolean preserveIntegrity);
wstring unquotePhraseOrAddrWString(in wstring line, in boolean preserveIntegrity);

Methods

extractHeaderAddressMailboxes()

Given a string which contains a list of Header addresses, returns a comma-separated list of just the 'mailbox' portions. If any of the addresses doesn't have a mailbox, then the user name 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

Native code only!

extractHeaderAddressNames

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

Native code only!

extractHeaderAddressName

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

Native code only!

makeFullAddressString

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

makeFullAddressWString()

Obsolete since Gecko 1.9 (Firefox 3) 

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

Native code only!

parseHeaderAddresses

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

Native code only!

reformatHeaderAddresses

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

Native code only!

removeDuplicateAddresses

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

Native code only!

unquotePhraseOrAddr

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