CFML Reference
|
|
ColdFusion Tags
|
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:
- The
firstrowasheaders
attribute is new.
- The
charset
attribute is new.
- ColdFusion uses the Sun JSSE library, which supports 128-bit encryption, to support Secure Sockets Layer (SSL).
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]
|
|
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.
- The fileContent variable is available for text and MIME file types.
- The
mimeType
variable is available for all file manipulations.
- The Header and responseHeader variables display response headers.
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:
- HTTP POST: You can nest
cfhttpparam
tags within a cfhttp
tag. The browser can be pointed to a URL that specifies a CGI executable or a ColdFusion page. Because cfhttpparam
tags can be nested, you can construct a multipart/form-data style post. A file content variable is created; you can use it in a cfoutput
tag. If path
and file
attributes are specified, the data returned from the server is saved to the specified location.
- Authentication:
cfhttp
supports Windows NT Basic Authentication for GET and POST operations. However, Basic Authentication does not work if your web server has Windows NT Challenge/Response (Microsoft IIS) enabled.
- Encryption:
cfhttp
uses SSL to negotiate secure transactions.
cfhttp.statuscode: cfhttp
provides the cfhttp.statuscode
variable for access to the HTTP error string associated with the error if the throwOnError
attribute is set to No (or if it is not specified, because it defaults to No).
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