gecko-dev/mailnews/mime/public/nsIMsgHeaderParser.idl

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"
#include "nsrootidl.idl"

interface nsISimpleEnumerator;

%{C++
// {932C53A5-F398-11d2-82B7-444553540002}
#define NS_MSGHEADERPARSER_CID \
        { 0x932c53a5, 0xf398, 0x11d2, \
        { 0x82, 0xb7, 0x44, 0x45, 0x53, 0x54, 0x0, 0x2 } }
%}

// This small nifty little interface helps make nsIMsgHeaderParser
// more useable from an xpconnect point of view. 
[scriptable, uuid(8987735B-C239-11d3-98AD-001083010E9B)]
interface nsIMsgHeaderParserResult : nsISupports {
	wstring getAddressAndName(out wstring address, out wstring name);
	readonly attribute unsigned long currentResultNumber;
	readonly attribute unsigned long totalNumberOfResults; 
};

/* 
 * nsIMsgRFCParser Interface declaration 
 */ 
[scriptable, uuid(10A88A11-729E-11d2-804A-006008128C4E)]
interface nsIMsgHeaderParser : nsISupports {
	// This is a version of ParseHeaderAddresses which is much easier to use
	// from xp connect. Basically, you get an enumerator back which you use
	// to enumerate over the parsed header objects. QI each object returned by
	// the enumerator for nsIMsgHeaderParserResult and you can ask it anything
	// you want =).

	nsISimpleEnumerator ParseHeadersWithEnumerator(in wstring line);

	/* 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 charset, in string line, out string names, 
	                           out string addresses, out PRUint32 numAddresses);

	/* Given a string which contains a list of Header addresses, returns a
	   comma-seperated list of just the `mailbox' portions.

     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

	   Caller must call PL_strfree on returnValue (which is allocated by the function)
    */
	void ExtractHeaderAddressMailboxes (in string charset, in string line, out string mailboxes);


	/* Given a string which contains a list of Header addresses, returns a
	   comma-seperated list of just the `user name' portions.  If any of
	   the addresses doesn't have a name, then the mailbox is used instead.

     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

	   Caller must PL_strfree usernames.
	 */
	void ExtractHeaderAddressNames (in string charset, in string line, out string userNames);

	/* Like MSG_ExtractHeaderAddressNames(), but only returns the first name
	   in the list, if there is more than one. 
	   
     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

	   Caller must call PL_strfree on name
	 */
	void ExtractHeaderAddressName (in string charset, in string line, out string name);

	/* 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.

     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

       Caller must call PL_strfree on reformattedAddress
	 */
	void ReformatHeaderAddresses (in string charset, in string line, 
	                              out string reformattedAddress);

	/* 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

     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

       Caller must call PL_strfree on newAddress which is the return value.
	 */
	void RemoveDuplicateAddresses (in string charset,  in string addrs, in string other_addrs, 
	                               in PRBool removeAliasesToMe, out string newAddress);


	/* Given an e-mail address and a person's name, cons them together into a
	   single string of the form "name <address>", doing all the necessary quoting.
	   A new string is returned, which you must free when you're done with it.

     The caller may pass nsnull for charset and it will be interpreted as "us-ascii".

       Caller must call PL_strfree on fullAddress (this is the out parameter)
	 */
	string MakeFullAddress (in string charset, in string name, in string addr);

	/* MSG_ParseHeaderAddresses returns quoted parsable addresses
	   This function removes the quoting if you want to show the
	   names to users. e.g. summary file, address book
	 */
	void UnquotePhraseOrAddr (in string charset, in string line, out string lineout);
};