mailnews/mime/public/nsIMsgHeaderParser.idl
author Mozilla Releng Treescript <release+treescript@mozilla.org>
Sun, 26 Sep 2021 08:37:27 +0000
changeset 43964 a7b58a9f45f455e51ba9e4852eb08ea758a4c43e
parent 36221 471b8c1ca0f42fcf72ce060549f39c4b72ed5986
permissions -rw-r--r--
no bug - Bumping Thunderbird l10n changesets r=release a=l10n-bump DONTBUILD de -> 25fd973fe9a42d37b0377bfa6c741884ae5d7312 fi -> c90b1da58e538eac8aa0ed2e4d4e31a9770268b0 nn-NO -> b660bb0581711d00cb41015a08b17915e53d1bad pl -> 3af2f0351642c288b303e2507d7ef65d5a6e18b0 pt-BR -> 89625013d9161397441b0526d8892cd6f533e0e6 sl -> abf2ca8c4883ff43ad269fc35563c83ed715281b sv-SE -> 8ccbec862b89298ab70e1050ef574a7058552d6a tr -> ca7bac944dbb4179f6d89953547b05bbddc4128d

/* -*- 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.
   */
  Array<msgIAddressObject> parseEncodedHeader(in ACString aEncodedHeader,
                          [optional] in string aHeaderCharset,
                          [optional] in bool aPreserveGroups);

  /**
   * 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.
   */
  Array<msgIAddressObject> parseEncodedHeaderW(in AString aEncodedHeader);

/**
   * 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.
   */
   Array<msgIAddressObject> parseDecodedHeader(in AString aDecodedHeader,
                          [optional] in bool aPreserveGroups);

  /**
   * 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.
   * @return           A string that is suitable for writing in a MIME message.
   */
  AString makeMimeHeader(in Array<msgIAddressObject> aAddresses);

  /**
   * Return the first address in the list in a format suitable for display.
   *
   * This is largely a convenience 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,
                                    in Array<msgIAddressObject> aMembers);

  /**
   * 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.
   */
  Array<msgIAddressObject> makeFromDisplayAddress(in AString aDisplayAddresses);

  /**
   * 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.
   */
  ACString extractHeaderAddressMailboxes(in ACString 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);
};