## NAME

DwMailboxList -- Class representing a list of RFC-822 mailboxes

## SYNOPSIS

    class DW_EXPORT DwMailboxList : public DwFieldBody {

    public:

        DwMailboxList();
        DwMailboxList(const DwMailboxList& aList);
        DwMailboxList(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwMailboxList();
        const DwMailboxList& operator = (const DwMailboxList& aList);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        DwMailbox* FirstMailbox() const;
        void Add(DwMailbox* aMailbox);
        void Remove(DwMailbox* aMailbox);
        void DeleteAll();
        static DwMailboxList* NewMailboxList(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwMailboxList* (*sNewMailboxList)(const DwString&,
            DwMessageComponent*);

    protected:

        DwMailbox* mFirstMailbox;
        void _AddMailbox(DwMailbox* aMailbox);
        void _DeleteAll();

    public:

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

    protected:

        void _PrintDebugInfo(ostream& aStrm) const;
    };

## DESCRIPTION

`DwMailboxList` represents a list of mailboxes as described in RFC-822. In MIME++, `DwMailboxList` is a container for objects of type `DwMailbox`, and it contains various member functions to manage its contained objects. `DwAddressList` is also a `DwFieldBody`. This reflects the fact that certain RFC-822 header fields, such as the "From" header field, have a list of mailboxes as their field bodies.

## Public Member Functions

DwMailboxList()
DwMailboxList(const DwMailboxList& aList)
DwMailboxList(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the `DwMailboxList` object's string representation to the empty string and sets its parent to `NULL`.

The second constructor is the copy constructor, which copies the string representation and all `DwMailbox` objects from `aList`. The parent of the new `DwMailboxList` object is set to `NULL`.

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

const DwMailboxList& operator = (const DwMailboxList& aList)

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

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwMailboxList` objects. The parse method creates or updates the broken-down representation from the string representation. For `DwMailboxList` objects, the parse method parses the string representation to create a list of `DwMailbox` objects. This member function also calls the `Parse()` member function of each `DwMailbox` object in its list.

You should call this member function after you set or modify the string representation, and before you access any of the contained `DwMailbox` objects.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwMailboxList` objects. The assemble method creates or updates the string representation from the broken-down representation. For `DwMailboxList` objects, the assemble method builds the string representation from its list of `DwMailbox` objects. Before it builds the string representation for the `DwMailboxList` object, this function first calls the `Assemble()` member function of each `DwMailbox` object in its list.

You should call this member function after you set or modify any of the contained `DwMailbox` objects, and before you retrieve the string representation.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

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

DwMailbox* FirstMailbox() const

Gets the first `DwMailbox` object in the list. Use the member function `DwMailbox::Next()` to iterate. Returns `NULL` if the list is empty.

void Add(DwMailbox* aMailbox)

Adds `aMailbox` to the end of the list of `DwMailbox` objects maintained by this `DwMailboxList` object.

void Remove(DwMailbox* aMailbox)

Removes `aMailbox` from the list of `DwMailbox` objects maintained by this `DwMailboxList` object. The `DwMailbox` object is not deleted by this member function.

void DeleteAll()

Removes and deletes all `DwMailbox` objects from the list maintained by this `DwMailboxList` object.

static DwMailboxList* NewMailboxList(const DwString& aStr, DwMessageComponent* aParent)

Creates a new `DwMailboxList` object on the free store. If the static data member `sNewMailboxList` is `NULL`, this member function will create a new `DwMailboxList` and return it. Otherwise, `NewMailboxList()` will call the user-supplied function pointed to by `sNewMailboxList`, which is assumed to return an object from a class derived from `DwMailboxList`, and return that 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.

## Public Data Members

static DwMailboxList* (*sNewMailboxList)(const DwString&, DwMessageComponent*)

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

## Protected Member Functions

void _AddMailbox(DwMailbox* aMailbox)

Adds a mailbox, but does not set the is-modified flag.

void _DeleteAll()

Removes and deletes all `DwMailbox` objects from the list maintained by this `DwMailboxList` object. Doesn't set the is-modified flag.

## Protected Data Members

DwMailbox* mFirstMailbox

Points to first `DwMailbox` object in list.