Base64.dll Documentation

**********************************************************************************************

UINT CharsNeededToEncode(UINT cb)

Description:

Calculates the amount of characters needed in the Base64 string,
depending on the amount of bytes in the input buffer.

Parameters:

cb - Amount of bytes in the buffer to encode.

Return value:

The amount of characters (TCHARS) required in the Base64 string,
including the null terminator, to encode a buffer with the given size.

If cb is zero, the function returns zero.

**********************************************************************************************

UINT BytesNeededToDecode(UINT cb, UINT nEqualSigns)

Description:

Calculates the amount of bytes needed in the output buffer, depending
on the length of the Base64 string and the amount of equal signs at its end.

Parameters:

cb - The length, in characters, of the Base64 string.
nEqualSigns - The amount of equal signs ("=") at the end of the Base64 string.

Return value:

The amount of bytes needed in the output buffer, to decode a Base64 string
with the given length.

If one of the parameters is invalid, the function returns zero.
This happens if cb is zero, cb is not perfectly divisible by 4, or nEqualSigns
is bigger than 2.

**********************************************************************************************

UINT CountEqualSigns(LPCTSTR lpInput)

Description:

Counts the amount of equal signs ("=") at the end of the given string, without
checking whether or not it is a valid Base64 string.

Parameters:

lpInput - The string to check.

Return value:

The amount of equal signs on success, or 0xFFFFFFFF on failure.
Failure occurs if the parameter is an invalid pointer, or if there are too many
equal signs at the end of the string (over 2).
Return values indicating success are 0, 1, and 2.

**********************************************************************************************

BOOL IsValidBase64String(LPCTSTR lpString, LPUINT lpEqualSigns)

Description:

Verifies that the string given is a valid Base64 string, and optionally
returns the amount of equal signs at the end of the string (0, 1 or 2).

Parameters:

lpString - The string to check.
lpEqualSigns - Pointer to a UINT value which, on return, specifies the amount
	of equal signs ("=") at the end of the string, if it is a Base64 string.

Return value:

TRUE if the string is a Base64 string, FALSE if it isn't.

Remarks:

If the return value is FALSE, the value pointed by lpEqualSigns is not changed.

**********************************************************************************************

BOOL Base64Encode(LPCBYTE lpInput, UINT cbInput, LPTSTR lpOutput, UINT cbOutput)

Description:

Encodes a buffer with the given size.

Parameters:

lpInput - The input buffer to encode.
cbInput - The size, in bytes, of the input buffer.
lpOutput - The output buffer which will receive the Base64 string.
cbOutput - The size, in characters (ANSI version) or bytes (Unicode version)
	of the output buffer, including the null terminator.

Return value:

TRUE on success, FALSE on failure.

Remarks:

The function may fail if the input and/or output buffers are invalid, or if the
output buffer is not big enough for the Base64 string.
To obtain the minimum size required, use the CharsNeededToEncode() function.

Internally, the encoding is done with an ANSI string. Therefore, the Unicode
version of this function (Base64EncodeW) may also fail when translating the
result from ANSI to Unicode, or when allocating an ANSI string for the encoding.

**********************************************************************************************

BOOL Base64Decode(LPCTSTR lpInput, LPBYTE lpOutput, UINT cbOutput)

Description:

Decodes a Base64 string and writes the result in a buffer with the given size.

Parameters:

lpInput - The Base64 string to decode.
lpOutput - The output buffer which will receive the decoded data.
cbOutput - The size of the output buffer, in bytes.

Return value:

TRUE on success, FALSE on failure.

Remarks:

The function may fail if the input and/or output buffers are invalid, or if the
output buffer is not big enough for the decoded data.
To obtain the minimum size required, use the BytesNeeededToDecode() function.

Internally, the decoding is done with an ANSI string. Therefore, the Unicode
version of this function (Base64EncodeW) may also fail when translating the
result from ANSI to Unicode, or when allocating an ANSI string for the encoding.

If it's possible to decode the beginning of the string, but the middle is invalid,
then lpOutput will be filled with decoded characters up to the undecodable area.
From this point on, lpOutput will remain unchanged. Under such circumstances,
FALSE is returned.

*********************************************************************************************

HANDLE Base64EncodeAsync(LPCBYTE lpInput, UINT cbInput, LPTSTR lpOutput, UINT cbOutput,
                         BASE64CALLBACK lpEndCallback, LPVOID lpvParam)

Description:

Encodes a buffer with the given size, asynchronously (in another thread).

Parameters:

lpInput, cbInput, lpOutput, cbOutput - See Base64Encode description above.
lpEndCallback - Pointer to function that will be called when the encoding is
	finished. See Base64Callback description below.
lpvParam - Application-defined value to pass to the callback function.

Return value:

On success, the return value is the handle of the thread which is doing
	the encoding.
On failure, the return value is INVALID_HANDLE_VALUE.

Remarks:

You can use the handle to pause the thread by using SuspendThread, resume it
by using ResumeThread and terminate it by using TerminateThread. You must close
it by using CloseHandle when you are done with it.

*********************************************************************************************

UINT Base64DecodeAsync(LPCTSTR lpInput, LPBYTE lpOutput, UINT cbOutput,
                       BASE64CALLBACK lpEndCallback, LPVOID lpvParam)

Description:

Decodes a Base64 string, asynchronously (in another thread).

Parameters:

lpInput, lpOutput, cbOutput - See Base64Decode description above.
lpEndCallback - Pointer to function that will be called when the decoding is
	finished. See Base64Callback description below.
lpvParam - Application-defined value to pass to the callback function.

Return value:

On success, the return value is the handle of the thread which is doing
	the decoding.
On failure, the return value is INVALID_HANDLE_VALUE.

Remarks:

You can use the handle to pause the thread by using SuspendThread, resume it
by using ResumeThread and terminate it by using TerminateThread. You must close
it by using CloseHandle when you are done with it.

If it's possible to decode the beginning of the string, but the middle is invalid,
then lpOutput will be filled with decoded characters up to the undecodable area.
From this point on, lpOutput will remain unchanged. Under such circumstances,
FALSE is passed to the callback function as the bSuccess parameter.

*********************************************************************************************

BOOL GetEncodeAsyncState(HANDLE hThread, LPUINT uFinished, LPUINT uTotal)

Description:

Retrieves the amount of bytes already encoded and the amount of bytes total
to encode, where the operation is performed asynchronously by the specified
thread.

Parameters:

hThread - Specifies the thread that's encoding. This value is returned
	by Base64EncodeAsync.
uFinished - Points at a UINT which will receive the amount of bytes
	already encoded.
uTotal - Points at a UINT which will receive the amount of bytes
	total to encode.

Return value:

TRUE on success, FALSE on failure (if the thread does not exist, or isn't an
encoding thread, or at least one of the pointer parameters is invalid, or if
the actual encoding operation didn't start yet).

*********************************************************************************************

BOOL GetDecodeAsyncState(HANDLE hThread, LPUINT uFinished, LPUINT uTotal)

Description:

Retrieves the amount of characters already decoded and the amount of characters
total to decode, where the operation is performed asynchronously by the
specified thread.

Parameters:

hThread - Specifies the thread that's decoding. This value is returned
	by Base64DecodeAsync.
uFinished - Points at a UINT which will receive the amount of characters
	already decoded.
uTotal - Points at a UINT which will receive the amount of characters
	total to decode.

Return value:

TRUE on success, FALSE on failure (if the thread does not exist, or isn't an
decoding thread, or at least one of the pointer parameters is invalid, or if
the actual decoding operation didn't start yet).

*********************************************************************************************

void CALLBACK Base64Callback(HANDLE hThread, BOOL bSuccess, LPVOID lpvParam)

Description:

This is an application-defined function which is called when an asynchronous
encode or decode operation is completed.
The address of this function should be passed to Base64EncodeAsync or
Base64DecodeAsync.

Parameters:

hThread - The handle of the thread that did the asynchronous operation which
	was completed. The functions Base64EncodeAsync and Base64DecodeAsync return
	this value.
bSuccess - A boolean value specifying the success or failure of the encode
	or decode operation. See the return value description of Base64Encode
	and Base64Decode for more information.
lpvParam - An application-defined value. This is specified in the last
	parameter of Base64EncodeAsync and Base64DecodeAsync.

Return value:

This function does not return a value.

*********************************************************************************************