socket.*

Type Library
Revision Release 2024.3703
Keywords socket, LuaSocket, networking
See also LuaSocket Documentation
network.request()
network.download()
network.canDetectNetworkStatusChanges
network.setStatusListener()

Overview

Important

The socket library provides low-level access to the network stack on the host device. It is not intended for general networking usage (the network library is much easier to use). There are a small number of specific tasks that require socket APIs, but these are uncommon and require a level of expertise in network programming that is also uncommon. Any code that uses the socket APIs will need ongoing tweaking as device vendors change rules for network access, for example in regard to IPv6 networks, while code written using the network APIs will generally continue to work because it is directly supported by device vendors.

Solar2D currently includes version 3.0-rc1 of the LuaSocket libraries. These Lua modules implement common network protocols such as SMTP, HTTP, and FTP. Also included are features to support MIME (common encodings), URL manipulation, and LTN12 for transferring and filtering data.

For asynchronous HTTP functions instead of synchronous LuaSocket functions, see network.request() and network.download().

Gotchas

On Android, you must add the INTERNET permission to the build.settings file.

settings =
{
   android =
   {
      usesPermissions =
      {
         "android.permission.INTERNET",
      },
   },
}

Examples

Retrieve IP Address and Port
local socket = require( "socket" )

-- Connect to the client
local client = socket.connect( "www.apple.com", 80 )
-- Get IP and port from client
local ip, port = client:getsockname()
 
-- Print the IP address and port to the terminal
print( "IP Address:", ip )
print( "Port:", port )
Download Image From Remote URL
-- Load the relevant LuaSocket modules
local http = require( "socket.http" )
local ltn12 = require( "ltn12" )
 
-- Create local file for saving data
local path = system.pathForFile( "hello.png", system.DocumentsDirectory )
myFile = io.open( path, "w+b" ) 
 
-- Request remote file and save data to local file
http.request{
    url = "https://coronalabs.com/wordpress/wp-content/uploads/2018/07/orange_vertikal_RGB.png", 
    sink = ltn12.sink.file( myFile )
}
 
-- Display local file
local testImage = display.newImage( "hello.png", system.DocumentsDirectory )