mozIStorageBaseStatement.idl (4799B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- 2 * vim: sw=2 ts=2 sts=2 et 3 * This Source Code Form is subject to the terms of the Mozilla Public 4 * License, v. 2.0. If a copy of the MPL was not distributed with this 5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 6 7 #include "nsISupports.idl" 8 #include "mozIStorageBindingParams.idl" 9 10 interface mozIStorageConnection; 11 interface mozIStorageStatementCallback; 12 interface mozIStoragePendingStatement; 13 interface mozIStorageBindingParams; 14 interface mozIStorageBindingParamsArray; 15 16 /** 17 * The base interface for both pure asynchronous storage statements 18 * (mozIStorageAsyncStatement) and 'classic' storage statements 19 * (mozIStorageStatement) that can be used for both synchronous and asynchronous 20 * purposes. 21 */ 22 [scriptable, builtinclass, uuid(16ca67aa-1325-43e2-aac7-859afd1590b2)] 23 interface mozIStorageBaseStatement : mozIStorageBindingParams { 24 /** 25 * Finalizes a statement so you can successfully close a database connection. 26 * Once a statement has been finalized it can no longer be used for any 27 * purpose. 28 * 29 * Statements are implicitly finalized when their reference counts hits zero. 30 * If you are a native (C++) caller this is accomplished by setting all of 31 * your nsCOMPtr instances to be NULL. If you are operating from JavaScript 32 * code then you cannot rely on this behavior because of the involvement of 33 * garbage collection. 34 * 35 * When finalizing an asynchronous statement you do not need to worry about 36 * whether the statement has actually been executed by the asynchronous 37 * thread; you just need to call finalize after your last call to executeAsync 38 * involving the statement. However, you do need to use asyncClose instead of 39 * close on the connection if any statements have been used asynchronously. 40 */ 41 void finalize(); 42 43 /** 44 * Binds the array of parameters to the statement. When executeAsync is 45 * called, all the parameters in aParameters are bound and then executed. 46 * 47 * @param aParameters 48 * The array of parameters to bind to the statement upon execution. 49 * 50 * @note This is only works on statements being used asynchronously. 51 */ 52 void bindParameters(in mozIStorageBindingParamsArray aParameters); 53 54 /** 55 * Creates a new mozIStorageBindingParamsArray that can be used to bind 56 * multiple sets of data to a statement with bindParameters. 57 * 58 * @return a mozIStorageBindingParamsArray that multiple sets of parameters 59 * can be bound to. 60 * 61 * @note This is only useful for statements being used asynchronously. 62 */ 63 mozIStorageBindingParamsArray newBindingParamsArray(); 64 65 /** 66 * Execute a query asynchronously using any currently bound parameters. This 67 * statement can be reused immediately, and reset does not need to be called. 68 * 69 * @note If you have any custom defined functions, they must be re-entrant 70 * since they can be called on multiple threads. 71 * 72 * @param aCallback [optional] 73 * The callback object that will be notified of progress, errors, and 74 * completion. 75 * @return an object that can be used to cancel the statements execution. 76 */ 77 mozIStoragePendingStatement executeAsync( 78 [optional] in mozIStorageStatementCallback aCallback 79 ); 80 81 /** 82 * The statement is not usable, either because it failed to initialize or 83 * was explicitly finalized. 84 */ 85 const long MOZ_STORAGE_STATEMENT_INVALID = 0; 86 /** 87 * The statement is usable. 88 */ 89 const long MOZ_STORAGE_STATEMENT_READY = 1; 90 /** 91 * Indicates that the statement is executing and the row getters may be used. 92 * 93 * @note This is only relevant for mozIStorageStatement instances being used 94 * in a synchronous fashion. 95 */ 96 const long MOZ_STORAGE_STATEMENT_EXECUTING = 2; 97 98 /** 99 * Find out whether the statement is usable (has not been finalized). 100 */ 101 readonly attribute long state; 102 103 /** 104 * Escape a string for SQL LIKE search. 105 * 106 * @note Consumers will have to use same escape char when doing statements 107 * such as: ...LIKE '?1' ESCAPE '/'... 108 * 109 * @param aValue 110 * The string to escape for SQL LIKE. 111 * @param aEscapeChar 112 * The escape character. 113 * @return an AString of an escaped version of aValue 114 * (%, _ and the escape char are escaped with the escape char) 115 * For example, we will convert "foo/bar_baz%20cheese" 116 * into "foo//bar/_baz/%20cheese" (if the escape char is '/'). 117 */ 118 AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar); 119 120 /** 121 * The same as above, but for UTF8 strings. 122 */ 123 AUTF8String escapeUTF8StringForLIKE(in AUTF8String aValue, 124 in char aEscapeChar); 125 };