Inheritance diagram for Mailbox:
Joe Schmoe <jschmoe@example.com>
"Joe Schmoe" is the display name, "jschmoe" is the local part, and "example.com" is the domain. The optional route is rarely seen in current usage, and is deprecated according to RFC 2822.
Note: The terms are not as precise as they should be. Technically, we should make a distinction between a mailbox and a mailbox name. We don't make that distinction because RFC 2822 doesn't make that distinction.
In Hunny MIME++, an RFC 2822 mailbox is represented by a Mailbox object. Mailbox is a subclass of Address, which reflects the fact that a mailbox is also an address. A Mailbox contains strings for the display name, local part, route, and domain of a mailbox.
Mailbox has member functions for getting or setting the strings it contains.
In the document tree representation of a message, a Mailbox object may be only a leaf node, having a parent node but no child nodes. Its parent node should be a Field object, an AddressList object, or a MailboxList object.
Usage
To use Mailbox to parse a mailbox string, create an instance using the constructor that takes a String argument. Call the parse() member function to parse the string representation. Then call displayNameUtf8(), localPart(), and domain() to get the parsed substrings.
To use Mailbox to generate a mailbox string, create an instance using the default constructor. Call setLocalPart(), setDomain(), and optionally setDisplayNameUtf8() to set the local part, domain, and display name, respectively. Call assemble() to update the string representation. Then, call getString() to retrieve the string representation.
Mailbox Formats
The format of mailboxes found in Internet mail varies. The following shows some alternative formats:
In example (2), the quotation marks are required because the display name contains the characters "." and ",". In example (3), there is no display name. The format in example (4) is the traditional format for Usenet articles. Examples (5) and (6) use the encoding specified in RFC 2047. The encoding is not needed in these examples, because all the characters are 7-bit US-ASCII characters. However, the encoding is required if the display name contains characters not in the 7-bit US-ASCII character set. Example (5) uses a modified form of the quoted-printable transfer encoding (RFC 2045) to encode the display name "Joe H. Schmoe, Jr.", which uses the ISO 8859-1 character set. Example (6) uses the base64 transfer encoding (RFC 2045) to encode only the second "word" of the display name "Joe Schmoe", which uses the UTF-8 encoding of Unicode.
Hunny MIME++ correctly parses mailboxes in all the formats shown above. When mailboxes are assembled (that is, generated), one of the formats in examples (1), (2), or (5) is selected in that order.
Public Member Functions | |
| Mailbox () | |
| Default constructor. | |
| Mailbox (const Mailbox &other) | |
| Copy constructor. | |
| Mailbox (const String &str, Node *parent=0) | |
| Constructor that takes an initial string and parent node. | |
| virtual | ~Mailbox () |
| Destructor. | |
| const Mailbox & | operator= (const Mailbox &other) |
| Assignment operator. | |
| virtual void | parse () |
| Parses the string representation. | |
| virtual void | assemble () |
| Assembles the string representation. | |
| virtual Node * | clone () const |
| Creates a copy of this object. | |
| const String & | displayNameUtf8 () const |
| Gets the display name. | |
| const String & | charset () const |
| Gets the charset identifier for the display name. | |
| void | setDisplayNameUtf8 (const String &name) |
| Sets the display name from a UTF-8 string. | |
| void | setDisplayNameUtf8 (const String &name, const String &charset) |
| Sets the display name from a UTF-8 string, with a charset hint. | |
| const String & | encodedDisplayName () const |
| Gets the encoded display name. | |
| void | setEncodedDisplayName (const String &name) |
| Sets the encoded display name. | |
| const String & | route () const |
| Gets the source route. | |
| void | setRoute (const String &route) |
| Sets the source route. | |
| const String & | localPart () const |
| Gets the local part. | |
| void | setLocalPart (const String &localPart) |
| Sets the local part. | |
| const String & | domain () const |
| Gets the domain. | |
| void | setDomain (const String &domain) |
| Sets the domain. | |
Static Public Member Functions | |
| Mailbox * | newMailbox () |
| Creates a new instance. | |
Static Public Attributes | |
| Mailbox *(* | sNewMailbox )() |
| Provides a class factory hook. | |
|
|
This constructor sets the Mailbox object's string representation to the empty string and sets its parent node to NULL. |
|
|
This constructor performs a deep copy of its argument. The parent node of the new Mailbox object is set to NULL.
|
|
||||||||||||
|
This constructor sets the Mailbox object's string representation to str and sets its parent node to parent. Normally, you call the virtual function parse() immediately after this constructor to create the broken-down representation.
|
|
|
Destructor |
|
|
This virtual function, inherited from Node, executes the assemble operation for Mailbox objects. The assemble operation creates or updates the string representation from the broken-down representation. For Mailbox objects, the assemble operation builds the string representation from the display name, local part, route, and domain strings. You should call this member function after you set or modify the display name, local part, route, or domain, and before you retrieve the string representation. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Gets the charset identifier for the display name.
|
|
|
This virtual function, inherited from Node, creates a new MailboxList object that has the same value as this Mailbox object. The parent node of the new Mailbox object is set to NULL.
Reimplemented from FieldBody. |
|
|
Gets the display name as a UTF-8 string. This convenience function decodes any encoded words in the display name. It also unquotes any quoted strings. To get the charset identifier for the display name, call the charset() member function. To get the encoded display name, call the encodedDisplayName() member function.
|
|
|
Gets the domain. When the domain is parsed, white space and comments are removed if they are present. For example, if the mailbox string is
"John Doe" <john.doe @ example (yeah,right!) . net > then the domain returned by this function is
example.net
|
|
|
Gets the encoded display name. If the display name contains non-ASCII characters, it must be encoded before it can be used in a header field. This member function provides a way to get the encoded display name directly. This member function is useful if you want to store the display name in its encoded form in a database. It is also useful if you are just "editing" a message: perhaps you want to copy addresses from one message to another. By getting the encoded display name, you can be sure that there is no loss of information when character encodings are converted. The following is a simple example of a display name encoded with the modified quoted-printable encoding:
Decoded: Jürgen König For more information about the encoding of text in header fields, see RFC 2047.
|
|
|
Gets the local part for this Mailbox object. When the local part is parsed, white space and comments are removed if they are present. For example, if the mailbox string is
"John Doe" < john . (average) doe @example.net> then the local part returned by this function is
john.doe However, double quote characters are not removed, since they are rarely needed and rarely seen.
|
|
|
Creates a new Mailbox object. If the static data member sNewMailbox is NULL, this member function creates a new Mailbox object and returns it. Otherwise, newMailbox() calls the user-supplied function that sNewMailbox points to and returns the object created by that function.
|
|
|
Performs a deep copy of its argument. The parent node of this Mailbox object is not changed.
|
|
|
This virtual function, inherited from Node, executes the parse operation for Mailbox objects. The parse operation creates or updates the broken-down representation from the string representation. For Mailbox objects, the parse operation parses the string representation into the substrings for the display name, local part, route, and domain. You should call this member function after you set or modify the string representation, and before you retrieve the display name, local part, route, or domain. This function clears the is-modified flag. Reimplemented from FieldBody. |
|
|
Gets the route. The route, sometimes called the "source route", is deprecated in current usage, and is rarely seen. Hunny MIME++ supports it only to be fully compliant with standards, and to provide compatibility with obsolete mail systems.
|
|
||||||||||||
|
Sets the display name from a UTF-8 string, with a hint about the character encoding to use. This member function attempts to use the specified character encoding (charset) when the display name is encoded. As a special case, if all characters are in the US-ASCII character set, the charset will be changed to US-ASCII and no encoding will be performed. Use this member function to set the display name if:
|
|
|
Sets the display name from a UTF-8 string. This member function automatically determines the character encoding (charset) to use by examining the content of its string argument. The charset chosen is one of the following: US-ASCII, ISO-8859-1, or UTF-8. Use this member function to set the display name if:
If you want to specify an external character encoding other than US-ASCII, ISO-8859-1, or UTF-8, then use the sSetDisplayName() member function.
|
|
|
Sets the domain. When the string representation is assembled, the domain is not interpreted in any way. White space characters are not removed and the domain is not checked for invalid characters.
|
|
|
Sets the encoded display name. If the display name contains non-ASCII characters, it must be encoded before it can be used in a header field. This member function provides a way to set the encoded display name directly. The argument is used "as is": when the string representation is assembled, no additional conversion is performed on the display name. This member function is useful in certain situations. If you never display Internet mail addresses, there is no need to convert the display name to a displayable form. For example, if you were managing a mailing list, you could extract a display name from a mailbox using encodedDisplayName(), store it in a database, and insert it into another mailbox using setEncodedDisplayName(). The encoded display name is handy for databases, because it keeps the display name and its charset identifier together. The following is a simple example of a display name encoded with the modified quoted-printable encoding:
Decoded: Jürgen König For more information about the encoding of text in header fields, see RFC 2047.
|
|
|
Sets the local part for this Mailbox object. When the string representation is assembled, the local part is not interpreted in any way. In particular, characters that are not allowed in the local part of a valid mailbox are not quoted. If you need to set a local part that requires quotes, then you must quote the local part before setting it. Rationale: Most mail addresses that are assigned by mail administrators do not allow a local part that must be quoted. Consequently, a local part that requires quoting is very rarely seen. (They are seen, however. A typical situation in which a local part requires quoting is when a message originates from an X.400 mail system.)
|
|
|
Sets the route. The route, sometimes called the "source route", is deprecated in current usage, and is rarely seen. Hunny MIME++ supports it only to be fully compliant with standards, and to provide compatibility with obsolete mail systems.
|
|
|
If sNewMailbox is not NULL, it must point to a user-supplied function that returns a new instance of a subclass of Mailbox.
|
Copyright © 2001-2007 Hunny Software, Inc. All rights reserved.