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 for detailed information on many of the properties listed here.
Sets/gets 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.
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.
The length of the received content stream.
The MIME content type of the received content stream.
Sets/gets 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.
Sets/gets 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(); }
The document name segment from the requested URL.
The most recent response content block when content stream is sent from the server in multiple responses.
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.
Sets/gets the Modified-Since request-header field.
Sets/gets whether the HTTPProvider uses multithreading when executing HTTP requests.
Sets/gets the NoCache request-header field.
Sets/gets the Web server access password.
Sets/gets 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);
Sets/gets the proxy server port.
Sets/gets the proxy server username.
Sets/gets the proxy server password.
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.
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
The header elements as a string. The header elements are separated on different lines.
Sets/gets the RECEIVED stream as a string. Use SaveReceivedStreamToFile to save the received stream into a file.
Sets/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 keyboard.
Sets/gets the sender parameter.
Sets/gets the SEND stream as a string.
The size of the content stream sent to the server. This property can be used to display progress during asynchronous POST operations.
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
The HTTP request Status-Code element. This is a 3-digit integer result code of the attempt to understand and satisfy the request.
Sets/gets the URL location of the resource on which an HTTP method is to be applied.
Sets/gets the Web server access username.
procedure Abort()
Abort the current HTTP operation.
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 demonstrates 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; }
procedure GetAsync()
Performs an HTTP GET method request asynchronously.
procedure Head()
Performs an HTTP HEAD method request.
procedure HeadAsync()
Performs an HTTP HEAD method request asynchronously.
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; }
procedure PostAsync()
Performs an HTTP POST method request asynchronously.
procedure SaveReceivedStreamToFile(FilePath: OleVariant; bOverwrite: wordbool): OleVariant
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 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); }
}
function URLEncode(const wsValue: WideString): WideString
Returns a URLEncoded form of the wsValue string. This function is useful when populating URL or FORM data.