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