NAME

DwEntity -- Abstract class representing a MIME entity

SYNOPSIS

class DW_EXPORT DwEntity : public DwMessageComponent {

public:

    DwEntity();
    DwEntity(const DwEntity& aEntity);
    DwEntity(const DwString& aStr, DwMessageComponent* aParent=0);
    virtual ~DwEntity();
    const DwEntity& operator = (const DwEntity& aEntity);
    virtual void Parse();
    virtual void Assemble();
    DwHeaders& Headers() const;
    DwBody& Body() const;

protected:

    DwHeaders* mHeaders;
    DwBody*    mBody;

public:

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

protected:

    void _PrintDebugInfo(ostream& aStrm) const;
};

DESCRIPTION

RFC-2045 defines an entity as either a message or a body part, both of which have a collection of headers and a body. In MIME++, an entity is represented by the class DwEntity, which contains both a DwHeaders object and a DwBody object.

In the tree (broken-down) representation of message, a DwEntity object may be either a root node, having child nodes but no parent node, or an intermediate node, having both a parent node and child nodes. A DwEntity object that is a root node must also be a DwMessage object. If a DwEntity object is an intermediate node, its parent must be a DwBody object. The child nodes of a DwEntity object are the DwHeaders and DwBody objects it contains.

Since DwEntity is an abstract base class, you cannot create instances of it directly. DwEntity has two derived classes, DwMessage and DwBodyPart, which are concrete classes.

To access the contained DwHeaders object, use the member function Headers(). To access the contained DwBody object, use the member function Body().

Public Member Functions

DwEntity()
DwEntity(const DwEntity& aEntity)
DwEntity(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the DwEntity 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 aEntity. The parent of the new DwEntity object is set to NULL.

The third constructor copies aStr to the DwEntity object's string representation and sets aParent as its parent. The virtual member function Parse() should be called immediately after this constructor in order to parse the string representation. Unless it is NULL, aParent should point to an object of a class derived from DwBody.

const DwEntity& operator = (const DwEntity& aEntity)

This is the assignment operator, which performs a deep copy of aEntity. The parent node of the DwEntity object is not changed.

virtual void Parse()

This virtual function, inherited from DwMessageComponent, executes the parse method for DwEntity objects. The parse method creates or updates the broken-down representation from the string representation. For DwEntity objects, the parse method parses the string representation and sets the values of the DwHeaders and DwBody objects it contains. This member function also calls the Parse() member functions of the contained DwHeaders and DwBody objects.

You should call this member function after you set or modify the string representation, and before you access either the contained headers or body.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from DwMessageComponent, executes the assemble method for DwEntity objects. The assemble method creates or updates the string representation from the broken-down representation. In more concrete terms, the assemble method builds the string representation from the string representations of the contained DwHeaders and DwBody objects. This member function calls the Assemble() member functions of its DwHeaders and DwBody objects.

You should call this member function after you modify either the contained headers or body, and before you retrieve the string representation.

This function clears the is-modified flag.

DwHeaders& Headers() const

This function returns the DwHeaders object contained by this object.

DwBody& Body() const

This function returns the DwBody object contained by this object.

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

This virtual function, inherited from DwMessageComponent, 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.