QpEncoder.h File Reference

Encode quoted-printable encoding. More...

Functions
XMIME_API int	QpEncoder_initialize (QpEncoder *encoder)
	Initializes the encoder object.
XMIME_API void	QpEncoder_finalize (QpEncoder *encoder)
	Finalizes the encoder object.
XMIME_API void	QpEncoder_setMaxLineLen (QpEncoder *encoder, size_t len)
	Sets the maximum line length of the encoded output.
XMIME_API size_t	QpEncoder_getMaxLineLen (QpEncoder *encoder)
	Gets the maximum line length of the encoded output.
XMIME_API void	QpEncoder_setOutputCrLf (QpEncoder *encoder, int b)
	Sets the CRLF end-of-line characters option.
XMIME_API int	QpEncoder_getOutputCrLf (QpEncoder *encoder)
	Gets the CRLF end-of-line characters option.
XMIME_API void	QpEncoder_setSuppressFinalNewline (QpEncoder *encoder, int b)
	Sets the option to suppress a final newline in the output.
XMIME_API int	QpEncoder_getSuppressFinalNewline (QpEncoder *encoder)
	Gets the option to suppress a final newline in the output.
XMIME_API void	QpEncoder_setProtectFrom (QpEncoder *encoder, int b)
	Sets the option to protect "From " at the beginning of a line.
XMIME_API int	QpEncoder_getProtectFrom (QpEncoder *encoder)
	Gets the option to protect "From " at the beginning of a line.
XMIME_API void	QpEncoder_setProtectDot (QpEncoder *encoder, int b)
	Sets the option to protect a dot at the beginning of a line.
XMIME_API int	QpEncoder_getProtectDot (QpEncoder *encoder)
	Gets the option to protect a dot at the beginning of a line.
XMIME_API void	QpEncoder_setEncodeMap (QpEncoder *encoder, unsigned char *map)
	Sets the lookup table that determines how characters are encoded.
XMIME_API void	QpEncoder_start (QpEncoder *encoder)
	Starts an encode operation.
XMIME_API void	QpEncoder_encode (QpEncoder *encoder, ByteBuffer *inBuf, Char8Buffer *outBuf)
	Encodes data from the input buffer to the output buffer.
XMIME_API void	QpEncoder_finish (QpEncoder *encoder, Char8Buffer *outBuf)
	Finishes an encode operation.

---

Detailed Description

Quoted-printable encoding is an encoding that encodes 8-bit text into printable ASCII characters in a way that makes it safe for sending through the legacy Internet mail system. The encoding is required because 8-bit characters cannot pass reliably through the Internet mail system. In the quoted-printable encoding, characters that are not part of the ASCII 7-bit character set are encoded as an equals sign (the character '=') followed by two hex digits (0-9 and A-F). Certain ASCII characters are also encoded. The quoted-printable encoding also encodes "soft" line breaks, since long lines also cannot pass reliably through the Internet mail system. The details of quoted-printable encoding can be found in RFC 2045.

The QpEncoder module allows you to encode 8-bit text data one buffer at a time, thus allowing you to encode text data of unlimited size using a limited amount of memory. For example, if you want to encode data from an input file to an output file, you may read from the input file one buffer at a time, present each buffer to the encoder, and write to the output file one buffer at a time.

Encoder Options

The following list enumerates the options that affect the behavior of QpEncoder:

• Maximum Line Length You may change this option to set the maximum length of a line in the encoder's output. The maximum allowed value for this option is 76, which is the maximum line length allowed by the MIME standard. The default value is 76.

• Output CR LF If this option is true, then the encoder uses CR LF as the end-of-line characters in the encoded output. If the option is false, then the encoder uses LF alone. The default value is false.

• Suppress Final Newline If this option is true, then the encoder does not put a final newline (CR LF, or LF) at the end of the encoded output, unless the input ends with a hard line break. If the option is false, then the encoder always adds a newline to the end of the encoded output. If the option is false and the input does not end with a hard line break, then the encoder adds a soft line break (that is, "=\r\n" or "=\n") at the end of the encoded output. The default value is false.

• Protect From Because of the way many applications store mail messages in a file, if the string "From " occurs at the beginning of a line, it is often changed to ">From ". If this option is true, then when "From " occurs at the beginning of a line, the encoder encodes it as "From=20" -- that is, the space character is encoded using the hex encoding. The default value is true.

• Protect Dot Because of the way mail messages are sent in the SMTP and POP3 protocols, a dot (the character '.') at the beginning of a line is treated specially. A single dot on a line by itself indicates the end of the message. For this reason, the protocol implementation must scan every line for a dot at the beginning and "escape" it by adding an extra dot when sending, and "unescape" it by removing the extra dot when receiving. If this option is true, then the encoder encodes every dot at the beginning of a line using the hex encoding. Setting this option may provide better interoperability with SMTP or POP3 implementations that do not correctly handle the escaping or unescaping of the dot character. The default value is true.

• Encode Map This option allows you to control precisely the characters that the encoder encodes. Two encoding maps, ENCODE_MAP_LOW_RISK and ENCODE_MAP_HIGH_RISK, are provided by static data members. See QpEncoder_setEncodeMap() for the details of how to create your own encode map. The default value is ENCODE_MAP_LOW_RISK, which encodes all the recommended characters listed in RFC 2045 (page 21).

Using QpEncoder

The encode procedure uses three functions: QpEncoder_start(), QpEncoder_encode(), and QpEncoder_finish(). The procedure is described here:

1. Call QpEncoder_initialize() to initialize the encoder object.

2. Set any encoder options.

3. Call QpEncoder_start() to start a new encode operation.

4. Initialize an input buffer and an output buffer. These buffers are instances of ByteBuffer and Char8Buffer, respectively. To initialize an input buffer named inBuf, you set inBuf.bytes to a char array that contains the data to be encoded, set inBuf.pos to the offset of the beginning of the data in inBuf.bytes, and set inBuf.endPos to the offset of the first byte past the end of the data in inBuf.bytes. To initialize an output buffer named outBuf, set outBuf.chars to a char array of any size, set outBuf.pos to zero, and set outBuf.endPos to the length of the array referenced by outBuf.chars.

5. Call QpEncoder_encode() with the input buffer and output buffer as arguments.

6. Check to see if the output buffer is full or if the input buffer is empty. If outBuf.pos == outBuf.endPos, then the output buffer is full, and you must make room in the output buffer before you call QpEncoder_encode() again. If inBuf.pos == inBuf.endPos, then the input buffer is empty, and you must supply the input buffer with more data before you call QpEncoder_encode() again.

7. Repeat steps 5 and 6 as many times as necessary until you have processed all the input data.

8. Call QpEncoder_finish() to flush any internally buffered data to the output buffer. If the output buffer is full after QpEncoder_finish() returns, you must make room in the output buffer and call QpEncoder_finish() again. If QpEncoder_finish() returns and the output buffer is not full, then the encode operation is finished.

9. You may repeat steps 2 through 8 multiple times to perform multiple encode operations.

10. When you have finished using the encoder, call QpEncoder_finalize() to free the memory allocated by the encoder.

---

Function Documentation

XMIME_API void QpEncoder_encode	(	QpEncoder *	encoder,
		ByteBuffer *	inBuf,
		Char8Buffer *	outBuf
	)

Encodes data from the input buffer to the output buffer.

This function takes an input buffer and an output buffer as parameters, and encodes data from the input buffer to the output buffer until either (1) the input buffer is empty, or (2) the output buffer is full. Therefore, one of the following conditions is always true when the function returns:

• inBuf.pos == inBuf.endPos (input buffer empty)
• outBuf.pos == outBuf.endPos (output buffer full)

You may call the function multiple times to encode multiple buffers of input data. However, both of the following conditions should be true before the function is called:

• inBuf.pos < inBuf.endPos (input buffer data available)
• outBuf.pos < outBuf.endPos (output buffer space available)

Parameters:

	encoder	the encoder object
	inBuf	input buffer
	outBuf	output buffer

XMIME_API void QpEncoder_finalize

(

QpEncoder *

encoder

)

Finalizes the encoder object.

You must call this function when you have finished using the encoder. Failure to call this function causes a memory leak.

Parameters:

encoder

the encoder object

XMIME_API void QpEncoder_finish	(	QpEncoder *	encoder,
		Char8Buffer *	outBuf
	)

Finishes an encode operation.

When you perform an encode operation, the encoder buffers some data internally. Therefore, after you have processed all the input data, you must call this function to flush the internal buffer.

The following condition must be true when the function is called:

• outBuf.pos < outBuf.endPos (output buffer space available)

The above condition must also be true when the function returns in order to guarantee that all output data has been written to the output buffer. If the condition is false when the function returns, you must make room in the output buffer and call the function again.

Parameters:

	encoder	the encoder object
	outBuf	output buffer

XMIME_API size_t QpEncoder_getMaxLineLen

(

QpEncoder *

encoder

)

Gets the maximum line length of the encoded output.

Parameters:

encoder

the encoder object

Returns:

maximum line length of the encoded output

XMIME_API int QpEncoder_getOutputCrLf

(

QpEncoder *

encoder

)

Gets the CRLF end-of-line characters option.

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API int QpEncoder_getProtectDot

(

QpEncoder *

encoder

)

Gets the option to protect a dot at the beginning of a line

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API int QpEncoder_getProtectFrom

(

QpEncoder *

encoder

)

Gets the option to protect "From " at the beginning of a line.

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API int QpEncoder_getSuppressFinalNewline

(

QpEncoder *

encoder

)

Gets the option to suppress a final newline in the output.

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API int QpEncoder_initialize

(

QpEncoder *

encoder

)

Initializes the encoder object.

You must initialize the encoder object before you use it. After you have initialized it, you may use the encoder object for multiple encode operations.

When you have finished using the encoder object, call QpEncoder_finalize() to free the memory allocated by the encoder object.

Parameters:

encoder

the encoder object

XMIME_API void QpEncoder_setEncodeMap	(	QpEncoder *	encoder,
		unsigned char *	map
	)

Sets the lookup table that determines how characters are encoded.

This is an advanced option. Please contact Hunny Software's support staff if you want the details on how to use this option.

Parameters:

	encoder	the encoder object
	map	encode map

XMIME_API void QpEncoder_setMaxLineLen	(	QpEncoder *	encoder,
		size_t	len
	)

Sets the maximum line length of the encoded output.

For MIME-compliant Internet mail, lines should be no longer than 76 characters, and that rule is enforced by this class. If the parameter to this method has a value larger than 76, the maximum line length will be set to 76.

The default value is 76.

Parameters:

	encoder	the encoder object
	len	maximum line length in the encoded output

XMIME_API void QpEncoder_setOutputCrLf	(	QpEncoder *	encoder,
		int	b
	)

Sets the CRLF end-of-line characters option.

If this option is true, then the encoder uses CR LF as the end-of-line characters in the encoded output. If the option is false, then the encoder uses LF alone.

The default value is false.

Parameters:

	encoder	the encoder object
	b	true value causes CR LF in the output; false causes LF

XMIME_API void QpEncoder_setProtectDot	(	QpEncoder *	encoder,
		int	b
	)

Sets the option to protect a dot at the beginning of a line.

Because of the way mail messages are sent in the SMTP and POP3 protocols, a dot (the character '.') at the beginning of a line is treated specially. A single dot on a line by itself indicates the end of the message. For this reason, the protocol implementation must scan every line for a dot at the beginning and "escape" it by adding an extra dot when sending, and "unescape" it by removing the extra dot when receiving. If this option is true, then the encoder encodes every dot at the beginning of a line using the hex encoding. Setting this option may provide better interoperability with SMTP or POP3 implementations that do not correctly handle the escaping or unescaping of the dot character.

The default value is true.

Parameters:

	encoder	the encoder object
	b	if true, "." at the beginning of a line is encoded as "=2E"

XMIME_API void QpEncoder_setProtectFrom	(	QpEncoder *	encoder,
		int	b
	)

Sets the option to protect "From " at the beginning of a line.

Because of the way many applications store mail messages in a file, if the string "From " occurs at the beginning of a line, it is often changed to ">From ". If this option is true, then when "From " occurs at the beginning of a line, the encoder encodes it as "From=20" -- that is, the space character is encoded using the hex encoding.

The default value is true.

Parameters:

	encoder	the encoder object
	b	if true, "From " is encoded as "From=20"

XMIME_API void QpEncoder_setSuppressFinalNewline	(	QpEncoder *	encoder,
		int	b
	)

Sets the option to suppress a final newline in the output.

If this option is true, then the encoder does not put a final newline (CR LF, or LF) at the end of the encoded output, unless the input ends with a hard line break. If the option is false, then the encoder always adds a newline to the end of the encoded output. If the option is false and the input does not end with a hard line break, then the encoder adds a soft line break (that is, "=\r\n" or "=\n") at the end of the encoded output.

The default value is false.

Parameters:

	encoder	the encoder object
	b	if true, a final newline will be suppressed; if false, a final newline is always added

XMIME_API void QpEncoder_start

(

QpEncoder *

encoder

)

Starts an encode operation.

After you call QpEncoder_start(), you call QpEncoder_encode() one or more times, followed by QpEncoder_finish() to complete the encode operation.

Parameters:

encoder

the encoder object