1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
/*
* Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
*
* Licensed under the Apache License, Version 2.0 (the License);
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an AS IS BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef __MESSAGING_EMAIL_H__
#define __MESSAGING_EMAIL_H__
/**
* @addtogroup CAPI_MESSAGING_EMAIL_MODULE
* @{
*/
/**
* @file email.h
* @ingroup CAPI_MESSAGING_FRAMEWORK
* @brief Messaging API file, support for sending email messages.
*/
#include <stdlib.h>
#include <stdio.h>
#include <email_types.h>
#include <email_error.h>
#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */
/**
* @brief Creates an email message handle for sending an email message.
*
* @remarks a email must be released with email_destroy_message() by you.
*
* @param[out] email A handle to the email message
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
* @retval #EMAIL_ERROR_ACCOUNT_NOT_FOUND Email account not found
*
* @see email_destroy_message()
*/
int email_create_message(email_h *email);
/**
* @brief Destroys the email message handle and releases all its resources.
*
* @param[in] email The handle to the email message
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #EMAIL_ERROR_OPERATION_FAILED Operation failed
*
* @see email_create_message()
*/
int email_destroy_message(email_h email);
/**
* @brief Sets a subject of the email message.
*
* @param[in] email The handle to the email message
* @param[in] subject The subject of the email message
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
*
* @see email_create_message()
*/
int email_set_subject(email_h email, const char *subject);
/**
* @brief Populates a body of the email message.
* @details Email message body means the text data to be delivered.
*
* @param[in] email The handle to the email message
* @param[in] body The message body
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @retval # EMAIL_ERROR_OPERATION_FAILED Operation failed
* @pre An email message handle is created using #email_create_message().
* @see email_create_message()
*/
int email_set_body(email_h email, const char *body);
/**
* @brief Adds a recipient to the email message.
* @details The email API supports sending an email message to multiple recipients.
*
* @remarks Email address should be in standard format (as described in
* Internet standards RFC 5321 and RFC 5322).\n
*
* @param[in] email The handle to the email message
* @param[in] type The recipient type
* @param[in] address The recipient email address
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
*
* @see email_create_message()
* @see email_remove_all_recipients()
*/
int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
/**
* @brief Removes all recipients for the email message.
*
* @param[in] email The handle to the email message
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see email_add_recipient()
*/
int email_remove_all_recipients(email_h email);
/**
* @brief Adds a file as an attachment to the email message.
* @details It should be used to add a file to the attachment list
* of the email message.
*
* @remarks The maximum attachment file size is 10MB.
*
* @param[in] email The handle to the email message
* @param[in] filepath The absolute full path of the file to be attached
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
*
* @see email_remove_all_attachments()
*
*/
int email_add_attach(email_h email, const char *filepath);
/**
* @brief Clears all attachments of the email message.
*
* @param[in] email The handle to the email message
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see email_create_message()
* @see email_add_attach()
*/
int email_remove_all_attachments(email_h email);
/**
* @brief Sends the email message.
*
* @remarks In order to check whether sending a message succeeds, \n you should register email_message_sent_cb() using #email_set_message_sent_cb().
*
*
* @param[in] email The handle to the email message
* @param[in] save_to_sentbox Set to true to save the message in the sentbox, else false
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see email_create_message()
* @see email_set_message_sent_cb()
* @see email_add_recipient()
*/
int email_send_message(email_h email, bool save_to_sentbox);
/**
* @brief Called when the process of sending an email finishes.
* @details You can check whether sending an email succeeds using this function.
*
*
* @param[in] email The handle to the email message
* @param[in] result The result of email message sending\n
* #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
* @param[in] user_data The user data passed from the callback registration function
*
* @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
*
* @see email_send_message()
* @see email_set_message_sent_cb()
* @see email_unset_message_sent_cb()
*/
typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
/**
* @brief Registers a callback function to be invoked when an email message is sent.
* @details You will be notified when sending a message finishes and check whether it succeeds using this function.
*
* @param[in] email The handle to the email message
* @param[in] callback The callback function to register
* @param[in] user_data The user data to be passed to the callback function
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
* @post It will invoke email_message_sent_cb().
* @see email_message_sent_cb()
* @see email_unset_message_sent_cb()
* @see email_send_message()
*/
int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
/**
* @brief Unregisters the callback function.
*
* @param[in] email The handle to the email message
*
* @return 0 on success, otherwise a negative error value.
* @retval #EMAIL_ERROR_NONE Successful
* @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see email_message_sent_cb()
* @see email_set_message_sent_cb()
* @see email_send_message()
*/
int email_unset_message_sent_cb(email_h msg);
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* __MESSAGING_EMAIL_H__ */
|
