2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FIoDbEnumerator.h
19 * @brief This is the header file for the %DbEnumerator class.
21 * This header file contains the declarations of the %DbEnumerator class.
24 #ifndef _FIO_DB_ENUMERATOR_H_
25 #define _FIO_DB_ENUMERATOR_H_
27 #include <FBaseObject.h>
28 #include <FBaseRtMutex.h>
29 #include <FIoDbTypes.h>
30 #include <FIoIDbEnumerator.h>
32 namespace Tizen { namespace Base
39 namespace Tizen { namespace Io
44 * @brief This class provides methods for navigating the result set from the SELECT query.
48 * @final This class is not intended for extension.
50 * The %DbEnumerator class provides methods for navigating the result set from the SELECT query.
51 * All the members of this class are guaranteed to be thread-safe.
53 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/io/database_operations.htm">Database Operations</a>.
55 * @see Tizen::Io::Database
57 class _OSP_EXPORT_ DbEnumerator
58 : public Tizen::Base::Object
59 , public Tizen::Io::IDbEnumerator
64 * This destructor overrides Tizen::Base::Object::~Object().
68 virtual ~DbEnumerator(void);
71 * Moves the enumerator to the next position.
74 * @brief <i> [Compatibility] </i>
78 * @compatibility This method has compatibility issues with OSP compatible applications. @n
79 * For more information, see @ref CompDatabaseExceptionPage "here".
82 * @return An error code
83 * @exception E_SUCCESS The method is successful.
84 * @exception E_INVALID_STATE Either of the following conditions has occurred:
85 * - This instance has not been properly constructed.
86 * - The method has tried to move the cursor position of the result set that is not activated
87 * (the query did not yield any result).
88 * - The Database or DbStatement instance associated with this instance is deleted.
89 * @exception E_OUT_OF_RANGE The enumerator has reached out of the result set returned by the SELECT query.
90 * @exception E_OBJECT_LOCKED The database instance is locked.
91 * @exception E_INVALID_FORMAT The database file is malformed.
92 * @exception E_IO Either of the following conditions has occurred:
93 * - An unexpected device failure has occurred as the media ejected suddenly.
94 * - %File corruption is detected.
95 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
96 * @see Tizen::Io::Database::ExecuteStatementN()
97 * @see Tizen::Io::Database::QueryN()
98 * @see Tizen::Io::DbEnumerator::MovePrevious()
99 * @see Tizen::Io::DbEnumerator::MoveFirst()
100 * @see Tizen::Io::DbEnumerator::MoveLast()
102 virtual result MoveNext(void);
105 * Moves the enumerator to the previous position.
109 * @return An error code
110 * @exception E_SUCCESS The method is successful.
111 * @exception E_INVALID_STATE Either of the following conditions has occurred:
112 * - This instance has not been properly constructed.
113 * - The method has tried to move the cursor position of the result set that is not activated
114 * (the query did not yield any result).
115 * - The Database or DbStatement instance associated with this instance is deleted.
116 * @exception E_OUT_OF_RANGE The enumerator has reached out of the result set returned by the SELECT query.
117 * @exception E_OBJECT_LOCKED The database instance is locked.
118 * @exception E_INVALID_FORMAT The database file is malformed.
119 * @exception E_IO Either of the following conditions has occurred:
120 * - An unexpected device failure has occurred as the media ejected suddenly.
121 * - %File corruption is detected.
122 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
123 * @see Tizen::Io::Database::ExecuteStatementN()
124 * @see Tizen::Io::Database::QueryN()
125 * @see Tizen::Io::DbEnumerator::MoveNext()
126 * @see Tizen::Io::DbEnumerator::MoveFirst()
127 * @see Tizen::Io::DbEnumerator::MoveLast()
129 virtual result MovePrevious(void);
132 * Moves the enumerator to the first position.
136 * @return An error code
137 * @exception E_SUCCESS The method is successful.
138 * @exception E_INVALID_STATE Either of the following conditions has occurred:
139 * - This instance has not been properly constructed.
140 * - The method has tried to move the cursor position of the result set that is not activated
141 * (the query did not yield any result).
142 * - The Database or DbStatement instance associated with this instance is deleted.
143 * @exception E_OBJECT_LOCKED The database instance is locked.
144 * @exception E_INVALID_FORMAT The database file is malformed.
145 * @exception E_IO Either of the following conditions has occurred:
146 * - An unexpected device failure has occurred as the media ejected suddenly.
147 * - %File corruption is detected.
148 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
149 * @see Tizen::Io::Database::ExecuteStatementN()
150 * @see Tizen::Io::Database::QueryN()
151 * @see Tizen::Io::DbEnumerator::MoveNext()
152 * @see Tizen::Io::DbEnumerator::MovePrevious()
153 * @see Tizen::Io::DbEnumerator::MoveLast()
155 virtual result MoveFirst(void);
158 * Moves the enumerator to the last position.
162 * @return An error code
163 * @exception E_SUCCESS The method is successful.
164 * @exception E_INVALID_STATE Either of the following conditions has occurred:
165 * - This instance has not been properly constructed.
166 * - The method has tried to move the cursor position of the result set that is not activated
167 * (the query did not yield any result).
168 * - The Database or DbStatement instance associated with this instance is deleted.
169 * @exception E_OBJECT_LOCKED The database instance is locked.
170 * @exception E_INVALID_FORMAT The database file is malformed.
171 * @exception E_IO Either of the following conditions has occurred:
172 * - An unexpected device failure has occurred as the media ejected suddenly.
173 * - %File corruption is detected.
174 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
175 * @see Tizen::Io::Database::ExecuteStatementN()
176 * @see Tizen::Io::Database::QueryN()
177 * @see Tizen::Io::DbEnumerator::MoveNext()
178 * @see Tizen::Io::DbEnumerator::MovePrevious()
179 * @see Tizen::Io::DbEnumerator::MoveFirst()
181 virtual result MoveLast(void);
184 * Resets the current %DbEnumerator instance to its initial state.
187 * @brief <i> [Compatibility] </i>
191 * @compatibility This method has compatibility issues with OSP compatible applications. @n
192 * For more information, see @ref CompDatabaseExceptionPage "here".
195 * @return An error code
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_INVALID_STATE Either of the following conditions has occurred:
198 * - This instance has not been properly constructed.
199 * - The method has tried to reset the enumerator of the result set that is not activated
200 * (the query did not yield any result).
201 * - The Database or DbStatement instance associated with this instance is deleted.
202 * @exception E_OBJECT_LOCKED The database instance is locked.
203 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
204 * @remarks If MoveNext() is called after this method, the cursor goes to the first position.
206 virtual result Reset(void);
209 * Gets the @c int value from the column with the specified index.
213 * @return An error code
214 * @param[in] columnIndex The index of the column to get the value
215 * @param[in,out] value The integer value obtained from the specified column
216 * @exception E_SUCCESS The method is successful.
217 * @exception E_INVALID_STATE Either of the following conditions has occurred:
218 * - This instance has not been properly constructed.
219 * - The method has tried to fetch the column data of a result set that is not activated
220 * (the query did not yield any result).
221 * - The Database or DbStatement instance associated with this instance is deleted.
222 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
223 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
225 virtual result GetIntAt(int columnIndex, int& value) const;
228 * Gets the @c long @c long value from the column with the specified index.
232 * @return An error code
233 * @param[in] columnIndex The index of the column to get the value
234 * @param[in,out] value The 64-bit integer value obtained from the specified column
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_INVALID_STATE Either of the following conditions has occurred:
237 * - This instance has not been properly constructed.
238 * - The method has tried to fetch the column data of a result set that is not activated
239 * (the query did not yield any result).
240 * - The Database or DbStatement instance associated with this instance is deleted.
241 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
242 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
244 virtual result GetInt64At(int columnIndex, long long& value) const;
247 * Gets the @c double value from the column with the specified index.
251 * @return An error code
252 * @param[in] columnIndex The index of the column to get the value
253 * @param[in,out] value The double value obtained from the column
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_INVALID_STATE Either of the following conditions has occurred:
256 * - This instance has not been properly constructed.
257 * - The method has tried to fetch the column data of a result set that is not activated
258 * (the query did not yield any result).
259 * - The Database or DbStatement instance associated with this instance is deleted.
260 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
261 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
263 virtual result GetDoubleAt(int columnIndex, double& value) const;
266 * Gets the @c String value from the column with the specified index.
270 * @return An error code
271 * @param[in] columnIndex The index of the column to get the value
272 * @param[in,out] value The @c String value obtained from the column
273 * @exception E_SUCCESS The method is successful.
274 * @exception E_INVALID_STATE Either of the following conditions has occurred:
275 * - This instance has not been properly constructed.
276 * - The method has tried to fetch the column data of a result set that is not activated
277 * (the query did not yield any result).
278 * - The Database or DbStatement instance associated with this instance is deleted.
279 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
280 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
281 * @exception E_INVALID_ENCODING_RANGE Either of the following conditions has occurred:
282 * - The string conversion has failed due to invalid encoding range.
283 * - The database file is corrupted.
285 virtual result GetStringAt(int columnIndex, Tizen::Base::String& value) const;
288 * Gets the byte array value from the column with the specified index.
292 * @return An error code
293 * @param[in] columnIndex The index of the column to get the value
294 * @param[in,out] value The buffer to receive the blob data as a stream of type ByteBuffer @n
295 * The buffer will be filled from the current position and the data copying will be continued
296 * until the buffer limitation is reached or no more blob data remains. @n
297 * The maximum size available is limited to 100 MByte.
298 * @exception E_SUCCESS The method is successful.
299 * @exception E_INVALID_STATE Either of the following conditions has occurred:
300 * - This instance has not been properly constructed.
301 * - The method has tried to fetch the column data of a result set that is not activated
302 * (the query did not yield any result).
303 * - The Database or DbStatement instance associated with this instance is deleted.
304 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
305 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
306 * @exception E_OUT_OF_RANGE The byte buffer operation has failed.
307 * @exception E_OVERFLOW The specified @c value of the byte buffer is insufficient to save the data.
309 virtual result GetBlobAt(int columnIndex, Tizen::Base::ByteBuffer& value) const;
312 * Gets the blob data from the column with the specified index.
316 * @return An error code
317 * @param[in] columnIndex The index of the column to get the value
318 * @param[in,out] buffer The buffer to receive the blob data @n
319 * The maximum size available is limited to 100 MByte.
320 * @param[out] size The maximum buffer length in bytes
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_INVALID_STATE Either of the following conditions has occurred:
323 * - This instance has not been properly constructed.
324 * - The method has tried to fetch the column data of a result set that is not activated
325 * (the query did not yield any result).
326 * - The Database or DbStatement instance associated with this instance is deleted.
327 * @exception E_INVALID_ARG The specified @c columnIndex is out of range, or the specified @c size is invalid.
328 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
329 * @exception E_OVERFLOW The specified @c buffer is insufficient to save the data.
331 virtual result GetBlobAt(int columnIndex, void* buffer, int size) const;
334 * Gets the @c DateTime value from the column with the specified index.
338 * @return An error code
339 * @param[in] columnIndex The index of the column to get the value
340 * @param[in,out] value The value obtained from the column as a %DateTime instance
341 * @exception E_SUCCESS The method is successful.
342 * @exception E_INVALID_STATE Either of the following conditions has occurred:
343 * - This instance has not been properly constructed.
344 * - The method has tried to fetch the column data of a result set that is not activated
345 * (the query did not yield any result).
346 * - The Database or DbStatement instance associated with this instance is deleted.
347 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
348 * @exception E_TYPE_MISMATCH The column type accessed by the method do not match.
349 * @exception E_INVALID_FORMAT The date is not correctly formatted. The date format should be 'mm/dd/yyyy hh:mm:ss'.
350 * @exception E_OUT_OF_RANGE Either the year, month, day, hour, minute, or second value is out of range, or the method is trying to access a column having an invalid value.
353 virtual result GetDateTimeAt(int columnIndex, Tizen::Base::DateTime& value) const;
356 * Gets the number of columns for this enumerator.
360 * @return The number of columns in the current enumerator, @n
361 * else @c -1 if an exception occurs
362 * @exception E_SUCCESS The method is successful.
363 * @exception E_INVALID_STATE Either of the following conditions has occurred:
364 * - This instance has not been properly constructed.
365 * - The method has tried to fetch the column data of a result set that is not activated
366 * (the query did not yield any result).
367 * - The Database or DbStatement instance associated with this instance is deleted.
369 * - The method must be called after MoveNext(), MoveFirst(), or MoveLast().
370 * - The specific error code can be accessed using the GetLastResult() method.
372 virtual int GetColumnCount(void) const;
375 * Gets the type of the column specified by the index.
379 * @return The column type, @n
380 * else DB_COLUMNTYPE_UNDEFINED if an exception occurs
381 * @param[in] columnIndex The column index
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_INVALID_STATE Either of the following conditions has occurred:
384 * - This instance has not been properly constructed.
385 * - The method has tried to fetch the column data of a result set that is not activated
386 * (the query did not yield any result).
387 * - The Database or DbStatement instance associated with this instance is deleted.
388 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
390 * - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
391 * - Currently, ::DB_COLUMNTYPE_INT is returned for a 64-bit integer.
392 * - The specific error code can be accessed using the GetLastResult() method.
394 virtual DbColumnType GetColumnType(int columnIndex) const;
397 * Gets the name of the column specified by the index.
401 * @return The name of the column, @n
402 * else an empty string if an exception occurs
403 * @param[in] columnIndex The column index
404 * @exception E_SUCCESS The method is successful.
405 * @exception E_INVALID_STATE Either of the following conditions has occurred:
406 * - This instance has not been properly constructed.
407 * - The method has tried to fetch the column data of a result set that is not activated
408 * (the query did not yield any result).
409 * - The Database or DbStatement instance associated with this instance is deleted.
410 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
411 * @exception E_INVALID_ENCODING_RANGE Either of the following conditions has occurred:
412 * - The string conversion has failed due to invalid encoding range.
413 * - The database file is corrupted.
415 * - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
416 * - The specific error code can be accessed using the GetLastResult() method.
418 virtual Tizen::Base::String GetColumnName(int columnIndex) const;
421 * Gets the size of data in bytes of the column specified by the index.
425 * @return The size of the data in bytes, @n
426 * else @c -1 if an exception occurs
427 * @param[in] columnIndex The column index
428 * @exception E_SUCCESS The method is successful.
429 * @exception E_INVALID_STATE Either of the following conditions has occurred:
430 * - This instance has not been properly constructed.
431 * - The method has tried to fetch the column data of a result set that is not activated
432 * (the query did not yield any result).
433 * - The Database or DbStatement instance associated with this instance is deleted.
434 * @exception E_INVALID_ARG The specified @c columnIndex is out of range.
436 * - This method must be called after MoveNext(), MoveFirst(), or MoveLast().
437 * - If the destination column is of type String, this method returns the @c byte length excluding the @c null terminator character.
438 * - The specific error code can be accessed using the GetLastResult() method.
440 virtual int GetColumnSize(int columnIndex) const;
444 * This default constructor is intentionally declared as private so that only the platform can create an instance.
451 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
455 DbEnumerator(const DbEnumerator& rhs);
458 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
461 DbEnumerator& operator =(const DbEnumerator& rhs);
463 class _DbEnumeratorImpl* __pDbEnumeratorImpl;
465 friend class _DbEnumeratorImpl;
471 #endif // _FIO_DB_ENUMERATOR_H_