Class wwHTTP - West Wind Web Connection

Class wwHTTP

This class can be used to make HTTP requests to Web servers, to retrieve data. You can also send data to the server using POST or PUT operations. All HTTP verbs are supported.

At it's simplest you can retrieve HTTP content like this:

loHttp = CREATEOBJECT("wwHttp")
lcHtml = loHttp.Get("https://markdownmonster.west-wind.com")

Content retrieved can also be saved to a file directly using the lcOutputName parameter of all the retrieval routines (.Get(), .Post(), .Put(), .Delete()):

loHttp = CREATEOBJECT('wwhttp')
loHttp.Get("https://west-wind.com/files/wwclient.zip","c:\temp\wwclient.zip")

You can also POST data to the server using the .AddPostKey() method which lets you post either individual form values or a complete POST buffer to the server.

POST some data to a server using HTML style form vars:

oHTTP=CREATEOBJECT("wwHTTP")

oHTTP.AddPostKey("FirstName","Rick")
oHTTP.AddPostKey("LastName","Strahl")
oHTTP.AddPostKey("Company","West Wind Technologies")

*** Optionally add custom headers
oHTTP.AppendHeader("cache-control","private")
oHttp.AppendHeader("Custom-Header","Custom value")

lcHTML = oHTTP.Post("http://www.west-wind.com/wconnect/TestPage.wwd")

ShowHTML( lcHTML )

alternately you can post an entire buffer of data to the server. This is common when you sent JSON or XML documents:

loHttp = CREATEOBJECT("wwHttp")

*** Specify that we want to post raw data and a custom content type
loHttp.cContentType = "application/json"  && Content type of the data posted
* loHttp.cHttpVerb = "POST"       && Use for anything but POST/GET verbs (PUT/DELETE/HEAD/OPTIONS)

*** Load up the XML data any way you need
lcJson = FILETOSTR("Data.json")

*** New simpler syntax for raw buffers
lcJsonResult = loHttp.Post("http://www.west-wind.com/JsonService.xsvc", lcJson)

*** Alternately you can also explicitly use `.AddPostKey()` (same behavior)
loHttp.AddPostKey(lcJson)
lcJsonResult = loHttp.Post("http://www.west-wind.com/JsonService.xsvc")

* do something with the JSON data

The wwHttp class provides HTTP access via WinInet to Visual FoxPro application. This class provides tight control over most aspects of the HTTP protocol including HTTP headers (client and server side), timeouts, proxy support, authentication, SSL connectivity as well as providing support for asynchronous HTTP operation.

For a variety of examples of using this class please see:

Access HTTP content over the Web

Based on: Relation
Stored in: wwHTTP.prg

Relation
wwHttp

Remarks

External Dependencies
wwIPstuff.dll
zLib.dll

Class Members

Member		Description
	OnHttpBufferUpdate	The OnHttpBufferUpdate() method is called whenever a buffer is downloaded from the server and allows you to display download status information for large file downloads. It's also useful for freeing up the UI to avoid blocking HTTP calls that freeze the FoxPro UI when requests take too long.
	OnHttpPostConnect	This event fires after the Http connection has been established and can be useful to set specific WinInet options on the HTTP connection.
	AddBasicAuthenticationHeader	Adds a Basic Authentication `Authorize` header with properly encoded scheme and encoded username and password to the Http headers of the request. o.AddBasicAuthenticationHeader(lcUsername, lcPassword)
	AddHeader	Allows you to add HTTP headers to the HTTP request sent to the server. Headers can be of the standard HTTP header kind like Content-encoding or Cache, or custom headers specific to your application. o.AddHeader(lcHeader,lcValue)
	AddPostFile	A specific version of `AddPostKey()` designed for File or Data uploads for multi-part HTTP forms. o.AddPostFile(tcKey, tcValue, tlIsFile, tcContentType, tcExtraHeaders)
	AddPostKey	Set POST data to send on a POST or PUT request. o.AddPostKey(tcKey, tcValue)
	Delete	Uses an HTTP `DELETE` operation to retrieve Web content from a URL. o.Delete(lcUrl, lcUserName, lcPassword, lcOutputFile)
	Get	Uses an HTTP `GET` operation to retrieve Web content from a URL. `GET` operations pass only the URL and no content body data and expect back an HTTP response. o.Get(lcUrl, lcUserName, lcPassword, lcOutputFile)
	GetCertificates	Retrieves a list of certificates that are installed on the local machine as a collection. o.GetCertificates(lcStoreName, lcLocation)
	GetHttpHeader	Retrieves an HTTP once the Response has been returned. Requires that a successfull call to HttpGet or HttpGetEx was made that returns a header in cHttpHeaders. o.wwHTTP.GetHttpHeader(lcHeader)
	GetMessageFromResultCode	Returns the HTTP message for a given HTTP Result Code. o.GetMessageFromResultCode(lcResultCode)
	GetSystemErrorMsg	Returns a WinInet or Win32 API error message. o.getsystemerrormsg(lnErrorNo, llAPI)
	HttpCancelDownload	Cancels a download if OnHttpBufferUpdate are hooked up to do incremental URL downloads. When called cancels the current download. o.httpcanceldownload()
	HttpClose	Closes an HTTP Session opened with HTTPConnect(). This method is automatically called during DESTROY. o.httpclose()
	HttpConnect	This low level HTTP method initiates a low level HTTP request for use with HTTPGetEx by establishing an IP Session and connecting to a target server. The main purpose of this method is to specify the server name and the security options when connecting. o.httpconnect(lcServer, lcUsername, lcPassword, llHTTPS)
	HttpGetEx	This low level method is the full featured HTTP access method that provides full support for the HTTP protocol including POST data, Basic Authentication and HTTPS protocol support. Requires `HTTPConnect()` to open a connection first and HTTPClose() to shut down. o.HTTPGetEx(tcPage, @tcBuffer, @tnBufferSize, tcHeaders, tcFileName)
	HttpGetHeader	Retrieves just the HTTP header from a URL. Useful for retrieving information about a request prior to actually downloading the full URL. You can spy the content length from the header for example. o.httpgetheader(tcPage, tcHeaders, tnHeaderSize)
	HttpPing	Use this method to ping a Web site to check whether a valid Internet connection can be made. o.HTTPPing(lnTimeout,lcUrl)
	InternetCrackUrl	This method breaks down an incoming URL into its component pieces. loUrl = o.InternetCrackUrl(lcUrl)
	Post	Uses an HTTP `POST` operation to post content to the Web server and to retrieve Web content from a URL. You can pass in a URL and the raw Post data to send. Make sure to set `.cContentType` if using non-Html form data. o.Post(lcUrl, lcPostData, lcOutputFile)
	Put	Uses an HTTP `PUT` operation to post content to the server and to retrieve Web content from a URL. o.Put(lcUrl, lcUserName, lcPassword, lcOutputFile)
	Send	This is the generic (and classical) Http operation that handles all types of HTTP requests. o.Send(lcUrl, lcUsername, lcPassword, lcOutputFile)
	SetOption	Sets an Internet option on a given connection handle. The handle can be either an Internet handle or the Http handle so this method has to be called after the connection has been opened. It is meant primarily for internal purposes. o.SetOption(lnHandle,lnOptionId,lnOptionValue)
	WinInetSetTimeout	Allows setting the timeout period for an HTTP request. The timeout is specified in seconds and controls how long a Connect, Read or Send operation waits before being considered timed out. o.wininetsettimeout(dwTimeoutSecs)
	cContentType	Sets the Content Type for POST data sent to the server. Use the content type if you're posting raw POST buffers for data like JSON (`application/json`) or XML (`text/xml`) or raw binary data.
	cErrorMsg	Last Error Message Text for the last operation. Implemented only for SMTP and HTTP operations.
	cExtraHeaders	Allows you to specify extra HTTP or SMTP headers when sending requests to Web Servers or SMTP serveres.
	chttpheaders	This property is set when calling HTTPGetEx and contains the entire HTTP header of a request. This property is a result property only after an HTTP request completes. Use cExtraHeaders to specify custom headers when sending requests to the Web server (or the parameter in HTTPGetEx).
	cHTTPProxyByPass	This property allows you to specify a list of host names or IP Addresses that should not be routed through the proxy server. IOW, this list allows you to directly access the requested domains/IPs bypassing the proxy.
	cHTTPProxyName	Use this method to override proxy information if the default Proxy connection types via nHTTPConnectType don't work for you.
	cHttpProxyPassword	Proxy server password if the proxy requires a login.
	cHttpProxyUserName	Proxy server user name if the proxy requires a login.
	cHttpVerb	Allows you to override the HTTP Verb for the request.
	cLink	HTTP Link to visit on a site. Site relative URL. Example: /default.asp, /, /wconnect.dll?wwDemo~TestPage
	cpassword	Password to log on to server (applies to FTP and HTTP)
	cResultCode	Returns the HTTP result code from a request. These are HTTP spec result codes that are typically returned in the HTTP response header from the Web Server.
	cResultCodeMessage	Returns the HTTP Result Code message based on the active cResultCode property.
	cserver	HTTP Server Address. Format: www.west-wind.com, or 111.111.111.111
	cUserAgent	The name of the user agent that the wwIPStuff client sends to the Web server. Change this property if you need to emulate a specific browser like Internet Explorer or Netscape.
	cusername	Username that can be used for HTTP authentication that requires username and password.
	lAllowGZip	Determines whether wwHTTP requests and decodes GZip content.
	lCacheRequest	If set causes the current request to be cached if possible so that subsequent requests do not go back to the server to retrieve the data.
	lDecodeUtf8	If .T. (default) automatically decodes UTF-8 encoded content from the server. Looks for the `charset=utf-8` in the `Content-Type`.
	lHttpCancelDownload	Property that can be read to see whether the current request was cancelled with HTTPCancelDownload.
	lIgnoreCertificateWarnings	When .T. ignores warnings about invalid certificates. If the server responds with warnings rather than a complete revoked and out of date certificate, these warnings are ignored and the request continues as normal. The default behavior is that any warning causes an error.
	lUseLargePostBuffer	Flag that can be set to cause the Post Buffer to use a File Stream to hold POST data. This allows the buffer to be larger than 16 megs to send large content to the server.
	nClientCertificateIndex	If a client certificate is requested this flag determines which certificate is used. This is a zero based index. By default the first is used (0).
	nconnecttimeout	Allows setting the timeout period for an HTTP request. The timeout is specified in seconds and controls how long a Connect, Read or Send operation waits before being considered timed out.
	nerror	Returns the error code from the last request. This value is 0 if no error occurred or non-zero if an error occurred.
	nHttpConnectType	Allows to specify how the connection is opened.
	nHttpPostMode	Sets the form POST mode for requests specifically for key value pair form submissions that use `AddPostKey(lcKey, lcValue)`. This property only applies to Url Encoded (`application/x-www-form-urlencoded`) or Multi-Part (`multipart/form-data`) form data not to full document types like `application/json` or `text/xml` for example.
	nHttpServiceFlags	Flags that are used on the HTTP connection in WinInet. This method is needed to pass options that require setting values. For option switches you can use the `.nHttpServiceFlags` or `.nServiceFlags` settings instead.
	nhttpworkbuffersize	Size of the download HTTP buffer used while downloading dynamically sized requests with HTTPGetEx. This is the size of chunks that will be pulled at a time and also determines how often OnHTTPBufferUpdate is called.
	nServiceFlags	Use this property to override internet service connection flags used by WinINet. Used in the call to InternetConnect().
	oPostStream	Internal `wwFileStream` instance that holds large string data when `.lUseLargePostBuffer` is used.

Remarks

Class Members

See also: