email-api/include/email-api-mailbox.h

   1 /*\r
   2 *  email-service\r
   3 *\r
   4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.\r
   5 *\r
   6 * Contact: Kyuho Jo <kyuho.jo@samsung.com>, Sunghyun Kwon <sh0701.kwon@samsung.com>\r
   7 *\r
   8 * Licensed under the Apache License, Version 2.0 (the "License");\r
   9 * you may not use this file except in compliance with the License.\r
  10 * You may obtain a copy of the License at\r
  11 *\r
  12 * http://www.apache.org/licenses/LICENSE-2.0\r
  13 *\r
  14 * Unless required by applicable law or agreed to in writing, software\r
  15 * distributed under the License is distributed on an "AS IS" BASIS,\r
  16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  17 * See the License for the specific language governing permissions and\r
  18 * limitations under the License.\r
  19 *\r
  20 */\r
  21 \r
  22 \r
  23 #ifndef __EMAIL_API_MAILBOX_H__\r
  24 #define __EMAIL_API_MAILBOX_H__\r
  25 \r
  26 #include "email-types.h"\r
  27 \r
  28 /**\r
  29 * @defgroup EMAIL_SERVICE Email Service\r
  30 * @{\r
  31 */\r
  32 \r
  33 \r
  34 /**\r
  35 * @ingroup EMAIL_SERVICE\r
  36 * @defgroup EMAIL_API_MAILBOX Email Mailbox API\r
  37 * @{\r
  38 */\r
  39 \r
  40 /**\r
  41  *\r
  42  * This file contains the data structures and interfaces needed for application,\r
  43  * to interact with email-service.\r
  44  * @file                email-api-mailbox.h\r
  45  * @author      Kyuho Jo <kyuho.jo@samsung.com>\r
  46  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>\r
  47  * @version     0.1\r
  48  * @brief               This file contains the data structures and interfaces of mailbox provided by\r
  49  *                      email-service .\r
  50  * @{\r
  51  * @code\r
  52  *\r
  53  *  #include "email_api_mailbox.h"\r
  54  *\r
  55  *  bool other_app_invoke_uniform_api_sample(int *error_code)\r
  56  *      {\r
  57  *              emf_mailbox_t mbox;\r
  58  *              emf_mailbox_t *new_mailbox =NULL;\r
  59  *              emf_mailbox_t *mailbox_list = NULL;\r
  60  *              int count = 0;\r
  61  *              int mailbox_type;\r
  62  *              unsigned handle = 0;\r
  63  *              char *pMaiboxName;\r
  64  *              char *pParentMailbox;\r
  65  *\r
  66  *              memset(&mbox,0x00,sizeof(emf_mailbox_t));\r
  67  *              mbox.name = strdup("test");\r
  68  *              mbox.alias = strdup("Personal");\r
  69  *              mbox.account_id = 1;\r
  70  *              printf("Enter local_yn(1/0)");\r
  71  *              scanf("%d",&local_yn);\r
  72  *              mbox.local=local_yn;\r
  73  *              mbox.mailbox_type = 7;\r
  74  *\r
  75  *              //create new mailbox\r
  76  *\r
  77  *              if(EMF_ERR_NONE != email_add_mailbox(&mbox,local_yn,&handle))\r
  78  *                      printf("email_add_mailbox failed\n");\r
  79  *              else\r
  80  *                      printf("email_add_mailbox success");\r
  81  *\r
  82  *              //update mailbox\r
  83  *             new_mailbox = malloc(sizeof(emf_mailbox_t));\r
  84  *             memset(new_mailbox,0x00,sizeof(emf_mailbox_t));\r
  85  *\r
  86  *             new_mailbox->name = strdup("PersonalUse");\r
  87  *\r
  88  *             if(EMF_ERROR_NONE != email_update_mailbox(&mbox,new_mailbox))\r
  89  *                      printf("email_update_mailbox failed\n");\r
  90  *             else\r
  91  *                      printf("email_update_mailbox success\n");\r
  92  *              //delete mailbox\r
  93  *\r
  94  *              if(EMF_ERROR_NONE != email_delete_mailbox(mbox,local_yn,&handle))\r
  95  *                      printf("email_delete_mailbox failed\n");\r
  96  *              else\r
  97  *                      printf("email_delete_mailbox success\n");\r
  98  *\r
  99  *              //free mailbox\r
 100  *              email_free_mailbox("new_mailbox,1");\r
 101  *\r
 102  *              //Get mailbox list\r
 103  *              if(EMF_ERROR_NONE != email_get_mailbox_list(account_id,local_yn,&mailbox_list,&count))\r
 104  *                      //failure\r
 105  *              else\r
 106  *                      //success\r
 107  *\r
 108  *              //Get mailbox by name\r
 109  *              pMailboxName = strdup("test");\r
 110  *              if(EMF_ERROR_NONE != email_get_mailbox_by_name(account_id,pMailboxName,&mailbox_list))\r
 111  *                      //failure\r
 112  *              else\r
 113  *                      //success\r
 114  *\r
 115  *              //Get child mailbox list\r
 116  *              pParentMailbox = strdup("test");\r
 117  *              if(EMF_ERROR_NONE != email_get_child_mailbox_list(account_id, paerent_mailbox,&mailbox_list,&count))\r
 118  *                      //failure\r
 119  *              else\r
 120  *                      //success\r
 121  *\r
 122  *              //Get mailbox by mailbox_type\r
 123  *              printf("Enter mailbox_type\n");\r
 124  *              scanf("%d",&mailbox_type);\r
 125  *              if(EMF_ERROR_NONE != email_get_mailbox_by_mailbox_type(account_id,mailbox_type,&mailbox_list))\r
 126  *                      //failure\r
 127  *              else\r
 128  *                      //success\r
 129  *\r
 130  *      }\r
 131  *\r
 132  * @endcode\r
 133  * @}\r
 134  */\r
 135 \r
 136 \r
 137 \r
 138 #ifdef __cplusplus\r
 139 extern "C"\r
 140 {\r
 141 #endif /* __cplusplus */\r
 142 \r
 143 \r
 144 /**\r
 145 \r
 146  * @open\r
 147  * @fn EXPORT_API int email_add_mailbox(emf_mailbox_t* new_mailbox, int on_server, unsigned* handle)\r
 148  * @brief       Create a new mailbox or mailbox.This function is invoked when user wants to create a new mailbox for the specified account.\r
 149  *              If On_server is true then it will create the mailbox on server as well as in local also.\r
 150  *\r
 151  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 152  * @param[in] new_mailbox       Specifies the pointer of creating mailbox information.\r
 153 *  @param[in] on_server         Specifies the creating mailbox information on server.\r
 154  * @param[out] handle           Specifies the sending handle.\r
 155  * @exception   none\r
 156  * @see         emf_mailbox_t\r
 157   * @remarks N/A\r
 158  */\r
 159 EXPORT_API int email_add_mailbox(emf_mailbox_t* new_mailbox, int on_server, unsigned* handle);\r
 160 \r
 161 \r
 162 /**\r
 163 \r
 164  * @open\r
 165  * @fn EXPORT_API int email_delete_mailbox(emf_mailbox_t* mailbox, int on_server,  unsigned* handle)\r
 166  * @brief       Delete a mailbox or mailbox.This function deletes the existing mailbox for specified account based on the option on_server.\r
 167  *              If the on_server is true then it deletes mailbox from server as well as locally.\r
 168  *\r
 169  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 170  * @param[in] mailbox   Specifies the pointer of deleting mailbox information.\r
 171  * @param[in] on_server         Specifies the creating mailbox information on server.\r
 172  * @param[out] handle           Specifies the sending handle.\r
 173  * @exception   #EMF_ERROR_INVALID_PARAM        -Invaid argument\r
 174  * @see         emf_mailbox_t\r
 175  * @remarks N/A\r
 176  */\r
 177 EXPORT_API int email_delete_mailbox(emf_mailbox_t* mailbox, int on_server,  unsigned* handle);\r
 178 \r
 179 \r
 180 /**\r
 181 \r
 182  * @fn EXPORT_API int email_update_mailbox(emf_mailbox_t* old_mailbox, emf_mailbox_t* new_mailbox)\r
 183  * @brief       Change mailbox or mailbox information.This function is invoked when user wants to change the existing mail box information.\r
 184  *                      This supports ONLY updating mailbox_type in local db. This can be used to match a specific mail box and a specific mailbox_type.\r
 185  *\r
 186  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 187  * @param[in] old_mailbox       Specifies the information of previous mailbox. <br>mandatory field : account_id, name\r
 188  * @param[in] new_mailbox       Specifies the information of new mailbox. <br\r
 189  * @exception #EMF_ERROR_INVALID_PARAM          -Invaid argument\r
 190  * @see         emf_mailbox_t, emf_mailbox_type_e\r
 191   * @remarks N/A\r
 192  */\r
 193 EXPORT_API int email_update_mailbox(emf_mailbox_t* old_mailbox, emf_mailbox_t* new_mailbox);\r
 194 \r
 195 /**\r
 196 \r
 197  * @open\r
 198  * @fn email_get_mailbox_list(int account_id, int mailbox_sync_type, emf_mailbox_t** mailbox_list, int* count)\r
 199  * @brief       Get all mailboxes from account.\r
 200  *\r
 201  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 202  * @param[in] account_id                Specifies the account ID.\r
 203  * @param[in] mailbox_sync_type         Specifies the sync type.\r
 204  * @param[out] mailbox_list     Specifies the pointer of mailbox structure pointer.(possibly NULL)\r
 205  * @param[out] count                    The mailbox count is saved here.(possibly 0)\r
 206  * @exception           none\r
 207  * @see         emf_mailbox_t\r
 208 \r
 209  * @code\r
 210  *      #include "email-api-mailbox.h"\r
 211  *      bool\r
 212  *      _api_sample_get_mailbox_list()\r
 213  *      {\r
 214  *              int account_id =0,count = 0;\r
 215  *              int mailbox_sync_type;\r
 216  *              int error_code = EMF_ERROR_NONE;\r
 217  *              emf_mailbox_t *mailbox_list=NULL;\r
 218  *\r
 219  *              printf("\n > Enter account id: ");\r
 220  *              scanf("%d", &account_id);\r
 221  *              printf("\n > Enter mailbox_sync_type: ");\r
 222  *              scanf("%d", &mailbox_sync_type);\r
 223  *\r
 224  *              if((EMF_ERROR_NONE != email_get_mailbox_list(account_id, mailbox_sync_type, &mailbox_list, &count)))\r
 225  *              {\r
 226  *                      printf(" Error\n");\r
 227  *              }\r
 228  *              else\r
 229  *              {\r
 230  *                      printf("Success\n");\r
 231  *                      email_free_mailbox(&mailbox_list,count);\r
 232  *              }\r
 233  *      }\r
 234  * @endcode\r
 235  * @remarks N/A\r
 236  */\r
 237 EXPORT_API int email_get_mailbox_list(int account_id, int mailbox_sync_type, emf_mailbox_t** mailbox_list, int* count);\r
 238 \r
 239 EXPORT_API int email_get_mailbox_list_ex(int account_id, int mailbox_sync_type, int with_count, emf_mailbox_t** mailbox_list, int* count);\r
 240 \r
 241 /**\r
 242 \r
 243  * @open\r
 244  * @fn EXPORT_API int email_get_mailbox_by_name(int account_id, const char *pMailboxName, emf_mailbox_t **pMailbox);\r
 245  * @brief       Get the mailbox information by name.This function gets the mailbox by given mailbox name for a specified account.\r
 246  *\r
 247  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 248  * @param[in] account_id                Specifies the information of account Id.\r
 249  * @param[in] pMailboxName              Specifies the mailbox name.\r
 250  * @param[out] pMailbox                 Specifies the information of mailbox\r
 251  * @exception none\r
 252  * @see         emf_mailbox_t\r
 253  * @remarks N/A\r
 254  */\r
 255 \r
 256 EXPORT_API int email_get_mailbox_by_name(int account_id, const char *pMailboxName, emf_mailbox_t **pMailbox);\r
 257 \r
 258 // Belows are for A Project\r
 259 \r
 260 /**\r
 261 \r
 262  * @open\r
 263  * @fn email_get_child_mailbox_list(int account_id, char *parent_mailbox,  emf_mailbox_t** mailbox_list, int* count)\r
 264  * @brief       Get all sub mailboxes for given parent mailbox.This function gives all the child mailbox list for a given parent mailbox for specified account.\r
 265  *\r
 266  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 267  * @param[in] account_id                Specifies the account ID.\r
 268  * @param[in] parent_mailbox            Specifies the parent mailbox\r
 269  * @param[out] mailbox_list            Specifies the pointer of mailbox structure pointer.(possibly NULL)\r
 270  * @param[out] count                    The mailbox count\r
 271  * @exception  #EMF_ERROR_INVALID_PARAM         -Invalid argument\r
 272  * @see         emf_mailbox_t\r
 273  * @remarks N/A\r
 274  * @return This function returns true on success or false on failure.\r
 275  */\r
 276 EXPORT_API int email_get_child_mailbox_list(int account_id, const char *parent_mailbox,  emf_mailbox_t** mailbox_list, int* count);\r
 277 \r
 278 \r
 279 /**\r
 280  * @open\r
 281  * @fn email_get_mailbox_by_mailbox_type(int account_id, emf_mailbox_type_e mailbox_type,  emf_mailbox_t** mailbox)\r
 282  * @brief       Get mailbox by mailbox_type.This function is invoked when user wants to know the mailbox information by mailbox_type for the given account.\r
 283  *\r
 284  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 285  * @param[in] account_id                Specifies the account ID.\r
 286  * @param[in] mailbox_type              Specifies the mailbox type.\r
 287  * @param[out] mailbox          Specifies the pointer of mailbox structure pointer.(possibly NULL)\r
 288  * @exception none\r
 289  * @see         emf_mailbox_t\r
 290  * @remarks N/A\r
 291  */\r
 292 EXPORT_API int email_get_mailbox_by_mailbox_type(int account_id, emf_mailbox_type_e mailbox_type,  emf_mailbox_t** mailbox);\r
 293 \r
 294 /**\r
 295  * @open\r
 296  * @fn email_set_mail_slot_size(int account_id, char* mailbox_name, int new_slot_size, unsigned* handle)\r
 297  * @brief       Set mail slot size.This function is invoked when user wants to set the size of mail slot.\r
 298  *\r
 299  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.\r
 300  * @param[in] account_id                Specifies the account ID.\r
 301  * @param[in] mailbox_name              Specifies the mailbox name.\r
 302  * @param[in] new_slot_size             Specifies the mail slot size.\r
 303  * @exception none\r
 304  * @see         emf_mailbox_t\r
 305  * @remarks N/A\r
 306  */\r
 307 EXPORT_API int email_set_mail_slot_size(int account_id, char* mailbox_name, int new_slot_size/*, unsigned* handle*/);\r
 308 \r
 309 /**\r
 310  * @open\r
 311  * @fn email_free_mailbox(emf_mailbox_t** mailbox_list, int count)\r
 312  * @brief       Free allocated memory for mailbox information.\r
 313  *\r
 314  * @return This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 315  * @param[in] mailbox_list      Specifies the pointer for searching mailbox structure pointer.\r
 316  * @param[in] count                     Specifies the count of mailboxes.\r
 317  * @exception           none\r
 318  * @see                 emf_mailbox_t\r
 319 \r
 320  * @code\r
 321  *      #include "email-api-mailbox.h"\r
 322  *      bool\r
 323  *      _api_sample_free_mailbox_info()\r
 324  *      {\r
 325  *              emf_mailbox_t *mailbox;\r
 326  *\r
 327  *              //fill the mailbox structure\r
 328  *              //count - number of mailbox structure user want to free\r
 329  *               if(EMF_ERROR_NONE == email_free_mailbox(&mailbox,count))\r
 330  *                      //success\r
 331  *               else\r
 332  *                      //failure\r
 333  *\r
 334  *      }\r
 335  * @endcode\r
 336  * @remarks N/A\r
 337  */\r
 338 \r
 339 EXPORT_API int email_free_mailbox(emf_mailbox_t** mailbox_list, int count);\r
 340 \r
 341 #ifdef __cplusplus\r
 342 }\r
 343 #endif /* __cplusplus */\r
 344 \r
 345 /**\r
 346 * @} @}\r
 347 */\r
 348 \r
 349 \r
 350 \r
 351 #endif /* __EMAIL_API_MAILBOX_H__ */\r
 352 \r
 353 \r