HTTP Action Plugin

Actions

HTTP.SubmitMultipart(string URL, table Values, number Method = SUBMITWEB_POST, number Timeout = 20, number Port = 80, table AuthData = nil, table ProxyData = nil)

Description:

Submits a multipart form to a remote web server.

URL:

(string) The full URL to to the form that will be submitted to.

Values:

(table) A table of values that will be passed to the script. Pass values in the form: name="value".

Method:

(string) The method used to submit the data. This parameter is ignored and will be set to POST - kept for backwards compatibility purposes only.

Timeout:

(number) The connection timeout.

Port:

(number) The port to use, generally this should remain 80.

AuthData:

(table) A table of HTTP basic authentication information that will be used in order to gain access to the form.

ProxyData:

(table) A table of proxy information that will be used in order to gain access to the form.

Callback:

(string) A string specifying a function name that will be called with progress information if default progress handling is not desired.

Returns:

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

Below is a simple PHP excerpt, which can be used to receive multipart/form-data on a web server. Any files uploaded are deleted after reception, and only the names, values and size of the files are reported back to the Lua script.

	// this program will just echo the received parameters
	// any uploaded files should be deleted

	if (isset($_SERVER['HTTPS'])) {
		print "Using a SECURE connection (SSL)\r\n";
	}
	else {
		print "Using an unencrypted connection\r\n";
	}

	if (isset($_SERVER['PHP_AUTH_USER'])) {
		print "HTTP Auth User: " . $_SERVER['PHP_AUTH_USER'] . "\r\n";
	}
	if (isset($_SERVER['PHP_AUTH_PW'])) {
		print "HTTP Auth Password: " . $_SERVER['PHP_AUTH_PW'] . "\r\n";
	}

	foreach ($_POST as $key => $val) {
		print "POST parameter '$key' contains '$val'\r\n";
	}

	foreach ($_GET as $key => $val) {
		print "GET parameter '$key' contains '$val'\r\n";
	}

	foreach ($_FILES as $name => $props) {
		// there may be more than one file upload in a single POST
		if ($_FILES[$name]['error'] == UPLOAD_ERR_OK) {
			print "Variable " . $name . "\r\n";
			print "File '" . $_FILES[$name]['name'] . "' transferred, " . $_FILES[$name]['size'] . " bytes received on server\r\n";
			if (file_exists($_FILES[$name]['tmp_name'])) {
				if (unlink($_FILES[$name]['tmp_name'])) {
					print "Temporary file deleted\r\n";
				}
				else {
					print "Failed to delete temporary file\r\n";
				}
			}
			else {
				print "Temporary file does not exist\r\n";
			}
		}
		else {
			print "File '" . $_FILES[$name]['name'] . "' not received, Error code " . $_FILES[$name]['error'] . "\r\n";
		}
	}
	print "Finished\r\n";

Example:

-- this is sample code from a AutoPlay Media Studio project which can be downloaded from
-- http://www.mindquake.com.br/files/ams/HTTP_SubmitMultipart.apz

function CustomCallback(nDataType, sDataContent)
	-- use the on-page controls to show the progress
	if (nDataType == 1) then
		-- UploadFilename: "sDataContent" carries the name of the file being uploaded
		Label.SetText("lblFilename", String.AbbreviateFilePath(sDataContent, 71));
	else
		-- PercentDone: "sDataContent" carries the percentage uploaded (0 - 100)
		Progress.SetCurrentPos("pbCustomProgress", tonumber(sDataContent));
	end
end

function ShowStatusDlg()
	-- set up the built-in StatusDlg to show the progress
	StatusDlg.Show();
	StatusDlg.SetTitle("Submitting data...");
	StatusDlg.SetMessage("");
	StatusDlg.SetStatusText("");
	StatusDlg.ShowCancelButton(false); -- Cancel button is not implemented at this time
	StatusDlg.ShowProgressMeter(true);
	StatusDlg.SetMeterRange(0, 100);
	StatusDlg.SetAutoSize(true);
end


-- form parameters
local tParameters = {};
Table.Insert(tParameters, 1, Input.GetText("inpParameter1Name") .. "=" .. Input.GetText("inpParameter1Data"));
Table.Insert(tParameters, 2, Input.GetText("inpParameter2Name") .. "=" .. Input.GetText("inpParameter2Data"));
-- a "file" parameter must have the text "_FILE_" in front of the field name!
-- The "_FILE_" text will be stripped out before submitting the form to the server.
-- In this sample, the field name will be just "userfile1".
if (Input.GetText("inpFilePath1") ~= "") then
	Table.Insert(tParameters, 3, "_FILE_userfile1=" .. Input.GetText("inpFilePath1"));
end
if (Input.GetText("inpFilePath2") ~= "") then
	Table.Insert(tParameters, 4, "_FILE_userfile2=" .. Input.GetText("inpFilePath2"));
end

--[[
-- HTTP Basic Auth data (see documentation of HTTP.Submit() for details)
-- set this parameter to nil if you don't need this, *not* an empty table
local tAuthData = {};
tAuthData["UserName"] = "anonymous";
tAuthData["Password"] = "trustNo1";
--]]
tAuthData = nil;

--[[
-- Proxy Authentication (see documentation of HTTP.Submit() for details)
-- set this parameter to nil if you don't need this, *not* an empty table
local tProxyData = {};
tProxyData["PUserName"] = "proxyuser";
tProxyData["PPassword"] = "proxypassword";
tProxyData["PServerAddress"] = "187.75.180.20:3128";
--]]
tProxyData = nil;

-- adjust for testing...
local bUseSSL = true;
local sURL = "https://www.mindquake.com.br/files/tmp/file-upload-sample.php";

-- Submit multipart/form-data to web server
if bUseSSL then
	if bUseCustomProgress then
		sReply = HTTP.SubmitMultipartSecure(sURL, tParameters, SUBMITWEB_POST, 20, 443, tAuthData, tProxyData, "CustomCallback");
	else
		ShowStatusDlg();
		StatusDlg.SetMessage("Processing");
		sReply = HTTP.SubmitMultipartSecure(sURL, tParameters, SUBMITWEB_POST, 20, 443, tAuthData, tProxyData);
		StatusDlg.Hide();
	end
else
	if bUseCustomProgress then
		sReply = HTTP.SubmitMultipart(sURL, tParameters, SUBMITWEB_POST, 20, 80, tAuthData, tProxyData, "CustomCallback");
	else
		ShowStatusDlg();
		StatusDlg.SetMessage("Processing");
		sReply = HTTP.SubmitMultipart(sURL, tParameters, SUBMITWEB_POST, 20, 80, tAuthData, tProxyData);
		StatusDlg.Hide();
	end
end

-- check the reply or error
error = Application.GetLastError();
if (error ~= 0) then
	Dialog.Message("Error", sReply .. "\r\n" .. _tblErrorMessages[error], MB_OK, MB_ICONEXCLAMATION);
else
	Dialog.Message("Info", "Web server replied:\r\n\r\n"..sReply, MB_OK, MB_ICONINFORMATION);
end

HTTP.SubmitMultipartSecure(string URL, table Values, number Method = SUBMITWEB_POST, number Timeout = 20, number Port = 443, table AuthData = nil, table ProxyData = nil)

Description:

Submits a multipart form to a remote web server via HTTPS.

URL:

(string) The full URL to to the form that will be submitted to.

Values:

(table) A table of values that will be passed to the script. Pass values in the form: name="value".

Method:

(string) The method used to submit the data. This parameter is ignored and will be set to POST - kept for backwards compatibility purposes only.

Timeout:

(number) The connection timeout.

Port:

(number) The port to use, generally this should remain 443.

AuthData:

(table) A table of HTTP basic authentication information that will be used in order to gain access to the form.

ProxyData:

(table) A table of proxy information that will be used in order to gain access to the form.

Callback:

(string) A string specifying a function name that will be called with progress information if default progress handling is not desired.

Returns:

(string) The contents of the file returned by the web script. If an error occurs, a blank string "" is returned. You can use Application.GetLastError() to determine whether this action failed, and why.

HTTP.ResumeDownload(string URL, string Filename, number Mode = MODE_BINARY, number Timeout = 20, number Port = 80, table AuthData = nil, table ProxyData = nil, function CallbackFunction = nil ) )

Description:

Resumes the transfer of an aborted or incomplete download. Please note that you cannot resume a download if nothing was downloaded yet, e.g. the local file does not exist.

URL:

(string) The full URL to the file to be downloaded.

Filename:

(string) The destination path and filename of the file you want to download. For example, C:\MyFolder\patch.zip.

Mode:

(table) The mode you want to use to save the file. Choose between MODE_BINARY and MODE_TEXT.

Timeout:

(number) The connection timeout.

Port:

(number) The port to use, generally this should remain 80.

AuthData:

(table) A table of HTTP basic authentication information that will be used in order to gain access to the file.

ProxyData:

(table) A table of proxy information that will be used in order to gain access to the file.

Callback:

(string) A string specifying a function name that will be called with progress information if default progress handling is not desired.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

HTTP.ResumeDownloadSecure(string URL, string Filename, number Mode = MODE_BINARY, number Timeout = 20, number Port = 443, table AuthData = nil, table ProxyData = nil, function CallbackFunction = nil ) )

Description:

Resumes the transfer of an aborted or incomplete download via HTTPS. Please note that you cannot resume a download if nothing was downloaded yet, e.g. the local file does not exist.

URL:

(string) The full URL to the file to be downloaded.

Filename:

(string) The destination path and filename of the file you want to download. For example, C:\MyFolder\patch.zip.

Mode:

(table) The mode you want to use to save the file. Choose between MODE_BINARY and MODE_TEXT.

Timeout:

(number) The connection timeout.

Port:

(number) The port to use, generally this should remain 443.

AuthData:

(table) A table of HTTP basic authentication information that will be used in order to gain access to the file.

ProxyData:

(table) A table of proxy information that will be used in order to gain access to the file.

Callback:

(string) A string specifying a function name that will be called with progress information if default progress handling is not desired.

Returns:

Nothing. You can use Application.GetLastError() to determine whether this action failed, and why.

HTTP.IsValidCertificate(string URL)

Description:

Checks if the SSL certificate of a web server is valid, not expired, revoked, self-signed, etc.

URL:

(string) The server name to be tested, such as "www.domain.com".

Returns:

(boolean) True if the certificate appears to be valid, false if an issue was detected. You can use Application.GetLastError() to determine whether this action failed, and why.

Example:

-- check if HTTPS server is using a valid SSL certificate
bResult = HTTP.IsValidCertificate("revoked.badssl.com");
error = Application.GetLastError();
if bResult then
    Dialog.Message("SSL", "Certificate is valid.", MB_OK, MB_ICONINFORMATION);
else
    Dialog.Message("SSL", "Issue detected:\r\n" .. _tblErrorMessages[error], MB_OK, MB_ICONSTOP);
end

HTTP.GetFileSizeEx(string URL, number Mode = MODE_BINARY, number Timeout = 20, number Port = 80, table AuthData = nil, table ProxyData = nil, function CallbackFunction = nil)

Description:

Gets the size (in bytes) of a file located on an Internet Web site. This action can return file sizes above 2147483647 bytes.

URL:

(string) The full URL to the file to be checked.

Mode:

(table) This parameter is ignored, and serves only for compatibility reasons.

Timeout:

(number) The connection timeout.

Port:

(number) This parameter is ignored, and serves only for compatibility reasons. Will use port 80 for URL starting with http and port 443 for URL starting with https.

AuthData:

(table) A table of HTTP basic authentication information that will be used in order to gain access to the file.

ProxyData:

(table) A table of proxy information that will be used in order to gain access to the file. See example below for required fields.

Callback:

(string) A string specifying a function name that will be called with progress information if default progress handling is not desired.

Returns:

(number) The size of the file on the Internet Web site (in bytes). If the file's size could not be retrieved, -1 is returned. You can use Application.GetLastError to determine whether this action failed, and why.

Example:

-- fetch the size of a file on a web server
local sURL = "https://download.microsoft.com/download/7/f/8/7f8a9c43-8c8a-4f7c-9f92-83c18d96b681/SQL2019-SSEI-Expr.exe";
nSize = HTTP.GetFileSizeEx(sURL, MODE_BINARY, 20, 80, { UserName="MyUsername", Password="MyPassword" },
            { PUserName="user", PPassword="password", PServerAddress="127.0.0.1", PPort="6691" });
error = Application.GetLastError();
if (error ~= 0) then
    Dialog.Message("Error" - Got error code " .. error .. " while checking the file", MB_OK, MB_ICONEXCLAMATION);
else
    Dialog.Message("Info", "Remote file size: " .. String.GetFormattedSize(nSize, FMTSIZE_AUTOMATIC), MB_OK, MB_ICONINFORMATION);
end