storage/public/mozIStorageBaseStatement.idl@8bccb770b82d (annotated)
storage/public/mozIStorageBaseStatement.idl
Wed, 31 Dec 2014 13:27:57 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 13:27:57 +0100
- branch
- TOR_BUG_3246
- changeset 6
- 8bccb770b82d
- permissions
- -rw-r--r--
Ignore runtime configuration files generated during quality assurance.
| michael@0 | 1 | /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- |
| michael@0 | 2 | * vim: sw=2 ts=2 sts=2 et |
| michael@0 | 3 | * This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 4 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 5 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 6 | |
| michael@0 | 7 | #include "nsISupports.idl" |
| michael@0 | 8 | #include "mozIStorageBindingParams.idl" |
| michael@0 | 9 | |
| michael@0 | 10 | interface mozIStorageConnection; |
| michael@0 | 11 | interface mozIStorageStatementCallback; |
| michael@0 | 12 | interface mozIStoragePendingStatement; |
| michael@0 | 13 | interface mozIStorageBindingParams; |
| michael@0 | 14 | interface mozIStorageBindingParamsArray; |
| michael@0 | 15 | |
| michael@0 | 16 | /** |
| michael@0 | 17 | * The base interface for both pure asynchronous storage statements |
| michael@0 | 18 | * (mozIStorageAsyncStatement) and 'classic' storage statements |
| michael@0 | 19 | * (mozIStorageStatement) that can be used for both synchronous and asynchronous |
| michael@0 | 20 | * purposes. |
| michael@0 | 21 | */ |
| michael@0 | 22 | [scriptable, uuid(5d34f333-ed3f-4aa2-ba51-f2a8b0cfa33a)] |
| michael@0 | 23 | interface mozIStorageBaseStatement : mozIStorageBindingParams { |
| michael@0 | 24 | /** |
| michael@0 | 25 | * Finalizes a statement so you can successfully close a database connection. |
| michael@0 | 26 | * Once a statement has been finalized it can no longer be used for any |
| michael@0 | 27 | * purpose. |
| michael@0 | 28 | * |
| michael@0 | 29 | * Statements are implicitly finalized when their reference counts hits zero. |
| michael@0 | 30 | * If you are a native (C++) caller this is accomplished by setting all of |
| michael@0 | 31 | * your nsCOMPtr instances to be NULL. If you are operating from JavaScript |
| michael@0 | 32 | * code then you cannot rely on this behavior because of the involvement of |
| michael@0 | 33 | * garbage collection. |
| michael@0 | 34 | * |
| michael@0 | 35 | * When finalizing an asynchronous statement you do not need to worry about |
| michael@0 | 36 | * whether the statement has actually been executed by the asynchronous |
| michael@0 | 37 | * thread; you just need to call finalize after your last call to executeAsync |
| michael@0 | 38 | * involving the statement. However, you do need to use asyncClose instead of |
| michael@0 | 39 | * close on the connection if any statements have been used asynchronously. |
| michael@0 | 40 | */ |
| michael@0 | 41 | void finalize(); |
| michael@0 | 42 | |
| michael@0 | 43 | /** |
| michael@0 | 44 | * Bind the given value at the given numeric index. |
| michael@0 | 45 | * |
| michael@0 | 46 | * @param aParamIndex |
| michael@0 | 47 | * 0-based index, 0 corresponding to the first numbered argument or |
| michael@0 | 48 | * "?1". |
| michael@0 | 49 | * @param aValue |
| michael@0 | 50 | * Argument value. |
| michael@0 | 51 | * @param aValueSize |
| michael@0 | 52 | * Length of aValue in bytes. |
| michael@0 | 53 | * @{ |
| michael@0 | 54 | */ |
| michael@0 | 55 | [deprecated] void bindUTF8StringParameter(in unsigned long aParamIndex, |
| michael@0 | 56 | in AUTF8String aValue); |
| michael@0 | 57 | [deprecated] void bindStringParameter(in unsigned long aParamIndex, |
| michael@0 | 58 | in AString aValue); |
| michael@0 | 59 | [deprecated] void bindDoubleParameter(in unsigned long aParamIndex, |
| michael@0 | 60 | in double aValue); |
| michael@0 | 61 | [deprecated] void bindInt32Parameter(in unsigned long aParamIndex, |
| michael@0 | 62 | in long aValue); |
| michael@0 | 63 | [deprecated] void bindInt64Parameter(in unsigned long aParamIndex, |
| michael@0 | 64 | in long long aValue); |
| michael@0 | 65 | [deprecated] void bindNullParameter(in unsigned long aParamIndex); |
| michael@0 | 66 | [deprecated] void bindBlobParameter( |
| michael@0 | 67 | in unsigned long aParamIndex, |
| michael@0 | 68 | [array,const,size_is(aValueSize)] in octet aValue, |
| michael@0 | 69 | in unsigned long aValueSize); |
| michael@0 | 70 | [deprecated] void bindAdoptedBlobParameter( |
| michael@0 | 71 | in unsigned long aParamIndex, |
| michael@0 | 72 | [array,size_is(aValueSize)] in octet aValue, |
| michael@0 | 73 | in unsigned long aValueSize); |
| michael@0 | 74 | /**@}*/ |
| michael@0 | 75 | |
| michael@0 | 76 | /** |
| michael@0 | 77 | * Binds the array of parameters to the statement. When executeAsync is |
| michael@0 | 78 | * called, all the parameters in aParameters are bound and then executed. |
| michael@0 | 79 | * |
| michael@0 | 80 | * @param aParameters |
| michael@0 | 81 | * The array of parameters to bind to the statement upon execution. |
| michael@0 | 82 | * |
| michael@0 | 83 | * @note This is only works on statements being used asynchronously. |
| michael@0 | 84 | */ |
| michael@0 | 85 | void bindParameters(in mozIStorageBindingParamsArray aParameters); |
| michael@0 | 86 | |
| michael@0 | 87 | /** |
| michael@0 | 88 | * Creates a new mozIStorageBindingParamsArray that can be used to bind |
| michael@0 | 89 | * multiple sets of data to a statement with bindParameters. |
| michael@0 | 90 | * |
| michael@0 | 91 | * @return a mozIStorageBindingParamsArray that multiple sets of parameters |
| michael@0 | 92 | * can be bound to. |
| michael@0 | 93 | * |
| michael@0 | 94 | * @note This is only useful for statements being used asynchronously. |
| michael@0 | 95 | */ |
| michael@0 | 96 | mozIStorageBindingParamsArray newBindingParamsArray(); |
| michael@0 | 97 | |
| michael@0 | 98 | /** |
| michael@0 | 99 | * Execute a query asynchronously using any currently bound parameters. This |
| michael@0 | 100 | * statement can be reused immediately, and reset does not need to be called. |
| michael@0 | 101 | * |
| michael@0 | 102 | * @note If you have any custom defined functions, they must be re-entrant |
| michael@0 | 103 | * since they can be called on multiple threads. |
| michael@0 | 104 | * |
| michael@0 | 105 | * @param aCallback [optional] |
| michael@0 | 106 | * The callback object that will be notified of progress, errors, and |
| michael@0 | 107 | * completion. |
| michael@0 | 108 | * @return an object that can be used to cancel the statements execution. |
| michael@0 | 109 | */ |
| michael@0 | 110 | mozIStoragePendingStatement executeAsync( |
| michael@0 | 111 | [optional] in mozIStorageStatementCallback aCallback |
| michael@0 | 112 | ); |
| michael@0 | 113 | |
| michael@0 | 114 | /** |
| michael@0 | 115 | * The statement is not usable, either because it failed to initialize or |
| michael@0 | 116 | * was explicitly finalized. |
| michael@0 | 117 | */ |
| michael@0 | 118 | const long MOZ_STORAGE_STATEMENT_INVALID = 0; |
| michael@0 | 119 | /** |
| michael@0 | 120 | * The statement is usable. |
| michael@0 | 121 | */ |
| michael@0 | 122 | const long MOZ_STORAGE_STATEMENT_READY = 1; |
| michael@0 | 123 | /** |
| michael@0 | 124 | * Indicates that the statement is executing and the row getters may be used. |
| michael@0 | 125 | * |
| michael@0 | 126 | * @note This is only relevant for mozIStorageStatement instances being used |
| michael@0 | 127 | * in a synchronous fashion. |
| michael@0 | 128 | */ |
| michael@0 | 129 | const long MOZ_STORAGE_STATEMENT_EXECUTING = 2; |
| michael@0 | 130 | |
| michael@0 | 131 | /** |
| michael@0 | 132 | * Find out whether the statement is usable (has not been finalized). |
| michael@0 | 133 | */ |
| michael@0 | 134 | readonly attribute long state; |
| michael@0 | 135 | |
| michael@0 | 136 | /** |
| michael@0 | 137 | * Escape a string for SQL LIKE search. |
| michael@0 | 138 | * |
| michael@0 | 139 | * @note Consumers will have to use same escape char when doing statements |
| michael@0 | 140 | * such as: ...LIKE '?1' ESCAPE '/'... |
| michael@0 | 141 | * |
| michael@0 | 142 | * @param aValue |
| michael@0 | 143 | * The string to escape for SQL LIKE. |
| michael@0 | 144 | * @param aEscapeChar |
| michael@0 | 145 | * The escape character. |
| michael@0 | 146 | * @return an AString of an escaped version of aValue |
| michael@0 | 147 | * (%, _ and the escape char are escaped with the escape char) |
| michael@0 | 148 | * For example, we will convert "foo/bar_baz%20cheese" |
| michael@0 | 149 | * into "foo//bar/_baz/%20cheese" (if the escape char is '/'). |
| michael@0 | 150 | */ |
| michael@0 | 151 | AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar); |
| michael@0 | 152 | }; |
