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: @n
  80         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
  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: @n
 104         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 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: @n
 124         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 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: @n
 144         *                                                                               - An unexpected device failure has occurred as the media ejected suddenly. @n
 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 calling %DataSetEnumerator instance back 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              After this method is called, if MoveNext() is called the cursor goes to the first position.
 164         */
 165         virtual result Reset(void);
 166
 167         /**
 168         * Gets an @c int value from the column whose index is specified.
 169         *
 170         * @since                2.1
 171         *
 172         * @return               An error code
 173         * @param[in]            columnIndex                     The index of the column whose value is required
 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 operation has attempted to access columns of different types.
 179         */
 180         virtual result GetIntAt(int columnIndex, int& value) const;
 181
 182         /**
 183         * Gets a @c long @c long value from the column whose index is specified.
 184         *
 185         * @since                2.1
 186         *
 187         * @return               An error code
 188         * @param[in]            columnIndex                     The index of the column whose value is required
 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 operation has attempted to access columns of different types.
 194         */
 195         virtual result GetInt64At(int columnIndex, long long& value) const;
 196
 197         /**
 198         * Gets a @c double value from the column whose index is specified.
 199         *
 200         * @since                2.1
 201         *
 202         * @return               An error code
 203         * @param[in]            columnIndex                     The index of the column whose value is required
 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 operation has attempted to access columns of different types.
 209         */
 210         virtual result GetDoubleAt(int columnIndex, double& value) const;
 211
 212         /**
 213         * Gets a Tizen::Base::String value from the column whose index is specified.
 214         *
 215         * @since                2.1
 216         *
 217         * @return               An error code
 218         * @param[in]            columnIndex                     The index of the column whose value is required
 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 operation has attempted to access columns of different types.
 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 a Tizen::Base::ByteBuffer value from the column whose index is specified.
 230         *
 231         * @since                2.1
 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 Tizen::Base::ByteBuffer value obtained from the specified column @n
 236         *                                                                       The %Tizen::Base::ByteBuffer will be filled from the current position and data copy
 237         *                                                                               will be continued until %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 operation has attempted to access columns of different types.
 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 a blob data from the column whose index is specified.
 250         *
 251         * @since                2.1
 252         *
 253         * @return               An error code
 254         * @param[in]            columnIndex                     The index of the column whose value is required
 255         * @param[in,out]        buffer                          The user-provided buffer used 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 operation has attempted to access columns of different types.
 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 a Tizen::Base::DateTime value from the column whose index is specified.
 267         *
 268         * @since                2.1
 269         *
 270         * @return               An error code
 271         * @param[in]            columnIndex                     The index of the column whose value is required
 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 operation has attempted to access columns of different types.
 277         * @exception            E_INVALID_FORMAT        The date is not correctly formatted, or the method is trying to access column of type String. @n
 278         *                                                                       The date format should be 'mm/dd/yyyy hh:mm:ss'.
 279         * @exception            E_OUT_OF_RANGE          Either the year, month, day, hour, minute, or second value is out of range,
 280         *                                                                               or the method is trying to access a column of type String.
 281         */
 282         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;
 283
 284         /**
 285         * Gets the number of columns for this enumerator.
 286         *
 287         * @since                2.1
 288         *
 289         * @return               The number of columns in the calling enumerator, @n
 290         *                               else @c -1 if an exception occurs
 291         * @exception            E_SUCCESS                       The method is successful.
 292         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.
 293         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 294         *                               The specific error code can be accessed using the GetLastResult() method.
 295         */
 296         virtual int GetColumnCount(void) const;
 297
 298         /**
 299         * Gets the type of the column indicated by a specified index.
 300         *
 301         * @since                2.1
 302         *
 303         * @return               The type of column, @n
 304         *                               else @c DB_COLUMNTYPE_UNDEFINED if an exception occurs
 305         * @param[in]            columnIndex                     The index of the destination column
 306         * @exception            E_SUCCESS                       The method is successful.
 307         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.
 308         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 309         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 310         *                               Currently, @c DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n
 311         *                               The specific error code can be accessed using the GetLastResult() method.
 312         */
 313         virtual DbColumnType GetColumnType(int columnIndex) const;
 314
 315         /**
 316         * Gets the name of the column indicated by a specified index.
 317         *
 318         * @since                2.1
 319         *
 320         * @return               The name of the column, @n
 321         *                               else an empty string if an exception occurs
 322         * @param[in]            columnIndex                     The index of the destination column
 323         * @exception            E_SUCCESS                       The method is successful.
 324         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.
 325         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 326         * @exception            E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range.
 327         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 328         *                               The specific error code can be accessed using the GetLastResult() method.
 329         */
 330         virtual Tizen::Base::String GetColumnName(int columnIndex) const;
 331
 332         /**
 333         * Gets the size of data in bytes.
 334         *
 335         * @since                2.1
 336         *
 337         * @return               The size of the data in bytes, @n
 338         *                               else @c -1 if an exception occurs
 339         * @param[in]            columnIndex                     The index of the destination column
 340         * @exception            E_SUCCESS                       The method is successful.
 341         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.
 342         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.
 343         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n
 344         *                               If the destination column is of type String, this method returns the @c byte length excluding
 345         *                                       the @c null terminator character. @n
 346         *                               The specific error code can be accessed using the GetLastResult() method.
 347         */
 348         virtual int GetColumnSize(int columnIndex) const;
 349
 350 private:
 351         //
 352         // This default constructor is intentionally declared as private so that only the platform can create an instance.
 353         //
 354         // @since       2.1
 355         //
 356         DataSetEnumerator(void);
 357
 358         //
 359         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 360         //
 361         // @since       2.1
 362         //
 363         DataSetEnumerator(const DataSetEnumerator& rhs);
 364
 365         //
 366         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 367         // @since       2.1
 368         //
 369         DataSetEnumerator& operator =(const DataSetEnumerator& rhs);
 370
 371         class _DataSetEnumeratorImpl* __pDataSetEnumeratorImpl;
 372         friend class _DataSetEnumeratorImpl;
 373
 374 }; // DataSetEnumerator
 375
 376 }} // Tizen::Io
 377
 378 #endif // _FIO_DATA_SET_ENUMERATOR_H_