storage/src/mozStorageAsyncStatement.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is Oracle Corporation code.
  17  *
  18  * The Initial Developer of the Original Code is
  19  *  Oracle Corporation
  20  * Portions created by the Initial Developer are Copyright (C) 2004
  21  * the Initial Developer. All Rights Reserved.
  22  *
  23  * Contributor(s):
  24  *   Vladimir Vukicevic <vladimir.vukicevic@oracle.com>
  25  *   Andrew Sutherland <asutherland@asutherland.org>
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 #ifndef mozilla_storage_mozStorageAsyncStatement_h_
  42 #define mozilla_storage_mozStorageAsyncStatement_h_
  43
  44 #include "nsAutoPtr.h"
  45 #include "nsString.h"
  46
  47 #include "nsTArray.h"
  48
  49 #include "mozStorageBindingParamsArray.h"
  50 #include "mozStorageStatementData.h"
  51 #include "mozIStorageAsyncStatement.h"
  52 #include "StorageBaseStatementInternal.h"
  53
  54 class nsIXPConnectJSObjectHolder;
  55 struct sqlite3_stmt;
  56
  57 namespace mozilla {
  58 namespace storage {
  59
  60 class AsyncStatementJSHelper;
  61 class Connection;
  62
  63 class AsyncStatement : public mozIStorageAsyncStatement
  64                      , public StorageBaseStatementInternal
  65 {
  66 public:
  67   NS_DECL_ISUPPORTS
  68   NS_DECL_MOZISTORAGEASYNCSTATEMENT
  69   NS_DECL_MOZISTORAGEBASESTATEMENT
  70   NS_DECL_MOZISTORAGEBINDINGPARAMS
  71   NS_DECL_STORAGEBASESTATEMENTINTERNAL
  72
  73   AsyncStatement();
  74
  75   /**
  76    * Initializes the object on aDBConnection by preparing the SQL statement
  77    * given by aSQLStatement.
  78    *
  79    * @param aDBConnection
  80    *        The Connection object this statement is associated with.
  81    * @param aSQLStatement
  82    *        The SQL statement to prepare that this object will represent.
  83    */
  84   nsresult initialize(Connection *aDBConnection,
  85                       const nsACString &aSQLStatement);
  86
  87   /**
  88    * Obtains and transfers ownership of the array of parameters that are bound
  89    * to this statment.  This can be null.
  90    */
  91   inline already_AddRefed<BindingParamsArray> bindingParamsArray()
  92   {
  93     return mParamsArray.forget();
  94   }
  95
  96
  97 private:
  98   ~AsyncStatement();
  99
 100   /**
 101    * Clean up the references JS helpers hold to us.  For cycle-avoidance reasons
 102    * they do not hold reference-counted references to us, so it is important
 103    * we do this.
 104    */
 105   void cleanupJSHelpers();
 106
 107   /**
 108    * @return a pointer to the BindingParams object to use with our Bind*
 109    *         method.
 110    */
 111   mozIStorageBindingParams *getParams();
 112
 113   /**
 114    * The SQL string as passed by the user.  We store it because we create the
 115    * async statement on-demand on the async thread.
 116    */
 117   nsCString mSQLString;
 118
 119   /**
 120    * Holds the array of parameters to bind to this statement when we execute
 121    * it asynchronously.
 122    */
 123   nsRefPtr<BindingParamsArray> mParamsArray;
 124
 125   /**
 126    * Caches the JS 'params' helper for this statement.
 127    */
 128   nsCOMPtr<nsIXPConnectJSObjectHolder> mStatementParamsHolder;
 129
 130   /**
 131    * Have we been explicitly finalized by the user?
 132    */
 133   bool mFinalized;
 134
 135   /**
 136    * Required for access to private mStatementParamsHolder field by
 137    * AsyncStatementJSHelper::getParams.
 138    */
 139   friend class AsyncStatementJSHelper;
 140 };
 141
 142 } // storage
 143 } // mozilla
 144
 145 #endif // mozilla_storage_mozStorageAsyncStatement_h_