inc/FCntContentSearch.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  * @file                FCntContentSearch.h
  18  * @brief               This is the header file for the %ContentSearch class.
  19  *
  20  * This header file contains the declarations of the %ContentSearch class.
  21  */
  22
  23 #ifndef _FCNT_CONTENT_SEARCH_H_
  24 #define _FCNT_CONTENT_SEARCH_H_
  25
  26 #include <FBaseString.h>
  27 #include <FCntTypes.h>
  28
  29 namespace Tizen { namespace Base { namespace Collection
  30 {
  31 class IList;
  32 }}}
  33
  34 namespace Tizen { namespace Content
  35 {
  36
  37 class _ContentSearchImpl;
  38
  39 /**
  40  * @class       ContentSearch
  41  * @brief       This class provides methods for the content search.
  42  *
  43  * @since       2.0
  44  *
  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.
  47  *
  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>.
  49  *
  50  * The following example demonstrates how to use the %ContentSearch class.
  51  *
  52  * @code
  53  * #include <FContent.h>
  54  *
  55  * using namespace Tizen::Base;
  56  * using namespace Tizen::Base::Collection;
  57  * using namespace Tizen::Content;
  58  *
  59  * void
  60  * MyClass::Test(void)
  61  * {
  62  *      // Call Construct() of ContentSearch
  63  *      ContentSearch search;
  64  *      result r = search.Construct(CONTENT_TYPE_AUDIO);
  65  *      if (IsFailed(r))
  66  *      {
  67  *              // Do something for an error
  68  *      }
  69  *
  70  *      // Call SearchN() of ContentSearch as the first page
  71  *      int pageNo = 1;
  72  *      int countPerPage = 5;
  73  *      int totalPage = 0;
  74  *      int totalCount = 0;
  75  *      IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
  76  *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
  77  *      if (IsFailed(GetLastResult()))
  78  *      {
  79  *              // Do something for an error
  80  *      }
  81  *
  82  *      // Delete resource
  83  *      pContentInfoList->RemoveAll(true);
  84  *      delete pContentInfoList;
  85  * }
  86  *
  87  * @endcode
  88  *
  89  */
  90 class _OSP_EXPORT_ ContentSearch
  91         : virtual public Tizen::Base::Object
  92 {
  93
  94 public:
  95         /**
  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.
  98          *
  99          * @since               2.0
 100          */
 101         ContentSearch(void);
 102
 103         /**
 104          * This destructor overrides Tizen::Base::Object::~Object().
 105          *
 106          * @since               2.0
 107          */
 108         virtual ~ContentSearch(void);
 109
 110         /**
 111          * Initializes this instance of %ContentSearch with the specified parameter.
 112          *
 113          * @since               2.0
 114          *
 115          * @return              An error code
 116          * @param[in]   type                    The content type
 117          * @exception   E_SUCCESS               The method is successful.
 118          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 119          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 120          * @exception   E_SYSTEM                A system error has occurred.
 121          *
 122          * @remarks     To search a specific type, use the content type as @c CONTENT_TYPE_OTHER, @c CONTENT_TYPE_IMAGE, @c CONTENT_TYPE_AUDIO, or @c CONTENT_TYPE_VIDEO.
 123          *
 124          * The following example demonstrates how to use the %Construct() method.
 125          *
 126          * @code
 127          *
 128          *      // Call Construct() of ContentSearch
 129          *      ContentSearch search;
 130          *      result r = search.Construct(CONTENT_TYPE_IMAGE);
 131          *      if (IsFailed(r))
 132          *      {
 133          *              // Do something for an error
 134          *      }
 135          *
 136          * @endcode
 137          */
 138         result Construct(ContentType type);
 139
 140         /**
 141          * Searches the content and returns the search result list according to the query.
 142          *
 143          * @since               2.0
 144          * @privlevel           public
 145          * @privilege   %http://tizen.org/privilege/content.read
 146          *
 147          * @return              A pointer to a list containing the ContentSearchResult instances @n
 148          *                              An empty list is returned if there is no result and there is no error, @n
 149          *                              else @c null if an exception occurs.
 150          * @param[in]   pageNo                  The page number @n
 151          *                                                              It must be equal to or greater than @c 1.
 152          * @param[in]   countPerPage    The count of the search results per page  @n
 153          *                                                              It must be equal to or greater than @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 covered with 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: @n
 166          *                                      - The specified @c column is either invalid or empty. @n
 167          *                                      - The content is searched with @c type set as ::CONTENT_TYPE_UNKNOWN. @n
 168          *                                      - The length of the specified @c whereExpr parameter exceeds 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.
 171          * @remarks
 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.
 176          *
 177          * The following example demonstrates how to use the %SearchN() method.
 178          *
 179          * @code
 180          *
 181          *      // Call Construct() of ContentSearch
 182          *      ContentSearch search;
 183          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 184          *      if (IsFailed(r))
 185          *      {
 186          *              // Do something for an error
 187          *      }
 188          *
 189          *      // Call SearchN() of ContentSearch as the first page
 190          *      int pageNo = 1;
 191          *      int countPerPage = 5;
 192          *      int totalPage = 0;
 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()))
 197          *      {
 198          *              // Do something for an error
 199          *      }
 200          *
 201          *      // Do something
 202          *
 203          *      // Delete resource
 204          *      pContentInfoList->RemoveAll(true);
 205          *      delete pContentInfoList;
 206          *
 207          * @endcode
 208          */
 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;
 210
 211         /**
 212          * Gets the value list of the specified column within a specified range.
 213          *
 214          * @since               2.0
 215          * @privlevel   public
 216          * @privilege   %http://tizen.org/privilege/content.read
 217          *
 218          * @return              A pointer to a list containing the values of a 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 equal to or greater than @c 1.
 224          * @param[in]   countPerPage    The count of the value list per page  @n
 225          *                                                              It must be equal to or greater than @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   The specified @c column is either invalid or empty, or
 233          *                                                              the content is searched with @c type set as ::CONTENT_TYPE_UNKNOWN.
 234          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 235          * @exception   E_SYSTEM                A system error has occurred.
 236          * @remarks
 237          *                              - The specific error code can be accessed using the GetLastResult() method.
 238          *                              - The return value must be deleted. @n
 239          *                                      The result of GetValueListN() returns a distinct value.
 240          *                              - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
 241          *                                      If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
 242          *
 243          * The following example demonstrates how to use the %GetValueListN() method.
 244          *
 245          * @code
 246          *
 247          *      // Call Construct() of ContentSearch
 248          *      ContentSearch search;
 249          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 250          *      if (IsFailed(r))
 251          *      {
 252          *              // Do something for an error
 253          *      }
 254          *
 255          *      // Call GetValueListN() of ContentSearch
 256          *      int pageNo = 1;
 257          *      int countPerPage = 10;
 258          *      int totalPage = 0;
 259          *      int totalCount = 0;
 260          *      IList* pValueList = search.GetValueListN(pageNo, countPerPage, totalPage, totalCount, L"Genre", SORT_ORDER_NONE);
 261          *
 262          *      if (IsFailed(GetLastResult()))
 263          *      {
 264          *              // Do something for an error
 265          *      }
 266          *
 267          *      // Do something
 268          *
 269          *      // Delete resource
 270          *      pValueList->RemoveAll(true);
 271          *      delete pValueList;
 272          *
 273          * @endcode
 274          */
 275         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;
 276
 277         /**
 278          * @if OSPDEPREC
 279         * Gets the list consisting of values of a specified column in the specified order.
 280         *
 281         * @brief        <i> [Deprecated] </i>
 282         * @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
 283         *                               Tizen::Base::SortOrder) method, that gets the value list of the specified column.
 284         * @since                2.0
 285         * @privlevel    public
 286         * @privilege    %http://tizen.org/privilege/content.read
 287         *
 288         * @return               A pointer to a list containing the values of a column @n
 289         *                               The type of value can be Tizen::Base::Integer, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String. @n
 290         *                               An empty list is returned if the specified column has no value and there is no error, @n
 291         *               else @c null if an exception occurs.
 292         * @param[in]    column                  The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 293         * @param[in]    sortOrder               The sort order
 294         * @exception    E_SUCCESS               The method is successful.
 295         * @exception    E_OUT_OF_MEMORY The memory is insufficient.
 296         * @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.
 297         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 298         * @exception    E_SYSTEM                A system error has occurred.
 299         * @remarks
 300         *                               - The specific error code can be accessed using the GetLastResult() method.
 301         *                               - The return value must be deleted. @n
 302         *                                       The result of GetValueListN() returns a distinct value.
 303         *                               - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
 304         *                                       If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c 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_