## NAME

DwGroup -- Class representing an RFC-822 address group

## SYNOPSIS

    class DW_EXPORT DwGroup : public DwAddress {

    public:

        DwGroup();
        DwGroup(const DwGroup& aGroup);
        DwGroup(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwGroup();
        const DwGroup& operator = (const DwGroup& aGroup);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        const DwString& GroupName() const;
        const DwString& Phrase() const;
        void SetGroupName(const DwString& aName);
        void SetPhrase(const DwString& aPhrase);
        DwMailboxList& MailboxList() const;
        static DwGroup* NewGroup(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwGroup* (*sNewGroup)(const DwString&, DwMessageComponent*);

    protected:

        DwMailboxList* mMailboxList;

    public:

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

    protected:

        void _PrintDebugInfo(ostream& aStrm) const;
    };

## DESCRIPTION

`DwGroup` represents a group as described in RFC-822. A group contains a group name and a (possibly empty) list of mailboxes. In MIME++, a `DwGroup` object contains a string for the group name and a `DwMailboxList` object for the list of mailboxes.

In the tree (broken-down) representation of message, a `DwGroup` object may be only an intermediate node, having both a parent and a single child node. Its parent node must be a `DwField` or a `DwAddressList`. Its child is a `DwMailboxList`.

A `DwGroup` is a `DwAddress`, and therefore it can be included in a list of `DwAddress` objects. To get the next `DwAddress` object in a list, use the inherited member function `DwAddress::Next()`.

## Public Member Functions

DwGroup()
DwGroup(const DwGroup& aGroup)
DwGroup(const DwString& aStr, DwMessageComponent* aParent=0)

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

The third constructor copies `aStr` to the `DwGroup` 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` or `DwAddressList`.

const DwGroup& operator = (const DwGroup& aGroup)

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

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwGroup` objects. The parse method creates or updates the broken-down representation from the string representation. For `DwGroup` objects, the parse method parses the string representation to extract the group name and to create a `DwMailboxList` object from the list of mailboxes. This member function also calls the `Parse()` member function of the `DwMailboxList` object it creates.

You should call this member function after you set or modify the string representation, and before you access the group name or the mailbox list.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwGroup` 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 group name and mailbox list. Before it builds the string representation, this function calls the `Assemble()` member function of its contained `DwMailboxList` object.

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

const DwString& GroupName() const

Returns the name of the group.

const DwString& Phrase() const

Returns the name of the phrase part of a group as described in RFC-822. The phrase is the same as the group name.

void SetGroupName(const DwString& aName)

Sets the name of the group.

void SetPhrase(const DwString& aPhrase)

Sets the name of the phrase part of a group as described in RFC-822. The phrase is the same as the group name.

DwMailboxList& MailboxList() const

Provides access to the list of mailboxes that is part of a group as described in RFC-822.

static DwGroup* NewGroup(const DwString& aStr, DwMessageComponent* aParent)

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

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

## Protected Data Members

DwMailboxList* mMailboxList

Points to the `DwMailboxList` object.