http.Fetch

http.Fetch( string url, function onSuccess = nil, function onFailure = nil, table headers = {} )

Description

Launches an asynchronous GET request to an HTTP server. Internally calls HTTP.

HTTP requests returning a status code >= 400 are still considered a success and will call the onSuccess callback.

The onFailure callback is usually only called on DNS or TCP errors (e.g. the website is unavailable or the domain does not exist).

A rough overview of possible onFailure messages:

invalid url - Invalid/empty url ( no request was attempted )
invalid request - Steam HTTP lib failed to create a HTTP request
error - OnComplete callback's second argument, bError, is true
unsuccessful - OnComplete's first argument, pResult->m_bRequestSuccessful, returned false

This cannot send or receive multiple headers with the same name.

Issue Tracker: 2232

HTTP-requests that respond with a large body may return an unsuccessful error. Try using the Range header to download the file in chunks.

HTTP-requests to destinations on private networks (such as 192.168.0.1, or 127.0.0.1) won't work.
To enable HTTP-requests to destinations on private networks use Command Line Parameters -allowlocalhttp. (Dedicated servers only)

Not all headers are allowed in the client realm, here is a list of known blacklisted headers inside the client realm:

host expect content-length proxy-authenticate accept-charset connection accept-encoding origin date

Arguments

1 string url

The URL of the website to fetch.

2 function onSuccess = nil

Function to be called on success.

Function argument(s):

1 string body - No description given.

2 number size - equal to string.len(body).

3 table headers - No description given.

4 number code - The HTTP success code.

3 function onFailure = nil

Function to be called on failure.

Function argument(s):

1 string error - The error message.

4 table headers = {}

KeyValue table for headers.

Example

Shows the typical usage to get the HTML of a webpage.

local theReturnedHTML = "" -- Blankness http.Fetch( "https://www.google.com", -- onSuccess function function( body, length, headers, code ) -- The first argument is the HTML we asked for. theReturnedHTML = body end, -- onFailure function function( message ) -- We failed. =( print( message ) end, -- header example { ["accept-encoding"] = "gzip, deflate", ["accept-language"] = "fr" } )

Output: If it successfully fetched the page, the variable theReturnedHTML should contain the returned HTML in plain text.