/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
%{C++
#define NS_MAILNEWS_MIME_HEADER_PARSER_CONTRACTID \
"@mozilla.org/messenger/headerparser;1"
%}
/**
* A structured representation of an address.
*
* This is meant to correspond to the address production from RFC 5322. As a
* result, an instance of this interface is either a single mailbox or a group
* of mailboxes. The difference between the two forms is in which attribute is
* undefined: mailboxes leave the members attribute undefined while groups leave
* the email attribute undefined.
*
* For example, an address like "John Doe <jdoe@machine.example>" will, when
* parsed, result in an instance with the name attribute set to "John Doe", the
* email attribute set to "jdoe@machine.example", and the members variable left
* undefined.
*
* A group like "undisclosed-recipients:;" will, when parsed, result in an
* instance with the name attribute set to "undisclosed-recipients", the email
* attribute left defined, and the members variable set to an empty array.
*
* In general, the attributes of this interface are always meant to be in a form
* suitable for display purposes, and not in a form usable for MIME emission. In
* particular, email addresses could be fully internationalized and non-ASCII,
* RFC 2047-encoded words may appear in names, and the name or email parameters
* are unquoted.
*/
[scriptable, uuid(b19f5636-ebc4-470e-b46c-98b5fc7e88c9)]
interface msgIAddressObject : nsISupports {
/// The name of the mailbox or group.
readonly attribute AString name;
/// The email of the mailbox.
readonly attribute AString email;
/**
* The member mailboxes of this group, which may be an empty list.
*
* Due to the limitations of XPIDL, the type of this attribute cannot be
* properly reflected. It is actually an array of msgIAddressObject instances,
* although it is instead undefined if this object does not represent a group.
*/
readonly attribute jsval group;
/// Return a string form of this object that is suitable for display.
AString toString();
};
/**
* A utility service for manipulating addressing headers in email messages.
*
* This interface is designed primarily for use from JavaScript code; code in
* C++ should use the methods in MimeHeaderParser.h instead, as it is better
* designed to take advantage of C++'s features, particularly with respect to
* arrays.
*
* There are two methods for parsing MIME headers, one for RFC 2047-decoded
* strings, and one for non-RFC 2047-decoded strings.
*
* In general, this API attempts to preserve the format of addresses as
* faithfully as possible. No case normalization is performed at any point.
* However, internationalized email addresses generally need extra processing to
* work properly, so while this API should handle them without issues, consumers
* of this API may fail to work properly when presented with such addresses. To
* ease use for such cases, future versions of the API may incorporate necessary
* normalization steps to make oblivious consumers more likely to work properly.
*/
[scriptable, uuid(af2f9dd1-0226-4835-b981-a4f88b5e97cc)]
interface nsIMsgHeaderParser : nsISupports {
/**
* Parse an address-based header that has not yet been 2047-decoded.
*
* The result of this method is an array of objects described in the above
* comment. Note that the header is a binary string that will be decoded as if
* passed into nsIMimeConverter.
*
* @param aEncodedHeader The RFC 2047-encoded header to parse.
* @param aHeaderCharset The charset to assume for raw octets.
* @param aPreserveGroups If false (the default), the result is a flat array
* of mailbox objects, containing no group objects.
* @return An array corresponding to the header description.
*/
void parseEncodedHeader(in ACString aEncodedHeader,
in string aHeaderCharset,
[optional] in bool aPreserveGroups,
[optional] out unsigned long length,
[retval, array, size_is(length)]
out msgIAddressObject addresses);
/**
* Parse an address-based header that has not yet been 2047-decoded and does not
* contain raw octets but instead wide (UTF-16) characters.
*
* @param aEncodedHeader The RFC 2047-encoded header to parse.
* @return An array corresponding to the header description.
*/
void parseEncodedHeaderW(in AString aEncodedHeader,
[optional] out unsigned long length,
[retval, array, size_is(length)]
out msgIAddressObject addresses);
/**
* Parse an address-based header that has been 2047-decoded.
*
* The result of this method is an array of objects described in the above
* comment. Note that the header is a binary string that will be decoded as if
* passed into nsIMimeConverter.
*
* @param aDecodedHeader The non-RFC 2047-encoded header to parse.
* @param aPreserveGroups If false (the default), the result is a flat array
* of mailbox objects, containing no group objects.
* @return An array corresponding to the header description.
*/
void parseDecodedHeader(in AString aDecodedHeader,
[optional] in bool aPreserveGroups,
[optional] out unsigned long length,
[retval, array, size_is(length)]
out msgIAddressObject addresses);
/**
* Given an array of addresses, make a MIME header suitable for emission.
*
* The return value of this method is not directly suitable for use in a MIME
* message but rather needs to be passed through nsIMimeConverter first to
* have RFC-2047 encoding applied and the resulting output wrapped to adhere
* to maximum line length formats.
*
* @param aAddresses An array corresponding to the header description.
* @param aLength The length of said array of addresses.
* @return A string that is suitable for writing in a MIME message.
*/
AString makeMimeHeader([array, size_is(aLength)]
in msgIAddressObject aAddresses,
in unsigned long aLength);
/**
* Return the first address in the list in a format suitable for display.
*
* This is largely a convience method for handling From headers (or similar),
* which are expected to only have a single element in them. It is exactly
* equivalent to saying (parseDecodedHeader(decodedHeader))[0].toString().
*
* @param decodedHeader The non-RFC 2047-encoded header to parse.
* @return The first address, suitable for display.
*/
AString extractFirstName(in AString aDecodedHeader);
/**
* Returns a copy of the input which may have had some addresses removed.
* Addresses are removed if they are already in either of the supplied
* address lists.
*
* Addresses are considered to be the same if they contain the same email
* part (case-insensitive). Since the email part should never be RFC
* 2047-encoded, this method should work whether or not the header is
* RFC 2047-encoded.
*
* @param aAddrs The addresses to remove duplicates from.
* @param aOtherAddrs Other addresses that the duplicate removal process also
* checks for duplicates against. Addresses in this list
* will not be added to the result.
* @return The original header with duplicate addresses removed.
*/
AUTF8String removeDuplicateAddresses(in AUTF8String aAddrs,
[optional] in AUTF8String aOtherAddrs);
/// Return a structured mailbox object having the given name and email.
msgIAddressObject makeMailboxObject(in AString aName, in AString aEmail);
/// Return a structured group object having the given name and members.
msgIAddressObject makeGroupObject(in AString aName,
[array, size_is(aLength)] in msgIAddressObject aMembers,
in unsigned long aLength);
/**
* Return an array of structured mailbox objects for the given display name
* string.
*
* The string is expected to be a comma-separated sequence of strings that
* would be produced by msgIAddressObject::toString(). For example, the string
* "Bond, James <agent007@mi5.invalid>" would produce one address object,
* while the string "webmaster@nowhere.invalid, child@nowhere.invalid" would
* produce two address objects.
*/
void makeFromDisplayAddress(in AString aDisplayAddresses,
[optional] out unsigned long count,
[retval, array, size_is(count)] out msgIAddressObject addresses);
[deprecated] 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);
/**
* Given a string which contains a list of Header addresses, returns a
* comma-separated list of just the `mailbox' portions.
*
* @param aLine The header line to parse.
* @return A comma-separated list of just the mailbox parts
* of the email-addresses.
*/
[deprecated] ACString extractHeaderAddressMailboxes(in ACString aLine);
/**
* 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.
*
* @param aLine The header line to parse.
* @return A comma-separated list of just the name parts
* of the addresses.
*/
[deprecated] AUTF8String extractHeaderAddressNames(in AUTF8String aLine);
/*
* Like extractHeaderAddressNames, but only returns the first name in the
* header if there is one. This function will return unquoted strings suitable
* for display.
*
* @param aLine The header line to parse.
* @return The first name found in the list.
*/
[deprecated] AUTF8String extractHeaderAddressName(in AUTF8String aLine);
/**
* Given a name and email address, produce a string that is suitable for
* emitting in a MIME header (after applying RFC 2047 encoding).
*
* @note This is a temporary method.
*/
[deprecated] AString makeMimeAddress(in AString aName, in AString aEmail);
};