Defined in file: hzMailer.h
hzEmail is a single email message container, used to compose email messages prior to sending, and for deconstruction of recieved email messages into their component parts. In the send case, the hzEmail instance starts out empty and the message is built in a step by step process. The sender is set, recipients are added one by one, the subject is set, the text body is added, the HTML body is added (optional), then attachments (if any) are added one by one. Finally hzEmail::Compose() is called to assemble an IMF message, ready for SMTP relay. In the recv case, hzEmail::Import() processes an IMF message to populate the set of headers and parts, thereby availing these to the application. Note that four hzEmail members are used for email addresses related to the sender, three of which are set by SMTP headers in the IMF message as follows:- m_AddrReturn is set by Return-path; m_AddrReply is set by Reply-To; m_AddrFrom is set by From. The forth, m_AddrRelay is set at the start of an SMTP client session (message incoming). It is used to set m_AddrFrom if the relayed IMF lacks the From: header, but will be ignored otherwise. m_AddrFrom is the definative sender address. HadronZoo::Epistula stores the m_AddrFrom value as the sender in its message repository, and in the webmail service, this value appears in the folder listings. In the construction of an outgoing message, m_AddrFrom is set by hzEmail::SetSender(). In the subsequent relay session, the m_AddrFrom value is used as the initiator address. m_AddrReply and m_AddrReturn are set separately. m_AddrReply can be NULL but if m_AddrReturn is NULL, it will assume the m_AddrFrom value.
This class employes the private sub-class _efile as follows:-
_efile
Constructors/Detructors
| hzEmail* | hzEmail | (void) | |
| void | ~hzEmail | (void) |
Public Methods:
| hzEcode | AddAttachment | (const char* dir)const char* fname, hzMimetype mtype, | Add an attachment using both a directory path and a filename to name the file. |
| hzEcode | AddAttachment | (const char* fpath)hzMimetype mtype, | Add an attachment using a full file path to name the file. |
| hzEcode | AddAttachment | (const char* fpath) | Add an attachment using a full file path to name the file, but do not specify the file's MIME type. This will be assigned later on the basis of file ending. |
| hzEcode | AddBody | (hzChain& Z) | Addd chain content to the email body. Can be called multiple times. |
| hzEcode | AddBody | (hzString& S) | Addd a string to the email body. Can be called multiple times. |
| hzEcode | AddBody | (const char* msg) | Add a char string to the email body. Can be called multiple times. |
| hzEcode | AddRecipient | (hzEmaddr& ema) | Add a 'To' recipient to a hzEmail instance using a formal email address (hzEmaddr) as argument |
| hzEcode | AddRecipient | (const char* cpRecipient) | Add a 'To' recipient to a hzEmail instance using an informal email address (const char*) as argument |
| hzEcode | AddRecipientBCC | (hzEmaddr& ema) | Add a 'Bcc' recipient to a hzEmail instance using a formal email address (hzEmaddr) as argument |
| hzEcode | AddRecipientBCC | (const char* cpRecipient) | Add a 'Bcc' recipient to a hzEmail instance using an informal email address (const char*) as argument |
| hzEcode | AddRecipientCC | (hzEmaddr& ema) | Add a 'Cc' recipient to a hzEmail instance using a formal email address (hzEmaddr) as argument |
| hzEcode | AddRecipientCC | (const char* cpRecipient) | Add a 'Cc' recipient to a hzEmail instance using an informal email address (const char*) as argument |
| void | Clear | (void) | Clear hzEmail instance Arguments: None Returns: None |
| hzEcode | Compose | (void) | Compose is called strictly as part of an email origination process. Once everything has been added in - the sender, the complete list of reciepients, the subject, the body, and files named as attachments, Compose is called to compile into a single chain, the complete message as it will be relayed. Arguments: None |
| uint32_t | CountRecipientsAll | (void) | |
| uint32_t | CountRecipientsBC | (void) | |
| uint32_t | CountRecipientsCC | (void) | |
| uint32_t | CountRecipientsStd | (void) | |
| hzList<hzEmaddr>& | GetRecipientsBCC | (void) | |
| hzList<hzEmaddr>& | GetRecipientsCC | (void) | |
| hzList<hzEmaddr>& | GetRecipientsStd | (void) | |
| hzEmaddr& | GetSender | (void) | |
| hzString& | GetSenderReal | (void) | |
| hzString& | GetSubject | (void) | |
| hzEcode | Import | (hzChain& emRaw)bool bHead, | Import a serialized email message in IMF (Internet Message Format). This hzEmail instance is first cleared, then populated with the supplied IMF datum. To be valid, a message must have a sender, at least one recipient, a date and time and a message id. For the purpose of HadronZoo::Epistula, a message must have a body. Within the message header, there is usually a Content-Type header. This can specify a format such as "text/plain", but this is only where the message body is not comprised of multiple parts. Email messages are mostly multipart, with a Content-Type of either:- multipart/mixed This is for sending files with different Content-Type header fields, either to be displayed upon opening by the mail client, or as attachments. multipart/alternative This indicates that each part is an alternative version of the same (or similar) content, e.g. a text part and a HTML part. Each part will have its own Content-Type header to state the format. multipart/related This is used to indicate that each message part is a component of an aggregate whole. It is for messages consisting of a number of inter-related parts. The message consists of a root part which reference other parts, which may in turn reference other parts. One use would be to send a web page complete with images in a single message. The parts are separated by a boundary sequence which is specified in the line after a multipart Content-Type header. In theory a single boundary sequence would suffice, but email messages often use one part to specify another boundary sequence. This latter sequence is then used to separate parts, until it is terminated (postpended with --), at which point use of the previous boundary sequence resumes. Because of this approach, this function calls a recursive support function, _part_process(), to process parts. |
| hzEcode | SendEpistula | (hzChain& report) | Directly inject email into the epistula mail que. |
| hzEcode | SendSmtp | (const char* server)const char* uname, const char* passwd, | Directly relay the email to the target domain SMTP server for immediate transmission, as opposed to queuing the email to the local SMTP server. This is the fastest means of establishing the validity of the recipient address, widely used by webapps during new member registration to verify the member's email address. The following scenarios are taken into account:- 1) The DNS may be down or temporarily busy so it is not possible to determine if the domain part of the email address actually exists.# 2) The DNS provides the mail servers for the domain but none can be connected to at the moment. 3) The DNS is up but cannot find a mail server for the domain 4) The mail server was connected to but rejected the sender (the web application on your server) 5) The mail server was connected to but denied the existance of the recipient. 6) The mail server accepted the email. Of the above, scenarios 1 and 2 are inconclusive. Yet the HTTP response to the form submission (containing the user email address), must be sent without delay. The message should be queued and the user notified of this. The message should make clear the email could not be verified but if it is a live email address, the verification code will arrive in due course. Any sessions left unfullfilled after a certain period must be purged. Senarios 3, 4 and 5 are terminal. The email will not be sent at any point. Only scenario 6 is where the response can say "an email has been sent". It could be of course, that the address is incorrect. Note that bypassing the local SMTP server foregoes any email management the local SMTP server may offer. If you need a permanent and easily searchable record of the email, the calling applications will have to make arrangements for this. |
| hzEcode | SetSender | (hzEmaddr& sender) | |
| hzEcode | SetSender | (const char* cpSender)const char* cpRealname, | Set the email's sender. |
| hzEcode | SetSubject | (const char* cpSubject) | Set the subject of the email. |
| hzEcode | _part_process | (hzChain::Iter& zi)hzString& mark, uint32_t nLevel, | Process message parts until termination sequence (--boundary--) Message parts take the following form:- a) A line of the form --boundary b) Headers to state 'filename', content type, content encoding and size c) A blank line d) The content e) Another blank line f) A terminating line of the form --boundary-- The headers may state another boundary, in which case one or more message parts will be enclosed between (a) and (f). These parts will be of the same form (a - f), and are handled by a recursive call to this function. |
Member Variables:
| hzEmaddr | m_AddrFrom | Authorative address of sender, as given by From header | |
| hzEmaddr | m_AddrRelay | Sender address as stated at the outset of the SMTP client session. In outgoing messages, this is always the same as m_AddrFrom. | |
| hzEmaddr | m_AddrReply | Address given in the ReplyTo header | |
| hzEmaddr | m_AddrReturn | Return address (Return-path header) | |
| hzEmaddr | m_AddrTo | Address of primary recipient | |
| hzList<hzEmpart> | m_Attach | List of message parts that are attached files | |
| hzList<hzEmaddr> | m_BCC | List of bcc recipient(s) | |
| hzList<hzEmaddr> | m_CC | List of cc recipient(s) | |
| hzContentType | m_ContType | Content type | |
| hzXDate | m_Date | Date of email (recv only) | |
| hzString | m_DomainOrig | Domain part of m_AddrRelay (see below). Note for the message to be accepted, the domain part of m_AddrReturn, m_AddrReply, and m_AddrFrom must concur. | |
| hzContentEncoding | m_Encoding | Content encoding | |
| hzChain | m_Err | For error reporting (e.g. failed import) | |
| hzChain | m_Final | Fully composed email (IMF) | |
| hzVect<hzPair> | m_Hdrs | Message headers: Note this is only filled by Import. Composure of an outgoing message does not populate this list. | |
| hzChain | m_Html | Body of email (Html part) | |
| hzString | m_Id | Mail id (typically as set by first SMTP server to handle it) | |
| hzList<hzEmpart> | m_Inline | List of message parts (inline) | |
| hzString | m_RealFrom | Real name of sender | |
| hzString | m_RealReply | Real name given in Reply-To header (if any) | |
| hzString | m_RealTo | Real name of recipient (rarely used) | |
| hzList<hzEmaddr> | m_Recipients | List of main recipient(s) | |
| hzList<hzEmail::_efile> | m_SendAttach | List of file attachments (added by Attach() as part of forming an outgoing email) | |
| hzIpaddr | m_SenderIP | Sender IP address | |
| hzString | m_Subject | Subject | |
| hzChain | m_Text | Body of email (Text part) |