storage/public/mozIStorageService.idl

   1 /* -*- Mode: idl; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* ***** BEGIN LICENSE BLOCK *****
   3  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4  *
   5  * The contents of this file are subject to the Mozilla Public License Version
   6  * 1.1 (the "License"); you may not use this file except in compliance with
   7  * the License. You may obtain a copy of the License at
   8  * http://www.mozilla.org/MPL/
   9  *
  10  * Software distributed under the License is distributed on an "AS IS" basis,
  11  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12  * for the specific language governing rights and limitations under the
  13  * License.
  14  *
  15  * The Original Code is Oracle Corporation code.
  16  *
  17  * The Initial Developer of the Original Code is
  18  *  Oracle Corporation
  19  * Portions created by the Initial Developer are Copyright (C) 2004
  20  * the Initial Developer. All Rights Reserved.
  21  *
  22  * Contributor(s):
  23  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  24  *
  25  * Alternatively, the contents of this file may be used under the terms of
  26  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28  * in which case the provisions of the GPL or the LGPL are applicable instead
  29  * of those above. If you wish to allow use of your version of this file only
  30  * under the terms of either the GPL or the LGPL, and not to allow others to
  31  * use your version of this file under the terms of the MPL, indicate your
  32  * decision by deleting the provisions above and replace them with the notice
  33  * and other provisions required by the GPL or the LGPL. If you do not delete
  34  * the provisions above, a recipient may use your version of this file under
  35  * the terms of any one of the MPL, the GPL or the LGPL.
  36  *
  37  * ***** END LICENSE BLOCK ***** */
  38
  39 #include "nsISupports.idl"
  40
  41 interface mozIStorageConnection;
  42 interface nsIFile;
  43
  44 /**
  45  * The mozIStorageService interface is intended to be implemented by
  46  * a service that can create storage connections (mozIStorageConnection)
  47  * to either a well-known profile database or to a specific database file.
  48  *
  49  * This is the only way to open a database connection.
  50  */
  51 [scriptable, uuid(fe8e95cb-b377-4c8d-bccb-d9198c67542b)]
  52 interface mozIStorageService : nsISupports {
  53   /**
  54    * Get a connection to a named special database storage.
  55    *
  56    * @param aStorageKey a string key identifying the type of storage
  57    * requested.  Valid values include: "profile", "memory".
  58    *
  59    * @see openDatabase for restrictions on how database connections may be
  60    * used. For the profile database, you should only access it from the main
  61    * thread since other callers may also have connections.
  62    *
  63    * @returns a new mozIStorageConnection for the requested
  64    * storage database.
  65    *
  66    * @throws NS_ERROR_INVALID_ARG if aStorageKey is invalid.
  67    */
  68   mozIStorageConnection openSpecialDatabase(in string aStorageKey);
  69
  70   /**
  71    * Open a connection to the specified file.
  72    *
  73    * Consumers should check mozIStorageConnection::connectionReady to ensure
  74    * that they can use the database.  If this value is false, it is strongly
  75    * recommended that the database be backed up with
  76    * mozIStorageConnection::backupDB so user data is not lost.
  77    *
  78    * ==========
  79    *   DANGER
  80    * ==========
  81    *
  82    * If you have more than one connection to a file, you MUST use the EXACT
  83    * SAME NAME for the file each time, including case. The sqlite code uses
  84    * a simple string compare to see if there is already a connection. Opening
  85    * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
  86    *
  87    * The connection object returned by this function is not threadsafe. You must
  88    * use it only from the thread you created it from.
  89    *
  90    * If your database contains virtual tables (f.e. for full-text indexes), you
  91    * must open it with openUnsharedDatabase, as those tables are incompatible
  92    * with a shared cache.  If you attempt to use this method to open a database
  93    * containing virtual tables, it will think the database is corrupted and
  94    * throw NS_ERROR_FILE_CORRUPTED.
  95    *
  96    * @param aDatabaseFile
  97    *        A nsIFile that represents the database that is to be opened..
  98    *
  99    * @returns a mozIStorageConnection for the requested database file.
 100    *
 101    * @throws NS_ERROR_OUT_OF_MEMORY
 102    *         If allocating a new storage object fails.
 103    * @throws NS_ERROR_FILE_CORRUPTED
 104    *         If the database file is corrupted.
 105    */
 106   mozIStorageConnection openDatabase(in nsIFile aDatabaseFile);
 107
 108   /**
 109    * Open a connection to the specified file that doesn't share a sqlite cache.
 110    *
 111    * Each connection uses its own sqlite cache, which is inefficient, so you
 112    * should use openDatabase instead of this method unless you need a feature
 113    * of SQLite that is incompatible with a shared cache, like virtual table
 114    * and full text indexing support.
 115    *
 116    * Consumers should check mozIStorageConnection::connectionReady to ensure
 117    * that they can use the database.  If this value is false, it is strongly
 118    * recommended that the database be backed up with
 119    * mozIStorageConnection::backupDB so user data is not lost.
 120    *
 121    * ==========
 122    *   DANGER
 123    * ==========
 124    *
 125    * If you have more than one connection to a file, you MUST use the EXACT
 126    * SAME NAME for the file each time, including case. The sqlite code uses
 127    * a simple string compare to see if there is already a connection. Opening
 128    * a connection to "Foo.sqlite" and "foo.sqlite" will CORRUPT YOUR DATABASE.
 129    *
 130    * The connection object returned by this function is not threadsafe. You must
 131    * use it only from the thread you created it from.
 132    *
 133    * @param aDatabaseFile
 134    *        A nsIFile that represents the database that is to be opened..
 135    *
 136    * @returns a mozIStorageConnection for the requested database file.
 137    *
 138    * @throws NS_ERROR_OUT_OF_MEMORY
 139    *         If allocating a new storage object fails.
 140    * @throws NS_ERROR_FILE_CORRUPTED
 141    *         If the database file is corrupted.
 142    */
 143   mozIStorageConnection openUnsharedDatabase(in nsIFile aDatabaseFile);
 144
 145   /*
 146    * Utilities
 147    */
 148
 149   /**
 150    * Copies the specified database file to the specified parent directory with
 151    * the specified file name.  If the parent directory is not specified, it
 152    * places the backup in the same directory as the current file.  This function
 153    * ensures that the file being created is unique.
 154    *
 155    * @param aDBFile
 156    *        The database file that will be backed up.
 157    * @param aBackupFileName
 158    *        The name of the new backup file to create.
 159    * @param [optional] aBackupParentDirectory
 160    *        The directory you'd like the backup file to be placed.
 161    * @return The nsIFile representing the backup file.
 162    */
 163   nsIFile backupDatabaseFile(in nsIFile aDBFile, in AString aBackupFileName,
 164                              [optional] in nsIFile aBackupParentDirectory);
 165 };
 166
 167 %{C++
 168
 169 #define MOZ_STORAGE_MEMORY_STORAGE_KEY    "memory"
 170 #define MOZ_STORAGE_PROFILE_STORAGE_KEY   "profile"
 171
 172 %}