QuotedPrintableEncoder Class

Class that performs quoted-printable encoding.

For a list of all members of this type, see QuotedPrintableEncoder Members.

System.Object
   QuotedPrintableEncoder

Remarks

Quoted-printable encoding encodes 8-bit text into printable ASCII characters for sending through the Internet mail system. The encoding is required because 8-bit characters cannot pass reliably through the Internet mail system. In the quoted-printable encoding, a character that is not in the ASCII 7-bit character set is 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.

QuotedPrintableEncoder provides two interfaces for performing quoted-printable encoding.

A high-level interface encodes from an input ByteString to an output ByteString. This interface comprises a single method, Encode().

A low-level interface allows encoding by passing multiple buffers to the encoder. The correct procedure for using this interface is described below.

QuotedPrintableEncoder allows you to change certain options, which affect the behavior of the encoder:

• Maximum Line Length The value of this option determines the maximum length of a line in the encoder's output. The maximum value allowed 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 you set this option to true, then the encoder uses CR LF as the end-of-line characters in the encoded output. If you set this option to false, then the encoder uses LF alone. The default value is true if TextUtil.EOL is TextUtil.CRLF_EOL.

• Suppress Final Newline If you set this option to 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 you set this option to 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, LowRiskEncodeMap and HighRiskEncodeMap, are provided by class fields. See EncodeMap for the details of how to create your own encode map. The default value is LowRiskEncodeMap", which encodes all the recommended characters listed in RFC 2045 (page 21).

Using the Low-Level Interface

The low-level interface allows you to encode 8-bit text data one buffer at a time; thus you may 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, pass each buffer to the encoder, and write to the output file one buffer at a time.

The low-level interface comprises three methods: Start(), EncodeSegment(), and Finish(). The procedure is described here:

1. Call Start() to initialize the encoder.
2. Initialize an input buffer and an output buffer. These buffers are instances of ByteBuffer. To initialize an input buffer named inBuf, set inBuf.Bytes to a byte 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.Bytes to a byte array, set outBuf.Pos to zero, and set outBuf.EndPos to the length of the array referenced by outBuf.Bytes.
3. Call EncodeSegment() with the input buffer and output buffer as arguments.
4. 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 EncodeSegment() 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 EncodeSegment() again.
5. Repeat steps 3 and 4 until the last input buffer is empty.
6. Call Finish() to flush any internally buffered data to the output buffer. If the output buffer is full after Finish() returns, you must make room in the output buffer and call Finish() again. If Finish() returns and the output buffer is not full, then the encoding is finished.

You may use the same encoder object for multiple encode operations.

Requirements

Namespace: Hunny.Mime

Assembly: Hunny.Mime (in Hunny.Mime.dll)

See Also

QuotedPrintableEncoder Members | Hunny.Mime Namespace | QuotedPrintableEncoderW | Quoted-printable in RFC 2045