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