home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / body.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  11.7 KB  |  276 lines
  1. //=============================================================================
  2. // File:       body.h
  3. // Contents:   Declarations for DwBody
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. //
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_BODY_H
  24. #define DW_BODY_H
  25.  
  26. #ifndef DW_CONFIG_H
  27. #include <mimelib/config.h>
  28. #endif
  29.  
  30. #ifndef DW_STRING_H
  31. #include <mimelib/string.h>
  32. #endif
  33.  
  34. #ifndef DW_ENTITY_H
  35. #include <mimelib/entity.h>
  36. #endif
  37.  
  38. class DwMessage;
  39. class DwEntity;
  40. class DwBodyPart;
  41.  
  42. //=============================================================================
  43. //+ Name DwBody -- Class representing a MIME message body
  44. //+ Description
  45. //. {\tt DwBody} represents a {\it body}, as described in RFC-2045.  A body
  46. //. is always part of an {\it entity}, which could be either a {\it message}
  47. //. or a {\it body part}.  An entity has a collection of {\it header fields}
  48. //. and a body.  If the content type of a body is ``multipart,'' then the
  49. //. body contains one or more body parts.  If the content type is ``message,''
  50. //. then the body contains an encapsulated message.  In all content types,
  51. //. the body contains a string of characters.
  52. //.
  53. //. In MIME++, a {\tt DwBody} object is contained in a {\tt DwEntity} object.
  54. //. The {\tt DwBody} object may contain a discrete body consisting only of a
  55. //. string of characters, or it may be a composite body, consisting of several
  56. //. contained {\tt DwBodyPart} objects or a single contained {\tt DwMessage}
  57. //. object.  The only reliable way to determine the type of {\tt DwBody} is
  58. //. to access the Content-Type header field from the {\tt DwHeaders} object
  59. //. of the {\tt DwEntity} that contains it.  For this reason, a {\tt DwBody}
  60. //. should always be part of a {\tt DwEntity}.
  61. //.
  62. //. In the tree (broken-down) representation of a message, a {\tt DwBody}
  63. //. object can be an intermediate node, having both a parent node and
  64. //. one or more child nodes, or a leaf node, having a parent but no child
  65. //. nodes.  In either case, the parent node is the {\tt DwEntity} object
  66. //. that contains it.  If it is an intermediate node, it must be of type
  67. //. multipart with {\tt DwBodyPart} objects as child nodes, or of type
  68. //. message with a single {\tt DwMessage} object as its child node.
  69. //.
  70. //. Normally, you do not create a {\tt DwBody} object directly, but you
  71. //. access it through the {\tt Body()} member function of {\tt DwEntity},
  72. //. which creates the {\tt DwBody} object for you.
  73. //.
  74. //. To add a {\tt DwBodyPart} to a multipart {\tt DwBody}, use the member
  75. //. function {\tt AddBodyPart()}.  To iterate over the {\tt DwBodyParts}
  76. //. contained in multipart {\tt DwBody}, get the first {\tt DwBodyPart}
  77. //. by calling {\tt FirstBodyPart()}.  Then get the following {\tt DwBodyParts}
  78. //. by calling {\tt DwBodyPart::Next()} on the current {\tt DwBodyPart}.
  79. //. To get the {\tt DwMessage} contained in a {\tt Body} with message
  80. //. content type, call {\tt Message()}.
  81. //=============================================================================
  82. // Last modified 1997-08-23
  83. //+ Noentry ~DwBody sClassName DeleteBodyParts CopyBodyParts _PrintDebugInfo
  84.  
  85.  
  86. class DW_EXPORT DwBody : public DwMessageComponent {
  87.  
  88.     friend class DwHeaders;
  89.     friend class DwEntity;
  90.     friend class DwBodyPart;
  91.  
  92. public:
  93.  
  94.     DwBody();
  95.     DwBody(const DwBody& aBody);
  96.     DwBody(const DwString& aStr, DwMessageComponent* aParent=0);
  97.     //. The first constructor is the default constructor, which sets the
  98.     //. {\tt DwBody} object's string representation to the empty string
  99.     //. and sets its parent to {\tt NULL}.
  100.     //.
  101.     //. The second constructor is the copy constructor, which performs
  102.     //. a deep copy of {\tt aBody}.
  103.     //. The parent of the new {\tt DwBody} object is set to {\tt NULL}.
  104.     //.
  105.     //. The third constructor copies {\tt aStr} to the {\tt DwBody}
  106.     //. object's string representation and sets {\tt aParent} as its parent.
  107.     //. The virtual member function {\tt Parse()} should be called immediately
  108.     //. after this constructor in order to parse the string representation.
  109.     //. Unless it is {\tt NULL}, {\tt aParent} should point to an object of
  110.     //. a class derived from {\tt DwEntity}.
  111.  
  112.     virtual ~DwBody();
  113.  
  114.     const DwBody& operator = (const DwBody& aBody);
  115.     //. This is the assignment operator, which performs a deep copy of
  116.     //. {\tt aBody}.  The parent node of the {\tt DwBody} object
  117.     //. is not changed.
  118.  
  119.     virtual void Parse();
  120.     //. This virtual function, inherited from {\tt DwMessageComponent},
  121.     //. executes the parse method for {\tt DwBody} objects.  The parse
  122.     //. method creates or updates the broken-down representation from the
  123.     //. string representation.  For a multipart {\tt DwBody} object, the
  124.     //. parse method creates a collection of {\tt DwBodyPart} objects.
  125.     //. For a message {\tt DwBody}, the parse method creates a single
  126.     //. {\tt DwMessage} object.  For any other type of {\tt DwBody},
  127.     //. the parse method does nothing.  This member function calls the
  128.     //. {\tt Parse()} member function of any objects it creates.
  129.     //.
  130.     //. Note: If the {\tt DwBody} object has no parent node -- that is,
  131.     //. it is not contained by a {\tt DwEntity} object -- then the parse
  132.     //. method does nothing, since it is unable to determine the type of
  133.     //. body.
  134.     //.
  135.     //. You should call this member function after you set or modify the
  136.     //. string representation, and before you access a contained
  137.     //. {\tt DwBodyPart} or {\tt DwMessage}.
  138.     //.
  139.     //. This function clears the is-modified flag.
  140.  
  141.     virtual void Assemble();
  142.     //. This virtual function, inherited from {\tt DwMessageComponent},
  143.     //. executes the assemble method for {\tt DwBody} objects.  The
  144.     //. assemble method creates or updates the string representation
  145.     //. from the broken-down representation.  Only {\tt DwBody} objects
  146.     //. with content type of multipart or message require assembling.
  147.     //. In either case, the {\tt DwBody} object must be able to find the
  148.     //. headers of the message or body part that contains it.  Therefore,
  149.     //. if the {\tt DwBody} object is not the child of a {\tt DwEntity}
  150.     //. ({\it i.e.}, {\tt DwMessage} or {\tt DwBodyPart}) object, the
  151.     //. {\tt DwBody} cannot be assembled because the content type cannot
  152.     //. be determined.
  153.     //.
  154.     //. This function calls the {\tt Parse()} member function of any
  155.     //. {\tt DwBodyPart} or {\tt DwMessage} object it contains.
  156.     //.
  157.     //. You should call this member function after you add a {\tt DwBodyPart}
  158.     //. object to a multipart body, or add a {\tt DwMessage} object to a
  159.     //. message body, and before you access the object's string representation.
  160.     //.
  161.     //. This function clears the is-modified flag.
  162.  
  163.     virtual DwMessageComponent* Clone() const;
  164.     //. This virtual function, inherited from {\tt DwMessageComponent},
  165.     //. creates a new {\tt DwBody} on the free store that has the same
  166.     //. value as this {\tt DwBody} object.  The basic idea is that of
  167.     //. a virtual copy constructor.
  168.  
  169.     DwBodyPart* FirstBodyPart() const;
  170.     //. For a multipart {\tt DwBody}, this member function returns the
  171.     //. first contained {\tt DwBodyPart} object.
  172.     //. Use {\tt DwBodyPart::Next()} to iterate through the list of
  173.     //. {\tt DwBodyPart}s.
  174.  
  175.     void AddBodyPart(DwBodyPart* aPart);
  176.     //. For a multipart {\tt DwBody}, this member function appends a
  177.     //. {\tt DwBodyPart} object to the list.  Any {\tt DwBodyPart} objects
  178.     //. added to a {\tt DwBody} object's list will be deleted by the
  179.     //. {\tt DwBody} object's destructor.
  180.  
  181.     void RemoveBodyPart(DwBodyPart* aPart);
  182.     //. For a multipart {\tt DwBody}, this member function removes a
  183.     //. {\tt DwBodyPart} object from the list. The caller is responsible
  184.     //. for deleting the bodypart afterwards!
  185.  
  186.     DwMessage* Message() const;
  187.     //. For a {\tt DwBody} with content type of message, this member function
  188.     //. returns the {\tt DwMessage} encapsulated in it.
  189.  
  190.     void SetMessage(DwMessage* aMessage);
  191.     //. For a {\tt DwBody} with content type of message, this member function
  192.     //. sets the {\tt DwMessage} object it contains.
  193.  
  194.     static DwBody* NewBody(const DwString& aStr, DwMessageComponent* aParent);
  195.     //. Creates a new {\tt DwBody} object on the free store.
  196.     //. If the static data member {\tt sNewBody} is {\tt NULL},
  197.     //. this member function will create a new {\tt DwBody}
  198.     //. and return it.  Otherwise, {\tt NewBody()} will call
  199.     //. the user-supplied function pointed to by {\tt sNewBody},
  200.     //. which is assumed to return an object from a class derived from
  201.     //. {\tt DwBody}, and return that object.
  202.  
  203.     //+ Var sNewBody
  204.     static DwBody* (*sNewBody)(const DwString&, DwMessageComponent*);
  205.     //. If {\tt sNewBody} is not {\tt NULL}, it is assumed to point to a
  206.     //. user-supplied function that returns an object from a class
  207.     //. derived from {\tt DwBody}.
  208.  
  209. protected:
  210.  
  211.     DwString    mBoundaryStr;
  212.     //. A cache for the boundary string, which is obtained from the
  213.     //. headers associated with this body.
  214.  
  215.     DwString    mPreamble;
  216.     //. Contains the preamble -- the text preceding the first boundary --
  217.     //. in a ``multipart/*'' media type.
  218.  
  219.     DwString    mEpilogue;
  220.     //. Contains the epilogue -- the text following the last boundary --
  221.     //. in a ``multipart/*'' media type.
  222.  
  223.     DwBodyPart* mFirstBodyPart;
  224.     //. Points to the first body part in a ``multipart/*'' media type.
  225.     //. Is {\tt NULL} if there are no body parts.
  226.  
  227.     DwMessage*  mMessage;
  228.     //. Points to the contained message, in a ``message/*'' media type.
  229.  
  230.     static const char* const sClassName;
  231.  
  232.     void _AddBodyPart(DwBodyPart*);
  233.     //. Adds a body part to a multipart body.  This function differs
  234.     //. from {\tt AddBodyPart} in that it does not set the is-modified
  235.     //. flag.
  236.  
  237.     void _RemoveBodyPart(DwBodyPart*);
  238.     //. Removes a body part from a multipart body.  This function differs
  239.     //. from {\tt RemoveBodyPart} in that it does not set the is-modified
  240.     //. flag.
  241.  
  242.     void _SetMessage(DwMessage*);
  243.     //. Sets a message to a body.  This function differs from
  244.     //. {\tt SetMessage()} in that it does not set the is-modified
  245.     //. flag.
  246.  
  247.     void CopyBodyParts(const DwBodyPart* aFirst);
  248.  
  249. public:
  250.     void DeleteBodyParts();
  251.  
  252.     virtual void PrintDebugInfo(std::ostream& aStrm, int aDepth=0) const;
  253.     //. This virtual function, inherited from {\tt DwMessageComponent},
  254.     //. prints debugging information about this object to {\tt aStrm}.
  255.     //. It will also call {\tt PrintDebugInfo()} for any of its child
  256.     //. components down to a level of {\tt aDepth}.
  257.     //.
  258.     //. This member function is available only in the debug version of
  259.     //. the library.
  260.  
  261.     virtual void CheckInvariants() const;
  262.     //. Aborts if one of the invariants of the object fails.  Use this
  263.     //. member function to track down bugs.
  264.     //.
  265.     //. This member function is available only in the debug version of
  266.     //. the library.
  267.  
  268. protected:
  269.  
  270.     void _PrintDebugInfo(std::ostream& aStrm) const;
  271.  
  272. };
  273.  
  274. #endif
  275.  
  276.