mozIStorageValueArray
Last changed in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)For an introduction on how to use this interface, see the Storage overview document.
Method overview
void initialize(in Obsolete since Gecko 1.9.1 |
void finalize(); |
|
AUTF8String getParameterName(in unsigned long aParamIndex); |
unsigned long getParameterIndex(in AUTF8String aName); |
AUTF8String getColumnName(in unsigned long aColumnIndex); |
unsigned long getColumnIndex(in AUTF8String aName); |
void reset(); |
AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar); |
void bindParameters(in |
|
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); |
|
boolean executeStep(); |
boolean step(); |
void execute(); |
Attributes
Attribute | Type | Description |
columnCount |
unsigned long |
Number of columns returned. Read only. |
parameterCount |
unsigned long |
Number of parameters. Read only. |
params |
mozIStorageStatementParams |
The current list of named parameters, which may be set. Only available to JavaScript code. Read only. |
row |
mozIStorageStatementRow |
The current row, with access to all data members by name. Available only to JavaScript code. Read only. |
state |
long |
The current state defined by mozIStorageStatement.MOZ_STORAGE_STATEMENT_INVALID , mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY , or mozIStorageStatement.MOZ_STORAGE_STATEMENT_EXECUTING . Read only. |
Statement status constants
Constant | Value | Description |
MOZ_STORAGE_STATEMENT_INVALID |
0 | The SQL statement is Invalid. |
MOZ_STORAGE_STATEMENT_READY |
1 | The SQL statement is ready to be executed. |
MOZ_STORAGE_STATEMENT_EXECUTING |
2 | The SQL statement is executing at the moment. |
Methods
initialize()
Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)mozIStorageConnection.createStatement()
. This method exists back to Gecko 1.8.0.Initialize this query with the given SQL statement.
void initialize( in mozIStorageConnection aDBConnection, in AUTF8String aSQLStatement );
Parameters
aDBConnection
- A
mozIStorageConnection
database connection. aSQLStatement
- String key representing the SQL statement.
finalize()
Finalizes a statement which releases all resources that were allocated for it. You must call this method on every active statement before you try to call mozIStorageConnection.close()
.
void finalize();
clone()
Creates a copy of the statement whose state will be mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY
.
mozIStorageStatement clone();
Return value
A mozIStorageStatement
that is a copy of the current statement.
getParameterName()
Obtains the name of the parameter for the specified index.
AUTF8String getParameterName( in unsigned long aParamIndex );
Parameters
aParamIndex
-
The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
Return value
An AUTF8String
representing the parameter name for the specified index.
getParameterIndex()
Obtains the index of the parameter with the specified name. This method was added in 1.9.0. In 1.8.1 you had to use getParameterIndexes()
. See bug 388048 for details.
unsigned long getParameterIndex( in AUTF8String aName );
Parameters
aName
- Name of the parameter to get the index for. For parameter 'foo', name's format is ':foo' in 1.9.0 and 1.9.1. In 1.9.2 the ':' was dropped and name's value should be just 'foo'. See bug 528166 for details.
Return value
The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
getColumnName()
Obtains the name of the column for the specified index.
AUTF8String getColumnName( in unsigned long aColumnIndex );
Parameters
aColumnIndex
-
The zero-based numerical index for the column to get data from.
Return value
An AUTF8String
with the of the column name for the specified index.
getColumnIndex()
Obtains the index of the column with the specified name.
unsigned long getColumnIndex( in AUTF8String aName );
Parameters
aName
- Name of the column.
Return value
The zero-based numerical index for the column to get data from.
reset()
Resets the bound parameters and statement execution state. This must be called before reusing the statement.
See the overview document on storage for more details.
void reset()
escapeStringForLIKE()
Escapes a string for SQL LIKE search.
...LIKE '?1' ESCAPE '/'...
. See the sample code for more details.AString escapeStringForLIKE( in AString aValue, in wchar aEscapeChar );
Parameters
aValue
- String to escape for SQL LIKE.
aEscapeChar
- The escape character to use. Generally,
/
will be sufficient.
Return value
An UTF-16 encoded string that has characters that have special meaning escaped from aValue
.
Sample Code
var statement = dbConn.createStatement( "SELECT * " + "FROM table_name " + "WHERE column_name LIKE :userInput ESCAPE '/'" ); statement.params.userInput = statement.escapeStringForLIKE(someUserInput, "/");
Binding Functions
These functions are discussed in more detail with sample code in the overview document.
newBindingParamsArray()
Creates and returns a new mozIStorageBindingParamsArray
object that can be used to bind multiple values to parameters in preparation for calling executeAsync()
.
mozIStorageBindingParamsArray newBindingParamsArray();
Parameters
None.
bindParameters()
Binds all the parameters in the specified array to the statement in preparation for calling executeAsync()
.
NS_ERROR_UNEXPECTED
if the specified mozIStorageBindingParamsArray
is empty.void bindParameters( in mozIStorageBindingParamsArray aParameters );
Parameters
- aParameters
- The
mozIStorageBindingParamsArray
object containing one or moremozIStorageBindingParams
objects with the parameters to be bound to the statement prior to execution.
bindUTF8StringParameter()
Binds a UTF8String to the specified index.
void bindUTF8StringParameter( in unsigned long aParamIndex, in AUTF8String aValue );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
bindStringParameter()
Binds a string parameter to the specified index.
void bindStringParameter( in unsigned long aParamIndex, in AString aValue );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
bindDoubleParameter()
Binds a double parameter to the specified index.
void bindDoubleParameter( in unsigned long aParamIndex, in double aValue );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
bindInt32Parameter()
Binds an Int32 parameter to the specified index.
void bindInt32Parameter( in unsigned long aParamIndex, in long aValue );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
bindInt64Parameter()
Binds an Int64 parameter to the specified index.
void bindInt64Parameter( in unsigned long aParamIndex, in long long aValue );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
bindNullParameter()
Binds a null parameter to the specified index.
void bindNullParameter( in unsigned long aParamIndex );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
bindBlobParameter()
Binds a blob parameter to the specified index.
void bindBlobParameter( in unsigned long aParamIndex, [array,const,size_is(aValueSize)] in octet aValue, in unsigned long aValueSize );
Parameters
aParamIndex
- The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).
aValue
- to be bound to the specified index.
aValueSize
- Size of
aValue
.
Execution Functions
These functions are discussed in more detail with sample code in the overview document.
executeAsync()
Starts the execution of a query asynchronously using the currently bound parameters. The optional callback routine receives notifications about the progress of the query. For sample code and more details, see the overview document.
mozIStoragePendingStatement executeAsync( [optional] mozIStorageStatementCallback aCallback );
Parameters
aCallback
- A callback object that will be notified of progress, errors, and query completion. This parameter is optional.
Return value
A mozIStoragePendingStatement
object that can be used to cancel the execution of the statement.
executeStep()
Warning: Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!
Executes a query with the currently bound parameters, and steps through the results one row at a time. For sample code and more details, see the overview document.
boolean executeStep();
Return value
Returns a boolean
indicating whether there are more rows or not. Row data may be accessed using mozIStorageValueArray
methods on the statement.
step()
Identical to calling executeStep()
, and then calling reset()
when no more rows are returned.
boolean step()
Return value
true
if there are more rows left in the results, otherwise false
.
execute()
Warning: Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!
Execute the query, ignoring any results. This is accomplished by calling executeStep()
, and then calling reset()
.
void execute();
See also
- Storage introduction and how-to article
mozIStorageConnection
Database connection to a specific file or in-memory data storagemozIStorageValueArray
Wraps an array of SQL values, such as a result row.mozIStorageFunction
Create a new SQLite function.mozIStorageAggregateFunction
Create a new SQLite aggregate function.mozIStorageProgressHandler
Monitor progress during the execution of a statement.mozIStorageAsyncStatement
mozIStorageStatementWrapper
Storage statement wrappermozIStorageBindingParams
mozIStorageBindingParamsArray