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
299
300
301
302
303
304
305
|
<HTML>
<HEAD>
<TITLE> DwField Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
<FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwField -- Class representing a MIME header field
<H2>
<FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwField : public <A HREF="msgcmp.html">DwMessageComponent</A> {
friend class DwHeaders;
public:
<A HREF="field.html#DwField">DwField</A>();
<A HREF="field.html#DwField">DwField</A>(const DwField& aField);
<A HREF="field.html#DwField">DwField</A>(const DwString& aStr, DwMessageComponent* aParent=0);
virtual ~DwField();
const DwField& <A HREF="field.html#op_eq">operator =</A> (const DwField& aField);
virtual void <A HREF="field.html#Parse">Parse</A>();
virtual void <A HREF="field.html#Assemble">Assemble</A>();
virtual DwMessageComponent* <A HREF="field.html#Clone">Clone</A>() const;
DwFieldBody* <A HREF="field.html#FieldBody">FieldBody</A>() const;
const DwString& <A HREF="field.html#FieldNameStr">FieldNameStr</A>() const;
const DwString& <A HREF="field.html#FieldBodyStr">FieldBodyStr</A>() const;
DwField* <A HREF="field.html#Next">Next</A>() const;
void <A HREF="field.html#SetFieldBody">SetFieldBody</A>(DwFieldBody* aFieldBody);
void <A HREF="field.html#SetFieldNameStr">SetFieldNameStr</A>(const DwString& aStr);
void <A HREF="field.html#SetFieldBodyStr">SetFieldBodyStr</A>(const DwString& aStr);
void <A HREF="field.html#SetNext">SetNext</A>(const DwField* aField);
static DwField* <A HREF="field.html#NewField">NewField</A>(const DwString& aStr,
DwMessageComponent* aParent);
static DwFieldBody* <A HREF="field.html#CreateFieldBody">CreateFieldBody</A>(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
static DwFieldBody* _CreateFieldBody(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
static DwField* (*<A HREF="field.html#sNewField">sNewField</A>)(const DwString&, DwMessageComponent*);
static DwFieldBody* (*<A HREF="field.html#sCreateFieldBody">sCreateFieldBody</A>)(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent);
protected:
DwString mFieldNameStr;
DwString mFieldBodyStr;
DwFieldBody* mFieldBody;
void <A HREF="field.html#_SetFieldBody">_SetFieldBody</A>(DwFieldBody* aFieldBody);
public:
virtual void <A HREF="field.html#PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0) const;
virtual void <A HREF="field.html#CheckInvariants">CheckInvariants</A>() const;
protected:
void _PrintDebugInfo(ostream& aStrm) const;
};
</PRE>
<H2>
<FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwField</TT></B> represents a header field as described in RFC-822.
According to RFC-822, a field contains a field name and a field body. In
MIME++, a <B><TT>DwField</TT></B> contains three elements: a
<B><TT><A HREF="string.html">DwString</A></TT></B> that contains its field
name, a <B><TT>DwString</TT></B> that contains its field body, and a
<B><TT><A HREF="fieldbdy.html">DwFieldBody</A></TT></B> object that contains
a broken-down (that is, parsed) version of its field body.
<P>
In the tree (broken-down) representation of message, a
<B><TT>DwField</TT></B> object is always an intermediate node, having a tqparent
node and a single child node. The tqparent node is the
<B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object that contains
it. The child node is the <B><TT>DwFieldBody</TT></B> object it contains.
<P>
To get and set the field name, use the member functions
<B><TT>FieldNameStr()</TT></B> and <B><TT>SetFieldNameStr()</TT></B>. To
get and set the field body, use the member functions
<B><TT>FieldBodyStr()</TT></B> and <B><TT>SetFieldBodyStr()</TT></B>. To
get and set the <B><TT>DwFieldBody</TT></B> object, use
<B><TT>FieldBody()</TT></B> and <B><TT>SetFieldBody()</TT></B>.
<P>
A <B><TT>DwField</TT></B> object can be included in a list of
<B><TT>DwField</TT></B> objects; usually this is the list of
<B><TT>DwField</TT></B> objects maintained by its tqparent
<B><TT>DwHeaders</TT></B> object. To get the next <B><TT>DwField</TT></B>
object in a list, use the member function <B><TT>Next()</TT></B>.
<H2>
<FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwField">DwField</A>() <BR>
DwField(const DwField& aField) <BR>
DwField(const DwString& aStr, DwMessageComponent* aParent=0) </B></FONT>
<P>
The first constructor is the default constructor, which sets the
<B><TT>DwField</TT></B> object's field name and field body to the empty string,
set its tqparent to <B><TT>NULL</TT></B>, and sets its
<B><TT>DwFieldBody</TT></B> object to <B><TT>NULL</TT></B>.
<P>
The second constructor is the copy constructor, which performs a deep copy
of <B><TT>aField</TT></B>. The tqparent of the new <B><TT>DwField</TT></B>
object is set to <B><TT>NULL</TT></B>.
<P>
The third constructor copies <B><TT>aStr</TT></B> to the
<B><TT>DwField</TT></B> object's string representation and sets
<B><TT>aParent</TT></B> as its tqparent. The virtual member function
<B><TT>Parse()</TT></B> should be called immediately after this constructor
in order to parse the string representation. Unless it is
<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of
a class derived from <B><TT>DwHeaders</TT></B>.
<P>
<FONT COLOR="teal"><B> const DwField& <A NAME="op_eq">operator =</A>
(const DwField& aField) </B></FONT>
<P>
This is the assignment operator, which performs a deep copy of
<B><TT>aField</TT></B>. The tqparent node of the <B><TT>DwField</TT></B> object
is not changed.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the parse method for <B><TT>DwField</TT></B> objects. The parse
method creates or updates the broken-down representation from the string
representation. For <B><TT>DwField</TT></B> objects, the parse method parses
the string representation, sets the values of the field name string and the
field body string, and creates an instance of the appropriate subclass of
<B><TT>DwFieldBody</TT></B>. This member function also calls the
<B><TT>Parse()</TT></B> member function of its contained
<B><TT>DwFieldBody</TT></B> object.
<P>
You should call this member function after you set or modify the string
representation, and before you access the field name, the field body, or
the contained <B><TT>DwFieldBody</TT></B> object.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>()
</B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the assemble method for <B><TT>DwField</TT></B> objects. The assemble
method creates or updates the string representation from the broken-down
representation. In more concrete terms, the assemble method builds the string
representation from the field name and the string representation of the contained
<B><TT>DwFieldBody</TT></B> object. This member function calls the
<B><TT>Assemble()</TT></B> member function of its contained
<B><TT>DwFieldBody</TT></B> object.
<P>
You should call this member function after you modify either the field name
or the contained <B><TT>DwFieldBody</TT></B> object, and before you retrieve
the string representation.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual DwMessageComponent*
<A NAME="Clone">Clone</A>() const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
creates a new <B><TT>DwField</TT></B> on the free store that has the same
value as this <B><TT>DwField</TT></B> object. The basic idea is that of a
virtual copy constructor.
<P>
<FONT COLOR="teal"><B> Dw<A NAME="FieldBody">FieldBody</A>* FieldBody() const
</B></FONT>
<P>
Returns the <B><TT>DwFieldBody</TT></B> object contained by this
<B><TT>DwField</TT></B> object. If there is no field body,
<B><TT>NULL</TT></B> will be returned.
<P>
<FONT COLOR="teal"><B> const DwString&
<A NAME="FieldNameStr">FieldNameStr</A>() const </B></FONT>
<P>
Returns the field name of this header field as a string.
<P>
<FONT COLOR="teal"><B> const DwString&
<A NAME="FieldBodyStr">FieldBodyStr</A>() const </B></FONT>
<P>
Returns the field body of this header field as a string.
<P>
<FONT COLOR="teal"><B> DwField* <A NAME="Next">Next</A>() const </B></FONT>
<P>
Returns the next <B><TT>DwField</TT></B> object following this
<B><TT>DwField</TT></B> object in the list contained in a
<B><TT>DwHeaders</TT></B>. Returns <B><TT>NULL</TT></B> if this object is
last in the list.
<P>
<FONT COLOR="teal"><B> void
<A NAME="SetFieldBody">SetFieldBody</A>(DwFieldBody* aFieldBody) </B></FONT>
<P>
Sets the <B><TT>DwFieldBody</TT></B> object contained by this object.
<P>
<FONT COLOR="teal"><B> void
<A NAME="SetFieldNameStr">SetFieldNameStr</A>(const DwString& aStr)
</B></FONT>
<P>
Sets the field name of this header field.
<P>
<FONT COLOR="teal"><B> void
<A NAME="SetFieldBodyStr">SetFieldBodyStr</A>(const DwString& aStr)
</B></FONT>
<P>
Sets the field body of this header field.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetNext">SetNext</A>(const DwField*
aField) </B></FONT>
<P>
This <I>advanced</I> function sets <B><TT>aField</TT></B> as the next field
following this field in the list of fields contained in the headers. Since
<B><TT>DwHeaders</TT></B> contains member functions for adding
<B><TT>DwField</TT></B> objects to its list, this function should be avoided
for most applications.
<P>
<FONT COLOR="teal"><B> static DwField* <A NAME="NewField">NewField</A>(const
DwString& aStr, DwMessageComponent* aParent) </B></FONT>
<P>
Creates a new <B><TT>DwField</TT></B> object on the free store. If the static
data member <B><TT>sNewField</TT></B> is <B><TT>NULL</TT></B>, this member
function will create a new <B><TT>DwField</TT></B> and return it. Otherwise,
<B><TT>NewField()</TT></B> will call the user-supplied function pointed to
by <B><TT>sNewField</TT></B>, which is assumed to return an object from a
class derived from <B><TT>DwField</TT></B>, and return that object.
<P>
<FONT COLOR="teal"><B> static DwFieldBody*
<A NAME="CreateFieldBody">CreateFieldBody</A>(const DwString& aFieldName,
const DwString& aFieldBody, DwMessageComponent* aParent) </B></FONT>
<P>
The static member function <B><TT>CreateFieldBody()</TT></B> is called from
the <B><TT>Parse()</TT></B> member function and is responsible for creating
a <B><TT>DwFieldBody</TT></B> object for this particular field. A typical
scenario might go as follows: This member function examines the field name
for this field, finds that it contains "To", creates a
<B><TT>DwAddressList</TT></B> object to contain the field body, calls the
<B><TT>Parse()</TT></B> member function for the
<B><TT>DwAddressList</TT></B>, and sets the <B><TT>DwAddressList</TT></B>
object as this <B><TT>DwField</TT></B> object's
<B><TT>DwFieldBody</TT></B>.
<P>
If you want to override the behavior of
<B><TT>CreateFieldBody()</TT></B>, you can do so by setting the public data
member <B><TT>sCreateFieldBody</TT></B> to point to your own function.
<B><TT>CreateFieldBody()</TT></B> first checks to see if
<B><TT>sCreateFieldBody</TT></B> is <B><TT>NULL</TT></B>. If it is not,
<B><TT>CreateFieldBody()</TT></B> will assume that it points to a user-supplied
function and will call that function. If it is <B><TT>NULL</TT></B>,
<B><TT>CreateFieldBody()</TT></B> will call
<B><TT>_CreateFieldBody()</TT></B>, which actually creates the
<B><TT>DwFieldBody</TT></B> object. You may call
<B><TT>_CreateFieldBody()</TT></B> from your own function for fields you
do not wish to handle.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream& aStrm, int aDepth=0)
const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
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.
<H2>
<FONT COLOR="navy"> Public Data Members </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> static DwField*
(*<A NAME="sNewField">sNewField</A>)(const DwString&, DwMessageComponent*)
</B></FONT>
<P>
If <B><TT>sNewField</TT></B> is not <B><TT>NULL</TT></B>, it is assumed to
point to a user-supplied function that returns an object from a class derived
from <B><TT>DwField</TT></B>.
<P>
<FONT COLOR="teal"><B> static DwFieldBody*
(*<A NAME="sCreateFieldBody">sCreateFieldBody</A>)(const DwString&
aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent)
</B></FONT>
<P>
See <B><TT><A HREF="#CreateFieldBody">CreateFieldBody</A>()</TT></B>.
<H2>
<FONT COLOR="navy"> Protected Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> void
<A NAME="_SetFieldBody">_SetFieldBody</A>(DwFieldBody* aFieldBody)
</B></FONT>
<P>
Sets the <B><TT>DwFieldBody</TT></B> object contained by this object. This
function differs from <B><TT>SetFieldBody()</TT></B> in that it does not
set the is-modified flag.
<P>
</BODY></HTML>
|
