michael@0: /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- michael@0: * vim: sw=2 ts=2 sts=2 et michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsISupports.idl" michael@0: #include "mozIStorageBindingParams.idl" michael@0: michael@0: interface mozIStorageConnection; michael@0: interface mozIStorageStatementCallback; michael@0: interface mozIStoragePendingStatement; michael@0: interface mozIStorageBindingParams; michael@0: interface mozIStorageBindingParamsArray; michael@0: michael@0: /** michael@0: * The base interface for both pure asynchronous storage statements michael@0: * (mozIStorageAsyncStatement) and 'classic' storage statements michael@0: * (mozIStorageStatement) that can be used for both synchronous and asynchronous michael@0: * purposes. michael@0: */ michael@0: [scriptable, uuid(5d34f333-ed3f-4aa2-ba51-f2a8b0cfa33a)] michael@0: interface mozIStorageBaseStatement : mozIStorageBindingParams { michael@0: /** michael@0: * Finalizes a statement so you can successfully close a database connection. michael@0: * Once a statement has been finalized it can no longer be used for any michael@0: * purpose. michael@0: * michael@0: * Statements are implicitly finalized when their reference counts hits zero. michael@0: * If you are a native (C++) caller this is accomplished by setting all of michael@0: * your nsCOMPtr instances to be NULL. If you are operating from JavaScript michael@0: * code then you cannot rely on this behavior because of the involvement of michael@0: * garbage collection. michael@0: * michael@0: * When finalizing an asynchronous statement you do not need to worry about michael@0: * whether the statement has actually been executed by the asynchronous michael@0: * thread; you just need to call finalize after your last call to executeAsync michael@0: * involving the statement. However, you do need to use asyncClose instead of michael@0: * close on the connection if any statements have been used asynchronously. michael@0: */ michael@0: void finalize(); michael@0: michael@0: /** michael@0: * Bind the given value at the given numeric index. michael@0: * michael@0: * @param aParamIndex michael@0: * 0-based index, 0 corresponding to the first numbered argument or michael@0: * "?1". michael@0: * @param aValue michael@0: * Argument value. michael@0: * @param aValueSize michael@0: * Length of aValue in bytes. michael@0: * @{ michael@0: */ michael@0: [deprecated] void bindUTF8StringParameter(in unsigned long aParamIndex, michael@0: in AUTF8String aValue); michael@0: [deprecated] void bindStringParameter(in unsigned long aParamIndex, michael@0: in AString aValue); michael@0: [deprecated] void bindDoubleParameter(in unsigned long aParamIndex, michael@0: in double aValue); michael@0: [deprecated] void bindInt32Parameter(in unsigned long aParamIndex, michael@0: in long aValue); michael@0: [deprecated] void bindInt64Parameter(in unsigned long aParamIndex, michael@0: in long long aValue); michael@0: [deprecated] void bindNullParameter(in unsigned long aParamIndex); michael@0: [deprecated] void bindBlobParameter( michael@0: in unsigned long aParamIndex, michael@0: [array,const,size_is(aValueSize)] in octet aValue, michael@0: in unsigned long aValueSize); michael@0: [deprecated] void bindAdoptedBlobParameter( michael@0: in unsigned long aParamIndex, michael@0: [array,size_is(aValueSize)] in octet aValue, michael@0: in unsigned long aValueSize); michael@0: /**@}*/ michael@0: michael@0: /** michael@0: * Binds the array of parameters to the statement. When executeAsync is michael@0: * called, all the parameters in aParameters are bound and then executed. michael@0: * michael@0: * @param aParameters michael@0: * The array of parameters to bind to the statement upon execution. michael@0: * michael@0: * @note This is only works on statements being used asynchronously. michael@0: */ michael@0: void bindParameters(in mozIStorageBindingParamsArray aParameters); michael@0: michael@0: /** michael@0: * Creates a new mozIStorageBindingParamsArray that can be used to bind michael@0: * multiple sets of data to a statement with bindParameters. michael@0: * michael@0: * @return a mozIStorageBindingParamsArray that multiple sets of parameters michael@0: * can be bound to. michael@0: * michael@0: * @note This is only useful for statements being used asynchronously. michael@0: */ michael@0: mozIStorageBindingParamsArray newBindingParamsArray(); michael@0: michael@0: /** michael@0: * Execute a query asynchronously using any currently bound parameters. This michael@0: * statement can be reused immediately, and reset does not need to be called. michael@0: * michael@0: * @note If you have any custom defined functions, they must be re-entrant michael@0: * since they can be called on multiple threads. michael@0: * michael@0: * @param aCallback [optional] michael@0: * The callback object that will be notified of progress, errors, and michael@0: * completion. michael@0: * @return an object that can be used to cancel the statements execution. michael@0: */ michael@0: mozIStoragePendingStatement executeAsync( michael@0: [optional] in mozIStorageStatementCallback aCallback michael@0: ); michael@0: michael@0: /** michael@0: * The statement is not usable, either because it failed to initialize or michael@0: * was explicitly finalized. michael@0: */ michael@0: const long MOZ_STORAGE_STATEMENT_INVALID = 0; michael@0: /** michael@0: * The statement is usable. michael@0: */ michael@0: const long MOZ_STORAGE_STATEMENT_READY = 1; michael@0: /** michael@0: * Indicates that the statement is executing and the row getters may be used. michael@0: * michael@0: * @note This is only relevant for mozIStorageStatement instances being used michael@0: * in a synchronous fashion. michael@0: */ michael@0: const long MOZ_STORAGE_STATEMENT_EXECUTING = 2; michael@0: michael@0: /** michael@0: * Find out whether the statement is usable (has not been finalized). michael@0: */ michael@0: readonly attribute long state; michael@0: michael@0: /** michael@0: * Escape a string for SQL LIKE search. michael@0: * michael@0: * @note Consumers will have to use same escape char when doing statements michael@0: * such as: ...LIKE '?1' ESCAPE '/'... michael@0: * michael@0: * @param aValue michael@0: * The string to escape for SQL LIKE. michael@0: * @param aEscapeChar michael@0: * The escape character. michael@0: * @return an AString of an escaped version of aValue michael@0: * (%, _ and the escape char are escaped with the escape char) michael@0: * For example, we will convert "foo/bar_baz%20cheese" michael@0: * into "foo//bar/_baz/%20cheese" (if the escape char is '/'). michael@0: */ michael@0: AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar); michael@0: };