cfhttp

<cfhttp>

The Hypertext Transfer Protocol (HTTP) is the most common and generalized method for transferring information across the Web from servers to clients (browsers) and back again. Although it usually is associated with Hypertext Markup Language (HTML), HTTP is basically unlimited in the types of files it can transfer. In fact, both Web Services and Macromedia's Flash Remoting run on this protocol. Any file with a defined MIME (Multipurpose Internet Mail Extensions) type can be moved using this protocol. However, for large file transfer, it's recommended that you use FTP for transferring from server to server because of its optimization for this sort of action. FTP is covered in the "<cfftp>"section of this chapter.

Through the <cfhttp> tag, ColdFusion can make an internal call, using the HTTP protocol, to the Web server in the same way a Web browser would. Think of this arrangement as a virtual Web browser. Keeping that in mind, the <cfhttp> tag is susceptible to all the same errors to which a Web browser is susceptible.

Using the <cfhttp> tag, you can retrieve any Web page or Web-based file. The tag supports both the plain retrieval of information using the GET action, and an interactive retrieval (similar to a form posting) using the POST action. Again, remember that anything that can be done through a Web browser can be done through this tag. The latest release of ColdFusion also supports HEAD, PUT, DELETE, OPTIONS, and trACE methods. These will be discussed later.

The <cfhttp> tag provides a variety of options, such as simply displaying a requested page, interacting with pages to retrieve specialized content, and building a ColdFusion query from a delimited text file. (Code examples that demonstrate these options are shown in the section "Putting the <cfhttp> Tag to Use" later in this chapter.)

The standard tag syntax for <cfhttp> is as follows:

 <cfhttp url="url" method="get "> 

When using the POST operations, the <cfhttp> must be terminated with a closing tag; </cfhttp>. The GET operation does not require this termination. The <cfhttp> tag's final behavior can be changed depending on the value of the attributes supplied to it during execution. Table 21.1 explains the attributes and their functions.

Table 21.1. Attributes of the <cfhttp> Tag

ATTRIBUTE	DESCRIPTION
url	Required. Absolute URL of hostname or IP address of server on which file resides. url must include protocol (http or https) and hostname. It can contain a port number, and this value overrides the port value.
port	Optional. The port number on the server from which the object is being requested. Default is 80 when using http, and 443 when using https. When used with resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document.
method	Required. GET, POST, HEAD, PUT, DELETE, OPTIONS, trACE. Use GET to retrieve a binary or text file or to build a query using the contents of a text file. Use POST to send information to a CGI program or server page for processing. POST operations require the use of one or more <cfhttpparam> tags. HEAD acts like GET, but only the header of the remote resource is returned. This is a handy way to test if a URL simply exists. Use PUT to store a file on a remote server. The server has to understand and accept the request. Use DELETE to remove a file from a remote server. Like PUT, the remote server has to accept the command. Use trACE to ask the remote server simply to respond with your request. This could be used to examine your own request. Finally, OPTIONS will request the remote server to enumerate what features the server supports.
username	Optional. Submitted when a server requires a username for access.
password	Optional. Submitted when a server requires a password for access.
name	Optional. The name assigned to a query object when a query is to be constructed from a text file. Only used with GET and POST methods.
columns	Optional. Column names for a query. If no column names are specified, it defaults to the columns listed in the first row of the text file. Only used with GET and POST methods.
firstRowAsHeader	Optional. Determines how ColdFusion processes the first row of the query record set: Defaults to YES. Only used with GET and POST methods.
path	Optional. Path to the directory (local) in which a file is to be stored. If a path is not specified in a GET or POST operation, the results are created in the CFHTTP.FileContent variable for output.
file	Optional. The filename in which the results of the specified operation are stored. The path to the file is specified in the path attribute. Defaults to the name of the file being requested.
delimiter	Required for creating a query. Valid characters are a tab or a comma. The default is a comma (,).Only used with GET and POST methods.
textQualifier	Required for creating a query. Indicates the start and finish of a column. Must be escaped when embedded in a column. If the qualifier is a quotation mark, it should be escaped as "". If no text qualifier appears in the file, specify a blank space as " ". The default is the double quotation mark (").Only used with GET and POST methods.
resolveURL	Optional. YES or NO. Used for GET and POST operations. Default is NO. When set to YES, any link referenced in the remote page has its internal URL fully resolved and returned to the CFHTTP.FileContent variable so that the links remain intact. The following HTML tags, which can contain links, are resolved: img src, a href, form action, applet code, script src, embed src, embed pluginspace, body background, frame src, bgsound src, -object data, object classid, object codebase, and object usemap.
proxyServer	Optional. Hostname or IP address of a proxy server, if required.
proxyPort	Optional. The port number on the proxy server from which the object is being requested. Default is 80.
proxyUser	Optional. Username for the proxy server.
proxyPassword	Optional. Password for the proxy server.
userAgent	Optional. User agent request header. Defaults to "ColdFusion."
throwOnError	Optional. Boolean indicating whether to throw an exception that can be caught by using the <cftry> and <cfcatch> tags. The default is NO.
redirect	Optional. Boolean indicating whether to redirect execution or stop execution. The default is YES. If set to NO and throwOnError is set to YES, execution stops if <cfhttp> fails, and the status code and associated error message are returned in the variable CFHTTP.StatusCode. To see where execution would have been redirected, use the variable CFHTTP.ResponseHeader[LOCATION]. The key LOCATION identifies the path of redirection.
timeout	Optional. Value in seconds. When a URL timeout is specified in the browser, this setting takes precedence over the ColdFusion Administrator timeout, and ColdFusion uses the lesser of the URL timeout and the timeout passed in the timeout attribute, so that the request always times out before or at the same time as the page. If URL timeout is not specified, ColdFusion uses the lesser of the Administrator timeout and the timeout passed in the timeout attribute. If the timeout is not set in any of these, ColdFusion waits indefinitely for the <cfhttp> request to process. This attribute does not function with JDK 1.3.
charset	Optional. Defaults to UTF-8. A Java character-set name for the file or URL in a GET or POST. The following values are typically used: UTF-8, ISO-8859-1, UTF-16, US-ASCII, UTF-16BE and UTF-16LE.
getAsBinary	Optional. Allows you to convert a response to binary. Possible values are no, auto, and yes. If no, the result is converted into a ColdFusion object. This object can be displayed if the contents were text. If auto, ColdFusion will convert the result to a binary object if it recognizes the response as binary data. Finally, yes will always convert the result to binary.
result	Optional. By default, the result of a <cfhttp> call is stored in a variable called cfhttp. The result attribute lets you specify the name of the result struct. Default is cfhttp.
multipart	Optional. Instructs ColdFusion to send form data as multipart form data. Normally ColdFusion will send form data as application/x-www-form-urlencoded. Default is no.

Errors and Results for a <cfhttp> Call

As mentioned earlier, the <cfhttp> tag experiences all the same errors that a normal browser would, such as a 404 error when the requested page can't be found. In ColdFusion, a predefined error-handling routine is used to allow the program access and control to errors that happen throughout an application. This topic is covered in Macromedia ColdFusion MX 7 Web Application Construction Kit (Macromedia Press).

The <cfhttp> tag handles errors in two ways. One is through the ColdFusion error-handling framework, and the other is through suppression and population of a status code. The attribute that controls the mode that this tag runs through is tHRowOnError. When this attribute is set to trUE, the <cfhttp> will throw any error just like any other tag, thus enabling you to handle these errors inside the normal ColdFusion error-handling process of <cftry>/<cfcatch> or <cferror>.

When this attribute is FALSE (the default), ColdFusion suppresses any and all HTTP errors, including a 404 error, and populates the status code of this error inside the return structure called cfhttp.

NOTE

When a delimited text file is converted into a query, errors generated in the process ignore the throwOnError attribute and throw a standard ColdFusion error.

Each request, regardless of whether it is a POST or a simple GET, creates the cfhttp structure that stores the outcome of the request. A quick way to look at the resulting CFHTTP structure is to display it through the <cfdump> tag preceding a <cfhttp> call. Table 21.2 shows the keys of the CFHTTP structure and when they are populated. Do not forget that you can change the name of this result structure by using the result attribute.

Table 21.2. The Keys of the CFHTTP Structure

KEY	DESCRIPTION
charset	The character set of the response.
errorDetail	Contains the error, if any, that occurred when performing the request.
FileContent	Returns the contents of the file for the text and MIME files.
MimeType	Returns the MIME type.
ResponseHeader[KEY]	Returns the response headers. If there is only one instance of a header key, the value can be accessed as a simple type. If there is more than one instance, the values are placed in an array within the ResponseHeader structure.
Header	Returns the raw response header.
StatusCode	Returns the HTTP error code and associated error string if the throwOnError is False.
text	ColdFusion will attempt to determine if the response was plain text. The text result will either be Yes or No, depending on whether ColdFusion recognizes the response as text.

Using the <cfhttpparam> Tag

Sometimes one Web site needs to interact with another Web site by passing it data. Setting <cfhttp> to POST and passing each piece of data through a <cfhttpparam> tag accomplishes this. The <cfhttpparam> tag can pass a HEADER, BODY, XML, FORM, COOKIE, FILE, URL, or CGI variable to the URL specified in the <cfhttp> tag. It requires that it is placed between the start and end <cfhttp> tags. Do note that the passed values are URL encoded, so that special characters are preserved as they are passed to the server.

The syntax for the <cfhttpparam> tag is as follows:

 <cfhttpparam name="name" type="transaction type" value="value" file="filename" > 

Table 21.3 shows the attributes for this tag.

Table 21.3. Attributes of the <cfhttpparam> Tag

ATTRIBUTE	DESCRIPTION
name	Required. A variable name for data being passed.
type	Required. The transaction type. Valid entries are HEADER, BODY, XML, URL, FORMFIELD, COOKIE, CGI, and FILE.
value	Optional for type="File". Specifies the HEADER, BODY, XML, URL, FORMFIELD, COOKIE, FILE, or CGI variable being passed to the server.
file	Required for type="File". Fully qualified local filename to be uploaded to the server. For example, c:\temp\amazon.lst.
encoded	Optional. Only applies for type="FormField" or type="CGI". If set to true, the value will be URL encoded.
mimeType	Optional, Only applies for type="File". Signifies the MIME type for the data in the file.