DwMessageComponent Man Page

From b479c22c713be413b9135be8f1d4e108d33f17f6 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Sun, 6 Oct 2013 10:33:05 -0700 Subject: lurker-2.3 mimelib-3.1.1 --- mimelib/doc/msgcmp.html | 298 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 mimelib/doc/msgcmp.html (limited to 'mimelib/doc/msgcmp.html') diff --git a/mimelib/doc/msgcmp.html b/mimelib/doc/msgcmp.html new file mode 100644 index 0000000..48a7ab5 --- /dev/null +++ b/mimelib/doc/msgcmp.html @@ -0,0 +1,298 @@ + + + DwMessageComponent Man Page + + +

+ NAME +

+DwMessageComponent -- Abstract base class for all message components +

+ SYNOPSIS +

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
+    };
+    DwMessageComponent();
+    DwMessageComponent(const DwMessageComponent& aCmp);
+    DwMessageComponent(const DwString& aStr, DwMessageComponent* aParent=0);
+    virtual ~DwMessageComponent();
+    const DwMessageComponent& operator = (const DwMessageComponent& aCmp);
+    virtual void Parse() = 0;
+    virtual void Assemble() = 0;
+    virtual DwMessageComponent* Clone() const = 0;
+    void FromString(const DwString& aStr);
+    void FromString(const char* aCstr);
+    const DwString& AsString();
+    DwMessageComponent* Parent();
+    void SetParent(DwMessageComponent* aParent);
+    DwBool IsModified() const;
+    void SetModified();
+    int ClassId() const;
+    const char* ClassName() const;
+    int ObjectId() const;
+
+protected:
+
+    DwString mString;
+    DwBool mIsModified;
+    DwMessageComponent* mParent;
+    componentType mClassId;
+    const char* mClassName;
+
+public:
+
+    virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
+    virtual void CheckInvariants() const;
+
+protected:
+
+    void _PrintDebugInfo(ostream& aStrm) const;
+};
+

+ DESCRIPTION +

+DwMessageComponent is the root of an inheritance hierarchy +from which all MIME message components are derived. Thus, +DwMessageComponent defines important features that are inherited +by nearly all other classes that represent components of a MIME message. +These features are the following: +

+ A string representation. The DwMessageComponent class provides + a member function FromString(const DwString&) to set + the string representation and a member function + AsString() to get the string representation. +
+
+ 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. DwMessageComponent 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. +
+
+ A parse method to extract the broken-down representation from the string + representation. In the DwDateTime class, for example, the + parse method extracts the year, month, day, hour, minute, second, and time + zone from the RFC-822 date-time contained in the string representation. + DwMessageComponent provides a pure virtual function + Parse(), which executes the parse method for a derived class. +
+
+ An assemble method to convert the broken-down representation to a string + representation. This is the opposite of the parse method. In the + DwDateTime class, for example, the assemble method creates + an RFC-822 date-time string from values of the year, month, day, hour, + minute, second, and time zone. DwMessageComponent provides + a pure virtual function Assemble(), which executes the assemble + method for a derived class. +
+
+ 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 DwMessageComponent 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. + DwMessageComponent also provides a member function + SetModified() which forces the is-modified flag to be set. +
+
+ 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. +
+
+ 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. DwMessageComponent does not deal directly with children. + Derived classes bear all the responsibility for handling their children. +

+ Public Member Functions +

+ DwMessageComponent() +
+DwMessageComponent(const DwMessageComponent& aCmp)
+DwMessageComponent(const DwString& aStr, DwMessageComponent* aParent=0) + +

+The first constructor is the default constructor, which sets the +DwMessageComponent object's string representation to the +empty string and sets its parent to NULL. +

+The second constructor is the copy constructor, which performs a deep copy +of aCmp. The parent of the new +DwMessageComponent object is set to NULL. +

+The third constructor copies aStr to the new +DwMessageComponent object's string representation and sets +aParent as its parent. In typical cases, the virtual member +function Parse() should be called immediately after this +constructor to parse the new DwMessageComponent object and +all of its children into their broken-down representations. +

+ const DwMessageComponent& operator += (const DwMessageComponent& aCmp) +

+This is the assignment operator, which performs a deep copy of +aCmp. +

+ virtual void Parse() = 0 + +

+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 DwHeaders, the parse method is also responsible +for creating the children of the object. (In the case of +DwHeaders, the children created are the +DwField objects that represent the fields contained +in the headers.) The Parse() function always calls +the Parse() function of all of its children. +

+ virtual void Assemble() = 0 + +

+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 +DwMessageComponent is cleared, the +Assemble() function will return immediately without calling +the Assemble() function of any of its children. +

+ virtual DwMessageComponent* +Clone() const = 0 +

+Creates a new DwMessageComponent 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.'' +

+ void FromString(const +DwString& aStr)
+void FromString(const char* aCstr) +

+Sets the object's string representation. aCstr must be +NUL-terminated. This member function does not invoke the parse method. Typically, +the virtual member function Parse() should be called immediately +after this member function to parse the +DwMessageComponent object and all of its children into their +broken-down representations. See also +DwMessageComponent::Parse() +

+ const DwString& AsString() + +

+Returns the DwMessageComponent object's string representation. +The assemble method is not called automatically. Typically, the +Assemble() 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 +DwMessageComponent::Assemble(). +

+ DwMessageComponent* Parent() + +

+Returns the DwMessageComponent object that is the parent +of this object. +

+ void +SetParent(DwMessageComponent* aParent) +

+Sets aParent as the DwMessageComponent object's +parent. +

+ DwBool IsModified() const + +

+Returns 1 if the is-modified flag is set for this +DwMessageComponent object. +

+ void SetModified() + +

+Sets the is-modified (dirty) flag for this +DwMessageComponent object and notifies the object's parent +to also set its is-modified flag. +

+ int ClassId() const +

+Returns an integer id for the object's class. +

+ const char* ClassName() const + +

+Returns the name of the class as a NUL-terminated char string. +

+ int ObjectId() const + +

+Returns a object id that is unique among all DwMessageComponent objects. +

+ virtual void +PrintDebugInfo(ostream& aStrm, int aDepth=0) +const +

+This virtual function prints debugging information about this object to +aStrm. It will also call PrintDebugInfo() +for any of its child components down to a level of +aDepth. +

+This member function is available only in the debug version of the library. +

+ virtual void +CheckInvariants() const +

+Aborts if one of the invariants of the object fails. Use this member function +to track down bugs. +

+This member function is available only in the debug version of the library. + -- cgit v1.2.3