diff options
Diffstat (limited to 'mimelib/doc/msgcmp.html')
| -rw-r--r-- | mimelib/doc/msgcmp.html | 298 |
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& 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> |