<cfftp>The other transfer protocol this chapter examines is the File Transfer Protocol (FTP). FTP is a streamlined mechanism for transferring files from one computer to another. Because both ASCII and binary transfers are supported by the FTP protocol, it is a de facto way of distributing software and files across the Internet. This protocol is not used as a means to interact with other servers for processing, as HTTP is used. Rather, FTP provides a mechanism for delivery or pulling across the Internet. In ColdFusion, the <cfftp> tag is used to implement FTP operations. In its default configuration, the <cfftp> tag caches connections for reuse within the same template. Operations using the <cfftp> tag are divided into two types:
Connection Operations with <cfftp>The syntax used in connection operations for the <cfftp> tag is as follows: <cfftp action="action" username="username" password="password" server="server" timeout="timeout in seconds" port="port" connection="name" proxyServer="proxyserver" retryCount="number" passive="YES/NO" stopOnError="Yes/No" result="cfftp"> This form of the <cfftp> tag is used to establish or close an FTP connection. No file manipulation can occur without a valid connection to the FTP server. Connections to the server can be made with each and every request by providing all the connection information for each request or by establishing a named connection and referring it in the connection attribute. If a connection is established, all subsequent requests can be referred to by the connection name in the connection attribute. The attributes that control the behavior of the <cfftp> tag during the establishment or closure of a session are shown in Table 21.4.
Listing 21.9 shows a simple template that establishes an FTP connection. Listing 21.9. ftp1.cfmEstablishing an FTP Connection<!--- Filename: ftp1.cfm Purpose: Do a simple FTP operation ---> <cfftp action="open" username="anonymous" password="" server="ftp.mozilla.org" connection="mozilla" stoponerror="No"> <cfif cfftp.succeeded> <cfoutput> FTP Operation Successful: #CFFTP.succeeded#<br> FTP Return Value: <pre>#CFFTP.returnValue#</pre> </cfoutput> <cfftp action="close" connection="mozilla" stoponerror="No"> <cfelse> <cfoutput> FTP Error Code: #CFFTP.ErrorCode#<br> FTP Error Text: #CFFTP.ErrorText#<br> </cfoutput> </cfif> This simple example opens an FTP connection to Mozilla's FTP server, checks the status, and then closes the connection. NOTE <cfftp> can be used to push and pull files only on servers that have an FTP service running. During a connection, the <cfftp> tag always requires the username and password attributes. When you need to use an anonymous access to an FTP site, set username to anonymous and password to blank. Looking at the first example, notice that the second <cfftp> didn't have to specify the server, username, or password attribute. This opened a cached connection in the first <cfftp>, enabling you to perform a series of file and directory operations without the overhead of opening and closing a connection. This is accomplished by the connection attribute when the FTP connection is established. All subsequent calls to the <cfftp> tag in the same template use the same connection name. Using this name forces <cfftp> to automatically reuse the connection information, which results in faster connections and improves file transfer performance. NOTE If you're using a cached connection, you do not have to specify the username, password, and server attributes for your file and directory operations. The scope of the connection in the first example is local to the current template. To cache connections across multiple pages, you must set the connection attribute to a persistent scope, such as session or application. Even though it can maintain a connection across multiple pages, it is recommended that you keep it open only for the duration of your requests. Managing the number of unique connections to the FTP server is critical because most FTP servers allow a set number of concurrent connections at any one time. Having a persistent connection to the FTP server effectively ties up one of the connections to the server. Depending on the FTP server you are connecting to, making changes to cached connection settings, such as changing retryCount or timeout, will require shutting down and reestablishing the connection. File and Directory Operations with <cfftp>After you establish an FTP connection, you can perform various file and directory operations to send files to the server or receive files and directory listings from the server. Table 21.5 shows the attributes for file and directory operations.
Table 21.6 shows the attributes required for <cfftp> actions when a cached connection is used. If a cached connection is not used, the username, password, and server attributes must also be set.
Errors and Results for a <cfftp> CallEach FTP request, regardless of success or failure, results in CFFTP variables. (Remember, however, that you can rename this variable by using the result attribute.) The value of these variables depends in part on the action requested. The CFFTP is represented as a ColdFusion structure for manipulation. Table 21.7 lists the CFFTP variables available and their possible values. Because the value of CFFTP.ReturnValue is dependent on the type of action, see Table 21.8 for an explanation of what that value means.
Error handling with the <cfftp> tag can be done through the traditional error-handling framework of ColdFusion or through checking the status code on the resulting CFFTP scope. The attribute stopOnError is used to determine which mode you are running in. With its value set to TRUE, it will raise an error upon failure. However, this option is not recommended for handling errors with <cfftp> for two reasons. First, the errors are not as descriptive as the status errors returned through the CFFTP structure; second, no CFFTP structure is created if <cfftp> tHRows the error itself. Therefore, stopOnError should only be set to True if you want to just stop the page right there and do nothing with the error itself. The other way to handle errors is to set the stopOnError value to False. This causes ColdFusion to suppress the normal error handling and instead record the error into several CFFTP variables. To verify the success of the request, simply query the CFFTP.Succeeded variable. This is a Boolean value that determines whether the request was successful. Due to the granularity of the information provided in this structure, this is the recommended way to handle errors when you want to handle the error at all programmatically. TIP If you want to fold errors from a <cfftp> call into the error-handling framework of ColdFusion, use the <cfthrow> tag to raise the error. To populate its attributes, use the keys of the resulting CFFTP structure. Table 21.9 shows the possible error codes and their text descriptions.
|