Base64EncoderW.h File Reference

Encode base64 encoding. More...

Functions
XMIME_API void	Base64EncoderW_setMaxLineLen (Base64EncoderW *encoder, size_t n)
	Sets the maximum line length of the encoded output.
XMIME_API size_t	Base64EncoderW_getMaxLineLen (Base64EncoderW *encoder)
	Gets the maximum line length of the encoded output.
XMIME_API void	Base64EncoderW_setOutputCrLf (Base64EncoderW *encoder, int b)
	Sets the CRLF end-of-line characters option.
XMIME_API int	Base64EncoderW_getOutputCrLf (Base64EncoderW *encoder)
	Gets the CRLF end-of-line characters option.
XMIME_API void	Base64EncoderW_setSuppressFinalNewline (Base64EncoderW *encoder, int b)
	Sets the option to suppress a final newline in the output.
XMIME_API int	Base64EncoderW_getSuppressFinalNewline (Base64EncoderW *encoder)
	Gets the option to suppress a final newline in the output.
XMIME_API void	Base64EncoderW_initialize (Base64EncoderW *encoder)
	Initializes the encoder object.
XMIME_API void	Base64EncoderW_start (Base64EncoderW *encoder)
	Starts an encode operation.
XMIME_API void	Base64EncoderW_encode (Base64EncoderW *encoder, struct ByteBuffer *inBuf, struct Char16Buffer *outBuf)
	Encodes data from the input buffer to the output buffer.
XMIME_API void	Base64EncoderW_finish (Base64EncoderW *encoder, struct Char16Buffer *outBuf)
	Finishes an encode operation.

---

Detailed Description

Base64EncoderW is a version of Base64Encoder that outputs text with 16-bit Unicode characters. The difference is that Base64EncoderW_encode() and Base64EncoderW_finish() take a Char16Buffer argument, while Base64Encoder_encode() and Base64Encoder_finish() take a Char8Buffer argument. Base64EncoderW may be convenient to use with Java, .NET, or COM, where text most often consists of 16-bit Unicode characters.

If your program operates in an environment that uses the UTF-8 encoding of Unicode (Linux or Solaris, for example), then you can use the Base64Encoder module without any problems, because the base64-encoded data uses only 7-bit characters.

Please see the documentation for Base64Encoder.

---

Function Documentation

XMIME_API void Base64EncoderW_encode	(	Base64EncoderW *	encoder,
		ByteBuffer *	inBuf,
		Char16Buffer *	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

XMIME_API void Base64EncoderW_finish	(	Base64EncoderW *	encoder,
		Char16Buffer *	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

XMIME_API size_t Base64EncoderW_getMaxLineLen

(

Base64EncoderW *

encoder

)

Gets the maximum line length of the encoded output.

Parameters:

encoder

the encoder object

Returns:

maximum line length of the encoded output

XMIME_API int Base64EncoderW_getOutputCrLf

(

Base64EncoderW *

encoder

)

Gets the CRLF end-of-line characters option.

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API int Base64EncoderW_getSuppressFinalNewline

(

Base64EncoderW *

encoder

)

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

Parameters:

encoder

the encoder object

Returns:

boolean value of this option

XMIME_API void Base64EncoderW_initialize

(

Base64EncoderW *

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

XMIME_API void Base64EncoderW_setMaxLineLen	(	Base64EncoderW *	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 Base64EncoderW_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

XMIME_API void Base64EncoderW_setOutputCrLf	(	Base64EncoderW *	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

XMIME_API void Base64EncoderW_setSuppressFinalNewline	(	Base64EncoderW *	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

XMIME_API void Base64EncoderW_start

(

Base64EncoderW *

encoder

)

Starts an encode operation.

After you call Base64EncoderW_start(), you call Base64EncoderW_encode() one or more times, followed by Base64EncoderW_finish() to complete the encode operation.

Parameters:

encoder

the encoder object