ColdFusion 9.0 Resources

BinaryEncode

Description

Converts binary data to a string.

Returns

An encoded string representing the binary data.

Function syntax

BinaryEncode(binarydata, encoding)

History

ColdFusion MX 7: Added this function.

Parameters

Parameter	Description
`binarydata`	A variable containing the binary data to encode.
`encoding`	A string that specifies the encoding method to use to represent the data; one of the following: Hex: use the characters 0-9 and A-F to represent the hexadecimal value of each byte; for example, 3A. UU: use the UNIX UUencode algorithm to convert the data. Base64: use the Base64 algorithm to convert the data, as specified by IETF RFC 2045, at www.ietf.org/rfc/rfc2045.txt.

Usage

Binary objects and, in some cases, 8-bit characters, cannot be transported over many Internet protocols, such as HTTP and SMTP, and might not be supported by some database systems. By Binary encoding the data, you convert the data into a format that you can transfer over any Internet protocol or store in a database as character data. To convert the data back to a binary format, use the BinaryDecode function.

Adobe recommends that you use the BinaryEncode function, and not the ToBase64(binarydata) function, to convert binary data to Base64 data in all new applications.

This function provides a superset of the functionality of the ToBase64(binarydata) function.

See the following pages for additional information on handling binary data:

cffile for loading and reading binary data
cfwddx for serializing and deserializing binary data
IsBinary for checking variables for binary format
Len for determining the length of a binary object

Example

The following example reads a GIF file as binary data, converts it to a binary-encoded string, converts the binary-encoded data back to binary data, and writes the result to a file. It displays the encoded string and the image in the output file.

<h3>Binary Encoding Conversion Example</h3> 
 
<!--- Do the following if the form has been submitted. ---> 
<cfif IsDefined("Form.binEncoding")> 
 
    <!--- Read in a binary data file. ---> 
    <cffile action="readbinary" 
        file="C:\images\help.gif"  
        variable="binimage"> 
 
    <!--- Convert the read data to binary encoding and back to binary data. ---> 
    <cfscript> 
        binencode=BinaryEncode(binimage, Form.binEncoding); 
        bindecode=BinaryDecode(binencode, Form.binEncoding); 
    </cfscript> 
 
    <!---Write the converted results to a file. ---> 
    <cffile action="write" file="C:\temp\help.gif" output="#bindecode#" addnewline="No" > 
 
    <!--- Display the results. ---> 
    <cfoutput> 
        <p><b>The binary encoding:</b> #Form.binEncoding#</p> 
         
        <p><b>The image converted into a binary-encoded string by BinaryEncode 
            </b><br> 
            #binencode#</p> 
        <p><b>The image as written back to a file after converting back to binary 
            using BinaryDecode</b><br> 
        <img src="C:\temp\help.gif"><br></p> 
    </cfoutput> 
</cfif> 
 
<!--- The input form. ---> 
<form action="#CGI.SCRIPT_NAME#" method="post"> 
    <b>Select binary encoding</b><br> 
    <select size="1" name="binEncoding" > 
        <option selected>UU</option> 
        <option>Base64</option> 
        <option>Hex</option> 
    </select><br> 
    <br> 
    <input type = "Submit" value = "convert my data"> 
</form>