1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
|
<HTML>
<HEAD>
<TITLE> DwMessageComponent Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
<FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwMessageComponent -- Abstract base class for all message components
<H2>
<FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwMessageComponent {
public:
enum componentType {
kCidError=-1,
kCidUnknown=0,
kCidAddress,
kCidAddressList,
kCidBody,
kCidBodyPart,
kCidDispositionType,
kCidMechanism,
kCidMediaType,
kCidParameter,
kCidDateTime,
kCidEntity,
kCidField,
kCidFieldBody,
kCidGroup,
kCidHeaders,
kCidMailbox,
kCidMailboxList,
kCidMessage,
kCidMessageComponent,
kCidMsgId,
kCidText
};
<A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>();
<A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(const DwMessageComponent& aCmp);
<A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(const DwString& aStr, DwMessageComponent* aParent=0);
virtual ~DwMessageComponent();
const DwMessageComponent& <A HREF="msgcmp.html#op_eq">operator =</A> (const DwMessageComponent& aCmp);
virtual void <A HREF="msgcmp.html#Parse">Parse</A>() = 0;
virtual void <A HREF="msgcmp.html#Assemble">Assemble</A>() = 0;
virtual DwMessageComponent* <A HREF="msgcmp.html#Clone">Clone</A>() const = 0;
void <A HREF="msgcmp.html#FromString">FromString</A>(const DwString& aStr);
void <A HREF="msgcmp.html#FromString">FromString</A>(const char* aCstr);
const DwString& <A HREF="msgcmp.html#AsString">AsString</A>();
DwMessageComponent* <A HREF="msgcmp.html#Parent">Parent</A>();
void <A HREF="msgcmp.html#SetParent">SetParent</A>(DwMessageComponent* aParent);
DwBool <A HREF="msgcmp.html#IsModified">IsModified</A>() const;
void <A HREF="msgcmp.html#SetModified">SetModified</A>();
int <A HREF="msgcmp.html#ClassId">ClassId</A>() const;
const char* <A HREF="msgcmp.html#ClassName">ClassName</A>() const;
int <A HREF="msgcmp.html#ObjectId">ObjectId</A>() const;
protected:
DwString mString;
DwBool mIsModified;
DwMessageComponent* mParent;
componentType mClassId;
const char* mClassName;
public:
virtual void <A HREF="msgcmp.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const;
virtual void <A HREF="msgcmp.html#CheckInvariants">CheckInvariants</A>() const;
protected:
void _PrintDebugInfo(ostream& aStrm) const;
};
</PRE>
<H2>
<FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwMessageComponent</TT></B> is the root of an inheritance hierarchy
from which all MIME message components are derived. Thus,
<B><TT>DwMessageComponent</TT></B> defines important features that are inherited
by nearly all other classes that represent components of a MIME message.
These features are the following:
<P>
<UL>
<LI>
A string representation. The <B><TT>DwMessageComponent</TT></B> class provides
a member function <B><TT>FromString(const DwString&)</TT></B> to set
the string representation and a member function
<B><TT>AsString()</TT></B> to get the string representation.
<P>
<LI>
A broken-down, or parsed, representation. An RFC-822 date-time, for example,
has a year, month, day, hour, minute, second, and time zone as elements of
its broken-down representation. <B><TT>DwMessageComponent</TT></B> does not
deal directly with the broken-down representation, since it is
component-specific. Derived classes bear all the responsibility for their
broken-down representations.
<P>
<LI>
A parse method to extract the broken-down representation from the string
representation. In the <B><TT>DwDateTime</TT></B> class, for example, the
parse method extracts the year, month, day, hour, minute, second, and time
zone from the RFC-822 <I>date-time</I> contained in the string representation.
<B><TT>DwMessageComponent</TT></B> provides a pure virtual function
<B><TT>Parse()</TT></B>, which executes the parse method for a derived class.
<P>
<LI>
An assemble method to convert the broken-down representation to a string
representation. This is the opposite of the parse method. In the
<B><TT>DwDateTime</TT></B> class, for example, the assemble method creates
an RFC-822 <I>date-time</I> string from values of the year, month, day, hour,
minute, second, and time zone. <B><TT>DwMessageComponent</TT></B> provides
a pure virtual function <B><TT>Assemble()</TT></B>, which executes the assemble
method for a derived class.
<P>
<LI>
An is-modified flag. When the string representation and the broken-down
representation are consistent, the assemble method does not need to be executed.
The is-modified flag is cleared when the two representations are consistent,
and is set when they are inconsistent. The flag is set automatically whenever
a <B><TT>DwMessageComponent</TT></B> object's broken-down representation
is changed by calling one of the object's member functions, and it is cleared
when the assemble or parse method is executed.
<B><TT>DwMessageComponent</TT></B> also provides a member function
<B><TT>SetModified()</TT></B> which forces the is-modified flag to be set.
<P>
<LI>
A parent. Most message components are part of another component. A collection
of headers is part of a message or body part, a header field is part of a
collection of headers, a field-body is part of a header field, and so on.
The parent of a component is the component that contains it. This tree structure
is important, since a component's parent must be parsed before the component
can be. Also, a component's string representation must be assembled before
its parent's. To maintain consistency in the tree, whenever a component's
is-modified flag is set, the component notifies its parent to also set its
is-modified flag. In this way, an is-modified flag set anywhere in the tree
always propagates up to the root component.
<P>
<LI>
Children. The preceding discussion about a component's parent is relevant
to an understanding of a component's children. A component's parse method
calls the parse methods of its children after it has executed its own parse
method (and, in some cases, created all of its children). Also, a component
typically calls the assemble method of its children before it executes its
own. A component's child may request that the component set its is-modified
flag. <B><TT>DwMessageComponent</TT></B> does not deal directly with children.
Derived classes bear all the responsibility for handling their children.
</UL>
<H2>
<FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwMessageComponent">DwMessageComponent</A>()
<BR>
DwMessageComponent(const DwMessageComponent& aCmp) <BR>
DwMessageComponent(const DwString& aStr, DwMessageComponent* aParent=0)
</B></FONT>
<P>
The first constructor is the default constructor, which sets the
<B><TT>DwMessageComponent</TT></B> object's string representation to the
empty string and sets its parent to NULL.
<P>
The second constructor is the copy constructor, which performs a deep copy
of <B><TT>aCmp</TT></B>. The parent of the new
<B><TT>DwMessageComponent</TT></B> object is set to NULL.
<P>
The third constructor copies <B><TT>aStr</TT></B> to the new
<B><TT>DwMessageComponent</TT></B> object's string representation and sets
<B><TT>aParent</TT></B> as its parent. In typical cases, the virtual member
function <B><TT>Parse()</TT></B> should be called immediately after this
constructor to parse the new <B><TT>DwMessageComponent</TT></B> object and
all of its children into their broken-down representations.
<P>
<FONT COLOR="teal"><B> const DwMessageComponent& <A NAME="op_eq">operator
=</A> (const DwMessageComponent& aCmp) </B></FONT>
<P>
This is the assignment operator, which performs a deep copy of
<B><TT>aCmp</TT></B>.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() = 0
</B></FONT>
<P>
A pure virtual function which provides an interface to the parse method.
The parse method, implemented in derived classes, is responsible for extracting
the broken-down representation from the string representation. In some derived
classes, such as <B><TT>DwHeaders</TT></B>, the parse method is also responsible
for creating the children of the object. (In the case of
<B><TT>DwHeaders</TT></B>, the children created are the
<B><TT>DwField</TT></B> objects that represent the <I>field</I>s contained
in the <I>headers</I>.) The <B><TT>Parse()</TT></B> function always calls
the <B><TT>Parse()</TT></B> function of all of its children.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>() = 0
</B></FONT>
<P>
A pure virtual function which provides an interface to the assemble method.
The assemble method, implemented in derived classes, is responsible for creating
the string representation from the broken-down representation. In other words,
the assemble method is the opposite of the parse method. Before assembling
its string representation, the assemble method calls the assemble method
of each of its children. In this way, the entire tree structure that represents
a message may be traversed. If the is-modifed flag for a
<B><TT>DwMessageComponent</TT></B> is cleared, the
<B><TT>Assemble()</TT></B> function will return immediately without calling
the <B><TT>Assemble()</TT></B> function of any of its children.
<P>
<FONT COLOR="teal"><B> virtual DwMessageComponent*
<A NAME="Clone">Clone</A>() const = 0 </B></FONT>
<P>
Creates a new <B><TT>DwMessageComponent</TT></B> on the free store that is
of the same type as, and has the same value as, this object. The basic idea
is that of a ``virtual copy constructor.''
<P>
<FONT COLOR="teal"><B> void <A NAME="FromString">FromString</A>(const
DwString& aStr) <BR>
void FromString(const char* aCstr) </B></FONT>
<P>
Sets the object's string representation. <B><TT>aCstr</TT></B> must be
NUL-terminated. This member function does not invoke the parse method. Typically,
the virtual member function <B><TT>Parse()</TT></B> should be called immediately
after this member function to parse the
<B><TT>DwMessageComponent</TT></B> object and all of its children into their
broken-down representations. See also
<B><TT>DwMessageComponent::Parse()</TT></B>
<P>
<FONT COLOR="teal"><B> const DwString& <A NAME="AsString">AsString</A>()
</B></FONT>
<P>
Returns the <B><TT>DwMessageComponent</TT></B> object's string representation.
The assemble method is not called automatically. Typically, the
<B><TT>Assemble()</TT></B> member function should be called immediately before
this member function to insure that the broken-down representation and the
string representation are consistent. See also
<B><TT>DwMessageComponent::Assemble()</TT></B>.
<P>
<FONT COLOR="teal"><B> DwMessageComponent* <A NAME="Parent">Parent</A>()
</B></FONT>
<P>
Returns the <B><TT>DwMessageComponent</TT></B> object that is the parent
of this object.
<P>
<FONT COLOR="teal"><B> void
<A NAME="SetParent">SetParent</A>(DwMessageComponent* aParent) </B></FONT>
<P>
Sets <B><TT>aParent</TT></B> as the <B><TT>DwMessageComponent</TT></B> object's
parent.
<P>
<FONT COLOR="teal"><B> DwBool <A NAME="IsModified">IsModified</A>() const
</B></FONT>
<P>
Returns 1 if the is-modified flag is set for this
<B><TT>DwMessageComponent</TT></B> object.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetModified">SetModified</A>()
</B></FONT>
<P>
Sets the is-modified (dirty) flag for this
<B><TT>DwMessageComponent</TT></B> object and notifies the object's parent
to also set its is-modified flag.
<P>
<FONT COLOR="teal"><B> int <A NAME="ClassId">ClassId</A>() const </B></FONT>
<P>
Returns an integer id for the object's class.
<P>
<FONT COLOR="teal"><B> const char* <A NAME="ClassName">ClassName</A>() const
</B></FONT>
<P>
Returns the name of the class as a NUL-terminated char string.
<P>
<FONT COLOR="teal"><B> int <A NAME="ObjectId">ObjectId</A>() const
</B></FONT>
<P>
Returns a object id that is unique among all DwMessageComponent objects.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0)
const </B></FONT>
<P>
This virtual function prints debugging information about this object to
<B><TT>aStrm</TT></B>. It will also call <B><TT>PrintDebugInfo()</TT></B>
for any of its child components down to a level of
<B><TT>aDepth</TT></B>.
<P>
This member function is available only in the debug version of the library.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT>
<P>
Aborts if one of the invariants of the object fails. Use this member function
to track down bugs.
<P>
This member function is available only in the debug version of the library.
</BODY></HTML>
|
