DwBody 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/body.html | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 mimelib/doc/body.html (limited to 'mimelib/doc/body.html') diff --git a/mimelib/doc/body.html b/mimelib/doc/body.html new file mode 100644 index 000000000..1526751a4 --- /dev/null +++ b/mimelib/doc/body.html @@ -0,0 +1,308 @@ + + + DwBody Man Page + + +

+ NAME +

+DwBody -- Class representing a MIME message body +

+ SYNOPSIS +

class DW_EXPORT DwBody : public DwMessageComponent {
+
+    friend class DwHeaders;
+    friend class DwEntity;
+    friend class DwBodyPart;
+
+public:
+
+    DwBody();
+    DwBody(const DwBody& aBody);
+    DwBody(const DwString& aStr, DwMessageComponent* aParent=0);
+    virtual ~DwBody();
+    const DwBody& operator = (const DwBody& aBody);
+    virtual void Parse();
+    virtual void Assemble();
+    virtual DwMessageComponent* Clone() const;
+    DwBodyPart* FirstBodyPart() const;
+    void AddBodyPart(DwBodyPart* aPart);
+    DwMessage* Message() const;
+    void SetMessage(DwMessage* aMessage);
+    static DwBody* NewBody(const DwString& aStr, DwMessageComponent* aParent);
+    static DwBody* (*sNewBody)(const DwString&, DwMessageComponent*);
+
+protected:
+
+    DwString    mBoundaryStr;
+    DwString    mPreamble;
+    DwString    mEpilogue;
+    DwBodyPart* mFirstBodyPart;
+    DwMessage*  mMessage;
+    static const char* const sClassName;
+    void _AddBodyPart(DwBodyPart*);
+    void _SetMessage(DwMessage*);
+    void DeleteBodyParts();
+    void CopyBodyParts(const DwBodyPart* aFirst);
+
+public:
+
+    virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
+    virtual void CheckInvariants() const;
+
+protected:
+
+    void _PrintDebugInfo(ostream& aStrm) const;
+};
+

+ DESCRIPTION +

+DwBody represents a body, as described in RFC-2045. +A body is always part of an entity, which could be either a +message or a body part. An entity has a collection of header +fields and a body. If the content type of a body is ``multipart,'' then +the body contains one or more body parts. If the content type is ``message,'' +then the body contains an encapsulated message. In all content types, the +body contains a string of characters. +

+In MIME++, a DwBody object is contained in a +DwEntity object. The +DwBody object may contain a discrete body consisting only +of a string of characters, or it may be a composite body, consisting of several +contained DwBodyPart objects +or a single contained +DwMessage object. The only reliable +way to determine the type of DwBody is to access the Content-Type +header field from the +DwHeaders object of the +DwEntity that contains it. For this reason, a +DwBody should always be part of a +DwEntity. +

+In the tree (broken-down) representation of a message, a +DwBody object can be an intermediate node, having both a +parent node and one or more child nodes, or a leaf node, having a parent +but no child nodes. In either case, the parent node is the +DwEntity object that contains it. If it is an intermediate +node, it must be of type multipart with DwBodyPart objects +as child nodes, or of type message with a single +DwMessage object as its child node. +

+Normally, you do not create a DwBody object directly, but +you access it through the Body() member function of +DwEntity, which creates the DwBody object +for you. +

+To add a DwBodyPart to a multipart +DwBody, use the member function +AddBodyPart(). To iterate over the +DwBodyParts contained in multipart +DwBody, get the first DwBodyPart by calling +FirstBodyPart(). Then get the following +DwBodyParts by calling DwBodyPart::Next() +on the current DwBodyPart. To get the +DwMessage contained in a Body with message +content type, call Message(). +

+ Public Member Functions +

+ DwBody()
+DwBody(const DwBody& aBody)
+DwBody(const DwString& aStr, DwMessageComponent* aParent=0) +

+The first constructor is the default constructor, which sets the +DwBody 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 aBody. The parent of the new DwBody object +is set to NULL. +

+The third constructor copies aStr to the +DwBody 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 DwBody& operator = (const +DwBody& aBody) +

+This is the assignment operator, which performs a deep copy of +aBody. The parent node of the DwBody object +is not changed. +

+ virtual void Parse() +

+This virtual function, inherited from DwMessageComponent, +executes the parse method for DwBody objects. The parse method +creates or updates the broken-down representation from the string representation. +For a multipart DwBody object, the parse method creates a +collection of DwBodyPart objects. For a message +DwBody, the parse method creates a single +DwMessage object. For any other type of +DwBody, the parse method does nothing. This member function +calls the Parse() member function of any objects it creates. +

+Note: If the DwBody object has no parent node -- that is, +it is not contained by a DwEntity object -- then the parse +method does nothing, since it is unable to determine the type of body. +

+You should call this member function after you set or modify the string +representation, and before you access a contained +DwBodyPart or DwMessage. +

+This function clears the is-modified flag. +

+ virtual void Assemble() + +

+This virtual function, inherited from DwMessageComponent, +executes the assemble method for DwBody objects. The assemble +method creates or updates the string representation from the broken-down +representation. Only DwBody objects with content type of +multipart or message require assembling. In either case, the +DwBody object must be able to find the headers of the message +or body part that contains it. Therefore, if the DwBody object +is not the child of a DwEntity (i.e., +DwMessage or DwBodyPart) object, the +DwBody cannot be assembled because the content type cannot +be determined. +

+This function calls the Parse() member function of any +DwBodyPart or DwMessage object it contains. +

+You should call this member function after you add a +DwBodyPart object to a multipart body, or add a +DwMessage object to a message body, and before you access +the object's string representation. +

+This function clears the is-modified flag. +

+ virtual DwMessageComponent* +Clone() const +

+This virtual function, inherited from DwMessageComponent, +creates a new DwBody on the free store that has the same +value as this DwBody object. The basic idea is that of a +virtual copy constructor. +

+ DwBodyPart* +FirstBodyPart() const +

+For a multipart DwBody, this member function returns the +first contained DwBodyPart object. Use +DwBodyPart::Next() to iterate through the list of +DwBodyParts. +

+ void AddBodyPart(DwBodyPart* +aPart) +

+For a multipart DwBody, this member function appends a +DwBodyPart object to the list. Any +DwBodyPart objects added to a DwBody object's +list will be deleted by the DwBody object's destructor. +

+ DwMessage* Message() const + +

+For a DwBody with content type of message, this member function +returns the DwMessage encapsulated in it. +

+ void SetMessage(DwMessage* +aMessage) +

+For a DwBody with content type of message, this member function +sets the DwMessage object it contains. +

+ static DwBody* NewBody(const +DwString& aStr, DwMessageComponent* aParent) +

+Creates a new DwBody object on the free store. If the static +data member sNewBody is NULL, this member +function will create a new DwBody and return it. Otherwise, +NewBody() will call the user-supplied function pointed to +by sNewBody, which is assumed to return an object from a +class derived from DwBody, 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 DwBody* +(*sNewBody)(const DwString&, DwMessageComponent*) + +

+If sNewBody is not NULL, it is assumed to +point to a user-supplied function that returns an object from a class derived +from DwBody. +

+ Protected Member Functions +

+ void +_AddBodyPart(DwBodyPart*) +

+Adds a body part to a multipart body. This function differs from +AddBodyPart in that it does not set the is-modified flag. +

+ void _SetMessage(DwMessage*) + +

+Sets a message to a body. This function differs from +SetMessage() in that it does not set the is-modified flag. +

+ Protected Data Members +

+ DwString mBoundaryStr + +

+A cache for the boundary string, which is obtained from the headers associated +with this body. +

+ DwString mPreamble +

+Contains the preamble -- the text preceding the first boundary -- in a +``multipart/*'' media type. +

+ DwString mEpilogue +

+Contains the epilogue -- the text following the last boundary -- in a +``multipart/*'' media type. +

+ DwBodyPart* +mFirstBodyPart +

+Points to the first body part in a ``multipart/*'' media type. Is +NULL if there are no body parts. +

+ DwMessage* mMessage +

+Points to the contained message, in a ``message/*'' media type. +

+ -- cgit v1.2.1