inc/FIoDataSetEnumerator.h

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