DwMessageComponent Man Page

## NAME

DwMessageComponent -- Abstract base class for all message components

## SYNOPSIS

    class DW_CORE_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,
            kCidStamp,
            kCidText,
            kCidEncodedWord
        };
        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() const;
        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(DW_STD ostream& aStrm, int aDepth=0) const;
        virtual void CheckInvariants() const;

    protected:

        void _PrintDebugInfo(DW_STD 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()` 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() const

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 true value (`DwTrue`) 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(DW_STD 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.