Hunny Software Home || Hunny XStream MIME Home

Main Page | Data Structures | File List | Data Fields | Globals
src / xmime

Base64Encoder.h File Reference

Detailed Description

Base64 encoding is an encoding that encodes binary data into printable ASCII characters. The encoding is required because binary data cannot pass reliably through the Internet mail system. The encoding method is really quite simple: a group of three 8-bit bytes (3 x 8 bits = 24 bits) is encoded into a group of four printable characters. Only 64 different printable characters are used, so six bits uniquely identify each character. The four printable characters sufficiently encode the original three bytes (4 x 6 bits = 24 bits). The characters that occur in the encoding include the upper- and lower-case letters, the digits, and the characters '+' and '/'. RFC 2045 describes the details of base64 encoding.

The Base64Encoder module allows you to encode binary data one buffer at a time, thus allowing you to encode 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 a Base64Encoder object. These options are set by calling functions in the Base64Encoder module.

Using Base64Encoder

The encode procedure uses three functions: Base64Encoder_start(), Base64Encoder_encode(), and Base64Encoder_finish(). The procedure is described here:

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

  2. Set any encoder options.

  3. Call Base64Encoder_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 Base64Encoder_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 Base64Encoder_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 Base64Encoder_encode() again.

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

  8. Call Base64Encoder_finish() to flush any internally buffered data to the output buffer. If the output buffer is full after Base64Encoder_finish() returns, you must make room in the output buffer and call Base64Encoder_finish() again. If Base64Encoder_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.

Tips

There is a certain amount of overhead associated with saving and restoring the encoder's state with each call to Base64Encoder_encode(). If you use small buffers, the overhead may have an impact on performance. For larger buffers, the overhead is negligible. A good buffer size is 8192, which also happens to be a good size for I/O to the file system on many machines. If you use 8K buffers for I/O to the file system, make sure your reads and writes are properly aligned.

The operation of the encoder itself never causes an error, therefore error handling is not necessary.


Functions

void Base64Encoder_setMaxLineLen (Base64Encoder *encoder, size_t n)
 Sets the maximum line length of the encoded output.
size_t Base64Encoder_getMaxLineLen (Base64Encoder *encoder)
 Gets the maximum line length of the encoded output.
void Base64Encoder_setOutputCrLf (Base64Encoder *encoder, int b)
 Sets the CRLF end-of-line characters option.
int Base64Encoder_getOutputCrLf (Base64Encoder *encoder)
 Gets the CRLF end-of-line characters option.
void Base64Encoder_setSuppressFinalNewline (Base64Encoder *encoder, int b)
 Sets the option to suppress a final newline in the output.
int Base64Encoder_getSuppressFinalNewline (Base64Encoder *encoder)
 Gets the option to suppress a final newline in the output.
void Base64Encoder_initialize (Base64Encoder *encoder)
 Initializes the encoder object.
void Base64Encoder_start (Base64Encoder *encoder)
 Starts an encode operation.
void Base64Encoder_encode (Base64Encoder *encoder, ByteBuffer *inBuf, Char8Buffer *outBuf)
 Encodes data from the input buffer to the output buffer.
void Base64Encoder_finish (Base64Encoder *encoder, Char8Buffer *outBuf)
 Finishes an encode operation.

Function Documentation

void Base64Encoder_encode (  Base64Encoder *  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 you call the function:

  • 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

void Base64Encoder_finish (  Base64Encoder *  encoder,
Char8Buffer *  outBuf
) 
 

Finishes an encode operation by flushing any internally buffered data to the output buffer.

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

size_t Base64Encoder_getMaxLineLen (  Base64Encoder *  encoder  ) 
 

Gets the maximum line length of the encoded output.

Parameters:
encoder the encoder object
Returns:
maximum line length of the encoded output

int Base64Encoder_getOutputCrLf (  Base64Encoder *  encoder  ) 
 

Gets the CRLF end-of-line characters option.

Parameters:
encoder the encoder object
Returns:
boolean value of this option

int Base64Encoder_getSuppressFinalNewline (  Base64Encoder *  encoder  ) 
 

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

Parameters:
encoder the encoder object
Returns:
boolean value of this option

void Base64Encoder_initialize (  Base64Encoder *  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.

Parameters:
encoder the encoder object

void Base64Encoder_setMaxLineLen (  Base64Encoder *  encoder,
size_t  len
) 
 

Sets the maximum line length of the encoded output.

For MIME-compliant Internet mail, lines may be no longer than 76 characters. However, applications other than mail might allow lines longer than 76 characters. You may call Base64Encoder_setMaxLineLen() to change the maximum line length to a value appropriate for your application. You may even force output without any line breaks by setting the maximum line length to a very large value (for example, 0x7FFFFFFF) and by setting the Suppress Final Newline option to true.

This function enforces the restriction that the maximum line length be a multiple of 4. If the argument is not a multiple of 4, then it is rounded down to the nearest multiple of 4.

The default value is 72.

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

void Base64Encoder_setOutputCrLf (  Base64Encoder *  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

void Base64Encoder_setSuppressFinalNewline (  Base64Encoder *  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 last line of output is a full line. If the option is false, then the encoder always adds a newline to the end of the encoded output, even if the last line is a partial line. If you don't want any end-of-line characters in the output, you may set this option to true and set the Maximum Line Length to a very large value.

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

void Base64Encoder_start (  Base64Encoder *  encoder  ) 
 

Starts an encode operation.

After you call Base64Encoder_start(), you call Base64Encoder_encode() one or more times, followed by Base64Encoder_finish() to complete the encode operation.

Parameters:
encoder the encoder object

Copyright © 2001-2006 Hunny Software, Inc. All rights reserved.