DwMailboxList Man Page

## NAME

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

## SYNOPSIS

    class DW_CORE_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;
        int NumMailboxes() const;
        void AddMailbox(DwMailbox* aMailbox);
        void DeleteAllMailboxes();
        DwMailbox& MailboxAt(int aIndex) const;
        void InsertMailboxAt(int aIndex, DwMailbox* aMailbox);
        DwMailbox* RemoveMailboxAt(int aIndex);
        static DwMailboxList* NewMailboxList(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwMailboxList* (*sNewMailboxList)(const DwString&,
            DwMessageComponent*);

    protected:

        void _CopyMailboxes(const DwMailboxList& aList);
        void _AddMailbox(DwMailbox* aMailbox);
        void _InsertMailboxAt(int aIndex, DwMailbox* aMbox);
        void _DeleteAllMailboxes();

    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

`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. `DwMailboxList` 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.

int NumMailboxes() const

Returns the number of `DwMailbox` objects contained in this `DwMailboxList` object.

void AddMailbox(DwMailbox* aMailbox)

Appends a `DwMailbox` object to the list managed by this `DwMailboxList` object.

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

void DeleteAllMailboxes()

Removes and deletes all `DwMailbox` objects contained in this `DwMailboxList` object.

DwMailbox& MailboxAt(int aIndex) const

Returns the `DwMailbox` object at position `aIndex` in this `DwMailboxList` 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` < `NumMailboxes()`.

void InsertMailboxAt(int aIndex, DwMailbox* aMailbox)

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

Any `DwMailbox` objects contained in a `DwMailboxList` object's list will be deleted by the `DwMailboxList` 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` <= `NumMailboxes()`.

DwMailbox* RemoveMailboxAt(int aIndex)

Removes the `DwMailbox` object at position `aIndex` from the list and returns it. If `aIndex` is less than `NumMailboxes()-1`, then any `DwMailbox` objects at a position greater than `aIndex` will be shifted up in the list after the requested `DwMailbox` 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` < `NumMailboxes()`.

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(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 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 _CopyMailboxes(const DwMailboxList& aList)

Copies the list of `DwMailbox` objects from `aList`.

void _AddMailbox(DwMailbox* aMailbox)

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

void _InsertMailboxAt(int aIndex, DwMailbox* aMbox)

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

void _DeleteAllMailboxes()

Deletes all mailboxes. Differs from `DeleteMailboxes()` in that it does not set the is-modified flag.