inc/FIoIDbEnumerator.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        FIoIDbEnumerator.h
  19  * @brief       This is the header file for the %IDbEnumerator interface.
  20  *
  21  * This header file contains the declarations of the %IDbEnumerator interface.
  22  */
  23
  24 #ifndef _FIO_IDB_ENUMERATOR_H_
  25 #define _FIO_IDB_ENUMERATOR_H_
  26
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FBaseDateTime.h>
  30 #include <FIoDbTypes.h>
  31
  32 namespace Tizen { namespace Io
  33 {
  34
  35 /**
  36  * @interface   IDbEnumerator
  37  * @brief               This interface provides methods for navigating the result set from the SELECT query.
  38  *
  39  * @since               2.0
  40  *
  41  * The %IDbEnumerator interface provides methods for navigating the result set from the SELECT query.
  42  */
  43 class _OSP_EXPORT_ IDbEnumerator
  44 {
  45
  46 public:
  47         /**
  48         * This polymorphic destructor should be overridden if required. @n
  49         * This way, the destructors of the derived classes are called when the destructor of this interface is called.
  50         *
  51         * @since        2.0
  52         */
  53         virtual ~IDbEnumerator(void) {}
  54
  55         /**
  56         * Moves the enumerator to the next position.
  57         *
  58         * @since                2.0
  59         *
  60         * @return               An error code
  61         * @exception    E_SUCCESS                       The method is successful.
  62         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
  63         *                                                                       - This instance has not been properly constructed.
  64         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
  65         *                                                                         (the query did not yield any result).
  66         * @exception    E_OUT_OF_RANGE          The enumerator has reached out of the result set returned by the SELECT query.
  67         * @exception    E_OBJECT_LOCKED         The database instance is locked.
  68         * @exception    E_INVALID_FORMAT        The database file is malformed.
  69         * @exception    E_IO                            Either of the following conditions has occurred:
  70         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
  71         *                                                                       - %File corruption is detected.
  72         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  73         */
  74         virtual result MoveNext(void) = 0;
  75
  76         /**
  77         * Moves the enumerator to the previous position.
  78         *
  79         * @since                2.0
  80         *
  81         * @return               An error code
  82         * @exception    E_SUCCESS                       The method is successful.
  83         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
  84         *                                                                       - This instance has not been properly constructed.
  85         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
  86         *                                                                         (the query did not yield any result).
  87         * @exception    E_OUT_OF_RANGE          The enumerator has reached out of the result set returned by the SELECT query.
  88         * @exception    E_OBJECT_LOCKED         The database instance is locked.
  89         * @exception    E_INVALID_FORMAT        The database file is malformed.
  90         * @exception    E_IO                            Either of the following conditions has occurred:
  91         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
  92         *                                                                       - %File corruption is detected.
  93         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
  94         */
  95         virtual result MovePrevious(void) = 0;
  96
  97         /**
  98         * Moves the enumerator to the first position.
  99         *
 100         * @since                2.0
 101         *
 102         * @return               An error code
 103         * @exception    E_SUCCESS                       The method is successful.
 104         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 105         *                                                                       - This instance has not been properly constructed.
 106         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 107         *                                                                         (the query did not yield any result).
 108         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 109         * @exception    E_INVALID_FORMAT        The database file is malformed.
 110         * @exception    E_IO                            Either of the following conditions has occurred:
 111         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 112         *                                                                       - %File corruption is detected.
 113         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 114         */
 115         virtual result MoveFirst(void) = 0;
 116
 117         /**
 118         * Moves the enumerator to the last position.
 119         *
 120         * @since                2.0
 121         *
 122         * @return               An error code
 123         * @exception    E_SUCCESS                       The method is successful.
 124         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 125         *                                                                       - This instance has not been properly constructed.
 126         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 127         *                                                                         (the query did not yield any result).
 128         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 129         * @exception    E_INVALID_FORMAT        The database file is malformed.
 130         * @exception    E_IO                            Either of the following conditions has occurred:
 131         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly.
 132         *                                                                       - %File corruption is detected.
 133         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 134         */
 135         virtual result MoveLast(void) = 0;
 136
 137         /**
 138         * Resets the calling %IDbEnumerator instance to its initial state.
 139         *
 140         * @since                2.0
 141         *
 142         * @return               An error code
 143         * @exception    E_SUCCESS                       The method is successful.
 144         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 145         *                                                                       - This instance has not been properly constructed.
 146         *                                                                       - The method has tried to reset the enumerator of the result set that is not activated
 147         *                                                                         (the query did not yield any result).
 148         * @exception    E_OBJECT_LOCKED         The database instance is locked.
 149         * @exception    E_SYSTEM                        The method cannot proceed due to a severe system error.
 150         * @remarks              If MoveNext() is called after this method, the cursor goes to the first position.
 151         */
 152         virtual result Reset(void) = 0;
 153
 154         /**
 155         * Gets the @c int value from the column with the specified index.
 156         *
 157         * @since                        2.0
 158         *
 159         * @return                       An error code
 160         * @param[in]            columnIndex                     The index of the column to get the value
 161         * @param[in,out]        value                           The integer value obtained from the column
 162         * @exception            E_SUCCESS                       The method is successful.
 163         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 164         *                                                                               - This instance has not been properly constructed.
 165         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 166         *                                                                                 (the query did not yield any result).
 167         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 168         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 169         */
 170         virtual result GetIntAt(int columnIndex, int& value) const = 0;
 171
 172         /**
 173         * Gets the @c long @c long value from the column with the specified index.
 174         *
 175         * @since                        2.0
 176         *
 177         * @return                       An error code
 178         * @param[in]            columnIndex                     The index of the column to get the value
 179         * @param[in,out]        value                           The 64-bit integer value obtained from the column
 180         * @exception            E_SUCCESS                       The method is successful.
 181         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 182         *                                                                               - This instance has not been properly constructed.
 183         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 184         *                                                                                 (the query did not yield any result).
 185         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 186         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 187         */
 188         virtual result GetInt64At(int columnIndex, long long& value) const = 0;
 189
 190         /**
 191         * Gets the @c double value from the column with the specified index.
 192         *
 193         * @since                        2.0
 194         *
 195         * @return                       An error code
 196         * @param[in]            columnIndex                     The index of the column to get the value
 197         * @param[in,out]        value                           The double value obtained from the column
 198         * @exception            E_SUCCESS                       The method is successful.
 199         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 200         *                                                                               - This instance has not been properly constructed.
 201         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 202         *                                                                                 (the query did not yield any result).
 203         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 204         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 205         */
 206         virtual result GetDoubleAt(int columnIndex, double& value) const = 0;
 207
 208         /**
 209         * Gets the @c String 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 @c String 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:
 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         * @exception            E_INVALID_ARG                           The specified @c columnIndex is out of range.
 222         * @exception            E_TYPE_MISMATCH                         The column type accessed by the method do not match.
 223         * @exception            E_INVALID_ENCODING_RANGE        Either of the following conditions has occurred:
 224         *                                                                                               - The string conversion has failed due to invalid encoding range.
 225         *                                                                                               - The database file is corrupted.
 226         */
 227         virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const = 0;
 228
 229         /**
 230         * Gets the byte array value from the column with the specified index.
 231         *
 232         * @since                        2.0
 233         *
 234         * @return                       An error code
 235         * @param[in]            columnIndex                     The index of the column to get the value
 236         * @param[in,out]        value                           The buffer used to receive the blob data as a stream of type ByteBuffer @n
 237         *                                                                               The buffer will be filled from the current position and the data copying will be continued
 238         *                                                                               until the buffer limitation is reached or no more blob data remains. @n
 239         *                                                                               The maximum size available is limited to 100 MByte.
 240         * @exception            E_SUCCESS                       The method is successful.
 241         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 242         *                                                                               - This instance has not been properly constructed.
 243         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 244         *                                                                                 (the query did not yield any result).
 245         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 246         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 247         * @exception            E_OUT_OF_RANGE          The byte buffer operation has failed.
 248         * @exception            E_OVERFLOW                      The specified @c value of the byte buffer is insufficient to save the data.
 249         */
 250         virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const = 0;
 251
 252         /**
 253         * Gets the blob data from the column with the specified index.
 254         *
 255         * @since                        2.0
 256         *
 257         * @return                       An error code
 258         * @param[in]            columnIndex                     The index of the column to get the value
 259         * @param[in,out]        buffer                          The buffer used to receive the blob data @n
 260         *                                                                               The maximum size available is limited to 100 MByte.
 261         * @param[out]           size                            The maximum buffer length in bytes
 262         * @exception            E_SUCCESS                       The method is successful.
 263         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 264         *                                                                               - This instance has not been properly constructed.
 265         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 266         *                                                                                 (the query did not yield any result).
 267         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range, or the specified @c size is invalid.
 268         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 269         * @exception            E_OVERFLOW                      The specified @c buffer is insufficient to save the data.
 270         */
 271         virtual result GetBlobAt(int columnIndex, void* buffer, int size) const = 0;
 272
 273         /**
 274         * Gets the @c DateTime value from the column with the specified index.
 275         *
 276         * @since                        2.0
 277         *
 278         * @return                       An error code
 279         * @param[in]            columnIndex                     The index of the column to get the value
 280         * @param[in,out]        value                           The value obtained from the column as a DateTime instance
 281         * @exception            E_SUCCESS                       The method is successful.
 282         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 283         *                                                                               - This instance has not been properly constructed.
 284         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 285         *                                                                                 (the query did not yield any result).
 286         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 287         * @exception            E_TYPE_MISMATCH         The column type accessed by the method do not match.
 288         * @exception            E_INVALID_FORMAT        The date is not correctly formatted. The date format should be 'mm/dd/yyyy hh:mm:ss'.
 289         * @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.
 290         */
 291         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const = 0;
 292
 293         /**
 294         * Gets the number of columns for this enumerator.
 295         *
 296         * @since                2.0
 297         *
 298         * @return               The number of columns in the current enumerator, @n
 299         *                               else @c -1 if an exception occurs
 300         * @exception    E_SUCCESS                       The method is successful.
 301         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 302         *                                                                       - This instance has not been properly constructed.
 303         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 304         *                                                                         (the query did not yield any result).
 305         * @remarks
 306         *                               - The method must be called after MoveNext(), MoveFirst(), or MoveLast().
 307         *                               - The specific error code can be accessed using the GetLastResult() method.
 308         */
 309         virtual int GetColumnCount(void) const = 0;
 310
 311         /**
 312         * Gets the type of the column specified by the index.
 313         *
 314         * @since                2.0
 315         *
 316         * @return               The column type, @n
 317         *                               else @c DB_COLUMNTYPE_UNDEFINED if an exception occurs
 318         * @param[in]    columnIndex                     The column index
 319         * @exception    E_SUCCESS                       The method is successful.
 320         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 321         *                                                                       - This instance has not been properly constructed.
 322         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 323         *                                                                         (the query did not yield any result).
 324         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 325         * @remarks
 326         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 327         *                               - Currently, @c DB_COLUMNTYPE_INT is returned for a 64-bit integer.
 328         *                               - The specific error code can be accessed using the GetLastResult() method.
 329         */
 330         virtual DbColumnType GetColumnType(int columnIndex) const = 0;
 331
 332         /**
 333         * Gets the name of the column specified by the index.
 334         *
 335         * @since                2.0
 336         *
 337         * @return               The name of the column, @n
 338         *                               else an empty string if an exception occurs
 339         * @param[in]    columnIndex                                     The column index
 340         * @exception    E_SUCCESS                                       The method is successful.
 341         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred:
 342         *                                                                                       - This instance has not been properly constructed.
 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).
 345         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 346         * @exception    E_INVALID_ENCODING_RANGE        Either of the following conditions has occurred:
 347         *                                                                                       - The string conversion has failed due to invalid encoding range.
 348         *                                                                                       - The database file is corrupted.
 349         * @remarks
 350         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 351         *                               - The specific error code can be accessed using the GetLastResult() method.
 352         */
 353         virtual Tizen::Base::String GetColumnName(int columnIndex) const = 0;
 354
 355         /**
 356         * Gets the size of data in bytes of the column specified by the index.
 357         *
 358         * @since                2.0
 359         *
 360         * @return               The size of the data in bytes, @n
 361         *                               else @c -1 if an exception occurs
 362         * @param[in]    columnIndex                     The column index
 363         * @exception    E_SUCCESS                       The method is successful.
 364         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 365         *                                                                       - This instance has not been properly constructed.
 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).
 368         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 369         * @remarks
 370         *                               - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
 371         *                               - If the destination column is of type String, this method returns the @c byte length excluding the @c null terminator character.
 372         *                               - The specific error code can be accessed using the GetLastResult() method.
 373         */
 374         virtual int GetColumnSize(int columnIndex) const = 0;
 375
 376 protected:
 377         //
 378         // This method is for internal use only.
 379         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 380         //
 381         // This method is reserved and may change its name at any time without prior notice.
 382         //
 383         // @since       2.0
 384         //
 385         virtual void IDbEnumerator_Reserved1(void) {}
 386
 387         //
 388         // This method is for internal use only.
 389         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 390         //
 391         // This method is reserved and may change its name at any time without prior notice.
 392         //
 393         // @since       2.0
 394         //
 395         virtual void IDbEnumerator_Reserved2(void) {}
 396
 397         //
 398         // This method is for internal use only.
 399         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 400         //
 401         // This method is reserved and may change its name at any time without prior notice.
 402         //
 403         // @since       2.0
 404         //
 405         virtual void IDbEnumerator_Reserved3(void) {}
 406
 407 }; // IDBEnumerator
 408
 409 }} // Tizen::App
 410
 411 #endif // _FIO_IDB_ENUMERATOR_H_
 412