summaryrefslogtreecommitdiffstats
path: root/mimelib/doc/msgcmp.html
diff options
context:
space:
mode:
Diffstat (limited to 'mimelib/doc/msgcmp.html')
-rw-r--r--mimelib/doc/msgcmp.html298
1 files changed, 298 insertions, 0 deletions
diff --git a/mimelib/doc/msgcmp.html b/mimelib/doc/msgcmp.html
new file mode 100644
index 000000000..48a7ab549
--- /dev/null
+++ b/mimelib/doc/msgcmp.html
@@ -0,0 +1,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&amp; aCmp);
+ <A HREF="msgcmp.html#DwMessageComponent">DwMessageComponent</A>(const DwString&amp; aStr, DwMessageComponent* aParent=0);
+ virtual ~DwMessageComponent();
+ const DwMessageComponent&amp; <A HREF="msgcmp.html#op_eq">operator =</A> (const DwMessageComponent&amp; 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&amp; aStr);
+ void <A HREF="msgcmp.html#FromString">FromString</A>(const char* aCstr);
+ const DwString&amp; <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&amp; aStrm, int aDepth=0) const;
+ virtual void <A HREF="msgcmp.html#CheckInvariants">CheckInvariants</A>() const;
+
+protected:
+
+ void _PrintDebugInfo(ostream&amp; 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&amp;)</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&amp; aCmp) <BR>
+DwMessageComponent(const DwString&amp; 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&amp; <A NAME="op_eq">operator
+=</A> (const DwMessageComponent&amp; 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&amp; 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&amp; <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&amp; 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>