Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da
author: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
committer: toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da> 2009-11-25 17:56:58 +0000
commit: 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree: 67208f7c145782a7e90b123b982ca78d88cc2c87 /mimelib/doc/msgcmp.html
download: tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz
tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip
1 files changed, 298 insertions, 0 deletions
diff --git a/mimelib/doc/msgcmp.html b/mimelib/doc/msgcmp.html
new file mode 100644
index 00000000..48a7ab54
--- /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>
author	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
committer	toma <toma@283d02a7-25f6-0310-bc7c-ecb5cbfe19da>	2009-11-25 17:56:58 +0000
commit	460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 (patch)
tree	67208f7c145782a7e90b123b982ca78d88cc2c87 /mimelib/doc/msgcmp.html
download	tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.tar.gz tdepim-460c52653ab0dcca6f19a4f492ed2c5e4e963ab0.zip