## 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.