You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
299 lines
13 KiB
299 lines
13 KiB
<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>
|