src/io/inc/FIo_DataControlResultSetEnumerator.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    FIo_DataControlResultSetEnumerator.h
  20  * @brief   This is the header file for the %_DataControlResultSetEnumerator class.
  21  *
  22  * This header file contains the declarations of the %_DataControlResultSetEnumerator class.
  23  */
  24
  25 #ifndef _FIO_INTERNAL_DATACONTROL_RESULTSET_ENUMERATOR_H_
  26 #define _FIO_INTERNAL_DATACONTROL_RESULTSET_ENUMERATOR_H_
  27
  28 #include <FBaseString.h>
  29 #include <FBaseDateTime.h>
  30 #include <FBaseByteBuffer.h>
  31 #include <FOspConfig.h>
  32 #include <FIoDbTypes.h>
  33 #include <FIoIDbEnumerator.h>
  34 #include <FBaseColLinkedList.h>
  35
  36 namespace Tizen { namespace App
  37 {
  38 class _SqlDataControlImpl;
  39 }}
  40
  41 namespace Tizen { namespace Io
  42 {
  43
  44 /**
  45 * @class    _DataControlResultSetEnumerator
  46 * @brief    This class provides methods for navigating the result set from SQL-type data control query request.
  47 * @since 2.1
  48 */
  49 class _OSP_EXPORT_ _DataControlResultSetEnumerator
  50         : public Tizen::Base::Object
  51         , public Tizen::Io::IDbEnumerator
  52 {
  53
  54 public:
  55         /**
  56         * This is the destructor for this class.
  57         *
  58         * @since 2.1
  59         */
  60         virtual ~_DataControlResultSetEnumerator(void);
  61
  62         /**
  63         * Moves the enumerator to the next position.
  64         *
  65         * @since 2.1
  66         * @return               An error code
  67         * @exception    E_SUCCESS                       The method is successful.
  68         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
  69         *                                                                       - This instance has not been properly constructed.
  70         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
  71         *                                                                         (the query did not yield any result).
  72         * @exception    E_OUT_OF_RANGE          The enumerator has reached out of the result set.
  73         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
  74         */
  75         virtual result MoveNext(void);
  76
  77         /**
  78         * Moves the enumerator to the previous position.
  79         *
  80         * @since 2.1
  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.
  88         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
  89         */
  90         virtual result MovePrevious(void);
  91
  92         /**
  93         * Moves the enumerator to the first position.
  94         *
  95         * @since 2.1
  96         * @return               An error code
  97         * @exception    E_SUCCESS                       The method is successful.
  98         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
  99         *                                                                       - This instance has not been properly constructed.
 100         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 101         *                                                                         (the query did not yield any result).
 102         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 103         */
 104         virtual result MoveFirst(void);
 105
 106         /**
 107         * Moves the enumerator to the last position.
 108         *
 109         * @since 2.1
 110         * @return               An error code
 111         * @exception    E_SUCCESS                       The method is successful.
 112         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 113         *                                                                       - This instance has not been properly constructed.
 114         *                                                                       - The method has tried to move the cursor position of the result set that is not activated
 115         *                                                                         (the query did not yield any result).
 116         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 117         */
 118         virtual result MoveLast(void);
 119
 120         /**
 121         * Resets the calling %DataControlResultSetEnumerator instance back to its initial state.
 122         *
 123         * @since 2.1
 124         * @return           An error code
 125         * @exception    E_SUCCESS                       The method is successful.
 126         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 127         *                                                                       - This instance has not been properly constructed.
 128         *                                                                       - The method has tried to reset the enumerator of the result set that is not activated
 129         *                                                                         (the query did not yield any result).
 130         * @remarks              After this method is called, if MoveNext() is called the cursor goes to the first position.
 131         * @see                  Tizen::Io::DataControlResultSetEnumerator::MoveNext()
 132         */
 133         virtual result Reset(void);
 134
 135         /**
 136         * Gets a @c int value from the column whose index is specified.
 137         *
 138         * @since 2.1
 139         * @return                       An error code
 140         * @param[in]            columnIndex                     The index of the column whose value is required
 141         * @param[in,out]        value                           The integer value obtained from the column
 142         * @exception            E_SUCCESS                       The method is successful.
 143         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 144         *                                                                               - This instance has not been properly constructed.
 145         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 146         *                                                                                 (the query did not yield any result).
 147         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 148         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 149         */
 150         virtual result GetIntAt(int columnIndex, int& value) const;
 151
 152         /**
 153         * Gets a @c long @c long value from the column whose index is specified.
 154         *
 155         * @since 2.1
 156         * @return                       An error code
 157         * @param[in]            columnIndex                     The index of the column whose value is required
 158         * @param[in,out]        value                           The 64-bit integer value obtained from the column
 159         * @exception            E_SUCCESS                       The method is successful.
 160         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 161         *                                                                               - This instance has not been properly constructed.
 162         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 163         *                                                                                 (the query did not yield any result).
 164         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 165         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 166         */
 167         virtual result GetInt64At(int columnIndex, long long& value) const;
 168
 169         /**
 170         * Gets a @c double value from the column whose index is specified.
 171         *
 172         * @since 2.1
 173         * @return                       An error code
 174         * @param[in]            columnIndex                     The index of the column whose value is required
 175         * @param[in,out]        value                           The value obtained from the column as a double
 176         * @exception            E_SUCCESS                       The method is successful.
 177         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 178         *                                                                               - This instance has not been properly constructed.
 179         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 180         *                                                                                 (the query did not yield any result).
 181         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 182         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 183         */
 184         virtual result GetDoubleAt(int columnIndex, double& value) const;
 185
 186         /**
 187         * Gets a @c String value from the column whose index is specified.
 188         *
 189         * @since 2.1
 190         * @return                       An error code
 191         * @param[in]            columnIndex                                     The index of the column whose value is required
 192         * @param[in,out]        value                                           The value obtained from the column as a String
 193         * @exception            E_SUCCESS                                       The method is successful.
 194         * @exception            E_INVALID_STATE                         Either of the following conditions has occurred:
 195         *                                                                                               - This instance has not been properly constructed.
 196         *                                                                                               - The method has tried to fetch the column data of a result set that is not activated
 197         *                                                                                                 (the query did not yield any result).
 198         * @exception            E_INVALID_ARG                           The specified @c columnIndex is out of range.
 199         * @exception            E_TYPE_MISMATCH                         The operation has attempted to access columns of different types.
 200         * @exception            E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range.
 201         */
 202         virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const;
 203
 204         /**
 205         * Gets a byte array value from the column whose index is specified.
 206         *
 207         * @since 2.1
 208         * @return                       An error code
 209         * @param[in]            columnIndex                     The index of the column whose value is required
 210         * @param[in,out]        value                           The user-provided buffer used to receive the blob data as a stream of type ByteBuffer. @n
 211         *                                                                               The buffer will be filled from the current position and data copy will be continued
 212         *                                                                               until buffer limitation is reached or no more blob data remains. @n
 213         *                                                                               The maximum size available is limited to 100 MByte.
 214         * @exception            E_SUCCESS                       The method is successful.
 215         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 216         *                                                                               - This instance has not been properly constructed.
 217         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 218         *                                                                                 (the query did not yield any result).
 219         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 220         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 221         * @exception            E_OUT_OF_RANGE          The byte buffer operation has failed.
 222         * @exception            E_OVERFLOW                      The specified @c value of the byte buffer is insufficient to save the data.
 223         */
 224         virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const;
 225
 226         /**
 227         * Gets a blob data from the column whose index is specified.
 228         *
 229         * @since 2.1
 230         * @return                       An error code
 231         * @param[in]            columnIndex                     The index of the column whose value is required
 232         * @param[in,out]        buffer                          The user-provided buffer used to receive the blob data @n
 233         *                                                                               The maximum size available is limited to 100 MByte.
 234         * @param[out]           size                            The maximum buffer length in bytes
 235         * @exception            E_SUCCESS                       The method is successful.
 236         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 237         *                                                                               - This instance has not been properly constructed.
 238         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 239         *                                                                                 (the query did not yield any result).
 240         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range, or the specified @c size is invalid.
 241         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 242         * @exception            E_OVERFLOW                      The specified @c buffer is insufficient to save the data.
 243         */
 244         virtual result GetBlobAt(int columnIndex, void* buffer, int size) const;
 245
 246         /**
 247         * Gets a @c DateTime value from the column whose index is specified.
 248         *
 249         * @since 2.1
 250         * @return                       An error code
 251         * @param[in]            columnIndex             The index of the column whose value is required
 252         * @param[in,out]        value                   The value obtained from the column as a DateTime instance
 253         * @exception            E_SUCCESS                       The method is successful.
 254         * @exception            E_INVALID_STATE         Either of the following conditions has occurred:
 255         *                                                                               - This instance has not been properly constructed.
 256         *                                                                               - The method has tried to fetch the column data of a result set that is not activated
 257         *                                                                                 (the query did not yield any result).
 258         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 259         * @exception            E_TYPE_MISMATCH         The operation has attempted to access columns of different types.
 260         * @exception            E_INVALID_FORMAT        The date is not correctly formatted, or the method is trying to access column of type String. @n
 261         *                                                                               The date format should be 'mm/dd/yyyy hh:mm:ss'.
 262         * @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,
 263         *                                                                               or the method is trying to access a column of type String.
 264         * @remarks                      Note that the DateTime is constructed inside the method.
 265         */
 266         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;
 267
 268         /**
 269         * Gets the number of columns for this enumerator.
 270         *
 271         * @since 2.1
 272         * @return               The number of columns in the calling enumerator, @n
 273         *                               else @c -1 if an exception occurs
 274         * @exception    E_SUCCESS                       The method is successful.
 275         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 276         *                                                                       - This instance has not been properly constructed.
 277         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 278         *                                                                         (the query did not yield any result).
 279         * @remarks              This method should be called after MoveNext() or MoveFirst() or MoveLast(). @n
 280         *                               The specific error code can be accessed using the GetLastResult() method.
 281         */
 282         virtual int GetColumnCount(void) const;
 283
 284         /**
 285         * Gets the type of the column indicated by the specified index.
 286         *
 287         * @since 2.1
 288         * @return               The type of column @n
 289         *                               else DB_COLUMNTYPE_UNDEFINED if an exception occurs
 290         * @param[in]    columnIndex                     The index of the destination column
 291         * @exception    E_SUCCESS                       The method is successful.
 292         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 293         *                                                                       - This instance has not been properly constructed.
 294         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 295         *                                                                         (the query did not yield any result).
 296         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 297         * @remarks              The method should be called after MoveNext() or MoveFirst() or MoveLast(). @n
 298         *                               Currently, DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 299         *                               The specific error code can be accessed using the GetLastResult() method.
 300         */
 301         virtual DbColumnType GetColumnType(int columnIndex) const;
 302
 303         /**
 304         * Gets the name of the column indicated by the specified index.
 305         *
 306         * @since 2.1
 307         * @return               The name of the column, @n
 308         *                               else an empty string if an exception occurs
 309         * @param[in]    columnIndex                                     The index of the destination column
 310         * @exception    E_SUCCESS                                       The method is successful.
 311         * @exception    E_INVALID_STATE                         Either of the following conditions has occurred:
 312         *                                                                                       - This instance has not been properly constructed.
 313         *                                                                                       - The method has tried to fetch the column data of a result set that is not activated
 314         *                                                                                         (the query did not yield any result).
 315         * @exception    E_INVALID_ARG                           The specified @c columnIndex is out of range.
 316         * @exception    E_INVALID_ENCODING_RANGE        String conversion failed due to invalid encoding range. @n
 317         * @remarks              The method should be called after MoveNext() or MoveFirst() or MoveLast(). @n
 318         *                               The specific error code can be accessed using the GetLastResult() method.
 319         */
 320         virtual Tizen::Base::String GetColumnName(int columnIndex) const;
 321
 322         /**
 323         * Gets the size of data in bytes.
 324         *
 325         * @since 2.1
 326         * @return               The size of the data in bytes, @n
 327         *                               else @c -1 if an exception occurs
 328         * @param[in]    columnIndex                     The index of the destination column
 329         * @exception    E_SUCCESS                       The method is successful.
 330         * @exception    E_INVALID_STATE         Either of the following conditions has occurred:
 331         *                                                                       - This instance has not been properly constructed.
 332         *                                                                       - The method has tried to fetch the column data of a result set that is not activated
 333         *                                                                         (the query did not yield any result).
 334         * @exception    E_INVALID_ARG           The specified @c columnIndex is out of range.
 335         * @remarks              The method should be called after MoveNext() or MoveFirst() or MoveLast(). @n
 336         *                               If the destination column is of type %String, this method returns the @c byte length excluding the @c null terminator character. @n
 337         *                               The specific error code can be accessed using the GetLastResult() method.
 338         */
 339         virtual int GetColumnSize(int columnIndex) const;
 340
 341 private:
 342         /**
 343         * This is the default constructor for this class.
 344         *
 345         * @since 2.1
 346         */
 347         _DataControlResultSetEnumerator(void);
 348
 349         /**
 350         * Initializes this instance of _DataControlResultSetEnumerator with the specified parameters.
 351         *
 352         * @since 2.1
 353         * @return               An error code
 354         * @param[in]    filePath                        The path to the file storing the result set.
 355         * @exception    E_SUCCESS                       The method was successful.
 356         */
 357         result SetPath(const Tizen::Base::String filePath);
 358
 359         void* __pFile;
 360
 361         int __rowCount;
 362
 363         int __columnCount;
 364
 365         int __columnTypeOffset;
 366
 367         int __columnNameOffset;
 368
 369         int __contentOffset;
 370
 371         int __currentOffset;
 372
 373         int __currentRowCount;
 374
 375         Tizen::Base::Collection::LinkedList __rowOffsetList;
 376
 377         friend class Tizen::App::_SqlDataControlImpl;
 378
 379 }; // _DataControlResultSetEnumerator
 380
 381 } } // Tizen::Io
 382
 383 #endif // _FIO_INTERNAL_DATACONTROL_RESULTSET_ENUMERATOR_H_
 384