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 tqcontains 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 tqparent to NULL.

The second constructor is the copy constructor, which copies the string representation and all DwMailbox objects from aList. The tqparent 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 tqparent. 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 tqparent 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.