http.get

Gets an HTTP resource from the specified URL as a string.

http.get(url, { options })

Parameters

url is the URL to be downloaded.

options is a table of options used for this HTTP retrieval

• progress is a Lua callback function that receives two numeric arguments representing total and current download progress in bytes.
• headers is a Lua table with HTTP headers to be used on the request.
• userpwd is a username and optional password in the format of username:password which will be used to authenticate the request
• username is the username which will be used to authenticate the request
• password is the password which will be used to authenticate the request
• timeout is the timeout in seconds.
• timeoutms is the timeout in milliseconds.
• sslverifyhost Verify the host name in the SSL certificate. See CURLOPT_SSL_VERIFYHOST
• sslverifypeer Verify the SSL certificate. See CURLOPT_SSL_VERIFYPEER

Return Values

There are three return values.

resource, result_str, response_code = http.get(url, { options })

• resource is the content that was retrieved or nil if it could not be retrieved.
• result_str is set to "OK" if successful or contains a description of the failure.
• result_code is the HTTP result code of the get.

Examples

local resource, result_str, response_code = http.get("http://example.com/api.json")

function progress(total, current)
  local ratio = current / total;
  ratio = math.min(math.max(ratio, 0), 1);
  local percent = math.floor(ratio * 100);
  print("Download progress (" .. percent .. "%/100%)")
end

local resource, result_str, response_code = http.get("http://example.com/api.json", {
    progress = progress,
    headers = { "From: Premake", "Referer: Premake" }, 
    userpwd = "username:password"
})

Backward compatible function signature

The previous signature of this function was

http.get(url, progress, headers)

and continues to be supported. This is equivalent to

http.get(url, { progress = progress, headers = headers })

Availability

Premake 5.0 or later.

See Also

• http.download
• http.post