Parent | Child | Previous | Next
 
Xbasic

HTTP_GET Function

Syntax

Result as P = http_get(url as C [,cookie as C [,port as N [,timeout as N [,show_before_send as L [,validate_ssl_cert as L [,SSLCipherList as C]]]]]])

Arguments

urlCharacter

The URL of the page to retrieve.

cookieCharacter

Default = "". Cookie data. Limited to 8 MB (megabytes.)

portNumeric

Default = -1. The port to use. When set to -1 or 0, the correct standard port for the protocol specified will be used (e.g. 80 for http://, 443 for https://).

timeoutNumeric

Default = 8000 milliseconds. The number of milliseconds to wait before timing out.

show_before_sendLogical

Default = .F.. When .T., displays the request before being sent. Useful for debugging.

validate_ssl_certLogical

Default = .T.. If the specified URL starts with "https://", this flag controls whether or not the certificate offered by the server will be validated.

SSLCipherListCharacter

Default = "". SSL Cipher List. When an empty list is provided, the function [httpd_defaultCipherList()] is used to set the acceptable ciphers for this request.

followRedirectsLogical

Default = .F.. By default, this function will not follow any server redirects. Set this to .T. to follow redirects. The maximum allowed number of redirects is 20.

Returns

ResultPointer

A dot variable containing the server's response.

error_textCharacter

The error message, if any. If no error occurs, error_text will be empty.

error_codeNumeric

The error number, if any. If no error occurs, error_code will be 0.

headersCharacter

Response headers. If error_code is 0, the result will contain a dot variable, parsed_headers, with a property representing each response header.

bodyCharacter

Response body.

parsed_headersPointer

Contains all the headers in the response split out into individual properties. If an error occurred when trying to communicate with the server, parsed_headers will be empty. parsed_headers will always contain the following properties in addition to the headers in the response:

http_versionCharacter

The HTTP version used.

reason_phraseCharacter

A description of the status code.

status_codeNumeric

The response status code. See Status Codes for a list of status codes.

Description

Use the HTTP method GET to retrieve the specified URL.

Discussion

The HTTP_GET() function downloads from a URL using the GET method with TLS 1.2 or newer. The function supports cookies and returns a pointer with the parsed response from the server. If error_code is "0", parsed_response will contain the headers in the result:

result = http_get("https://www.alphasoftware.com")

? result.error_code
= 0

? result.parsed_headers
= AccessControlAllowCredentials = "false"
CacheControl = "s-maxage=0,max-age=0"
CFCacheStatus = "MISS"
CFRay = "6670eee43f011a70-EWR"
cfrequestid = "0afa73a2a600001a70d0247000000001"
Connection = "close"
ContentSecurityPolicy = "upgrade-insecure-requests"
ContentType = "text/html;charset=utf-8"
Date = "Tue, 29 Jun 2021 17:39:15 GMT"
EdgeCacheTag = "CT-35182565649,P-106714,L-35181923534,L-5604761998,CW-24331389464,CW-35229429723,CW-5735045208,CW-5735324780,CW-5737318041,E-2213003845,E-34723407283,E-48984798551,E-5218256228,E-5218258420,E-5218269128,E-5218270162,PGS-ALL,SW-1,GC-28400762621"
ExpectCT = max-age=604800, report-uri="https://report-uri.cloudflare.com/cdn-cgi/beacon/expect-ct"
http_version = "HTTP/1.1"
Link = "</hs/hsstatic/cos-i18n/static-1.37/bundles/project.js>; rel=preload; as=script, </hs/hsstatic/HubspotToolsMenu/static-1.103/js/index.js>; rel=preload; as=script"
NEL = {"report_to":"cf-nel","max_age":604800}
reason_phrase = "OK"
ReferrerPolicy = "no-referrer-when-downgrade"
ReportTo = {"endpoints":[{"url":"https:\/\/a.nel.cloudflare.com\/report\/v2?s=bj2NYewys4axOmkRAKRF%2BAqzfhj%2B2fXHr8ib8wYh1dv3taAyRYmH85Bdsu5n1AAws6pSqs1HZJGR6HjcOWJcGaiGIZ4v3I0WyGIfsebkiauedORarKQOL7mFTVrjYsseeIg%3D"}],"group":"cf-nel","max_age":604800}
Server = "cloudflare"
SetCookie = "__cfruid=6ecc829e5dcc9b33e3192a52d6758830e9cf1016-1624988355; path=/; domain=.www.alphasoftware.com; HttpOnly; Secure; SameSite=None"
status_code = 200
StrictTransportSecurity = "max-age=0"
Vary = "Accept-Encoding"
XHSCacheConfig = "BrowserCache-0s-EdgeCache-0s"
XHSContentId = "35182565649"
XHSHubId = "106714"
XHubSpotCorrelationId = "14f0e1de-6feb-4f4c-8973-90863867f09a"
XPoweredBy = "HubSpot"
XTrace = "2B6A4B63690779FED0913D6BF90FF40AB4098349DC000000000000000000"

Status code 200 indicates that the page exists. Status code 404 indicates that it does not. Other status codes you may encounter, along with the meanings of each, are documented in Status Codes.

Handling Redirects

When the server responds with a 301, 302, 307, or 308 code, HTTP_GET() does not automatically use the new URL. As of build 8596, developers my optionally specify that redirects should be followed by using the settings.Redirects.follow property. In earlier builds or if automatice redirect handling is not desired, the developer needs to examine result.parsed_headers.status_code, then if appropriate, try the URL provided in result.parsed_headers.location. For example:

dim url as C = "https://www.alphasoftware.com/"
dim result as P
result = http_get(url)

if (result.error_code == 0) then
    while (result.parsed_headers.status_code == 301 .or. result.parsed_headers.status_code == 302 .or. result.parsed_headers.status_code == 307 .or. result.parsed_headers.status_code == 308)
        result = http_get(result.parsed_headers.Location)
        if (result.error_code <> 0)
            showvar(result.error_text)
            end
        end if
    end while
    if (result.parsed_headers.status_code <> 200) then
        ' Request returned with an error.
        ui_msg_box("Error","The request returned with the following status code: " + result.parsed_headers.status_code,UI_STOP_SYMBOL)
        showvar(result.parsed_headers)
        end
    else
        ' status 200
        showvar(result)
    end if

else
    ui_msg_box("Error","The request failed with the following error code: " + result.error_code + crlf() + "Error details: " + result.error_text)
end if

HTTP GET vs HTTP POST

HTTP GET is different from HTTP POST in two significant ways. Some devices may restrict the total length of a URL to 128 characters, which may trim the arguments appended by a GET command. There is no such restriction with POST commands. You may save (bookmark) and refresh URLs formatted through HTTP GET. The arguments sent by HTTP POST are not saved in a bookmark.

Example: Retrieve a Page

This example retrieves the Alpha Software home page:

dim alpha as P
alpha = http_get("https://www.alphasoftware.com/")

if (alpha.error_code == 0) then
    if (alpha.parsed_headers.status_code = 200) then
        a5_show_html(alpha.body)
    end if
else
    ui_msg_box("Error","The request failed with the following error code: " + alpha.error_code + crlf() + "Error details: " + alpha.error_text)
end if

Example: Search Google

In the example below, HTTP_GET is used to perform a search using www.google.com:

dim search_term as C
dim google as P
search_term = ui_get_text("Search for...","What are you looking for?")
google = http_get("http://www.google.com/search?hl=en&ie=UTF-8&oe=UTF-8&q=" + urlencode(search_term))

if (google.error_code == 0) then
    if (google.parsed_headers.status_code = 200) then
        a5_show_html(google.body)
    end if
else
    ui_msg_box("Error","The request failed with the following error code: " + google.error_code + crlf() + "Error details: " + google.error_text)
end if

Example: RSS Feed

In this example, RSS text is retrieved from Slashdot.org using HTTP_GET:

dim rss as P

rss = http_get("http://rss.slashdot.org/Slashdot/slashdot")

if (rss.error_code == 0) then
    if .not. eval_valid("rss.body")
        ui_msg_box("Error","The RSS file was not downloaded from the server.",UI_STOP_SYMBOL)
    else
        dim num_items as N
        num_items = count_textblocks(rss.body,"<item","</item>")
        dim item[num_items] as P
        dim i as N
        dim this_item as C
        for i = 1 to num_items
            this_item = extract_string(rss.body,"<item","</item>",i,.t.)
            item[i].title = extract_string(this_item,"<title>","</title>")
            item[i].link = extract_string(this_item,"<link>","</link>")
            item[i].description = extract_string(this_item, "<description>", "</description>")
            item[i].creator = extract_string(this_item, "<dc:creator>", "</dc:creator>")
            item[i].subject = extract_string(this_item, "<dc:subject>", "</dc:subject>")
            item[i].date = extract_string(this_item, "<dc:date>", "</dc:date>")
            item[i].section = extract_string(this_item, "<slash:section>", "</slash:section>")
            item[i].department = extract_string(this_item, "<slash:department>", "</slash:department>")
            item[i].comments = extract_string(this_item, "<slash:comments>", "</slash:comments>")
            item[i].hitparade = extract_string(this_item, "<slash:hitparade>", "</slash:hitparade>")
        next i
        'now do something with this, like put it into a table or build an output file.
        showvar(item)
    end if
else
    ui_msg_box("Error","The request failed with the following error code: " + rss.error_code + crlf() + "Error details: " + rss.error_text)
end if

See Also