DwHeaders Man Page

## NAME

DwHeaders -- Class representing the collection of header fields in a message or body part

## SYNOPSIS

    class DW_CORE_EXPORT DwHeaders : public DwMessageComponent {

    public:

        DwHeaders();
        DwHeaders(const DwHeaders& aHeaders);
        DwHeaders(const DwString& aStr, DwMessageComponent* aParent=0);
        virtual ~DwHeaders();
        const DwHeaders& operator = (const DwHeaders& aHeaders);
        virtual void Parse();
        virtual void Assemble();
        virtual DwMessageComponent* Clone() const;
        DwBool HasBcc() const;
        DwBool HasCc() const;
        DwBool HasComments() const;
        DwBool HasDate() const;
        DwBool HasEncrypted() const;
        DwBool HasFrom() const;
        DwBool HasInReplyTo() const;
        DwBool HasKeywords() const;
        DwBool HasMessageId() const;
        DwBool HasReceived() const;
        DwBool HasReferences() const;
        DwBool HasReplyTo() const;
        DwBool HasResentBcc() const;
        DwBool HasResentCc() const;
        DwBool HasResentDate() const;
        DwBool HasResentFrom() const;
        DwBool HasResentMessageId() const;
        DwBool HasResentReplyTo() const;
        DwBool HasResentSender() const;
        DwBool HasResentTo() const;
        DwBool HasReturnPath() const;
        DwBool HasSender() const;
        DwBool HasSubject() const;
        DwBool HasTo() const;
        DwBool HasApproved() const;
        DwBool HasControl() const;
        DwBool HasDistribution() const;
        DwBool HasExpires() const;
        DwBool HasFollowupTo() const;
        DwBool HasLines() const;
        DwBool HasNewsgroups() const;
        DwBool HasOrganization() const;
        DwBool HasPath() const;
        DwBool HasSummary() const;
        DwBool HasXref() const;
        DwBool HasContentDescription() const;
        DwBool HasContentId() const;
        DwBool HasContentTransferEncoding() const;
        DwBool HasCte() const;
        DwBool HasContentType() const;
        DwBool HasMimeVersion() const;
        DwBool HasContentDisposition() const;
        DwBool HasField(const char* aFieldName) const;
        DwBool HasField(const DwString& aFieldName) const;
        DwAddressList&  Bcc();
        DwAddressList&  Cc();
        DwText&         Comments();
        DwDateTime&     Date();
        DwText&         Encrypted();
        DwMailboxList&  From();
        DwText&         InReplyTo();
        DwText&         Keywords();
        DwMsgId&        MessageId();
        DwStamp&        Received();
        DwText&         References();
        DwAddressList&  ReplyTo();
        DwAddressList&  ResentBcc();
        DwAddressList&  ResentCc();
        DwDateTime&     ResentDate();
        DwMailboxList&  ResentFrom();
        DwMsgId&        ResentMessageId();
        DwAddressList&  ResentReplyTo();
        DwMailbox&      ResentSender();
        DwAddressList&  ResentTo();
        DwAddress&      ReturnPath();
        DwMailbox&      Sender();
        DwText&         Subject();
        DwAddressList&  To();
        DwText& Approved();
        DwText& Control();
        DwText& Distribution();
        DwText& Expires();
        DwText& FollowupTo();
        DwText& Lines();
        DwText& Newsgroups();
        DwText& Organization();
        DwText& Path();
        DwText& Summary();
        DwText& Xref();
        DwText&         ContentDescription();
        DwMsgId&        ContentId();
        DwMechanism&    ContentTransferEncoding();
        DwMechanism&    Cte();
        DwMediaType&    ContentType();
        DwText&         MimeVersion();
        DwDispositionType& ContentDisposition();
        DwFieldBody& FieldBody(const char* aFieldName);
        int NumFields() const;
        void AddField(DwField* aField);
        void DeleteAllFields();
        DwField& FieldAt(int aIndex) const;
        void InsertFieldAt(int aIndex, DwField* aField);
        DwField* RemoveFieldAt(int aIndex);
        DwField* FindField(const char* aFieldName) const;
        DwField* FindField(const DwString& aFieldName) const;
        static DwHeaders* NewHeaders(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwHeaders* (*sNewHeaders)(const DwString&, DwMessageComponent*);

    protected:

        void _CopyFields(const DwHeaders& aHeaders);
        void _AddField(DwField* aField);
        void _InsertFieldAt(int aIndex, DwField* aField);
        void _DeleteAllFields();

    public:

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

## DESCRIPTION

`DwHeaders` represents the collection of header fields (often called just headers) in an entity (either a message or body part), as described in RFC-822 and RFC-2045. A `DwHeaders` object manages a list of `DwField` objects, which represent the individual header fields.

In the tree (broken-down) representation of a message, a `DwHeaders` object is an intermediate node, having both a parent node and several child nodes. The parent node is the `DwEntity` object that contains it. The child nodes are the `DwField` objects in the list it manages. (See the man page for `DwMessageComponent` for a discussion of the tree representation of a message.)

Normally, you do not create a `DwHeaders` object directly, but you access it through the `Headers()` member function of `DwEntity`, which creates the `DwHeaders` object for you.

While `DwHeaders` has public member functions for managing the list of `DwField` objects it contains, you will normally use convenience functions to access the field bodies of the header fields directly. You can access the field body for a specific well-known header field by using the member function `<Field>()`, where `<Field>` is the field name of the header field with hyphens removed and the first word following a hyphen capitalized. For example, to access the field body for the "MIME-version" header field, use `MimeVersion()`. The member function `<Field>()` will create a header field with field name `<Field>` if such a header field does not already exist. You can check for the existence of a particular well-known header field by using the member function `Has<Field>()`. For example, to check for the existence of the MIME-version header field, use `HasMimeVersion()`. Well-known header fields are those documented in RFC-822 (standard email), RFC-1036 (USENET messages), RFC-2045 (MIME messages), and possibly other RFCs.

In the case of an extension field or user-defined field, you can access the field body of the header field by calling the member function `FieldBody()` with the field name as its argument. If the extension field or user-defined field does not exist, `FieldBody()` will create it. You can check for the existence of an extension field or user-defined field by using the member function `HasField()` with the field name as its argument.

`DwHeaders` has several other member functions provided for the sake of completeness that are not required for most applications. These functions are documented below.

## Public Member Functions

DwHeaders()
DwHeaders(const DwHeaders& aHeaders)
DwHeaders(const DwString& aStr, DwMessageComponent* aParent=0)

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

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

const DwHeaders& operator = (const DwHeaders& aHeaders)

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

virtual void Parse()

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

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from `DwMessageComponent`, executes the assemble method for `DwHeaders` 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 `DwField` objects. Before it builds the string representation, this function first calls the `Assemble()` member function of each `DwField` object in its list.

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

DwBool HasBcc() const
DwBool HasCc() const
DwBool HasComments() const
DwBool HasDate() const
DwBool HasEncrypted() const
DwBool HasFrom() const
DwBool HasInReplyTo() const
DwBool HasKeywords() const
DwBool HasMessageId() const
DwBool HasReceived() const
DwBool HasReferences() const
DwBool HasReplyTo() const
DwBool HasResentBcc() const
DwBool HasResentCc() const
DwBool HasResentDate() const
DwBool HasResentFrom() const
DwBool HasResentMessageId() const
DwBool HasResentReplyTo() const
DwBool HasResentSender() const
DwBool HasResentTo() const
DwBool HasReturnPath() const
DwBool HasSender() const
DwBool HasSubject() const
DwBool HasTo() const
DwBool HasApproved() const
DwBool HasControl() const
DwBool HasDistribution() const
DwBool HasExpires() const
DwBool HasFollowupTo() const
DwBool HasLines() const
DwBool HasNewsgroups() const
DwBool HasOrganization() const
DwBool HasPath() const
DwBool HasSummary() const
DwBool HasXref() const
DwBool HasContentDescription() const
DwBool HasContentId() const
DwBool HasContentTransferEncoding() const
DwBool HasCte() const
DwBool HasContentType() const
DwBool HasMimeVersion() const
DwBool HasContentDisposition() const

Each member function in this group returns a boolean value indicating whether a particular well-known header field is present in this object's collection of header fields.

DwBool HasField(const char* aFieldName) const
DwBool HasField(const DwString& aFieldName) const

Returns true if the header field specified by `aFieldName` is present in this object's collection of header fields. These member functions are used for extension fields or user-defined fields.

DwAddressList& Bcc()
DwAddressList& Cc()
DwText& Comments()
DwDateTime& Date()
DwText& Encrypted()
DwMailboxList& From()
DwText& InReplyTo()
DwText& Keywords()
DwMsgId& MessageId()
DwStamp& Received()
DwText& References()
DwAddressList& ReplyTo()
DwAddressList& ResentBcc()
DwAddressList& ResentCc()
DwDateTime& ResentDate()
DwMailboxList& ResentFrom()
DwMsgId& ResentMessageId()
DwAddressList& ResentReplyTo()
DwMailbox& ResentSender()
DwAddressList& ResentTo()
DwAddress& ReturnPath()
DwMailbox& Sender()
DwText& Subject()
DwAddressList& To()
DwText& Approved()
DwText& Control()
DwText& Distribution()
DwText& Expires()
DwText& FollowupTo()
DwText& Lines()
DwText& Newsgroups()
DwText& Organization()
DwText& Path()
DwText& Summary()
DwText& Xref()
DwText& ContentDescription()
DwMsgId& ContentId()
DwMechanism& ContentTransferEncoding()
DwMechanism& Cte()
DwMediaType& ContentType()
DwText& MimeVersion()
DwDispositionType& ContentDisposition()

Each member function in this group returns a reference to a `DwFieldBody` object for a particular header field. If the header field does not already exist, it is created. Use the corresponding `Has<Field>()` function to test if the header field already exists without creating it.

DwFieldBody& FieldBody(const char* aFieldName)

Returns a reference to the `DwFieldBody` object for a particular header field with field name `aFieldName`. If the header field does not already exist, it is created. Use `HasField()` to test if the header field already exists without creating it. This member function allows access to extension fields or user-defined fields.

int NumFields() const

Returns the number of `DwField` objects contained in this `DwHeaders` object.

void AddField(DwField* aField)

Appends a `DwField` object to the list managed by this `DwHeaders` object.

Any `DwField` objects contained in a `DwHeaders` object's list will be deleted by the `DwHeaders` object's destructor.

void DeleteAllFields()

Removes and deletes all `DwField` objects contained in this `DwHeaders` object.

DwField& FieldAt(int aIndex) const

Returns the `DwField` object at position `aIndex` in this `DwHeaders` object's list.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumFields()`.

void InsertFieldAt(int aIndex, DwField* aField)

Inserts `aField` into the list of `DwField` objects at the position given by `aIndex`. A value of zero for `aIndex` will insert `aField` as the first one in the list; a value of `NumFields()` will insert it as the last one in the list. If `aIndex` is less than `NumFields()`, the `DwField` objects at position `aIndex` or greater will be shifted down the list to make room to insert `aField`.

Any `DwField` objects contained in a `DwHeaders` object's list will be deleted by the `DwHeaders` object's destructor.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` <= `NumFields()`.

DwField* RemoveFieldAt(int aIndex)

Removes the `DwField` object at position `aIndex` from the list and returns it. If `aIndex` is less than `NumFields()-1`, then any `DwField` objects at a position greater than `aIndex` will be shifted up in the list after the requested `DwField` is removed.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumFields()`.

DwField* FindField(const char* aFieldName) const
DwField* FindField(const DwString& aFieldName) const

Searches for a header field by its field name. Returns `NULL` if the field is not found. This is an advanced function: most applications should use the `<Field>()` or `Has<Field>()` family of functions.

static DwHeaders* NewHeaders(const DwString& aStr, DwMessageComponent* aParent)

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

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

## Protected Member Functions

void _CopyFields(const DwHeaders& aHeaders)

Copies the list of `DwField` objects from `aHeaders`.

void _AddField(DwField* aField)

Same as `AddField()`, but does not set is-modified flag.

void _InsertFieldAt(int aIndex, DwField* aField)

Performs all the work of adding `DwField` objects to the list. This function does not set the is-modified flag.

void _DeleteAllFields()

Deletes all fields. Differs from `DeleteAllFields()` in that it does not set the is-modified flag.