DwMediaType Man Page

## NAME

DwMediaType -- Class representing a MIME media-type

## SYNOPSIS

    class DW_CORE_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);
        int NumParameters() const;
        void AddParameter(DwParameter* aParam);
        void DeleteAllParameters();
        DwParameter& ParameterAt(int aIndex) const;
        void InsertParameterAt(int aIndex, DwParameter* aParam);
        DwParameter* RemoveParameterAt(int aIndex);
        static DwMediaType* NewMediaType(const DwString& aStr,
            DwMessageComponent* aParent);
        static DwMediaType* (*sNewMediaType)(const DwString&,
            DwMessageComponent*);

    protected:

        int mType;
        int mSubtype;
        DwString mTypeStr;
        DwString mSubtypeStr;
        DwString mBoundaryStr;
        DwString mNameStr;
        virtual void TypeEnumToStr();
        virtual void TypeStrToEnum();
        virtual void SubtypeEnumToStr();
        virtual void SubtypeStrToEnum();
        void _CopyParameters(const DwMediaType& aType);
        void _AddParameter(DwParameter* aParameter);
        void _InsertParameterAt(int aIndex, DwParameter* aParam);
        void _DeleteAllParameters();

    public:

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

    protected:

        void _PrintDebugInfo(DW_STD 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.

int NumParameters() const

Returns the number of `DwParameter` objects contained in this `DwMediaType` object.

void AddParameter(DwParameter* aParam)

Appends a `DwParameter` object to the list managed by this `DwMediaType` object.

Any `DwParameter` objects contained in a `DwMediaType` object's list will be deleted by the `DwMediaType` object's destructor.

void DeleteAllParameters()

Removes and deletes all `DwParameter` objects contained in this `DwMediaType` object.

DwParameter& ParameterAt(int aIndex) const

Returns the `DwParameter` object at position `aIndex` in this `DwMediaType` object's list.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `NumParameters()`.

void InsertParameterAt(int aIndex, DwParameter* aParam)

Inserts `aParam` into the list of `DwParameter` objects at the position given by `aIndex`. A value of zero for `aIndex` will insert `aParam` as the first one in the list; a value of `NumParameters()` will insert it as the last one in the list. If `aIndex` is less than `NumParameters()`, the `DwParameter` objects at position `aIndex` or greater will be shifted down the list to make room to insert `aParam`.

Any `DwParameter` objects contained in a `DwMediaType` object's list will be deleted by the `DwMediaType` object's destructor.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` <= `NumParameters()`.

DwParameter* RemoveParameterAt(int aIndex)

Removes the `DwParameter` object at position `aIndex` from the list and returns it. If `aIndex` is less than `NumParameters()-1`, then any `DwParameter` objects at a position greater than `aIndex` will be shifted up in the list after the requested `DwParameter` is removed.

If the library is compiled to throw exceptions, the function will throw a `DwBoundsException` if `aIndex` is out of range. Otherwise, (if the library is compiled not to throw exceptions) the behavior is undefined if `aIndex` is out of range. Valid values for `aIndex` are 0 <= `aIndex` < `Numparameters()`.

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(DW_STD 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`.

## Protected Member Functions

void _CopyParameters(const DwMediaType& aType)

Copies the list of `DwParameter` objects from `aType`.

void _AddParameter(DwParameter* aParameter)

Same as `AddParameter()`, but does not set is-modified flag.

void _InsertParameterAt(int aIndex, DwParameter* aParam)

Performs all the work of adding `DwParameter` objects to the list. This function does not set the is-modified flag.

void _DeleteAllParameters()

Deletes all parameters. Differs from `DeleteAllParameters()` in that it does not set the is-modified flag.