DwBody Man Page

## NAME

DwBody -- Class representing a MIME message body

## SYNOPSIS

    class DW_CORE_EXPORT DwBody : public DwMessageComponent {

    public:

        DwBody();
        DwBody(const DwBody& aBody);
        DwBody(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwBody();
        const DwBody& operator = (const DwBody& aBody);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        int NumBodyParts() const;
        void AddBodyPart(DwBodyPart* aPart);
        void DeleteAllBodyParts();
        DwBodyPart& BodyPartAt(int aIndex) const;
        void InsertBodyPartAt(int aIndex, DwBodyPart* aPart);
        DwBodyPart* RemoveBodyPartAt(int aIndex);
        DwMessage* Message() const;
        void SetMessage(DwMessage* aMessage);
        const DwString& Preamble() const;
        void SetPreamble(const DwString& aStr);
        const DwString& Epilogue() const;
        void SetEpilogue(const DwString& aStr);
        static DwBody* NewBody(const DwString& aStr, DwMessageComponent* aParent);
        static DwBody* (*sNewBody)(const DwString&, DwMessageComponent*);

    protected:

        void _CopyBodyParts(const DwBody& aBody);
        void _AddBodyPart(DwBodyPart* aPart);
        void _InsertBodyPartAt(int aIndex, DwBodyPart* aPart);
        void _DeleteAllBodyParts();
        void _SetMessage(DwMessage* aMessage);

    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

`DwBody` represents a body, as described in RFC-2045. A body is always part of an entity, which could be either a message or a body part. An entity has a collection of header fields and a body. If the content type of a body is ``multipart,'' then the body contains one or more body parts. If the content type is ``message,'' then the body contains an encapsulated message. In all content types, the body contains a string of characters.

In MIME++, a `DwBody` object is contained in a `DwEntity` object. The `DwBody` object may contain a discrete body consisting only of a string of characters, or it may be a composite body, consisting of several contained `DwBodyPart` objects or a single contained `DwMessage` object. The only reliable way to determine the type of `DwBody` is to access the Content-Type header field from the `DwHeaders` object of the `DwEntity` that contains it. For this reason, a `DwBody` should always be part of a `DwEntity`.

In the tree (broken-down) representation of a message, a `DwBody` object can be an intermediate node, having both a parent node and one or more child nodes, or a leaf node, having a parent but no child nodes. In either case, the parent node is the `DwEntity` object that contains it. If it is an intermediate node, it must be of type multipart with `DwBodyPart` objects as child nodes, or of type message with a single `DwMessage` object as its child node. (See the man page for `DwMessageComponent` for a discussion of the tree representation of a message.)

Normally, you do not create a `DwBody` object directly, but you access it through the `Body()` member function of `DwEntity`, which creates the `DwBody` object for you.

To add a `DwBodyPart` to a multipart `DwBody`, call the member function `AddBodyPart()` or `InsertBodyPartAt()` . To get the number of body parts, call `NumBodyParts()`. To access a particular body part, call `BodyPartAt()`. To remove a single body part without deleting it, call `RemoveBodyPartAt()`. To remove and delete all body parts, call `DeleteAllBodyParts()`.

To get the `DwMessage` contained in a `Body` with message content type, call `Message()`. To set the contained message, call `SetMessage()`.

## Public Member Functions

DwBody()
DwBody(const DwBody& aBody)
DwBody(const DwString& aStr, DwMessageComponent* aParent=0)

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

The third constructor copies `aStr` to the `DwBody` 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 `DwEntity`.

const DwBody& operator = (const DwBody& aBody)

This is the assignment operator, which performs a deep copy of `aBody`. The parent node of the `DwBody` object is not changed.

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwBody` objects. The parse method creates or updates the broken-down representation from the string representation. For a multipart `DwBody` object, the parse method creates a collection of `DwBodyPart` objects. For a message `DwBody`, the parse method creates a single `DwMessage` object. For any other type of `DwBody`, the parse method does nothing. This member function calls the `Parse()` member function of any objects it creates.

Note: If the `DwBody` object has no parent node -- that is, it is not contained by a `DwEntity` object -- then the parse method does nothing, since it is unable to determine the type of body.

You should call this member function after you set or modify the string representation, and before you access a contained `DwBodyPart` or `DwMessage`.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwBody` objects. The assemble method creates or updates the string representation from the broken-down representation. Only `DwBody` objects with content type of multipart or message require assembling. In either case, the `DwBody` object must be able to find the headers of the message or body part that contains it. Therefore, if the `DwBody` object is not the child of a `DwEntity` (i.e., `DwMessage` or `DwBodyPart`) object, the `DwBody` cannot be assembled because the content type cannot be determined.

This function calls the `Parse()` member function of any `DwBodyPart` or `DwMessage` object it contains.

You should call this member function after you add a `DwBodyPart` object to a multipart body, or add a `DwMessage` object to a message body, and before you access the object's string representation.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

This virtual function, inherited from `DwMessageComponent`, creates a new `DwBody` on the free store that has the same value as this `DwBody` object. The basic idea is that of a virtual copy constructor.

int NumBodyParts() const

Returns the number of `DwBodyPart` objects contained in this `DwBody` object.

void AddBodyPart(DwBodyPart* aPart)

Appends a `DwBodyPart` object to the list managed by this `DwBody` object.

Any `DwBodyPart` objects contained in a `DwBody` object's list will be deleted by the `DwBody` object's destructor.

void DeleteAllBodyParts()

Removes and deletes all `DwBodyPart` objects contained in this `DwBody` object.

DwBodyPart& BodyPartAt(int aIndex) const

Returns the `DwBodyPart` object at position `aIndex` in this `DwBody` object's list.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumBodyParts()`.

void InsertBodyPartAt(int aIndex, DwBodyPart* aPart)

Inserts `aPart` into the list of `DwBodyPart` objects at the position given by `aIndex`. A value of zero for `aIndex` will insert `aPart` as the first one in the list; a value of `NumBodyParts()` will insert it as the last one in the list. If `aIndex` is less than `NumBodyParts()`, the `DwBodyPart` objects at position `aIndex` or greater will be shifted down the list to make room to insert `aPart`.

Any `DwBodyPart` objects contained in a `DwBody` object's list will be deleted by the `DwBody` object's destructor.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` <= `NumBodyParts()`.

DwBodyPart* RemoveBodyPartAt(int aIndex)

Removes the `DwBodyPart` object at position `aIndex` from the list and returns it. If `aIndex` is less than `NumBodyParts()-1`, then any `DwBodyPart` objects at a position greater than `aIndex` will be shifted up in the list after the requested `DwBodyPart` is removed.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumBodyParts()`.

DwMessage* Message() const

For a `DwBody` with content type of message, this member function returns the `DwMessage` encapsulated in it.

void SetMessage(DwMessage* aMessage)

For a `DwBody` with content type of message, this member function sets the `DwMessage` object it contains.

The `DwMessage` object will be destroyed by the `DwBody` object's destructor.

const DwString& Preamble() const

Returns the preamble for a multipart body. The preamble is the part of the body that precedes the first body part. It is not normally shown in a message viewer, and usually contains a message that's meaningful to users of non-MIME capable message viewers.

void SetPreamble(const DwString& aStr)

Sets the preamble for a multipart body. The preamble is the part of the body that precedes the first body part. It is not normally shown in a message viewer, and usually contains a message that's meaningful to users of non-MIME capable message viewers.

const DwString& Epilogue() const

Returns the epliogue for a multipart body. The epilogue is the part of the body that follows the last body part. It is not normally shown in a message viewer, and is empty in most messages.

void SetEpilogue(const DwString& aStr)

Sets the epliogue for a multipart body. The epilogue is the part of the body that follows the last body part. It is not normally shown in a message viewer, and is empty in most messages.

static DwBody* NewBody(const DwString& aStr, DwMessageComponent* aParent)

Creates a new `DwBody` object on the free store. If the static data member `sNewBody` is `NULL`, this member function will create a new `DwBody` and return it. Otherwise, `NewBody()` will call the user-supplied function pointed to by `sNewBody`, which is assumed to return an object from a class derived from `DwBody`, and return that object.

virtual void PrintDebugInfo(DW_STD 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.

## Public Data Members

static DwBody* (*sNewBody)(const DwString&, DwMessageComponent*)

If `sNewBody` is not `NULL`, it is assumed to point to a user-supplied function that returns an object from a class derived from `DwBody`.

## Protected Member Functions

void _CopyBodyParts(const DwBody& aBody)

Copies the list of `DwBodyPart` objects from `aBody`.

void _AddBodyPart(DwBodyPart* aPart)

Same as `AddBodyPart()`, but does not set is-modified flag.

void _InsertBodyPartAt(int aIndex, DwBodyPart* aPart)

Performs all the work of adding `DwBodyPart` objects to the list. This function does not set the is-modified flag.

void _DeleteAllBodyParts()

Deletes all body parts. Differs from `DeleteAllBodyParts()` in that it does not set the is-modified flag.

void _SetMessage(DwMessage* aMessage)

Same as `SetMessage()`, but it does not set the is-modified flag.