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

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