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

   1 /*
   2 *  email-service
   3 *
   4 * Copyright (c) 2012 - 2013 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  *              int 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  * @fn int email_add_mailbox(email_mailbox_t* new_mailbox, int on_server, int *handle)
 136  * @brief       Create a new mailbox or mailbox.This function is invoked when user wants to create a new mailbox for the specified account.
 137  *              If On_server is true then it will create the mailbox on server as well as in local also.
 138  *
 139  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 140  * @param[in] new_mailbox       Specifies the pointer of creating mailbox information.
 141 *  @param[in] on_server         Specifies the creating mailbox on server.
 142  * @param[out] handle           Specifies the sending handle.
 143  * @exception   none
 144  * @see         email_mailbox_t
 145   * @remarks N/A
 146  */
 147 EXPORT_API int email_add_mailbox(email_mailbox_t *new_mailbox, int on_server, int *handle);
 148
 149 /**
 150  * @fn int email_rename_mailbox(int input_mailbox_id, char *input_mailbox_name, char *input_mailbox_alias)
 151  * @brief       Change mailbox name. This function is invoked when user wants to change the name of existing mail box.
 152  *
 153  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 154  * @param[in] input_mailbox_id  Specifies the id of the mailbox.
 155  * @param[in] input_mailbox_name        Specifies the name of the mailbox.
 156  * @param[in] input_mailbox_alias       Specifies the alias of the mailbox.
 157  * @param[in] input_on_server   Specifies the moving mailbox on server.
 158  * @param[out] output_handle    Specifies the handle to manage tasks.
 159  *
 160  * @exception see email-errors.h
 161  * @see         email_mailbox_t, email_mailbox_type_e
 162  * @remarks N/A
 163  */
 164 EXPORT_API int email_rename_mailbox(int input_mailbox_id, char *input_mailbox_name, char *input_mailbox_alias, int input_on_server, int *output_handle);
 165
 166 /**
 167  * @fn int email_delete_mailbox(int input_mailbox_id, int input_on_server, int *output_handle)
 168  * @brief       Delete a mailbox or mailbox.This function deletes the existing mailbox for specified account based on the option on_server.
 169  *              If the on_server is true then it deletes mailbox from server as well as locally.
 170  *
 171  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 172  * @param[in] input_mailbox_id  Specifies the id of target mailbox .
 173  * @param[in] input_on_server   Specifies the deleting mailbox on server.
 174  * @param[out] output_handle    Specifies the sending handle.
 175  * @exception   see email-errors.h
 176  * @see         email_mailbox_t
 177  * @remarks N/A
 178  */
 179 EXPORT_API int email_delete_mailbox(int input_mailbox_id, int input_on_server, int *output_handle);
 180
 181 EXPORT_API int email_delete_mailbox_ex(int input_account_id, int *input_mailbox_id_array, int input_mailbox_id_count, int input_on_server, int *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  * @fn int email_set_local_mailbox(int input_mailbox_id, int input_is_local_mailbox)
 199  * @brief       Change the attribute 'local' of email_mailbox_t. This function is invoked when user wants to change the attribute 'local'.
 200  *
 201  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 202  * @param[in] input_mailbox_id                  Specifies the id of the mailbox.
 203  * @param[in] input_is_local_mailbox    Specifies the value of the attribute 'local' of email_mailbox_t.
 204  * @exception see email-errors.h
 205  * @see         none
 206  * @remarks N/A
 207  */
 208 EXPORT_API int email_set_local_mailbox(int input_mailbox_id, int input_is_local_mailbox);
 209
 210 /**
 211  * @fn email_get_mailbox_list(int account_id, int mailbox_sync_type, email_mailbox_t** mailbox_list, int* count)
 212  * @brief       Get all mailboxes from account.
 213  *
 214  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 215  * @param[in] account_id                Specifies the account ID.
 216  * @param[in] mailbox_sync_type         Specifies the sync type.
 217  * @param[out] mailbox_list     Specifies the pointer of mailbox structure pointer.(possibly NULL)
 218  * @param[out] count                    The mailbox count is saved here.(possibly 0)
 219  * @exception           none
 220  * @see         email_mailbox_t
 221
 222  * @code
 223  *      #include "email-api-mailbox.h"
 224  *      bool
 225  *      _api_sample_get_mailbox_list()
 226  *      {
 227  *              int account_id =0,count = 0;
 228  *              int mailbox_sync_type;
 229  *              int error_code = EMAIL_ERROR_NONE;
 230  *              email_mailbox_t *mailbox_list=NULL;
 231  *
 232  *              printf("\n > Enter account id: ");
 233  *              scanf("%d", &account_id);
 234  *              printf("\n > Enter mailbox_sync_type: ");
 235  *              scanf("%d", &mailbox_sync_type);
 236  *
 237  *              if((EMAIL_ERROR_NONE != email_get_mailbox_list(account_id, mailbox_sync_type, &mailbox_list, &count)))
 238  *              {
 239  *                      printf(" Error\n");
 240  *              }
 241  *              else
 242  *              {
 243  *                      printf("Success\n");
 244  *                      email_free_mailbox(&mailbox_list,count);
 245  *              }
 246  *      }
 247  * @endcode
 248  * @remarks N/A
 249  */
 250 EXPORT_API int email_get_mailbox_list(int account_id, int mailbox_sync_type, email_mailbox_t** mailbox_list, int* count);
 251
 252 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);
 253
 254 /**
 255  * @fn email_get_mailbox_by_mailbox_type(int account_id, email_mailbox_type_e mailbox_type,  email_mailbox_t** mailbox)
 256  * @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.
 257  *
 258  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 259  * @param[in] account_id                Specifies the account ID.
 260  * @param[in] mailbox_type              Specifies the mailbox type.
 261  * @param[out] mailbox          Specifies the pointer of mailbox structure pointer.(possibly NULL)
 262  * @exception none
 263  * @see         email_mailbox_t
 264  * @remarks N/A
 265  */
 266 EXPORT_API int email_get_mailbox_by_mailbox_type(int account_id, email_mailbox_type_e mailbox_type,  email_mailbox_t** mailbox);
 267
 268 /**
 269  * @fn email_get_mailbox_by_mailbox_id(int input_mailbox_id, email_mailbox_t** output_mailbox)
 270  * @brief       Get mailbox by mailbox_id. This function is invoked when user wants to know the mailbox information by mailbox id.
 271  *
 272  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 273  * @param[in]  input_mailbox_id Specifies the mailbox id.
 274  * @param[out] output_mailbox   Specifies the pointer of mailbox structure pointer.(possibly NULL)
 275  * @exception none
 276  * @see         email_mailbox_t
 277  * @remarks N/A
 278  */
 279 EXPORT_API int email_get_mailbox_by_mailbox_id(int input_mailbox_id, email_mailbox_t** output_mailbox);
 280
 281 /**
 282  * @fn email_set_mail_slot_size(int input_account_id, int input_mailbox_id, int input_new_slot_size)
 283  * @brief       Set mail slot size.This function is invoked when user wants to set the size of mail slot.
 284  *
 285  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 286  * @param[in] input_account_id          Specifies the account ID.
 287  * @param[in] input_mailbox_id          Specifies the mailbox id.
 288  * @param[in] input_new_slot_size       Specifies the mail slot size.
 289  * @exception none
 290  * @see         email_mailbox_t
 291  * @remarks N/A
 292  */
 293 EXPORT_API int email_set_mail_slot_size(int input_account_id, int input_mailbox_id, int input_new_slot_size);
 294
 295 /**
 296  * @fn email_stamp_sync_time_of_mailbox(int input_mailbox_id)
 297  * @brief       Stamp sync time of mailbox. This function is invoked when user wants to set the sync time of the mailbox.
 298  *
 299  * @return This function returns EMAIL_ERROR_NONE on success or error code(refer to EMAIL_ERROR_XXX) on failure.
 300  * @param[in] input_mailbox_id          Specifies the mailbox id.
 301  * @exception none
 302  * @see         email_mailbox_t
 303  * @remarks N/A
 304  */
 305 EXPORT_API int email_stamp_sync_time_of_mailbox(int input_mailbox_id);
 306
 307
 308 /**
 309  * @fn email_free_mailbox(email_mailbox_t** mailbox_list, int count)
 310  * @brief       Free allocated memory for mailbox information.
 311  *
 312  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 313  * @param[in] mailbox_list      Specifies the pointer for searching mailbox structure pointer.
 314  * @param[in] count                     Specifies the count of mailboxes.
 315  * @exception           none
 316  * @see                 email_mailbox_t
 317
 318  * @code
 319  *      #include "email-api-mailbox.h"
 320  *      bool
 321  *      _api_sample_free_mailbox_info()
 322  *      {
 323  *              email_mailbox_t *mailbox;
 324  *
 325  *              //fill the mailbox structure
 326  *              //count - number of mailbox structure user want to free
 327  *               if(EMAIL_ERROR_NONE == email_free_mailbox(&mailbox,count))
 328  *                      //success
 329  *               else
 330  *                      //failure
 331  *
 332  *      }
 333  * @endcode
 334  * @remarks N/A
 335  */
 336
 337 EXPORT_API int email_free_mailbox(email_mailbox_t** mailbox_list, int count);
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif /* __cplusplus */
 342
 343 /**
 344 * @} @}
 345 */
 346
 347 #endif /* __EMAIL_API_MAILBOX_H__ */
 348
 349