EncodedWord Class Reference

Class that represents an encoded word in a header field More...

Inheritance diagram for EncodedWord:

List of all members.

Public Member Functions
	EncodedWord ()
	Default constructor.
	EncodedWord (const EncodedWord &word)
	Copy constructor.
	EncodedWord (const String &str, Node *parent=0)
	Constructor that takes an initial string and parent node.
virtual	~EncodedWord ()
	Destructor.
const EncodedWord &	operator= (const EncodedWord &word)
	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.
const String &	charset () const
	Gets the charset designator.
void	setCharset (const String &charset)
	Sets the charset designator.
char	encodingType () const
	Gets the encoding type.
void	setEncodingType (char encodingType)
	Sets the encoding type.
const String &	decodedText () const
	Gets the decoded text.
void	setDecodedText (const String &text)
	Sets the decoded text.
Static Public Member Functions
static String	qEncode (const String &str)
	Encodes a string with the Q encoding.
static String	bEncode (const String &str)
	Encodes a string with the B encoding.
static int	qDecode (const String &inStr, String &outStr)
	Decodes a string with the Q encoding.
static int	bDecode (const String &inStr, String &outStr)
	Decodes a string with the B encoding.
static EncodedWord *	newEncodedWord ()
	Creates a new instance.
Static Public Attributes
static EncodedWord *(*	sNewEncodedWord )()
	Provides a class factory hook.

---

Detailed Description

EncodedWord represents an encoded word in a non-structured header field. In Internet email, and in MIME, only 7-bit ASCII characters are allowed in the header fields. RFC 2047 describes the method by which non-ASCII text can be encoded and inserted into certain header fields. In Hunny MIME++, EncodedWord represents a segment of encoded text and performs the encoding/decoding.

Encoded words have a charset designator attribute, such as ISO-8859-1, and an encoding type, which can be quoted-printable or base64. EncodedWord provides member functions to set or get the charset designator and encoding type. The charset designator must be an identifier registered with the Internet Assigned Numbers Authority (IANA). The encoding type must be either quoted-printable (the 'Q' encoding) or base64 (the 'B' encoding).

EncodedWord also contains strings for the decoded text and the entire encoded word. (Use the inherited member functions Node::setString() and Node::getString() to set or get the text of the entire encoded word.)

To use EncodedWord to decode an encoded word, set the encoded word string using either the constructor EncodedWord(const String&,Node*) or the inherited member function Node::setString(). Then call parse(). You can then get the charset designator and the decoded text.

To use EncodedWord to encode non-ASCII text, set the non-ASCII text using setDecodedText(). Also set the charset designator using setCharset() and the encoding type using setEncodingType(). Then call assemble(). You can then get the encoded word using the inherited member function Node::getString().

To set an encoded word into a header field (which must be a non-structured header field), use the member function Text::addEncodedWord().

Because encoded words can be mixed with unencoded ASCII text, Hunny MIME++ provides pseudo-encoded words, which are treated like encoded words but are not really encoded. If the encoding type of an EncodedWord is the NUL character, then no encoding or decoding is done. Other than the fact that no encoding is done, such pseudo-encoded words can be treated exactly like regular encoded words.

If there is an error decoding an encoded word, EncodedWord will present the entire encoded word as the decoded text.

---

Constructor & Destructor Documentation

EncodedWord

(

)

This constructor sets the EncodedWord object's string representation to the empty string and sets its parent node to NULL.

EncodedWord

(

const EncodedWord &

other

)

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

Parameters:

other

EncodedWord instance to copy

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

This constructor sets the EncodedWord 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

~EncodedWord

(

)

[virtual]

Destructor

---

Member Function Documentation

void assemble

(

)

[virtual]

This virtual function, inherited from Node, executes the assemble operation for EncodedWord objects. The assemble operation creates or updates the string representation from the broken-down representation. For EncodedWord objects, the assemble operation builds the string representation from the charset, encoding type, and decoded text.

You should call this member function after you set or modify the charset, encoding type, or decoded text, and before you retrieve the string representation.

This function clears the is-modified flag.

Implements Node.

int bDecode	(	const String &	inStr,
		String &	outStr
	)			[static]

Decodes a string with the B encoding.

Parameters:

	inStr	encoded string
	outStr	decoded string

Returns:

0 if the decoding succeeded; -1 if the decoding failed

See also:

bEncode()

String bEncode

(

const String &

str

)

[static]

Encodes a string with the B encoding.

The 'B' encoding is the same as base64 encoding, except that white space characters (including the end of line characters) are not allowed in the encoded text.

Parameters:

str

the string to encode

Returns:

the encoded string

const String & charset

(

)

const

Gets the charset designator.

The charset designator should be an identifier that has been registered with IANA. Examples of common charset designators include "US-ASCII", "ISO-8859-1" (Western Europe), "GB2312" (China), "BIG5" (Taiwan), "EUC-KR" (Korea), "UTF-8" and others.

Returns:

charset designator

Node * clone

(

)

const [virtual]

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

Returns:

a copy of this object

Implements Node.

const String & decodedText

(

)

const

Gets the decoded text.

Returns:

decoded text

char encodingType

(

)

const

Gets the encoding type.

The value 'Q' or 'q' indicates the modified quoted-printable encoding. The value 'B' or 'b' indicates the base64 encoding.

Returns:

encoding type

EncodedWord * newEncodedWord

(

)

[static]

Creates a new EncodedWord object.

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

Returns:

new EncodedWord instance

See also:

sNewEncodedWord

const EncodedWord & operator=

(

const EncodedWord &

other

)

Performs a deep copy of its argument. The parent node of this EncodedWord object is not changed.

Parameters:

other

EncodedWord instance to copy

void parse

(

)

[virtual]

This virtual function, inherited from Node, executes the parse operation for EncodedWord objects. The parse operation creates or updates the broken-down representation from the string representation. For EncodedWord objects, the parse operation parses the string representation to extract the charset designator, encoding type, and the decoded text.

You should call this member function after you set or modify the string representation, and before you access the charset, encoding type, or decoded text.

This function clears the is-modified flag.

Implements Node.

int qDecode	(	const String &	inStr,
		String &	outStr
	)			[static]

Decodes a string with the Q encoding.

Parameters:

	inStr	encoded string
	outStr	decoded string

Returns:

0 if the decoding succeeded; -1 if the decoding failed

See also:

qEncode()

String qEncode

(

const String &

str

)

[static]

Encodes a string with the Q encoding.

The Q encoding is a modified form the the quoted-printable encoding. In the Q encoding, white space characters, including the end of line characters, are not allowed. The space character (ASCII 32) may be encoded as an underscore character ('_', ASCII 95), and the underscore character itself is always encoded using the hexadecimal encoding form ("_" encoded as "=5F"). In addition, other special characters such as '?' must be encoded using the hexadecimal encoding.

Parameters:

str

the string to encode

Returns:

the encoded string

void setCharset

(

const String &

charset

)

Sets the charset designator.

The charset designator must be an identifier that has been registered with IANA. Examples of common charset designators include "US-ASCII", "ISO-8859-1" (Western Europe), "GB2312" (China), "BIG5" (Taiwan), "EUC-KR" (Korea), "UTF-8" and others.

Parameters:

charset

charset designator

void setDecodedText

(

const String &

text

)

Sets the decoded text.

Parameters:

text

decoded text

void setEncodingType

(

char

encodingType

)

Sets the encoding type.

The encoding type must be one of: 'Q', 'q', 'B', 'b', or NUL. 'Q' and 'q' are equivalent and indicate the quoted-printable encoding. 'B' and 'b' are equivalent, and indicate the base64 encoding. The NUL character indicates no encoding, making this a pseudo-encoded word.

Parameters:

encodingType

encoding type

---

Member Data Documentation

EncodedWord *(* sNewEncodedWord)()=0

(

)

[static]

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

See also:

newEncodedWord()