inc/FCntContentSearch.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file                FCntContentSearch.h
  19  * @brief               This is the header file for the %ContentSearch class.
  20  *
  21  * This header file contains the declarations of the %ContentSearch class.
  22  */
  23
  24 #ifndef _FCNT_CONTENT_SEARCH_H_
  25 #define _FCNT_CONTENT_SEARCH_H_
  26
  27 #include <FBaseString.h>
  28 #include <FCntTypes.h>
  29
  30 namespace Tizen { namespace Base { namespace Collection
  31 {
  32 class IList;
  33 }}}
  34
  35 namespace Tizen { namespace Content
  36 {
  37
  38 class _ContentSearchImpl;
  39
  40 /**
  41  * @class       ContentSearch
  42  * @brief       This class provides methods for the content search.
  43  *
  44  * @since       2.0
  45  *
  46  * The %ContentSearch class provides methods to search content based on conditions and to retrieve the results for a specific
  47  * column. It enables searching for content stored on the Tizen device. The local content is stored in the form of database columns.
  48  *
  49  * 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  *
  51  * The following example demonstrates how to use the %ContentSearch class.
  52  *
  53  * @code
  54  * #include <FContent.h>
  55  *
  56  * using namespace Tizen::Base;
  57  * using namespace Tizen::Base::Collection;
  58  * using namespace Tizen::Content;
  59  *
  60  * void
  61  * MyClass::Test(void)
  62  * {
  63  *      // Call Construct() of ContentSearch
  64  *      ContentSearch search;
  65  *      result r = search.Construct(CONTENT_TYPE_AUDIO);
  66  *      if (IsFailed(r))
  67  *      {
  68  *              // Do something for an error
  69  *      }
  70  *
  71  *      // Call SearchN() of ContentSearch as the first page
  72  *      int pageNo = 1;
  73  *      int countPerPage = 5;
  74  *      int totalPage = 0;
  75  *      int totalCount = 0;
  76  *      IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
  77  *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
  78  *      if (IsFailed(GetLastResult()))
  79  *      {
  80  *              // Do something for an error
  81  *      }
  82  *
  83  *      // Delete resource
  84  *      pContentInfoList->RemoveAll(true);
  85  *      delete pContentInfoList;
  86  * }
  87  *
  88  * @endcode
  89  *
  90  */
  91 class _OSP_EXPORT_ ContentSearch
  92         : virtual public Tizen::Base::Object
  93 {
  94
  95 public:
  96         /**
  97          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
  98          *
  99          * @since               2.0
 100          *
 101          * @remarks             After creating an instance of this class, one of the Construct() methods must be called explicitly to initialize this instance.
 102          * @see         Construct()
 103          */
 104         ContentSearch(void);
 105
 106         /**
 107          * This destructor overrides Tizen::Base::Object::~Object().
 108          *
 109          * @since               2.0
 110          */
 111         virtual ~ContentSearch(void);
 112
 113         /**
 114          * Initializes this instance of %ContentSearch with the specified parameter.
 115          *
 116          * @since               2.0
 117          *
 118          * @return              An error code
 119          * @param[in]   type                    The content type
 120          * @exception   E_SUCCESS               The method is successful.
 121          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 122          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 123          * @exception   E_SYSTEM                A system error has occurred.
 124          *
 125          * @remarks     To search a specific type, use the content type as CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, or CONTENT_TYPE_VIDEO.
 126          *
 127          * The following example demonstrates how to use the %Construct() method.
 128          *
 129          * @code
 130          *
 131          *      // Call Construct() of ContentSearch
 132          *      ContentSearch search;
 133          *      result r = search.Construct(CONTENT_TYPE_IMAGE);
 134          *      if (IsFailed(r))
 135          *      {
 136          *              // Do something for an error
 137          *      }
 138          *
 139          * @endcode
 140          */
 141         result Construct(ContentType type);
 142
 143         /**
 144          * Searches the content and returns the search result list according to the query.
 145          *
 146          * @since               2.0
 147          * @privlevel           public
 148          * @privilege   http://tizen.org/privilege/content.read
 149          *
 150          * @return              A pointer to a list containing the ContentSearchResult instances @n
 151          *                              An empty list is returned if there is no result and there is no error, @n
 152          *                              else @c null if an exception occurs.
 153          * @param[in]   pageNo                  The page number @n
 154          *                                                              It must be equal to or greater than @c 1.
 155          * @param[in]   countPerPage    The count of the search results per page  @n
 156          *                                                              It must be equal to or greater than @c 1.
 157          * @param[out]  totalPageCount  The total page count of the search result
 158          * @param[out]  totalCount              The total count of the search result
 159          * @param[in]   whereExpr               The search condition like an sql "where" expression style @n
 160          *                                                              If it uses the default value, L"", it searches for all the content of the content type set in the constructor. @n
 161          *                                                              In case of the "DateTime" condition, the range starts from '01/01/1970 00:00:00'. @n
 162          *                                                              Every type of value has to be covered with single quotation marks, even if it is a decimal type.
 163          * @param[in]   sortColumn              The sort <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> @n
 164          *                                                              The default value is @c L"".
 165          * @param[in]   sortOrder               The sort order
 166          * @exception   E_SUCCESS               The method is successful.
 167          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 168          * @exception   E_INVALID_ARG   Either of the following conditions has occurred: @n
 169          *                                      - The specified @c column is either invalid or empty. @n
 170          *                                      - The content is searched with @c type set as CONTENT_TYPE_UNKNOWN. @n
 171          *                                      - The length of the specified @c whereExpr parameter exceeds 512 characters.
 172          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 173          * @exception   E_SYSTEM                A system error has occurred.
 174          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 175          * @remarks     The return value must be deleted. @n
 176          *                              ContentType supports CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, and CONTENT_TYPE_VIDEO.
 177          *                              If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 178          *
 179          * The following example demonstrates how to use the %SearchN() method.
 180          *
 181          * @code
 182          *
 183          *      // Call Construct() of ContentSearch
 184          *      ContentSearch search;
 185          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 186          *      if (IsFailed(r))
 187          *      {
 188          *              // Do something for an error
 189          *      }
 190          *
 191          *      // Call SearchN() of ContentSearch as the first page
 192          *      int pageNo = 1;
 193          *      int countPerPage = 5;
 194          *      int totalPage = 0;
 195          *      int totalCount = 0;
 196          *      IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
 197          *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
 198          *      if (IsFailed(GetLastResult()))
 199          *      {
 200          *              // Do something for an error
 201          *      }
 202          *
 203          *      // Do something
 204          *
 205          *      // Delete resource
 206          *      pContentInfoList->RemoveAll(true);
 207          *      delete pContentInfoList;
 208          *
 209          * @endcode
 210          */
 211         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
 213         /**
 214          * Gets the value list of the specified column within a specified range.
 215          *
 216          * @since               2.0
 217          * @privlevel   public
 218          * @privilege   http://tizen.org/privilege/content.read
 219          *
 220          * @return              A pointer to a list containing the values of a column @n
 221          *                              The type of value can be Tizen::Base::Float, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String. @n
 222          *                              An empty list is returned if the specified column has no value and there is no error, @n
 223          *              else @c null if an exception occurs.
 224          * @param[in]   pageNo                  The page number @n
 225          *                                                              It must be equal to or greater than @c 1.
 226          * @param[in]   countPerPage    The count of the value list per page  @n
 227          *                                                              It must be equal to or greater than @c 1.
 228          * @param[out]  totalPageCount  The total page count of the value list
 229          * @param[out]  totalCount              The total count of the value list
 230          * @param[in]   column                  The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 231          * @param[in]   sortOrder               The sort order
 232          * @exception   E_SUCCESS               The method is successful.
 233          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 234          * @exception   E_INVALID_ARG   The specified @c column is either invalid or empty, or
 235          *                                                              the content is searched with @c type set as CONTENT_TYPE_UNKNOWN.
 236          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 237          * @exception   E_SYSTEM                A system error has occurred.
 238          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 239          * @remarks     The return value must be deleted. @n
 240          *                      The result of GetValueListN() returns a distinct value. @n
 241          *                      ContentType supports CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, and CONTENT_TYPE_VIDEO.
 242          *                      If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 243          *
 244          * The following example demonstrates how to use the %GetValueListN() method.
 245          *
 246          * @code
 247          *
 248          *      // Call Construct() of ContentSearch
 249          *      ContentSearch search;
 250          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 251          *      if (IsFailed(r))
 252          *      {
 253          *              // Do something for an error
 254          *      }
 255          *
 256          *      // Call GetValueListN() of ContentSearch
 257          *      int pageNo = 1;
 258          *      int countPerPage = 10;
 259          *      int totalPage = 0;
 260          *      int totalCount = 0;
 261          *      IList* pValueList = search.GetValueListN(pageNo, countPerPage, totalPage, totalCount, L"Genre", SORT_ORDER_NONE);
 262          *
 263          *      if (IsFailed(GetLastResult()))
 264          *      {
 265          *              // Do something for an error
 266          *      }
 267          *
 268          *      // Do something
 269          *
 270          *      // Delete resource
 271          *      pValueList->RemoveAll(true);
 272          *      delete pValueList;
 273          *
 274          * @endcode
 275          */
 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;
 277
 278         /**
 279          * @if OSPDEPREC
 280         * Gets the list consisting of values of a specified column in the specified order.
 281         *
 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.
 285         * @since                2.0
 286         * @privlevel    public
 287         * @privilege    http://tizen.org/privilege/content.read
 288         *
 289         * @return               A pointer to a list containing the values of a 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   The specified @c column is either invalid or empty, or the content is searched with @c type set as CONTENT_TYPE_UNKNOWN.
 298         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 299         * @exception    E_SYSTEM                A system error has occurred.
 300         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 301         * @remarks The return value must be deleted. @n
 302         *                       The result of GetValueListN() returns a distinct value. @n
 303         *                       ContentType supports CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, and CONTENT_TYPE_VIDEO.
 304         *                       If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 305         *
 306         * The following example demonstrates how to use the %GetValueListN() method.
 307         *
 308         * @code
 309         *
 310         *       // Call Construct() of ContentSearch
 311         *       ContentSearch search;
 312         *       result r = search.Construct(CONTENT_TYPE_AUDIO);
 313         *       if (IsFailed(r))
 314         *       {
 315         *               // Do something for an error
 316         *       }
 317         *
 318         *       // Call GetValueListN() of ContentSearch
 319         *       IList* pValueList = search.GetValueListN(L"Artist", SORT_ORDER_NONE);
 320         *
 321         *       if (IsFailed(GetLastResult()))
 322         *       {
 323         *               // Do something for an error
 324         *       }
 325         *
 326         *       // Do something
 327         *
 328         *       // Delete resource
 329         *       pValueList->RemoveAll(true);
 330         *       delete pValueList;
 331         *
 332         * @endcode
 333         * @endif
 334         */
 335         Tizen::Base::Collection::IList* GetValueListN(const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE);
 336 private:
 337         /**
 338          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 339          */
 340         ContentSearch(const ContentSearch& rhs);
 341
 342         /**
 343          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 344          */
 345         ContentSearch& operator =(const ContentSearch& rhs);
 346
 347         _ContentSearchImpl* __pImpl;
 348
 349         friend class _ContentSearchImpl;
 350 };  // class ContentSearch
 351
 352 }}  // Tizen::Content
 353
 354 #endif  // _FCNT_CONTENT_SEARCH_H_