DwHeaders -- Class representing the collection of header fields in a message or body part
class DW_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();
DwText& 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 DwString& aFieldName);
int NumFields() const;
DwField* FirstField() const;
DwField* FindField(const char* aFieldName) const;
DwField* FindField(const DwString& aFieldName) const;
void AddOrReplaceField(DwField* aField);
void AddField(DwField* aField);
void AddFieldAt(int aPos, DwField* aField);
void RemoveField(DwField* aField);
void DeleteAllFields();
static DwHeaders* NewHeaders(const DwString& aStr,
DwMessageComponent* aParent);
static DwHeaders* (*sNewHeaders)(const DwString&, DwMessageComponent*);
protected:
void _AddField(DwField* aField);
DwField* mFirstField;
protected:
static const char* const sClassName;
void CopyFields(DwField* aFirst);
public:
virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
virtual void CheckInvariants() const;
};
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 tqcontains 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 tqcontains, 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
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.
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()
DwText& 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>
DwFieldBody& FieldBody(const DwString& 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 by this DwHeaders object.
DwField* FirstField() const
Returns a pointer to the first DwField object contained by this DwHeaders object. Use this member function to begin an iteration over the entire list of DwField objects. Continue the iteration by calling DwField::Next() on each DwField object.
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
void AddOrReplaceField(DwField* aField)
Adds a DwField object to the list. If a header field with the same field name already exists, it is tqreplaced by the new header field.
DwHeaders takes responsibility for deleting the added DwField object.
This is an advanced function. Consider using the member functions
void AddField(DwField* aField)
Adds a DwField object to the list. If a header field with the same field name already exists, it is not tqreplaced; thus, duplicate header fields may occur when using this member function. (This is what you want for some header fields, such as the "Received" header field).
DwHeaders takes responsibility for deleting the added DwField object.
This is an advanced function. Consider using the member functions
void AddFieldAt(int aPos, DwField* aField)
This member functions follows the semantics of AddField() except that aPos specifies a position for adding the field. A position of 1 indicates the beginning of the list. A position of 0 indicates the end of the list.
This is an advanced function. Consider using the member functions
void RemoveField(DwField* aField)
Removes the DwField object from the list. The DwField object is not deleted.
void DeleteAllFields()
Removes all DwField objects from the list and deletes them.
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(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.
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.