ColdFusion FTP (cfftp)
If you've ever uploaded a website to a hosting provider, chances are, you've used FTP to do this. FTP stands for File Transfer Protocol. As the name would suggest, FTP is a standard protocol for transferring files across the Internet.
To use FTP, you need an "FTP client". This is a piece of software that enables you to initiate a transfer. Also, the destination computer needs to have an FTP server. This is a server that has been installed on the computer which allows FTP sites to be configured. IIS includes an FTP server. Once an FTP site has been configured, users with FTP clients can connect and transfer files to and from the server.
You may be familiar with programs such as WSFTP, FileZilla, CuteFTP etc. These are FTP clients. Using ColdFusion, you can create your own FTP client too.
Now, there's probably not much reason to create an FTP client for yourself if you already have one. But, what if your application needs to run a scheduled task on a regular basis that FTP's files from another server? Or, you might have a content management system that needs to allow users to FTP files to/from a business partner but access needs to be restricted to a given action (for example, you could prevent them from deleting files). The cfftp tag is perfect for this.
List the Contents of a Directory
The following code lists the contents of a directory on the remote FTP server. By leaving the directory attribute blank, we will get a list of the working directory. To specify another directory, use a relative path to that directory.
Note that listing the contents of a directory takes two steps. First, you do the FTP bit and save the result to a query. This is specified by providing a name. Once you've done the FTP bit, you can now work with the results by referring to the name. For now, we will simply output the results using the <cfdump> tag.
Also note that, I am using localhost as the server name. This is because, in order to test these examples, I configured an FTP site on my local machine, then performed actions against that site. There's no rule that says the FTP site can't be on the same machine as the client machine (although, apart from creating examples like these, you probably wouldn't bother).
Depending on the contents of the directory, the above code might result in something like this:
| query | ||||||||
|---|---|---|---|---|---|---|---|---|
| ATTRIBUTES | ISDIRECTORY | LASTMODIFIED | LENGTH | MODE | NAME | PATH | URL | |
| 1 | [empty string] | YES | {ts '2007-01-13 05:15:15'} | 0 | not currently supported | images | /images | ftp://localhost/images |
| 2 | [empty string] | NO | {ts '2007-01-13 05:15:15'} | 4 | not currently supported | index.html | /index.html | ftp://localhost/index.html |
| 3 | [empty string] | NO | {ts '2007-01-13 07:14:15'} | 6500 | not currently supported | ReadmeLater.htm | /ReadmeLater.htm | ftp://localhost/ReadmeLater.htm |
To be slightly more elaborate, rather than using <cfdump>, you could use <cfoutput> and refer to each element you need by name:
This would result in:
/index.html
/ReadmeLater.htm
Get File
The following code copies a file from the remote FTP server to the local machine. We can use the failIfExists attribute to determine what to do if the file already exists. In this case it is overwritten because we specify failIfExists="no".
Put File
The following code copies a file from the local machine to the remote FTP server.
Remove File
The following code removes (deletes) a file from the remote FTP server.
Rename File
The following code renames a remote file called "ReadmeLater.htm" to "ReadmeNow.htm".
Other Useful Attributes
The <cfftp> tag accepts various optional attributes that you may need to use, depending on your requirements or the FTP configuration. Usage will also depend on the FTP action you are performing too. These attributes are:
stoponerror- If this equals "yes", ColdFusion will throw an error if the FTP operation fails. Using stoponerror="yes" allows you to use cftry/cfcatch to handle the error.
timeout- Allows you to provide a timeout period.
retrycount- Number of times it will attempt to connect if there are problems.
asciiextensionlist- Allows you to provide a list of file extensions that are considered ASCII files. If transferMode="auto", these files will be transferred as ASCII.
transferMode- Allows you to set the transfer mode. Possible values are "auto", "ASCII" and "binary".
passive- Lets you determine whether to use passive mode or active mode. Some FTP servers require that you use passive mode. Possible values are "yes" and "no"
proxyServer- Lets you provide the details of a proxy server.