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