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