summaryrefslogtreecommitdiffstats
path: root/mimelib/doc/entity.html
blob: 9a2d00187758f09a1b0727fc376b7d995ffd85f7 (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
<HTML>
<HEAD>
  <TITLE> DwEntity Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
  <FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwEntity -- Abstract class representing a MIME entity
<H2>
  <FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>class DW_EXPORT DwEntity : public <A HREF="msgcmp.html">DwMessageComponent</A> {

public:

    <A HREF="entity.html#DwEntity">DwEntity</A>();
    <A HREF="entity.html#DwEntity">DwEntity</A>(const DwEntity&amp; aEntity);
    <A HREF="entity.html#DwEntity">DwEntity</A>(const DwString&amp; aStr, DwMessageComponent* aParent=0);
    virtual ~DwEntity();
    const DwEntity&amp; <A HREF="entity.html#op_eq">operator =</A> (const DwEntity&amp; aEntity);
    virtual void <A HREF="entity.html#Parse">Parse</A>();
    virtual void <A HREF="entity.html#Assemble">Assemble</A>();
    DwHeaders&amp; <A HREF="entity.html#Headers">Headers</A>() const;
    DwBody&amp; <A HREF="entity.html#Body">Body</A>() const;

protected:

    DwHeaders* mHeaders;
    DwBody*    mBody;

public:

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

protected:

    void _PrintDebugInfo(ostream&amp; aStrm) const;
};
</PRE>
<H2>
  <FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
RFC-2045 defines an <I>entity</I> as either a <I>message</I> or a <I>body
part</I>, both of which have a collection of headers and a <I>body</I>. In
MIME++, an entity is represented by the class <B><TT>DwEntity</TT></B>, which
tqcontains both a <B><TT><A HREF="headers.html">DwHeaders</A></TT></B> object
and a <B><TT><A HREF="body.html">DwBody</A></TT></B> object.
<P>
In the tree (broken-down) representation of message, a
<B><TT>DwEntity</TT></B> object may be either a root node, having child nodes
but no parent node, or an intermediate node, having both a parent node and
child nodes. A <B><TT>DwEntity</TT></B> object that is a root node must also
be a <B><TT><A HREF="message.html">DwMessage</A></TT></B> object. If a
<B><TT>DwEntity</TT></B> object is an intermediate node, its parent must
be a <B><TT>DwBody</TT></B> object. The child nodes of a
<B><TT>DwEntity</TT></B> object are the <B><TT>DwHeaders</TT></B> and
<B><TT>DwBody</TT></B> objects it tqcontains.
<P>
Since <B><TT>DwEntity</TT></B> is an abstract base class, you cannot create
instances of it directly. <B><TT>DwEntity</TT></B> has two derived classes,
<B><TT><A HREF="message.html">DwMessage</A></TT></B> and
<B><TT><A HREF="bodypart.html">DwBodyPart</A></TT></B>, which are concrete
classes.
<P>
To access the contained <B><TT>DwHeaders</TT></B> object, use the member
function <B><TT>Headers()</TT></B>. To access the contained
<B><TT>DwBody</TT></B> object, use the member function
<B><TT>Body()</TT></B>.
<H2>
  <FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwEntity">DwEntity</A>() <BR>
DwEntity(const DwEntity&amp; aEntity) <BR>
DwEntity(const DwString&amp; aStr, DwMessageComponent* aParent=0) </B></FONT>
<P>
The first constructor is the default constructor, which sets the
<B><TT>DwEntity</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 a deep copy
of <B><TT>aEntity</TT></B>. The parent of the new
<B><TT>DwEntity</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>DwEntity</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>DwBody</TT></B>.
<P>
<FONT COLOR="teal"><B> const DwEntity&amp; <A NAME="op_eq">operator =</A>
(const DwEntity&amp; aEntity) </B></FONT>
<P>
This is the assignment operator, which performs a deep copy of
<B><TT>aEntity</TT></B>. The parent node of the <B><TT>DwEntity</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>DwEntity</TT></B> objects. The parse
method creates or updates the broken-down representation from the string
representation. For <B><TT>DwEntity</TT></B> objects, the parse method parses
the string representation and sets the values of the
<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects it tqcontains.
This member function also calls the <B><TT>Parse()</TT></B> member functions
of the contained <B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects.
<P>
You should call this member function after you set or modify the string
representation, and before you access either the contained headers or body.
<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>DwEntity</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 string representations of the contained
<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects. This member
function calls the <B><TT>Assemble()</TT></B> member functions of its
<B><TT>DwHeaders</TT></B> and <B><TT>DwBody</TT></B> objects.
<P>
You should call this member function after you modify either the contained
headers or body, and before you retrieve the string representation.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> Dw<A NAME="Headers">Headers</A>&amp; Headers() const
</B></FONT>
<P>
This function returns the <B><TT>DwHeaders</TT></B> object contained by this
object.
<P>
<FONT COLOR="teal"><B> Dw<A NAME="Body">Body</A>&amp; Body() const
</B></FONT>
<P>
This function returns the <B><TT>DwBody</TT></B> object contained by this
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.
<P>
</BODY></HTML>