HTTPProvider Object

The HTTPProvider object is a general purpose HTTP protocol object. It can be used from VTOM scripts for low level HTTP operations. The HTTPProvider was introduced as an alternative to simplified HTTP-related methods such as GetURL method of the main Application object which is limited in the number of customizable HTTP parameters. Using HTTPProvider you can initialize specific HTTP provider properties (e.g. Proxy, ProxyPort, Username, Password etc.) and execute GET, POST and HEAD HTTP method requests. See the W3C HTTP Specification fordetailed information on many of the properties listed here.

Properties

Agent (OleVariant)

Sets/returns the identification of the client which initiates a request. You can use this property to identify yourself as a client type or emulate a browser.

AuthorizationRequest (OleVariant; readonly)

Returns The WWW-Authenticate response-header field. This field is included in 401 (unauthorized) response messages. The field value consists of at least one challenge that indicates the authentication scheme(s) and parameters applicable to the Request-URI.

ContentLength (Integer; readonly)

Returns the length of the received content stream.

ContentType (OleVariant; readonly)

Returns the MIME content type of the received content stream.

ContentTypePost (OleVariant)

Sets/returns the Content-Type entity-header field indicates the media type of the Entity-Body sent to the recipient or, in the case of the HEAD method, the media type that would have been sent had the request been a GET.

Cookie (OleVariant)

Sets/returns the Cookie header element. You can use this property to send a set of client cookies to the server along the HTTP request.

The following example would send cookies named Customer and Cust_ID to a ColdFusion application.

function Main ()
{
var app = Application;
var httpPro = app.HTTPProvider;
httpPro.URL    = "http://127.0.0.1/GetCustomerRegistration.cfm"; 
httpPro.Cookie = `Customer="John_Doe"; $Path="/myapp";Cust_ID="4567"; 
$Path="/myapp"';  
httpPro.Get(); 
}               

DocName (OleVariant; readonly)

Returns the document name segment from the requested URL.

LastResponse (OleVariant; readonly)

Returns the most recent response content block when content stream is sent from the server in mutliple responses.

Location (OleVariant; readonly)

Returns the response-header field which defines the exact location of the resource that was identified by the Request-URI. During redirection this is the final URL of the resource returned.

ModifiedSince (OleVariant)

Sets/returns the Modified-Since request-header field.

MultiThreaded (WordBool)

Sets/returns whether the HTTPProvider uses mutlithreading when executing HTTP requests.

NoCache (WordBool)

Sets/returns the NoCache request-header field.

Password (OleVariant)

Sets/returns the web server access password.

Proxy (OleVariant)

Sets/returns the proxy server. You can use the GetApplicationSetting() function with the following setting constants: (50 and 51) to extract the users' proxy server settings:

var app = Application; 
var httpPro = app.HTTPProvider;
httpPro.Proxy      = app.GetApplicationSetting(50); 
httpPro.ProxyPort  = app.GetApplicationSetting(51);              

ProxyPort (OleVariant)

Sets/returns the proxy server port.

ProxyUsername (OleVariant)

Sets/returns the proxy server username.

ProxyPassword (OleVariant)

Sets/returns the proxy server password.

RcvdCount (Integer; readonly)

Returns the size of the content stream received from the server. This property can be used to display progress during asynchronous GET operations. The ContentLength property value (extracted from the document header) can be used to get the total length of the incoming content stream.

ReasonPhrase (OleVariant; readonly)

Returns the Reason-Phrase element which is intended to give a short textual description of the Status-Code. The Status-Code is intended for use by automata and the Reason-Phrase is intended for the human user.

The following are some of the Status-Code, Reason-Phrase pairs:

200 - OK
201 - Created
202 - Accepted
204 - No Content
301 - Moved Permanently
302 - Moved Temporarily
304 - Not Modified
400 - Bad Request
401 - Unauthorized 
403 - Forbidden 
404 - Not Found
500 - Internal Server Error 
501 - Not Implemented 
502 - Bad Gateway
503 - Service Unavailable

ReceivedHeaderAsString (OleVariant; readonly)

Returns the header elements as a string. The header elements are separated on different lines.

ReceivedStreamAsString (OleVariant)

Sets/returns the RECEIVED stream as a string. Use SaveReceivedStreamToFile to save the received stream into a file.

Reference (OleVariant)

Sets/returns the Referer request-header field. This field allows the client to specify, for the server's benefit, the address (URI) of the resource from which the Request-URI was obtained. This allows a server to generate lists of back-links to resources for interest, logging, optimized caching, etc. It also allows obsolete or mistyped links to be traced for maintenance. The Referer field must not be sent if the Request-URI was obtained from a source that does not have its own URI, such as input from the user keyboard.

Sender (OleVariant)

Sets/returns the sender parameter.

SendStreamAsString (OleVariant)

Sets/returns the SEND stream as a string.

SentCount (Integer; readonly)

Returns the size of the content stream sent to the server. This property can be used to display progress during asynchronous POST operations.

State (TAllaireHTTPProviderState; readonly)

Returns the state of the HTTPProvider object. The enumerated state values are:

0 - httpReady 
1 - httpNotConnected
2 - httpConnected (browse)
3 - httpDnsLookup    
4 - httpDnsLookupDone
5 - httpWaitingHeader
6 - httpWaitingBody
7 - httpAborting 

StatusCode (Integer; readonly)

Returns the HTTP request Status-Code element. This is a 3-digit integer result code of the attempt to understand and satisfy the request.

URL (OleVariant)

Sets/returns the URL location of the resource on which an HTTP method is to be applied.

Username (OleVariant)

Sets/returns the web server access username.

Methods

Abort

procedure Abort;

Abort the current HTTP operation.

Get

procedure Get;

Performs an HTTP GET method request. Uses the appropriate properties of the HTTPProvider object to set HTTP request parameters such as proxy server settings, username and password etc.

The following example demostrates a simple GET method against the Allaire home page:

// Message box constants
var hsOKInfo = 64;
function Main () {

var app = Application;
var httpPro = app.HTTPProvider;

httpPro.URL        = "http://www.allaire.com";

httpPro.Get();

app.MessageBox( httpPro.ReceivedHeaderAsString ,"Received HTTP Header", 
hsOKInfo);
app.MessageBox(
    "URL='"                    + httpPro.URL + "`\n" +
    "ProxyUsername='"   + httpPro.Username + "`\n" +
    "ProxyPassword='"   + httpPro.Password + "`\n" +
    "Proxy='"           + httpPro.Proxy + "`\n" +
    "ProxyPort='"       + httpPro.Proxyport + "`\n" +
    "ProxyUsername='"   + httpPro.ProxyUsername + "`\n" +
    "ProxyPassword='"   + httpPro.ProxyPassword + "`\n" +
    "Sender='"          + httpPro.Sender + "`\n" +
    "Agent='"           + httpPro.Agent + "`\n" +
    "Reference='"       + httpPro.Reference + "`\n" +
    "NoCache='"         + httpPro.NoCache + "`\n" +
    "ModifiedSince='"   + httpPro.ModifiedSince + "`\n" +
    "Cookie='"          + httpPro.Cookie + "`\n" +
    "ContentTypePost='" + httpPro.ContentTypePost + "`\n" +
    "MultiThreaded='"   + httpPro.MultiThreaded + "`\n"+
    "State='"           + httpPro.State + "`\n"+
    "ContentLength='"   + httpPro.ContentLength + "`\n"+
    "ContentType='"     + httpPro.ContentType + "`\n"+
    "RcvdCount='"       + httpPro.RcvdCount + "`\n"+
    "SentCount='"       + httpPro.SentCount + "`\n"+
    "StatusCode='"      + httpPro.StatusCode + "`\n"+
    "ReasonPhrase='"    + httpPro.ReasonPhrase + "`\n"+
    "AuthorizationRequest='"   + httpPro.AuthorizationRequest + "`\n"+
    "DocName='"         + httpPro.DocName + "`\n"+
    "Location='"        + httpPro.Location + "`\n"
    ,"HTTP Provider Diagnostics", hsOKInfo);

var sOutput = httpPro.ReceivedStreamAsString;
app.activeDocument.Text = sOutput;
}                          

GetAsync

procedure GetAsync;

Performs an HTTP GET method request asynchronously.

Head

procedure Head;

Performs an HTTP HEAD method request.

HeadAsync

procedure HeadAsync;

Performs an HTTP HEAD method request asynchronously.

Post

procedure Post;

Performs an HTTP POST method request. The following example illustrates a POST method by which three FORM variables are submitted to a ColdFusion page.

function Main () {

var app = Application; 
var httpPro = app.HTTPProvider;

httpPro.URL        = "http://127.0.0.1/httptest.cfm";

var CustomerID  = "John Doe"; 
var ProductID   = "3456"; 
var DateSold    = "10/10/99";

var PostStream =                    'Customer_ID='     + httpPro.URLEncode( CustomerID ) +
                     '&ProductNumber='   + httpPro.URLEncode( ProductID ) +
                    `&SaleDate='        + httpPro.URLEncode( DateSold );  

httpPro.SendStreamAsString = PostStream; httpPro.Post(); 

var sOutput = httpPro.ReceivedStreamAsString;
app.activeDocument.Text = sOutput; 

}

PostAsync

procedure PostAsync;

Performs an HTTP POST method request asynchronously.

SaveReceivedStreamToFile

procedure SaveReceivedStreamToFile(FilePath: OleVariant; bOverwrite: wordbool): OleVariant;

Saves the received stream into a file and returns the error message if an error occured. The bOverwrite parameter specifies whether to overwrite any existing files or return an error.

The following are predefined error messages. Check for the error strings to detect these error cases:

'File already exits.' - returned when file specified in FilePath exists and bOverwrite is set to false.

'Path does not exist.' - Returned when the path specified in FilePath does not exist.

The following scripts illustrates a download of a ZIP file using SaveReceivedStreamToFile :

function Main () {
    var hsOKInfo = 64;     
    var app = Application;
    var httpPro = app.HTTPProvider;
    
    httpPro.URL      = "http://127.0.0.1/test.zip";
    httpPro.Get(); 
    
    var bOverwrite = false;
    var sErrorMsg = 
    
    httpPro.SaveReceivedStreamToFile("d:\\downloads\\test.zip",
        bOverwrite );
    if ( sErrorMsg != "" )     
    {
        app.MessageBox( "A error occured :" + sErrorMsg ,"HTTPProvider
        Error", hsOKInfo); 
    }

}

URLEncode

function URLEncode(const wsValue: WideString): WideString;

Returnes a URLEncoded form of the wsValue string. This function is usefull when populating URL or FORM data.