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
 175          *                              - The specific error code can be accessed using the GetLastResult() method.
 176          *                              - The return value must be deleted.
 177          *                              - ContentType supports CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, and CONTENT_TYPE_VIDEO.
 178          *                                      If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 179          *
 180          * The following example demonstrates how to use the %SearchN() method.
 181          *
 182          * @code
 183          *
 184          *      // Call Construct() of ContentSearch
 185          *      ContentSearch search;
 186          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 187          *      if (IsFailed(r))
 188          *      {
 189          *              // Do something for an error
 190          *      }
 191          *
 192          *      // Call SearchN() of ContentSearch as the first page
 193          *      int pageNo = 1;
 194          *      int countPerPage = 5;
 195          *      int totalPage = 0;
 196          *      int totalCount = 0;
 197          *      IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
 198          *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
 199          *      if (IsFailed(GetLastResult()))
 200          *      {
 201          *              // Do something for an error
 202          *      }
 203          *
 204          *      // Do something
 205          *
 206          *      // Delete resource
 207          *      pContentInfoList->RemoveAll(true);
 208          *      delete pContentInfoList;
 209          *
 210          * @endcode
 211          */
 212         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;
 213
 214         /**
 215          * Gets the value list of the specified column within a specified range.
 216          *
 217          * @since               2.0
 218          * @privlevel   public
 219          * @privilege   %http://tizen.org/privilege/content.read
 220          *
 221          * @return              A pointer to a list containing the values of a column @n
 222          *                              The type of value can be Tizen::Base::Float, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String. @n
 223          *                              An empty list is returned if the specified column has no value and there is no error, @n
 224          *              else @c null if an exception occurs.
 225          * @param[in]   pageNo                  The page number @n
 226          *                                                              It must be equal to or greater than @c 1.
 227          * @param[in]   countPerPage    The count of the value list per page  @n
 228          *                                                              It must be equal to or greater than @c 1.
 229          * @param[out]  totalPageCount  The total page count of the value list
 230          * @param[out]  totalCount              The total count of the value list
 231          * @param[in]   column                  The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 232          * @param[in]   sortOrder               The sort order
 233          * @exception   E_SUCCESS               The method is successful.
 234          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 235          * @exception   E_INVALID_ARG   The specified @c column is either invalid or empty, or
 236          *                                                              the content is searched with @c type set as CONTENT_TYPE_UNKNOWN.
 237          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 238          * @exception   E_SYSTEM                A system error has occurred.
 239          * @remarks
 240          *                              - The specific error code can be accessed using the GetLastResult() method.
 241          *                              - The return value must be deleted. @n
 242          *                                      The result of GetValueListN() returns a distinct value.
 243          *                              - ContentType supports CONTENT_TYPE_OTHER, CONTENT_TYPE_IMAGE, CONTENT_TYPE_AUDIO, and CONTENT_TYPE_VIDEO.
 244          *                                      If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 245          *
 246          * The following example demonstrates how to use the %GetValueListN() method.
 247          *
 248          * @code
 249          *
 250          *      // Call Construct() of ContentSearch
 251          *      ContentSearch search;
 252          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 253          *      if (IsFailed(r))
 254          *      {
 255          *              // Do something for an error
 256          *      }
 257          *
 258          *      // Call GetValueListN() of ContentSearch
 259          *      int pageNo = 1;
 260          *      int countPerPage = 10;
 261          *      int totalPage = 0;
 262          *      int totalCount = 0;
 263          *      IList* pValueList = search.GetValueListN(pageNo, countPerPage, totalPage, totalCount, L"Genre", SORT_ORDER_NONE);
 264          *
 265          *      if (IsFailed(GetLastResult()))
 266          *      {
 267          *              // Do something for an error
 268          *      }
 269          *
 270          *      // Do something
 271          *
 272          *      // Delete resource
 273          *      pValueList->RemoveAll(true);
 274          *      delete pValueList;
 275          *
 276          * @endcode
 277          */
 278         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;
 279
 280         /**
 281          * @if OSPDEPREC
 282         * Gets the list consisting of values of a specified column in the specified order.
 283         *
 284         * @brief        <i> [Deprecated] </i>
 285         * @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
 286         *                               Tizen::Base::SortOrder) method, that gets the value list of the specified column.
 287         * @since                2.0
 288         * @privlevel    public
 289         * @privilege    %http://tizen.org/privilege/content.read
 290         *
 291         * @return               A pointer to a list containing the values of a column @n
 292         *                               The type of value can be Tizen::Base::Integer, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String. @n
 293         *                               An empty list is returned if the specified column has no value and there is no error, @n
 294         *               else @c null if an exception occurs.
 295         * @param[in]    column                  The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 296         * @param[in]    sortOrder               The sort order
 297         * @exception    E_SUCCESS               The method is successful.
 298         * @exception    E_OUT_OF_MEMORY The memory is insufficient.
 299         * @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.
 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.
 302         * @remarks
 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.
 307         *                                       If %ContentType in Construct() uses CONTENT_TYPE_UNKNOWN or an invalid value, E_INVALID_ARG occurs.
 308         *
 309         * The following example demonstrates how to use the %GetValueListN() method.
 310         *
 311         * @code
 312         *
 313         *       // Call Construct() of ContentSearch
 314         *       ContentSearch search;
 315         *       result r = search.Construct(CONTENT_TYPE_AUDIO);
 316         *       if (IsFailed(r))
 317         *       {
 318         *               // Do something for an error
 319         *       }
 320         *
 321         *       // Call GetValueListN() of ContentSearch
 322         *       IList* pValueList = search.GetValueListN(L"Artist", SORT_ORDER_NONE);
 323         *
 324         *       if (IsFailed(GetLastResult()))
 325         *       {
 326         *               // Do something for an error
 327         *       }
 328         *
 329         *       // Do something
 330         *
 331         *       // Delete resource
 332         *       pValueList->RemoveAll(true);
 333         *       delete pValueList;
 334         *
 335         * @endcode
 336         * @endif
 337         */
 338         Tizen::Base::Collection::IList* GetValueListN(const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE);
 339 private:
 340         /**
 341          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 342          */
 343         ContentSearch(const ContentSearch& rhs);
 344
 345         /**
 346          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 347          */
 348         ContentSearch& operator =(const ContentSearch& rhs);
 349
 350         _ContentSearchImpl* __pImpl;
 351
 352         friend class _ContentSearchImpl;
 353 };  // class ContentSearch
 354
 355 }}  // Tizen::Content
 356
 357 #endif  // _FCNT_CONTENT_SEARCH_H_