cfhttp

Description

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

Syntax


<cfhttp url = "hostname"

  port = "port_number"

  method = "get_or_post"

  username = "username"

  password = "password"

  name = "queryname"

  columns = "query_columns"

  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">

</cfhttp>

Attributes

Attribute

Description

url
Required. Full URL of the host name or IP address of the server on which the file resides. The URL must be an absolute URL, including the protocol (http or https) and hostname. It may optionally contain a port number. Port numbers specified in the url attribute override the port attribute.

port
Optional. The port number on the server from which the object is requested. Default is 80. When used with resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document. If a port number is specified in the url attribute, the port value overrides the value of the port attribute.

method
Required. GET or POST. Use GET to download a text or binary file or to create a query from the contents of a text file. Use POST to send information to a server page or a CGI program for processing. POST requires the use of a cfhttpparam tag.

username
Optional. When required by a server, a valid username.

password
Optional. When required by a server, a valid password.

name
Optional. The name to assign to a query if the a query is constructed from a file.

columns
Optional. Specifies the column names for a query when creating a query as a result of a cfhttp GET.
By default, the first row of a text file is interpreted as column headings. If there are column headers in the text file from which the query is drawn, do not specify this attribute except to overwrite them.
When duplicate column heading names are encountered, ColdFusion appends an underscore character to the duplicate column name to make it unique.
If there are no column headers in the text file, or to override those in the file, you must specify the columns attribute. However ColdFusion never treats the first row of the file as data, even if you specify the columns attribute.

path
Optional. The path to the directory in which a file is to be stored. If a path is not specified in a POST or GET operation, a variable is created (cfhttp.fileContent) that you can use to display the results of the POST operation in a cfoutput.

file
Required in a POST operation if path is specified. The filename to be used for the file that is accessed. For GET operations, defaults to the name specified in url. Enter path information in the path attribute.

delimiter
Required for creating a query. Options are a tab or comma. Default is a comma.

textQualifier
Required for creating a query. Indicates the start and finish of a column. Should be appropriately escaped when embedded in a column. For example, if the qualifier is a double quotation mark, it should be escaped as """". If there is no text qualifier in the file, specify it as " ". Default is the double quotation mark (").

resolveURL
Optional. Yes or No. Default is No. For GET and POST operations, if Yes, page reference returned into the fileContent internal variable has its internal URLs fully resolved, including port number, so that 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

object usemap

proxyServer
Optional. Host name or IP address of a proxy server.

proxyPort
Optional. The port number on the proxy server from which the object is requested. Default is 80. When used with resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document.

userAgent
Optional. User agent request header.

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 = "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. ColdFusion will follow up to five redirections on a request. if this limit is exceeded, ColdFusion behaves as if redirect = "no".

timeout
Optional. A value, in seconds. When a URL timeout is specified in the browser, the timeout attribute setting takes precedence over the ColdFusion Administrator timeout. The ColdFusion server then 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 times out. If there is no URL timeout specified, ColdFusion takes the lesser of the ColdFusion Administrator timeout and the timeout passed in the timeout attribute.
If there is no timeout set on the URL in the browser, no timeout set in the ColdFusion Administrator, and no timeout set with the timeout attribute, ColdFusion waits indefinitely for the cfhttp request to process.

Attribute	Description
url	Required. Full URL of the host name or IP address of the server on which the file resides. The URL must be an absolute URL, including the protocol (`http` or `https`) and hostname. It may optionally contain a port number. Port numbers specified in the `url` attribute override the `port` attribute.
port	Optional. The port number on the server from which the object is requested. Default is 80. When used with `resolveURL`, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document. If a port number is specified in the `url` attribute, the port value overrides the value of the `port` attribute.
method	Required. GET or POST. Use GET to download a text or binary file or to create a query from the contents of a text file. Use POST to send information to a server page or a CGI program for processing. POST requires the use of a `cfhttpparam` tag.
username	Optional. When required by a server, a valid username.
password	Optional. When required by a server, a valid password.
name	Optional. The name to assign to a query if the a query is constructed from a file.
columns	Optional. Specifies the column names for a query when creating a query as a result of a `cfhttp` GET. By default, the first row of a text file is interpreted as column headings. If there are column headers in the text file from which the query is drawn, do not specify this attribute except to overwrite them. When duplicate column heading names are encountered, ColdFusion appends an underscore character to the duplicate column name to make it unique. If there are no column headers in the text file, or to override those in the file, you must specify the `columns` attribute. However ColdFusion never treats the first row of the file as data, even if you specify the `columns` attribute.
path	Optional. The path to the directory in which a file is to be stored. If a path is not specified in a POST or GET operation, a variable is created (`cfhttp.fileContent`) that you can use to display the results of the POST operation in a `cfoutput`.
file	Required in a POST operation if `path` is specified. The filename to be used for the file that is accessed. For GET operations, defaults to the name specified in `url`. Enter path information in the `path` attribute.
delimiter	Required for creating a query. Options are a tab or comma. Default is a comma.
textQualifier	Required for creating a query. Indicates the start and finish of a column. Should be appropriately escaped when embedded in a column. For example, if the qualifier is a double quotation mark, it should be escaped as """". If there is no text qualifier in the file, specify it as " ". Default is the double quotation mark (").
resolveURL	Optional. Yes or No. Default is No. For GET and POST operations, if Yes, page reference returned into the fileContent internal variable has its internal URLs fully resolved, including port number, so that 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 object usemap
proxyServer	Optional. Host name or IP address of a proxy server.
proxyPort	Optional. The port number on the proxy server from which the object is requested. Default is 80. When used with `resolveURL`, the URLs of retrieved documents that specify a port number are automatically resolved to preserve links in the retrieved document.
userAgent	Optional. User agent request header.
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 = "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. ColdFusion will follow up to five redirections on a request. if this limit is exceeded, ColdFusion behaves as if `redirect = "no"`.
timeout	Optional. A value, in seconds. When a URL timeout is specified in the browser, the `timeout` attribute setting takes precedence over the ColdFusion Administrator timeout. The ColdFusion server then 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 times out. If there is no URL timeout specified, ColdFusion takes the lesser of the ColdFusion Administrator timeout and the timeout passed in the `timeout` attribute. If there is no timeout set on the URL in the browser, no timeout set in the ColdFusion Administrator, and no timeout set with the `timeout` attribute, ColdFusion waits indefinitely for the `cfhttp` request to process.

Usage

You must enable the timeout set in the ColdFusion Administrator in order for the ColdFusion Administrator timeout and the URL timeout to take effect. This setting is on the ColdFusion Administrator Server Settings page. For more information, see Advanced ColdFusion Administration.

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 let you see the response headers.

These variables can be accessed in the following manner:

#cfhttp.fileContent#

#cfhttp.mimeType#

#cfhttp.header#

#cfhttp.responseHeader[http_header_key]#

The responseHeader variable is returned as a CFML structure. The other variables are returned as strings. For a summary of variables returned by cfhttp, see the table at the end of this section.

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-separated or tab-delimited. Text qualification may be omitted, although this is risky. The file is parsed and an appropriate query is built from it. Columns may be specified in the attribute list so that 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.

HTTP POST cfhttpparam tags can be nested inside a cfhttp tag in a POST operation. The browser can be pointed to a URL that specifies a CGI executable or a ColdFusion page. Since multiple cfhttpparam tags can be nested in one cfhttp tag, you can construct a multipart/form-data style post. A file content variable is created; it can be used 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 can use Secure Sockets Layer (SSL) for negotiating secured transactions over the wire.
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 not specified, since it defaults to "No."

The following table shows all variables returned by cfhttp.

Variable Names

Description

#cfhttp.fileContent#
Returns the contents of the file for text and MIME files.

#cfhttp.mimeType#
Returns the MIME type.

#cfhttp.responseHeader[http_hd_key]#
Returns the response headers. If there is only one instance of a header key, the value may be accessed as a simple type. If there is more than one instance, the values are placed in an array within the responseHeader structure.

#cfhttp.header#
Returns the raw response header.

#cfhttp.statuscode#
Returns the HTTP error code and associated error string if throwOnError is NO.

Variable Names	Description
`#cfhttp.`fileContent`#`	Returns the contents of the file for text and MIME files.
`#cfhttp.mimeType#`	Returns the MIME type.
#cfhttp.responseHeader[http_hd_key]#	Returns the response headers. If there is only one instance of a header key, the value may be accessed as a simple type. If there is more than one instance, the values are placed in an array within the responseHeader structure.
`#cfhttp.header#`	Returns the raw response header.
#`cfhttp`.`statuscode`#	Returns the HTTP error code and associated error string if `throwOnError` is NO.

Terminate cfhttp method = "post" operations with </cfhttp>. Termination is not required with cfhttp method = "get" operations.

Example

<!--------------------------------------------------------------------

This example shows the use of cfhttp to pull information from a web page. 

---------------------------------------------------------------------->

<html>

<head>

<title>

cfhttp Example

</title>

</head>



<body>

<H3>cfhttp Example</H3>



<P>This example shows the ability of cfhttp to pull

the contents of a web page from the Internet, and shows how 

you can get the following information by using cfhttp variables:

</P>

<UL>

<LI>display the page (fileContent)

<LI>derive the MIME type of the page (mimeType) 

<LI>find the header responses (responseHeader).

</UL>



<cfhttp

  url = "http://www.allaire.com"

  resolveurl = 1

  throwOnError = "Yes"

>

</cfhttp>



<cfoutput>

#cfhttp.fileContent#<BR>

<BR>

<H3><B>The mime-type:</B></H3><BR>

#cfhttp.mimeType#<BR>

<H3><B>The Status Code:</B></H3><BR>

#cfhttp.statuscode#<BR>

<H3><B>The Raw Header:</B></H3><BR>

#cfhttp.header#<BR>



</cfoutput>



<H3><B>Output the Response Headers:</B></H3><BR>

<HR>



<cfloop collection = #cfhttp.responseHeader# item = "httpHeader">

  <cfset value = cfhttp.responseHeader[httpHeader]>

  <cfif IsSimpleValue(value)>

    <cfoutput>

      #httpHeader# : #value#<BR>

    </cfoutput>

  <cfelse>

    <cfloop index = "counter" from = 1 to = #ArrayLen(value)#>

      <cfoutput>

        #httpHeader# : #value[counter]#<BR> 

      </cfoutput>

    </cfloop>

  </cfif>

</cfloop>



</body>

</html>