Putting cfftp to Use

Putting <cfftp> to Use

The core functionality of the <cfftp> tag is transferring files quickly across multiple servers. The potential for this base functionality to assist your applications is limited only by your imagination. The <cfftp> tag can be used to create an FTP interface to your Web sites; to asynchronously syndicate data out to an affiliate site in the form of an HTML or XML document; and to pull a list of available software to download from another Web site and display to users. The rest of this section demonstrates a few of the capabilities of this robust tag.

Displaying Available Files

The code in Listing 21.10 performs directory operations using the <cfftp> tag while connected to Mozilla's FTP site. This code retrieves a file listing and displays the results. It also uses ColdFusion's error handling by setting the tHRowOnError attribute to YES, and leverages connection caching to maintain a connection to the server during directory and file operations.

Listing 21.10. ftp_listdir.cfmDisplaying a File Listing Using the <cfftp> Tag

 <!---  Filename: ftp_listdir.cfm  Purpose: Do a simple FTP operation and show the files ---> <!--- Connect to the Mozilla FTP server ---> <cfftp action="open" username="anonymous" password="" server="ftp.mozilla.org" connection="moz" stopOnError="yes"> <cfftp connection="moz" action="getCurrentDir" stopOnError="yes"> <cfoutput> <p> FTP Directory Listing of the following directory on Mozilla's directory: #CFFTP.returnvalue#. </p> </cfoutput> <!--- Get a list of files from the directory ---> <cfftp connection="moz" action="ListDir" directory="#CFFTP.returnvalue#" name="dirlist" stopOnError="Yes"> <hr> <table border> <tr> <th>Name</th> <th>Path</th> <th>URL</th> <th>Length</th> <th>LastModified</th> <th>Is Directory</th> </tr> <tr> <!--- Output the results of the directory listing ---> <cfoutput query="dirlist"> <td>#dirlist.name#</td> <td>#dirlist.path#</td> <td>#dirlist.url#</td> <td>#dirlist.length#</td> <td>#dateFormat(dirlist.lastmodified)#</td> <td>#dirlist.isDirectory#</td> </tr> </cfoutput> </table> <!--- close connection ---> <cfftp action="close" connection="moz" stopOnError="yes"> 

Let's step through the code example. The first thing that happens is that a named connection to the Mozilla FTP server (ftp.mozilla.org) is established under the name "Moz". This allows all other FTP requests to use this name in their connection attribute instead of specifying the connection information in each request. Immediately following the connection to the server is a request to the directory returned by the getCurrentDir call for a listing of what is in that directory. The result of the directory listing is stored as a query object in the variable specified in the name attribute, which in our example is "dirlist". After grabbing the directory listing, the results are output into an HTML table by using <cfoutput>. Figure 21.7 shows the output from this example.

Figure 21.7. The <cfftp> directory listing.

When requesting a directory listing, the results are stored in a query object. The name attribute of the <cfftp> is set to the name of the query object that is to be created. After it is created, the query object can be manipulated just as if it were created with <cfquery>. Information about each file or subdirectory found in the specified directory is stored in a separate row in the query. The columns of the created query object are shown in Table 21.10.

Table 21.10. <cfftp> Query Object Definitions

COLUMN	DESCRIPTION
Name	Name of the file or directory.
Path	File path (without drive designation).
URL	Complete URL of the file or directory.
Length	Number indicating the size of the file.
LastModified	Date/Time value indicating when the file or directory was last modified.
Attributes	String indicating attributes of the file or directory.
IsDirectory	Boolean value indicating whether the element is a directory.
Mode	Applies only to Solaris and HP-UX. Permissions. Octal string.

Using <cfftp> to Download a File

The <cfftp> tag can be used to download a file from an FTP server to your local machine. Listing 21.11 shows the code used to download a file, which in this case is the Welcome file for the ftp.mozilla.org server. In this example the stopOnError is set to FALSE, so the CFFTP variables are checked for success. If the file type (binary or ASCII) is known ahead of time, transferMode can be specified ahead of time. If it is not known, the default of auto should be used.

Listing 21.11. ftp_getfile.cfmCode to Download a File Using <cfftp>

 <!---  Filename: ftp_getfile.cfm  Purpose: Do a simple FTP operation and get a file ---> <cfftp action="open" username="anonymous" password="" server="ftp.mozilla.org" connection="moz" stopOnError="yes"> <cfftp connection="moz" action="GetFile"  localfile= "#getDirectoryFromPath(getCurrentTemplatePath())#\welcome.txt"  remotefile="/Welcome" stopOnError="No"  transfermode="BINARY" failIfExists="No"> <cfoutput> FTP Operation Return Value: #CFFTP.ReturnValue#<br> FTP Operation Successful: #CFFTP.Succeeded#<br> FTP Operation Error Code: #CFFTP.ErrorCode#<br> FTP Operation Error Message: #CFFTP.ErrorText#<br> </cfoutput> 

Using <cfftp> to Upload a File

The <cfftp> tag can also be used to push a file to an FTP server from your local machine. Listing 21.12 shows the code used to push a file. Again, if the file type (binary or ASCII) is known ahead of time, the transferMode can be specified ahead of time. If it is not known, the default autoDetect should be used. This listing uses an FTP server local to the machine itself. You will need to modify the settings in order for the listing to work.

Listing 21.12. Using <cfftp> to Upload a File

 <cfset ftpServer = "127.0.0.1"> <cfset username="foo"> <cfset password="moo"> <cfftp action="open" username="#username#" password="#password#" server="#ftpServer#" connection="mycon" stopOnError="yes"> <!--- The file to put up. ---> <cfset localFile = getDirectoryFromPath(getCurrentTemplatePath()) &     getFileFromPath(getCurrentTemplatePath())> <cfoutput><p>Moving up #localFile#</p></cfoutput> <cfftp action="putfile" stopOnError="yes" connection="mycon"   localFile="#localFile#"   remoteFile="#getFileFromPath(getCurrentTemplatePath())#"   transfermode="autoDetect"> <cfoutput> FTP Operation Return Value: #CFFTP.ReturnValue#<br> FTP Operation Successful: #CFFTP.Succeeded#<br> FTP Operation Error Code: #CFFTP.ErrorCode#<br> FTP Operation Error Message: #CFFTP.ErrorText#<br> </cfoutput> <cfftp action="close" connection="mycon" stopOnError="yes"> 

The template begins by specifying the settings for the FTP server, username, and password. As mentioned earlier, you will need to modify these values in order for this script to work. A connection is opened using these settings. Next, we create a variable, localFile, that points to this template itself. This file is uploaded to the remote server using the same name as the local file (although without the directory). After the file is uploaded, the values in the CFFTP struct are displayed. Lastly, the connection is closed.

When you interact with a server and manipulate files or directories, security becomes an issue. You can do a couple of things to minimize your exposure during FTP communication. First, if you are not looking to have public anonymous access, move the FTP from port 21 (the default) to a different port. This is then broadcast only to your partners who need to use the site. Second, restrict certain functionality and directories to certain user accounts, so that you only expose what is absolutely necessary for each user. The <cfftp> tag has the username, password, and port attributes, which can all be used to deal with this issue.

Summarizing the <cfftp> Tag

The preceding examples demonstrate how to use the <cfftp> tag to transfer and view files across networks. Though using FTP is simple, the options it provides as it becomes a reaction to a needed business process make it a significant addition to ColdFusion.