gecko/storage/public/mozIStorageStatement.idl
Paul O’Shannessy 5b3c2717f0 Bug 518440 - Deprecate mozIStorageStatementWrapper & mozIStorageStatement.step() in IDL. r=sdwilsh
--HG--
extra : rebase_source : 0ede87a6eb9a34475d9efafa433809e571a104d3
2009-09-25 15:32:21 -07:00

238 lines
8.3 KiB
Plaintext

/* -*- 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 <vladimir.vukicevic@oracle.com>
*
* 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 executeStep() 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.
*
* @deprecated As of Mozilla 1.9.2 in favor of executeStep().
*
* @returns a boolean indicating whether there are more rows or not.
*
* [deprecated] 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);
};