3
<TITLE> DwMailbox Man Page </TITLE>
5
<BODY BGCOLOR="#FFFFFF">
7
<FONT COLOR="navy"> NAME </FONT>
10
DwMailbox -- Class representing an RFC-822 mailbox
12
<FONT COLOR="navy"> SYNOPSIS </FONT>
14
<PRE>class DW_EXPORT DwMailbox : public <A HREF="address.html">DwAddress</A> {
16
friend class DwMailboxList;
20
<A HREF="mailbox.html#DwMailbox">DwMailbox</A>();
21
<A HREF="mailbox.html#DwMailbox">DwMailbox</A>(const DwMailbox& aMailbox);
22
<A HREF="mailbox.html#DwMailbox">DwMailbox</A>(const DwString& aStr, DwMessageComponent* aParent=0);
24
const DwMailbox& <A HREF="mailbox.html#op_eq">operator =</A> (const DwMailbox& aMailbox);
25
virtual void <A HREF="mailbox.html#Parse">Parse</A>();
26
virtual void <A HREF="mailbox.html#Assemble">Assemble</A>();
27
virtual DwMessageComponent* <A HREF="mailbox.html#Clone">Clone</A>() const;
28
const DwString& <A HREF="mailbox.html#FullName">FullName</A>() const;
29
void <A HREF="mailbox.html#SetFullName">SetFullName</A>(const DwString& aFullName);
30
const DwString& <A HREF="mailbox.html#Route">Route</A>() const;
31
void <A HREF="mailbox.html#SetRoute">SetRoute</A>(const DwString& aRoute);
32
const DwString& <A HREF="mailbox.html#LocalPart">LocalPart</A>() const;
33
void <A HREF="mailbox.html#SetLocalPart">SetLocalPart</A>(const DwString& aLocalPart);
34
const DwString& <A HREF="mailbox.html#Domain">Domain</A>() const;
35
void <A HREF="mailbox.html#SetDomain">SetDomain</A>(const DwString& aDomain);
36
static DwMailbox* <A HREF="mailbox.html#NewMailbox">NewMailbox</A>(const DwString& aStr, DwMessageComponent*
38
static DwMailbox* (*<A HREF="mailbox.html#sNewMailbox">sNewMailbox</A>)(const DwString&, DwMessageComponent*);
42
virtual void <A HREF="mailbox.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const;
43
virtual void <A HREF="mailbox.html#CheckInvariants">CheckInvariants</A>() const;
47
void _PrintDebugInfo(ostream& aStrm) const;
51
<FONT COLOR="navy"> DESCRIPTION </FONT>
54
RFC-822 defines a <I>mailbox</I> as an entity that can be the recipient of
55
a message. A mailbox is more specific than an <I>address</I>, which may be
56
either a mailbox or a <I>group</I>. An RFC-822 mailbox contains a full name,
57
a <I>local-part</I>, an optional <I>route</I>, and a <I>domain</I>. For example,
60
Joe Schmoe <jschmoe@aol.co>
62
"Joe Schmoe" is the full name, "jschmoe" is the local-part, and "aol.com"
63
is the domain. The optional route is rarely seen in current usage, and is
64
deprecated according to RFC-1123.
66
In MIME++, an RFC-822 mailbox is represented by a
67
<B><TT>DwMailbox</TT></B> object. <B><TT>DwMailbox</TT></B> is a subclass
68
of <B><TT><A HREF="address.html">DwAddress</A></TT></B>, which reflects the
69
fact that a mailbox is also an address. A <B><TT>DwMailbox</TT></B> contains
70
strings representing the full name, local-part, route, and domain of a mailbox.
72
In the tree (broken-down) representation of message, a
73
<B><TT>DwMailbox</TT></B> object may be only a leaf node, having a parent
74
but no child nodes. Its parent node must be a
75
<B><TT><A HREF="field.html">DwField</A></TT></B>, a
76
<B><TT><A HREF="addrlist.html">DwAddressList</A></TT></B>, or a
77
<B><TT><A HREF="mboxlist.html">DwMailboxList</A></TT></B> object.
79
<B><TT>DwMailbox</TT></B> has member functions for getting or setting the
82
<B><TT>DwMailbox</TT></B> object can be included in a list of
83
<B><TT>DwMailbox</TT></B> objects. To get the next
84
<B><TT>DwMailbox</TT></B> object in a list, use the inherited member function
85
<B><TT>DwAddress::Next()</TT></B>.
87
<FONT COLOR="navy"> Public Member Functions </FONT>
90
<FONT COLOR="teal"><B> <A NAME="DwMailbox">DwMailbox</A>() <BR>
91
DwMailbox(const DwMailbox& aMailbox) <BR>
92
DwMailbox(const DwString& aStr, DwMessageComponent* aParent=0)
95
The first constructor is the default constructor, which sets the
96
<B><TT>DwMailbox</TT></B> object's string representation to the empty string
97
and sets its parent to <B><TT>NULL</TT></B>.
99
The second constructor is the copy constructor, which performs a deep copy
100
of <B><TT>aMailbox</TT></B>. The parent of the new
101
<B><TT>DwMailbox</TT></B> is set to <B><TT>NULL</TT></B>.
103
The third constructor copies <B><TT>aStr</TT></B> to the
104
<B><TT>DwMailbox</TT></B> object's string representation and sets
105
<B><TT>aParent</TT></B> as its parent. The virtual member function
106
<B><TT>Parse()</TT></B> should be called immediately after this constructor
107
in order to parse the string representation. Unless it is
108
<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of
109
a class derived from <B><TT>DwField</TT></B>.
111
<FONT COLOR="teal"><B> const DwMailbox& <A NAME="op_eq">operator =</A>
112
(const DwMailbox& aMailbox) </B></FONT>
114
This is the assignment operator, which performs a deep copy of
115
<B><TT>aMailbox</TT></B>. The parent node of the
116
<B><TT>DwMailbox</TT></B> object is not changed.
118
<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT>
120
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
121
executes the parse method for <B><TT>DwMailbox</TT></B> objects. The parse
122
method creates or updates the broken-down representation from the string
123
representation. For <B><TT>DwMailbox</TT></B> objects, the parse method parses
124
the string representation into the substrings for the full name, local-part,
127
You should call this member function after you set or modify the string
128
representation, and before you retrieve the full name, local-part, route,
131
This function clears the is-modified flag.
133
<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>()
136
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
137
executes the assemble method for <B><TT>DwMailbox</TT></B> objects. The assemble
138
method creates or updates the string representation from the broken-down
139
representation. For <B><TT>DwMailbox</TT></B> objects, the assemble method
140
builds the string representation from the full name, local-part, route, and
143
You should call this member function after you modify the full name, local-part,
144
route, or domain, and before you retrieve the string representation.
146
This function clears the is-modified flag.
148
<FONT COLOR="teal"><B> virtual DwMessageComponent*
149
<A NAME="Clone">Clone</A>() const </B></FONT>
151
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
152
creates a new <B><TT>DwMailbox</TT></B> on the free store that has the same
153
value as this <B><TT>DwMailbox</TT></B> object. The basic idea is that of
154
a virtual copy constructor.
156
<FONT COLOR="teal"><B> const DwString& <A NAME="FullName">FullName</A>()
159
Returns the full name for this <B><TT>DwMailbox</TT></B> object.
161
<FONT COLOR="teal"><B> void <A NAME="SetFullName">SetFullName</A>(const
162
DwString& aFullName) </B></FONT>
164
Sets the full name for this <B><TT>DwMailbox</TT></B> object.
166
<FONT COLOR="teal"><B> const DwString& <A NAME="Route">Route</A>() const
169
Returns the route for this <B><TT>DwMailbox</TT></B> object.
171
<FONT COLOR="teal"><B> void <A NAME="SetRoute">SetRoute</A>(const DwString&
174
Sets the route for this <B><TT>DwMailbox</TT></B> object.
176
<FONT COLOR="teal"><B> const DwString&
177
<A NAME="LocalPart">LocalPart</A>() const </B></FONT>
179
Returns the local-part for this <B><TT>DwMailbox</TT></B> object.
181
<FONT COLOR="teal"><B> void <A NAME="SetLocalPart">SetLocalPart</A>(const
182
DwString& aLocalPart) </B></FONT>
184
Sets the local-part for this <B><TT>DwMailbox</TT></B> object.
186
<FONT COLOR="teal"><B> const DwString& <A NAME="Domain">Domain</A>()
189
Returns the domain for this <B><TT>DwMailbox</TT></B> object.
191
<FONT COLOR="teal"><B> void <A NAME="SetDomain">SetDomain</A>(const
192
DwString& aDomain) </B></FONT>
194
Sets the domain for this <B><TT>DwMailbox</TT></B> object.
196
<FONT COLOR="teal"><B> static DwMailbox*
197
<A NAME="NewMailbox">NewMailbox</A>(const DwString& aStr, DwMessageComponent*
200
Creates a new <B><TT>DwMailbox</TT></B> object on the free store. If the
201
static data member <B><TT>sNewMailbox</TT></B> is <B><TT>NULL</TT></B>, this
202
member function will create a new <B><TT>DwMailbox</TT></B> and return it.
203
Otherwise, <B><TT>NewMailbox()</TT></B> will call the user-supplied function
204
pointed to by <B><TT>sNewMailbox</TT></B>, which is assumed to return an
205
object from a class derived from <B><TT>DwMailbox</TT></B>, and return that
208
<FONT COLOR="teal"><B> virtual void
209
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0)
212
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
213
prints debugging information about this object to <B><TT>aStrm</TT></B>.
214
It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child
215
components down to a level of <B><TT>aDepth</TT></B>.
217
This member function is available only in the debug version of the library.
219
<FONT COLOR="teal"><B> virtual void
220
<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT>
222
Aborts if one of the invariants of the object fails. Use this member function
225
This member function is available only in the debug version of the library.
227
<FONT COLOR="navy"> Public Data Members </FONT>
230
<FONT COLOR="teal"><B> static DwMailbox*
231
(*<A NAME="sNewMailbox">sNewMailbox</A>)(const DwString&,
232
DwMessageComponent*) </B></FONT>
234
If <B><TT>sNewMailbox</TT></B> is not <B><TT>NULL</TT></B>, it is assumed
235
to point to a user-supplied function that returns an object from a class
236
derived from <B><TT>DwMailbox</TT></B>.