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