1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/storage/public/mozIStorageBaseStatement.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,152 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
1.5 + * vim: sw=2 ts=2 sts=2 et
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +#include "nsISupports.idl"
1.11 +#include "mozIStorageBindingParams.idl"
1.12 +
1.13 +interface mozIStorageConnection;
1.14 +interface mozIStorageStatementCallback;
1.15 +interface mozIStoragePendingStatement;
1.16 +interface mozIStorageBindingParams;
1.17 +interface mozIStorageBindingParamsArray;
1.18 +
1.19 +/**
1.20 + * The base interface for both pure asynchronous storage statements
1.21 + * (mozIStorageAsyncStatement) and 'classic' storage statements
1.22 + * (mozIStorageStatement) that can be used for both synchronous and asynchronous
1.23 + * purposes.
1.24 + */
1.25 +[scriptable, uuid(5d34f333-ed3f-4aa2-ba51-f2a8b0cfa33a)]
1.26 +interface mozIStorageBaseStatement : mozIStorageBindingParams {
1.27 + /**
1.28 + * Finalizes a statement so you can successfully close a database connection.
1.29 + * Once a statement has been finalized it can no longer be used for any
1.30 + * purpose.
1.31 + *
1.32 + * Statements are implicitly finalized when their reference counts hits zero.
1.33 + * If you are a native (C++) caller this is accomplished by setting all of
1.34 + * your nsCOMPtr instances to be NULL. If you are operating from JavaScript
1.35 + * code then you cannot rely on this behavior because of the involvement of
1.36 + * garbage collection.
1.37 + *
1.38 + * When finalizing an asynchronous statement you do not need to worry about
1.39 + * whether the statement has actually been executed by the asynchronous
1.40 + * thread; you just need to call finalize after your last call to executeAsync
1.41 + * involving the statement. However, you do need to use asyncClose instead of
1.42 + * close on the connection if any statements have been used asynchronously.
1.43 + */
1.44 + void finalize();
1.45 +
1.46 + /**
1.47 + * Bind the given value at the given numeric index.
1.48 + *
1.49 + * @param aParamIndex
1.50 + * 0-based index, 0 corresponding to the first numbered argument or
1.51 + * "?1".
1.52 + * @param aValue
1.53 + * Argument value.
1.54 + * @param aValueSize
1.55 + * Length of aValue in bytes.
1.56 + * @{
1.57 + */
1.58 + [deprecated] void bindUTF8StringParameter(in unsigned long aParamIndex,
1.59 + in AUTF8String aValue);
1.60 + [deprecated] void bindStringParameter(in unsigned long aParamIndex,
1.61 + in AString aValue);
1.62 + [deprecated] void bindDoubleParameter(in unsigned long aParamIndex,
1.63 + in double aValue);
1.64 + [deprecated] void bindInt32Parameter(in unsigned long aParamIndex,
1.65 + in long aValue);
1.66 + [deprecated] void bindInt64Parameter(in unsigned long aParamIndex,
1.67 + in long long aValue);
1.68 + [deprecated] void bindNullParameter(in unsigned long aParamIndex);
1.69 + [deprecated] void bindBlobParameter(
1.70 + in unsigned long aParamIndex,
1.71 + [array,const,size_is(aValueSize)] in octet aValue,
1.72 + in unsigned long aValueSize);
1.73 + [deprecated] void bindAdoptedBlobParameter(
1.74 + in unsigned long aParamIndex,
1.75 + [array,size_is(aValueSize)] in octet aValue,
1.76 + in unsigned long aValueSize);
1.77 + /**@}*/
1.78 +
1.79 + /**
1.80 + * Binds the array of parameters to the statement. When executeAsync is
1.81 + * called, all the parameters in aParameters are bound and then executed.
1.82 + *
1.83 + * @param aParameters
1.84 + * The array of parameters to bind to the statement upon execution.
1.85 + *
1.86 + * @note This is only works on statements being used asynchronously.
1.87 + */
1.88 + void bindParameters(in mozIStorageBindingParamsArray aParameters);
1.89 +
1.90 + /**
1.91 + * Creates a new mozIStorageBindingParamsArray that can be used to bind
1.92 + * multiple sets of data to a statement with bindParameters.
1.93 + *
1.94 + * @return a mozIStorageBindingParamsArray that multiple sets of parameters
1.95 + * can be bound to.
1.96 + *
1.97 + * @note This is only useful for statements being used asynchronously.
1.98 + */
1.99 + mozIStorageBindingParamsArray newBindingParamsArray();
1.100 +
1.101 + /**
1.102 + * Execute a query asynchronously using any currently bound parameters. This
1.103 + * statement can be reused immediately, and reset does not need to be called.
1.104 + *
1.105 + * @note If you have any custom defined functions, they must be re-entrant
1.106 + * since they can be called on multiple threads.
1.107 + *
1.108 + * @param aCallback [optional]
1.109 + * The callback object that will be notified of progress, errors, and
1.110 + * completion.
1.111 + * @return an object that can be used to cancel the statements execution.
1.112 + */
1.113 + mozIStoragePendingStatement executeAsync(
1.114 + [optional] in mozIStorageStatementCallback aCallback
1.115 + );
1.116 +
1.117 + /**
1.118 + * The statement is not usable, either because it failed to initialize or
1.119 + * was explicitly finalized.
1.120 + */
1.121 + const long MOZ_STORAGE_STATEMENT_INVALID = 0;
1.122 + /**
1.123 + * The statement is usable.
1.124 + */
1.125 + const long MOZ_STORAGE_STATEMENT_READY = 1;
1.126 + /**
1.127 + * Indicates that the statement is executing and the row getters may be used.
1.128 + *
1.129 + * @note This is only relevant for mozIStorageStatement instances being used
1.130 + * in a synchronous fashion.
1.131 + */
1.132 + const long MOZ_STORAGE_STATEMENT_EXECUTING = 2;
1.133 +
1.134 + /**
1.135 + * Find out whether the statement is usable (has not been finalized).
1.136 + */
1.137 + readonly attribute long state;
1.138 +
1.139 + /**
1.140 + * Escape a string for SQL LIKE search.
1.141 + *
1.142 + * @note Consumers will have to use same escape char when doing statements
1.143 + * such as: ...LIKE '?1' ESCAPE '/'...
1.144 + *
1.145 + * @param aValue
1.146 + * The string to escape for SQL LIKE.
1.147 + * @param aEscapeChar
1.148 + * The escape character.
1.149 + * @return an AString of an escaped version of aValue
1.150 + * (%, _ and the escape char are escaped with the escape char)
1.151 + * For example, we will convert "foo/bar_baz%20cheese"
1.152 + * into "foo//bar/_baz/%20cheese" (if the escape char is '/').
1.153 + */
1.154 + AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
1.155 +};
