Base64Decoder.h File Reference

Detailed Description

The Base64Decoder module allows you to decode base64-encoded data one buffer at a time, thus allowing you to decode data of unlimited size using a limited amount of memory. For example, if you want to decode 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 decoder, and write to the output file one buffer at a time.

Using Base64Decoder

The decoding procedure uses two functions: Base64Decoder_start() and Base64Decoder_decode(). The procedure is described here:

Call Base64Decoder_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 Base64Decoder_decode() with the input buffer and output buffer as arguments.
Check to see if the output buffer is full, if the input buffer is empty, or if a decoding error has occurred. If outBuf.pos == outBuf.endPos, then the output buffer is full, and you must make room in the output buffer before calling Base64Decoder_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 Base64Decoder_decode() again. If Base64Decoder_decode() returns -1, then a fatal decoding error has occurred, and you must terminate the decode operation.
Repeat steps 3 and 4 as many times as necessary until you have decoded all the data.

Dealing With Errors

The Base64Decoder module correctly decodes all data that is correctly encoded. However, if the data is not correctly encoded, the decoder detects these errors. All decoding errors are treated as fatal errors -- the decoder does not try to recover. The decoder notifies your application of decoding errors by returning -1 from the function Base64Decoder_decode(). Your program code should check the return value and abort the decode operation when an error occurs.

Functions

void Base64Decoder_start (Base64Decoder *decoder)

Starts a decode operation.

int Base64Decoder_decode (Base64Decoder *decoder, Char8Buffer *inBuf, ByteBuffer *outBuf)

Decodes data from the input buffer to the output buffer.

Function Documentation

int Base64Decoder_decode ( Base64Decoder * decoder,

Char8Buffer * inBuf,

ByteBuffer * outBuf

)

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, (2) the output buffer is full, or (3) a decoding error occurs. 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)

return value is -1 (decoding error occurred)

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:

inBuf.pos < inBuf.endPos (input buffer data available)

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

If a decoding error occurs, the function returns -1. You must check the return value and abort the decode operation if a decoding error occurs.

Parameters:

decoder the decoder object

inBuf input buffer

outBuf output buffer

Returns:
0 if successful; -1 if a decoding error occurs

void Base64Decoder_start ( Base64Decoder * decoder )

Starts a decode operation.
After you call Base64Decoder_start(), you call Base64Decoder_decode() one or more times to complete the decode operation.

Parameters:

decoder the decoder object


Functions
void	Base64Decoder_start (Base64Decoder *decoder)
	Starts a decode operation.
int	Base64Decoder_decode (Base64Decoder decoder, Char8Buffer inBuf, ByteBuffer *outBuf)
	Decodes data from the input buffer to the output buffer.