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, month, day, hour, minute, or second value is out of range,
 352         *                                                                               or the method is trying to access a column of type String.
 353         */
 354         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;
 355
 356         /**
 357         * Gets the number of columns for this enumerator.
 358         *
 359         * @since                2.0
 360         *
 361         * @return               The number of columns in the calling enumerator, @n
 362         *                               else @c -1 if an exception occurs
 363         * @exception    E_SUCCESS                       The method is successful.
 364         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 365         *                                                                       - This instance has not been properly constructed. @n
 366         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 367         *                                                                         (the query did not yield any result). @n
 368         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 369         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 370         *                               The specific error code can be accessed using the GetLastResult() method.
 371         */
 372         virtual int GetColumnCount(void) const;
 373
 374         /**
 375         * Gets the type of the column indicated by the specified index.
 376         *
 377         * @since                2.0
 378         *
 379         * @return               The type of column, @n
 380         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 381         * @param[in]    columnIndex                     The index of the destination column
 382         * @exception    E_SUCCESS                       The method is successful.
 383         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 384         *                                                                       - This instance has not been properly constructed. @n
 385         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 386         *                                                                         (the query did not yield any result). @n
 387         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 388         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 389         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 390         *                               Currently, DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 391         *                               The specific error code can be accessed using the GetLastResult() method.
 392         */
 393         virtual DbColumnType GetColumnType(int columnIndex) const;
 394
 395         /**
 396         * Gets the name of the column indicated by the specified index.
 397         *
 398         * @since                2.0
 399         *
 400         * @return               The name of the column, @n
 401         *                               else an empty string if an exception occurs
 402         * @param[in]    columnIndex                                     The index of the destination column
 403         * @exception    E_SUCCESS                                       The method is successful.
 404         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred: @n
 405         *                                                                                       - This instance has not been properly constructed. @n
 406         *                                                                                       - The method has tried to fetch the column data of a result set that is not activated
 407         *                                                                                         (the query did not yield any result). @n
 408         *                                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 409         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 410         * @exception    E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 411         *                                                                                       it is possible if the database file is corrupted.
 412         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 413         *                               The specific error code can be accessed using the GetLastResult() method.
 414         */
 415         virtual Tizen::Base::String GetColumnName(int columnIndex) const;
 416
 417         /**
 418         * Gets the size of data in bytes.
 419         *
 420         * @since                2.0
 421         *
 422         * @return               The size of the data in bytes, @n
 423         *                               else @c -1 if an exception occurs
 424         * @param[in]    columnIndex                     The index of the destination column
 425         * @exception    E_SUCCESS                       The method is successful.
 426         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 427         *                                                                       - This instance has not been properly constructed. @n
 428         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 429         *                                                                         (the query did not yield any result). @n
 430         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 431         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 432         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 433         *                               If the destination column is of type String, this method returns the @c byte length excluding the @c null terminator character. @n
 434         *                               The specific error code can be accessed using the GetLastResult() method.
 435         */
 436         virtual int GetColumnSize(int columnIndex) const;
 437
 438 private:
 439         /**
 440         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 441         *
 442         * @since 2.0
 443         */
 444         DbEnumerator(void);
 445
 446         /**
 447         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 448         *
 449         * @since 2.0
 450         */
 451         DbEnumerator(const DbEnumerator& rhs);
 452
 453         /**
 454         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 455         * @since 2.0
 456         */
 457         DbEnumerator& operator =(const DbEnumerator& rhs);
 458
 459         class _DbEnumeratorImpl* __pDbEnumeratorImpl;
 460
 461         friend class _DbEnumeratorImpl;
 462
 463 }; // DbEnumerator
 464
 465 }} // Tizen::Io
 466
 467 #endif // _FIO_DB_ENUMERATOR_H_
 468