HTTPProvider Object

The HTTPProvider object is a general purpose HTTP protocol object. You can use it in VTOM scripts for low-level HTTP operations. The HTTPProvider object is an alternative to simplified HTTP-related methods, such as the GetURL method of the main Application object, which has a limited number of customizable HTTP parameters. Using the HTTPProvider object, you can initialize specific HTTP provider properties (such as Proxy, ProxyPort, Username, Password), and execute GET, POST, and HEAD HTTP method requests. For detailed information on many of the properties in this section, see http://www.w3.org/Protocols/ .

Properties

Agent

Syntax

Agent: OleVariant  

Description

Sets and gets the identification of the client that initiates a request. Use this property to identify yourself as a client type or emulate a browser.

AuthorizationRequest

Syntax

AuthorizationRequest: OleVariant (read-only)  

Description

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

ContentLength

Syntax

ContentLength: Integer (read-only) 

Description

Specifies the length of the received content stream.

ContentType

Syntax

ContentType: OleVariant (read-only) 

Description

Specifies the MIME content type of the received content stream.

ContentTypePost

Syntax

ContentTypePost: OleVariant 

Description

Sets and gets the Content-Type entity-header field, which indicates the media type of the Entity-Body sent to the recipient. For the HEAD method, indicates the media type that is sent if the request is a GET.

Cookie

Syntax

Cookie: OleVariant 

Description

Sets and gets the Cookie header element. Use this property to send a set of client cookies to the server along the HTTP request.

Example

Sample cookie script

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

Syntax

DocName: OleVariant (read-only)  

Description

The document name segment from the requested URL.

LastResponse

Syntax

LastResponse: OleVariant (read-only)  

Description

The most recent response content block when content stream is sent from the server in multiple responses.

Location

Syntax

Location: OleVariant (read-only) 

Description

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

Syntax

ModifiedSince: OleVariant 

Description

Sets and gets the Modified-Since request-header field.

MultiThreaded

Syntax

MultiThreaded: WordBool  

Description

Boolean. Sets and gets whether the HTTPProvider uses multithreading when executing HTTP requests.

NoCache

Syntax

NoCache: WordBool  

Description

Boolean. Sets and gets the NoCache request-header field.

Password

Syntax

Password: OleVariant  

Description

Sets and gets the Web server access password.

Proxy

Syntax

Proxy: OleVariant  

Description

Sets and gets the proxy server. 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

Syntax

ProxyPort: OleVariant  

Description

Sets/gets the proxy server port.

ProxyUsername

Syntax

ProxyUsername: OleVariant 

Description

Sets/gets the proxy server username.

ProxyPassword

Syntax

ProxyPassword: OleVariant 

Description

Sets/gets the proxy server password.

RcvdCount

Syntax

RcvdCount: Integer (read-only) 

Description

The size of the content stream received from the server. Use this property to display progress during asynchronous GET operations. Use the ContentLength property value extracted from the document header to get the total length of the incoming content stream.

ReasonPhrase

Syntax

ReasonPhrase: OleVariant (read-only)  

Description

The Reason-Phrase element provides a short textual description of the Status-Code. The Status-Code is used by automata and the Reason-Phrase is 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

Syntax

ReceivedHeaderAsString: OleVariant (read-only) 

Description

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

ReceivedStreamAsString

Syntax

ReceivedStreamAsString: OleVariant 

Description

Sets and gets the RECEIVED stream as a string. Use SaveReceivedStreamToFile to save the received stream into a file.

Reference

Syntax

Reference: OleVariant  

Description

Sets and gets 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, and so on. 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's keyboard.

Sender

Syntax

Sender: OleVariant 

Description

Sets and gets the sender parameter.

SendStreamAsString

Syntax

SendStreamAsString: OleVariant 

Description

Sets and gets the SEND stream as a string.

SentCount

Syntax

SentCount: Integer (readonly)  

Description

The size of the content stream sent to the server. Use this property to display progress during asynchronous POST operations.

State

Syntax

State: TAllaireHTTPProviderState (read-only) 

Description

The state of the HTTPProvider object.

The enumerated state values are as follows:

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

StatusCode

Syntax

StatusCode: Integer (read-only)  

Description

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

URL

Syntax

URL: OleVariant 

Description

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

Username

Syntax

Username: OleVariant  

Description

Sets and gets the Web server access username.

Methods

Abort

Syntax

Abort(); 

Description

Aborts the current HTTP operation.

Get

Syntax

Get(); 

Description

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.

Example

Sample GET script

//*********************************************//
// This script demonstrates a simple GET method
// against the Macromedia home page. 
//*******************************************//
// Message box constants
var hsOKInfo = 64;
function Main () {

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

httpPro.URL        = "http://www.macromedia.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

Syntax

GetAsync(); 

Description

Performs an HTTP GET method request asynchronously.

Head

Syntax

Head(); 

Description

Performs an HTTP HEAD method request.

HeadAsync

Syntax

HeadAsync();  

Description

Performs an HTTP HEAD method request asynchronously.

Post

Syntax

Post(); 

Description

Performs an HTTP POST method request.

Example

Sample POST script

//*******************************************//
// This script 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

Syntax

PostAsync(); 

Description

Performs an HTTP POST method request asynchronously.

SaveReceivedStreamToFile

Syntax

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

Description

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

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

Example

Sample download script

//*******************************************//
// This script downloads 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

Syntax

URLEncode(const wsValue: WideString): WideString; 

Description

Returns a URLEncoded form of the wsValue string. Use this function when populating URL or FORM data.

Sample HTTPProvider script

//**********************************************//
// ActiveScripting example (JScript)
//**********************************************//
// This script contacts the site specified by the user URL,
// copies its source code and displays the page in the internal 
// browser of the application
//**********************************************//
function Main (){

  var sDocName; 
        var sSource;
  var sMessage;
with (Application){

   if (HTTPProvider.State == 0){
    // Set the URL property of HTTPProvider Object.
    HTTPProvider.URL = InputBox(VersionText, "Please Enter the URL.", "http://www.yahoo.com"); 
    // Perform HTTP Get Request  
    HTTPProvider.Get();
    sSource = '';
    if (HTTPProvider.ReasonPhrase == "OK") // Check if the requested URL can be displayed
       sSource = HTTPProvider.ReceivedStreamAsString;  //Save the page source into the string  
    else{
        sSource = '<font size="+2" color="#0000ff" >'  //If the page cannot be displayed, post error message and show a reason. 
        sSource =  sSource + 'The request could not be completed: <br><br><li>'
        sSource =  sSource + HTTPProvider.ReasonPhrase + '.</font></li>';
          }
    sMessage = "The source of the requested page has been copied successfully,\n";
    sMessage = sMessage + 'the page now will be displayed ';
    sMessage = sMessage + 'in the browse window of \n' + VersionText + '!';
    MessageBox (sMessage, VersionText, 0);
   }     
   else{ 
    sSource  = 'You are not connected to Internet properly, '; 
    sSource =  sSource + 'please check the connection and try again';
    }
MessageBox("Some images may not be downloaded properly!","Warning!",0);
  NewDocument (false);     // Initialize a new document. 
  ActiveDocument.InsertText(sSource, false); // Insert the received source code into new document.
  CurrentView = 2;  // Change to the browse mode.
  }  
}

Comments