Difference between revisions of "lua-https"

m (Change description.)
m (fixed to Pages with syntax highlighting errors.)
 
(2 intermediate revisions by one other user not shown)
Line 16: Line 16:
 
{{param|string|url|HTTP or HTTPS URL to access.}}
 
{{param|string|url|HTTP or HTTPS URL to access.}}
 
{{param|table|options|Optional options for advanced mode.}}
 
{{param|table|options|Optional options for advanced mode.}}
{{subparam|string|data|Additional data to send as application/x-www-form-urlencoded.}}
+
{{subparam|string|data|Additional data to send as application/x-www-form-urlencoded (unless specified otherwise in Content-Type header).}}
 
{{subparam|string|method|HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.}}
 
{{subparam|string|method|HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.}}
 
{{subparam|table|headers|Additional headers to add to the request as key-value pairs.}}
 
{{subparam|table|headers|Additional headers to add to the request as key-value pairs.}}
Line 23: Line 23:
 
{{param|string|body|HTTP response body or nil on failure.}}
 
{{param|string|body|HTTP response body or nil on failure.}}
 
{{param|table|headers|HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.}}
 
{{param|table|headers|HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.}}
 +
=== Notes ===
 +
To urlencode a Lua table suitable for application/x-www-form-urlencoded data, use a LuaSocket function.
 +
<source lang="lua">
 +
local url = require("socket.url")
 +
 +
function urlencode(list)
 +
-- Since order of pairs is undefined, the key-value order is also undefined.
 +
local result = {}
 +
for k, v in pairs(list) do
 +
result[#result + 1] = url.escape(k).."="..url.escape(v)
 +
end
 +
return table.concat(result, "&")
 +
end
 +
 +
-- Usage
 +
code, body, headers = https.request("https://example.com", {data = urlencode({key = "value", foo = "bar"})
 +
</source>
  
 
== Compile From Source ==
 
== Compile From Source ==
Line 29: Line 46:
 
=== Windows ===
 
=== Windows ===
 
Compilation is done using CMake. This assume MSVC toolchain is used. Change "x64" to "Win32" to compile for x86 32-bit platform or "ARM64" for ARM64 platform.
 
Compilation is done using CMake. This assume MSVC toolchain is used. Change "x64" to "Win32" to compile for x86 32-bit platform or "ARM64" for ARM64 platform.
<source>
+
<source lang="bash">
 
cmake -Bbuild -S. -A x64 -DCMAKE_INSTALL_PREFIX=%CD%\install
 
cmake -Bbuild -S. -A x64 -DCMAKE_INSTALL_PREFIX=%CD%\install
 
cmake --build build --config Release --target install
 
cmake --build build --config Release --target install
Line 37: Line 54:
 
=== Linux ===
 
=== Linux ===
 
Compilation is done using CMake. Ensure you have [https://www.openssl.org/ OpenSSL] and [https://curl.se/ cURL] development libraries installed to enable all supported Linux backends.
 
Compilation is done using CMake. Ensure you have [https://www.openssl.org/ OpenSSL] and [https://curl.se/ cURL] development libraries installed to enable all supported Linux backends.
<source>
+
<source lang="bash">
 
cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD\install
 
cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD\install
 
cmake --build build --target install
 
cmake --build build --target install
Line 46: Line 63:
 
{{newin|[[11.4]]|114|text=Proper 3rd-party C module support requires this LÖVE version}}
 
{{newin|[[11.4]]|114|text=Proper 3rd-party C module support requires this LÖVE version}}
 
Compilation is done by placing lua-https source code in <code><love-android>/love/src/jni/lua-modules</code>. The structure will look like this:
 
Compilation is done by placing lua-https source code in <code><love-android>/love/src/jni/lua-modules</code>. The structure will look like this:
<source>
+
<source lang="text">
 
<love-android>/love/src/jni/lua-modules/lua-https
 
<love-android>/love/src/jni/lua-modules/lua-https
 
+ example
 
+ example
Line 65: Line 82:
 
{{#set:Description=A simple Lua HTTPS module using native platform backends where applicable.}}
 
{{#set:Description=A simple Lua HTTPS module using native platform backends where applicable.}}
 
{{#set:LOVE Version=12.0}}
 
{{#set:LOVE Version=12.0}}
 +
{{#set:LOVE Min Version=Any}}
 
{{#set:Keyword=Networking}}
 
{{#set:Keyword=Networking}}
 +
{{#set:Standalone Lua Module=Yes (12.0)/No (C module)}}
  
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|lua-https}}
 
{{i18n|lua-https}}

Latest revision as of 11:16, 10 July 2023

Available since LÖVE 12.0
Users can compile from source for earlier versions of LÖVE.


lua-https is a simple Lua HTTPS module using native platform backends specifically written for LÖVE 12.0 and supports Windows, Linux, macOS, iOS, and Android.

lua-https is licensed under zLib license, same as LÖVE.

Reference

To use lua-https, load it with require like local https = require("https"). lua-https does not create global variables!

The https table expose single function: https.request

Synopsis

code, body, headers = https.request( url, options )

Arguments

string url
HTTP or HTTPS URL to access.
table options
Optional options for advanced mode.
string data
Additional data to send as application/x-www-form-urlencoded (unless specified otherwise in Content-Type header).
string method
HTTP method. If absent, it's either "GET" or "POST" depending on the data field above.
table headers
Additional headers to add to the request as key-value pairs.

Returns

number code
HTTP status code, or 0 on failure.
string body
HTTP response body or nil on failure.
table headers
HTTP response headers as key-value pairs or nil on failure or option parameter above is nil.

Notes

To urlencode a Lua table suitable for application/x-www-form-urlencoded data, use a LuaSocket function.

local url = require("socket.url")

function urlencode(list)
	-- Since order of pairs is undefined, the key-value order is also undefined.
	local result = {}
	for k, v in pairs(list) do
		result[#result + 1] = url.escape(k).."="..url.escape(v)
	end
	return table.concat(result, "&")
end

-- Usage
code, body, headers = https.request("https://example.com", {data = urlencode({key = "value", foo = "bar"})

Compile From Source

While lua-https will be bundled in LÖVE 12.0 by default, it's possible to compile the module from source and use it on earlier version of LÖVE. Grab the source code at https://github.com/love2d/lua-https. All compilation requires Lua 5.1 (or LuaJIT) headers and libraries available.

Windows

Compilation is done using CMake. This assume MSVC toolchain is used. Change "x64" to "Win32" to compile for x86 32-bit platform or "ARM64" for ARM64 platform.

cmake -Bbuild -S. -A x64 -DCMAKE_INSTALL_PREFIX=%CD%\install
cmake --build build --config Release --target install

https.dll can be found in the install folder.

Linux

Compilation is done using CMake. Ensure you have OpenSSL and cURL development libraries installed to enable all supported Linux backends.

cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD\install
cmake --build build --target install

https.so can be found in the install folder.

Android

Available since LÖVE 11.4
Proper 3rd-party C module support requires this LÖVE version.

Compilation is done by placing lua-https source code in <love-android>/love/src/jni/lua-modules. The structure will look like this:

<love-android>/love/src/jni/lua-modules/lua-https
+ example
+ src
+ Android.mk
+ CMakeLists.txt
+ java.txt
+ license.txt

Afterwards compile love-android as usual. The modules will be automatically embedded to the APK. This can be verified by checking the APK with Zip viewer application and inspecting files in lib/arm64-v8a and lib/armeabi-v7a.

See Also




Other Languages