CF.http

Description

Executes HTTP POST and GET operations on files. (POST operations upload MIME file types to a server, or post cookie, formfield, URL, file, or CGI variables directly to a server.)

Return value

Returns an object containing properties that you reference to access data.

Syntax

CF.http 
    ({ 
            method:"get or post", 
        url:"URL", 
        username:"username", 
        password:"password", 
        resolveurl:"yes or no", 
        params:arrayvar, 
        path:"path", 
        file:"filename" 
    })

Arguments

Arguments

Req/Opt

Description

method

Required

One of two arguments:

  • get: downloads a text or binary file or creates a query from the contents of a text file.

  • post: sends information to the server page or CGI program for processing. Requires the params argument.

url

Required

The absolute URL of the host name or IP address of the server on which the file resides. The URL must include the protocol (http or https) and host name.

username

Optional

When required by a server, a username.

password

Optional

When required by a server, a password.

resolveurl

Optional

For Get and Post methods.

  • Yes or No. Default is No.

For GET and POST operations, if Yes, the page reference that is returned into the Filecontent property 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

params

Optional

HTTP parameters passed as an array of objects. Supports the following parameter types:

  • name

  • type

  • value

CF.http params are passed as an array of objects. The params argument is required for POST operations.

path

Optional

The path to the directory in which to store files. When using the path argument, the file argument is required.

file

Optional

Name of the file that is accessed. For GET operations, defaults to the name specified in the url argument. Enter path information in the path argument. This argument is required if you are using the path argument.

Usage

You can write the CF.http function using named arguments or positional arguments. You can invoke all supported arguments using the named argument style, as follows:

CF.http({method:"method", url:"URL", username:"username", password:"password", 
    resolveurl:"yes or no", params:arrayvar,  
    path:"path", file:"filename"});
Note: The named argument style uses curly braces {} to surround the function arguments.

Positional arguments let you use a shorthand coding style. However, not all arguments are supported for the positional argument style. Use the following syntax to code the CF.http function using positional arguments:

CF.http(url); 
CF.http(method, url); 
CF.http(method, url, username, password); 
CF.http(method, url, params, username, password);
Note: Do not use curly braces {} with positional arguments.

The following parameters can only be passed as an array of objects in the params argument in the CF.http function:

Parameter

Description

name

The variable name for data that is passed

type

The transaction type:

  • URL

  • FormField

  • Cookie

  • CGI

  • File

value

Value of URL, FormField, Cookie, File, or CGI variables that are passed

The CF.http function returns data as a set of object properties, as described in the following table:

Property

Description

Text

A Boolean value that indicates whether the specified URL location contains text data.

Charset

The charset used by the document specified in the URL.

HTTP servers normally provide this information, or the charset is specified in the charset parameter of the Content-Type header field of the HTTP protocol. For example, the following HTTP header announces that the character encoding is EUC-JP:

Content-Type: text/html; charset=EUC-JP

Header

Raw response header. For example:

HTTP/1.1 200 OK

Date: Mon, 04 Mar 2002 17:27:44 GMT

Server: Apache/1.3.22 (Unix) mod_perl/1.26

Set-Cookie: MM_cookie=207.22.48.162.4731015262864476; path=/; expires=Wed, 03-Mar-04 17:27:44 GMT;

domain=adobe.com

Connection: close

Content-Type: text/html

Filecontent

File contents, for text and MIME files.

Mimetype

MIME type. Examples of MIME types include text/html, image/png, image/gif, video/mpeg, text/css, and audio/basic.

responseHeader

Response header. If there is only one header key, its value can be accessed as simple type. If there are multiple header keys, the values are put in an array in a responseHeader structure.

Statuscode

HTTP error code and associated error string. Common HTTP status codes returned in the response header include:

400: Bad Request

401: Unauthorized

403: Forbidden

404: Not Found

405: Method Not Allowed

You access these attributes using the get function:

function basicGet() 
{ 
url = "http://localhost:8100/"; 
     
// Invoke with just the url. This is an HTTP GET. 
result = CF.http(url); 
return result.get("Filecontent"); 
}
Note: For more information on using server-side ActionScript, see Using Server-Side ActionScript in the Developing ColdFusion Applications.

Example

The following examples show a number of the ways to use the CF.http function:

function postWithNamedArgs() 
{ 
    // Set up the array of Post parameters. 
    params = new Array(); 
    params[1] = {name:"arg1", type:"FormField", value:"value1"}; 
    params[2] = {name:"arg2", type:"URL", value:"value2"}; 
    params[3] = {name:"arg3", type:"CGI", value:"value3"}; 
 
    url = "http://localhost:8100/"; 
 
    path = application.getContext("/").getRealPath("/"); 
    file = "foo.txt"; 
 
    result = CF.http({method:"post", url:url, username:"karl", password:"salsa", 
    resolveurl:true, params:params, path:path, file:file}); 
 
    if (result) 
        return result.get("Statuscode"); 
    return null; 
} 
 
// Example of a basic HTTP GET operation 
// Shows that HTTP GET is the default 
function basicGet() 
{ 
    url = "http://localhost:8100/"; 
 
    // Invoke with just the url. This is an HTTP GET. 
    result = CF.http(url); 
    return result.get("Filecontent"); 
} 
 
// Example showing simple array created to pass params arguments 
function postWithParams() 
{ 
    // Set up the array of Post parameters. These are just like cfhttpparam tags. 
    params = new Array(); 
    params[1] = {name:"arg2", type:"URL", value:"value2"}; 
 
    url = "http://localhost:8100/"; 
 
    // Invoke with the method, url, and params 
    result = CF.http("post", url, params); 
    return result.get("Filecontent"); 
} 
 
// Example with username and params arguments 
function postWithParamsAndUser() 
{ 
    // Set up the array of Post parameters. These are just like cfhttpparam tags. 
    params = new Array(); 
    params[1] = {name:"arg2", type:"URL", value:"value2"}; 
 
    url = "http://localhost:8100/"; 
 
    // Invoke with the method, url, params, username, and password 
    result = CF.http("post", url, params, "karl", "salsa"); 
    return result.get("Filecontent"); 
}