summaryrefslogtreecommitdiffstats
path: root/mailnews/import/public/nsIImportAddressBooks.idl
diff options
context:
space:
mode:
Diffstat (limited to 'mailnews/import/public/nsIImportAddressBooks.idl')
-rw-r--r--mailnews/import/public/nsIImportAddressBooks.idl153
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++
+
+%}