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:
Call QpEncoder_initialize() to initialize the encoder object.
Set any encoder options.
Call QpEncoder_start() to start a new encode operation.
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.
Call QpEncoder_encode() with the input buffer and output buffer as arguments.
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.
Repeat steps 5 and 6 as many times as necessary until you have processed all the input data.
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.
You may repeat steps 2 through 8 multiple times to perform multiple encode operations.
When you have finished using the encoder, call QpEncoder_finalize() to free the memory allocated by the encoder.
Functions | |
| int | QpEncoder_initialize (QpEncoder *encoder) |
| Initializes the encoder object. | |
| void | QpEncoder_finalize (QpEncoder *encoder) |
| Finalizes the encoder object. | |
| void | QpEncoder_setMaxLineLen (QpEncoder *encoder, size_t len) |
| Sets the maximum line length of the encoded output. | |
| size_t | QpEncoder_getMaxLineLen (QpEncoder *encoder) |
| Gets the maximum line length of the encoded output. | |
| void | QpEncoder_setOutputCrLf (QpEncoder *encoder, int b) |
| Sets the CRLF end-of-line characters option. | |
| int | QpEncoder_getOutputCrLf (QpEncoder *encoder) |
| Gets the CRLF end-of-line characters option. | |
| void | QpEncoder_setSuppressFinalNewline (QpEncoder *encoder, int b) |
| Sets the option to suppress a final newline in the output. | |
| int | QpEncoder_getSuppressFinalNewline (QpEncoder *encoder) |
| Gets the option to suppress a final newline in the output. | |
| void | QpEncoder_setProtectFrom (QpEncoder *encoder, int b) |
| Sets the option to protect "From " at the beginning of a line. | |
| int | QpEncoder_getProtectFrom (QpEncoder *encoder) |
| Gets the option to protect "From " at the beginning of a line. | |
| void | QpEncoder_setProtectDot (QpEncoder *encoder, int b) |
| Sets the option to protect a dot at the beginning of a line. | |
| int | QpEncoder_getProtectDot (QpEncoder *encoder) |
| Gets the option to protect a dot at the beginning of a line. | |
| void | QpEncoder_setEncodeMap (QpEncoder *encoder, unsigned char *map) |
| Sets the lookup table that determines how characters are encoded. | |
| void | QpEncoder_start (QpEncoder *encoder) |
| Starts an encode operation. | |
| void | QpEncoder_encode (QpEncoder *encoder, ByteBuffer *inBuf, Char8Buffer *outBuf) |
| Encodes data from the input buffer to the output buffer. | |
| void | QpEncoder_finish (QpEncoder *encoder, Char8Buffer *outBuf) |
| Finishes an encode operation. | |
|
||||||||||||||||
|
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:
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:
|
|
|
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.
|
|
||||||||||||
|
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:
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.
|
|
|
Gets the maximum line length of the encoded output.
|
|
|
Gets the CRLF end-of-line characters option.
|
|
|
Gets the option to protect a dot at the beginning of a line
|
|
|
Gets the option to protect "From " at the beginning of a line.
|
|
|
Gets the option to suppress a final newline in the output.
|
|
|
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
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
||||||||||||
|
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.
|
|
|
Starts an encode operation.
After you call
|
Copyright © 2001-2006 Hunny Software, Inc. All rights reserved.