NAME

DwAddressList -- Class representing a list of RFC-822 addresses

SYNOPSIS

class DW_EXPORT DwAddressList : public DwFieldBody {

public:

    DwAddressList();
    DwAddressList(const DwAddressList& aList);
    DwAddressList(const DwString& aStr, DwMessageComponent* aParent=0);
    virtual ~DwAddressList();
    const DwAddressList& operator = (const DwAddressList& aList);
    virtual void Parse();
    virtual void Assemble();
    virtual DwMessageComponent* Clone() const;
    DwAddress* FirstAddress() const;
    void Add(DwAddress* aAddr);
    void Remove(DwAddress* aAddr);
    void DeleteAll();
    static DwAddressList* NewAddressList(const DwString& aStr,
        DwMessageComponent* aParent);
    static DwAddressList* (*sNewAddressList)(const DwString&,
        DwMessageComponent*);

protected:

    DwAddress* mFirstAddress;

public:

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

protected:

    void _PrintDebugInfo(ostream& aStrm) const;
};

DESCRIPTION

DwAddressList represents a list of addresses as described in RFC-822. In MIME++, DwAddressList is a container for objects of type DwAddress, 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 ``To'' header field, have a list of addresses as their field bodies.

Public Member Functions

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

The first constructor is the default constructor, which sets the DwAddressList 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 DwAddress objects from aList. The tqparent of the new DwAddressList object is set to NULL.

The third constructor copies aStr to the DwAddressList 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 DwAddressList& operator = (const DwAddressList& aList)

This is the assignment operator, which performs a deep copy of aList. The tqparent node of the DwAddressList object is not changed.

virtual void Parse()

This virtual function, inherited from DwMessageComponent, executes the parse method for DwAddressList objects. The parse method creates or updates the broken-down representation from the string representation. For DwAddressList objects, the parse method parses the string representation to create a list of DwAddress objects. This member function also calls the Parse() member function of each DwAddress 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 DwAddress objects.

This function clears the is-modified flag.

virtual void Assemble()

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

You should call this member function after you set or modify any of the contained DwAddress 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 DwAddressList on the free store that has the same value as this DwAddressList object. The basic idea is that of a virtual copy constructor.

DwAddress* FirstAddress() const

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

void Add(DwAddress* aAddr)

Adds aAddr to the end of the list of DwAddress objects maintained by this DwAddressList object.

void Remove(DwAddress* aAddr)

Removes aAddr from the list of DwAddress objects maintained by this DwAddressList object. The DwAddress object is not deleted by this member function.

void DeleteAll()

Removes and deletes all DwAddress objects from the list maintained by this DwAddressList object.

static DwAddressList* NewAddressList(const DwString& aStr, DwMessageComponent* aParent)

Creates a new DwAddressList object on the free store. If the static data member sNewAddressList is NULL, this member function will create a new DwAddressList and return it. Otherwise, NewAddressList() will call the user-supplied function pointed to by sNewAddressList, which is assumed to return an object from a class derived from DwAddressList, 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 DwAddressList* (*sNewAddressList)(const DwString&, DwMessageComponent*)

If sNewAddressList is not NULL, it is assumed to point to a user-supplied function that returns a pointer to an object from a class derived from DwAddressList.

Protected Data Members

DwAddress* mFirstAddress

Points to first DwMailbox object in list.