email-api/include/email-api-rule.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_RULE_H__
  24 #define __EMAIL_API_RULE_H__
  25
  26 #include "email-types.h"
  27
  28 /**
  29 * @defgroup EMAIL_SERVICE Email Service
  30 * @{
  31 */
  32
  33 /**
  34 * @ingroup EMAIL_SERVICE
  35 * @defgroup EMAIL_API_RULE Email Rule API
  36 * @{
  37 */
  38
  39  /**
  40  *
  41  * This file contains the data structures and interfaces needed for application,
  42  * to interact with email-service.
  43  * @file                email-api-rule.h
  44  * @author      Kyuho Jo <kyuho.jo@samsung.com>
  45  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>
  46  * @version     0.1
  47  * @brief               This file contains the data structures and interfaces of Rule related Functionality provided by
  48  *                      email-service .
  49  * @{
  50
  51  * @code
  52  *      #include "email-api-rule.h"
  53  *      bool
  54  *      other_app_invoke_uniform_api_sample(int* error_code)
  55  *      {
  56  *              int err = EMAIL_ERROR_NONE;
  57  *              email_rule_t*  rule = NULL;
  58  *              int filter_id = 1;
  59  *              int count = 0;
  60  *
  61  *              // Get a information of filtering
  62  *              printf("Enter filter Id:\n");
  63  *              scanf("%d",&filter_id);
  64  *
  65  *              if(EMAIL_ERROR_NONE == email_get_rule (filter_id,&rule))
  66  *                      //success
  67  *              else
  68  *                      //failure
  69  *
  70  *              // Get all filterings
  71  *              if(EMAIL_ERROR_NONE == email_get_rule_list(&rule,&count))
  72  *                      //success
  73  *              else
  74  *                      //failure
  75  *
  76  *
  77  *              // Add a filter information
  78  *              if(EMAIL_ERROR_NONE == email_add_rule (rule))
  79  *                      //success
  80  *              else
  81  *                      //failure
  82  *              err = email_free_rule (&rule,1);
  83  *
  84  *              // Change a filter information
  85  *              if(EMAIL_ERROR_NONE == email_update_rule (filter_id,rule))
  86  *                      //success
  87  *              else
  88  *                      //failure
  89  *              err = email_free_rule (&rule,1);
  90  *
  91  *              // Delete a filter information
  92  *              printf("Enter filter Id:\n");
  93  *              scanf("%d",&filter_id);
  94  *
  95  *              if(EMAIL_ERROR_NONE == email_delete_rule (filter_id))
  96  *                      //success
  97  *              else
  98  *                      //failure
  99  *
 100  *              // Free allocated memory
 101  *              if(EMAIL_ERROR_NONE == email_free_rule (&rule,1))
 102  *                      //success
 103  *              else
 104  *                      //failure
 105  *
 106  *      }
 107  *
 108  * @endcode
 109  * @}
 110  */
 111
 112
 113
 114 #ifdef __cplusplus
 115 extern "C" {
 116 #endif /* __cplusplus */
 117
 118 /**
 119
 120
 121  * @fn email_get_rule(int filter_id, email_rule_t** filtering_set)
 122  * @brief       Get a information of filtering.
 123  *
 124  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure
 125  * @param[in] filter_id                 Specifies the filter ID.
 126  * @param[out] filtering_set    The returned information of filter are saved here.
 127  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 128  * @see         email_rule_t
 129  * @remarks N/A
 130  */
 131 EXPORT_API int email_get_rule(int filter_id, email_rule_t** filtering_set);
 132
 133 /**
 134
 135
 136  * @fn email_get_rule_list(email_rule_t** filtering_set, int* count)
 137  * @brief       Get all filterings.This function gives all the filter rules already set before by user.
 138  *              This will provide total number of filter rules available and information of all rules.
 139  *
 140  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure
 141  * @param[out] filtering_set            The returned filterings are saved here.(possibly NULL)
 142  * @param[out] count                            The count of returned filters is saved here.(possibly 0)
 143  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 144  * @see         email_rule_t
 145  * @remarks N/A
 146  */
 147 EXPORT_API int email_get_rule_list(email_rule_t** filtering_set, int* count);
 148
 149 /**
 150
 151
 152  * @fn email_add_rule(email_rule_t* filtering_set)
 153  * @brief       Add a filter information.This function is invoked if user wants to add a new filter rule.
 154  *
 155  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 156  * @param[in] filtering_set             Specifies the pointer of adding filter structure.
 157  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 158  * @see         email_rule_t
 159  * @remarks N/A
 160  */
 161 EXPORT_API int email_add_rule(email_rule_t* filtering_set);
 162
 163 /**
 164
 165
 166  * @fn email_update_rule(int filter_id, email_rule_t* new_set)
 167  * @brief       Change a filter information.This function will update the existing filter rule with new information.
 168  *
 169  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 170  * @param[in] filter_id Specifies the original filter ID.
 171  * @param[in] new_set   Specifies the information of new filter.
 172  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 173  * @see         email_rule_t
 174  * @remarks N/A
 175  */
 176 EXPORT_API int email_update_rule(int filter_id, email_rule_t* new_set);
 177
 178 /**
 179
 180  * @fn email_delete_rule(int filter_id)
 181  * @brief       Delete a filter information.This function will delete the exsting filter information by specified filter Id.
 182  *
 183  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure
 184  * @param[in] filter_id Specifies the filter ID.
 185  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 186  * @see         none
 187  * @remarks N/A
 188  */
 189 EXPORT_API int email_delete_rule(int filter_id);
 190
 191
 192
 193 /**
 194
 195  * @fn email_free_rule (email_rule_t** filtering_set, int count)
 196  * @brief       Free allocated memory.
 197  *
 198  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure
 199  * @param[in] filtering_set     Specifies the pointer of pointer of filter structure for memory free.
 200  * @param[in] count                     Specifies the count of filter.
 201  * @exception   EMAIL_ERROR_INVALID_PARAM       -Invalid argument
 202  * @see         email_rule_t
 203  * @remarks N/A
 204  */
 205 EXPORT_API int email_free_rule (email_rule_t** filtering_set, int count);
 206
 207 #ifdef __cplusplus
 208 }
 209 #endif /* __cplusplus */
 210
 211 /**
 212 * @} @}
 213 */
 214
 215
 216 #endif /* __EMAIL_API_RULE_H__ */