Back to index

lightning-sunbird  0.9+nobinonly
nsIMsgHeaderParser.idl
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #include "nsISupports.idl"
00039 #include "nsrootidl.idl"
00040 
00041 interface nsISimpleEnumerator;
00042 
00043 %{C++
00044 
00045 #define NS_MAILNEWS_MIME_HEADER_PARSER_CONTRACTID \
00046   "@mozilla.org/messenger/headerparser;1"
00047 %}
00048 
00049 /* 
00050  * nsIMsgRFCParser Interface declaration 
00051  */ 
00052 [scriptable, uuid(10A88A11-729E-11d2-804A-006008128C4E)]
00053 interface nsIMsgHeaderParser : nsISupports {
00054 
00055   void parseHeadersWithArray(in wstring aLine, 
00056                              [array, size_is(count)] out wstring aEmailAddresses,
00057                              [array, size_is(count)] out wstring aNames,
00058                              [array, size_is(count)] out wstring aFullNames,
00059                              [retval] out unsigned long count);
00060 
00061 
00062   /* Given a string which contains a list of Header addresses, parses it into
00063      their component names and mailboxes.
00064 
00065      The returned value is the number of addresses, or a negative error code;
00066      the names and addresses are returned into the provided pointers as
00067      consecutive null-terminated strings.  It is up to the caller to free them.
00068      Note that some of the strings may be zero-length.
00069 
00070      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00071 
00072      Either of the provided pointers may be NULL if the caller is not interested
00073      in those components.
00074   */
00075   [noscript] void parseHeaderAddresses (in string charset, in string line, out string names, 
00076                              out string addresses, out PRUint32 numAddresses);
00077 
00078   /* Given a string which contains a list of Header addresses, returns a
00079      comma-separated list of just the `mailbox' portions.
00080 
00081      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00082 
00083      Caller must call PL_strfree on returnValue (which is allocated by the function)
00084   */
00085   string extractHeaderAddressMailboxes (in string charset, in string line);
00086 
00087 
00088   /* Given a string which contains a list of Header addresses, returns a
00089      comma-separated list of just the `user name' portions.  If any of
00090      the addresses doesn't have a name, then the mailbox is used instead.
00091 
00092      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00093 
00094      Caller must PL_strfree usernames.
00095   */
00096   [noscript] void extractHeaderAddressNames (in string charset, in string line, out string userNames);
00097 
00098   /* Like MSG_ExtractHeaderAddressNames(), but only returns the first name
00099      in the list, if there is more than one. 
00100      
00101      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00102 
00103      Caller must call PL_strfree on name
00104   */
00105   [noscript] void extractHeaderAddressName (in string charset, in string line, out string name);
00106 
00107   /* Given a string which contains a list of Header addresses, returns a new
00108      string with the same data, but inserts missing commas, parses and reformats
00109      it, and wraps long lines with newline-tab.
00110 
00111      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00112 
00113      Caller must call PL_strfree on reformattedAddress
00114   */
00115   [noscript] void reformatHeaderAddresses (in string charset, in string line, 
00116                                 out string reformattedAddress);
00117 
00118   /* Returns a copy of ADDRS which may have had some addresses removed.
00119      Addresses are removed if they are already in either ADDRS or OTHER_ADDRS.
00120      (If OTHER_ADDRS contain addresses which are not in ADDRS, they are not
00121      added.  That argument is for passing in addresses that were already
00122      mentioned in other header fields.)
00123 
00124      Addresses are considered to be the same if they contain the same mailbox
00125      part (case-insensitive.)  Real names and other comments are not compared.
00126 
00127      removeAliasesToMe allows the address parser to use the preference which
00128      contains regular expressions which also mean 'me' for the purpose of
00129      stripping the user's email address(es) out of addrs
00130 
00131      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00132 
00133      Caller must call PL_strfree on newAddress which is the return value.
00134   */
00135   [noscript] void removeDuplicateAddresses (in string charset,  in string addrs, in string other_addrs, 
00136                                  in PRBool removeAliasesToMe, out string newAddress);
00137 
00138 
00139   /* Given an e-mail address and a person's name, cons them together into a
00140      single string of the form "name <address>", doing all the necessary quoting.
00141      A new string is returned, which you must free when you're done with it.
00142 
00143      The caller may pass nsnull for charset and it will be interpreted as "us-ascii".
00144 
00145      Caller must call PL_strfree on fullAddress (this is the out parameter)
00146   */
00147   [noscript] string makeFullAddress (in string charset, in string name, in string addr);
00148   wstring makeFullAddressWString (in wstring name, in wstring addr);
00149 
00150   /* This function removes the quoting if you want to show the
00151      names to users. e.g. summary file, address book. If preserveIntegrity is set to true,
00152      quote will not be removed in case the name part of the email contains a comma.
00153   */
00154   [noscript] string unquotePhraseOrAddr (in string line, in boolean preserveIntegrity);
00155   wstring unquotePhraseOrAddrWString (in wstring line, in boolean preserveIntegrity);
00156 
00157   /* Given a string, will make it safe to use by adding missing quote and escaping needed quote */
00158   wstring reformatUnquotedAddresses(in wstring line);
00159 };
00160