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.