2 * \brief header file for libquickmail
3 * \author Brecht Sanders
8 This file is part of libquickmail.
10 libquickmail is free software: you can redistribute it and/or modify
11 it under the terms of the GNU General Public License as published by
12 the Free Software Foundation, either version 3 of the License, or
13 (at your option) any later version.
15 libquickmail is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License for more details.
20 You should have received a copy of the GNU General Public License
21 along with libquickmail. If not, see <http://www.gnu.org/licenses/>.
24 #ifndef __INCLUDED_QUICKMAIL_H
25 #define __INCLUDED_QUICKMAIL_H
33 /*! \brief quickmail object type */
34 typedef struct email_info_struct* quickmail;
38 /*! \brief type of pointer to function for opening attachment data
39 * \param filedata custom data as passed to quickmail_add_body_custom/quickmail_add_attachment_custom
40 * \return data structure to be used in calls to quickmail_attachment_read_fn and quickmail_attachment_close_fn functions
41 * \sa quickmail_add_body_custom()
42 * \sa quickmail_add_attachment_custom()
44 typedef void* (*quickmail_attachment_open_fn)(void* filedata);
46 /*! \brief type of pointer to function for reading attachment data
47 * \param handle data structure obtained via the corresponding quickmail_attachment_open_fn function
48 * \param buf buffer for receiving data
49 * \param len size in bytes of buffer for receiving data
50 * \return number of bytes read (zero on end of file)
51 * \sa quickmail_add_body_custom()
52 * \sa quickmail_add_attachment_custom()
54 typedef size_t (*quickmail_attachment_read_fn)(void* handle, void* buf, size_t len);
56 /*! \brief type of pointer to function for closing attachment data
57 * \param handle data structure obtained via the corresponding quickmail_attachment_open_fn function
58 * \sa quickmail_add_body_custom()
59 * \sa quickmail_add_attachment_custom()
61 typedef void (*quickmail_attachment_close_fn)(void* handle);
63 /*! \brief type of pointer to function for cleaning up custom data in quickmail_destroy
64 * \param filedata custom data as passed to quickmail_add_body_custom/quickmail_add_attachment_custom
65 * \sa quickmail_add_body_custom()
66 * \sa quickmail_add_attachment_custom()
68 typedef void (*quickmail_attachment_free_filedata_fn)(void* filedata);
70 /*! \brief type of pointer to function for cleaning up custom data in quickmail_destroy
71 * \param mailobj quickmail object
72 * \param filename attachment filename (same value as mimetype for mail body)
73 * \param mimetype MIME type
74 * \param attachment_data_open function for opening attachment data
75 * \param attachment_data_read function for reading attachment data
76 * \param attachment_data_close function for closing attachment data (optional, free() will be used if NULL)
77 * \param callbackdata custom data passed to quickmail_list_attachments
78 * \sa quickmail_list_bodies()
79 * \sa quickmail_list_attachments()
81 typedef void (*quickmail_list_attachment_callback_fn)(quickmail mailobj, const char* filename, const char* mimetype, quickmail_attachment_open_fn email_info_attachment_open, quickmail_attachment_read_fn email_info_attachment_read, quickmail_attachment_close_fn email_info_attachment_close, void* callbackdata);
85 /*! \brief get version quickmail library
86 * \return library version
88 const char* quickmail_get_version ();
90 /*! \brief initialize quickmail library
91 * \return zero on success
93 int quickmail_initialize ();
95 /*! \brief create a new quickmail object
96 * \param from sender e-mail address
97 * \param subject e-mail subject
98 * \return quickmail object or NULL on error
100 quickmail quickmail_create (const char* from, const char* subject);
102 /*! \brief clean up a quickmail object
103 * \param mailobj quickmail object
105 void quickmail_destroy (quickmail mailobj);
107 /*! \brief set the sender (from) e-mail address of a quickmail object
108 * \param mailobj quickmail object
109 * \param from sender e-mail address
111 void quickmail_set_from (quickmail mailobj, const char* from);
113 /*! \brief get the sender (from) e-mail address of a quickmail object
114 * \param mailobj quickmail object
115 * \return sender e-mail address
117 const char* quickmail_get_from (quickmail mailobj);
119 /*! \brief add a recipient (to) e-mail address to a quickmail object
120 * \param mailobj quickmail object
121 * \param e-mail recipient e-mail address
123 void quickmail_add_to (quickmail mailobj, const char* email);
125 /*! \brief add a carbon copy recipient (cc) e-mail address to a quickmail object
126 * \param mailobj quickmail object
127 * \param e-mail recipient e-mail address
129 void quickmail_add_cc (quickmail mailobj, const char* email);
131 /*! \brief add a blind carbon copy recipient (bcc) e-mail address to a quickmail object
132 * \param mailobj quickmail object
133 * \param e-mail recipient e-mail address
135 void quickmail_add_bcc (quickmail mailobj, const char* email);
137 /*! \brief set the subject of a quickmail object
138 * \param mailobj quickmail object
139 * \param subject e-mail subject
141 void quickmail_set_subject (quickmail mailobj, const char* subject);
143 /*! \brief set the subject of a quickmail object
144 * \param mailobj quickmail object
145 * \return e-mail subject
147 const char* quickmail_get_subject (quickmail mailobj);
149 /*! \brief add an e-mail header to a quickmail object
150 * \param mailobj quickmail object
151 * \param headerline header line to add
153 void quickmail_add_header (quickmail mailobj, const char* headerline);
155 /*! \brief set the body of a quickmail object
156 * \param mailobj quickmail object
157 * \param body e-mail body
159 void quickmail_set_body (quickmail mailobj, const char* body);
161 /*! \brief set the body of a quickmail object
162 * any existing bodies will be removed and a single plain text body will be added
163 * \param mailobj quickmail object
164 * \return e-mail body or NULL on error (caller must free result)
166 char* quickmail_get_body (quickmail mailobj);
168 /*! \brief add a body file to a quickmail object (deprecated)
169 * \param mailobj quickmail object
170 * \param mimetype MIME type (text/plain will be used if set to NULL)
171 * \param path path of file with body data
173 void quickmail_add_body_file (quickmail mailobj, const char* mimetype, const char* path);
175 /*! \brief add a body from memory to a quickmail object
176 * \param mailobj quickmail object
177 * \param mimetype MIME type (text/plain will be used if set to NULL)
178 * \param data body content
179 * \param datalen size of data in bytes
180 * \param mustfree non-zero if data must be freed by quickmail_destroy
182 void quickmail_add_body_memory (quickmail mailobj, const char* mimetype, char* data, size_t datalen, int mustfree);
184 /*! \brief add a body with custom read functions to a quickmail object
185 * \param mailobj quickmail object
186 * \param mimetype MIME type (text/plain will be used if set to NULL)
187 * \param data custom data passed to attachment_data_open and attachment_data_filedata_free functions
188 * \param attachment_data_open function for opening attachment data
189 * \param attachment_data_read function for reading attachment data
190 * \param attachment_data_close function for closing attachment data (optional, free() will be used if NULL)
191 * \param attachment_data_filedata_free function for cleaning up custom data in quickmail_destroy (optional, free() will be used if NULL)
193 void quickmail_add_body_custom (quickmail mailobj, const char* mimetype, char* data, quickmail_attachment_open_fn attachment_data_open, quickmail_attachment_read_fn attachment_data_read, quickmail_attachment_close_fn attachment_data_close, quickmail_attachment_free_filedata_fn attachment_data_filedata_free);
195 /*! \brief remove body from quickmail object
196 * \param mailobj quickmail object
197 * \param mimetype MIME type (text/plain will be used if set to NULL)
198 * \return zero on success
200 int quickmail_remove_body (quickmail mailobj, const char* mimetype);
202 /*! \brief list bodies by calling a callback function for each body
203 * \param mailobj quickmail object
204 * \param callback function to call for each attachment
205 * \param callbackdata custom data to pass to the callback function
206 * \sa quickmail_list_attachment_callback_fn
208 void quickmail_list_bodies (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);
210 /*! \brief add a file attachment to a quickmail object
211 * \param mailobj quickmail object
212 * \param path path of file to attach
213 * \param mimetype MIME type of file to attach (application/octet-stream will be used if set to NULL)
215 void quickmail_add_attachment_file (quickmail mailobj, const char* path, const char* mimetype);
217 /*! \brief add an attachment from memory to a quickmail object
218 * \param mailobj quickmail object
219 * \param filename name of file to attach (must not include full path)
220 * \param mimetype MIME type of file to attach (set to NULL for default binary file)
221 * \param data data content
222 * \param datalen size of data in bytes
223 * \param mustfree non-zero if data must be freed by quickmail_destroy
225 void quickmail_add_attachment_memory (quickmail mailobj, const char* filename, const char* mimetype, char* data, size_t datalen, int mustfree);
227 /*! \brief add an attachment with custom read functions to a quickmail object
228 * \param mailobj quickmail object
229 * \param filename name of file to attach (must not include full path)
230 * \param mimetype MIME type of file to attach (set to NULL for default binary file)
231 * \param data custom data passed to attachment_data_open and attachment_data_filedata_free functions
232 * \param attachment_data_open function for opening attachment data
233 * \param attachment_data_read function for reading attachment data
234 * \param attachment_data_close function for closing attachment data (optional, free() will be used if NULL)
235 * \param attachment_data_filedata_free function for cleaning up custom data in quickmail_destroy (optional, free() will be used if NULL)
237 void quickmail_add_attachment_custom (quickmail mailobj, const char* filename, const char* mimetype, char* data, quickmail_attachment_open_fn attachment_data_open, quickmail_attachment_read_fn attachment_data_read, quickmail_attachment_close_fn attachment_data_close, quickmail_attachment_free_filedata_fn attachment_data_filedata_free);
239 /*! \brief remove attachment from quickmail object
240 * \param mailobj quickmail object
241 * \param filename name of file to attach (must not include full path)
242 * \return zero on success
244 int quickmail_remove_attachment (quickmail mailobj, const char* filename);
246 /*! \brief list attachments by calling a callback function for each attachment
247 * \param mailobj quickmail object
248 * \param callback function to call for each attachment
249 * \param callbackdata custom data to pass to the callback function
250 * \sa quickmail_list_attachment_callback_fn
252 void quickmail_list_attachments (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);
254 /*! \brief set the debug logging destination of a quickmail object
255 * \param mailobj quickmail object
256 * \param filehandle file handle of logging destination (or NULL for no logging)
258 void quickmail_set_debug_log (quickmail mailobj, FILE* filehandle);
260 /*! \brief save the generated e-mail to a file
261 * \param mailobj quickmail object
262 * \param filehandle file handle to write the e-mail contents to
264 void quickmail_fsave (quickmail mailobj, FILE* filehandle);
266 /*! \brief read data the next data from the e-mail contents (can be used as CURLOPT_READFUNCTION callback function)
267 * \param buffer buffer to copy data to (bust be able to hold size * nmemb bytes)
268 * \param size record size
269 * \param nmemb number of records to copy to \p buffer
270 * \param mailobj quickmail object
271 * \return number of bytes copied to \p buffer or 0 if at end
273 size_t quickmail_get_data (void* buffer, size_t size, size_t nmemb, void* mailobj);
275 /*! \brief send the e-mail via SMTP
276 * \param mailobj quickmail object
277 * \param smtpserver IP address or hostname of SMTP server
278 * \param smtpport SMTP port number (normally this is 25)
279 * \param username username to use for authentication (or NULL if not needed)
280 * \param password password to use for authentication (or NULL if not needed)
281 * \return NULL on success or error message on error
283 const char* quickmail_send (quickmail mailobj, const char* smtpserver, unsigned int smtpport, const char* username, const char* password);
289 #endif //__INCLUDED_QUICKMAIL_H