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:
|
|||||||||||||
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:
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> ---> |
URL | |
Required | |
Default value: "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 | |
Default value: "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 | |
Default value: "get"
|
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 | |
Default value: "yes"
Determines how ColdFusion processes the first row of the query record set:
|
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 | |
Default value: ", [comma]"
|
TEXTQUALIFIER | |
Required to create query | |
Default value: """ [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 | |
Default value: "No"
Applies to get and post.
|
PROXYSERVER | |
Optional | |
Host name or IP address of a proxy server. |
PROXYPORT | |
Optional | |
Default value: "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 | |
Default value: "No"
|
REDIRECT | |
Optional | |
Default value: "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".
|
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 | |
Default value: "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:
For a list of character sets, see:http://www.w3.org/International/O-charset-lang.html |