inc/FWebWebBookmark.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 /**
  19 * @file                 FWebWebBookmark.h
  20 * @brief                This is the header file for the %WebBookmark class.
  21 *
  22 * This header file contains the declarations of the %WebBookmark class.
  23 */
  24
  25 #ifndef _FWEB_WEB_BOOKMARK_H_
  26 #define _FWEB_WEB_BOOKMARK_H_
  27
  28 #include <FBaseString.h>
  29 #include <FWebBookmarkItem.h>
  30
  31 namespace Tizen { namespace Graphics
  32 {
  33 class Bitmap;
  34 }} // Tizen::Graphics
  35
  36 namespace Tizen { namespace Web
  37 {
  38 class _WebBookmarkImpl;
  39
  40 /**
  41  * @class               WebBookmark
  42  * @brief               This class provides methods to manage bookmark items of the browser.
  43  *
  44  * @since               2.1
  45  *
  46  * @final               This class is not intended for extension.
  47  *
  48  * The %WebBookmark class provides methods to get bookmark information of the browser and organize it.
  49  * The bookmark system has hierarchical structure with the parent folder ID supporting multiple folders and the bookmark items are represented by the BookmarkItem class. @n
  50  * If you use these APIs to backup and restore the bookmark, add bookmark items and folders recursively from the topmost level.
  51  */
  52 class _OSP_EXPORT_ WebBookmark
  53         : public Tizen::Base::Object
  54 {
  55 public:
  56         /**
  57          * The object is not fully constructed after this constructor is called. @n
  58          * For full construction, the Construct() method must be called right after calling this constructor.
  59          *
  60          * @since               2.1
  61          */
  62         WebBookmark(void);
  63
  64         /**
  65          * This destructor overrides Osp::Base::Object::~Object().
  66          *
  67          * @since               2.1
  68          */
  69         virtual ~ WebBookmark(void);
  70
  71         /**
  72          * Initializes this instance of %WebBookmark.
  73          *
  74          * @since               2.1
  75          *
  76          * @return              An error code
  77          * @exception   E_SUCCESS                       The method is successful.
  78          * @exception   E_SYSTEM                        A system error has occurred.
  79          */
  80         result Construct(void);
  81
  82         /**
  83          * Adds a bookmark folder.
  84          *
  85          * @since               2.1
  86          * @privlevel   platform
  87          * @privilege   %http://tizen.org/privilege/bookmark.write
  88          *
  89          * @return              An error code
  90          * @param[in]   title                   The title of bookmark item
  91          * @param[out]  folderId                The current folder ID
  92          * @param[in]   parentId                The parent folder ID
  93          * @exception   E_SUCCESS                       The method is successful.
  94          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
  95          *                                                                       - The specified title is an empty string. @n
  96          *                                                                       - The specified @c parentId is invalid.
  97          * @exception   E_OBJ_ALREADY_EXIST     A folder with the same title and parent ID already exists.
  98          * @exception   E_SYSTEM                        The method has failed.
  99          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 100          * @see BookmarkItem::GetParentFolderId()
 101          */
 102         result AddFolder(const Tizen::Base::String& title, RecordId& folderId, RecordId parentId = ROOT_FOLDER_ID);
 103
 104
 105         /**
 106          * Adds bookmark contents.
 107          *
 108          * @since               2.1
 109          * @privlevel   platform
 110          * @privilege   %http://tizen.org/privilege/bookmark.write
 111          *
 112          * @return              An error code
 113          * @param[in]   title                   The title of bookmark item
 114          * @param[in]   url                             The URL of bookmark item
 115          * @param[out]  bookmarkId              The current bookmark ID
 116          * @param[in]   parentId                The parent folder ID
 117          * @exception   E_SUCCESS                       The method is successful.
 118          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 119          *                                                                       - The specified @c title is an empty string. @n
 120          *                                                                       - The specified @c url is an empty string. @n
 121          *                                                                       - The specified @c parentId is invalid.
 122          * @exception   E_OBJ_ALREADY_EXIST     A folder with the same title and parent ID already exists.
 123          * @exception   E_SYSTEM                        The method has failed.
 124          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 125          * @see BookmarkItem::GetParentFolderId()
 126          */
 127         result AddBookmark(const Tizen::Base::String& title, const Tizen::Base::String& url, RecordId& bookmarkId, RecordId parentId = ROOT_FOLDER_ID);
 128
 129         /**
 130          * Sets a favicon.
 131          *
 132          * @since               2.1
 133          * @privlevel   platform
 134          * @privilege   %http://tizen.org/privilege/bookmark.write
 135          *
 136          * @return              An error code
 137          * @param[in]   bookmarkId              The bookmark ID
 138          * @param[in]   favicon                 The favicon image
 139          * @exception   E_SUCCESS                       The method is successful.
 140          * @exception   E_INVALID_ARG           The specified @c bookmarkId is invalid.
 141          * @exception   E_INVALID_DATA          The specified @c favicon data is invalid.
 142          * @exception   E_SYSTEM                        The method has failed.
 143          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 144          * @see BookmarkItem::GetFaviconN()
 145          */
 146         result SetFavicon(RecordId bookmarkId, const Tizen::Graphics::Bitmap& favicon);
 147
 148         /**
 149          * Gets the bookmark item pointed to by the specified @c index.
 150          *
 151          * @since               2.1
 152          * @privlevel   platform
 153          * @privilege   %http://tizen.org/privilege/bookmark.read
 154          *
 155          * @return              The bookmark item at the specified @c index
 156          * @param[in]   index                   The index of an element @n
 157          *                                                              The value of the @c index must be greater than or equal to @c 0.
 158          * @exception   E_SUCCESS                       The method is successful.
 159          * @exception   E_OUT_OF_RANGE          The specified @c index is out of range.
 160          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 161          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 162          */
 163         const BookmarkItem* GetItemAt(int index) const;
 164
 165         /**
 166          * Gets the total number of items.
 167          *
 168          * @since               2.1
 169          * @privlevel   platform
 170          * @privilege   %http://tizen.org/privilege/bookmark.read
 171          *
 172          * @return              The total number of items
 173          * @exception   E_SUCCESS                       The method is successful.
 174          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 175          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 176          */
 177         int GetItemCount(void) const;
 178
 179         /**
 180          * Removes all elements.
 181          *
 182          * @since               2.1
 183          * @privlevel   platform
 184          * @privilege   %http://tizen.org/privilege/bookmark.write
 185          *
 186          * @return              An error code
 187          * @exception   E_SUCCESS                       The method is successful.
 188          * @exception   E_SYSTEM                        The method has failed.
 189          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 190          */
 191         result RemoveAll(void);
 192
 193 private:
 194         //
 195         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 196         //
 197         // @param[in]   rhs                             The instance of the %WebBookmark class to copy from
 198         // @remarks             This constructor is hidden.
 199         //
 200         WebBookmark(const WebBookmark & rhs);
 201
 202         //
 203         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 204         //
 205         // @param[in]   rhs                             An instance of %WebBookmark
 206         // @remarks             The method is declared but not implemented.
 207         //
 208         WebBookmark& operator=(const WebBookmark& rhs);
 209
 210 private:
 211         _WebBookmarkImpl * __pWebBookmarkImpl;
 212
 213         friend class _WebBookmarkImpl;
 214 }; // WebBookmark
 215
 216 }} // Tizen::Web
 217 #endif // _FWEB_WEB_BOOKMARK_H_
 218