cfhttp

Description

Executes HTTP POST and GET operations on files. You can execute standard GET operations and create a query object from a text file. POST operations upload MIME file types to a server, or post cookie, formfield, URL, file, or CGI variables directly to a server.

Category

Forms tags, Internet Protocol tags

Syntax

<cfhttp 
  url = "hostname"
  port = "port_number"
  method = "get_or_post"
  username = "username"
  password = "password"
  name = "queryname"
  columns = "query_columns"
  firstrowasheaders = "yes" or "no" 
  path = "path"
  file = "filename"
  delimiter = "character"
  textQualifier = "character"
  resolveURL = "yes" or "no"
  proxyServer = "hostname"
  proxyPort = "port_number"
  userAgent = "user_agent"
  throwOnError = "yes" or "no"
  redirect = "yes" or "no"
  timeout = "timeout_period"
  charset = "character set">
</cfhttp> 

See also

cfftp, cfhttpparam, cfldap, cfmail, cfmailparam, cfpop

History

New in ColdFusion MX:

Attributes

Attribute Req/Opt Default Description
url
Required
http
Absolute URL of host name or IP address of server on which file resides. URL must include protocol (http or https) and hostname. It can contain a port number. This value overrides port value.
port
Optional
80
Port number on server from which object is requested. When used with resolveURL, URLs of retrieved documents that specify a port number are automatically resolved, so that links in retrieved document remain functional. Value in url attribute overrides this value.
method
Optional
get
  • get: downloads text or binary file, or create query from the contents of a text file.
  • post: sends information to server page or CGI program for processing. Requires a cfhttpparam tag.
username
Optional
 
A username. May be required by server.
password
Optional
 
A password. May be required by server
name
Optional
 
Name to assign to a query if it is constructed from returned HTTP results.
columns
Optional
 
Column names for a query, when creating it as a result of a cfhttp method = "get".
By default, the first row of a text file is interpreted as column heads. If there are column heads in the text file from which the query is drawn, do not specify this attribute, except to overwrite them.
If a duplicate column heading is encountered, ColdFusion appends an underscore to the name to make it unique.
If there are no column headers in the text file, or to override those in the file, specify the columns attribute. ColdFusion never processes the first row of a file as data,.
firstrowasheaders
Optional
yes
Determines how ColdFusion processes the first row of the query record set:
  • yes:
  • - If the columns attribute is not specified: processes as column heads
  • - If the columns attribute is specified: this attribute is not used
  • no:
  • - If the columns attribute is not specified: processes as data, and generates column names; for example, "column_1"
  • - If the columns attribute is specified: this attribute is not used
path
Optional
 
Path to directory in which to store file. If path is not specified in POST or GET, a variable (cfhttp.fileContent) is created; you can use it to display the post results, in a cfoutput tag.
file
Required if post and if path is specified
 
Name of file that is accessed. For a get operation, defaults to name specified in url. Enter path information in the path attribute.
delimiter
Required to create query
, [comma]
  • tab
  • comma
textQualifier
Required to create query
"" [double quotation mark]
Start and end of a column. If it is embedded in column, this value must be escaped. For example, if qualifier is a double quotation mark, it is escaped as """". If there is no text qualifier in the file, specify " ".
resolveURL
Optional
No
Applies to get and post.
  • Yes: internal URLs in a page reference returned into fileContent internal variable are fully resolved, including port number, so that links in the page remain functional. Applies to these HTML tags:
  • - 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
  • - object usemap
proxyServer
Optional
 
Host name or IP address of a proxy server.
proxyPort
Optional
80
Port number on proxy server from which object is requested. When used with resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved, so that links in the retrieved document remain functional.
userAgent
Optional
 
User agent request header.
throwOnError
Optional
No
  • Yes: throw an exception that can be caught with the cftry and cfcatch tags
  • No
redirect
Optional
Yes
If No, and throwOnError = "yes": if cfhttp fails, execution stops, and the status code and associated error message are returned in the variable cfhttp.statuscode.
To determine where execution would be redirected, use the variable cfhttp.responseHeader[LOCATION]. The key LOCATION shows the redirection path. ColdFusion follows a maximum of four redirects on a request. If there are more, ColdFusion functions as if redirect = "no".
  • Yes: redirect execution
  • No: stop execution
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
The server charset; if none, 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
  • UTF-16LE
For a list of character sets, see:
http://www.w3.org/International/O-charset-lang.html

Usage

If this value includes the substring "https" (which indicates that the object of the request is a secure server) but does not include a port number, the default value of the port attribute is 443. (If the URL value includes a port number, its value overrides the value of port.)

For the ColdFusion Administrator timeout and the URL timeout to take effect, you must enable the timeout in the ColdFusion Administrator, Server Settings page. For more information, see Administering ColdFusion MX.

Variables returned by a cfhttp get operation

The cfhttp tag returns data in variables. For example, if you specify a URL that points to a text or binary file in a cfhttp method = "get" operation, the file is downloaded and stored in a ColdFusion variable or file.

These variables can be accessed in this way:

#cfhttp.fileContent# 
#cfhttp.mimeType#
#cfhttp.header#
#cfhttp.responseHeader[http_header_key]#

The responseHeader variable is returned as a CFML structure; the others, as strings.

Building a query from a delimited text file

To download a file in a ColdFusion page so that a query can be built using the file, the file must be either comma- or tab-delimited. Macromedia recommends that you include text qualification. The file is parsed and an appropriate query is built from it. You can specify columns in the attribute list so the client can override the columns specified in the file.

There is error checking within the tag that prevents a user from entering an invalid column name, or using an invalid column name that was specified in the original file. If an illegal filename is encountered, the illegal characters are stripped. This action could produce duplicate column names, so duplicate columns are renamed and inserted into the query header.

The query has all of the functionality of a standard cfquery object, as follows:

The cfhttp tag returns the following variables:
Name Description
#cfhttp.fileContent#  

File contents, for text and MIME files.
#cfhttp.mimeType# 

MIME type.
#cfhttp.responseHeader[http_hd_key]# 

Response headers. If there is one instance of a header key, value can be accessed as simple type. If there is more than one instance, values are put in an array in responseHeader structure.
#cfhttp.header# 

Raw response header.
#cfhttp.statuscode# 

HTTP error code and associated error string, if throwOnError = "no".

Terminate a cfhttp method = "post" operation with </cfhttp>.

Example

<!--- This example shows the use of CFHTTP to pull information dynamically from 
the snippets directory ---> 
<p>This view-only example shows the ability of CFHTTP to pull the contents of 
a web resource from the Internet or from a local directory. 
<!--- 
<form action="index.cfm" method="POST"> 
Try entering a URL for the tag to return: 
  <input type="Text" size="25" name="urladdress" 
    value="http://www.macromedia.com"> 
  <input type="Submit" name="" value="get page"> 
</form> 
<!----- sets a default value for a URL to retrieve -----> 
<cfparam name="urladdress" 
  default="http://localhost/cfdocs/index.htm">
<!--- if we have passed a url address in the form, display the address ---> 
<cfif IsDefined("form.urladdress") is True> 
  <!--- do simple error check to avoid crashing the tag ---> 
  <cfif Trim(Form.urladdress) is "" 
    or Trim(Form.urladdress) is "http://"> 
    <!--- if error condition tripped, set alternative ---> 
    <cfset urlAddress ="http://localhost/cfdocs/index.htm"> 
    <h4>because you entered no url or an empty string, the tag will 
    return the following address: http://localhost/cfdocs/index.htm</h4> 
  <cfelse> 
    <!--- otherwise use address passed from form ---> 
    <cfset urlAddress = form.urladdress> 
  </cfif> 
  <!--- use CFHTTP tag to get the file content represented     by urladdress ---> 
  <cfhttp url="#urladdress#" 
    method="GET" resolveurl="YES"> 
  </cfhttp> 
<cfelse> 
  <!---   the first time through, retrieve a URL that we know exists ----> 
  <cfhttp url="http://localhost/cfdocs/index.htm" 
    method="GET" resolveurl="YES"> 
  </cfhttp> 
</cfif> 
<!----   Now, output the file, including the mimetype and content ------> 
<h3>Show the file</h3> 
<cfoutput> 
  <p>Your file was of type: #CFHTTP.MimeType#
  <p>#HTMLCodeFormat(CFHTTP.FileContent)# 
</cfoutput> ---> 

Comments