# CFHTTP

The CFHTTP tag allows you to execute POST and GET operations on files. Using CFHTTP, you can execute standard GET operations as well as create a query object from a text file. POST operations allow you to 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/No"
        PROXYSERVER="hostname"
        PROXYPORT="port_number"
        USERAGENT="user_agent"
        THROWONERROR="Yes/No"
        REDIRECT="Yes/No"
        TIMEOUT="timeout_period">
    </CFHTTP>

Note | Terminate CFHTTP POST operations with </CFHTTP>. Termination is not required with CFHTTP GET operations.

#### URL

Required. Full URL of the host name or IP address of the server on which the file resides.

#### PORT

Optional. The port number on the server from which the object is being 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.

#### 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 when a query is to be constructed from a file.

#### COLUMNS

Optional. The column names for a query. If no column names are specified, the query returns all rows in the query except for the first row. To get all the rows in a query, you must specify column names.

#### 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 present 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. Valid characters 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 quotation mark, it should be escaped as """". If there is no text qualifier in the file, specify a blank space as " ". Default is the quote mark ( " ).

#### RESOLVEURL

Optional. Yes or No. Default is No. For GET and POST operations, when Yes, any page reference returned into the FileContent internal variable will have its internal URLs fully resolved, including port number, so that links remain intact. The following HTML tags, which can contain links, will be 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 being 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 error code and its associated message can be viewed in the variable CFHTTP.StatusCode. The default is NO. See the Usage section for more information.

#### 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. Timeout period in seconds. By default, the ColdFusion server processes requests asynchronously; that is, the ColdFusion server uses the timeout set on the URL in the browser, the timeout set in the ColdFusion Administrator, and the timeout set in the tag to determine the timeout period for the CFHTTP request.

When a URL timeout is specified in the browser, this timeout setting will take precedence over the ColdFusion Administrator timeout. The ColdFusion server then takes the lesser of the URL timeout and the timeout passed in the TIMEOUT attribute so that the request will always time out before or at the same time as the page times out. Likewise, 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 processes requests synchronously; thus, ColdFusion waits indefinitely for the CFHTTP request to process.

Note that 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. Please refer to Administering ColdFusion Serverfor more information about ColdFusion settings.

### Usage

Note the following:

- HTTP GET -- A user can specify a URL that points to a text or binary file. The file will be downloaded and its contents stored in a CF variable or in a file so that the user can manipulate the data. The internal variable FileContent is available for text and MIME file types. The MimeType variable is available for all file manipulations. In addition, Header and ResponseHeader allow you to 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 a CFML structure; the other variables are strings. See the table at the end of this section for a summary of variables returned by CFHTTP.

- GET file into a query -- 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. Although risky, text qualification may be omitted. The file will be parsed and an appropriate query 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 either entering an invalid column name or using an invalid column name that was specified in the original file. If such an illegal filename is encountered, the illegal characters are stripped. Such 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 specifying 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 and this can be used in a CFOUTPUT. If PATH and FILE are specified, the data returned from the server is saved to the specified location.
- Authentication -- CFHTTP supports Windows NT Basic Authentication for both GET and POST operations. However, Basic Authentication will not work if your Web server has enabled Windows NT Challenge/Response (Microsoft IIS).
- Encryption -- CFHTTP is capable of using Secure Sockets Layer (SSL) for negotiating secured transactions over the wire.
- CFHTTP.StatusCode-- CFHTTP throws an error and provides the CFHTTP.StatusCode variable for access to the HTTP error string associated with the error if the THROWONERROR attribute is set to YES. See the following table for all the variables returned by CFHTTP.

  CFHTTP Variables
  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, then the value may be accessed as a simple type. If there is more than one instance, then 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 YES.

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