Back to index

lightning-sunbird  0.9+nobinonly
nsIImportAddressBooks.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 /*
00039 
00040   Interface for importing address books using the standard UI.  Address
00041   book import occurs in several forms (yuck!).
00042   The destination can be 1..n new address books corresponding to the source
00043   format.  For instance a text file would import into a new address book
00044   with the same name as the text file, Eudora may import multiple address books
00045   with the same names as the ones in Eudora.
00046   The destination can be 1 pre-defined address book, all entries will be 
00047   added to the supplied address book - this allows the address book UI so provide
00048   an import command specific for an individual address book.
00049   
00050   The source can import 1 or mulitple address books.
00051   The address books can be auto-discoverable or user specified.
00052   The address books can require field mapping or not.
00053   
00054   All of this is rather complicated but it should work out OK.  
00055   1) The first UI
00056   panel will allow selection of the address book and will indicate to the user
00057   if the address book will be imported into an existing address book or new address
00058   books.  (This could be 2 separate xul UI's?).
00059   2) The second panel will show field mapping if it is required - if it is required then
00060   there will be one panel per address book for formats that support multiple
00061   address books.  If it is not required then there will be no second panel.
00062   3) Show the progress dialog for the import - this could be per address book if
00063   mapping is required? what to do, what to doooooo.....
00064   4) All done, maybe a what was done panel??
00065   
00066 
00067 */
00068 
00069 /*
00070 */
00071 
00072 /*
00073               
00074 */
00075 
00076 #include "nsISupports.idl"
00077 
00078 interface     nsIFileSpec;
00079 interface     nsISupportsArray;
00080 interface     nsIImportABDescriptor;
00081 interface     nsIOutputStream;
00082 interface     nsIAddrDatabase;
00083 interface     nsIImportFieldMap;
00084 
00085 [scriptable, uuid(3fe29be0-3539-11d3-a206-00a0cc26da63)]
00086 interface nsIImportAddressBooks : nsISupports
00087 {      
00088        
00089        /*
00090               Does this interface supports 1 or 1..n address books.  You only
00091               get to choose 1 location so for formats where 1..n address books
00092               are imported from a directory, then return true.  For a 1 to 1 relationship
00093               between location and address books return false.
00094        */
00095        PRBool GetSupportsMultiple();
00096        
00097        /*
00098               If the address book is not found via a file location.then return true
00099               along with a description string of how or where the address book is
00100               located.  If it is a file location then return false.
00101               If true, return a string like: "Outlook Express standard address book,
00102               also known as the Windows address book" or just "Outlook Express address book".
00103               If false, GetDefaultLocation will be called.
00104        */
00105        
00106        PRBool GetAutoFind( out wstring description);
00107        
00108        /*
00109               Returns true if the address book needs the user to specify a field map
00110               for address books imported from this format.
00111        */
00112        PRBool GetNeedsFieldMap( in nsIFileSpec location);
00113        
00114        /*
00115               If found and userVerify BOTH return false, then it is assumed that this
00116               means an error - mail cannot be found on this machine.
00117               If userVerify is true, the user will have an opportunity to specify
00118               a different location to import mail from.
00119        */
00120        void   GetDefaultLocation( out nsIFileSpec location,
00121                                                         out boolean   found,
00122                                                         out boolean   userVerify);  
00123        /*
00124               Returns an nsISupportsArray which contains an nsIImportABDescriptor for each 
00125               mailbox.  The array is not sorted before display to the user.  location is
00126               null if GetAutoFind returned true.
00127        */
00128        nsISupportsArray FindAddressBooks( in nsIFileSpec location);
00129        
00130        /*
00131               Fill in defaults (if any) for a field map for importing address
00132               books from this location.
00133        */
00134        void InitFieldMap( in nsIFileSpec location, in nsIImportFieldMap fieldMap);
00135        
00136        /*
00137               Import a specific mailbox into the destination file supplied.  If an error
00138               occurs that is non-fatal, the destination will be deleted and other mailbox's
00139               will be imported.  If a fatal error occurs, the destination will be deleted
00140               and the import operation will abort.
00141        */
00142        void   ImportAddressBook(   in nsIImportABDescriptor source, 
00143                                                         in nsIAddrDatabase destination,
00144                                                         in nsIImportFieldMap fieldMap,
00145                                                         in boolean isAddrLocHome,
00146                                                         out wstring errorLog,
00147                                                         out wstring successLog,
00148                                                         out boolean fatalError);
00149        
00150        /*
00151               Return the amount of the address book that has been imported so far.  This number
00152               is used to present progress information and must never be larger than the
00153               size specified in nsIImportABDescriptor.GetSize();  May be called from
00154               a different thread than ImportAddressBook()
00155        */
00156        unsigned long GetImportProgress();
00157 
00158        /*
00159               Set the location for reading sample data, this should be the same
00160               as what is passed later to FindAddressBooks
00161        */
00162        void   SetSampleLocation( in nsIFileSpec location);
00163 
00164        /*
00165               Return a string of sample data for a record, each field
00166               is separated by a newline (which means no newlines in the fields!)
00167               This is only supported by address books which use field maps and
00168               is used by the field map UI to allow the user to properly
00169               align fields to be imported.
00170        */
00171        wstring GetSampleData( in long recordNumber, out boolean recordExists);
00172 
00173 };
00174        
00175 
00176 
00177 %{ C++
00178 
00179 %}