5c3b36570e1ee8a277444c41ae8899678b3100ba
[platform/framework/native/content.git] / inc / FCntContentDirectory.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                FCntContentDirectory.h
18  * @brief               This is the header file for the %ContentDirectory class.
19  *
20  * This header file contains the declarations of the %ContentDirectory class.
21  */
22
23 #ifndef _FCNT_CONTENT_DIRECTORY_H_
24 #define _FCNT_CONTENT_DIRECTORY_H_
25
26 #include <FBaseString.h>
27 #include <FBaseColIListT.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         static const int MAX_CONTENTTYPE_LIST_COUNT = 5;
38         static const int MIN_CONTENTTYPE_LIST_COUNT = 0;
39         static const int CONTENTTYPE_LIST_COUNT_ONE = 1;
40
41 class _ContentDirectoryImpl;
42 /**
43  * @class       ContentDirectory
44  * @brief       This class provides methods for the content directory.
45  * @since       2.0
46  *
47  * @final       This class is not intended for extension.
48  *
49  * The %ContentDirectory class provides methods to access a list of content directories 
50  * and information of the content (specified content type) in the content directories.
51  *
52  * For more information on the database columns and their corresponding content types, 
53  * see <a href="../org.tizen.native.appprogramming/html/guide/content/content_search_device.htm">Content Search on the Device</a>.
54  *
55  * The following example demonstrates how to use the %ContentDirectory class.
56  *
57  * @code
58  * #include <FContent.h>
59  *
60  * using namespace Tizen::Base;
61  * using namespace Tizen::Base::Collection;
62  * using namespace Tizen::Content;
63  *
64  * void
65  * MyClass::Test(void)
66  * {
67  *      // Call Construct() of ContentDirectory
68  *      ContentDirectory directory;
69  *      const Tizen::Base::String contentDirectoryPath = L"";
70  *      result r = directory.Construct(CONTENT_TYPE_AUDIO);
71  *      if (IsFailed(r))
72  *      {
73  *              // Do something for an error
74  *      }
75  *
76  *      // Call GetContentDirectoryItemListN() of ContentDirectory as the first page
77  *      int pageNo = 1;
78  *      int countPerPage = 5;
79  *      int totalPage = 0;
80  *      int totalCount = 0;
81  *      IList* pContentInfoList = directory.GetContentDirectoryItemListN(contentDirectoryPath, pageNo, countPerPage, L"Title", SORT_ORDER_ASCENDING);
82  *                               
83  *      if (IsFailed(GetLastResult()))
84  *      {
85  *              // Do something for an error
86  *      }
87  *
88  *      // Delete resource
89  *      pContentInfoList->RemoveAll(true);
90  *      delete pContentInfoList;
91  * }
92  *
93  * @endcode
94  *
95  */
96
97 class _OSP_EXPORT_ ContentDirectory
98         : public Tizen::Base::Object
99 {
100
101 public:
102
103         /**
104          * The object is not fully constructed after this constructor is called. @n
105          * For full construction, the Construct() method must be called right after calling this constructor.
106          *
107          * @since 2.0
108          */
109         ContentDirectory(void);
110
111         /**
112          * This destructor overrides Tizen::Base::Object::~Object().
113          *
114          * @since 2.0
115          */
116         virtual ~ContentDirectory(void);
117
118         /**
119          * Initializes this instance of %ContentDirectory with the specified parameter.
120          *
121          * @since 2.0
122          *
123          * @return    An error code
124          * @param     contentType               The content type @n
125          *                                                      This method is used to access only one type of content. The allowed types are 
126          *                                                      @c CONTENT_TYPE_OTHER, @c CONTENT_TYPE_IMAGE, @c CONTENT_TYPE_AUDIO, and @c CONTENT_TYPE_VIDEO. @n
127          *                                                      If you want to access more than one type of content, use Construct(const Tizen::Base::Collection::IListT<ContentType>&) 
128          *                                                      instead of this method.
129          * @exception E_SUCCESS                 The method is successful.
130          * @exception E_INVALID_ARG             The specified input parameter is invalid.
131          * @exception E_OUT_OF_MEMORY           The memory is insufficient.
132          * @exception E_SYSTEM                  The method cannot connect to the database.
133          */
134         result Construct(ContentType contentType);
135
136         /**
137          * Initializes this instance of %ContentDirectory with the specified parameter.
138          *
139          * @since 2.0
140          *
141          * @return    An error code
142          * @param     contentTypeList           The list of content types @n
143          *                                                      This method is used to access more than one type of content, but total count should not be greater than @c 4.
144          *                                                      The allowed types are @c CONTENT_TYPE_OTHER, @c CONTENT_TYPE_IMAGE, @c CONTENT_TYPE_AUDIO, 
145          *                                                      and @c CONTENT_TYPE_VIDEO. Any combination with @c CONTENT_TYPE_ALL is a invalid argument. @n
146          *                                                      If you want to access only one type of content, use Construct(ContentType) instead of this method.
147          * @exception E_SUCCESS                 The method is successful.
148          * @exception E_INVALID_ARG             The specified input parameter is invalid.
149          * @exception E_OUT_OF_MEMORY           The memory is insufficient.
150          * @exception E_SYSTEM                  The method cannot connect to the database.
151          */
152         result Construct(const Tizen::Base::Collection::IListT<ContentType>& contentTypeList);
153
154         /**
155          * Gets the count of content directories that contains the content type that is passed as a parameter in Construct().
156          *
157          * @since 2.0
158          *
159          * @return    The count of content directories
160          * @exception E_SUCCESS                 The method is successful.
161          * @exception E_OUT_OF_MEMORY           The memory is insufficient.
162          * @exception E_SERVICE_BUSY            The database is busy.
163          * @exception E_SYSTEM                  The method cannot access the database.
164          * @remarks The specific error code can be accessed using the GetLastResult() method.
165          */
166         int GetContentDirectoryCount(void) const;
167
168         /**
169          * Gets the list of content directory path that contains the content type that is passed as a parameter in Construct().
170          *
171          * @since 2.0
172          *
173          * @return    A list of Tizen::Base::String values that contains content directory path
174          * @param     sortOrder                 The sort order
175          * @exception E_SUCCESS                 The method is successful.
176          * @exception E_INVALID_ARG             The specified input parameter is invalid.
177          * @exception E_OUT_OF_MEMORY           The memory is insufficient.
178          * @exception E_SERVICE_BUSY            The database is busy.
179          * @exception E_SYSTEM                  The method cannot access the database.
180          * @remarks The specific error code can be accessed using the GetLastResult() method.
181          */
182         Tizen::Base::Collection::IList* GetContentDirectoryPathListN(Tizen::Base::SortOrder sortOrder) const;
183
184         
185         /**
186          * Gets the count of files in a directory.
187          *
188          * @since 2.0
189          *
190          * @return    The count of files
191          * @param     contentDirectoryPath              The content directory path @n
192          *                                                                                      The allowed directory path can be obtained by using
193          *                                                                                      Tizen::System::Environment::GetMediaPath() and Tizen::System::Environment::GetExternalStoragePath().
194          * @exception E_SUCCESS                 The method is successful.
195          * @exception E_INVALID_ARG             The specified input parameter is invalid.
196          * @exception E_OUT_OF_MEMORY           The memory is insufficient.
197          * @exception E_SERVICE_BUSY            The database is busy.
198          * @exception E_SYSTEM                  The method cannot access the database.
199          * @remarks The specific error code can be accessed using the GetLastResult() method.
200          * @see GetContentDirectoryPathListN()
201          */
202         int GetContentDirectoryItemCount(const Tizen::Base::String& contentDirectoryPath) const;
203
204         /**
205          * Gets the list of content information in a directory.
206          *
207          * @since 2.0
208          *
209          * @return     A list of ContentInfo classes that contains content information 
210          * @param     contentDirectoryPath                      The content directory path @n
211          *                                                                                              The allowed directory path can be obtained by using
212          *                                                                                              Tizen::System::Environment::GetMediaPath() and Tizen::System::Environment::GetExternalStoragePath().
213          * @param     pageNo                                                    The page number @n
214          *                                                                                              It must be equal to or greater than @c 1.
215          * @param     countPerPage                                      The count of the search results per page @n
216          *                                                                                              It must be equal to or greater than @c 1.
217          * @param     column                                                    The sort column name
218          * @param     sortOrder                                         The sort order
219          * @exception E_SUCCESS                                         The method is successful.
220          * @exception E_INVALID_ARG                                     A specified input parameter is invalid.
221          * @exception E_OUT_OF_MEMORY                           The memory is insufficient.
222          * @exception E_SERVICE_BUSY                            The database is busy.
223          * @exception E_SYSTEM                                          The method cannot access the database.
224          * @remarks The specific error code can be accessed using the GetLastResult() method.
225          * @see GetContentDirectoryPathListN()
226          */
227         Tizen::Base::Collection::IList* GetContentDirectoryItemListN(const Tizen::Base::String& contentDirectoryPath, int pageNo, int countPerPage,
228                                                                                 const Tizen::Base::String& column, Tizen::Base::SortOrder sortOrder) const;
229
230 private:
231         /**
232          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
233          */
234         ContentDirectory(const ContentDirectory& rhs);
235
236         /**
237          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
238          */
239         ContentDirectory& operator =(const ContentDirectory& rhs);
240
241         _ContentDirectoryImpl* __pImpl;
242
243         friend class _ContentDirectoryImpl;
244
245 };  // class ContentDirectory
246
247 }}  // Tizen::Content
248
249 #endif  // _FCNT_CONTENT_DIRECTORY_H_