diff options
Diffstat (limited to 'mailnews/import/public/nsIImportAddressBooks.idl')
| -rw-r--r-- | mailnews/import/public/nsIImportAddressBooks.idl | 153 |
1 files changed, 153 insertions, 0 deletions
diff --git a/mailnews/import/public/nsIImportAddressBooks.idl b/mailnews/import/public/nsIImportAddressBooks.idl new file mode 100644 index 000000000..a6f9a7800 --- /dev/null +++ b/mailnews/import/public/nsIImportAddressBooks.idl @@ -0,0 +1,153 @@ +/* -*- 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/. */ + +/* + Interface for importing address books using the standard UI. Address + book import occurs in several forms (yuck!). + The destination can be 1..n new address books corresponding to the source + format. For instance a text file would import into a new address book + with the same name as the text file. + The destination can be 1 pre-defined address book, all entries will be + added to the supplied address book - this allows the address book UI so provide + an import command specific for an individual address book. + + The source can import 1 or multiple address books. + The address books can be auto-discoverable or user specified. + The address books can require field mapping or not. + + All of this is rather complicated but it should work out OK. + 1) The first UI + panel will allow selection of the address book and will indicate to the user + if the address book will be imported into an existing address book or new address + books. (This could be 2 separate xul UI's?). + 2) The second panel will show field mapping if it is required - if it is required then + there will be one panel per address book for formats that support multiple + address books. If it is not required then there will be no second panel. + 3) Show the progress dialog for the import - this could be per address book if + mapping is required? what to do, what to doooooo..... + 4) All done, maybe a what was done panel?? +*/ + +#include "nsISupports.idl" + +interface nsIFile; +interface nsIArray; +interface nsIImportABDescriptor; +interface nsIAddrDatabase; +interface nsIImportFieldMap; + +[scriptable, uuid(6bba48be-331c-41e3-bc9f-c2ea3754d977)] +interface nsIImportAddressBooks : nsISupports +{ + + /* + Does this interface supports 1 or 1..n address books. You only + get to choose 1 location so for formats where 1..n address books + are imported from a directory, then return true. For a 1 to 1 relationship + between location and address books return false. + */ + boolean GetSupportsMultiple(); + + /* + If the address book is not found via a file location.then return true + along with a description string of how or where the address book is + located. If it is a file location then return false. + If true, return a string like: "Outlook Express standard address book, + also known as the Windows address book" or just "Outlook Express address book". + If false, GetDefaultLocation will be called. + */ + + boolean GetAutoFind( out wstring description); + + /* + Returns true if the address book needs the user to specify a field map + for address books imported from this format. + */ + boolean GetNeedsFieldMap( in nsIFile location); + + /* + If found and userVerify BOTH return false, then it is assumed that this + means an error - address book cannot be found on this machine. + If userVerify is true, the user will have an opportunity to specify + a different location to import address book from. + */ + void GetDefaultLocation( out nsIFile location, + out boolean found, + out boolean userVerify); + /* + Returns an nsIArray which contains an nsIImportABDescriptor for each + address book. The array is not sorted before display to the user. + location is null if GetAutoFind returned true. + */ + nsIArray FindAddressBooks(in nsIFile location); + + /* + Fill in defaults (if any) for a field map for importing address + books from this location. + */ + void InitFieldMap(in nsIImportFieldMap fieldMap); + + /** + * Import a specific address book into the destination file supplied. + * If an error occurs that is non-fatal, the destination will be deleted and + * other adress book will be imported. If a fatal error occurs, the + * destination will be deleted and the import operation will abort. + * + * @param aSource The source data for the import. + * @param aDestination The proxy database for the destination of the + * import. + * @param aFieldMap The field map containing the mapping of fields to be + * used in cvs and tab type imports. + * @param aSupportService An optional proxy support service (nullptr is + * acceptable if it is not required), may be required + * for certain import types (e.g. nsIAbLDIFService for + * LDIF import). + * @param aErrorLog The error log from the import. + * @param aSuccessLog The success log from the import. + * @param aFatalError True if there was a fatal error doing the import. + */ + void ImportAddressBook(in nsIImportABDescriptor aSource, + in nsIAddrDatabase aDestination, + in nsIImportFieldMap aFieldMap, + in nsISupports aSupportService, + out wstring aErrorLog, + out wstring aSuccessLog, + out boolean aFatalError); + + /* + Return the amount of the address book that has been imported so far. This number + is used to present progress information and must never be larger than the + size specified in nsIImportABDescriptor.GetSize(); May be called from + a different thread than ImportAddressBook() + */ + unsigned long GetImportProgress(); + + /* + Set the location for reading sample data, this should be the same + as what is passed later to FindAddressBooks + */ + void SetSampleLocation( in nsIFile location); + + /* + * Return a string of sample data for a record, each field + * is separated by a newline (which means no newlines in the fields!) + * This is only supported by address books which use field maps and + * is used by the field map UI to allow the user to properly + * align fields to be imported. + * + * @param recordNumber index of the recrds, starting from 0. + * @param recordExists true if the record exists. + * + * @returns a string of sample data for the desired record + */ + wstring GetSampleData(in long recordNumber, out boolean recordExists); + +}; + + + +%{ C++ + +%} |