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 methods 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 methods for evaluating pre-compiled statements.
  44  *
  45  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/io/database_operations.htm">Database Operations</a>.
  46  */
  47 class _OSP_EXPORT_ DbStatement
  48         : public Tizen::Base::Object
  49 {
  50
  51 public:
  52         /**
  53         * This destructor overrides Tizen::Base::Object::~Object().
  54         *
  55         * @since        2.0
  56         */
  57         virtual ~DbStatement(void);
  58
  59         /**
  60         * Binds the specified integer value to the statement parameter.
  61         *
  62         * @if OSPCOMPAT
  63         * @brief                        <i> [Compatibility] </i>
  64         * @endif
  65         * @since                        2.0
  66         * @if OSPCOMPAT
  67         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
  68         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
  69         * @endif
  70         *
  71         * @return               An error code
  72         * @param[in]    columnIndex                     The column index to bind the value
  73         * @param[out]   value                           The integer value to bind
  74         * @exception    E_SUCCESS                       The method is successful.
  75         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
  76         *                                                                       - The instance has not been properly constructed.
  77         *                                                                       - 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(). @n
  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 the specified @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 column index to bind the value
  99         * @param[out]   value                           The 64-bit integer value to bind
 100         * @exception    E_SUCCESS                       The method is successful.
 101         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 102         *                                                                       - The instance has not been properly constructed.
 103         *                                                                       - The instance is finalized.
 104         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 105         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 106         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 107         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 108         */
 109         result BindInt64(int columnIndex, long long value);
 110
 111         /**
 112         * Binds the specified @c double value to the statement parameter.
 113         *
 114         * @if OSPCOMPAT
 115         * @brief                        <i> [Compatibility] </i>
 116         * @endif
 117         * @since                        2.0
 118         * @if OSPCOMPAT
 119         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 120         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 121         * @endif
 122         *
 123         * @return               An error code
 124         * @param[in]    columnIndex                     The column index to bind the value
 125         * @param[out]   value                           The @c double value to bind
 126         * @exception    E_SUCCESS                       The method is successful.
 127         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 128         *                                                                       - The instance has not been properly constructed.
 129         *                                                                       - The instance is finalized.
 130         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 131         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 132         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 133         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 134         */
 135         result BindDouble(int columnIndex, double value);
 136
 137         /**
 138         * Binds the specified string value to the statement parameter.
 139         *
 140         * @if OSPCOMPAT
 141         * @brief                        <i> [Compatibility] </i>
 142         * @endif
 143         * @since                        2.0
 144         * @if OSPCOMPAT
 145         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 146         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 147         * @endif
 148         *
 149         * @return               An error code
 150         * @param[in]    columnIndex                     The column index to bind the value
 151         * @param[out]   value                           The string value to bind
 152         * @exception    E_SUCCESS                       The method is successful.
 153         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 154         *                                                                       - The instance has not been properly constructed.
 155         *                                                                       - The instance is finalized.
 156         * @exception    E_INVALID_ARG           The specified @c value exceeds size limit.
 157         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 158         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 159         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 160         */
 161         result BindString(int columnIndex, const Tizen::Base::String& value);
 162
 163         /**
 164         * Binds the specified ByteBuffer type value to the statement parameter.
 165         *
 166         * @if OSPCOMPAT
 167         * @brief                        <i> [Compatibility] </i>
 168         * @endif
 169         * @since                        2.0
 170         * @if OSPCOMPAT
 171         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 172         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 173         * @endif
 174         *
 175         * @return               An error code
 176         * @param[in]    columnIndex                 The column index to bind the value
 177         * @param[out]   value                   The blob value to bind @n
 178         *                                                               The maximum available size is limited to 100 MBytes.
 179         * @exception    E_SUCCESS                       The method is successful.
 180         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 181         *                                                                       - The instance has not been properly constructed.
 182         *                                                                       - The instance is finalized.
 183         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 184         *                                                                       - The specified @c columnIndex is invalid.
 185         *                                                                       - The size of the byte buffer is less than @c 0 or has @c null data.
 186         *                                                                       - The specified @c value exceeds size limit.
 187         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 188         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 189         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 190         * @remarks              The bound @c byte array size is from the current position of byte buffer to the limit.
 191         */
 192         result BindBlob(int columnIndex, const Tizen::Base::ByteBuffer& value);
 193
 194         /**
 195         * Binds the specified raw blob data to the statement parameter.
 196         *
 197         * @if OSPCOMPAT
 198         * @brief                        <i> [Compatibility] </i>
 199         * @endif
 200         * @since                        2.0
 201         * @if OSPCOMPAT
 202         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 203         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 204         * @endif
 205         *
 206         * @return               An error code
 207         * @param[in]    columnIndex             The index of the column to bind the value
 208         * @param[in]    buffer                          A pointer to the buffer where blob data is located @n
 209         *                                                                       The maximum available size is limited to 100 MBytes.
 210         * @param[in]    size                            The blob data length in bytes
 211         * @exception    E_SUCCESS                       The method is successful.
 212         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 213         *                                                                       - The instance has not been properly constructed.
 214         *                                                                       - The instance is finalized.
 215         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 216         *                                                                       - The specified @c columnIndex is invalid.
 217         *                                                                       - The specified @c size is less than @c 0.
 218         *                                                                       - The pointer to the buffer is @c null.
 219         *                                                                       - The specified @c buffer exceeds size limit.
 220         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 221         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 222         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 223         */
 224         result BindBlob(int columnIndex, const void* buffer, int size);
 225
 226         /**
 227         * Binds the specified DateTime value to the statement parameter.
 228         *
 229         * @if OSPCOMPAT
 230         * @brief                        <i> [Compatibility] </i>
 231         * @endif
 232         * @since                        2.0
 233         * @if OSPCOMPAT
 234         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 235         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 236         * @endif
 237         *
 238         * @return               An error code
 239         * @param[in]    columnIndex                     The index of the column to bind the value
 240         * @param[out]   value                           The date value to bind
 241         * @exception    E_SUCCESS                       The method is successful.
 242         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 243         *                                                                       - The instance has not been properly constructed.
 244         *                                                                       - The instance is finalized.
 245         * @exception    E_INVALID_ARG           Either of the following conditions has occurred:
 246         *                                                                       - The specified @c columnIndex is invalid.
 247         *                                                                       - The value is less than @c or a @c null pointer.
 248         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 249         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 250         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 251         */
 252         result BindDateTime(int columnIndex, const Tizen::Base::DateTime& value);
 253
 254         /**
 255         * Binds a @c null value to the statement parameter.
 256         *
 257         * @if OSPCOMPAT
 258         * @brief                        <i> [Compatibility] </i>
 259         * @endif
 260         * @since                        2.0
 261         * @if OSPCOMPAT
 262         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 263         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 264         * @endif
 265         *
 266         * @return               An error code
 267         * @param[in]    columnIndex                     The index of the column to bind the @c null value
 268         * @exception    E_SUCCESS                       The method is successful.
 269         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 270         *                                                                       - The instance has not been properly constructed.
 271         *                                                                       - The instance is finalized.
 272         * @exception    E_INVALID_ARG           The specified @c columnIndex is invalid.
 273         * @exception    E_INVALID_OPERATION     This method has failed to bind the parameter because the database state has not been reset
 274         *                                                                       after executing the SELECT query by using Database::ExecuteStatementN() or DbEnumerator::MoveNext(). @n
 275         *                                                                       In this case DbEnumerator::Reset() should be invoked before calling this method.
 276         */
 277         result BindNull(int columnIndex);
 278
 279 private:
 280         /**
 281         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 282         *
 283         * @since 2.0
 284         */
 285         DbStatement(void);
 286
 287         /**
 288         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 289         *
 290         * @since 2.0
 291         */
 292         DbStatement(const DbStatement& rhs);
 293
 294         /**
 295         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 296         *
 297         * @since 2.0
 298         */
 299         DbStatement& operator =(const DbStatement& rhs);
 300
 301         class _DbStatementImpl* __pDbStatementImpl;
 302
 303         friend class _DbStatementImpl;
 304
 305 }; // DbStatement
 306
 307 }} // Tizen::Io
 308
 309 #endif  //_FIO_DB_STATEMENT_H_
 310