inc/FIoIDbEnumerator.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        FIoIDbEnumerator.h
  20  * @brief       This is the header file for the %IDbEnumerator interface.
  21  *
  22  * This header file contains the declarations of the %IDbEnumerator interface.
  23  */
  24
  25 #ifndef _FIO_IDB_ENUMERATOR_H_
  26 #define _FIO_IDB_ENUMERATOR_H_
  27
  28 #include <FBaseString.h>
  29 #include <FBaseByteBuffer.h>
  30 #include <FBaseDateTime.h>
  31 #include <FIoDbTypes.h>
  32
  33 namespace Tizen { namespace Io
  34 {
  35
  36 /**
  37  * @interface   IDbEnumerator
  38  * @brief               This interface provides methods for navigating the result set from the SELECT query.
  39  *
  40  * @since               2.0
  41  *
  42  * The %IDbEnumerator interface provides methods for navigating the result set from the SELECT query.
  43  */
  44 class _OSP_EXPORT_ IDbEnumerator
  45 {
  46
  47 public:
  48         /**
  49         * This polymorphic destructor should be overridden if required. 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: @n
  63         *                                                                       - This instance has not been properly constructed. @n
  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). @n
  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: @n
  70         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
  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: @n
  84         *                                                                       - This instance has not been properly constructed. @n
  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). @n
  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: @n
  91         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
  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: @n
 105         *                                                                       - This instance has not been properly constructed. @n
 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). @n
 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: @n
 111         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 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: @n
 125         *                                                                       - This instance has not been properly constructed. @n
 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). @n
 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: @n
 131         *                                                                       - An unexpected device failure has occurred as the media ejected suddenly. @n
 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 back 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: @n
 145         *                                                                       - This instance has not been properly constructed. @n
 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). @n
 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              After this method is called, if MoveNext() is called the cursor goes to the first position.
 151         */
 152         virtual result Reset(void) = 0;
 153
 154         /**
 155         * Gets an @c int value from the column whose index is specified.
 156         *
 157         * @since                        2.0
 158         *
 159         * @return                       An error code
 160         * @param[in]            columnIndex                     The index of the column whose value is required
 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: @n
 164         *                                                                               - This instance has not been properly constructed. @n
 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). @n
 167         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 168         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 169         */
 170         virtual result GetIntAt(int columnIndex, int& value) const = 0;
 171
 172         /**
 173         * Gets a @c long @c long value from the column whose index is specified.
 174         *
 175         * @since                        2.0
 176         *
 177         * @return                       An error code
 178         * @param[in]            columnIndex                     The index of the column whose value is required
 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: @n
 182         *                                                                               - This instance has not been properly constructed. @n
 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). @n
 185         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 186         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 187         */
 188         virtual result GetInt64At(int columnIndex, long long& value) const = 0;
 189
 190         /**
 191         * Gets a @c double value from the column whose index is specified.
 192         *
 193         * @since                        2.0
 194         *
 195         * @return                       An error code
 196         * @param[in]            columnIndex                     The index of the column whose value is required
 197         * @param[in,out]        value                           The value obtained from the column as a double
 198         * @exception            E_SUCCESS                       The method is successful.
 199         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 200         *                                                                               - This instance has not been properly constructed. @n
 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). @n
 203         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 204         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 205         */
 206         virtual result GetDoubleAt(int columnIndex, double& value) const = 0;
 207
 208         /**
 209         * Gets a @c String value from the column whose index is specified.
 210         *
 211         * @since                        2.0
 212         *
 213         * @return                       An error code
 214         * @param[in]            columnIndex                                     The index of the column whose value is required
 215         * @param[in,out]        value                                           The value obtained from the column as a String
 216         * @exception            E_SUCCESS                                       The method is successful.
 217         * @exception            E_INVALID_STATE                         Either of the following conditions has occurred: @n
 218         *                                                                                               - This instance has not been properly constructed. @n
 219         *                                                                                               - The method has tried to fetch the column data of a result set that is not activated
 220         *                                                                                                 (the query did not yield any result). @n
 221         * @exception            E_INVALID_ARG                           The specified @c columnIndex is out of range.
 222         * @exception            E_TYPE_MISMATCH                         The operation has attempted to access columns of different types.
 223         * @exception            E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 224         *                                                                                               it is possible if the database file is corrupted.
 225         */
 226         virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const = 0;
 227
 228         /**
 229         * Gets a byte array 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 user-provided buffer used to receive the blob data as a stream of type ByteBuffer @n
 236         *                                                                               The buffer will be filled from the current position and data copy will be continued
 237         *                                                                               until buffer limitation is reached or no more blob data remains. @n
 238         *                                                                               The maximum size available is limited to 100 MByte.
 239         * @exception            E_SUCCESS                       The method is successful.
 240         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 241         *                                                                               - This instance has not been properly constructed. @n
 242         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 243         *                                                                                 (the query did not yield any result). @n
 244         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 245         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 246         * @exception            E_OUT_OF_RANGE          The byte buffer operation has failed.
 247         * @exception            E_OVERFLOW                      The specified @c value of the byte buffer is insufficient to save the data.
 248         */
 249         virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const = 0;
 250
 251         /**
 252         * Gets a blob data from the column whose index is specified.
 253         *
 254         * @since                        2.0
 255         *
 256         * @return                       An error code
 257         * @param[in]            columnIndex                     The index of the column whose value is required
 258         * @param[in,out]        buffer                          The user-provided buffer used to receive the blob data @n
 259         *                                                                               The maximum size available is limited to 100 MByte.
 260         * @param[out]           size                            The maximum buffer length in bytes
 261         * @exception            E_SUCCESS                       The method is successful.
 262         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 263         *                                                                               - This instance has not been properly constructed. @n
 264         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 265         *                                                                                 (the query did not yield any result). @n
 266         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range, or the specified @c size is invalid.
 267         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 268         * @exception            E_OVERFLOW                      The specified @c buffer is insufficient to save the data.
 269         */
 270         virtual result GetBlobAt(int columnIndex, void* buffer, int size) const = 0;
 271
 272         /**
 273         * Gets a @c DateTime value from the column whose index is specified.
 274         *
 275         * @since                        2.0
 276         *
 277         * @return                       An error code
 278         * @param[in]            columnIndex                     The index of the column whose value is required
 279         * @param[in,out]        value                           The value obtained from the column as a DateTime instance
 280         * @exception            E_SUCCESS                       The method is successful.
 281         * @exception            E_INVALID_STATE         Either of the following conditions has occurred: @n
 282         *                                                                               - This instance has not been properly constructed. @n
 283         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 284         *                                                                                 (the query did not yield any result). @n
 285         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 286         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 287         * @exception            E_INVALID_FORMAT        The date is not correctly formatted, or the method is trying to access column of type String. @n
 288         *                                                                               The date format should be 'mm/dd/yyyy hh:mm:ss'.
 289         * @exception            E_OUT_OF_RANGE          Either the year(%d), month(%d), day(%d), hour(%d), minute(%d), or second(%d) value is out of range,
 290         *                                                                               or the method is trying to access a column of type String.
 291         * @remarks                      Note that the DateTime is constructed inside the method.
 292         */
 293         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const = 0;
 294
 295         /**
 296         * Gets the number of columns for this enumerator.
 297         *
 298         * @since                2.0
 299         *
 300         * @return               The number of columns in the calling enumerator, @n
 301         *                               else @c -1 if an exception occurs
 302         * @exception    E_SUCCESS                       The method is successful.
 303         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 304         *                                                                       - This instance has not been properly constructed. @n
 305         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 306         *                                                                         (the query did not yield any result). @n
 307         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 308         *                               The specific error code can be accessed using the GetLastResult() method.
 309         */
 310         virtual int GetColumnCount(void) const = 0;
 311
 312         /**
 313         * Gets the type of the column indicated by the specified index.
 314         *
 315         * @since                2.0
 316         *
 317         * @return               The type of column, @n
 318         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 319         * @param[in]    columnIndex                     The index of the destination column
 320         * @exception    E_SUCCESS                       The method is successful.
 321         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 322         *                                                                       - This instance has not been properly constructed. @n
 323         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 324         *                                                                         (the query did not yield any result). @n
 325         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 326         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 327         *                               Currently, DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 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 indicated by the specified 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 index of the destination column
 340         * @exception    E_SUCCESS                                       The method is successful.
 341         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred: @n
 342         *                                                                                       - This instance has not been properly constructed. @n
 343         *                                                                                       - The method has tried to fetch the column data of a result set that is not activated
 344         *                                                                                         (the query did not yield any result). @n
 345         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 346         * @exception    E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 347         *                                                                                       it is possible if the database file is corrupted.
 348         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 349         *                               The specific error code can be accessed using the GetLastResult() method.
 350         */
 351         virtual Tizen::Base::String GetColumnName(int columnIndex) const = 0;
 352
 353         /**
 354         * Gets the size of data in bytes.
 355         *
 356         * @since                2.0
 357         *
 358         * @return               The size of the data in bytes, @n
 359         *                               else @c -1 if an exception occurs
 360         * @param[in]    columnIndex                     The index of the destination column
 361         * @exception    E_SUCCESS                       The method is successful.
 362         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 363         *                                                                       - This instance has not been properly constructed. @n
 364         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 365         *                                                                         (the query did not yield any result). @n
 366         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 367         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 368         *                               If the destination column is of type %String, this method returns the @c byte length excluding the @c null terminator character. @n
 369         *                               The specific error code can be accessed using the GetLastResult() method.
 370         */
 371         virtual int GetColumnSize(int columnIndex) const = 0;
 372
 373 protected:
 374         //
 375         // This method is for internal use only.
 376         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 377         //
 378         // This method is reserved and may change its name at any time without prior notice.
 379         //
 380         // @since       2.0
 381         //
 382         virtual void IDbEnumerator_Reserved1(void) {}
 383
 384         //
 385         // This method is for internal use only.
 386         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 387         //
 388         // This method is reserved and may change its name at any time without prior notice.
 389         //
 390         // @since       2.0
 391         //
 392         virtual void IDbEnumerator_Reserved2(void) {}
 393
 394         //
 395         // This method is for internal use only.
 396         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 397         //
 398         // This method is reserved and may change its name at any time without prior notice.
 399         //
 400         // @since       2.0
 401         //
 402         virtual void IDbEnumerator_Reserved3(void) {}
 403
 404 }; // IDBEnumerator
 405
 406 }} // Tizen::App
 407
 408 #endif // _FIO_IDB_ENUMERATOR_H_
 409