DwHeaders Man Page

From 460c52653ab0dcca6f19a4f492ed2c5e4e963ab0 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdepim@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- mimelib/doc/headers.html | 512 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 512 insertions(+) create mode 100644 mimelib/doc/headers.html (limited to 'mimelib/doc/headers.html') diff --git a/mimelib/doc/headers.html b/mimelib/doc/headers.html new file mode 100644 index 000000000..8bf94ad98 --- /dev/null +++ b/mimelib/doc/headers.html @@ -0,0 +1,512 @@ + + + DwHeaders Man Page + + +

+ NAME +

+DwHeaders -- Class representing the collection of header fields in a message +or body part +

+ SYNOPSIS +

+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;
+};
+

+ DESCRIPTION +

+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 contains 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 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 +<Field>(), where +<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 +MimeVersion(). The member function +<Field>() will create a header field with field +name <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 +Has<Field>(). For example, to check for the +existence of the MIME-version header field, use +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 +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. +

+ Public Member Functions +

+ 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>() function to test if the header +field already exists without creating it. +

+ 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 +<Field>() or +Has<Field>() family of functions. +

+ void +AddOrReplaceField(DwField* aField) + +

+Adds a DwField object to the list. If a header field with +the same field name already exists, it is replaced by the new header field. +

+DwHeaders takes responsibility for deleting the added +DwField object. +

+This is an advanced function. Consider using the member functions +<Field>() (e.g. To(), +ContentType(), and so on) and FieldBody() +to add header fields. +

+ 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 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). +

+DwHeaders takes responsibility for deleting the added +DwField object. +

+This is an advanced function. Consider using the member functions +<Field>() (e.g. To(), +ContentType(), and so on) and FieldBody() +for adding header fields. +

+ 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 +<Field>() (e.g. To(), +ContentType(), and so on) and FieldBody() +for adding header fields. +

+ 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. +

+ Public Data Members +

+ 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. +

+ -- cgit v1.2.1