1 //============================================================================= 2 // File: mediatyp.h 3 // Contents: Declarations for DwMediaType 4 // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net> 5 // WWW: http://www.fwb.gulf.net/~dwsauder/mimepp.html 6 // $Revision: 1.6 $ 7 // $Date: 1997/09/27 11:55:27 $ 8 // 9 // Copyright (c) 1996, 1997 Douglas W. Sauder 10 // All rights reserved. 11 // 12 // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT, 13 // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF 14 // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER 15 // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 16 // 17 // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT 18 // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 19 // PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS" 20 // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE, 21 // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS. 22 // 23 //============================================================================= 24 25 #ifndef DW_MEDIATYP_H 26 #define DW_MEDIATYP_H 27 28 #ifndef DW_CONFIG_H 29 #include <mimelib/config.h> 30 #endif 31 32 #ifndef DW_STRING_H 33 #include <mimelib/string.h> 34 #endif 35 36 #ifndef DW_FIELDBDY_H 37 #include <mimelib/fieldbdy.h> 38 #endif 39 40 class DwParameter; 41 42 //============================================================================= 43 //+ Name DwMediaType -- Class representing a MIME media-type 44 //+ Description 45 //. {\tt DwMediaType} represents a field body for the Content-Type header 46 //. field as described in RFC-2045. This field body specifies the kind of 47 //. data contained in the body of a message or a body part. A media type 48 //. is described by two keywords: a primary type (or just {\it type}) and 49 //. a {\it subtype}. RFC-2046 specifies the seven primary types text, 50 //. multipart, message, image, audio, video, and application. RFC-2077 51 //. adds the new primary type model. 52 //. 53 //. {\tt DwMediaType} has member functions that allow you to set or get 54 //. the type and subtype as either enumerated values or as strings. It 55 //. also contains a list of {\tt DwParameter} objects that represent the 56 //. parameters of the field body. You can use convenience functions to 57 //. directly access the boundary parameter of a multipart media type, or 58 //. to access the name parameter that is often used with several media 59 //. types, such as application/octet-stream. 60 //. 61 //. Some MIME parsers have problems with folded header fields, and this 62 //. especially seems to be a problem with the Content-Type field. 63 //. To disable folding when the {\tt DwMediaType} object is assembled, 64 //. call the inherited member function {\tt DwFieldBody::SetFolding()} 65 //. with an argument of {\tt DwFalse}. 66 //============================================================================= 67 // Last updated 1997-08-30 68 //+ Noentry ~DwMediaType 69 //+ Noentry _AddParameter TypeEnumToStr TypeStrToEnum SubtypeEnumToStr 70 //+ Noentry SubtypeStrToEnum DeleteParameterList CopyParameterList 71 //+ Noentry mType mSubtype mTypeStr mSubtypeStr mBoundaryStr mFirstParameter 72 //+ Noentry _PrintDebugInfo mNameStr 73 74 75 class DW_EXPORT DwMediaType : public DwFieldBody { 76 77 public: 78 79 DwMediaType(); 80 DwMediaType(const DwMediaType& aMediaType); 81 DwMediaType(const DwString& aStr, DwMessageComponent* aParent=0); 82 //. The first constructor is the default constructor, which sets the 83 //. {\tt DwMediaType} object's string representation to the empty string 84 //. and sets its parent to {\tt NULL}. 85 //. 86 //. The second constructor is the copy constructor, which performs 87 //. deep copy of {\tt aMediaType}. 88 //. The parent of the new {\tt DwMediaType} object is set to {\tt NULL}. 89 //. 90 //. The third constructor copies {\tt aStr} to the {\tt DwMediaType} 91 //. object's string representation and sets {\tt aParent} as its parent. 92 //. The virtual member function {\tt Parse()} should be called immediately 93 //. after this constructor in order to parse the string representation. 94 //. Unless it is {\tt NULL}, {\tt aParent} should point to an object of 95 //. a class derived from {\tt DwField}. 96 97 virtual ~DwMediaType(); 98 99 const DwMediaType& operator = (const DwMediaType& aMediaType); 100 //. This is the assignment operator, which performs a deep copy of 101 //. {\tt aMediaType}. The parent node of the {\tt DwMediaType} 102 //. object is not changed. 103 104 virtual void Parse(); 105 //. This virtual function, inherited from {\tt DwMessageComponent}, 106 //. executes the parse method for {\tt DwMediaType} objects. 107 //. It should be called immediately after the string representation 108 //. is modified and before the parts of the broken-down 109 //. representation are accessed. 110 //. 111 //. This function clears the is-modified flag. 112 113 virtual void Assemble(); 114 //. This virtual function, inherited from {\tt DwMessageComponent}, 115 //. executes the assemble method for {\tt DwMediaType} objects. 116 //. It should be called whenever one of the object's attributes 117 //. is changed in order to assemble the string representation from 118 //. its broken-down representation. It will be called 119 //. automatically for this object by the parent object's 120 //. {\tt Assemble()} member function if the is-modified flag is set. 121 //. 122 //. This function clears the is-modified flag. 123 124 virtual DwMessageComponent* Clone() const; 125 //. This virtual function, inherited from {\tt DwMessageComponent}, 126 //. creates a new {\tt DwMediaType} object on the free store that 127 //. has the same value as this {\tt DwMediaType} object. The basic 128 //. idea is that of a virtual copy constructor. 129 130 int Type() const; 131 //. Returns the primary type as an enumerated value. Enumerated values 132 //. are defined for all standard types in the file enum.h. If the type 133 //. is non-standard, {\tt DwMime::kTypeUnknown} is returned. The member 134 //. function {\tt TypeStr()} may be used to get the value of any type, 135 //. standard or non-standard, as a string. 136 137 void SetType(int aType); 138 //. Sets the primary type from the enumerated value {\tt aType}. 139 //. Enumerated values are defined for all standard types in the file 140 //. enum.h. The member function {\tt SetTypeStr()} may be used to 141 //. set the value of any type, standard or non-standard, from a string. 142 143 const DwString& TypeStr() const; 144 //. Returns the primary type as a string. 145 146 void SetTypeStr(const DwString& aStr); 147 //. Sets the primary type from a string. 148 149 int Subtype() const; 150 //. Returns the subtype as an enumerated value. Enumerated values 151 //. are defined for all standard subtypes in the file enum.h. If 152 //. the subtype is non-standard, {\tt DwMime::kSubtypeUnknown} is 153 //. returned. The member function {\tt SubtypeStr()} may be used 154 //. to get the value of any subtype, standard or non-standard, as 155 //. a string. 156 157 void SetSubtype(int aSubtype); 158 //. Sets the subtype from the enumerated value {\tt aSubtype}. 159 //. Enumerated values are defined for all standard subtypes in the 160 //. file enum.h. The member function {\tt SetSubtypeStr()} may be 161 //. used to set the value of any subtype, standard or non-standard, 162 //. from a string. 163 164 const DwString& SubtypeStr() const; 165 //. Returns the subtype as a string. 166 167 void SetSubtypeStr(const DwString& aStr); 168 //. Sets the subtype from a string. 169 170 const DwString& Boundary() const; 171 //. For the multipart type only, returns the value of the boundary 172 //. parameter. This member function is a convenience function 173 //. that searches the list of {\tt DwParameter} objects. 174 175 void SetBoundary(const DwString& aStr); 176 //. For the multipart type only, sets the value of the boundary 177 //. parameter. 178 //. This member function is a convenience function that accesses the 179 //. list of {\tt DwParameter} objects. 180 181 virtual void CreateBoundary(unsigned aLevel=0); 182 //. For the multipart type only, creates a boundary string. {\tt aLevel} 183 //. indicates the level of a nested multipart body part; if it is 184 //. positive, it is used to form part of the created boundary string. 185 //. This member function is a convenience function that accesses the 186 //. list of child {\tt DwParameter} objects. 187 188 const DwString& Name() const; 189 //. Returns the value of the "name" parameter, if such a parameter 190 //. is present. The name parameter is often found in several media 191 //. types, including the application/octet-stream media type; it 192 //. suggests a file name for saving to a disk file. (The filename 193 //. parameter in the Content-Disposition header field is an alternative 194 //. way to indicate a file name.) This member function is a convenience 195 //. function that searches the list of {\tt DwParameter} objects. 196 197 void SetName(const DwString& aStr); 198 //. Sets the value of the "name" parameter. If a name parameter is 199 //. not already present, it is added. The name parameter is often 200 //. found in several media types, including the application/octet-stream 201 //. media type; it suggests a file name for saving to a disk file. 202 //. (The filename parameter in the Content-Disposition header field 203 //. is an alternative way to indicate a file name.) This member 204 //. function is a convenience function that accesses the list of 205 //. {\tt DwParameter} objects. 206 207 DwParameter* FirstParameter() const; 208 //. Returns the first {\tt DwParameter} object in the list managed by 209 //. this {\tt DwMediaType} object. Use {\tt DwParameter::Next()} to 210 //. iterate through the list. 211 212 void AddParameter(DwParameter* aParam); 213 //. Adds a {\tt DwParameter} object to the list managed by this 214 //. {\tt DwMediaType} object. 215 216 static DwMediaType* NewMediaType(const DwString& aStr, 217 DwMessageComponent* aParent); 218 //. Creates a new {\tt DwMediaType} object on the free store. 219 //. If the static data member {\tt sNewMediaType} is {\tt NULL}, 220 //. this member function will create a new {\tt DwMediaType} 221 //. and return it. Otherwise, {\tt NewMediaType()} will call 222 //. the user-supplied function pointed to by {\tt sNewMediaType}, 223 //. which is assumed to return an object from a class derived from 224 //. {\tt DwMediaType}, and return that object. 225 226 //+ Var sNewMediaType 227 static DwMediaType* (*sNewMediaType)(const DwString&, 228 DwMessageComponent*); 229 //. If {\tt sNewMediaType} is not {\tt NULL}, it is assumed to point to a 230 //. user-supplied function that returns an object from a class derived 231 //. from {\tt DwMediaType}. 232 233 protected: 234 235 void _AddParameter(DwParameter* aParam); 236 //. Adds a parameter without setting the is-modified flag. 237 238 virtual void TypeEnumToStr(); 239 virtual void TypeStrToEnum(); 240 virtual void SubtypeEnumToStr(); 241 virtual void SubtypeStrToEnum(); 242 void DeleteParameterList(); 243 void CopyParameterList(DwParameter* aFirst); 244 245 int mType; 246 int mSubtype; 247 DwString mTypeStr; 248 DwString mSubtypeStr; 249 DwString mBoundaryStr; 250 DwString mNameStr; 251 DwParameter* mFirstParameter; 252 253 private: 254 255 static const char* const sClassName; 256 257 public: 258 259 virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const; 260 //. This virtual function, inherited from {\tt DwMessageComponent}, 261 //. prints debugging information about this object to {\tt aStrm}. 262 //. It will also call {\tt PrintDebugInfo()} for any of its child 263 //. components down to a level of {\tt aDepth}. 264 //. 265 //. This member function is available only in the debug version of 266 //. the library. 267 268 virtual void CheckInvariants() const; 269 //. Aborts if one of the invariants of the object fails. Use this 270 //. member function to track down bugs. 271 //. 272 //. This member function is available only in the debug version of 273 //. the library. 274 275 protected: 276 277 void _PrintDebugInfo(ostream& aStrm) const; 278 279 }; 280 281 #endif 282