/* -*- 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 " 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 " 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); };