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 to search content.
  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 <FBase.h>
  54  * #include <FContent.h>
  55  *
  56  * using namespace Tizen::Content;
  57  *
  58  * void
  59  * MyClass::Test(void)
  60  * {
  61  *              ContentSearch search;
  62  *              result r = search.Construct(CONTENT_TYPE_AUDIO);
  63  *
  64  *              int pageNo = 1;
  65  *              int countPerPage = 5;
  66  *              int totalPage = 0;
  67  *              int totalCount = 0;
  68  *              Tizen::Base::Collection::IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
  69  *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
  70  *              r = GetLastResult();
  71  *
  72  *              pContentInfoList->RemoveAll(true);
  73  *              delete pContentInfoList;
  74  * }
  75  *
  76  * @endcode
  77  *
  78  */
  79 class _OSP_EXPORT_ ContentSearch
  80         : virtual public Tizen::Base::Object
  81 {
  82
  83 public:
  84         /**
  85          * The object is not fully constructed after this constructor is called. @n
  86          * For full construction, the Construct() method must be called right after calling this constructor.
  87          *
  88          * @since               2.0
  89          */
  90         ContentSearch(void);
  91
  92         /**
  93          * This destructor overrides Tizen::Base::Object::~Object().
  94          *
  95          * @since               2.0
  96          */
  97         virtual ~ContentSearch(void);
  98
  99         /**
 100          * Initializes this instance of %ContentSearch with the specified parameter.
 101          *
 102          * @since               2.0
 103          *
 104          * @return              An error code
 105          * @param[in]   type                    The content type @n
 106          *                                                              Only @c CONTENT_TYPE_OTHER, @c CONTENT_TYPE_IMAGE,
 107          *                                                              @c CONTENT_TYPE_AUDIO, and @c CONTENT_TYPE_VIDEO is supported.
 108          * @exception   E_SUCCESS               The method is successful.
 109          * @exception   E_INVALID_ARG   The specified input parameter is invalid.
 110          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 111          * @exception   E_SYSTEM                A system error has occurred.
 112          *
 113          * The following example demonstrates how to use the %Construct() method.
 114          *
 115          * @code
 116          *
 117          *      // Calls Construct() of ContentSearch
 118          *      ContentSearch search;
 119          *      result r = search.Construct(CONTENT_TYPE_IMAGE);
 120          *      if (IsFailed(r))
 121          *      {
 122          *              // Do something for an error
 123          *      }
 124          *
 125          * @endcode
 126          */
 127         result Construct(ContentType type);
 128
 129         /**
 130          * Searches the content and returns the search result list according to the query.
 131          *
 132          * @since               2.0
 133          * @privlevel   public
 134          * @privilege   %http://tizen.org/privilege/content.read
 135          *
 136          * @return              A pointer to the list that contains the ContentSearchResult instances @n
 137          *                              An empty list is returned if there is no result or error, @n
 138          *                              else @c null if an exception occurs.
 139          * @param[in]   pageNo                          The page number @n
 140          *                                                                      It must be greater than or equal to @c 1.
 141          * @param[in]   countPerPage            The count of the search results per page @n
 142          *                                                                      It must be greater than or equal to @c 1.
 143          * @param[out]  totalPageCount          The total page count of the search result
 144          * @param[out]  totalCount                      The total count of the search result
 145          * @param[in]   whereExpr                       The search condition like an sql "where" expression style @n
 146          *                                                                      If it uses the default value, L"", it searches for all the content of the content type set in the constructor @n
 147          *                                                                      In case of the "DateTime" condition, the range starts from '01/01/1970 00:00:00' @n
 148          *                                                                      Every type of value has to be enclosed in single quotation marks, even if it is a decimal type.
 149          * @param[in]   sortColumn                      The sort <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> @n
 150          *                                                                      The default value is @c L"".
 151          * @param[in]   sortOrder                       The sort order
 152          * @exception   E_SUCCESS                       The method is successful.
 153          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 154          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 155          *                                                              - The specified @c column is either invalid or empty.
 156          *                                                              - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
 157          *                                                              - The length of the specified @c whereExpr exceeds @c 512 characters.
 158          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 159          * @exception   E_SYSTEM                        A system error has occurred.
 160          * @remarks
 161          *                              - The specific error code can be accessed using the GetLastResult() method.
 162          *                              - The return value must be deleted.
 163          *                              - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
 164          *                              If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
 165          *
 166          * The following example demonstrates how to use the %SearchN() method.
 167          *
 168          * @code
 169          *
 170          *      // Calls Construct() of ContentSearch
 171          *      ContentSearch search;
 172          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 173          *      if (IsFailed(r))
 174          *      {
 175          *              // Does something for an error
 176          *      }
 177          *
 178          *      // Calls SearchN() of ContentSearch as the first page
 179          *      int pageNo = 1;
 180          *      int countPerPage = 5;
 181          *      int totalPage = 0;
 182          *      int totalCount = 0;
 183          *      IList* pContentInfoList = search.SearchN(pageNo, countPerPage, totalPage, totalCount,
 184          *                              L"Artist='rain'", L"Title", SORT_ORDER_ASCENDING);
 185          *      if (IsFailed(GetLastResult()))
 186          *      {
 187          *              // Do something for an error
 188          *      }
 189          *
 190          *      // Does something
 191          *
 192          *      // Deletes resource
 193          *      pContentInfoList->RemoveAll(true);
 194          *      delete pContentInfoList;
 195          *
 196          * @endcode
 197          */
 198         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;
 199
 200         /**
 201          * Gets the value list of the specified column within the specified range.
 202          *
 203          * @since               2.0
 204          * @privlevel   public
 205          * @privilege   %http://tizen.org/privilege/content.read
 206          *
 207          * @return              A pointer to the list that contains the values of the column @n
 208          *                              The type of value can be Tizen::Base::Float, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String @n
 209          *                              An empty list is returned if the specified column has no value and there is no error, @n
 210          *              else @c null if an exception occurs.
 211          * @param[in]   pageNo                          The page number @n
 212          *                                                                      It must be greater than or equal to @c 1.
 213          * @param[in]   countPerPage            The count of the value list per page  @n
 214          *                                                                      It must be greater than or equal to @c 1.
 215          * @param[out]  totalPageCount          The total page count of the value list
 216          * @param[out]  totalCount                      The total count of the value list
 217          * @param[in]   column                          The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 218          * @param[in]   sortOrder                       The sort order
 219          * @exception   E_SUCCESS                       The method is successful.
 220          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 221          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 222          *                                                              - The specified @c column is either invalid or empty.
 223          *                                                              - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
 224          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 225          * @exception   E_SYSTEM                        A system error has occurred.
 226          * @remarks
 227          *                              - The specific error code can be accessed using the GetLastResult() method.
 228          *                              - The return value must be deleted.
 229          *                              - The result of GetValueListN() returns a distinct value.
 230          *                              - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
 231          *                              If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
 232          *
 233          * The following example demonstrates how to use the %GetValueListN() method.
 234          *
 235          * @code
 236          *
 237          *      // Call Construct() of ContentSearch
 238          *      ContentSearch search;
 239          *      result r = search.Construct(CONTENT_TYPE_AUDIO);
 240          *      if (IsFailed(r))
 241          *      {
 242          *              // Do something for an error
 243          *      }
 244          *
 245          *      // Call GetValueListN() of ContentSearch
 246          *      int pageNo = 1;
 247          *      int countPerPage = 10;
 248          *      int totalPage = 0;
 249          *      int totalCount = 0;
 250          *      IList* pValueList = search.GetValueListN(pageNo, countPerPage, totalPage, totalCount, L"Genre", SORT_ORDER_NONE);
 251          *
 252          *      if (IsFailed(GetLastResult()))
 253          *      {
 254          *              // Do something for an error
 255          *      }
 256          *
 257          *      // Do something
 258          *
 259          *      // Delete resource
 260          *      pValueList->RemoveAll(true);
 261          *      delete pValueList;
 262          *
 263          * @endcode
 264          */
 265         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;
 266
 267         /**
 268          * @if OSPDEPREC
 269         * Gets the list consisting of the values of the specified column in the specified order.
 270         *
 271         * @brief        <i> [Deprecated] </i>
 272         * @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
 273         *                               Tizen::Base::SortOrder) method, that gets the value list of the specified column.
 274         * @since                2.0
 275         * @privlevel    public
 276         * @privilege    %http://tizen.org/privilege/content.read
 277         *
 278         * @return               A pointer to the list that contains the values of the column @n
 279         *                               The type of value can be Tizen::Base::Integer, Tizen::Base::Double, Tizen::Base::LongLong, Tizen::Base::DateTime, or Tizen::Base::String @n
 280         *                               An empty list is returned if the specified column has no value and there is no error, @n
 281         *               else @c null if an exception occurs.
 282         * @param[in]    column                     The <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">column</a> name
 283         * @param[in]    sortOrder                  The sort order
 284         * @exception    E_SUCCESS                  The method is successful.
 285         * @exception    E_OUT_OF_MEMORY    The memory is insufficient.
 286         * @exception    E_INVALID_ARG      Either of the following conditions has occurred:
 287         *                                                               - The specified @c column is either invalid or empty.
 288         *                                                               - The content is searched with @c type set to ::CONTENT_TYPE_UNKNOWN.
 289         * @exception    E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 290         * @exception    E_SYSTEM                   A system error has occurred.
 291         * @remarks
 292         *                               - The specific error code can be accessed using the GetLastResult() method.
 293         *                               - The return value must be deleted. @n
 294         *                               - The result of GetValueListN() returns a distinct value.
 295         *                               - ContentType supports ::CONTENT_TYPE_OTHER, ::CONTENT_TYPE_IMAGE, ::CONTENT_TYPE_AUDIO, and ::CONTENT_TYPE_VIDEO. @n
 296         *                               If %ContentType in Construct() uses ::CONTENT_TYPE_UNKNOWN or an invalid value, @c E_INVALID_ARG occurs.
 297         *
 298         * The following example demonstrates how to use the %GetValueListN() method.
 299         *
 300         * @code
 301         *
 302         *       // Call Construct() of ContentSearch
 303         *       ContentSearch search;
 304         *       result r = search.Construct(CONTENT_TYPE_AUDIO);
 305         *       if (IsFailed(r))
 306         *       {
 307         *               // Do something for an error
 308         *       }
 309         *
 310         *       // Call GetValueListN() of ContentSearch
 311         *       IList* pValueList = search.GetValueListN(L"Artist", SORT_ORDER_NONE);
 312         *
 313         *       if (IsFailed(GetLastResult()))
 314         *       {
 315         *               // Do something for an error
 316         *       }
 317         *
 318         *       // Do something
 319         *
 320         *       // Delete resource
 321         *       pValueList->RemoveAll(true);
 322         *       delete pValueList;
 323         *
 324         * @endcode
 325         * @endif
 326         */
 327         Tizen::Base::Collection::IList* GetValueListN(const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE);
 328 private:
 329         /**
 330          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 331          */
 332         ContentSearch(const ContentSearch& rhs);
 333
 334         /**
 335          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 336          */
 337         ContentSearch& operator =(const ContentSearch& rhs);
 338
 339         _ContentSearchImpl* __pImpl;
 340
 341         friend class _ContentSearchImpl;
 342 };  // class ContentSearch
 343
 344 }}  // Tizen::Content
 345
 346 #endif  // _FCNT_CONTENT_SEARCH_H_