diff options
Diffstat (limited to 'mimelib/mimelib/headers.h')
| -rw-r--r-- | mimelib/mimelib/headers.h | 453 |
1 files changed, 453 insertions, 0 deletions
diff --git a/mimelib/mimelib/headers.h b/mimelib/mimelib/headers.h new file mode 100644 index 00000000..8f802ce5 --- /dev/null +++ b/mimelib/mimelib/headers.h @@ -0,0 +1,453 @@ +//============================================================================= +// 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 DwBodyPart; +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 + |