inc/FIoDataSetEnumerator.h

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