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 this method is called 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 Tizen::Base::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 Tizen::Base::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 Tizen::Base::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 Tizen::Base::ByteBuffer value obtained from the specified column @n\r
 237         *                                                                       The %Tizen::Base::ByteBuffer will be filled from the current position and data copy\r
 238         *                                                                               will be continued until %Tizen::Base::ByteBuffer limitation is reached or no more\r
 239         *                                                                               blob data remains.\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         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.\r
 243         * @exception            E_TYPE_MISMATCH The operation has attempted to access columns of different types.\r
 244         * @exception            E_OVERFLOW                      The specified Tizen::Base::ByteBuffer @c value is insufficient to save the data.\r
 245         * @see                  Tizen::Base::ByteBuffer\r
 246         */\r
 247         virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const;\r
 248 \r
 249         /**\r
 250         * Gets a blob data from the column whose index is specified.\r
 251         *\r
 252         * @since                2.1\r
 253         *\r
 254         * @return               An error code\r
 255         * @param[in]            columnIndex                     The index of the column whose value is required\r
 256         * @param[in,out]        buffer                          The user-provided buffer used to receive the blob data\r
 257         * @param[in]            size                                    The maximum buffer length in bytes\r
 258         * @exception            E_SUCCESS                       The method is successful.\r
 259         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 260         * @exception            E_INVALID_ARG           Either the specified @c columnIndex is out of range or the specified @c size is invalid.\r
 261         * @exception            E_TYPE_MISMATCH The operation has attempted to access columns of different types.\r
 262         * @exception            E_OVERFLOW                      The specified @c buffer is insufficient to save the data.\r
 263         */\r
 264         virtual result GetBlobAt(int columnIndex, void* buffer, int size) const;\r
 265 \r
 266         /**\r
 267         * Gets a Tizen::Base::DateTime value from the column whose index is specified.\r
 268         *\r
 269         * @since                2.1\r
 270         *\r
 271         * @return               An error code\r
 272         * @param[in]            columnIndex                     The index of the column whose value is required\r
 273         * @param[in,out]        value                           The Tizen::Base::DateTime value obtained from the specified column\r
 274         * @exception            E_SUCCESS                       The method is successful.\r
 275         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 276         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.\r
 277         * @exception            E_TYPE_MISMATCH The operation has attempted to access columns of different types.\r
 278         * @exception            E_INVALID_FORMAT        The date is not correctly formatted, or the method is trying to access column of type String. @n\r
 279         *                                                                       The date format should be 'mm/dd/yyyy hh:mm:ss'.\r
 280         * @exception            E_OUT_OF_RANGE          Either the year, month, day, hour, minute, or second value is out of range,\r
 281         *                                                                               or the method is trying to access a column of type String.\r
 282         */\r
 283         virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;\r
 284 \r
 285         /**\r
 286         * Gets the number of columns for this enumerator.\r
 287         *\r
 288         * @since                2.1\r
 289         *\r
 290         * @return               The number of columns in the calling enumerator, @n\r
 291         *                               else @c -1 if an exception occurs\r
 292         * @exception            E_SUCCESS                       The method is successful.\r
 293         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 294         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n\r
 295         *                               The specific error code can be accessed using the GetLastResult() method.\r
 296         */\r
 297         virtual int GetColumnCount(void) const;\r
 298 \r
 299         /**\r
 300         * Gets the type of the column indicated by a specified index.\r
 301         *\r
 302         * @since                2.1\r
 303         *\r
 304         * @return               The type of column, @n\r
 305         *                               else @c DB_COLUMNTYPE_UNDEFINED if an exception occurs\r
 306         * @param[in]            columnIndex                     The index of the destination column\r
 307         * @exception            E_SUCCESS                       The method is successful.\r
 308         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 309         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.\r
 310         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n\r
 311         *                               Currently, @c DB_COLUMNTYPE_INT is returned for a 64-bit integer. @n\r
 312         *                               The specific error code can be accessed using the GetLastResult() method.\r
 313         */\r
 314         virtual DbColumnType GetColumnType(int columnIndex) const;\r
 315 \r
 316         /**\r
 317         * Gets the name of the column indicated by a specified index.\r
 318         *\r
 319         * @since                2.1\r
 320         *\r
 321         * @return               The name of the column, @n\r
 322         *                               else an empty string if an exception occurs\r
 323         * @param[in]            columnIndex                     The index of the destination column\r
 324         * @exception            E_SUCCESS                       The method is successful.\r
 325         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 326         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.\r
 327         * @exception            E_INVALID_ENCODING_RANGE        The string conversion has failed due to invalid encoding range.\r
 328         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n\r
 329         *                               The specific error code can be accessed using the GetLastResult() method.\r
 330         */\r
 331         virtual Tizen::Base::String GetColumnName(int columnIndex) const;\r
 332 \r
 333         /**\r
 334         * Gets the size of data in bytes.\r
 335         *\r
 336         * @since                2.1\r
 337         *\r
 338         * @return               The size of the data in bytes, @n\r
 339         *                               else @c -1 if an exception occurs\r
 340         * @param[in]            columnIndex                     The index of the destination column\r
 341         * @exception            E_SUCCESS                       The method is successful.\r
 342         * @exception            E_INVALID_STATE         The DataSet instance associated with this instance is deleted.\r
 343         * @exception            E_INVALID_ARG           The specified @c columnIndex is out of range.\r
 344         * @remarks              This method must be called after MoveNext(), MoveFirst(), or MoveLast(). @n\r
 345         *                               If the destination column is of type String, this method returns the @c byte length excluding\r
 346         *                                       the @c null terminator character. @n\r
 347         *                               The specific error code can be accessed using the GetLastResult() method.\r
 348         */\r
 349         virtual int GetColumnSize(int columnIndex) const;\r
 350 \r
 351 private:\r
 352         //\r
 353         // This default constructor is intentionally declared as private so that only the platform can create an instance.\r
 354         //\r
 355         // @since       2.1\r
 356         //\r
 357         DataSetEnumerator(void);\r
 358 \r
 359         //\r
 360         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.\r
 361         //\r
 362         // @since       2.1\r
 363         //\r
 364         DataSetEnumerator(const DataSetEnumerator& rhs);\r
 365 \r
 366         //\r
 367         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.\r
 368         // @since       2.1\r
 369         //\r
 370         DataSetEnumerator& operator =(const DataSetEnumerator& rhs);\r
 371 \r
 372         class _DataSetEnumeratorImpl* __pDataSetEnumeratorImpl;\r
 373         friend class _DataSetEnumeratorImpl;\r
 374 \r
 375 }; // DataSetEnumerator\r
 376 \r
 377 }} // Tizen::Io\r
 378 \r
 379 #endif // _FIO_DATA_SET_ENUMERATOR_H_\r