MAPI/include/Emf_Mapi_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 __EMF_MAPI_FOLDER_H__   /* mailbox */
  24 #define __EMF_MAPI_FOLDER_H__
  25
  26 #include "emf-types.h"
  27
  28 /**
  29 * @defgroup EMAIL_FRAMEWORK Email Service
  30 * @{
  31 */
  32
  33
  34 /**
  35 * @ingroup EMAIL_FRAMEWORK
  36 * @defgroup EMAIL_MAPI_FOLDER Email mailbox(Mailbox) API
  37 * @{
  38 */
  39
  40 /**
  41  *
  42  * This file contains the data structures and interfaces needed for application,
  43  * to interact with Email Engine.
  44  * @file                Emf_Mapi_Folder.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 [mailbox] provided by
  49  *                      Email Engine .
  50  * @{
  51  * @code
  52  *
  53  *      #include "emf_mapi_folder.h"
  54  *
  55  *      bool
  56  *      other_app_invoke_uniform_api_sample(int *error_code)
  57  *      {
  58  *              emf_mailbox_t mbox;
  59  *              emf_mailbox_t *new_mailbox =NULL;
  60  *              emf_mailbox_t *mailbox_list = NULL;
  61  *              int count = 0;
  62  *              int mailbox_type;
  63  *              unsigned handle = 0;
  64  *              char *pMaiboxName;
  65  *              char *pParentMailbox;
  66  *
  67  *              memset(&mbox,0x00,sizeof(emf_mailbox_t));
  68  *              mbox.name = strdup("test");
  69  *              mbox.alias = strdup("Personal");
  70  *              mbox.account_id = 1;
  71  *              printf("Enter local_yn(1/0)");
  72  *              scanf("%d",&local_yn);
  73  *              mbox.local=local_yn;
  74  *              mbox.mailbox_type = 7;
  75  *
  76  *              //create new mailbox
  77  *
  78  *              if(EMF_ERR_NONE != email_add_mailbox(&mbox,local_yn,&handle))
  79  *                      printf("email_add_mailbox failed\n");
  80  *              else
  81  *                      printf("email_add_mailbox success");
  82  *
  83  *              //update mailbox
  84  *             new_mailbox = malloc(sizeof(emf_mailbox_t));
  85  *             memset(new_mailbox,0x00,sizeof(emf_mailbox_t));
  86  *
  87  *             new_mailbox->name = strdup("PersonalUse");
  88  *
  89  *             if(EMF_ERROR_NONE != email_update_mailbox(&mbox,new_mailbox))
  90  *                      printf("email_update_mailbox failed\n");
  91  *             else
  92  *                      printf("email_update_mailbox success\n");
  93  *              //delete mailbox
  94  *
  95  *              if(EMF_ERROR_NONE != email_delete_mailbox(mbox,local_yn,&handle))
  96  *                      printf("email_delete_mailbox failed\n");
  97  *              else
  98  *                      printf("email_delete_mailbox success\n");
  99  *
 100  *              //free mailbox
 101  *              email_free_mailbox("new_mailbox,1");
 102  *
 103  *              //Get mailbox list
 104  *              if(EMF_ERROR_NONE != email_get_mailbox_list(account_id,local_yn,&mailbox_list,&count))
 105  *                      //failure
 106  *              else
 107  *                      //success
 108  *
 109  *              //Get mailbox by name
 110  *              pMailboxName = strdup("test");
 111  *              if(EMF_ERROR_NONE != email_get_mailbox_by_name(account_id,pMailboxName,&mailbox_list))
 112  *                      //failure
 113  *              else
 114  *                      //success
 115  *
 116  *              //Get child mailbox list
 117  *              pParentMailbox = strdup("test");
 118  *              if(EMF_ERROR_NONE != email_get_child_mailbox_list(account_id, paerent_mailbox,&mailbox_list,&count))
 119  *                      //failure
 120  *              else
 121  *                      //success
 122  *
 123  *              //Get mailbox by mailbox_type
 124  *              printf("Enter mailbox_type\n");
 125  *              scanf("%d",&mailbox_type);
 126  *              if(EMF_ERROR_NONE != email_get_mailbox_by_mailbox_type(account_id,mailbox_type,&mailbox_list))
 127  *                      //failure
 128  *              else
 129  *                      //success
 130  *
 131  *      }
 132  *
 133  * @endcode
 134  * @}
 135  */
 136
 137
 138
 139 #ifdef __cplusplus
 140 extern "C"
 141 {
 142 #endif /* __cplusplus */
 143
 144
 145 /**
 146
 147  * @open
 148  * @fn EXPORT_API int email_add_mailbox(emf_mailbox_t* new_mailbox, int on_server, unsigned* handle)
 149  * @brief       Create a new mailbox or mailbox.This function is invoked when user wants to create a new mailbox for the specified account.
 150  *              If On_server is true then it will create the mailbox on server as well as in local also.
 151  *
 152  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 153  * @param[in] new_mailbox       Specifies the pointer of creating mailbox information.
 154 *  @param[in] on_server         Specifies the creating mailbox information on server.
 155  * @param[out] handle           Specifies the sending handle.
 156  * @exception   none
 157  * @see         emf_mailbox_t
 158   * @remarks N/A
 159  */
 160 EXPORT_API int email_add_mailbox(emf_mailbox_t* new_mailbox, int on_server, unsigned* handle);
 161
 162
 163 /**
 164
 165  * @open
 166  * @fn EXPORT_API int email_delete_mailbox(emf_mailbox_t* mailbox, int on_server,  unsigned* handle)
 167  * @brief       Delete a mailbox or mailbox.This function deletes the existing mailbox for specified account based on the option on_server.
 168  *              If the on_server is true then it deletes mailbox from server as well as locally.
 169  *
 170  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 171  * @param[in] mailbox   Specifies the pointer of deleting mailbox information.
 172  * @param[in] on_server         Specifies the creating mailbox information on server.
 173  * @param[out] handle           Specifies the sending handle.
 174  * @exception   #EMF_ERROR_INVALID_PARAM        -Invaid argument
 175  * @see         emf_mailbox_t
 176  * @remarks N/A
 177  */
 178 EXPORT_API int email_delete_mailbox(emf_mailbox_t* mailbox, int on_server,  unsigned* handle);
 179
 180
 181 /**
 182
 183  * @fn EXPORT_API int email_update_mailbox(emf_mailbox_t* old_mailbox, emf_mailbox_t* new_mailbox)
 184  * @brief       Change mailbox or mailbox information.This function is invoked when user wants to change the existing mail box information.
 185  *                      This supports ONLY updating mailbox_type in local db. This can be used to match a specific mail box and a specific mailbox_type.
 186  *
 187  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 188  * @param[in] old_mailbox       Specifies the information of previous mailbox. <br>mandatory field : account_id, name
 189  * @param[in] new_mailbox       Specifies the information of new mailbox. <br
 190  * @exception #EMF_ERROR_INVALID_PARAM          -Invaid argument
 191  * @see         emf_mailbox_t, emf_mailbox_type_e
 192   * @remarks N/A
 193  */
 194 EXPORT_API int email_update_mailbox(emf_mailbox_t* old_mailbox, emf_mailbox_t* new_mailbox);
 195
 196 EXPORT_API int email_get_sync_mailbox_list(int account_id, emf_mailbox_t** mailbox_list, int* count) DEPRECATED;
 197
 198
 199 /**
 200
 201  * @open
 202  * @fn email_get_mailbox_list(int account_id, int mailbox_sync_type, emf_mailbox_t** mailbox_list, int* count)
 203  * @brief       Get all mailboxes from account.
 204  *
 205  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 206  * @param[in] account_id                Specifies the account ID.
 207  * @param[in] mailbox_sync_type         Specifies the sync type.
 208  * @param[out] mailbox_list     Specifies the pointer of mailbox structure pointer.(possibly NULL)
 209  * @param[out] count                    The mailbox count is saved here.(possibly 0)
 210  * @exception           none
 211  * @see         emf_mailbox_t
 212
 213  * @code
 214  *      #include "Emf_Mapi_Message.h"
 215  *      bool
 216  *      _api_sample_get_mailbox_list()
 217  *      {
 218  *              int account_id =0,count = 0;
 219  *              int mailbox_sync_type;
 220  *              int error_code = EMF_ERROR_NONE;
 221  *              emf_mailbox_t *mailbox_list=NULL;
 222  *
 223  *              printf("\n > Enter account id: ");
 224  *              scanf("%d", &account_id);
 225  *              printf("\n > Enter mailbox_sync_type: ");
 226  *              scanf("%d", &mailbox_sync_type);
 227  *
 228  *              if((EMF_ERROR_NONE != email_get_mailbox_list(account_id, mailbox_sync_type, &mailbox_list, &count)))
 229  *              {
 230  *                      printf(" Error\n");
 231  *              }
 232  *              else
 233  *              {
 234  *                      printf("Success\n");
 235  *                      email_free_mailbox(&mailbox_list,count);
 236  *              }
 237  *      }
 238  * @endcode
 239  * @remarks N/A
 240  */
 241 EXPORT_API int  email_get_mailbox_list(int account_id, int mailbox_sync_type, emf_mailbox_t** mailbox_list, int* count);
 242
 243 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);
 244
 245 /**
 246
 247  * @open
 248  * @fn EXPORT_API int email_get_mailbox_by_name(int account_id, const char *pMailboxName, emf_mailbox_t **pMailbox);
 249  * @brief       Get the mailbox information by name.This function gets the mailbox by given mailbox name for a specified account.
 250  *
 251  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 252  * @param[in] account_id                Specifies the information of account Id.
 253  * @param[in] pMailboxName              Specifies the mailbox name.
 254  * @param[out] pMailbox                 Specifies the information of mailbox
 255  * @exception none
 256  * @see         emf_mailbox_t
 257  * @remarks N/A
 258  */
 259
 260 EXPORT_API int email_get_mailbox_by_name(int account_id, const char *pMailboxName, emf_mailbox_t **pMailbox);
 261
 262 // Belows are for A Project
 263
 264 /**
 265
 266  * @open
 267  * @fn email_get_child_mailbox_list(int account_id, char *parent_mailbox,  emf_mailbox_t** mailbox_list, int* count)
 268  * @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.
 269  *
 270  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 271  * @param[in] account_id                Specifies the account ID.
 272  * @param[in] parent_mailbox            Specifies the parent mailbox
 273  * @param[out] mailbox_list            Specifies the pointer of mailbox structure pointer.(possibly NULL)
 274  * @param[out] count                    The mailbox count
 275  * @exception  #EMF_ERROR_INVALID_PARAM         -Invalid argument
 276  * @see         emf_mailbox_t
 277  * @remarks N/A
 278  * @return This function returns true on success or false on failure.
 279  */
 280 EXPORT_API int email_get_child_mailbox_list(int account_id, const char *parent_mailbox,  emf_mailbox_t** mailbox_list, int* count);
 281
 282
 283 /**
 284  * @open
 285  * @fn email_get_mailbox_by_mailbox_type(int account_id, emf_mailbox_type_e mailbox_type,  emf_mailbox_t** mailbox)
 286  * @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.
 287  *
 288  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 289  * @param[in] account_id                Specifies the account ID.
 290  * @param[in] mailbox_type              Specifies the mailbox type.
 291  * @param[out] mailbox          Specifies the pointer of mailbox structure pointer.(possibly NULL)
 292  * @exception none
 293  * @see         emf_mailbox_t
 294  * @remarks N/A
 295  */
 296 EXPORT_API int email_get_mailbox_by_mailbox_type(int account_id, emf_mailbox_type_e mailbox_type,  emf_mailbox_t** mailbox);
 297
 298 /**
 299  * @open
 300  * @fn email_set_mail_slot_size(int account_id, char* mailbox_name, int new_slot_size, unsigned* handle)
 301  * @brief       Set mail slot size.This function is invoked when user wants to set the size of mail slot.
 302  *
 303  * @return This function returns EMF_ERROR_NONE on success or error code(refer to EMF_ERROR_XXX) on failure.
 304  * @param[in] account_id                Specifies the account ID.
 305  * @param[in] mailbox_name              Specifies the mailbox name.
 306  * @param[in] new_slot_size             Specifies the mail slot size.
 307  * @exception none
 308  * @see         emf_mailbox_t
 309  * @remarks N/A
 310  */
 311 EXPORT_API int email_set_mail_slot_size(int account_id, char* mailbox_name, int new_slot_size/*, unsigned* handle*/);
 312
 313
 314 #ifdef __cplusplus
 315 }
 316 #endif /* __cplusplus */
 317
 318 /**
 319 * @} @}
 320 */
 321
 322
 323
 324 #endif /* __EMF_MAPI_FOLDER_H__ */
 325
 326