You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdepim/mimelib/doc/headers.html

513 lines
26 KiB

<HTML>
<HEAD>
<TITLE> DwHeaders Man Page </TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<H2>
<FONT COLOR="navy"> NAME </FONT>
</H2>
<P>
DwHeaders -- Class representing the collection of header fields in a message
or body part
<H2>
<FONT COLOR="navy"> SYNOPSIS </FONT>
</H2>
<PRE>
class DW_EXPORT DwHeaders : public <A HREF="msgcmp.html">DwMessageComponent</A> {
public:
<A HREF="headers.html#DwHeaders">DwHeaders</A>();
<A HREF="headers.html#DwHeaders">DwHeaders</A>(const DwHeaders&amp; aHeaders);
<A HREF="headers.html#DwHeaders">DwHeaders</A>(const DwString&amp; aStr, DwMessageComponent* aParent=0);
virtual ~DwHeaders();
const DwHeaders&amp; <A HREF="headers.html#op_eq">operator =</A> (const DwHeaders&amp; aHeaders);
virtual void <A HREF="headers.html#Parse">Parse</A>();
virtual void <A HREF="headers.html#Assemble">Assemble</A>();
virtual DwMessageComponent* <A HREF="headers.html#Clone">Clone</A>() const;
DwBool <A HREF="headers.html#HasBcc">HasBcc</A>() const;
DwBool <A HREF="headers.html#HasCc">HasCc</A>() const;
DwBool <A HREF="headers.html#HasComments">HasComments</A>() const;
DwBool <A HREF="headers.html#HasDate">HasDate</A>() const;
DwBool <A HREF="headers.html#HasEncrypted">HasEncrypted</A>() const;
DwBool <A HREF="headers.html#HasFrom">HasFrom</A>() const;
DwBool <A HREF="headers.html#HasInReplyTo">HasInReplyTo</A>() const;
DwBool <A HREF="headers.html#HasKeywords">HasKeywords</A>() const;
DwBool <A HREF="headers.html#HasMessageId">HasMessageId</A>() const;
DwBool <A HREF="headers.html#HasReceived">HasReceived</A>() const;
DwBool <A HREF="headers.html#HasReferences">HasReferences</A>() const;
DwBool <A HREF="headers.html#HasReplyTo">HasReplyTo</A>() const;
DwBool <A HREF="headers.html#HasResentBcc">HasResentBcc</A>() const;
DwBool <A HREF="headers.html#HasResentCc">HasResentCc</A>() const;
DwBool <A HREF="headers.html#HasResentDate">HasResentDate</A>() const;
DwBool <A HREF="headers.html#HasResentFrom">HasResentFrom</A>() const;
DwBool <A HREF="headers.html#HasResentMessageId">HasResentMessageId</A>() const;
DwBool <A HREF="headers.html#HasResentReplyTo">HasResentReplyTo</A>() const;
DwBool <A HREF="headers.html#HasResentSender">HasResentSender</A>() const;
DwBool <A HREF="headers.html#HasResentTo">HasResentTo</A>() const;
DwBool <A HREF="headers.html#HasReturnPath">HasReturnPath</A>() const;
DwBool <A HREF="headers.html#HasSender">HasSender</A>() const;
DwBool <A HREF="headers.html#HasSubject">HasSubject</A>() const;
DwBool <A HREF="headers.html#HasTo">HasTo</A>() const;
DwBool <A HREF="headers.html#HasApproved">HasApproved</A>() const;
DwBool <A HREF="headers.html#HasControl">HasControl</A>() const;
DwBool <A HREF="headers.html#HasDistribution">HasDistribution</A>() const;
DwBool <A HREF="headers.html#HasExpires">HasExpires</A>() const;
DwBool <A HREF="headers.html#HasFollowupTo">HasFollowupTo</A>() const;
DwBool <A HREF="headers.html#HasLines">HasLines</A>() const;
DwBool <A HREF="headers.html#HasNewsgroups">HasNewsgroups</A>() const;
DwBool <A HREF="headers.html#HasOrganization">HasOrganization</A>() const;
DwBool <A HREF="headers.html#HasPath">HasPath</A>() const;
DwBool <A HREF="headers.html#HasSummary">HasSummary</A>() const;
DwBool <A HREF="headers.html#HasXref">HasXref</A>() const;
DwBool <A HREF="headers.html#HasContentDescription">HasContentDescription</A>() const;
DwBool <A HREF="headers.html#HasContentId">HasContentId</A>() const;
DwBool <A HREF="headers.html#HasContentTransferEncoding">HasContentTransferEncoding</A>() const;
DwBool <A HREF="headers.html#HasCte">HasCte</A>() const;
DwBool <A HREF="headers.html#HasContentType">HasContentType</A>() const;
DwBool <A HREF="headers.html#HasMimeVersion">HasMimeVersion</A>() const;
DwBool <A HREF="headers.html#HasContentDisposition">HasContentDisposition</A>() const;
DwBool <A HREF="headers.html#HasField">HasField</A>(const char* aFieldName) const;
DwBool <A HREF="headers.html#HasField">HasField</A>(const DwString&amp; aFieldName) const;
DwAddressList&amp; <A HREF="headers.html#Bcc">Bcc</A>();
DwAddressList&amp; <A HREF="headers.html#Cc">Cc</A>();
DwText&amp; <A HREF="headers.html#Comments">Comments</A>();
DwDateTime&amp; <A HREF="headers.html#Date">Date</A>();
DwText&amp; <A HREF="headers.html#Encrypted">Encrypted</A>();
DwMailboxList&amp; <A HREF="headers.html#From">From</A>();
DwText&amp; <A HREF="headers.html#InReplyTo">InReplyTo</A>();
DwText&amp; <A HREF="headers.html#Keywords">Keywords</A>();
DwMsgId&amp; <A HREF="headers.html#MessageId">MessageId</A>();
DwText&amp; <A HREF="headers.html#Received">Received</A>();
DwText&amp; <A HREF="headers.html#References">References</A>();
DwAddressList&amp; <A HREF="headers.html#ReplyTo">ReplyTo</A>();
DwAddressList&amp; <A HREF="headers.html#ResentBcc">ResentBcc</A>();
DwAddressList&amp; <A HREF="headers.html#ResentCc">ResentCc</A>();
DwDateTime&amp; <A HREF="headers.html#ResentDate">ResentDate</A>();
DwMailboxList&amp; <A HREF="headers.html#ResentFrom">ResentFrom</A>();
DwMsgId&amp; <A HREF="headers.html#ResentMessageId">ResentMessageId</A>();
DwAddressList&amp; <A HREF="headers.html#ResentReplyTo">ResentReplyTo</A>();
DwMailbox&amp; <A HREF="headers.html#ResentSender">ResentSender</A>();
DwAddressList&amp; <A HREF="headers.html#ResentTo">ResentTo</A>();
DwAddress&amp; <A HREF="headers.html#ReturnPath">ReturnPath</A>();
DwMailbox&amp; <A HREF="headers.html#Sender">Sender</A>();
DwText&amp; <A HREF="headers.html#Subject">Subject</A>();
DwAddressList&amp; <A HREF="headers.html#To">To</A>();
DwText&amp; <A HREF="headers.html#Approved">Approved</A>();
DwText&amp; <A HREF="headers.html#Control">Control</A>();
DwText&amp; <A HREF="headers.html#Distribution">Distribution</A>();
DwText&amp; <A HREF="headers.html#Expires">Expires</A>();
DwText&amp; <A HREF="headers.html#FollowupTo">FollowupTo</A>();
DwText&amp; <A HREF="headers.html#Lines">Lines</A>();
DwText&amp; <A HREF="headers.html#Newsgroups">Newsgroups</A>();
DwText&amp; <A HREF="headers.html#Organization">Organization</A>();
DwText&amp; <A HREF="headers.html#Path">Path</A>();
DwText&amp; <A HREF="headers.html#Summary">Summary</A>();
DwText&amp; <A HREF="headers.html#Xref">Xref</A>();
DwText&amp; <A HREF="headers.html#ContentDescription">ContentDescription</A>();
DwMsgId&amp; <A HREF="headers.html#ContentId">ContentId</A>();
DwMechanism&amp; <A HREF="headers.html#ContentTransferEncoding">ContentTransferEncoding</A>();
DwMechanism&amp; <A HREF="headers.html#Cte">Cte</A>();
DwMediaType&amp; <A HREF="headers.html#ContentType">ContentType</A>();
DwText&amp; <A HREF="headers.html#MimeVersion">MimeVersion</A>();
DwDispositionType&amp; <A HREF="headers.html#ContentDisposition">ContentDisposition</A>();
DwFieldBody&amp; <A HREF="headers.html#FieldBody">FieldBody</A>(const DwString&amp; aFieldName);
int <A HREF="headers.html#NumFields">NumFields</A>() const;
DwField* <A HREF="headers.html#FirstField">FirstField</A>() const;
DwField* <A HREF="headers.html#FindField">FindField</A>(const char* aFieldName) const;
DwField* <A HREF="headers.html#FindField">FindField</A>(const DwString&amp; aFieldName) const;
void <A HREF="headers.html#AddOrReplaceField">AddOrReplaceField</A>(DwField* aField);
void <A HREF="headers.html#AddField">AddField</A>(DwField* aField);
void <A HREF="headers.html#AddFieldAt">AddFieldAt</A>(int aPos, DwField* aField);
void <A HREF="headers.html#RemoveField">RemoveField</A>(DwField* aField);
void <A HREF="headers.html#DeleteAllFields">DeleteAllFields</A>();
static DwHeaders* <A HREF="headers.html#NewHeaders">NewHeaders</A>(const DwString&amp; aStr,
DwMessageComponent* aParent);
static DwHeaders* (*<A HREF="headers.html#sNewHeaders">sNewHeaders</A>)(const DwString&amp;, DwMessageComponent*);
protected:
void _AddField(DwField* aField);
DwField* mFirstField;
protected:
static const char* const sClassName;
void CopyFields(DwField* aFirst);
public:
virtual void <A HREF="headers.html#PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; aStrm, int aDepth=0) const;
virtual void <A HREF="headers.html#CheckInvariants">CheckInvariants</A>() const;
};
</PRE>
<H2>
<FONT COLOR="navy"> DESCRIPTION </FONT>
</H2>
<P>
<B><TT>DwHeaders</TT></B> represents the collection of <I>header fields</I>
(often called just <I>headers</I>) in an <I>entity</I> (either a message
or body part), as described in RFC-822 and RFC-2045. A
<B><TT>DwHeaders</TT></B> object manages a list of
<A HREF="field.html"><B><TT>DwField</TT></B> </A>objects, which represent
the individual header fields.
<P>
In the tree (broken-down) representation of a message, a
<B><TT>DwHeaders</TT></B> object is an intermediate node, having both a parent
node and several child nodes. The parent node is the
<B><TT><A HREF="entity.html">DwEntity</A></TT></B> object that contains it.
The child nodes are the <B><TT>DwField</TT></B> objects in the list it manages.
(See the man page for
<B><TT><A HREF="msgcmp.html">DwMessageComponent</A></TT></B> for a discussion
of the tree representation of a message.)
<P>
Normally, you do not create a <B><TT>DwHeaders</TT></B> object directly,
but you access it through the <B><TT>Headers()</TT></B> member function of
<B><TT>DwEntity</TT></B>, which creates the <B><TT>DwHeaders</TT></B> object
for you.
<P>
While <B><TT>DwHeaders</TT></B> has public member functions for managing
the list of <B><TT>DwField</TT></B> 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
<B><TT><Field>&lt;Field&gt;()</TT></B>, where <B><TT><Field></TT></B>
<B><TT>&lt;Field&gt;</TT></B> 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
<B><TT>MimeVersion()</TT></B>. The member function
<B><TT><Field>&lt;Field&gt;()</TT></B> will create a header field with field
name <B><TT><Field></TT></B> <B><TT>&lt;Field&gt;</TT></B> 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
<B><TT>Has<Field>&lt;Field&gt;()</TT></B>. For example, to check for the
existence of the MIME-version header field, use
<B><TT>HasMimeVersion()</TT></B>. Well-known header fields are those documented
in RFC-822 (standard email), RFC-1036 (USENET messages), RFC-2045 (MIME
messages), and possibly other RFCs.
<P>
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
<B><TT>FieldBody()</TT></B> with the field name as its argument. If the extension
field or user-defined field does not exist, <B><TT>FieldBody()</TT></B> will
create it. You can check for the existence of an extension field or user-defined
field by using the member function <B><TT>HasField()</TT></B> with the field
name as its argument.
<P>
<B><TT>DwHeaders</TT></B> has several other member functions provided for
the sake of completeness that are not required for most applications. These
functions are documented below.
<H2>
<FONT COLOR="navy"> Public Member Functions </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> <A NAME="DwHeaders">DwHeaders</A>() <BR>
DwHeaders(const DwHeaders&amp; aHeaders) <BR>
DwHeaders(const DwString&amp; aStr, DwMessageComponent* aParent=0)
</B></FONT>
<P>
The first constructor is the default constructor, which sets the
<B><TT>DwHeaders</TT></B> object's string representation to the empty string
and sets its parent to <B><TT>NULL</TT></B>.
<P>
The second constructor is the copy constructor, which performs a deep copy
of <B><TT>aHeaders</TT></B>. The parent of the new
<B><TT>DwHeaders</TT></B> object is set to <B><TT>NULL</TT></B>.
<P>
The third constructor copies <B><TT>aStr</TT></B> to the
<B><TT>DwHeaders</TT></B> object's string representation and sets
<B><TT>aParent</TT></B> as its parent. The virtual member function
<B><TT>Parse()</TT></B> should be called immediately after this constructor
in order to parse the string representation. Unless it is
<B><TT>NULL</TT></B>, <B><TT>aParent</TT></B> should point to an object of
a class derived from <B><TT>DwEntity</TT></B>.
<P>
<FONT COLOR="teal"><B> const DwHeaders&amp; <A NAME="op_eq">operator =</A>
(const DwHeaders&amp; aHeaders) </B></FONT>
<P>
This is the assignment operator, which performs a deep copy of
<B><TT>aHeaders</TT></B>. The parent node of the
<B><TT>DwHeaders</TT></B> object is not changed.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Parse">Parse</A>() </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the parse method for <B><TT>DwHeaders</TT></B> objects. The parse
method creates or updates the broken-down representation from the string
representation. For <B><TT>DwHeaders</TT></B> objects,
<B><TT>DwHeaders::Parse()</TT></B> parses the string representation to create
a list of <B><TT>DwField</TT></B> objects. This member function also calls
the <B><TT>Parse()</TT></B> member function of each
<B><TT>DwField</TT></B> object in its list.
<P>
You should call this member function after you set or modify the string
representation, and before you access any of the header fields.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual void <A NAME="Assemble">Assemble</A>()
</B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
executes the assemble method for <B><TT>DwHeaders</TT></B> 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 <B><TT>DwField</TT></B> objects. Before it builds the string
representation, this function first calls the <B><TT>Assemble()</TT></B>
member function of each <B><TT>DwField</TT></B> object in its list.
<P>
You should call this member function after you set or modify any of the header
fields, and before you retrieve the string representation.
<P>
This function clears the is-modified flag.
<P>
<FONT COLOR="teal"><B> virtual DwMessageComponent*
<A NAME="Clone">Clone</A>() const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
creates a new <B><TT>DwHeaders</TT></B> on the free store that has the same
value as this <B><TT>DwHeaders</TT></B> object. The basic idea is that of
a virtual copy constructor.
<P>
<FONT COLOR="teal"><B> DwBool <A NAME="HasBcc">HasBcc</A>() const<BR>
DwBool <A NAME="HasCc">HasCc</A>() const<BR>
DwBool <A NAME="HasComments">HasComments</A>() const<BR>
DwBool <A NAME="HasDate">HasDate</A>() const<BR>
DwBool <A NAME="HasEncrypted">HasEncrypted</A>() const<BR>
DwBool <A NAME="HasFrom">HasFrom</A>() const<BR>
DwBool <A NAME="HasInReplyTo">HasInReplyTo</A>() const<BR>
DwBool <A NAME="HasKeywords">HasKeywords</A>() const<BR>
DwBool <A NAME="HasMessageId">HasMessageId</A>() const<BR>
DwBool <A NAME="HasReceived">HasReceived</A>() const<BR>
DwBool <A NAME="HasReferences">HasReferences</A>() const<BR>
DwBool <A NAME="HasReplyTo">HasReplyTo</A>() const<BR>
DwBool <A NAME="HasResentBcc">HasResentBcc</A>() const<BR>
DwBool <A NAME="HasResentCc">HasResentCc</A>() const<BR>
DwBool <A NAME="HasResentDate">HasResentDate</A>() const<BR>
DwBool <A NAME="HasResentFrom">HasResentFrom</A>() const<BR>
DwBool <A NAME="HasResentMessageId">HasResentMessageId</A>() const<BR>
DwBool <A NAME="HasResentReplyTo">HasResentReplyTo</A>() const<BR>
DwBool <A NAME="HasResentSender">HasResentSender</A>() const<BR>
DwBool <A NAME="HasResentTo">HasResentTo</A>() const<BR>
DwBool <A NAME="HasReturnPath">HasReturnPath</A>() const<BR>
DwBool <A NAME="HasSender">HasSender</A>() const<BR>
DwBool <A NAME="HasSubject">HasSubject</A>() const<BR>
DwBool <A NAME="HasTo">HasTo</A>() const<BR>
DwBool <A NAME="HasApproved">HasApproved</A>() const<BR>
DwBool <A NAME="HasControl">HasControl</A>() const<BR>
DwBool <A NAME="HasDistribution">HasDistribution</A>() const<BR>
DwBool <A NAME="HasExpires">HasExpires</A>() const<BR>
DwBool <A NAME="HasFollowupTo">HasFollowupTo</A>() const<BR>
DwBool <A NAME="HasLines">HasLines</A>() const<BR>
DwBool <A NAME="HasNewsgroups">HasNewsgroups</A>() const<BR>
DwBool <A NAME="HasOrganization">HasOrganization</A>() const<BR>
DwBool <A NAME="HasPath">HasPath</A>() const<BR>
DwBool <A NAME="HasSummary">HasSummary</A>() const<BR>
DwBool <A NAME="HasXref">HasXref</A>() const<BR>
DwBool <A NAME="HasContentDescription">HasContentDescription</A>() const<BR>
DwBool <A NAME="HasContentId">HasContentId</A>() const<BR>
DwBool <A NAME="HasContentTransferEncoding">HasContentTransferEncoding</A>()
const<BR>
DwBool <A NAME="HasCte">HasCte</A>() const<BR>
DwBool <A NAME="HasContentType">HasContentType</A>() const<BR>
DwBool <A NAME="HasMimeVersion">HasMimeVersion</A>() const<BR>
DwBool <A NAME="HasContentDisposition">HasContentDisposition</A>() const
</B></FONT>
<P>
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.
<P>
<FONT COLOR="teal"><B> DwBool <A NAME="HasField">HasField</A>(const char*
aFieldName) const <BR>
DwBool HasField(const DwString&amp; aFieldName) const </B></FONT>
<P>
Returns true if the header field specified by <B><TT>aFieldName</TT></B>
is present in this object's collection of header fields. These member functions
are used for extension fields or user-defined fields.
<P>
<FONT COLOR="teal"><B> DwAddressList&amp; <A NAME="Bcc">Bcc</A>()<BR>
DwAddressList&amp; <A NAME="Cc">Cc</A>()<BR>
DwText&amp; <A NAME="Comments">Comments</A>()<BR>
Dw<A NAME="Date">Date</A>Time&amp; Date()<BR>
DwText&amp; <A NAME="Encrypted">Encrypted</A>()<BR>
DwMailboxList&amp; <A NAME="From">From</A>()<BR>
DwText&amp; <A NAME="InReplyTo">InReplyTo</A>()<BR>
DwText&amp; <A NAME="Keywords">Keywords</A>()<BR>
DwMsgId&amp; <A NAME="MessageId">MessageId</A>()<BR>
DwText&amp; <A NAME="Received">Received</A>()<BR>
DwText&amp; <A NAME="References">References</A>()<BR>
DwAddressList&amp; <A NAME="ReplyTo">ReplyTo</A>()<BR>
DwAddressList&amp; <A NAME="ResentBcc">ResentBcc</A>()<BR>
DwAddressList&amp; <A NAME="ResentCc">ResentCc</A>()<BR>
DwDateTime&amp; <A NAME="ResentDate">ResentDate</A>()<BR>
DwMailboxList&amp; <A NAME="ResentFrom">ResentFrom</A>()<BR>
DwMsgId&amp; <A NAME="ResentMessageId">ResentMessageId</A>()<BR>
DwAddressList&amp; <A NAME="ResentReplyTo">ResentReplyTo</A>()<BR>
DwMailbox&amp; <A NAME="ResentSender">ResentSender</A>()<BR>
DwAddressList&amp; <A NAME="ResentTo">ResentTo</A>()<BR>
DwAddress&amp; <A NAME="ReturnPath">ReturnPath</A>()<BR>
DwMailbox&amp; <A NAME="Sender">Sender</A>()<BR>
DwText&amp; <A NAME="Subject">Subject</A>()<BR>
DwAddressList&amp; <A NAME="To">To</A>()<BR>
DwText&amp; <A NAME="Approved">Approved</A>()<BR>
DwText&amp; <A NAME="Control">Control</A>()<BR>
DwText&amp; <A NAME="Distribution">Distribution</A>()<BR>
DwText&amp; <A NAME="Expires">Expires</A>()<BR>
DwText&amp; <A NAME="FollowupTo">FollowupTo</A>()<BR>
DwText&amp; <A NAME="Lines">Lines</A>()<BR>
DwText&amp; <A NAME="Newsgroups">Newsgroups</A>()<BR>
DwText&amp; <A NAME="Organization">Organization</A>()<BR>
DwText&amp; <A NAME="Path">Path</A>()<BR>
DwText&amp; <A NAME="Summary">Summary</A>()<BR>
DwText&amp; <A NAME="Xref">Xref</A>()<BR>
DwText&amp; <A NAME="ContentDescription">ContentDescription</A>()<BR>
DwMsgId&amp; <A NAME="ContentId">ContentId</A>()<BR>
DwMechanism&amp;
<A NAME="ContentTransferEncoding">ContentTransferEncoding</A>()<BR>
DwMechanism&amp; <A NAME="Cte">Cte</A>()<BR>
DwMediaType&amp; <A NAME="ContentType">ContentType</A>()<BR>
DwText&amp; <A NAME="MimeVersion">MimeVersion</A>()<BR>
DwDispositionType&amp; <A NAME="ContentDisposition">ContentDisposition</A>()
</B></FONT>
<P>
Each member function in this group returns a reference to a
<B><TT>DwFieldBody</TT></B> object for a particular header field. If the
header field does not already exist, it is created. Use the corresponding
<B><TT>Has&lt;Field&gt;<Field>()</TT></B> function to test if the header
field already exists without creating it.
<P>
<FONT COLOR="teal"><B> Dw<A NAME="FieldBody">FieldBody</A>&amp; FieldBody(const
DwString&amp; aFieldName) </B></FONT>
<P>
Returns a reference to the <B><TT>DwFieldBody</TT></B> object for a particular
header field with field name <B><TT>aFieldName</TT></B>. If the header field
does not already exist, it is created. Use <B><TT>HasField()</TT></B> to
test if the header field already exists without creating it. This member
function allows access to extension fields or user-defined fields.
<P>
<FONT COLOR="teal"><B> int <A NAME="NumFields">NumFields</A>() const
</B></FONT>
<P>
Returns the number of <B><TT>DwField</TT></B> objects contained by this
<B><TT>DwHeaders</TT></B> object.
<P>
<FONT COLOR="teal"><B> DwField* <A NAME="FirstField">FirstField</A>() const
</B></FONT>
<P>
Returns a pointer to the first <B><TT>DwField</TT></B> object contained by
this <B><TT>DwHeaders</TT></B> object. Use this member function to begin
an iteration over the entire list of <B><TT>DwField</TT></B> objects. Continue
the iteration by calling <B><TT>DwField::Next()</TT></B> on each
<B><TT>DwField</TT></B> object.
<P>
<FONT COLOR="teal"><B> DwField* <A NAME="FindField">FindField</A>(const char*
aFieldName) const <BR>
DwField* FindField(const DwString&amp; aFieldName) const </B></FONT>
<P>
Searches for a header field by its field name. Returns
<B><TT>NULL</TT></B> if the field is not found. This is an <I>advanced</I>
function: most applications should use the
<B><TT><Field>&lt;Field&gt;()</TT></B> or
<B><TT>Has&lt;Field&gt;()</TT></B> family of functions.
<P>
<FONT COLOR="teal"><B> void
<A NAME="AddOrReplaceField">AddOrReplaceField</A>(DwField* aField)
</B></FONT>
<P>
Adds a <B><TT>DwField</TT></B> object to the list. If a header field with
the same field name already exists, it is replaced by the new header field.
<P>
<B><TT>DwHeaders</TT></B> takes responsibility for deleting the added
<B><TT>DwField</TT></B> object.
<P>
This is an advanced function. Consider using the member functions
<B><TT><Field>&lt;Field&gt;()</TT></B> (e.g. <B><TT>To()</TT></B>,
<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B>
to add header fields.
<P>
<FONT COLOR="teal"><B> void <A NAME="AddField">AddField</A>(DwField* aField)
</B></FONT>
<P>
Adds a <B><TT>DwField</TT></B> object to the list. If a header field with
the same field name already exists, it is <I>not</I> replaced; 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).
<P>
<B><TT>DwHeaders</TT></B> takes responsibility for deleting the added
<B><TT>DwField</TT></B> object.
<P>
This is an advanced function. Consider using the member functions
<B><TT><Field>&lt;Field&gt;()</TT></B> (e.g. <B><TT>To()</TT></B>,
<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B>
for adding header fields.
<P>
<FONT COLOR="teal"><B> void <A NAME="AddFieldAt">AddFieldAt</A>(int aPos,
DwField* aField) </B></FONT>
<P>
This member functions follows the semantics of <B><TT>AddField()</TT></B>
except that <B><TT>aPos</TT></B> 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.
<P>
This is an advanced function. Consider using the member functions
<B><TT><Field>&lt;Field&gt;()</TT></B> (e.g. <B><TT>To()</TT></B>,
<B><TT>ContentType()</TT></B>, and so on) and <B><TT>FieldBody()</TT></B>
for adding header fields.
<P>
<FONT COLOR="teal"><B> void <A NAME="RemoveField">RemoveField</A>(DwField*
aField) </B></FONT>
<P>
Removes the <B><TT>DwField</TT></B> object from the list. The
<B><TT>DwField</TT></B> object is not deleted.
<P>
<FONT COLOR="teal"><B> void <A NAME="DeleteAllFields">DeleteAllFields</A>()
</B></FONT>
<P>
Removes all <B><TT>DwField</TT></B> objects from the list and deletes them.
<P>
<FONT COLOR="teal"><B> static DwHeaders*
<A NAME="NewHeaders">NewHeaders</A>(const DwString&amp; aStr, DwMessageComponent*
aParent) </B></FONT>
<P>
Creates a new <B><TT>DwHeaders</TT></B> object on the free store. If the
static data member <B><TT>sNewHeaders</TT></B> is <B><TT>NULL</TT></B>, this
member function will create a new <B><TT>DwHeaders</TT></B> and return it.
Otherwise, <B><TT>NewHeaders()</TT></B> will call the user-supplied function
pointed to by <B><TT>sNewHeaders</TT></B>, which is assumed to return an
object from a class derived from <B><TT>DwHeaders</TT></B>, and return that
object.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="PrintDebugInfo">PrintDebugInfo</A>(ostream&amp; aStrm, int aDepth=0)
const </B></FONT>
<P>
This virtual function, inherited from <B><TT>DwMessageComponent</TT></B>,
prints debugging information about this object to <B><TT>aStrm</TT></B>.
It will also call <B><TT>PrintDebugInfo()</TT></B> for any of its child
components down to a level of <B><TT>aDepth</TT></B>.
<P>
This member function is available only in the debug version of the library.
<P>
<FONT COLOR="teal"><B> virtual void
<A NAME="CheckInvariants">CheckInvariants</A>() const </B></FONT>
<P>
Aborts if one of the invariants of the object fails. Use this member function
to track down bugs.
<P>
This member function is available only in the debug version of the library.
<P>
<H2>
<FONT COLOR="navy"> Public Data Members </FONT>
</H2>
<P>
<FONT COLOR="teal"><B> static DwHeaders*
(*<A NAME="sNewHeaders">sNewHeaders</A>)(const DwString&amp;,
DwMessageComponent*) </B></FONT>
<P>
If <B><TT>sNewHeaders</TT></B> is not <B><TT>NULL</TT></B>, it is assumed
to point to a user-supplied function that returns an object from a class
derived from <B><TT>DwHeaders</TT></B>.
<P>
</BODY></HTML>