FTP Agents

<cfftp> allows developers to implement File Transfer Protocol operations from the ColdFusion server to an FTP server. The <cfftp> tag governs all the actions you require to connect to and perform file actions on the FTP server.

NOTE

The <cfftp> tag is specifically for transferring files between a ColdFusion server and an FTP server. <cfftp> is unable to move files between a ColdFusion server and a browser (client). Use <cffile> with action="upload" to copy files from the client to a ColdFusion server; use <cfcontent> to move and copy files from a ColdFusion server to the browser.

<cffile> and <cfcontent> are covered in Chapter 39, "System Integration."

First you need to establish, or "open," a connection with the FTP server. After a connection is made, the details (server, user name, password, and so on) can be cached by <cfftp>, so you need only refer to the name of the connection for subsequent actions on the server for that FTP session. If the FTP session times out or your connection is closed for whatever reason, you will need to reopen the connection.

 <cfftp action="OPEN"        server="ftp.forta.com"         username="grover"        password="elmo"        stoponerror="Yes"        connection="xfer"> 

After a connection has been made, the other ACTION attribute values can be used to perform operations on the FTP server. Generally the ACTION performs some task and returns a variable, CFFTP.ReturnValue. The value of this variable depends on the task being performed. For example, for an ACTION="ExistsFile" operation to test whether a file exists on the FTP server, CFFTP.ReturnValue will be either YES or NO. The exception to this is ACTION="ListDir", which instead generates a query object containing a directory listing of the specified directory.

 <cfftp action="LISTDIR"        stoponerror="Yes"        name="sales_files"        directory="/"        connection="xfer"> <cfoutput query="sales_files"> # Name#: #URL#<br> </cfoutput> 

On the FTP server, you must navigate to the directory you want before performing a file operation. For example, you might log in to a home directory on the FTP server, but then need to change the directory to /pub/uploads before being able to upload a file. You cannot nominate the directory and file in a single operation. FTP uses a slightly different vocabulary than you might be used to. PUT is used for uploading a file to the FTP site, and GET is used for retrieving files.

 <!--- check to see if the directory is there ---> <cfftp action="EXISTSDIR"         stoponerror="No"         directory="/pub/uploads"         connection="xfer"> <cfif CFFTP.returnvalue IS "NO">  <cfabort showerror="Uploads directory does not exist!"> </cfif> <!--- change directory ---> <cfftp action="CHANGEDIR"         stoponerror="No"         directory="/pub/uploads"         connection="xfer"> <!--- upload file to the current directory ---> <cfftp action="PUTFILE"        stoponerror="No"        localfile="c:salesjul.xls"        remotefile="jul.xls"        transfermode="AUTO"        connection="xfer"> 

NOTE

When your application is finished with the FTP connection, it is polite to close the FTP session by using action="CLOSE". If you neglect to close the session, it will remain open until the connection times out. This would be considered particularly poor etiquette if a connection time limit existed on the FTP server you were contacting.

CAUTION

Use of <cfftp> on the ColdFusion server can be blocked using basic security under ColdFusion Administrator. There are obvious security issues when allowing developers to move any file off the server to any remote FTP server.