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.
17 * @file FCntContentSearch.h
18 * @brief This is the header file for the %ContentSearch class.
20 * This header file contains the declarations of the %ContentSearch class.
23 #ifndef _FCNT_CONTENT_SEARCH_H_
24 #define _FCNT_CONTENT_SEARCH_H_
26 #include <FBaseString.h>
27 #include <FCntTypes.h>
29 namespace Tizen { namespace Base { namespace Collection
34 namespace Tizen { namespace Content
37 class _ContentSearchImpl;
40 * @class ContentSearch
41 * @brief This class provides methods to search content.
45 * The %ContentSearch class provides methods to search content based on conditions and to retrieve the results for a specific
46 * column. It enables searching for content stored on the %Tizen device. The local content is stored in the form of database columns.
48 * For more information on the database columns and their corresponding content types, see <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">Content Search on the Device</a>.
50 * The following example demonstrates how to use the %ContentSearch class.
53 * #include <FContent.h>
55 * using namespace Tizen::Base;
56 * using namespace Tizen::Base::Collection;
57 * using namespace Tizen::Content;
62 * // Call Construct() of ContentSearch
63 * ContentSearch search;
64 * result r = search.Construct(CONTENT_TYPE_AUDIO);
67 * // Do something for an error
70 * // Call SearchN() of ContentSearch as the first page
72 * int countPerPage = 5;
75 * IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
76 * L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
77 * if (IsFailed(GetLastResult()))
79 * // Do something for an error
83 * pContentInfoList->RemoveAll(true);
84 * delete pContentInfoList;
90 class _OSP_EXPORT_ ContentSearch
91 : virtual public Tizen::Base::Object
96 * The object is not fully constructed after this constructor is called. @n
97 * For full construction, the Construct() method must be called right after calling this constructor.
104 * This destructor overrides Tizen::Base::Object::~Object().
108 virtual ~ContentSearch(void);
111 * Initializes this instance of %ContentSearch with the specified parameter.
115 * @return An error code
116 * @param[in] type The content type @n
117 * Only @c CONTENT_TYPE_OTHER, @c CONTENT_TYPE_IMAGE,
118 * @c CONTENT_TYPE_AUDIO, and @c CONTENT_TYPE_VIDEO is supported.
119 * @exception E_SUCCESS The method is successful.
120 * @exception E_INVALID_ARG The specified input parameter is invalid.
121 * @exception E_OUT_OF_MEMORY The memory is insufficient.
122 * @exception E_SYSTEM A system error has occurred.
124 * The following example demonstrates how to use the %Construct() method.
128 * // Calls Construct() of ContentSearch
129 * ContentSearch search;
130 * result r = search.Construct(CONTENT_TYPE_IMAGE);
133 * // Do something for an error
138 result Construct(ContentType type);
141 * Searches the content and returns the search result list according to the query.
145 * @privilege %http://tizen.org/privilege/content.read
147 * @return A pointer to the list that contains the ContentSearchResult instances @n
148 * An empty list is returned if there is no result or error, @n
149 * else @c null if an exception occurs.
150 * @param[in] pageNo The page number @n
151 * It must be greater than or equal to @c 1.
152 * @param[in] countPerPage The count of the search results per page @n
153 * It must be greater than or equal to @c 1.
154 * @param[out] totalPageCount The total page count of the search result
155 * @param[out] totalCount The total count of the search result
156 * @param[in] whereExpr The search condition like an sql "where" expression style @n
157 * If it uses the default value, L"", it searches for all the content of the content type set in the constructor @n
158 * In case of the "DateTime" condition, the range starts from '01/01/1970 00:00:00' @n
159 * Every type of value has to be enclosed in single quotation marks, even if it is a decimal type.
160 * @param[in] sortColumn The sort <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> @n
161 * The default value is @c L"".
162 * @param[in] sortOrder The sort order
163 * @exception E_SUCCESS The method is successful.
164 * @exception E_OUT_OF_MEMORY The memory is insufficient.
165 * @exception E_INVALID_ARG Either of the following conditions has occurred:
166 * - The specified @c column is either invalid or empty.
167 * - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
168 * - The length of the specified @c whereExpr exceeds @c 512 characters.
169 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
170 * @exception E_SYSTEM A system error has occurred.
172 * - The specific error code can be accessed using the GetLastResult() method.
173 * - The return value must be deleted.
174 * - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
175 * If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
177 * The following example demonstrates how to use the %SearchN() method.
181 * // Calls Construct() of ContentSearch
182 * ContentSearch search;
183 * result r = search.Construct(CONTENT_TYPE_AUDIO);
186 * // Does something for an error
189 * // Calls SearchN() of ContentSearch as the first page
191 * int countPerPage = 5;
193 * int totalCount = 0;
194 * IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
195 * L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
196 * if (IsFailed(GetLastResult()))
198 * // Do something for an error
203 * // Deletes resource
204 * pContentInfoList->RemoveAll(true);
205 * delete pContentInfoList;
209 Tizen::Base::Collection::IList* SearchN(int pageNo, int countPerPage, int& totalPageCount, int& totalCount, const Tizen::Base::String& whereExpr = L"", const Tizen::Base::String& sortColumn = L"", Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE) const;
212 * Gets the value list of the specified column within the specified range.
216 * @privilege %http://tizen.org/privilege/content.read
218 * @return A pointer to the list that contains the values of the column @n
219 * The type of value can be Tizen::Base::Float, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String @n
220 * An empty list is returned if the specified column has no value and there is no error, @n
221 * else @c null if an exception occurs.
222 * @param[in] pageNo The page number @n
223 * It must be greater than or equal to @c 1.
224 * @param[in] countPerPage The count of the value list per page @n
225 * It must be greater than or equal to @c 1.
226 * @param[out] totalPageCount The total page count of the value list
227 * @param[out] totalCount The total count of the value list
228 * @param[in] column The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
229 * @param[in] sortOrder The sort order
230 * @exception E_SUCCESS The method is successful.
231 * @exception E_OUT_OF_MEMORY The memory is insufficient.
232 * @exception E_INVALID_ARG Either of the following conditions has occurred:
233 * - The specified @c column is either invalid or empty.
234 * - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
235 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
236 * @exception E_SYSTEM A system error has occurred.
238 * - The specific error code can be accessed using the GetLastResult() method.
239 * - The return value must be deleted.
240 * - The result of GetValueListN() returns a distinct value.
241 * - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
242 * If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
244 * The following example demonstrates how to use the %GetValueListN() method.
248 * // Call Construct() of ContentSearch
249 * ContentSearch search;
250 * result r = search.Construct(CONTENT_TYPE_AUDIO);
253 * // Do something for an error
256 * // Call GetValueListN() of ContentSearch
258 * int countPerPage = 10;
260 * int totalCount = 0;
261 * IList* pValueList = search.GetValueListN(pageNo, countPerPage, totalPage, totalCount, L"Genre", SORT_ORDER_NONE);
263 * if (IsFailed(GetLastResult()))
265 * // Do something for an error
271 * pValueList->RemoveAll(true);
276 Tizen::Base::Collection::IList* GetValueListN(int pageNo, int countPerPage, int& totalPageCount, int& totalCount, const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE) const;
280 * Gets the list consisting of the values of the specified column in the specified order.
282 * @brief <i> [Deprecated] </i>
283 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use the GetValueListN(int, int, int&, int&, const Tizen::Base::String&, @n
284 * Tizen::Base::SortOrder) method, that gets the value list of the specified column.
287 * @privilege %http://tizen.org/privilege/content.read
289 * @return A pointer to the list that contains the values of the column @n
290 * The type of value can be Tizen::Base::Integer, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String @n
291 * An empty list is returned if the specified column has no value and there is no error, @n
292 * else @c null if an exception occurs.
293 * @param[in] column The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
294 * @param[in] sortOrder The sort order
295 * @exception E_SUCCESS The method is successful.
296 * @exception E_OUT_OF_MEMORY The memory is insufficient.
297 * @exception E_INVALID_ARG Either of the following conditions has occurred:
298 * - The specified @c column is either invalid or empty.
299 * - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
300 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
301 * @exception E_SYSTEM A system error has occurred.
303 * - The specific error code can be accessed using the GetLastResult() method.
304 * - The return value must be deleted. @n
305 * - The result of GetValueListN() returns a distinct value.
306 * - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
307 * If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
309 * The following example demonstrates how to use the %GetValueListN() method.
313 * // Call Construct() of ContentSearch
314 * ContentSearch search;
315 * result r = search.Construct(CONTENT_TYPE_AUDIO);
318 * // Do something for an error
321 * // Call GetValueListN() of ContentSearch
322 * IList* pValueList = search.GetValueListN(L"Artist", SORT_ORDER_NONE);
324 * if (IsFailed(GetLastResult()))
326 * // Do something for an error
332 * pValueList->RemoveAll(true);
338 Tizen::Base::Collection::IList* GetValueListN(const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE);
341 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
343 ContentSearch(const ContentSearch& rhs);
346 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
348 ContentSearch& operator =(const ContentSearch& rhs);
350 _ContentSearchImpl* __pImpl;
352 friend class _ContentSearchImpl;
353 }; // class ContentSearch
357 #endif // _FCNT_CONTENT_SEARCH_H_