include/favorites.h

   1 /*\r
   2  * Copyright (c) 2012 Samsung Electronics Co., Ltd All Rights Reserved\r
   3  *\r
   4  * Licensed under the Apache License, Version 2.0 (the License);\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  * http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an AS IS BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 #ifndef __TIZEN_WEB_FAVORITES_H__\r
  18 #define __TIZEN_WEB_FAVORITES_H__\r
  19 \r
  20 #include <stdio.h>\r
  21 #include <stdlib.h>\r
  22 #include <Evas.h>\r
  23 #include <tizen.h>\r
  24 \r
  25 #ifdef __cplusplus\r
  26 extern "C" {\r
  27 #endif\r
  28 /**\r
  29  * @addtogroup CAPI_WEB_FAVORITES_MODULE\r
  30  * @{\r
  31  */\r
  32 \r
  33 /**\r
  34  * @brief Enumerations for favorites error.\r
  35  */\r
  36 typedef enum favorites_error{\r
  37         FAVORITES_ERROR_NONE                    = TIZEN_ERROR_NONE,              /**< Successful */\r
  38         FAVORITES_ERROR_INVALID_PARAMETER       = TIZEN_ERROR_INVALID_PARAMETER,/**< Invalid parameter */\r
  39         FAVORITES_ERROR_DB_FAILED               = TIZEN_ERROR_WEB_CLASS | 0x62,  /**< Database operation failure */\r
  40         FAVORITES_ERROR_ITEM_ALREADY_EXIST      = TIZEN_ERROR_WEB_CLASS | 0x63,  /**< Requested data already exists */\r
  41         FAVORITES_ERROR_NO_SUCH_FILE    = TIZEN_ERROR_NO_SUCH_FILE, /**< No such file or directory */\r
  42         FAVORITES_ERROR_UNKNOWN         = TIZEN_ERROR_UNKNOWN  /**< Unknown error */\r
  43 } favorites_error_e;\r
  44 \r
  45 /**\r
  46  * @brief   The structure of bookmark entry in search results.\r
  47  *\r
  48  * @details This structure is passed to callback function in all bookmark related\r
  49  * iterations through list received from search functions.\r
  50  *\r
  51  * @see  bookmark_foreach_cb()\r
  52  */\r
  53 typedef struct {\r
  54         char* address;  /**< Bookmark URL */\r
  55         char* title;    /**< The title of the bookmark */\r
  56         char* creation_date;    /**< The date of creation(yyyy-mm-dd hh:mm:ss) */\r
  57         char* update_date;      /**< The last updated date(yyyy-mm-dd hh:mm:ss) */\r
  58         char* visit_date;       /**< The last visit date(yyyy-mm-dd hh:mm:ss) */\r
  59         int id; /**< The unique ID of bookmark */\r
  60         bool is_folder; /**< property bookmark or folder\n @c 1: folder, @c 0: bookmark */\r
  61         int folder_id;  /**< The ID of parent folder */\r
  62         int order_index;        /**< The order index of bookmarks when show the list at the browser */\r
  63         bool editable;  /**< The flag of editability\n @c 1 : writable, @c 0: read-only, not ediable */\r
  64 } favorites_bookmark_entry_s;\r
  65 \r
  66 /**\r
  67  * @brief       Called to get bookmark details for each found bookmark.\r
  68  *\r
  69  * @param[in]   item    The bookmark entry handle or folder entry handle\r
  70  * @param[in]   user_data       The user data passed from the foreach function\r
  71  *\r
  72  * @return @c true to continue with the next iteration of the loop or @c false to break out of the loop.\r
  73  *\r
  74  * @pre         favorites_bookmark_foreach() will invoke this callback.\r
  75  *\r
  76  * @see         favorites_bookmark_foreach()\r
  77  */\r
  78 typedef bool (*favorites_bookmark_foreach_cb)(favorites_bookmark_entry_s *item, void *user_data);\r
  79 \r
  80 /**\r
  81  * @brief       Gets the id of the root folder.\r
  82  *\r
  83  * @param[out]  root_folder_id  The id of the root folder.\r
  84  *\r
  85  * @return  0 on success, otherwise a negative error value.\r
  86  * @retval  #FAVORITES_ERROR_NONE        Successful\r
  87  * @retval  #FAVORITES_ERROR_DB_FAILED   Database failed\r
  88  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
  89  *\r
  90  */\r
  91 int favorites_bookmark_get_root_folder_id(int *root_id);\r
  92 \r
  93 /**\r
  94  * @brief       Adds a bookmark to bookmark database.\r
  95  *\r
  96  * @remarks  If a folder named @a "foldername" doesn't exist, it will be created in the root folder.\r
  97  * @param[in]   url     Bookmark URL\r
  98  * @param[in]   title   The title of the bookmark\r
  99  * @param[in]   folder_name     The name of parent folder in the root folder\r
 100  * @param[out]  saved_id        The unique id of the added bookmark\r
 101  *\r
 102  * @return  0 on success, otherwise a negative error value.\r
 103  * @retval  #FAVORITES_ERROR_NONE        Successful\r
 104  * @retval  #FAVORITES_ERROR_DB_FAILED   Database failed\r
 105  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 106  * @retval  #FAVORITES_ERROR_ITEM_ALREADY_EXIST Requested data already exists\r
 107  *\r
 108  */\r
 109 int favorites_bookmark_add_bookmark(const char *url, const char *title, const char *folder_name, int *saved_id);\r
 110 \r
 111 /**\r
 112  * @brief       Adds a bookmark or folder item  to bookmark database.\r
 113  *\r
 114  * @remarks  If the parent_id is not valid folder id, this API will return error.\r
 115  * @param[in]   title   The title of the bookmark or folder\r
 116  * @param[in]   url     The bookmark URL. if the type is folder, this param will be ignored.\r
 117  * @param[in]   parent_id       The unique id of folder which added item belong to.\r
 118  * @param[in]   type    The type of item ( 0 : bookmark, 1 : folder )\r
 119  * @param[out]  saved_id         The unique id of the added item\r
 120  *\r
 121  * @return  0 on success, otherwise a negative error value.\r
 122  * @retval  #FAVORITES_ERROR_NONE        Successful\r
 123  * @retval  #FAVORITES_ERROR_DB_FAILED   Database failed\r
 124  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 125  * @retval  #FAVORITES_ERROR_ITEM_ALREADY_EXIST Requested data already exists\r
 126  * @retval  #FAVORITES_ERROR_NO_SUCH_FILE       parent_id is not valid\r
 127  *\r
 128  */\r
 129 int favorites_bookmark_add(const char *title, const char *url, int parent_id, int type, int *saved_id);\r
 130 \r
 131 /**\r
 132  * @brief       Deletes the bookmark item of given bookmark id.\r
 133  *\r
 134  * @param[in]   bookmark_id     The unique ID of bookmark to delete\r
 135  *\r
 136  * @return  0 on success, otherwise a negative error value.\r
 137  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 138  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 139  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 140  *\r
 141  */\r
 142 int favorites_bookmark_delete_bookmark(int bookmark_id);\r
 143 \r
 144 /**\r
 145  * @brief       Deletes all bookmarks and sub folders.\r
 146  *\r
 147  * @return  0 on success, otherwise a negative error value.\r
 148  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 149  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 150  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 151  *\r
 152  */\r
 153 int favorites_bookmark_delete_all_bookmarks(void);\r
 154 \r
 155 /**\r
 156  * @brief       Gets a number of bookmark list items.\r
 157  *\r
 158  * @param[out]  count   The number of bookmarks and sub folders.\r
 159  *\r
 160  * @return  0 on success, otherwise a negative error value.\r
 161  * @retval  #FAVORITES_ERROR_NONE        Successful\r
 162  * @retval  #FAVORITES_ERROR_DB_FAILED   Database failed\r
 163  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 164  *\r
 165  */\r
 166 int favorites_bookmark_get_count(int *count);\r
 167 \r
 168 /**\r
 169  * @brief       Retrieves all bookmarks and folders by invoking the given callback function iteratively.\r
 170  *\r
 171  * @remarks  All bookmarks and folders data are also used by browser application\r
 172  * @param[in]   callback        The callback function to invoke\r
 173  * @param[in]   user_data       The user data to be passed to the callback function\r
 174  *\r
 175  * @return  0 on success, otherwise a negative error value.\r
 176  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 177  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 178  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 179  *\r
 180  * @post        This function invokes bookmark_foreach_cb() repeatedly for each bookmark.\r
 181  *\r
 182  * @see bookmark_foreach_cb()\r
 183  */\r
 184 int favorites_bookmark_foreach(favorites_bookmark_foreach_cb callback, void *user_data);\r
 185 \r
 186 /**\r
 187  * @brief       Exports a whole bookmark list as a netscape HTML bookmark file.\r
 188  *\r
 189  * @param[in]   file_path      The absolute path of the export file. This must includes html file name.\r
 190  *\r
 191  * @return  0 on success, otherwise a negative error value.\r
 192  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 193  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 194  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 195  *\r
 196  */\r
 197 int favorites_bookmark_export_list(const char *file_path);\r
 198 \r
 199 /**\r
 200  * @brief       Gets the bookmark's favicon as a evas object type\r
 201  *\r
 202  * @param[in]   bookmark_id     The unique ID of bookmark\r
 203  * @param[in]   evas    The given canvas\r
 204  * @param[out]  icon    Retrieved favicon evas object of bookmark.\r
 205  *\r
 206  * @return  0 on success, otherwise a negative error value.\r
 207  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 208  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 209  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 210  *\r
 211  */\r
 212 int favorites_bookmark_get_favicon(int bookmark_id, Evas *evas, Evas_Object **icon);\r
 213 \r
 214 /**\r
 215  * @brief       Sets the bookmark's favicon\r
 216  *\r
 217  * @param[in]   bookmark_id     The unique ID of bookmark\r
 218  * @param[in]   icon    The favicon object to save\r
 219  *\r
 220  * @return  0 on success, otherwise a negative error value.\r
 221  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 222  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 223  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 224  *\r
 225  */\r
 226 int favorites_bookmark_set_favicon(int bookmark_id, Evas_Object *icon);\r
 227 \r
 228 /**\r
 229  * @brief   The structure of history entry in search results.\r
 230  *\r
 231  * @details This structure is passed to callback function in all history related\r
 232  * iterations through list received from search functions.\r
 233  *\r
 234  * @see  history_foreach_cb()\r
 235  */\r
 236 typedef struct {\r
 237         char* address;  /**< URL history */\r
 238         char* title;    /**< The title of history */\r
 239         int count;      /**< The visit count */\r
 240         char* visit_date;       /**< The last visit date */\r
 241         int id; /**< The unique ID of history */\r
 242 } favorites_history_entry_s;\r
 243 \r
 244 /**\r
 245  * @brief       Called to get history details for each found history.\r
 246  *\r
 247  * @param[in]   item    The history entry handle\r
 248  * @param[in]   user_data       The user data passed from the foreach function\r
 249  *\r
 250  * @return @c true to continue with the next iteration of the loop or @c false to break out of the loop.\r
 251  *\r
 252  * @pre         favorites_history_foreach() will invoke this callback.\r
 253  *\r
 254  * @see         favorites_history_foreach()\r
 255  */\r
 256 typedef bool (*favorites_history_foreach_cb)(favorites_history_entry_s *item, void *user_data);\r
 257 \r
 258 /**\r
 259  * @brief       Gets a number of history list items.\r
 260  *\r
 261  * @param[out]  count   The number of histories.\r
 262  *\r
 263  * @return  0 on success, otherwise a negative error value.\r
 264  * @retval  #FAVORITES_ERROR_NONE        Successful\r
 265  * @retval  #FAVORITES_ERROR_DB_FAILED   Database failed\r
 266  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 267  *\r
 268  */\r
 269 int favorites_history_get_count(int *count);\r
 270 \r
 271 /**\r
 272  * @brief       Retrieves all histories by invoking the given callback function iteratively.\r
 273  *\r
 274  * @param[in]   callback        The callback function to invoke\r
 275  * @param[in]   user_data       The user data to be passed to the callback function\r
 276  *\r
 277  * @return  0 on success, otherwise a negative error value.\r
 278  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 279  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 280  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 281  *\r
 282  * @post        This function invokes history_foreach_cb().\r
 283  *\r
 284  * @see history_foreach_cb()\r
 285  */\r
 286 int favorites_history_foreach(favorites_history_foreach_cb callback, void *user_data);\r
 287 \r
 288 /**\r
 289  * @brief       Deletes the history item of given history id.\r
 290  *\r
 291  * @param[in]   history_id      The history ID to delete\r
 292  *\r
 293  * @return  0 on success, otherwise a negative error value.\r
 294  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 295  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 296  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 297  *\r
 298  */\r
 299 int favorites_history_delete_history(int history_id);\r
 300 \r
 301 /**\r
 302  * @brief       Deletes the history item of given history url.\r
 303  *\r
 304  * @param[in]   url         history url which wants to be deleted\r
 305  *\r
 306  * @return  0 on success, otherwise a negative error value.\r
 307  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 308  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 309  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 310  *\r
 311  */\r
 312 int favorites_history_delete_history_by_url(const char *url);\r
 313 \r
 314 /**\r
 315  * @brief       Deletes all histories.\r
 316  *\r
 317  * @return  0 on success, otherwise a negative error value.\r
 318  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 319  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 320  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 321  *\r
 322  */\r
 323 int favorites_history_delete_all_histories(void);\r
 324 \r
 325 /**\r
 326  * @brief       Deletes all histories accessed with the browser within the specified time period.\r
 327  *\r
 328  * @param[in]   begin_date         The start date of the period\r
 329  * @param[in]   end_date           The end date of the period\r
 330  *\r
 331  * @remarks  Date format must be "yyyy-mm-dd hh:mm:ss" ex: "2000-01-01 01:20:35".\r
 332  *\r
 333  * @return  0 on success, otherwise a negative error value.\r
 334  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 335  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 336  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 337  *\r
 338  */\r
 339 int favorites_history_delete_history_by_term(const char *begin_date, const char *end_date);\r
 340 \r
 341 /**\r
 342  * @brief       Gets the history's favicon as an evas object type\r
 343  *\r
 344  * @param[in]   history_id      The unique ID of history item\r
 345  * @param[in]   evas    The given canvas\r
 346  * @param[out]  icon    Retrieved favicon evas object of bookmark.\r
 347  *\r
 348  * @return  0 on success, otherwise a negative error value.\r
 349  * @retval  #FAVORITES_ERROR_NONE                Successful\r
 350  * @retval  #FAVORITES_ERROR_INVALID_PARAMETER   Invalid parameter\r
 351  * @retval  #FAVORITES_ERROR_DB_FAILED           Database failed\r
 352  *\r
 353  */\r
 354 int favorites_history_get_favicon(int history_id, Evas *evas, Evas_Object **icon);\r
 355 \r
 356 /**\r
 357  * @}\r
 358  */\r
 359 \r
 360 #ifdef __cplusplus\r
 361 };\r
 362 #endif\r
 363 \r
 364 #endif /* __TIZEN_WEB_FAVORITES_H__ */\r