wwHTTP::HTTPGet - West Wind Client Tools

wwHTTP::HTTPGet

This is the generic (and classical) Http operation that handles all types of HTTP requests.

The .Get(),.Post(),.Put(),.Delete() methods are simply shortcut wrappers around this method that set the .cHttpVerb and meant to be more explicit for code readability.

The primary Http retrieval method of this class that retrieves HTTP content from the Web. Despite its name this method can also POST data to the server, in fact it can use any HTTP verb to submit data.

The method supports URL syntax, HTTPS syntax, username and password authentication, content data (via AddPostKey()), custom Http headers (via AddHeader()) and saving large download output directly to file. You can also use OnHttpBufferUpdate to get download progress events.

In short, for 95% of use cases you should use HttpGet() as your method to send and receive HTTP traffic. For a few of the edge cases HttpGetEx().

o.HttpGet(lcUrl, lcUsername, lcPassword, lcOutputFile)

Return Value

String - HTTP result, which most likely will be HTML, but can be whatever data the link returns. This includes XML and binary data like Word documents or even data files. On error this string will be blank and the nError and cErrorMsg properties will be set.

Parameters

lcUrl
The full URL you want to retrieve. This URL must include the protocol (HTTP or HTTPS for example) and the Domain Name or IP Address. Example: http://www.west-wind.com/wwipstuff.asp

lcUserName
Optional - Username used for Basic Authentication

lcPassword
Optional - Password used for Basic Authentication

Note: for backward compatibility the second parameter can also be numeric specifying the size of the result buffer to be returned

lcFileName
An optional path into which to download the content into. If this parameter is used the return value from this method will always return blank and only the file is created on success. To check for errors, check the nError/cErrorMsg and the cResultCode properties.

Remarks

This method returns raw text only - HTML is uninterpreted and presented as text. If the result is encoded you'll get the raw data back in encoded form. You need to explicitly decode the data.

To send custom headers use AddHeader(). To send data to the server use AddPostKey().

Example

Simple content retrieval:

oHTTP=CREATEOBJECT("wwHTTP")

lcHTML = oHTTP.HTTPGet("http://www.west-wind.com/")

*** Show HTML generated in Browser
ShowHTML( lcHTML )  && in wwUtils.prg

Sending Data to an HTML form:

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.HTTPGet("http://www.west-wind.com/wconnect/TestPage.wwd")

ShowHTML( lcHTML )

Posting raw data

loHttp = CREATEOBJECT("wwHttp")

*** Specify that we want to post raw data and a custom content type
loHttp.cContentType = "text/xml"  && 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
lcXML = FILETOSTR("XmlData.xml")

*** Set the POST buffer - Note: No name parameter, just the buffer
loHttp.AddPostKey(lcXML)

lcXmlResult = loHttp.HttpGet("http://www.west-wind.com/SomeXmlService.xsvc")
IF (loHttp.nError # 0)
   RETURN
ENDIF
   
ShowXml(lcXmlResult)

Making a REST Service call with JSON

DO wwHttp
DO wwJsonSerializer

loSer = CREATEOBJECT("wwJsonSerializer")
lcJsonIn = loSer.Serialize(loPostObject)    && Some object or value to serialize

loHttp = CREATEOBJECT("wwHttp")
loHttp.cContentType = "application/json"
loHttp.cHTTPVerb = "PUT"  && Use any HTTP verbs POST/PUT/DELETE/GET etc.
loHttp.AddPostKey(lcJsonIn)  && raw post data

lcJsonResult = loHttp.HttpGet(lcUrl)

loResultObject = loSer.DeserializeJson(lcJsonResult)

*** Do something with the result object
? loResultObject.status
? loResultObject.Data.SummaryValue

Uploading a file

loHttp = CREATEOBJECT("wwHttp")

*** Specify that we want to post raw data with a custom content type
loHttp.cContentType = "application/pdf" 

lcPdf = FILETOSTR("Invoice.pdf")
loHttp.AddPostKey(lcPdf)  && Add as raw string

*** Send to server and retrieve result
lcHtml = loHttp.HttpGet("http://www.west-wind.com/SomeUril.xsvc")