NAME

DwMediaType -- Class representing a MIME media-type

SYNOPSIS

class DW_EXPORT DwMediaType : public DwFieldBody {

public:

    DwMediaType();
    DwMediaType(const DwMediaType& aMediaType);
    DwMediaType(const DwString& aStr, DwMessageComponent* aParent=0);
    virtual ~DwMediaType();
    const DwMediaType& operator = (const DwMediaType& aMediaType);
    virtual void Parse();
    virtual void Assemble();
    virtual DwMessageComponent* Clone() const;
    int Type() const;
    void SetType(int aType);
    const DwString& TypeStr() const;
    void SetTypeStr(const DwString& aStr);
    int Subtype() const;
    void SetSubtype(int aSubtype);
    const DwString& SubtypeStr() const;
    void SetSubtypeStr(const DwString& aStr);
    const DwString& Boundary() const;
    void SetBoundary(const DwString& aStr);
    virtual void CreateBoundary(unsigned aLevel=0);
    const DwString& Name() const;
    void SetName(const DwString& aStr);
    DwParameter* FirstParameter() const;
    void AddParameter(DwParameter* aParam);
    static DwMediaType* NewMediaType(const DwString& aStr,
        DwMessageComponent* aParent);
    static DwMediaType* (*sNewMediaType)(const DwString&,
        DwMessageComponent*);

protected:

    void _AddParameter(DwParameter* aParam);
    virtual void TypeEnumToStr();
    virtual void TypeStrToEnum();
    virtual void SubtypeEnumToStr();
    virtual void SubtypeStrToEnum();
    void DeleteParameterList();
    void CopyParameterList(DwParameter* aFirst);
    int mType;
    int mSubtype;
    DwString mTypeStr;
    DwString mSubtypeStr;
    DwString mBoundaryStr;
    DwString mNameStr;
    DwParameter* mFirstParameter;

public:

    virtual void PrintDebugInfo(ostream& aStrm, int aDepth=0) const;
    virtual void CheckInvariants() const;

protected:

    void _PrintDebugInfo(ostream& aStrm) const;
};

DESCRIPTION

DwMediaType represents a field body for the Content-Type header field as described in RFC-2045. This field body specifies the kind of data contained in the body of a message or a body part. A media type is described by two keywords: a primary type (or just type) and a subtype. RFC-2046 specifies the seven primary types text, multipart, message, image, audio, video, and application. RFC-2077 adds the new primary type model.

DwMediaType has member functions that allow you to set or get the type and subtype as either enumerated values or as strings. It also contains a list of DwParameter objects that represent the parameters of the field body. You can use convenience functions to directly access the boundary parameter of a multipart media type, or to access the name parameter that is often used with several media types, such as application/octet-stream.

Some MIME parsers have problems with folded header fields, and this especially seems to be a problem with the Content-Type field. To disable folding when the DwMediaType object is assembled, call the inherited member function DwFieldBody::SetFolding() with an argument of DwFalse.

Public Member Functions

DwMediaType()
DwMediaType(const DwMediaType& aMediaType)
DwMediaType(const DwString& aStr, DwMessageComponent* aParent=0)

The first constructor is the default constructor, which sets the DwMediaType object's string representation to the empty string and sets its tqparent to NULL.

The second constructor is the copy constructor, which performs deep copy of aMediaType. The tqparent of the new DwMediaType object is set to NULL.

The third constructor copies aStr to the DwMediaType object's string representation and sets aParent as its tqparent. 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 DwField.

const DwMediaType& operator = (const DwMediaType& aMediaType)

This is the assignment operator, which performs a deep copy of aMediaType. The tqparent node of the DwMediaType object is not changed.

virtual void Parse()

This virtual function, inherited from DwMessageComponent, executes the parse method for DwMediaType objects. It should be called immediately after the string representation is modified and before the parts of the broken-down representation are accessed.

This function clears the is-modified flag.

virtual void Assemble()

This virtual function, inherited from DwMessageComponent, executes the assemble method for DwMediaType objects. It should be called whenever one of the object's attributes is changed in order to assemble the string representation from its broken-down representation. It will be called automatically for this object by the tqparent object's Assemble() member function if the is-modified flag is set.

This function clears the is-modified flag.

virtual DwMessageComponent* Clone() const

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

int Type() const

Returns the primary type as an enumerated value. Enumerated values are defined for all standard types in the file enum.h. If the type is non-standard, DwMime::kTypeUnknown is returned. The member function TypeStr() may be used to get the value of any type, standard or non-standard, as a string.

void SetType(int aType)

Sets the primary type from the enumerated value aType. Enumerated values are defined for all standard types in the file enum.h. The member function SetTypeStr() may be used to set the value of any type, standard or non-standard, from a string.

const DwString& TypeStr() const

Returns the primary type as a string.

void SetTypeStr(const DwString& aStr)

Sets the primary type from a string.

int Subtype() const

Returns the subtype as an enumerated value. Enumerated values are defined for all standard subtypes in the file enum.h. If the subtype is non-standard, DwMime::kSubtypeUnknown is returned. The member function SubtypeStr() may be used to get the value of any subtype, standard or non-standard, as a string.

void SetSubtype(int aSubtype)

Sets the subtype from the enumerated value aSubtype. Enumerated values are defined for all standard subtypes in the file enum.h. The member function SetSubtypeStr() may be used to set the value of any subtype, standard or non-standard, from a string.

const DwString& SubtypeStr() const

Returns the subtype as a string.

void SetSubtypeStr(const DwString& aStr)

Sets the subtype from a string.

const DwString& Boundary() const

For the multipart type only, returns the value of the boundary parameter. This member function is a convenience function that searches the list of DwParameter objects.

void SetBoundary(const DwString& aStr)

For the multipart type only, sets the value of the boundary parameter. This member function is a convenience function that accesses the list of DwParameter objects.

virtual void CreateBoundary(unsigned aLevel=0)

For the multipart type only, creates a boundary string. aLevel indicates the level of a nested multipart body part; if it is positive, it is used to form part of the created boundary string. This member function is a convenience function that accesses the list of child DwParameter objects.

const DwString& Name() const

Returns the value of the "name" parameter, if such a parameter is present. The name parameter is often found in several media types, including the application/octet-stream media type; it suggests a file name for saving to a disk file. (The filename parameter in the Content-Disposition header field is an alternative way to indicate a file name.) This member function is a convenience function that searches the list of DwParameter objects.

void SetName(const DwString& aStr)

Sets the value of the "name" parameter. If a name parameter is not already present, it is added. The name parameter is often found in several media types, including the application/octet-stream media type; it suggests a file name for saving to a disk file. (The filename parameter in the Content-Disposition header field is an alternative way to indicate a file name.) This member function is a convenience function that accesses the list of DwParameter objects.

DwParameter* FirstParameter() const

Returns the first DwParameter object in the list managed by this DwMediaType object. Use DwParameter::Next() to iterate through the list.

void AddParameter(DwParameter* aParam)

Adds a DwParameter object to the list managed by this DwMediaType object.

static DwMediaType* NewMediaType(const DwString& aStr, DwMessageComponent* aParent)

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

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