| |
| LONG WINAPI EncodeBuffer( |
| |
LPBYTE lpInput, |
|
| |
LONG cbInput, |
|
| |
LPTSTR lpszOutput, |
|
| |
LONG cchOutput, |
|
| |
DWORD dwOptions |
|
| ); |
The EncodeBuffer function encodes the contents of the
specified byte array, converting the data into printable text.
Parameters
- lpInput
- A pointer to a buffer that contains the data to be
encoded.
- cbInput
- A long integer which specifies the number of characters in the
buffer which should be encoded.
- lpszOutput
- A pointer to a string that will be used to store the encoded
text. The length of the string must be at least 33% larger than the
number of bytes being encoded, and will be terminated with a null
byte.
- cchOutput
- The maximum number of characters that may be stored in the
string buffer. If this value is too small to store the encoded
text, the function will fail.
- dwOptions
- An unsigned integer that specifies one or more options. This
parameter is constructed by using a bitwise operator with any of
the following values:
| Constant |
Description |
| DATA_ENCODE_BASE64 |
Use the base64 algorithm for encoding the data. This is the
encoding method that is used by most modern email client
software. Note that this option cannot be combined with other
encoding methods. |
| DATA_ENCODE_QUOTED |
Use the quoted-printable algorithm for encoding the data.
Most printable characters are left as-is, with control
characters and 8-bit characters encoded as their hexadecimal
value. Note that this option cannot be combined with the other
encoding methods. |
| DATA_ENCODE_URL |
Use the URL encoding algorithm for encoding the data.
Letters and numbers are left as-is, with control characters,
most punctuation and 8-bit characters encoded as their
hexadecimal value. Note that this option cannot be combined
with the other encoding methods. |
| DATA_ENCODE_UTF7 |
Encode the data using the Unicode Transformation Format.
This converts Unicode text into 7-bit characters. Note that
this option cannot be combined with the other encoding
methods. |
| DATA_ENCODE_UTF8 |
Encode the data using the Unicode Transformation Format.
This converts Unicode text into 8-bit characters. Note that
this option cannot be combined with the other encoding
methods. |
| DATA_ENCODE_COMPRESSED |
The data should be compressed before it is encoded. To
restore the original data, it must be expanded after it has
been decoded. This option is ignored if the encoding type is
not base64. |
| DATA_ENCODE_LINEBREAK |
The encoded data should broken into multiple lines of text
if the resulting string is longer than 72 characters. This
option is ignored if the encoding type is not base64 or
quoted-printable. This option should be specified if the
encoded data is going to be included in an email message. |
Return Value
If the function succeeds, it will return the number of bytes
encoded and stored in the string. If the function fails, it will
return -1. Failure typically indicates that the buffer is not large
enough to store the encoded data.
Remarks
The EncodeBuffer function is used to encode a block of data
and store it in the specified string buffer as printable text. To
encode the contents of a file it is recommended that you use the
EncodeFile function instead.
A common use of this function is to use the Base64 algorithm to
obscure a plain text string. This technique is used by some Internet
application protocols when passing authentication information over a
standard connection. Although it is not a secure method of encrypting
data, it does prevent a casual observer from reading the encoded
text.
If you specify either UTF-7 or UTF-8 encoding, the lpInput
parameter must point to a Unicode string and the cbInput
parameter must specify the number of characters, not bytes, that are
to be encoded. The conversion is always performed using the default
system code page.
It is recommended that you use the UnicodeEncodeText
function to convert a string to UTF-8 encoded text, and the
UnicodeDecodeText function to convert UTF-8 encoded text to a
UTF-16 or localized multi-byte string.
Requirements
Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header File: cstools10.h
Import Library: csncdv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
DecodeBuffer,
DecodeFile,
EncodeFile,
GetMessageDigest,
IsUnicodeText,
UnicodeDecodeText,
UnicodeEncodeText
|
|