## 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 parent to `NULL`.

The second constructor is the copy constructor, which performs deep copy of `aMediaType`. The parent 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 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 `DwField`.

const DwMediaType& operator = (const DwMediaType& aMediaType)

This is the assignment operator, which performs a deep copy of `aMediaType`. The parent 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 parent 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`.