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, month, day, hour, minute, or second value is out of range,
 290         *                                                                               or the method is trying to access a column of type String.
 291         */
 292         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const = 0;
 293
 294         /**
 295         * Gets the number of columns for this enumerator.
 296         *
 297         * @since                2.0
 298         *
 299         * @return               The number of columns in the calling enumerator, @n
 300         *                               else @c -1 if an exception occurs
 301         * @exception    E_SUCCESS                       The method is successful.
 302         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 303         *                                                                       - This instance has not been properly constructed. @n
 304         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 305         *                                                                         (the query did not yield any result). @n
 306         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 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 indicated by the specified index.
 313         *
 314         * @since                2.0
 315         *
 316         * @return               The type of column, @n
 317         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 318         * @param[in]    columnIndex                     The index of the destination column
 319         * @exception    E_SUCCESS                       The method is successful.
 320         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 321         *                                                                       - This instance has not been properly constructed. @n
 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). @n
 324         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 325         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 326         *                               Currently, DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 327         *                               The specific error code can be accessed using the GetLastResult() method.
 328         */
 329         virtual DbColumnType GetColumnType(int columnIndex) const = 0;
 330
 331         /**
 332         * Gets the name of the column indicated by the specified index.
 333         *
 334         * @since                2.0
 335         *
 336         * @return               The name of the column, @n
 337         *                               else an empty string if an exception occurs
 338         * @param[in]    columnIndex                                     The index of the destination column
 339         * @exception    E_SUCCESS                                       The method is successful.
 340         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred: @n
 341         *                                                                                       - This instance has not been properly constructed. @n
 342         *                                                                                       - The method has tried to fetch the column data of a result set that is not activated
 343         *                                                                                         (the query did not yield any result). @n
 344         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 345         * @exception    E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range, or
 346         *                                                                                       it is possible if the database file is corrupted.
 347         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 348         *                               The specific error code can be accessed using the GetLastResult() method.
 349         */
 350         virtual Tizen::Base::String GetColumnName(int columnIndex) const = 0;
 351
 352         /**
 353         * Gets the size of data in bytes.
 354         *
 355         * @since                2.0
 356         *
 357         * @return               The size of the data in bytes, @n
 358         *                               else @c -1 if an exception occurs
 359         * @param[in]    columnIndex                     The index of the destination column
 360         * @exception    E_SUCCESS                       The method is successful.
 361         * @exception    E_INVALID_STATE         Either of the following conditions has occurred: @n
 362         *                                                                       - This instance has not been properly constructed. @n
 363         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 364         *                                                                         (the query did not yield any result). @n
 365         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 366         * @remarks              The method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 367         *                               If the destination column is of type %String, this method returns the @c byte length excluding the @c null terminator character. @n
 368         *                               The specific error code can be accessed using the GetLastResult() method.
 369         */
 370         virtual int GetColumnSize(int columnIndex) const = 0;
 371
 372 protected:
 373         //
 374         // This method is for internal use only.
 375         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 376         //
 377         // This method is reserved and may change its name at any time without prior notice.
 378         //
 379         // @since       2.0
 380         //
 381         virtual void IDbEnumerator_Reserved1(void) {}
 382
 383         //
 384         // This method is for internal use only.
 385         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 386         //
 387         // This method is reserved and may change its name at any time without prior notice.
 388         //
 389         // @since       2.0
 390         //
 391         virtual void IDbEnumerator_Reserved2(void) {}
 392
 393         //
 394         // This method is for internal use only.
 395         // Using this method can cause behavioral, security-related, and consistency-related issues in the application.
 396         //
 397         // This method is reserved and may change its name at any time without prior notice.
 398         //
 399         // @since       2.0
 400         //
 401         virtual void IDbEnumerator_Reserved3(void) {}
 402
 403 }; // IDBEnumerator
 404
 405 }} // Tizen::App
 406
 407 #endif // _FIO_IDB_ENUMERATOR_H_
 408