inc/FIoDbStatement.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16 /**
  17  * @file        FIoDbStatement.h
  18  * @brief       This is the header file for the %DbStatement class.
  19  *
  20  * This header file contains the declarations of the %DbStatement class.
  21  */
  22
  23 #ifndef _FIO_DB_STATEMENT_H_
  24 #define _FIO_DB_STATEMENT_H_
  25
  26 #include <FBaseString.h>
  27 #include <FBaseByteBuffer.h>
  28 #include <FBaseDateTime.h>
  29 #include <FBaseRtMutex.h>
  30 #include <FIoDbTypes.h>
  31
  32 namespace Tizen { namespace Io
  33 {
  34
  35 /**
  36  * @class   DbStatement
  37  * @brief       This class provides a method for evaluating pre-compiled statements.
  38  *
  39  * @since       2.0
  40  *
  41  * @final       This class is not intended for extension.
  42  *
  43  * The %DbStatement class provides a method for evaluating pre-compiled statements.
  44  * All members of this class are guaranteed to be thread-safe.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/io/database_operations.htm">Database Operations</a>.
  47  */
  48 class _OSP_EXPORT_ DbStatement
  49         : public Tizen::Base::Object
  50 {
  51
  52 public:
  53         /**
  54         * This destructor overrides Tizen::Base::Object::~Object().
  55         *
  56         * @since        2.0
  57         */
  58         virtual ~DbStatement(void);
  59
  60         /**
  61         * Binds an integer value to the statement parameter.
  62         *
  63         * @if OSPCOMPAT
  64         * @brief                        <i> [Compatibility] </i>
  65         * @endif
  66         * @since                        2.0
  67         * @if OSPCOMPAT
  68         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
  69         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
  70         * @endif
  71         *
  72         * @return               An error code
  73         * @param[in]    columnIndex                     The index of the column whose value is bound
  74         * @param[out]   value                           The integer value to bind
  75         * @exception    E_SUCCESS                       The method is successful.
  76         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
  77         *                                                                       or the instance is finalized.
  78         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
  79         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
  80         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
  81         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
  82         */
  83         result BindInt(int columnIndex, int value);
  84
  85         /**
  86         * Binds a @c long @c long value to the statement parameter.
  87         *
  88         * @if OSPCOMPAT
  89         * @brief                        <i> [Compatibility] </i>
  90         * @endif
  91         * @since                        2.0
  92         * @if OSPCOMPAT
  93         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
  94         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
  95         * @endif
  96         *
  97         * @return               An error code
  98         * @param[in]    columnIndex                     The index of the column whose value is bound
  99         * @param[out]   value                           The 64-bit integer value to bind
 100         * @exception    E_SUCCESS                       The method is successful.
 101         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 102         *                                                                       or the instance is finalized.
 103         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 104         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 105         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 106         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 107         */
 108         result BindInt64(int columnIndex, long long value);
 109
 110         /**
 111         * Binds a @c double value to the statement parameter.
 112         *
 113         * @if OSPCOMPAT
 114         * @brief                        <i> [Compatibility] </i>
 115         * @endif
 116         * @since                        2.0
 117         * @if OSPCOMPAT
 118         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 119         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 120         * @endif
 121         *
 122         * @return               An error code
 123         * @param[in]    columnIndex                     The index of the column whose value is bound
 124         * @param[out]   value                           The @c double value to bind
 125         * @exception    E_SUCCESS                       The method is successful.
 126         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 127         *                                                                       or the instance is finalized.
 128         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 129         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 130         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 131         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 132         */
 133         result BindDouble(int columnIndex, double value);
 134
 135         /**
 136         * Binds a String value to the statement parameter.
 137         *
 138         * @if OSPCOMPAT
 139         * @brief                        <i> [Compatibility] </i>
 140         * @endif
 141         * @since                        2.0
 142         * @if OSPCOMPAT
 143         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 144         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 145         * @endif
 146         *
 147         * @return               An error code
 148         * @param[in]    columnIndex                     The index of the column whose value is bound
 149         * @param[out]   value                           The string value to bind
 150         * @exception    E_SUCCESS                       The method is successful.
 151         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 152         *                                                                       or the instance is finalized.
 153         * @exception    E_INVALID_ARG           The specified @c value exceeds size limit.
 154         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 155         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 156         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 157         */
 158         result BindString(int columnIndex, const Tizen::Base::String& value);
 159
 160         /**
 161         * Binds a value of type ByteBuffer to the statement parameter.
 162         *
 163         * @if OSPCOMPAT
 164         * @brief                        <i> [Compatibility] </i>
 165         * @endif
 166         * @since                        2.0
 167         * @if OSPCOMPAT
 168         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 169         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 170         * @endif
 171         *
 172         * @return               An error code
 173         * @param[in]    columnIndex                 The index of the column whose value is bound
 174         * @param[out]   value                   The blob value to bind @n
 175         *                                                               The maximum available size is limited to 100 MBytes.
 176         * @exception    E_SUCCESS                       The method is successful.
 177         * @exception    E_INVALID_STATE      The instance has not been properly constructed,
 178         *                                                                       or the instance is finalized.
 179         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 180         *                                                                       - The specified @c columnIndex is invalid. @n
 181         *                                                                       - The size of byte buffer is less than @c 0 or has @c null data. @n
 182         *                                                                       - The specified @c value exceeds size limit.
 183         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 184         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 185         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 186         * @remarks              The bound @c byte array size is from the current position of byte buffer to the limit.
 187         */
 188         result BindBlob(int columnIndex, const Tizen::Base::ByteBuffer& value);
 189
 190         /**
 191         * Binds the raw blob data to the statement parameter.
 192         *
 193         * @if OSPCOMPAT
 194         * @brief                        <i> [Compatibility] </i>
 195         * @endif
 196         * @since                        2.0
 197         * @if OSPCOMPAT
 198         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 199         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 200         * @endif
 201         *
 202         * @return               An error code
 203         * @param[in]    columnIndex             The index of the column whose value is bound
 204         * @param[in]    buffer                          A pointer to the buffer where blob data is located @n
 205         *                                                                       The maximum available size is limited to 100 MBytes.
 206         * @param[in]    size                            The blob data length in bytes
 207         * @exception    E_SUCCESS                       The method is successful.
 208         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 209         *                                                                       or the instance is finalized.
 210         * @exception    E_INVALID_ARG           Either of the following conditions has occurred: @n
 211         *                                                                       - The specified @c columnIndex is invalid. @n
 212         *                                                                       - The specified @c size is less than @c 0. @n
 213         *                                                                       - The pointer to the buffer is @c null. @n
 214         *                                                                       - The specified @c buffer exceeds size limit.
 215         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 216         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 217         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 218         */
 219         result BindBlob(int columnIndex, const void* buffer, int size);
 220
 221         /**
 222         * Binds a DateTime value to the statement parameter.
 223         *
 224         * @if OSPCOMPAT
 225         * @brief                        <i> [Compatibility] </i>
 226         * @endif
 227         * @since                        2.0
 228         * @if OSPCOMPAT
 229         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 230         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 231         * @endif
 232         *
 233         * @return               An error code
 234         * @param[in]    columnIndex                     The index of the column whose value is bound
 235         * @param[out]   value                           The date value to bind
 236         * @exception    E_SUCCESS                       The method is successful.
 237         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 238         *                                                                       or the instance is finalized.
 239         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid, or
 240         *                                                                       the value is less than @c or a @c null pointer.
 241         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 242         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 243         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 244         */
 245         result BindDateTime(int columnIndex, const Tizen::Base::DateTime& value);
 246
 247         /**
 248         * Binds a @c null value to the statement parameter.
 249         *
 250         * @if OSPCOMPAT
 251         * @brief                        <i> [Compatibility] </i>
 252         * @endif
 253         * @since                        2.0
 254         * @if OSPCOMPAT
 255         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 256         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 257         * @endif
 258         *
 259         * @return               An error code
 260         * @param[in]    columnIndex                     The index of the column whose value is bound
 261         * @exception    E_SUCCESS                       The method is successful.
 262         * @exception    E_INVALID_STATE         The instance has not been properly constructed,
 263         *                                                                       or the instance is finalized.
 264         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 265         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 266         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext().
 267         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 268         */
 269         result BindNull(int columnIndex);
 270
 271 private:
 272         /**
 273         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 274         *
 275         * @since 2.0
 276         */
 277         DbStatement(void);
 278
 279         /**
 280         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 281         *
 282         * @since 2.0
 283         */
 284         DbStatement(const DbStatement& rhs);
 285
 286         /**
 287         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 288         *
 289         * @since 2.0
 290         */
 291         DbStatement& operator =(const DbStatement& rhs);
 292
 293         class _DbStatementImpl* __pDbStatementImpl;
 294
 295         friend class _DbStatementImpl;
 296
 297 }; // DbStatement
 298
 299 }} // Tizen::Io
 300
 301 #endif  //_FIO_DB_STATEMENT_H_
 302