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