inc/FIoDbStatement.h

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