DwMailbox Man Page

## NAME

DwMailbox -- Class representing an RFC-822 mailbox

## SYNOPSIS

    class DW_CORE_EXPORT DwMailbox : public DwAddress {

    public:

        DwMailbox();
        DwMailbox(const DwMailbox& aMailbox);
        DwMailbox(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwMailbox();
        const DwMailbox& operator = (const DwMailbox& aMailbox);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        const DwString& FullName() const;
        void SetFullName(const DwString& aFullName);
        void GetFullName(DwString& aFullName, DwString& aCharset) const;
        void SetFullName(const DwString& aFullName, const DwString& aCharset,
            int aEncoding='Q');
        const DwString& Route() const;
        void SetRoute(const DwString& aRoute);
        const DwString& LocalPart() const;
        void SetLocalPart(const DwString& aLocalPart);
        const DwString& Domain() const;
        void SetDomain(const DwString& aDomain);
        static DwMailbox* NewMailbox(const DwString& aStr, DwMessageComponent*
            aParent);
        static DwMailbox* (*sNewMailbox)(const DwString&, DwMessageComponent*);

    public:

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

    protected:

        void _PrintDebugInfo(DW_STD ostream& aStrm) const;
        void _SetFullName(const DwString& aFullName);
    };

## DESCRIPTION

RFC-822 defines a mailbox as an entity that can be the recipient of a message. A mailbox is more specific than an address, which may be either a mailbox or a group. An RFC-822 mailbox contains a full name, a local-part, an optional route, and a domain. For example, in the mailbox

Joe Schmoe <jschmoe@aol.com>

"Joe Schmoe" is the full name, "jschmoe" is the local-part, and "aol.com" is the domain. The optional route is rarely seen in current usage, and is deprecated according to RFC-1123.

In MIME++, an RFC-822 mailbox is represented by a `DwMailbox` object. `DwMailbox` is a subclass of `DwAddress`, which reflects the fact that a mailbox is also an address. A `DwMailbox` contains strings representing the full name, local-part, route, and domain of a mailbox.

In the tree (broken-down) representation of message, a `DwMailbox` object may be only a leaf node, having a parent but no child nodes. Its parent node must be a `DwField`, a `DwAddressList`, or a `DwMailboxList` object.

`DwMailbox` has member functions for getting or setting the strings it contains.

## Public Member Functions

DwMailbox()
DwMailbox(const DwMailbox& aMailbox)
DwMailbox(const DwString& aStr, DwMessageComponent* aParent=0)

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

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

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

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwMailbox` objects. The parse method creates or updates the broken-down representation from the string representation. For `DwMailbox` objects, the parse method parses the string representation into the substrings for the full name, local-part, route, and domain.

You should call this member function after you set or modify the string representation, and before you retrieve the full name, local-part, route, or domain.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwMailbox` objects. The assemble method creates or updates the string representation from the broken-down representation. For `DwMailbox` objects, the assemble method builds the string representation from the full name, local-part, route, and domain strings.

You should call this member function after you modify the full name, local-part, route, or domain, 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 `DwMailbox` on the free store that has the same value as this `DwMailbox` object. The basic idea is that of a virtual copy constructor.

const DwString& FullName() const

Returns the full name for this `DwMailbox` object.

void SetFullName(const DwString& aFullName)
void SetFullName(const DwString& aFullName, const DwString& aCharset, int aEncoding='Q')

Sets the full name for this `DwMailbox` object. Sets the full name for this `DwMailbox` object.

void GetFullName(DwString& aFullName, DwString& aCharset) const

Gets the full name for this `DwMailbox` object.

const DwString& Route() const

Returns the route for this `DwMailbox` object.

void SetRoute(const DwString& aRoute)

Sets the route for this `DwMailbox` object.

const DwString& LocalPart() const

Returns the local-part for this `DwMailbox` object.

void SetLocalPart(const DwString& aLocalPart)

Sets the local-part for this `DwMailbox` object.

const DwString& Domain() const

Returns the domain for this `DwMailbox` object.

void SetDomain(const DwString& aDomain)

Sets the domain for this `DwMailbox` object.

static DwMailbox* NewMailbox(const DwString& aStr, DwMessageComponent* aParent)

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

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

## Protected Member Functions

void _SetFullName(const DwString& aFullName)