TDE
/
tdepim
mirror of https://mirror.git.trinitydesktop.org/gitea/TDE/tdepim
0
0
Fork 0
Code Issues Releases Wiki Activity
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.
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '90c6a46c9c'
${ noResults }
tdepim/mimelib/mimelib/headers.h

453 lines
17 KiB
Raw Blame History

//=============================================================================
// 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
View Git Blame Copy Permalink