inc/FIoDataSetEnumerator.h

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