DispositionType Class Reference

Class that represents a MIME content-disposition field body More...

Inheritance diagram for DispositionType:

List of all members.

Public Member Functions

DispositionType ()

Default constructor.

DispositionType (const DispositionType &other)

Copy constructor.

DispositionType (const String &str, Node *parent=0)

Constructor that takes an initial string and parent node.

virtual ~DispositionType ()

Destructor.

const DispositionType & operator= (const DispositionType &other)

Assignment operator.

virtual void parse ()

Parses the string representation.

virtual void assemble ()

Assembles the string representation.

virtual Node * clone () const

Creates a copy of this object.

DType asEnum () const

Gets the disposition type as an enumerated value.

void fromEnum (DType type)

Sets the disposition type from an enumerated value.

const String & type () const

Gets the disposition type value.

void setType (const String &type)

Sets the disposition type value.

const String & filename () const

Gets the value of the filename parameter, if present.

void setFilename (const String &name)

Sets the value of the filename parameter.

const String & filenameUtf8 () const

Gets the decoded filename parameter, if present.

void setFilenameUtf8 (const String &name)

Sets the encoded filename parameter.

int numParameters () const

Gets the number of parameters in the list.

void addParameter (Parameter *param)

Adds a parameter to the end of the list.

void deleteAllParameters ()

Deletes all parameters in the list.

Parameter & parameterAt (int index) const

Gets the parameter at the specified position in the list.

void insertParameterAt (int index, Parameter *param)

Inserts a parameter at the specified position in the list.

Parameter * removeParameterAt (int index)

Removes the parameter at the specified position in the list.

Static Public Member Functions

static DispositionType * newDispositionType ()

Creates a new instance.

Static Public Attributes

static DispositionType *(* sNewDispositionType )()

Provides a class factory hook.

Protected Member Functions

void _copyParameters (const DispositionType &type)

Copies all parameters from another list.

void _addParameter (Parameter *parameter)

Adds a parameter to the end of the list.

void _insertParameterAt (int index, Parameter *param)

Inserts a parameter at the specified position in the list.

Parameter * _removeParameterAt (int index)

Removes the parameter at the specified position in the list.

void _deleteAllParameters ()

Deletes all parameters in the list.

Detailed Description

DispositionType represents a field body for the content-disposition header field as described in RFC 2183. This header field specifies whether the content of a message or body part should be displayed automatically to a user. A disposition type of inline indicates that the content should be displayed; a disposition type of attachment indicates that it should not be. RFC 2183 specifies that a filename parameter may be optionally included in the field body; the filename parameter suggests a file name for saving the message or body part's content.

DispositionType provides member functions that allow you to set or get the disposition type value and to manage a list of parameters. DispositionType also provides a convenience function that allows you to set or get the filename parameter.

Constructor & Destructor Documentation

DispositionType ( )

Default constructor.

This constructor sets the DispositionType object's string representation to the empty string and sets its parent node to NULL. The list of Parameter objects is initially empty.

DispositionType ( const DispositionType & other )

Copy constructor.

This constructor performs a deep copy of its argument. The parent node of the new DispositionType object is set to NULL.

Parameters:

other

DispositionType instance to copy

DispositionType	(	const String &	str,
		Node *	parent = `0`
	)

Constructor that takes an initial string and parent node.

This constructor sets the DispositionType object's string representation to str and sets its parent node to parent.

Normally, you call the virtual function parse() immediately after this constructor to create the broken-down representation.

Parameters:

	str	initial value for the string representation
	parent	parent node for this object

Member Function Documentation

void _addParameter ( Parameter * param ) [protected]

Adds a parameter to the end of the list.

This advanced member function is the same as addParameter(), but it does not set the is-modified flag.

Parameters:

param

Parameter object to add

See also:: addParameter()

void _copyParameters ( const DispositionType & type ) [protected]

Copies all parameters from another list.

This advanced member function copies the list of Parameter objects from type. It assumes the list in this DispositionType object is emtpy. It does not set the is-modified flag.

Parameters:

type

DispositionType object to copy Parameter objects from

void _deleteAllParameters ( ) [protected]

Deletes all parameters in the list.

This advanced member function is the same as deleteAllParameters(), but it does not set the is-modified flag.

See also:: deleteAllParameters()

void _insertParameterAt	(	int	index,
		Parameter *	param
	)			`[protected]`

Inserts a parameter at the specified position in the list.

This advanced member function is the same as insertParameterAt(), but it does not set the is-modified flag.

Parameters:

	index	position in the list to insert the Parameter object
	param	Parameter object to insert

See also:: insertParameterAt()

Parameter * _removeParameterAt ( int index ) [protected]

Removes the parameter at the specified position in the list.

This advanced member function is the same as removeParameterAt(), but it does not set the is-modified flag.

Parameters:

index

position of the Parameter object to remove

Returns:: pointer to the removed Parameter object

See also:: removeParameterAt()

void addParameter ( Parameter * param )

Adds a parameter to the end of the list.

The DispositionType destructor deletes the Parameter objects in the list.

Parameters:

param

Parameter object to add

DispositionType::DType asEnum ( ) const

Gets the disposition type as an enumerated value.

The enumerated values are defined in the DispositionType class and include the following values:

DispositionType::_NULL -- value not set
DispositionType::UNKNOWN -- value set to an unrecognized value
DispositionType::INLINE -- "inline"
DispositionType::ATTACHMENT -- "attachment"

As an alternative to asEnum(), you may call type() to get the value of the disposition type as a string value.

Returns:: disposition type as an enumerated value

void assemble ( ) [virtual]

Assembles the string representation.

This virtual function, inherited from Node, executes the assemble operation for DispositionType objects. The assemble operation creates or updates the string representation from the broken-down representation. For DispositionType objects, the assemble operation builds the string representation from the disposition type value and the list of Parameter objects. Before it builds the string representation for the DispositionType object, this function first calls the assemble() member function of each Parameter object in its list.

You should call this member function after you set or modify the disposition type value or any of the contained Parameter objects, and before you retrieve the string representation.

This function clears the is-modified flag.

Reimplemented from FieldBody.

Node * clone ( ) const [virtual]

Creates a copy of this object.

This virtual function, inherited from Node, creates a new DispositionType object that has the same value as this DispositionType object. The parent node of the new DispositionType object is set to NULL.

Returns:: a copy of this object

Reimplemented from FieldBody.

const String & filename ( ) const

Gets the value of the filename parameter, if present.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

This convenience function gets the value of the filename parameter, if it is present. If it is absent, then this method returns an empty string.

The filename() member function gets the value of only the unencoded filename parameter. In most cases, you should use the filenameUtf8() member function, which gets the decoded value of the encoded filename parameter.

Returns:: value of the filename parameter; or the empty string if there is no filename parameter

See also:: filenameUtf8()

const String & filenameUtf8 ( ) const

Gets the decoded filename parameter, if present.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

RFC 2231 specifies how parameters in a MIME header field should be encoded if they contain values with non-ASCII characters, or if they have values that are too long to fit on a single line. Hunny MIME++ provides the filenameUtf8() convenience method to decode a filename parameter that is encoded according to RFC 2231.

Not many email clients support RFC 2231. Notably, Microsoft Outlook does not support it. Mozilla Thunderbird can accept a filename parameter encoded according to RFC 2231; however, it does not generate RFC-2231-encoded filename parameters. Therefore, it is probably a good idea to include both an unencoded filename and an encoded filename parameter. The following example has an unencoded and an encoded filename parameter:

 Disposition-Type: attachment;
   filename="Viel Spass.txt";
   filename*=utf-8''Viel%20Spa%c3%9f

Hunny MIME++ provides the filename() convenience function to get the unencoded filename parameter. However, that member function is not really necessary. If you want to keep your code simple, you can use just the filenameUtf8() member function. filenameUtf8() gets the encoded filename parameter (filename*) if it's present, but gets the unencoded parameter (filename) if the encoded filename parameter is absent.

Returns:: the Unicode file name, if present; otherwise, an empty string

See also:: RFC 2231 MIME Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations
filename()

void fromEnum ( DispositionType::DType type )

Sets the disposition type from an enumerated value.

The enumerated values are defined in the DispositionType class and include the following values:

DispositionType::_NULL -- value not set
DispositionType::UNKNOWN -- value set to an unrecognized value
DispositionType::INLINE -- "inline"
DispositionType::ATTACHMENT -- "attachment"

You should not use DispositionType::_NULL or DispositionType::UNKNOWN as arguments for the fromEnum() member function.

As an alternative to fromEnum(), you may call setType() to set the value of the disposition type from a string value.

Parameters:

type

disposition type as an enumerated value

void insertParameterAt	(	int	index,
		Parameter *	param
	)

Inserts a parameter at the specified position in the list.

If index is zero, then the function inserts param into the first position in the list. If index equals numParameters(), then the function inserts param into the last position in the list. If index is less than numParameters(), then the function moves the Parameter objects at position index or greater to a higher position in the list.

The DispositionType destructor deletes the Parameter objects in the list.

The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index <= numParameters().

Parameters:

	index	position in the list to insert the Parameter object
	param	Parameter object to insert

DispositionType * newDispositionType ( ) [static]

Creates a new instance.

If the static data member sNewDispositionType is NULL, this member function creates a new DispositionType object and returns it. Otherwise, newDispositionType() calls the user-supplied function that sNewDispositionType points to and returns the object created by that function.

Returns:: new DispositionType instance

See also:: sNewDispositionType

int numParameters ( ) const

Gets the number of parameters in the list.

Returns:: number of Parameter objects in the list

const DispositionType & operator= ( const DispositionType & other )

Assignment operator.

This function does not change parent node of this DispositionType object.

Parameters:

other

DispositionType instance to copy

Parameter & parameterAt ( int index ) const

Gets the parameter at the specified position in the list.

The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index < numParameters().

Parameters:

index

position of the Parameter object to get

Returns:: reference to the Parameter object at the specified position

void parse ( ) [virtual]

Parses the string representation.

This virtual function, inherited from Node, executes the parse operation for DispositionType objects. The parse operation creates or updates the broken-down representation from the string representation. For DispositionType objects, the parse operation parses the string representation to extract the disposition type value, and to create a list of Parameter objects. This member function also calls the parse() member function of each Parameter object in its list.

You should call this member function after you set or modify the string representation, and before you access the disposition type value or any of the contained Parameter objects.

This function clears the is-modified flag.

Reimplemented from FieldBody.

Parameter * removeParameterAt ( int index )

Removes the parameter at the specified position in the list.

The function returns a pointer to the Parameter object at the specified position and removes it from the list. To avoid a memory leak, you must delete the Parameter object when you no longer need it (which may be immediately after you remove it from the list).

If index is less than numParameters()-1, then the function moves the Parameter objects at position (index + 1) or greater to a lower position in the list.

The function's behavior is undefined if index is out of range. Valid values for index are 0 <= index < numParameters().

Parameters:

index

position of the Parameter object to remove

Returns:: pointer to the removed Parameter object

void setFilename ( const String & name )

Sets the value of the filename parameter.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

This convenience function sets the value of the filename parameter to name.

To comply with RFC 2822 and MIME, the file name must contain only ASCII characters. Hunny MIME++ also provides a setFilenameUtf8() convenience function that accepts any Unicode file name and correctly encodes it according to the MIME standard.

Parameters:

name

value of the filename parameter

See also:: filename()
setFilenameUtf8()

void setFilenameUtf8 ( const String & name )

Sets the encoded filename parameter.

The filename parameter suggests a file name for the body part, which in most cases is a file attachment.

RFC 2231 specifies how parameters in a MIME header field should be encoded if they contain values with non-ASCII characters, or if they have values that are too long to fit on a single line. Hunny MIME++ provides the setFilenameUtf8() convenience function to encode the filename parameter according to RFC 2231.

The setFilenameUtf8() member function encodes to UTF-8 only. The rationale for this decision is that all modern operating systems use Unicode for file names. So, if you encode a file name from Unicode into, say, EUC-KR (Korean), then the receiving implementation must decode from EUC-KR back into Unicode in order to pass the file name to the operating system.

Not many email clients support RFC 2231. Notably, Microsoft Outlook does not support it. Mozilla Thunderbird can accept a filename parameter encoded according to RFC 2231; however, it does not generate RFC-2231-encoded filename parameters. Therefore, it is probably a good idea to include both an unencoded filename and an encoded filename parameter. The following example has an unencoded and an encoded filename parameter:

 Disposition-Type: attachment;
   filename="Viel Spass.txt";
   filename*=utf-8''Viel%20Spa%c3%9f

With Hunny MIME++, you can set both an unencoded filename parameter and an encoded filename parameter. Use the setFilename() member function to set the unencoded filename parameter. Use setFilenameUtf8() to set the encoded filename parameter.

Parameters:

name

the value for the encoded filename parameter, as a UTF-8 string

filenameUtf8()

setFilename()

void setType ( const String & type )

Sets the disposition type value.

Parameters:

type

disposition type value

const String & type ( ) const

Gets the disposition type value.

Returns:: disposition type value

Member Data Documentation

DispositionType *(* sNewDispositionType)()=0 ( ) [static]

Provides a class factory hook.

If sNewDispositionType is not NULL, it must point to a user-supplied function that returns a new instance of a subclass of DispositionType.

See also:: newDispositionType()


Public Member Functions
	DispositionType ()
	Default constructor.
	DispositionType (const DispositionType &other)
	Copy constructor.
	DispositionType (const String &str, Node *parent=0)
	Constructor that takes an initial string and parent node.
virtual	~DispositionType ()
	Destructor.
const DispositionType &	operator= (const DispositionType &other)
	Assignment operator.
virtual void	parse ()
	Parses the string representation.
virtual void	assemble ()
	Assembles the string representation.
virtual Node *	clone () const
	Creates a copy of this object.
DType	asEnum () const
	Gets the disposition type as an enumerated value.
void	fromEnum (DType type)
	Sets the disposition type from an enumerated value.
const String &	type () const
	Gets the disposition type value.
void	setType (const String &type)
	Sets the disposition type value.
const String &	filename () const
	Gets the value of the filename parameter, if present.
void	setFilename (const String &name)
	Sets the value of the filename parameter.
const String &	filenameUtf8 () const
	Gets the decoded filename parameter, if present.
void	setFilenameUtf8 (const String &name)
	Sets the encoded filename parameter.
int	numParameters () const
	Gets the number of parameters in the list.
void	addParameter (Parameter *param)
	Adds a parameter to the end of the list.
void	deleteAllParameters ()
	Deletes all parameters in the list.
Parameter &	parameterAt (int index) const
	Gets the parameter at the specified position in the list.
void	insertParameterAt (int index, Parameter *param)
	Inserts a parameter at the specified position in the list.
Parameter *	removeParameterAt (int index)
	Removes the parameter at the specified position in the list.
Static Public Member Functions
static DispositionType *	newDispositionType ()
	Creates a new instance.
Static Public Attributes
static DispositionType (	sNewDispositionType )()
	Provides a class factory hook.
Protected Member Functions
void	_copyParameters (const DispositionType &type)
	Copies all parameters from another list.
void	_addParameter (Parameter *parameter)
	Adds a parameter to the end of the list.
void	_insertParameterAt (int index, Parameter *param)
	Inserts a parameter at the specified position in the list.
Parameter *	_removeParameterAt (int index)
	Removes the parameter at the specified position in the list.
void	_deleteAllParameters ()
	Deletes all parameters in the list.