DwField Man Page

## NAME

DwField -- Class representing a MIME header field

## SYNOPSIS

    class DW_EXPORT DwField : public DwMessageComponent {

        friend class DwHeaders;

    public:

        DwField();
        DwField(const DwField& aField);
        DwField(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwField();
        const DwField& operator = (const DwField& aField);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        DwFieldBody* FieldBody() const;
        const DwString& FieldNameStr() const;
        const DwString& FieldBodyStr() const;
        DwField* Next() const;
        void SetFieldBody(DwFieldBody* aFieldBody);
        void SetFieldNameStr(const DwString& aStr);
        void SetFieldBodyStr(const DwString& aStr);
        void SetNext(const DwField* aField);
        static DwField* NewField(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwFieldBody* CreateFieldBody(const DwString& aFieldName,
            const DwString& aFieldBody, DwMessageComponent* aParent);
        static DwFieldBody* _CreateFieldBody(const DwString& aFieldName,
            const DwString& aFieldBody, DwMessageComponent* aParent);
        static DwField* (*sNewField)(const DwString&, DwMessageComponent*);
        static DwFieldBody* (*sCreateFieldBody)(const DwString& aFieldName,
            const DwString& aFieldBody, DwMessageComponent* aParent);

    protected:

        DwString mFieldNameStr;
        DwString mFieldBodyStr;
        DwFieldBody* mFieldBody;
        void _SetFieldBody(DwFieldBody* aFieldBody);

    public:

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

    protected:

        void _PrintDebugInfo(ostream& aStrm) const;
    };

## DESCRIPTION

`DwField` represents a header field as described in RFC-822. According to RFC-822, a field contains a field name and a field body. In MIME++, a `DwField` contains three elements: a `DwString` that contains its field name, a `DwString` that contains its field body, and a `DwFieldBody` object that contains a broken-down (that is, parsed) version of its field body.

In the tree (broken-down) representation of message, a `DwField` object is always an intermediate node, having a parent node and a single child node. The parent node is the `DwHeaders` object that contains it. The child node is the `DwFieldBody` object it contains.

To get and set the field name, use the member functions `FieldNameStr()` and `SetFieldNameStr()`. To get and set the field body, use the member functions `FieldBodyStr()` and `SetFieldBodyStr()`. To get and set the `DwFieldBody` object, use `FieldBody()` and `SetFieldBody()`.

A `DwField` object can be included in a list of `DwField` objects; usually this is the list of `DwField` objects maintained by its parent `DwHeaders` object. To get the next `DwField` object in a list, use the member function `Next()`.

## Public Member Functions

DwField()
DwField(const DwField& aField)
DwField(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the `DwField` object's field name and field body to the empty string, set its parent to `NULL`, and sets its `DwFieldBody` object to `NULL`.

The second constructor is the copy constructor, which performs a deep copy of `aField`. The parent of the new `DwField` object is set to `NULL`.

The third constructor copies `aStr` to the `DwField` 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 `DwHeaders`.

const DwField& operator = (const DwField& aField)

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

virtual void Parse()

This virtual function, inherited from `DwMessageComponent`, executes the parse method for `DwField` objects. The parse method creates or updates the broken-down representation from the string representation. For `DwField` objects, the parse method parses the string representation, sets the values of the field name string and the field body string, and creates an instance of the appropriate subclass of `DwFieldBody`. This member function also calls the `Parse()` member function of its contained `DwFieldBody` object.

You should call this member function after you set or modify the string representation, and before you access the field name, the field body, or the contained `DwFieldBody` object.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwField` objects. The assemble method creates or updates the string representation from the broken-down representation. In more concrete terms, the assemble method builds the string representation from the field name and the string representation of the contained `DwFieldBody` object. This member function calls the `Assemble()` member function of its contained `DwFieldBody` object.

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

DwFieldBody* FieldBody() const

Returns the `DwFieldBody` object contained by this `DwField` object. If there is no field body, `NULL` will be returned.

const DwString& FieldNameStr() const

Returns the field name of this header field as a string.

const DwString& FieldBodyStr() const

Returns the field body of this header field as a string.

DwField* Next() const

Returns the next `DwField` object following this `DwField` object in the list contained in a `DwHeaders`. Returns `NULL` if this object is last in the list.

void SetFieldBody(DwFieldBody* aFieldBody)

Sets the `DwFieldBody` object contained by this object.

void SetFieldNameStr(const DwString& aStr)

Sets the field name of this header field.

void SetFieldBodyStr(const DwString& aStr)

Sets the field body of this header field.

void SetNext(const DwField* aField)

This advanced function sets `aField` as the next field following this field in the list of fields contained in the headers. Since `DwHeaders` contains member functions for adding `DwField` objects to its list, this function should be avoided for most applications.

static DwField* NewField(const DwString& aStr, DwMessageComponent* aParent)

Creates a new `DwField` object on the free store. If the static data member `sNewField` is `NULL`, this member function will create a new `DwField` and return it. Otherwise, `NewField()` will call the user-supplied function pointed to by `sNewField`, which is assumed to return an object from a class derived from `DwField`, and return that object.

static DwFieldBody* CreateFieldBody(const DwString& aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent)

The static member function `CreateFieldBody()` is called from the `Parse()` member function and is responsible for creating a `DwFieldBody` object for this particular field. A typical scenario might go as follows: This member function examines the field name for this field, finds that it contains "To", creates a `DwAddressList` object to contain the field body, calls the `Parse()` member function for the `DwAddressList`, and sets the `DwAddressList` object as this `DwField` object's `DwFieldBody`.

If you want to override the behavior of `CreateFieldBody()`, you can do so by setting the public data member `sCreateFieldBody` to point to your own function. `CreateFieldBody()` first checks to see if `sCreateFieldBody` is `NULL`. If it is not, `CreateFieldBody()` will assume that it points to a user-supplied function and will call that function. If it is `NULL`, `CreateFieldBody()` will call `_CreateFieldBody()`, which actually creates the `DwFieldBody` object. You may call `_CreateFieldBody()` from your own function for fields you do not wish to handle.

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 DwField* (*sNewField)(const DwString&, DwMessageComponent*)

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

static DwFieldBody* (*sCreateFieldBody)(const DwString& aFieldName, const DwString& aFieldBody, DwMessageComponent* aParent)

See `CreateFieldBody()`.

## Protected Member Functions

void _SetFieldBody(DwFieldBody* aFieldBody)

Sets the `DwFieldBody` object contained by this object. This function differs from `SetFieldBody()` in that it does not set the is-modified flag.