src/lib/quickmail.h

   1 /*! \file      quickmail.h
   2  *  \brief     header file for libquickmail
   3  *  \author    Brecht Sanders
   4  *  \date      2012-2013
   5  *  \copyright GPL
   6  */
   7 /*
   8     This file is part of libquickmail.
   9
  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.
  14
  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.
  19
  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/>.
  22 */
  23
  24 #ifndef __INCLUDED_QUICKMAIL_H
  25 #define __INCLUDED_QUICKMAIL_H
  26
  27 #include <stdio.h>
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 /*! \brief quickmail object type */
  34 typedef struct email_info_struct* quickmail;
  35
  36
  37
  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()
  43  */
  44 typedef void* (*quickmail_attachment_open_fn)(void* filedata);
  45
  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()
  53  */
  54 typedef size_t (*quickmail_attachment_read_fn)(void* handle, void* buf, size_t len);
  55
  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()
  60  */
  61 typedef void (*quickmail_attachment_close_fn)(void* handle);
  62
  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()
  67  */
  68 typedef void (*quickmail_attachment_free_filedata_fn)(void* filedata);
  69
  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()
  80  */
  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);
  82
  83
  84
  85 /*! \brief get version quickmail library
  86  * \return library version
  87  */
  88 const char* quickmail_get_version ();
  89
  90 /*! \brief initialize quickmail library
  91  * \return zero on success
  92  */
  93 int quickmail_initialize ();
  94
  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
  99  */
 100 quickmail quickmail_create (const char* from, const char* subject);
 101
 102 /*! \brief clean up a quickmail object
 103  * \param  mailobj     quickmail object
 104  */
 105 void quickmail_destroy (quickmail mailobj);
 106
 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
 110  */
 111 void quickmail_set_from (quickmail mailobj, const char* from);
 112
 113 /*! \brief get the sender (from) e-mail address of a quickmail object
 114  * \param  mailobj     quickmail object
 115  * \return sender e-mail address
 116  */
 117 const char* quickmail_get_from (quickmail mailobj);
 118
 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
 122  */
 123 void quickmail_add_to (quickmail mailobj, const char* email);
 124
 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
 128  */
 129 void quickmail_add_cc (quickmail mailobj, const char* email);
 130
 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
 134  */
 135 void quickmail_add_bcc (quickmail mailobj, const char* email);
 136
 137 /*! \brief set the subject of a quickmail object
 138  * \param  mailobj     quickmail object
 139  * \param  subject     e-mail subject
 140  */
 141 void quickmail_set_subject (quickmail mailobj, const char* subject);
 142
 143 /*! \brief set the subject of a quickmail object
 144  * \param  mailobj     quickmail object
 145  * \return e-mail subject
 146  */
 147 const char* quickmail_get_subject (quickmail mailobj);
 148
 149 /*! \brief add an e-mail header to a quickmail object
 150  * \param  mailobj     quickmail object
 151  * \param  headerline  header line to add
 152  */
 153 void quickmail_add_header (quickmail mailobj, const char* headerline);
 154
 155 /*! \brief set the body of a quickmail object
 156  * \param  mailobj     quickmail object
 157  * \param  body        e-mail body
 158  */
 159 void quickmail_set_body (quickmail mailobj, const char* body);
 160
 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)
 165  */
 166 char* quickmail_get_body (quickmail mailobj);
 167
 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
 172  */
 173 void quickmail_add_body_file (quickmail mailobj, const char* mimetype, const char* path);
 174
 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
 181  */
 182 void quickmail_add_body_memory (quickmail mailobj, const char* mimetype, char* data, size_t datalen, int mustfree);
 183
 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)
 192  */
 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);
 194
 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
 199  */
 200 int quickmail_remove_body (quickmail mailobj, const char* mimetype);
 201
 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
 207  */
 208 void quickmail_list_bodies (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);
 209
 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)
 214  */
 215 void quickmail_add_attachment_file (quickmail mailobj, const char* path, const char* mimetype);
 216
 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
 224  */
 225 void quickmail_add_attachment_memory (quickmail mailobj, const char* filename, const char* mimetype, char* data, size_t datalen, int mustfree);
 226
 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)
 236  */
 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);
 238
 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
 243  */
 244 int quickmail_remove_attachment (quickmail mailobj, const char* filename);
 245
 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
 251  */
 252 void quickmail_list_attachments (quickmail mailobj, quickmail_list_attachment_callback_fn callback, void* callbackdata);
 253
 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)
 257  */
 258 void quickmail_set_debug_log (quickmail mailobj, FILE* filehandle);
 259
 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
 263  */
 264 void quickmail_fsave (quickmail mailobj, FILE* filehandle);
 265
 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
 272  */
 273 size_t quickmail_get_data (void* buffer, size_t size, size_t nmemb, void* mailobj);
 274
 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
 282  */
 283 const char* quickmail_send (quickmail mailobj, const char* smtpserver, unsigned int smtpport, const char* username, const char* password);
 284
 285 #ifdef __cplusplus
 286 }
 287 #endif
 288
 289 #endif //__INCLUDED_QUICKMAIL_H