Revision control
Copy as Markdown
Other Tools
/* -*- 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
/**
* 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 nsIImportABDescriptor;
interface nsIAbDirectory;
[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 address book".
* If false, getDefaultLocation will be called.
*/
boolean GetAutoFind(out wstring description);
/**
* The default location for address book data of this type.
*/
nsIFile getDefaultLocation();
/**
* Returns an array containing an nsIImportABDescriptor for each
* address book. The array is not sorted before display to the user.
* location is null if GetAutoFind returned true.
*/
Array<nsIImportABDescriptor> findAddressBooks(in nsIFile location);
/**
* 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 address 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 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 nsIAbDirectory aDestination,
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();
};