1 #ifndef CONNECT___NCBI_SENDMAIL__H 2 #define CONNECT___NCBI_SENDMAIL__H 3 4 /* $Id: ncbi_sendmail.h 565384 2018-06-11 17:56:27Z lavr $ 5 * =========================================================================== 6 * 7 * PUBLIC DOMAIN NOTICE 8 * National Center for Biotechnology Information 9 * 10 * This software/database is a "United States Government Work" under the 11 * terms of the United States Copyright Act. It was written as part of 12 * the author's official duties as a United States Government employee and 13 * thus cannot be copyrighted. This software/database is freely available 14 * to the public for use. The National Library of Medicine and the U.S. 15 * Government have not placed any restriction on its use or reproduction. 16 * 17 * Although all reasonable efforts have been taken to ensure the accuracy 18 * and reliability of the software and data, the NLM and the U.S. 19 * Government do not and cannot warrant the performance or results that 20 * may be obtained by using this software or data. The NLM and the U.S. 21 * Government disclaim all warranties, express or implied, including 22 * warranties of performance, merchantability or fitness for any particular 23 * purpose. 24 * 25 * Please cite the author in any work or product based on this material. 26 * 27 * =========================================================================== 28 * 29 * Author: Anton Lavrentiev 30 * 31 * File Description: 32 * @file ncbi_sendmail.h 33 * Send mail (in accordance with RFC821 [protocol] and RFC822 [headers]) 34 * 35 */ 36 37 #include <connect/ncbi_util.h> 38 39 40 /** @addtogroup Sendmail 41 * 42 * @{ 43 */ 44 45 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 51 /** Options apply to various fields of SSendMailInfo structure, below 52 * @sa SSendMailInfo 53 */ 54 enum ESendMailOption { 55 fSendMail_LogOn = eOn, /**< see: fSOCK_LogOn */ 56 fSendMail_LogOff = eOff, /**< fSOCK_LogDefault */ 57 fSendMail_NoMxHeader = (1 << 4), /**< Don't add standard mail header, 58 just use what user provided */ 59 fSendMail_Old822Headers = (1 << 6), /**< Form "Date:" and "From:" hdrs 60 (usually they are defaulted) */ 61 fSendMail_StripNonFQDNHost = (1 << 8), /**< Strip host part off the "from" 62 field if it does not look like 63 an FQDN (i.e. does not have at 64 least two domain name labels 65 separated by a dot); leave only 66 the username part */ 67 fSendMail_ExtendedErrInfo = (1 << 10) /**< Return extended error info that 68 must be free()'d by caller */ 69 }; 70 typedef unsigned short TSendMailOptions; /**< Bitwise OR of ESendMailOption*/ 71 72 73 /** Define optional parameters for communication with sendmail. 74 */ 75 typedef struct { 76 const char* cc; /**< Carbon copy recipient(s) */ 77 const char* bcc; /**< Blind carbon copy recipient(s) */ 78 char from[1024]; /**< Originator address */ 79 const char* header; /**< Custom msg header ('\n'-separated) */ 80 size_t body_size; /**< Message body size (if specified) */ 81 STimeout mx_timeout; /**< Timeout for all network transactions*/ 82 const char* mx_host; /**< Host to contact an MTA at */ 83 unsigned short mx_port; /**< Port to contact an MTA at */ 84 TSendMailOptions mx_options; /**< See ESendMailOption */ 85 unsigned int magic; /**< RO, filled in by SendMailInfo_Init */ 86 } SSendMailInfo; 87 88 89 /** Initialize SSendMailInfo structure, setting: 90 * 'cc', 'bcc', 'header' to NULL (means no recipients/additional headers); 91 * 'from' filled out with a return address using either the provided 92 * (non-empty) user name or the name of the current user if 93 * discoverable ("anonymous" otherwise), and the host, in the form: 94 * "username@hostname"; that may later be reset by the application 95 * to "" for sending no-return messages (aka MAILER-DAEMON messages); 96 * 'mx_*' filled out in accordance with some hard-coded defaults, which are 97 * rather NCBI-specific; an outside application is likely to choose 98 * and use different values (at least for 'mx_host'). 99 * The mx_... fields can be configured via the registry file at 100 * [CONN]MX_HOST, [CONN]MX_PORT, and [CONN]MX_TIMEOUT, as well as 101 * through their process environment equivalents (which have higher 102 * precedence, and override the values found in the registry): 103 * CONN_MX_HOST, CONN_MX_PORT, and CONN_MX_TIMEOUT, respectively; 104 * 'magic_cookie' to a proper value (verified by CORE_SendMailEx()!). 105 * @note This call is the only valid way to properly init SSendMailInfo. 106 * @param info 107 * A pointer to the structure to initialize 108 * @param from 109 * Return address pattern to use in 'info->from' as the following: 110 * * "user@host" or "user" is copied verbatim (as-is); 111 * * "user@" is appended with the local host name; 112 * * "@host" is prepended with the user name according to the 'user' argument; 113 * * "@" is replaced with an empty string (for no-return messages); 114 * * "" or NULL cause to generate both the user and the host parts. 115 * @param user 116 * Which username to use when auto-generating (ignored otherwise) 117 * @return 118 * Return value equals the argument 'info' passed in. 119 * @note It is allowed to pre-fill 'info->from' (of the 'info' being inited) 120 * with one of the above patterns, and pass it as the 'from' parameter. 121 * @note Unlike the username part of the return address, the hostname part is 122 * never truncated but dropped altogether if it does not fit. 123 * @note If the username is unobtainable, then it is be replaced with the word 124 * "anonymous". 125 * @sa 126 * CORE_SendMailEx, CORE_GetUsernameEx 127 */ 128 extern NCBI_XCONNECT_EXPORT SSendMailInfo* SendMailInfo_InitEx 129 (SSendMailInfo* info, 130 const char* from, 131 ECORE_Username user 132 ); 133 134 #define SendMailInfo_Init(i) SendMailInfo_InitEx(i, 0, eCORE_UsernameLogin) 135 136 137 /** Send a simple message to recipient(s) defined in 'to', and having: 138 * 'subject', which may be empty (both NULL and "" treated equally), and 139 * message 'body' (may be NULL/empty, if not empty, lines are separated by 140 * '\n', must be '\0'-terminated). Communicaiton parameters for connection 141 * with sendmail are set using default values as described in 142 * SendMailInfo_InitEx(). 143 * @note Use of this call in out-of-house applications is discouraged as it is 144 * likely to fail because the MTA communication parameters (set to their 145 * defaults, which are NCBI-specific) may not be suitable. 146 * @param to 147 * Recipient list 148 * @param subject 149 * Subject of the message 150 * @param body 151 * The message body 152 * @return 153 * 0 on success; otherwise, a descriptive error message. The message is 154 * kept in a static storage and is not to be deallocated by the caller. 155 * @sa 156 * SendMailInfo_InitEx, CORE_SendMailEx 157 */ 158 extern NCBI_XCONNECT_EXPORT const char* CORE_SendMail 159 (const char* to, 160 const char* subject, 161 const char* body 162 ); 163 164 /** Send a message as in CORE_SendMail() but by explicitly specifying all 165 * additional parameters of the message and communication via the argument 166 * 'info'. In case of 'info' == NULL, the call is completely equivalent to 167 * CORE_SendMail(). 168 * @note Body may not necessarily be '\0'-terminated if 'info->body_size' 169 * specifies non-zero message body size (see SSendMailInfo::body_size above). 170 * 171 * @note 172 * Recipient lists are not validated; a valid recipient (according to the 173 * standard) can be specified in the form '"Name" \<address\>' (excluding all 174 * comment fields, which are discouraged from appearance in the addresses); 175 * recipients must be separated by commas. In case of address-only recipients 176 * (with no "Name" part above), the angle brackets around the address should 177 * be omitted. Group syntax for recipients 'groupname ":" [mailbox-list] ";"' 178 * is not currently supported. 179 * 180 * @note 181 * If not specified (0), and by default, the message body size is calculated as 182 * strlen() of the passed 'body' argument, which thus must be '\0'-terminated. 183 * Otherwise, exactly 'info->body_size' bytes are read from the location 184 * pointed to by the 'body' parameter, and are then sent in the message. 185 * 186 * @note 187 * If fSendMail_NoMxHeader is set in 'info->mx_options', the body can have 188 * an additional header part (otherwise, a standard header gets generated as 189 * needed). In this case, even if no additional headers are supplied, the body 190 * must provide the proper header / message text delimiter (an empty line), 191 * which will not be automatically inserted (aka "as-is" message mode). 192 * 193 * @param to 194 * Recipient list 195 * @param subject 196 * Subject of the message 197 * @param body 198 * The message body 199 * @param info 200 * Communicational and additional protocol parameters 201 * @return 202 * 0 on success; otherwise, a descriptive error message. The message is 203 * not to be deallocated by the caller unless fSendMail_ExtendedErrInfo is 204 * specified in SSendMailinfo::mx_options, in which case the message contains 205 * an explanation string followed by ": " and possibly an RFC821-compliant 206 * error code (as received from the server) followed by additional error text 207 * (which in turn may begin with RFC3462-compliant status as 208 * "class.subject.detail") -- this extended message string must be free()'d by 209 * the caller when no longer necessary. If there was an allocation error, the 210 * string is returned empty ("") and must not be deallocated. The latter 211 * makes the caller still aware there was a problem. 212 * @sa 213 * SendMailInfo_InitEx 214 */ 215 extern NCBI_XCONNECT_EXPORT const char* CORE_SendMailEx 216 (const char* to, 217 const char* subject, 218 const char* body, 219 const SSendMailInfo* info 220 ); 221 222 223 #ifdef __cplusplus 224 } /* extern "C" */ 225 #endif 226 227 228 /* @} */ 229 230 #endif /* CONNECT___NCBI_SENDMAIL__H */ 231