summaryrefslogtreecommitdiffstats
path: root/mimelib/doc/mediatyp.html
blob: 83e5c127aaf4281dae727798dc114ac8d9b77345 (plain)
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
306
307
308
309
310
311
<HTML>
<HEAD>
  <TITLE> DwMediaType Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
  <FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwMediaType -- Class representing a MIME media-type
<H2>
  <FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwMediaType : public <A HREF="fieldbdy.html">DwFieldBody</A> {

public:

    <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>();
    <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>(const DwMediaType&amp; aMediaType);
    <A HREF="mediatyp.html#DwMediaType">DwMediaType</A>(const DwString&amp; aStr, DwMessageComponent* aParent=0);
    virtual ~DwMediaType();
    const DwMediaType&amp; <A HREF="mediatyp.html#op_eq">operator =</A> (const DwMediaType&amp; aMediaType);
    virtual void <A HREF="mediatyp.html#Parse">Parse</A>();
    virtual void <A HREF="mediatyp.html#Assemble">Assemble</A>();
    virtual DwMessageComponent* <A HREF="mediatyp.html#Clone">Clone</A>() const;
    int <A HREF="mediatyp.html#Type">Type</A>() const;
    void <A HREF="mediatyp.html#SetType">SetType</A>(int aType);
    const DwString&amp; <A HREF="mediatyp.html#TypeStr">TypeStr</A>() const;
    void <A HREF="mediatyp.html#SetTypeStr">SetTypeStr</A>(const DwString&amp; aStr);
    int <A HREF="mediatyp.html#Subtype">Subtype</A>() const;
    void <A HREF="mediatyp.html#SetSubtype">SetSubtype</A>(int aSubtype);
    const DwString&amp; <A HREF="mediatyp.html#SubtypeStr">SubtypeStr</A>() const;
    void <A HREF="mediatyp.html#SetSubtypeStr">SetSubtypeStr</A>(const DwString&amp; aStr);
    const DwString&amp; <A HREF="mediatyp.html#Boundary">Boundary</A>() const;
    void <A HREF="mediatyp.html#SetBoundary">SetBoundary</A>(const DwString&amp; aStr);
    virtual void <A HREF="mediatyp.html#CreateBoundary">CreateBoundary</A>(unsigned aLevel=0);
    const DwString&amp; <A HREF="mediatyp.html#Name">Name</A>() const;
    void <A HREF="mediatyp.html#SetName">SetName</A>(const DwString&amp; aStr);
    DwParameter* <A HREF="mediatyp.html#FirstParameter">FirstParameter</A>() const;
    void <A HREF="mediatyp.html#AddParameter">AddParameter</A>(DwParameter* aParam);
    static DwMediaType* <A HREF="mediatyp.html#NewMediaType">NewMediaType</A>(const DwString&amp; aStr,
        DwMessageComponent* aParent);
    static DwMediaType* (*<A HREF="mediatyp.html#sNewMediaType">sNewMediaType</A>)(const DwString&amp;,
        DwMessageComponent*);

protected:

    void _AddParameter(DwParameter* aParam);
    virtual void TypeEnumToStr();
    virtual void TypeStrToEnum();
    virtual void SubtypeEnumToStr();
    virtual void SubtypeStrToEnum();
    void DeleteParameterList();
    void CopyParameterList(DwParameter* aFirst);
    int mType;
    int mSubtype;
    DwString mTypeStr;
    DwString mSubtypeStr;
    DwString mBoundaryStr;
    DwString <A HREF="mediatyp.html#mNameStr">mNameStr</A>;
    DwParameter* mFirstParameter;

public:

    virtual void <A HREF="mediatyp.html#PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; aStrm, int aDepth=0) const;
    virtual void <A HREF="mediatyp.html#CheckInvariants">CheckInvariants</A>() const;

protected:

    void _PrintDebugInfo(ostream&amp; aStrm) const;
};
</PRE>
<H2>
  <FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwMediaType</TT></B> represents a field body for the Content-Type
header field as described in RFC-2045. This field body specifies the kind
of data contained in the body of a message or a body part. A media type is
described by two keywords: a primary type (or just <I>type</I>) and a
<I>subtype</I>. RFC-2046 specifies the seven primary types text, multipart,
message, image, audio, video, and application. RFC-2077 adds the new primary
type model.
<P>
<B><TT>DwMediaType</TT></B> has member functions that allow you to set or
get the type and subtype as either enumerated values or as strings. It also
tqcontains a list of
<B><TT><A HREF="param.html">DwParameter</A></TT></B> objects that represent
the parameters of the field body. You can use convenience functions to directly
access the boundary parameter of a multipart media type, or to access the
name parameter that is often used with several media types, such as
application/octet-stream.
<P>
Some MIME parsers have problems with folded header fields, and this especially
seems to be a problem with the Content-Type field. To disable folding when
the <B><TT>DwMediaType</TT></B> object is assembled, call the inherited member
function <B><TT>DwFieldBody::SetFolding()</TT></B> with an argument of
<B><TT>DwFalse</TT></B>.
<H2>
  <FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwMediaType">DwMediaType</A>() <BR>
DwMediaType(const DwMediaType&amp; aMediaType) <BR>
DwMediaType(const DwString&amp; aStr, DwMessageComponent* aParent=0)
</B></FONT>
<P>
The first constructor is the default constructor, which sets the
<B><TT>DwMediaType</TT></B> object's string representation to the empty string
and sets its parent to <B><TT>NULL</TT></B>.
<P>
The second constructor is the copy constructor, which performs deep copy
of <B><TT>aMediaType</TT></B>. The parent of the new
<B><TT>DwMediaType</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>DwMediaType</TT></B> object's string representation and sets
<B><TT>aParent</TT></B> as its parent. 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>DwField</TT></B>.
<P>
<FONT COLOR="teal"><B> const DwMediaType&amp; <A NAME="op_eq">operator =</A>
(const DwMediaType&amp; aMediaType) </B></FONT>
<P>
This is the assignment operator, which performs a deep copy of
<B><TT>aMediaType</TT></B>. The parent node of the
<B><TT>DwMediaType</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>DwMediaType</TT></B> objects. It should
be called immediately after the string representation is modified and before
the parts of the broken-down representation are accessed.
<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>DwMediaType</TT></B> objects. It
should be called whenever one of the object's attributes is changed in order
to assemble the string representation from its broken-down representation.
It will be called automatically for this object by the parent object's
<B><TT>Assemble()</TT></B> member function if the is-modified flag is set.
<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>DwMediaType</TT></B> object on the free store that has
the same value as this <B><TT>DwMediaType</TT></B> object. The basic idea
is that of a virtual copy constructor.
<P>
<FONT COLOR="teal"><B> int <A NAME="Type">Type</A>() const </B></FONT>
<P>
Returns the primary type as an enumerated value. Enumerated values are defined
for all standard types in the file enum.h. If the type is non-standard,
<B><TT>DwMime::kTypeUnknown</TT></B> is returned. The member function
<B><TT>TypeStr()</TT></B> may be used to get the value of any type, standard
or non-standard, as a string.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetType">SetType</A>(int aType)
</B></FONT>
<P>
Sets the primary type from the enumerated value <B><TT>aType</TT></B>. Enumerated
values are defined for all standard types in the file enum.h. The member
function <B><TT>SetTypeStr()</TT></B> may be used to set the value of any
type, standard or non-standard, from a string.
<P>
<FONT COLOR="teal"><B> const DwString&amp; <A NAME="TypeStr">TypeStr</A>()
const </B></FONT>
<P>
Returns the primary type as a string.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetTypeStr">SetTypeStr</A>(const
DwString&amp; aStr) </B></FONT>
<P>
Sets the primary type from a string.
<P>
<FONT COLOR="teal"><B> int <A NAME="Subtype">Subtype</A>() const </B></FONT>
<P>
Returns the subtype as an enumerated value. Enumerated values are defined
for all standard subtypes in the file enum.h. If the subtype is non-standard,
<B><TT>DwMime::kSubtypeUnknown</TT></B> is returned. The member function
<B><TT>SubtypeStr()</TT></B> may be used to get the value of any subtype,
standard or non-standard, as a string.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetSubtype">SetSubtype</A>(int aSubtype)
</B></FONT>
<P>
Sets the subtype from the enumerated value <B><TT>aSubtype</TT></B>. Enumerated
values are defined for all standard subtypes in the file enum.h. The member
function <B><TT>SetSubtypeStr()</TT></B> may be used to set the value of
any subtype, standard or non-standard, from a string.
<P>
<FONT COLOR="teal"><B> const DwString&amp;
<A NAME="SubtypeStr">SubtypeStr</A>() const </B></FONT>
<P>
Returns the subtype as a string.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetSubtypeStr">SetSubtypeStr</A>(const
DwString&amp; aStr) </B></FONT>
<P>
Sets the subtype from a string.
<P>
<FONT COLOR="teal"><B> const DwString&amp; <A NAME="Boundary">Boundary</A>()
const </B></FONT>
<P>
For the multipart type only, returns the value of the boundary parameter.
This member function is a convenience function that searches the list of
<B><TT>DwParameter</TT></B> objects.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetBoundary">SetBoundary</A>(const
DwString&amp; aStr) </B></FONT>
<P>
For the multipart type only, sets the value of the boundary parameter. This
member function is a convenience function that accesses the list of
<B><TT>DwParameter</TT></B> objects.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="CreateBoundary">CreateBoundary</A>(unsigned aLevel=0) </B></FONT>
<P>
For the multipart type only, creates a boundary string.
<B><TT>aLevel</TT></B> indicates the level of a nested multipart body part;
if it is positive, it is used to form part of the created boundary string.
This member function is a convenience function that accesses the list of
child <B><TT>DwParameter</TT></B> objects.
<P>
<FONT COLOR="teal"><B> const DwString&amp; <A NAME="Name">Name</A>() const
</B></FONT>
<P>
Returns the value of the "name" parameter, if such a parameter is present.
The name parameter is often found in several media types, including the
application/octet-stream media type; it suggests a file name for saving to
a disk file. (The filename parameter in the Content-Disposition header field
is an alternative way to indicate a file name.) This member function is a
convenience function that searches the list of
<B><TT>DwParameter</TT></B> objects.
<P>
<FONT COLOR="teal"><B> void <A NAME="SetName">SetName</A>(const DwString&amp;
aStr) </B></FONT>
<P>
Sets the value of the "name" parameter. If a name parameter is not already
present, it is added. The name parameter is often found in several media
types, including the application/octet-stream media type; it suggests a file
name for saving to a disk file. (The filename parameter in the
Content-Disposition header field is an alternative way to indicate a file
name.) This member function is a convenience function that accesses the list
of <B><TT>DwParameter</TT></B> objects.
<P>
<FONT COLOR="teal"><B> DwParameter*
<A NAME="FirstParameter">FirstParameter</A>() const </B></FONT>
<P>
Returns the first <B><TT>DwParameter</TT></B> object in the list managed
by this <B><TT>DwMediaType</TT></B> object. Use
<B><TT>DwParameter::Next()</TT></B> to iterate through the list.
<P>
<FONT COLOR="teal"><B> void
<A NAME="AddParameter">AddParameter</A>(DwParameter* aParam) </B></FONT>
<P>
Adds a <B><TT>DwParameter</TT></B> object to the list managed by this
<B><TT>DwMediaType</TT></B> object.
<P>
<FONT COLOR="teal"><B> static DwMediaType*
<A NAME="NewMediaType">NewMediaType</A>(const DwString&amp; aStr,
DwMessageComponent* aParent) </B></FONT>
<P>
Creates a new <B><TT>DwMediaType</TT></B> object on the free store. If the
static data member <B><TT>sNewMediaType</TT></B> is <B><TT>NULL</TT></B>,
this member function will create a new <B><TT>DwMediaType</TT></B> and return
it. Otherwise, <B><TT>NewMediaType()</TT></B> will call the user-supplied
function pointed to by <B><TT>sNewMediaType</TT></B>, which is assumed to
return an object from a class derived from <B><TT>DwMediaType</TT></B>, and
return that object.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; 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 DwMediaType*
(*<A NAME="sNewMediaType">sNewMediaType</A>)(const DwString&amp;,
DwMessageComponent*) </B></FONT>
<P>
If <B><TT>sNewMediaType</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>DwMediaType</TT></B>.
</BODY></HTML>