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