WinHttp.WinHttpRequest.5.1
Last Updated April 2008
I got tired of waiting for MSDN as a reference to using the WinHttp ActiveXObject, so I'm transcribing things here. Visit MSDN's WinHttpRequest Object Reference for the original content.
Methods of WinHttp
  • Abort: Aborts a WinHTTP Send method.
  • GetAllResponseHeaders: Retrieves all HTTP response headers.
  • GetResponseHeader: Retrieves the HTTP response headers.
  • Open: Opens an HTTP connection to an HTTP resource.
  • Send: Sends an HTTP request to an HTTP server.
  • SetAutoLogonPolicy: Sets the current Automatic Logon Policy.
  • SetClientCertificate: Selects a client certificate to send to a Secure Hypertext Transfer Protocol (HTTPS) server.
  • SetCredentials: Sets credentials to be used with an HTTP server—either an origin or a proxy server.
  • SetProxy: Sets proxy server information.
  • SetRequestHeader: Adds, changes, or deletes an HTTP request header.
  • SetTimeouts: Specifies, in milliseconds, the individual time-out components of a send/receive operation.
  • WaitForResponse: Specifies the wait time, in seconds, for an asynchronous Send method to complete, with optional time-out value.

Properties of WinHttp
  • Option: Sets or retrieves a WinHTTP option value.
  • ResponseBody: Retrieves the response entity body as an array of unsigned bytes.
  • ResponseStream: Retrieves the response entity body as an IStream.
  • ResponseText: Retrieves the response entity body as a string.
  • Status: Retrieves the HTTP status code from the last response.
  • StatusText: Retrieves HTTP status text.

Events of WinHttp
  • OnError: Occurs when there is a run-time error in the application.
  • OnResponseDataAvailable: Occurs when data is available from the response.
  • OnResponseFinished: Occurs when the response data is complete.
  • OnResponseStart: Occurs when the response data starts to be received.

GetResponseHeader Method

  • bstrHeader (required): A value of type string that specifies the case-insensitive header name.
  • Return Value: This method returns the value of the HTTP response header named in bstrHeader.

Invoke this method only after the Send method has been called.
// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Initialize an HTTP request.
WinHttpReq.Open("GET",
                "http://www.microsoft.com",
                 false);

// Send the HTTP request.
WinHttpReq.Send();

// Display the date header.
WScript.Echo( WinHttpReq.GetResponseHeader("Date") );

Open Method

  • bstrMethod (required): A value of type string that specifies the HTTP verb used for the Open method, such as "GET" or "PUT". Always use uppercase as some servers ignore lowercase HTTP verbs.
  • bstrUrl (required): A value of type string that contains the name of the resource. This must be an absolute URL.
  • varAsync (default=false): A value of type Boolean that specifies whether to open in asynchronous mode. True=Opens the HTTP connection in asynchronous mode.
// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Initialize an HTTP request.
WinHttpReq.Open("GET", "http://www.example.com", false);

// Send the HTTP request.
WinHttpReq.Send();

// Display the response text.
WScript.Echo(WinHttpReq.ResponseText);

Send Method

  • varBody (optional): Data to be sent to the server.
The request to be sent was defined in a prior call to the Open method. The calling application can provide data to be sent to the server through the varBody parameter. If the HTTP verb of the object's Open is "GET", this method sends the request without varBody, even if it is provided by the calling application.
// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Initialize an HTTP request.
WinHttpReq.Open("PUT", "http://postserver/newdoc.htm", false);

// Post data to the HTTP server.
WinHttpReq.Send("Post data");

SetTimeouts Method

  • ResolveTimeout: Value of type Integer integer. Time-out value applied when resolving a host name (such as www.example.com) to an IP address (such as 192.168.131.199), in milliseconds. The default value is zero, meaning no time-out (infinite). If DNS timeout is specified using NAME_RESOLUTION_TIMEOUT, there is an overhead of one thread per request.
  • ConnectTimeout: Value of type Integer integer. Time-out value applied when establishing a communication socket with the target server, in milliseconds. The default value is 60,000 (60 seconds).
  • SendTimeout: Value of type Integer integer. Time-out value applied when sending an individual packet of request data on the communication socket to the target server, in milliseconds. A large request sent to an HTTP server are normally be broken up into multiple packets; the send time-out applies to sending each packet individually. The default value is 30,000 (30 seconds).
  • ReceiveTimeout: Value of type Integer integer. Time-out value applied when receiving a packet of response data from the target server, in milliseconds. Large responses are be broken up into multiple packets; the receive time-out applies to fetching each packet of data off the socket. The default value is 30,000 (30 seconds).

All parameters are required. A value of 0 or -1 sets a time-out to wait infinitely. A value greater than 0 sets the time-out value in milliseconds. For example, 30,000 would set the time-out to 30 seconds. All negative values other than -1 cause this method to fail.

Time-out values are applied at the Winsock layer.
// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Set 30 second time-outs. If time-outs are set, they must
// be set before open.
WinHttpReq.SetTimeouts(30000, 30000, 30000, 30000);

// Initialize an HTTP request.
WinHttpReq.Open("GET", "http://www.microsoft.com", false);

// Send the HTTP request.
WinHttpReq.Send();

WaitForResponse Method

  • Timeout (optional): Time-out value, in seconds. Default time-out is infinite. To explicitly set time-out to infinite, use the value -1.
  • Return Value: True=A response has been received. False=A time-out error occurred.

The WaitForResponse method waits for an asynchronous Send method to complete, with optional time-out value, in seconds.

This method suspends execution while waiting for a response to an asynchronous request. This method should be called after a Send. Calling applications can specify an optional Timeout value, in seconds. If this method times out, the request is not aborted. This way, the calling application can continue to wait for the request, if desired, in a subsequent call to this method.

Calling this property after a synchronous Send method returns immediately and has no effect.

// Instantiate a WinHttpRequest object.
var WinHttpReq = new ActiveXObject("WinHttp.WinHttpRequest.5.1");

// Initialize an HTTP request.
WinHttpReq.Open("GET", "http://www.example.com", true);

// Send the HTTP request.
WinHttpReq.Send();

// Wait for the response.
WinHttpReq.WaitForResponse();

// Display the response text.
WScript.Echo( WinHttpReq.ResponseText);