Decoder Options
Output CR LF If this option is true, then the decoder uses CR LF as the end-of-line characters in the decoded output for hard line breaks. If the option is false, then the decoder uses LF alone. The default value is false.
Using QpDecoder
The decoding procedure uses three functions: QpDecoder_start(), QpDecoder_decode(), and QpDecoder_finish(). The procedure is described here:
Call QpDecoder_initialize() to initialize the decoder object.
Set any decoder options.
Call QpDecoder_start() to start a new decode operation.
Initialize an input buffer and an output buffer. These buffers are instances of Char8Buffer and ByteBuffer, respectively. To initialize an input buffer named inBuf, you set inBuf.chars to a char array that contains the data to be decoded, set inBuf.pos to the offset of the beginning of the data in inBuf.chars, and set inBuf.endPos to the offset of the first byte past the end of the data in inBuf.chars. To initialize an output buffer named outBuf, set outBuf.bytes 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.bytes.
Call QpDecoder_decode() 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 calling QpDecoder_decode() again. If inBuf.pos == inBuf.endPos, then the input buffer is empty, and you must supply the input buffer with more data before calling QpDecoder_decode() again.
Repeat steps 5 and 6 as many times as necessary until you have processed all the input data.
Call QpDecoder_finish() to flush any internally buffered data to the output buffer. If the output buffer is full after QpDecoder_finish() returns, you must make room in the output buffer and call QpDecoder_finish() again. If QpDecoder_finish() returns and the output buffer is not full, then the decoding is finished.
You may repeat steps 2 through 8 multiple times to perform multiple decode operations.
When you have finished using the decoder, call QpDecoder_finalize() to free the memory allocated by the decoder.
Dealing With Errors
The QpDecoder module correctly decodes all data that is correctly encoded. However, if the data is not correctly encoded, the decoder detects these errors. Because the data is typically text that is presented to a human user, it makes sense for the decoder to be "forgiving" of errors. (Humans are much better at recovering from errors than computers are!) Therefore, decoding errors are not treated as fatal errors. Instead, the decoder tries to recover as best it can and continue. In most cases, if the decoder detects a decoding error, it just passes the encoded data through to the output until it can recover from the error.
You can check for a decoding error by calling the function QpDecoder_errorStatus() to get the value of the error flag. This flag is reset when you call QpDecoder_start() and is set whenever the decoder detects an error.
Functions | |
| int | QpDecoder_initialize (QpDecoder *decoder) |
| Initializes the decoder object. | |
| void | QpDecoder_finalize (QpDecoder *decoder) |
| Finalizes the decoder object. | |
| void | QpDecoder_setOutputCrLf (QpDecoder *decoder, int b) |
| Sets the CRLF end-of-line characters option. | |
| int | QpDecoder_getOutputCrLf (QpDecoder *decoder) |
| Gets the CRLF end-of-line characters option. | |
| void | QpDecoder_start (QpDecoder *decoder) |
| Starts a decode operation. | |
| void | QpDecoder_decode (QpDecoder *decoder, Char8Buffer *inBuf, ByteBuffer *outBuf) |
| Decodes data from the input buffer to the output buffer. | |
| void | QpDecoder_finish (QpDecoder *decoder, ByteBuffer *outBuf) |
| Finishes a decode operation. | |
| int | QpDecoder_errorStatus (QpDecoder *decoder) |
| Indicates if a decoding error occurred. | |
|
||||||||||||||||
|
Decodes data from the input buffer to the output buffer. This function takes an input buffer and an output buffer as parameters, and decodes 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 decode multiple buffers of input data. However, both of the following conditions should be true before the function is called:
|
|
|
Indicates if a decoding error occurred. The QpDecoder module correctly decodes all data that is correctly encoded. However, if the data is not correctly encoded, the decoder detects these errors. Because the data is typically text that is presented to a human user, it makes sense for the decoder to be "forgiving" of errors. (Humans are much better at recovering from errors than computers are!) Therefore, decoding errors are not treated as fatal errors. Instead, the decoder tries to recover as best it can and continue. In most cases, if the decoder detects a decoding error, it just passes the encoded data through to the output until it can recover from the error.
You can check for a decoding error by calling
|
|
|
Finalizes the decoder object. You must call this function when you have finished using the decoder. Failure to call this function causes a memory leak.
|
|
||||||||||||
|
Finishes a decode operation. When you perform a decode operation, the decoder 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 CRLF end-of-line characters option.
|
|
|
Initializes the decoder object. You must initialize the decoder object before you use it. After you have initialized it, you may use the decoder object for multiple decode operations.
When you have finished using the decoder object, call
|
|
||||||||||||
|
Sets the CRLF end-of-line characters option. If this option is true, then the decoder outputs CR LF as the end-of-line character sequence for hard line breaks. If the option is set to false, then the decoder outputs LF alone. The default value is false.
|
|
|
Starts a decode operation.
After you call
|
Copyright © 2001-2006 Hunny Software, Inc. All rights reserved.