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:
  85         *                                                                       - This instance has not been properly constructed.
  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).
  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:
  93         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
  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:
 112         *                                                                       - This instance has not been properly constructed.
 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).
 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:
 120         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 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:
 139         *                                                                       - This instance has not been properly constructed.
 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).
 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:
 146         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 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:
 165         *                                                                       - This instance has not been properly constructed.
 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).
 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:
 172         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 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 current %DbEnumerator instance 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:
 198         *                                                                       - This instance has not been properly constructed.
 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).
 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              If MoveNext() is called after this method, the cursor goes to the first position.
 205         */
 206         virtual result Reset(void);
 207
 208         /**
 209         * Gets the @c int value from the column with the specified index.
 210         *
 211         * @since                        2.0
 212         *
 213         * @return                       An error code
 214         * @param[in]            columnIndex                     The index of the column to get the value
 215         * @param[in,out]        value                           The integer value obtained from the specified column
 216         * @exception            E_SUCCESS                       The method is successful.
 217         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 218         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 224         */
 225         virtual result GetIntAt(int columnIndex, int& value) const;
 226
 227         /**
 228         * Gets the @c long @c long value from the column with the specified index.
 229         *
 230         * @since                        2.0
 231         *
 232         * @return                       An error code
 233         * @param[in]            columnIndex                     The index of the column to get the value
 234         * @param[in,out]        value                           The 64-bit integer value obtained from the specified column
 235         * @exception            E_SUCCESS                       The method is successful.
 236         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 237         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 243         */
 244         virtual result GetInt64At(int columnIndex, long long& value) const;
 245
 246         /**
 247         * Gets the @c double value from the column with the specified index.
 248         *
 249         * @since                        2.0
 250         *
 251         * @return                       An error code
 252         * @param[in]            columnIndex                     The index of the column to get the value
 253         * @param[in,out]        value                           The double value obtained from the column
 254         * @exception            E_SUCCESS                       The method is successful.
 255         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 256         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 262         */
 263         virtual result GetDoubleAt(int columnIndex, double& value) const;
 264
 265         /**
 266         * Gets the @c String value from the column with the specified index.
 267         *
 268         * @since                        2.0
 269         *
 270         * @return                       An error code
 271         * @param[in]            columnIndex                                     The index of the column to get the value
 272         * @param[in,out]        value                                           The @c String value obtained from the column
 273         * @exception            E_SUCCESS                                       The method is successful.
 274         * @exception            E_INVALID_STATE                         Either of the following conditions has occurred:
 275         *                                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 281         * @exception            E_INVALID_ENCODING_RANGE        Either of the following conditions has occurred:
 282         *                                                                                               - The string conversion has failed due to invalid encoding range.
 283         *                                                                                               - The database file is corrupted.
 284         */
 285         virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const;
 286
 287         /**
 288         * Gets the byte array value from the column with the specified index.
 289         *
 290         * @since                        2.0
 291         *
 292         * @return                       An error code
 293         * @param[in]            columnIndex                     The index of the column to get the value
 294         * @param[in,out]        value                           The buffer to receive the blob data as a stream of type ByteBuffer @n
 295         *                                                                               The buffer will be filled from the current position and the data copying will be continued
 296         *                                                                               until the 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:
 300         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 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 the blob data from the column with the specified index.
 313         *
 314         * @since                        2.0
 315         *
 316         * @return                       An error code
 317         * @param[in]            columnIndex                     The index of the column to get the value
 318         * @param[in,out]        buffer                          The buffer 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:
 323         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 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 the @c DateTime value from the column with the specified index.
 335         *
 336         * @since                        2.0
 337         *
 338         * @return                       An error code
 339         * @param[in]            columnIndex                     The index of the column to get the value
 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:
 343         *                                                                               - This instance has not been properly constructed.
 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).
 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 column type accessed by the method do not match.
 349         * @exception            E_INVALID_FORMAT        The date is not correctly formatted. 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, or the method is trying to access a column having an invalid value.
 351     *
 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 current 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:
 364         *                                                                       - This instance has not been properly constructed.
 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).
 367         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 368         * @remarks
 369         *                               - The method must be called after MoveNext(), MoveFirst(), or MoveLast().
 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 specified by the index.
 376         *
 377         * @since                2.0
 378         *
 379         * @return               The column type, @n
 380         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 381         * @param[in]    columnIndex                     The column index
 382         * @exception    E_SUCCESS                       The method is successful.
 383         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 384         *                                                                       - This instance has not been properly constructed.
 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).
 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
 390         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 391         *                               - Currently, ::DB_COLUMNTYPE_INT is returned for a 64-bit integer.
 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 specified by the 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 column index
 404         * @exception    E_SUCCESS                                       The method is successful.
 405         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred:
 406         *                                                                                       - This instance has not been properly constructed.
 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).
 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        Either of the following conditions has occurred:
 412         *                                                                                       - The string conversion has failed due to invalid encoding range.
 413         *                                                                                       - The database file is corrupted.
 414         * @remarks
 415         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 416         *                               - The specific error code can be accessed using the GetLastResult() method.
 417         */
 418         virtual Tizen::Base::String GetColumnName(int columnIndex) const;
 419
 420         /**
 421         * Gets the size of data in bytes of the column specified by the index.
 422         *
 423         * @since                2.0
 424         *
 425         * @return               The size of the data in bytes, @n
 426         *                               else @c -1 if an exception occurs
 427         * @param[in]    columnIndex                     The column index
 428         * @exception    E_SUCCESS                       The method is successful.
 429         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 430         *                                                                       - This instance has not been properly constructed.
 431         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 432         *                                                                         (the query did not yield any result).
 433         *                                                                       - The Database or DbStatement instance associated with this instance is deleted.
 434         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 435         * @remarks
 436         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 437         *                               - If the destination column is of type String, this method returns the @c byte length excluding the @c null terminator character.
 438         *                               - The specific error code can be accessed using the GetLastResult() method.
 439         */
 440         virtual int GetColumnSize(int columnIndex) const;
 441
 442 private:
 443         /**
 444         * This default constructor is intentionally declared as private so that only the platform can create an instance.
 445         *
 446         * @since 2.0
 447         */
 448         DbEnumerator(void);
 449
 450         /**
 451         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 452         *
 453         * @since 2.0
 454         */
 455         DbEnumerator(const DbEnumerator& rhs);
 456
 457         /**
 458         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 459         * @since 2.0
 460         */
 461         DbEnumerator& operator =(const DbEnumerator& rhs);
 462
 463         class _DbEnumeratorImpl* __pDbEnumeratorImpl;
 464
 465         friend class _DbEnumeratorImpl;
 466
 467 }; // DbEnumerator
 468
 469 }} // Tizen::Io
 470
 471 #endif // _FIO_DB_ENUMERATOR_H_
 472