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.
453 lines
17 KiB
453 lines
17 KiB
//=============================================================================
|
|
// File: headers.h
|
|
// Contents: Declarations for DwHeaders
|
|
// Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
|
|
// WWW: http://www.fwb.gulf.net/~dwsauder/mimepp.html
|
|
//
|
|
// Copyright (c) 1996, 1997 Douglas W. Sauder
|
|
// All rights reserved.
|
|
//
|
|
// IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
|
|
// INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
|
|
// THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
|
|
// HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
//
|
|
// DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
|
|
// NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
|
|
// PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
|
|
// BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
|
|
// SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
//
|
|
//=============================================================================
|
|
|
|
#ifndef DW_HEADERS_H
|
|
#define DW_HEADERS_H
|
|
|
|
#include <iostream>
|
|
#include <vector>
|
|
|
|
#ifndef DW_CONFIG_H
|
|
#include <mimelib/config.h>
|
|
#endif
|
|
|
|
#ifndef DW_STRING_H
|
|
#include <mimelib/string.h>
|
|
#endif
|
|
|
|
#ifndef DW_MSGCMP_H
|
|
#include <mimelib/msgcmp.h>
|
|
#endif
|
|
|
|
#ifndef DW_ENTITY_H
|
|
#include <mimelib/entity.h>
|
|
#endif
|
|
|
|
#ifndef DW_MSGID_H
|
|
#include <mimelib/msgid.h>
|
|
#endif
|
|
|
|
#ifndef DW_MAILBOX_H
|
|
#include <mimelib/mailbox.h>
|
|
#endif
|
|
|
|
#ifndef DW_MEDIATYP_H
|
|
#include <mimelib/mediatyp.h>
|
|
#endif
|
|
|
|
#ifndef DW_DATETIME_H
|
|
#include <mimelib/datetime.h>
|
|
#endif
|
|
|
|
#ifndef DW_MECHANSM_H
|
|
#include <mimelib/mechansm.h>
|
|
#endif
|
|
|
|
#ifndef DW_DISPTYPE_H
|
|
#include <mimelib/disptype.h>
|
|
#endif
|
|
|
|
class DwMessage;
|
|
class DwField;
|
|
class DwFieldBody;
|
|
class DwDateTime;
|
|
class DwMailboxList;
|
|
class DwAddressList;
|
|
class DwMediaType;
|
|
class DwMechanism;
|
|
class DwText;
|
|
|
|
//=============================================================================
|
|
//+ Name DwHeaders -- Class representing the collection of header fields in a message or body part
|
|
//+ Description
|
|
//. {\tt DwHeaders} represents the collection of {\it header fields} (often
|
|
//. called just {\it headers}) in an {\it entity} (either a message or body
|
|
//. part), as described in RFC-822 and RFC-2045. A {\tt DwHeaders} object
|
|
//. manages a list of {\tt DwField} objects, which represent the individual
|
|
//. header fields.
|
|
//.
|
|
//. In the tree (broken-down) representation of a message, a {\tt DwHeaders}
|
|
//. object is an intermediate node, having both a parent node and several
|
|
//. child nodes. The parent node is the {\tt DwEntity} object that contains
|
|
//. it. The child nodes are the {\tt DwField} objects in the list it manages.
|
|
//. (See the man page for {\tt DwMessageComponent} for a discussion of
|
|
//. the tree representation of a message.)
|
|
//.
|
|
//. Normally, you do not create a {\tt DwHeaders} object directly, but you
|
|
//. access it through the {\tt Headers()} member function of {\tt DwEntity},
|
|
//. which creates the {\tt DwHeaders} object for you.
|
|
//.
|
|
//. While {\tt DwHeaders} has public member functions for managing the list
|
|
//. of {\tt 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 {\tt <Field>()}, where {\tt <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 {\tt MimeVersion()}.
|
|
//. The member function {\tt <Field>()} will create a header field with
|
|
//. field name {\tt <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 {\tt Has<Field>()}. For example, to check
|
|
//. for the existence of the MIME-version header field, use
|
|
//. {\tt 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
|
|
//. {\tt FieldBody()} with the field name as its argument. If the extension
|
|
//. field or user-defined field does not exist, {\tt FieldBody()} will
|
|
//. create it. You can check for the existence of an extension field or
|
|
//. user-defined field by using the member function {\tt HasField()} with
|
|
//. the field name as its argument.
|
|
//.
|
|
//. {\tt DwHeaders} has several other member functions provided for the
|
|
//. sake of completeness that are not required for most applications.
|
|
//. These functions are documented below.
|
|
//=============================================================================
|
|
// Last updated 1997-08-26
|
|
//+ Noentry ~DwHeaders sClassName CopyFields mFirstField _AddField
|
|
|
|
|
|
class DW_EXPORT DwHeaders : public DwMessageComponent {
|
|
|
|
public:
|
|
|
|
DwHeaders();
|
|
DwHeaders(const DwHeaders& aHeaders);
|
|
DwHeaders(const DwString& aStr, DwMessageComponent* aParent=0);
|
|
//. The first constructor is the default constructor, which sets the
|
|
//. {\tt DwHeaders} object's string representation to the empty string
|
|
//. and sets its parent to {\tt NULL}.
|
|
//.
|
|
//. The second constructor is the copy constructor, which performs a
|
|
//. deep copy of {\tt aHeaders}.
|
|
//. The parent of the new {\tt DwHeaders} object is set to {\tt NULL}.
|
|
//.
|
|
//. The third constructor copies {\tt aStr} to the {\tt DwHeaders}
|
|
//. object's string representation and sets {\tt aParent} as its parent.
|
|
//. The virtual member function {\tt Parse()} should be called immediately
|
|
//. after this constructor in order to parse the string representation.
|
|
//. Unless it is {\tt NULL}, {\tt aParent} should point to an object of a class
|
|
//. derived from {\tt DwEntity}.
|
|
|
|
virtual ~DwHeaders();
|
|
|
|
const DwHeaders& operator = (const DwHeaders& aHeaders);
|
|
//. This is the assignment operator, which performs a deep copy of
|
|
//. {\tt aHeaders}. The parent node of the {\tt DwHeaders} object
|
|
//. is not changed.
|
|
|
|
virtual void Parse();
|
|
//. This virtual function, inherited from {\tt DwMessageComponent},
|
|
//. executes the parse method for {\tt DwHeaders} objects. The parse
|
|
//. method creates or updates the broken-down representation from the
|
|
//. string representation. For {\tt DwHeaders} objects,
|
|
//. {\tt DwHeaders::Parse()} parses the string representation to create
|
|
//. a list of {\tt DwField} objects. This member function also calls
|
|
//. the {\tt Parse()} member function of each {\tt 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 {\tt DwMessageComponent},
|
|
//. executes the assemble method for {\tt 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 {\tt DwField}
|
|
//. objects. Before it builds the string representation, this function
|
|
//. first calls the {\tt Assemble()} member function of each {\tt 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 {\tt DwMessageComponent},
|
|
//. creates a new {\tt DwHeaders} on the free store that has the same
|
|
//. value as this {\tt 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;
|
|
// RFC-822 fields
|
|
//
|
|
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;
|
|
// RFC-1036 fields
|
|
//
|
|
DwBool HasContentDescription() const;
|
|
DwBool HasContentId() const;
|
|
DwBool HasContentTransferEncoding() const;
|
|
DwBool HasCte() const;
|
|
DwBool HasContentType() const;
|
|
DwBool HasMimeVersion() const;
|
|
// RFC-2045 fields
|
|
//
|
|
DwBool HasContentDisposition() const;
|
|
// RFC-1806
|
|
//
|
|
//. 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 {\tt 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();
|
|
// RFC-822 fields
|
|
//
|
|
DwText& Approved();
|
|
DwText& Control();
|
|
DwText& Distribution();
|
|
DwText& Expires();
|
|
DwText& FollowupTo();
|
|
DwText& Lines();
|
|
DwText& Newsgroups();
|
|
DwText& Organization();
|
|
DwText& Path();
|
|
DwText& Summary();
|
|
DwText& Xref();
|
|
// RFC-1036 fields (USENET messages)
|
|
//
|
|
DwText& ContentDescription();
|
|
DwMsgId& ContentId();
|
|
DwMechanism& ContentTransferEncoding();
|
|
DwMechanism& Cte();
|
|
DwMediaType& ContentType();
|
|
DwText& MimeVersion();
|
|
// RFC-2045 fields
|
|
//
|
|
DwDispositionType& ContentDisposition();
|
|
// RFC-1806 Content-Disposition field
|
|
//
|
|
//. Each member function in this group returns a reference to a
|
|
//. {\tt DwFieldBody} object for a particular header field. If the
|
|
//. header field does not already exist, it is created. Use the
|
|
//. corresponding {\tt Has<Field>()} function to test if the header
|
|
//. field already exists without creating it.
|
|
|
|
DwFieldBody& FieldBody(const DwString& aFieldName);
|
|
//. Returns a reference to the {\tt DwFieldBody} object for a particular
|
|
//. header field with field name {\tt aFieldName}. If the header field
|
|
//. does not already exist, it is created. Use {\tt HasField()}
|
|
//. to test if the header field already exists without creating it.
|
|
//. This member function allows access to extension fields or
|
|
//. user-defined fields.
|
|
|
|
std::vector<DwFieldBody*> AllFieldBodies(const DwString& aFieldName);
|
|
//. Returns a vector of pointers to the {\tt DwFieldBody} objects for
|
|
//. all header fields with field name {\tt aFieldName}. If the header
|
|
//. field does not already exist, it is created. Use {\tt 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 {\tt DwField} objects contained by this
|
|
//. {\tt DwHeaders} object.
|
|
|
|
DwField* FirstField() const;
|
|
//. Returns a pointer to the first {\tt DwField} object contained by
|
|
//. this {\tt DwHeaders} object. Use this member function to begin an
|
|
//. iteration over the entire list of {\tt DwField} objects.
|
|
//. Continue the iteration by calling {\tt DwField::Next()} on each
|
|
//. {\tt DwField} object.
|
|
|
|
DwField* FindField(const char* aFieldName) const;
|
|
DwField* FindField(const DwString& aFieldName) const;
|
|
//. Searches for a header field by its field name. Returns {\tt NULL}
|
|
//. if the field is not found. This is an {\it advanced} function:
|
|
//. most applications should use the {\tt <Field>()} or
|
|
//. {\tt Has<Field>()} family of functions.
|
|
|
|
void AddOrReplaceField(DwField* aField);
|
|
//. Adds a {\tt DwField} object to the list. If a header field with
|
|
//. the same field name already exists, it is replaced by the new
|
|
//. header field.
|
|
//.
|
|
//. {\tt DwHeaders} takes responsibility for deleting the added
|
|
//. {\tt DwField} object.
|
|
//.
|
|
//. This is an advanced function. Consider using the member functions
|
|
//. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
|
|
//. and {\tt FieldBody()} to add header fields.
|
|
|
|
void AddField(DwField* aField);
|
|
//. Adds a {\tt DwField} object to the list. If a header field with
|
|
//. the same field name already exists, it is {\it not} 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).
|
|
//.
|
|
//. {\tt DwHeaders} takes responsibility for deleting the added
|
|
//. {\tt DwField} object.
|
|
//.
|
|
//. This is an advanced function. Consider using the member functions
|
|
//. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
|
|
//. and {\tt FieldBody()} for adding header fields.
|
|
|
|
void AddFieldAt(int aPos, DwField* aField);
|
|
//. This member functions follows the semantics of {\tt AddField()}
|
|
//. except that {\tt 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
|
|
//. {\tt <Field>()} (e.g. {\tt To()}, {\tt ContentType()}, and so on)
|
|
//. and {\tt FieldBody()} for adding header fields.
|
|
|
|
void RemoveField(DwField* aField);
|
|
//. Removes the {\tt DwField} object from the list. The {\tt DwField}
|
|
//. object is not deleted.
|
|
|
|
void DeleteAllFields();
|
|
//. Removes all {\tt DwField} objects from the list and deletes them.
|
|
|
|
static DwHeaders* NewHeaders(const DwString& aStr,
|
|
DwMessageComponent* aParent);
|
|
//. Creates a new {\tt DwHeaders} object on the free store.
|
|
//. If the static data member {\tt sNewHeaders} is {\tt NULL},
|
|
//. this member function will create a new {\tt DwHeaders}
|
|
//. and return it. Otherwise, {\tt NewHeaders()} will call
|
|
//. the user-supplied function pointed to by {\tt sNewHeaders},
|
|
//. which is assumed to return an object from a class derived from
|
|
//. {\tt DwHeaders}, and return that object.
|
|
|
|
//+ Var sNewHeaders
|
|
static DwHeaders* (*sNewHeaders)(const DwString&, DwMessageComponent*);
|
|
//. If {\tt sNewHeaders} is not {\tt NULL}, it is assumed to point to a
|
|
//. user-supplied function that returns an object from a class derived from
|
|
//. {\tt DwHeaders}.
|
|
|
|
protected:
|
|
|
|
void _AddField(DwField* aField);
|
|
//. Add field but don't set the is-modified flag
|
|
|
|
DwField* mFirstField;
|
|
DwField* mLastField;
|
|
|
|
protected:
|
|
|
|
static const char* const sClassName;
|
|
|
|
void CopyFields(DwField* aFirst);
|
|
|
|
public:
|
|
|
|
virtual void PrintDebugInfo(std::ostream& aStrm, int aDepth=0) const;
|
|
//. This virtual function, inherited from {\tt DwMessageComponent},
|
|
//. prints debugging information about this object to {\tt aStrm}.
|
|
//. It will also call {\tt PrintDebugInfo()} for any of its child
|
|
//. components down to a level of {\tt 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.
|
|
|
|
private:
|
|
|
|
void _PrintDebugInfo(std::ostream& aStrm) const;
|
|
|
|
};
|
|
|
|
|
|
inline DwField* DwHeaders::FirstField() const
|
|
{
|
|
return mFirstField;
|
|
}
|
|
|
|
#endif
|
|
|