Contents

• Functions
• Simple Callback
• Callback Table
• Options

Implements high-level asynchronous access to URLs, such as downloading webpages over HTTP(S).

Note that unlike other languages' URL access libraries, this class implements asynchronous requests. This means that the functions only start a request and return immediately. The request is then fulfilled in the background, while the server continues to run. The response is delivered back to the plugin using callbacks. This allows the plugin to start requests and not block the server until the response is received.

The functions that make network requests are all static and have a dual interface. Either you can use a single callback function, which gets called once the entire response is received or an error is encountered. Or you can use a table of callback functions, each function being called whenever the specific event happens during the request and response lifetime. See the Simple Callback and Callback Table chapters later on this page for details and examples.

All the request function also support optional parameters for further customization of the request - the Headers parameter specifies additional HTTP headers that are to be sent (as a dictionary-table of key -> value), the RequestBody parameter specifying the optional body of the request (used mainly for POST and PUT requests), and an Options parameter specifying additional options specific to the protocol used.

cUrlClient:Get(url,
	function (a_Body, a_Data)
		if (a_Body) then
			-- Response received correctly, a_Body contains the entire response body,
			-- a_Data is a dictionary-table of the response's HTTP headers
		else
			-- There was an error, a_Data is the error message string
		end
	end
)

The following callback functions are used by Cuberite. Any callback that is not assigned is silently ignored. The table may also contain other functions and other values, those are silently ignored.

The following example is adapted from the Debuggers plugin's "download" command, it downloads the contents of an URL into a file.

function HandleConsoleDownload(a_Split)  -- Console command handler
	-- Read the params from the command:
	local url = a_Split[2]
	local fnam = a_Split[3]
	if (not(url) or not(fnam)) then
		return true, "Missing parameters. Usage: download  "
	end
	
	-- Define the cUrlClient callbacks
	local callbacks =
	{
		OnStatusLine = function (self, a_HttpVersion, a_Status, a_Rest)
			-- Only open the output file if the server reports a success:
			if (a_Status ~= 200) then
				LOG("Cannot download " .. url .. ", HTTP error code " .. a_Status)
				return
			end
			local f, err = io.open(fnam, "wb")
			if not(f) then
				LOG("Cannot download " .. url .. ", error opening the file " .. fnam .. ": " .. (err or ""))
				return
			end
			self.m_File = f
		end,

		OnBodyData = function (self, a_Data)
			-- If the file has been opened, write the data:
			if (self.m_File) then
				self.m_File:write(a_Data)
			end
		end,
		
		OnBodyFinished = function (self)
			-- If the file has been opened, close it and report success
			if (self.m_File) then
				self.m_File:close()
				LOG("File " .. fnam .. " has been downloaded.")
			end
		end,
	}
	
	-- Start the URL download:
	local isSuccess, msg = cUrlClient:Get(url, callbacks)
	if not(isSuccess) then
		LOG("Cannot start an URL download: " .. (msg or ""))
		return true
	end
	return true
end

Redirection:

• If a redirect is received, and redirection is allowed by MaxRedirects, the redirection is reported via OnRedirecting() callback and the request is restarted at the redirect URL, without reporting any of the redirect's headers nor body.
• If a redirect is received and redirection is not allowed (maximum redirection attempts have been reached), the OnRedirecting() callback is called with the redirect URL and then the request terminates with an OnError() callback, without reporting the redirect's headers nor body.