inc/FIoDbEnumerator.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 /**
  19  * @file        FIoDbEnumerator.h
  20  * @brief       This is the header file for the %DbEnumerator class.
  21  *
  22  * This header file contains the declarations of the %DbEnumerator class.
  23  */
  24
  25 #ifndef _FIO_DB_ENUMERATOR_H_
  26 #define _FIO_DB_ENUMERATOR_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseRtMutex.h>
  30 #include <FIoDbTypes.h>
  31 #include <FIoIDbEnumerator.h>
  32
  33 namespace Tizen { namespace Base
  34 {
  35 class String;
  36 class ByteBuffer;
  37 class DateTime;
  38 }}
  39
  40 namespace Tizen { namespace Io
  41 {
  42
  43 /**
  44  * @class   DbEnumerator
  45  * @brief       This class provides methods for navigating the result set from the SELECT query.
  46  *
  47  * @since       2.0
  48  *
  49  * @final       This class is not intended for extension.
  50  *
  51  * The %DbEnumerator class provides methods for navigating the result set from the SELECT query.
  52  * All the members of this class are guaranteed to be thread-safe.
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/io/database_operations.htm">Database Operations</a>.
  55  *
  56  * @see Tizen::Io::Database
  57  */
  58 class _OSP_EXPORT_ DbEnumerator
  59         : public Tizen::Base::Object
  60         , public Tizen::Io::IDbEnumerator
  61 {
  62
  63 public:
  64         /**
  65         * This destructor overrides Tizen::Base::Object::~Object().
  66         *
  67         * @since        2.0
  68         */
  69         virtual ~DbEnumerator(void);
  70
  71         /**
  72         * Moves the enumerator to the next position.
  73         *
  74         * @if OSPCOMPAT
  75         * @brief                        <i> [Compatibility] </i>
  76         * @endif
  77         * @since                        2.0
  78         * @if OSPCOMPAT
  79         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
  80         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
  81         * @endif
  82         *
  83         * @return               An error code
  84         * @exception    E_SUCCESS                       The method is successful.
  85         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
  86         *                                                                       - This instance has not been properly constructed. @n
  87         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
  88         *                                                                         (the query did not yield any result). @n
  89         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
  90         * @exception    E_OUT_OF_RANGE          The enumerator has reached out of the result set returned by the SELECT query.
  91         * @exception    E_OBJECT_LOCKED         The database instance is locked.
  92         * @exception    E_INVALID_FORMAT        The database file is malformed.
  93         * @exception    E_IO                            Either of the following conditions has occurred:  @n
  94         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
  95         *                                                                       - %File corruption is detected.
  96         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  97         * @see          Tizen::Io::Database::ExecuteStatementN()
  98         * @see         Tizen::Io::Database::QueryN()
  99         * @see          Tizen::Io::DbEnumerator::MovePrevious()
 100         * @see         Tizen::Io::DbEnumerator::MoveFirst()
 101         * @see         Tizen::Io::DbEnumerator::MoveLast()
 102         */
 103         virtual result MoveNext(void);
 104
 105         /**
 106         * Moves the enumerator to the previous position.
 107         *
 108         * @since                2.0
 109         *
 110         * @return               An error code
 111         * @exception    E_SUCCESS                       The method is successful.
 112         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 113         *                                                                       - This instance has not been properly constructed. @n
 114         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 115         *                                                                         (the query did not yield any result). @n
 116         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 117         * @exception    E_OUT_OF_RANGE          The enumerator has reached out of the result set returned by the SELECT query.
 118         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 119         * @exception    E_INVALID_FORMAT        The database file is malformed.
 120         * @exception    E_IO                            Either of the following conditions has occurred: @n
 121         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 122         *                                                                       - %File corruption is detected.
 123         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 124         * @see          Tizen::Io::Database::ExecuteStatementN()
 125         * @see         Tizen::Io::Database::QueryN()
 126         * @see          Tizen::Io::DbEnumerator::MoveNext()
 127         * @see         Tizen::Io::DbEnumerator::MoveFirst()
 128         * @see         Tizen::Io::DbEnumerator::MoveLast()
 129         */
 130         virtual result MovePrevious(void);
 131
 132         /**
 133         * Moves the enumerator to the first position.
 134         *
 135         * @since                2.0
 136         *
 137         * @return               An error code
 138         * @exception    E_SUCCESS                       The method is successful.
 139         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 140         *                                                                       - This instance has not been properly constructed. @n
 141         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 142         *                                                                         (the query did not yield any result). @n
 143         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 144         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 145         * @exception    E_INVALID_FORMAT        The database file is malformed.
 146         * @exception    E_IO                            Either of the following conditions has occurred: @n
 147         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 148         *                                                                       - %File corruption is detected.
 149         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 150         * @see          Tizen::Io::Database::ExecuteStatementN()
 151         * @see          Tizen::Io::Database::QueryN()
 152         * @see          Tizen::Io::DbEnumerator::MoveNext()
 153         * @see          Tizen::Io::DbEnumerator::MovePrevious()
 154         * @see          Tizen::Io::DbEnumerator::MoveLast()
 155         */
 156         virtual result MoveFirst(void);
 157
 158         /**
 159         * Moves the enumerator to the last position.
 160         *
 161         * @since                2.0
 162         *
 163         * @return               An error code
 164         * @exception    E_SUCCESS                       The method is successful.
 165         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 166         *                                                                       - This instance has not been properly constructed. @n
 167         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 168         *                                                                         (the query did not yield any result). @n
 169         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 170         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 171         * @exception    E_INVALID_FORMAT        The database file is malformed.
 172         * @exception    E_IO                            Either of the following conditions has occurred: @n
 173         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 174         *                                                                       - %File corruption is detected.
 175         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 176         * @see          Tizen::Io::Database::ExecuteStatementN()
 177         * @see          Tizen::Io::Database::QueryN()
 178         * @see          Tizen::Io::DbEnumerator::MoveNext()
 179         * @see          Tizen::Io::DbEnumerator::MovePrevious()
 180         * @see          Tizen::Io::DbEnumerator::MoveFirst()
 181         */
 182         virtual result MoveLast(void);
 183
 184         /**
 185         * Resets the calling %DbEnumerator instance back to its initial state.
 186         *
 187         * @if OSPCOMPAT
 188         * @brief                        <i> [Compatibility] </i>
 189         * @endif
 190         * @since                        2.0
 191         * @if OSPCOMPAT
 192         * @compatibility        This method has compatibility issues with OSP compatible applications. @n
 193         *                                       For more information, see @ref CompDatabaseExceptionPage "here".
 194         * @endif
 195         *
 196         * @return               An error code
 197         * @exception    E_SUCCESS                       The method is successful.
 198         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 199         *                                                                       - This instance has not been properly constructed. @n
 200         *                                                                       - The method has tried to reset the enumerator of the result set that is not activated
 201         *                                                                         (the query did not yield any result). @n
 202         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 203         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 204         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 205         * @remarks              After this method is called, if MoveNext() is called the cursor goes to the first position.
 206         */
 207         virtual result Reset(void);
 208
 209         /**
 210         * Gets an @c int value from the column whose index is specified.
 211         *
 212         * @since                        2.0
 213         *
 214         * @return                       An error code
 215         * @param[in]            columnIndex                     The index of the column whose value is required
 216         * @param[in,out]        value                           The integer value obtained from the column
 217         * @exception            E_SUCCESS                       The method is successful.
 218         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 219         *                                                                               - This instance has not been properly constructed. @n
 220         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 221         *                                                                                 (the query did not yield any result). @n
 222         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 223         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 224         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 225         */
 226         virtual result GetIntAt(int columnIndex, int& value) const;
 227
 228         /**
 229         * Gets a @c long @c long value from the column whose index is specified.
 230         *
 231         * @since                        2.0
 232         *
 233         * @return                       An error code
 234         * @param[in]            columnIndex                     The index of the column whose value is required
 235         * @param[in,out]        value                           The 64-bit integer value obtained from the column
 236         * @exception            E_SUCCESS                       The method is successful.
 237         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 238         *                                                                               - This instance has not been properly constructed. @n
 239         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 240         *                                                                                 (the query did not yield any result). @n
 241         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 242         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 243         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 244         */
 245         virtual result GetInt64At(int columnIndex, long long& value) const;
 246
 247         /**
 248         * Gets a @c double value from the column whose index is specified.
 249         *
 250         * @since                        2.0
 251         *
 252         * @return                       An error code
 253         * @param[in]            columnIndex                     The index of the column whose value is required
 254         * @param[in,out]        value                           The value obtained from the column as a double
 255         * @exception            E_SUCCESS                       The method is successful.
 256         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 257         *                                                                               - This instance has not been properly constructed. @n
 258         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 259         *                                                                                 (the query did not yield any result). @n
 260         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 261         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 262         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 263         */
 264         virtual result GetDoubleAt(int columnIndex, double& value) const;
 265
 266         /**
 267         * Gets a @c String value from the column whose index is specified.
 268         *
 269         * @since                        2.0
 270         *
 271         * @return                       An error code
 272         * @param[in]            columnIndex                                     The index of the column whose value is required
 273         * @param[in,out]        value                                           The value obtained from the column as a String
 274         * @exception            E_SUCCESS                                       The method is successful.
 275         * @exception            E_INVALID_STATE                         Either of the following conditions has occurred: @n
 276         *                                                                                               - This instance has not been properly constructed. @n
 277         *                                                                                               - The method has tried to fetch the column data of a result set that is not activated
 278         *                                                                                                 (the query did not yield any result). @n
 279         *                                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 280         * @exception            E_INVALID_ARG                           The specified @c columnIndex is out of range.
 281         * @exception            E_TYPE_MISMATCH                         The operation has attempted to access columns of different types.
 282         * @exception            E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 283         *                                                                                               it is possible if the database file is corrupted.
 284         */
 285         virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const;
 286
 287         /**
 288         * Gets a byte array value from the column whose index is specified.
 289         *
 290         * @since                        2.0
 291         *
 292         * @return                       An error code
 293         * @param[in]            columnIndex                     The index of the column whose value is required
 294         * @param[in,out]        value                           The user-provided buffer used to receive the blob data as a stream of type ByteBuffer @n
 295         *                                                                               The buffer will be filled from the current position and data copy will be continued
 296         *                                                                               until buffer limitation is reached or no more blob data remains. @n
 297         *                                                                               The maximum size available is limited to 100 MByte.
 298         * @exception            E_SUCCESS                       The method is successful.
 299         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 300         *                                                                               - This instance has not been properly constructed. @n
 301         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 302         *                                                                                 (the query did not yield any result). @n
 303         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 304         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 305         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 306         * @exception            E_OUT_OF_RANGE          The byte buffer operation has failed.
 307         * @exception            E_OVERFLOW                      The specified @c value of the byte buffer is insufficient to save the data.
 308         */
 309         virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const;
 310
 311         /**
 312         * Gets a blob data from the column whose index is specified.
 313         *
 314         * @since                        2.0
 315         *
 316         * @return                       An error code
 317         * @param[in]            columnIndex                     The index of the column whose value is required
 318         * @param[in,out]        buffer                          The user-provided buffer used to receive the blob data @n
 319         *                                                                               The maximum size available is limited to 100 MByte.
 320         * @param[out]           size                            The maximum buffer length in bytes
 321         * @exception            E_SUCCESS                       The method is successful.
 322         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 323         *                                                                               - This instance has not been properly constructed. @n
 324         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 325         *                                                                                 (the query did not yield any result). @n
 326         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 327         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range, or the specified @c size is invalid.
 328         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 329         * @exception            E_OVERFLOW                      The specified @c buffer is insufficient to save the data.
 330         */
 331         virtual result GetBlobAt(int columnIndex, void* buffer, int size) const;
 332
 333         /**
 334         * Gets a @c DateTime value from the column whose index is specified.
 335         *
 336         * @since                        2.0
 337         *
 338         * @return                       An error code
 339         * @param[in]            columnIndex                     The index of the column whose value is required
 340         * @param[in,out]        value                           The value obtained from the column as a DateTime instance
 341         * @exception            E_SUCCESS                       The method is successful.
 342         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 343         *                                                                               - This instance has not been properly constructed. @n
 344         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 345         *                                                                                 (the query did not yield any result). @n
 346         *                                                                               - The Database or DbStatement instance associated with this instance is deleted.
 347         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 348         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 349         * @exception            E_INVALID_FORMAT        The date is not correctly formatted, or the method is trying to access column of type String. @n
 350         *                                                                               The date format should be 'mm/dd/yyyy hh:mm:ss'.
 351         * @exception            E_OUT_OF_RANGE          Either the year(%d), month(%d), day(%d), hour(%d), minute(%d), or second(%d) value is out of range,
 352         *                                                                               or the method is trying to access a column of type String.
 353         * @remarks                      Note that the DateTime is constructed inside the method.
 354         */
 355         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;
 356
 357         /**
 358         * Gets the number of columns for this enumerator.
 359         *
 360         * @since                2.0
 361         *
 362         * @return               The number of columns in the calling enumerator, @n
 363         *                               else @c -1 if an exception occurs
 364         * @exception    E_SUCCESS                       The method is successful.
 365         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 366         *                                                                       - This instance has not been properly constructed. @n
 367         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 368         *                                                                         (the query did not yield any result). @n
 369         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 370         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 371         *                               The specific error code can be accessed using the GetLastResult() method.
 372         */
 373         virtual int GetColumnCount(void) const;
 374
 375         /**
 376         * Gets the type of the column indicated by the specified index.
 377         *
 378         * @since                2.0
 379         *
 380         * @return               The type of column, @n
 381         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 382         * @param[in]    columnIndex                     The index of the destination column
 383         * @exception    E_SUCCESS                       The method is successful.
 384         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 385         *                                                                       - This instance has not been properly constructed. @n
 386         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 387         *                                                                         (the query did not yield any result). @n
 388         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 389         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 390         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 391         *                               Currently, DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 392         *                               The specific error code can be accessed using the GetLastResult() method.
 393         */
 394         virtual DbColumnType GetColumnType(int columnIndex) const;
 395
 396         /**
 397         * Gets the name of the column indicated by the specified index.
 398         *
 399         * @since                2.0
 400         *
 401         * @return               The name of the column, @n
 402         *                               else an empty string if an exception occurs
 403         * @param[in]    columnIndex                                     The index of the destination column
 404         * @exception    E_SUCCESS                                       The method is successful.
 405         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred: @n
 406         *                                                                                       - This instance has not been properly constructed. @n
 407         *                                                                                       - The method has tried to fetch the column data of a result set that is not activated
 408         *                                                                                         (the query did not yield any result). @n
 409         *                                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 410         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 411         * @exception    E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 412         *                                                                                       it is possible if the database file is corrupted.
 413         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 414         *                               The specific error code can be accessed using the GetLastResult() method.
 415         */
 416         virtual Tizen::Base::String GetColumnName(int columnIndex) const;
 417
 418         /**
 419         * Gets the size of data in bytes.
 420         *
 421         * @since                2.0
 422         *
 423         * @return               The size of the data in bytes, @n
 424         *                               else @c -1 if an exception occurs
 425         * @param[in]    columnIndex                     The index of the destination column
 426         * @exception    E_SUCCESS                       The method is successful.
 427         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 428         *                                                                       - This instance has not been properly constructed. @n
 429         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 430         *                                                                         (the query did not yield any result). @n
 431         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 432         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 433         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 434         *                               If the destination column is of type String, this method returns the @c byte length excluding the @c null terminator character. @n
 435         *                               The specific error code can be accessed using the GetLastResult() method.
 436         */
 437         virtual int GetColumnSize(int columnIndex) const;
 438
 439 private:
 440         /**
 441         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 442         *
 443         * @since 2.0
 444         */
 445         DbEnumerator(void);
 446
 447         /**
 448         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 449         *
 450         * @since 2.0
 451         */
 452         DbEnumerator(const DbEnumerator& rhs);
 453
 454         /**
 455         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 456         * @since 2.0
 457         */
 458         DbEnumerator& operator =(const DbEnumerator& rhs);
 459
 460         class _DbEnumeratorImpl* __pDbEnumeratorImpl;
 461
 462         friend class _DbEnumeratorImpl;
 463
 464 }; // DbEnumerator
 465
 466 }} // Tizen::Io
 467
 468 #endif // _FIO_DB_ENUMERATOR_H_
 469