mirror of
https://repo.dactyloidae.xyz/Dactyloidae/UXP.git
synced 2026-09-25 09:57:32 +09:00
244 lines
11 KiB
Text
244 lines
11 KiB
Text
/* -*- 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);
|
|
};
|
|
|