/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- * vim: sw=2 ts=2 sts=2 expandtab * ***** BEGIN LICENSE BLOCK ***** * Version: MPL 1.1/GPL 2.0/LGPL 2.1 * * The contents of this file are subject to the Mozilla Public License Version * 1.1 (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License * for the specific language governing rights and limitations under the * License. * * The Original Code is Oracle Corporation code. * * The Initial Developer of the Original Code is * Oracle Corporation * Portions created by the Initial Developer are Copyright (C) 2004 * the Initial Developer. All Rights Reserved. * * Contributor(s): * Vladimir Vukicevic * * Alternatively, the contents of this file may be used under the terms of * either the GNU General Public License Version 2 or later (the "GPL"), or * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"), * in which case the provisions of the GPL or the LGPL are applicable instead * of those above. If you wish to allow use of your version of this file only * under the terms of either the GPL or the LGPL, and not to allow others to * use your version of this file under the terms of the MPL, indicate your * decision by deleting the provisions above and replace them with the notice * and other provisions required by the GPL or the LGPL. If you do not delete * the provisions above, a recipient may use your version of this file under * the terms of any one of the MPL, the GPL or the LGPL. * * ***** END LICENSE BLOCK ***** */ #include "nsISupports.idl" #include "mozIStorageValueArray.idl" interface mozIStorageConnection; interface mozIStorageStatementCallback; interface mozIStoragePendingStatement; interface mozIStorageBindingParamsArray; [scriptable, uuid(20c45bdd-51d4-4f07-b70e-5feaa6302197)] interface mozIStorageStatement : mozIStorageValueArray { /** * Finalizes a statement so you can successfully close a database connection. * This method does not need to be used from native callers since you can just * set the statement to null, but is extremely useful to JS callers. */ void finalize(); /** * Create a clone of this statement, by initializing a new statement * with the same connection and same SQL statement as this one. It * does not preserve statement state; that is, if a statement is * being executed when it is cloned, the new statement will not be * executing. */ mozIStorageStatement clone(); /* * Number of parameters */ readonly attribute unsigned long parameterCount; /** * Name of nth parameter, if given */ AUTF8String getParameterName(in unsigned long aParamIndex); /** * Returns the index of the named parameter. * * @param aName * The name of the parameter you want the index for. This does not * include the leading ':'. * @returns the index of the named parameter. */ unsigned long getParameterIndex(in AUTF8String aName); /** * Number of columns returned */ readonly attribute unsigned long columnCount; /** * Name of nth column */ AUTF8String getColumnName(in unsigned long aColumnIndex); /** * Obtains the index of the column with the specified name. * * @param aName The name of the column. * @return The index of the column with the specified name. */ unsigned long getColumnIndex(in AUTF8String aName); /** * Obtains the declared column type of a prepared statement. * * @param aParamIndex The zero-based index of the column who's declared type * we are interested in. * @returns the declared index type. */ AUTF8String getColumnDecltype(in unsigned long aParamIndex); /** * Reset parameters/statement execution */ void reset(); /** * Bind the given value to the parameter at aParamIndex. Index 0 * denotes the first numbered argument or ?1. */ void bindUTF8StringParameter(in unsigned long aParamIndex, in AUTF8String aValue); void bindStringParameter(in unsigned long aParamIndex, in AString aValue); void bindDoubleParameter(in unsigned long aParamIndex, in double aValue); void bindInt32Parameter(in unsigned long aParamIndex, in long aValue); void bindInt64Parameter(in unsigned long aParamIndex, in long long aValue); void bindNullParameter(in unsigned long aParamIndex); void bindBlobParameter(in unsigned long aParamIndex, [array,const,size_is(aValueSize)] in octet aValue, in unsigned long aValueSize); /** * Binds the array of parameters to the statement. When executeAsync is * called, all the parameters in aParameters are bound and then executed. * * @param aParameters * The array of parameters to bind to the statement upon execution. */ void bindParameters(in mozIStorageBindingParamsArray aParameters); /** * Creates a new mozIStorageBindingParamsArray that can be used to bind * multiple sets of data to a statement. * * @returns a mozIStorageBindingParamsArray that multiple sets of parameters * can be bound to. */ mozIStorageBindingParamsArray newBindingParamsArray(); /** * Execute the query, ignoring any results. This is accomplished by * calling step() once, and then calling reset(). * * Error and last insert info, etc. are available from * the mozStorageConnection. */ void execute(); /** * Execute a query, using any currently-bound parameters. Reset * must be called on the statement after the last call of * executeStep. * * @returns a boolean indicating whether there are more rows or not; * row data may be accessed using mozIStorageValueArray methods on * the statement. * */ boolean executeStep(); /** * Execute a query, using any currently-bound parameters. Reset is called * when no more data is returned. This method is only available to JavaScript * consumers. * * @returns a boolean indicating whether there are more rows or not. * * boolean step(); */ /** * Obtains the current list of named parameters, which are settable. This * property is only available to JavaScript consumers. * * readonly attribute mozIStorageStatementParams params; */ /** * Obtains the current row, with access to all the data members by name. This * property is only available to JavaScript consumers. * * readonly attribute mozIStorageStatementRow row; */ /** * Execute a query asynchronously using any currently bound parameters. This * statement can be reused immediately, and reset does not need to be called. * * Note: If you have any custom defined functions, they must be re-entrant * since they can be called on multiple threads. * * @param aCallback [optional] * The callback object that will be notified of progress, errors, and * completion. * @returns an object that can be used to cancel the statements execution. */ mozIStoragePendingStatement executeAsync( [optional] in mozIStorageStatementCallback aCallback ); /** * The current state. Row getters are only valid while * the statement is in the "executing" state. */ const long MOZ_STORAGE_STATEMENT_INVALID = 0; const long MOZ_STORAGE_STATEMENT_READY = 1; const long MOZ_STORAGE_STATEMENT_EXECUTING = 2; readonly attribute long state; /** * Escape a string for SQL LIKE search. * * @param aValue the string to escape for SQL LIKE * @param aEscapeChar the escape character * @returns an AString of an escaped version of aValue * (%, _ and the escape char are escaped with the escape char) * For example, we will convert "foo/bar_baz%20cheese" * into "foo//bar/_baz/%20cheese" (if the escape char is '/'). * @note consumers will have to use same escape char * when doing statements such as: ...LIKE '?1' ESCAPE '/'... */ AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar); };