Inside Coldfusion MX

CFFTP

In the last section, we examined how we would use CFFILE to move files between the server and the client. Suppose we want to move files from the server to another server? That's where CFFTP comes in.

CFFTP enables ColdFusion developers to utilize FTP to move files between their ColdFusion Servers and other FTP servers.

Table 12.3 provides you with an overview of the CFFTP tag's syntax and attributes.

Table 12.3. CFFTP Attributes Table

Attribute

Description

action

This is a required attribute that determines the FTP action to be performed.

Valid actions for this attribute are as follows:

  • open

  • close

  • changedir

  • createdir

  • listdir

  • removedir

  • getfile

  • putfile

  • rename

  • remove

  • getcurrentdir

  • getcurrenturl

  • existsdir

  • existsfile

  • exists

To perform any action on an FTP server, you must first use the connect action to connect to that server. An example later in this section shows you how to connect and perform a directory listing.

username

This is a required attribute when the action is open. This attribute enables you to pass in the username with which you would like to connect.

password

This is a required attribute when the action is open; this attribute specifies the password of the user whom you are connecting as.

server

This is a required attribute for the open action and enables you to specify the server to which you are connecting.

timeout

This is an optional attribute that enables you to specify the maximum time you want ColdFusion to wait for any FTP action to be performed. If left blank, this value defaults to 30 seconds.

port

This attribute enables you to specify the port to which you would like to connect on the FTP server. The default port for FTP is 21, but you might need to change this if you have configuration or firewall considerations.

connection

This optional attribute enables you to assign a name to this FTP connection. This attribute is useful should you want to cache this connection for later use.

proxyserver

This is an optional string attribute that enables you to specify the name or address of a proxy server that you want to use to connect.

retrycount

This optional attribute enables you to specify the number of times that you would like the connection to be retried should an action fail. By default, this value is 1.

stoponerror

This is an optional attribute that enables you to tell CFFTP to stop processing if an error is encountered.

This attribute takes either a yes or no value. If set to yes, all processing is halted if an error is encountered. If this value is set to no and an error is encountered, three error variables are automatically populated so that you can diagnose the problem at a later time. These error values are as follows:

  • cfftp.succeded. Returns yes or no.

  • cfftp.errorcode. Returns the error number associated with the error that was encountered.

  • cfftp.errortext. Returns a message with a short description of the error that was encountered.

passive

This optional attribute enables you to specify whether you want to allow the FTP connection to enable passive mode FTP. This attribute takes a yes or no value.

Now let's look at an example of how we would use CFFTP to connect to an FTP server and perform a simple listing on a remote directory.

<html> <head> <title>CFFTP Usage Example</title> </head> <body> <!--- change these values to match an ftp account you know works ---> <cfparam name="ftpServer" default="ftp.mauzy-broadway.com"> <cfparam name="ftpUsername" default="anonymous"> <cfparam name="ftpPassword" default="info@mauzy-broadway.com"> <!--- open a connection to an ftp server ---> <cfftp action="open" connection="theConnection" server="#ftpServer#" username="#ftpUsername#" password="#ftpPassword#" stopOnError="Yes"> <!--- did we get connected? ---> <cfoutput>#cfftp.succeeded#</cfoutput> <cfif cfftp.succeeded> <!--- perform a listing on the initial directory ---> <cfftp action="LISTDIR" stopOnError="Yes" name="DirectoryListing" directory="/" connection="theConnection"> <cfoutput query="DirectoryListing"> #name#<BR> </cfoutput> </cfif> <!--- close the connection on the server ---> <cfftp action="close" connection="theConnection" stopOnError="Yes"> <!--- did the connection close ok? ---> <cfoutput>#cfftp.succeeded#</cfoutput> </body> </html>

In addition to performing simple directory listings, you can use CFFTP to interact with the files on the FTP server just as you would using any other FTP client. This gives your ColdFusion application the power to upload/ download files, manage a remote file system, and offer direct connections to file repositories for your web clients.

For a full explanation of the CFFTP syntax and its usage, see Appendix B, "Function Reference."
Related

Категории