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:

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.