Base64Encoder Class

Class that performs base64 encoding.

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

System.Object
   Base64Encoder

Remarks

Base64 encoding 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.

Base64Encoder provides two interfaces for performing base64 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.

Base64Encoder 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. If you don't want any line breaks at all, you may set the maximum line length to a very large value (for example, Int32.MaxValue). The allowed values must be a multiple of 4, and the library enforces this restriction by rounding down any value that is not a multiple of 4 (for example, it rounds 73, 74, or 75 down to 72). The default value is 72.

• 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 last line of output is a full line. If you set this option to 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 (meaning that a final newline is always added).

Using the Low-Level Interface

The low-level interface allows you to encode binary data one buffer at a time; thus you may 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, 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

Base64Encoder Members | Hunny.Mime Namespace | Base64EncoderW | Base64 in RFC 2045