Reference ❯ Network Connections and Requests

HTTP Requests

HTTP Callback Overview top ↑

HTTP requests are handled by the http.request function. This function accepts a url (string) as its first argument, and a success and failure function as its second and third arguments respectively. The more advanced form of http.request accepts a table of parameters as its fourth argument.

-- Success function format
function success( response string or image,
                  responseHeaders )

-- Failure function format
function fail( error )

http.request( url, successFunction ) top ↑


http.request( url, successFunction )
http.request( url, successFunction, 
                   failFunction )
http.request( url, success, fail, 
              parameterTable )    

This function allows you to send a http request to the url specified by url. The request is asynchronous, so you must provide a successFunction to be called when the request succeeds. The success or fail function will be called outside of your draw function at some point in the future. You may also provide additional parameters, such as a failure function, and request type by using the more advanced parameterTable form of the function. For details on the structure of the callback functions, please see the HTTP Callback Overview in the related items, below.

Note that the successFunction will be called if the request succeeds at all. This does not guarantee that the data was found. A 404 error will result in no data, but is an example of a successful request.

http.request has special behaviour when it comes to images in PNG, JPEG and other formats. Rather than provide the raw data in the successFunction callback, Codea will automatically convert the data to an image type, which you can then draw to the screen immediately.


string, the url to submit the request


function, the function to be called when the request succeeds. This function will be called with an argument representing the returned data.


function, the function to be called when the request fails. This function will be called with a string argument containing the error.


table, specifying advanced parameters "method" : "HEAD", "GET", "PUT", "POST", "DELETE"

"headers" : table, string pairs for name and value of HTTP headers

"data" : string, POST data. Only used for POST or PUT methods.

"useragent" : string


-- Downloading data function setup() -- Request some data http.request( '', didGetData, didNotGetData ) end -- Our callback function function didGetData( data, status, headers ) print( status..' : ' ) end -- Our failure function function didNotGetData( error ) print( "Failed to get data. Error:" ) print( error ) end
-- Downloading an image function setup() logoImage = nil -- Request some data http.request( '', didGetImage ) end -- Our callback function function didGetImage( theImage, status, head ) logoImage = theImage end function draw() background(20,20,40) if logoImage ~= nil then sprite(logoImage, WIDTH/2,HEIGHT/2,WIDTH) end end

Opening Links

openURL( url ) top ↑


openURL( url )
openURL( url, internal )

This function opens the URL specified by url. By default the URL will open in an external browser. Specifying true for the internal parameter will open the URL using an in-app browser.


string, the url to open


boolean, open the url in an internal browser


function touched(touch) openURL( '' ) end
function touched(touch) -- Open in-app browser openURL( '', true ) end

Open Sound Control (OSC)

OSC Overview top ↑

Open Sound Control is a protocol for networking computers and multimedia devices. This module allows you to start an OSC server and send messages to an OSC server.

Starting an OSC server is handled by osc.start(port), which returns the IP address of the started server.

Clients can be configured to send messages to a server by setting the and osc.port properties. And then calling the osc.send() function.

OSC messages are composed of an array of numbers, strings or integers and sent to an address (e.g., "/Test"). You can listen for OSC messages by starting a server and implementing the function osc.listen(address, ...).

-- OSC listen function
function osc.listen(address, ...)

osc top ↑

This module contains the functions and parameters necessary to configure, send and receive messages via OSC.


int, the port used by the osc.send function


string, the host or IP address used by the osc.send function


function, set this to the function you would like to use to handle incoming messages

osc.start top ↑


local host = osc.start(9000)

Starts the OSC server on the specified port. If the server started successfully, returns the local address of the server.


int, the port on which to start the OSC server. Defaults to 9000


function setup() local host = osc.start(9000) print("Server running at: ", host) end


string, the host on which the server is running or nil if the server failed to start

osc.stop top ↑



Stops the OSC server.

osc.listen top ↑


function osc.listen(address, ...)

You do not call this function. Instead you can either assign a function to osc.listen or declare a global Lua function named osc.listen. If this function exists, and an OSC server has been started using osc.start, then this function will be called whenever messages are received.

This function accepts a variable number of arguments because OSC messages can contain an arbitrary number of elements. See the examples for how to declare this function.


function osc.listen(address, ...) print(address) for _,v in pairs({...}) do print(v) end end
-- This is equivalent to the first example osc.listen = function(address, ...) print(address) for _,v in pairs({...}) do print(v) end end

osc.send top ↑


osc.send(address, ...)

Sends a message to the server running at on osc.port. This function accepts an address and a variable number of arguments (which can be string, number, or integer).


string, the OSC address to send the message to


varied, any number of integers, strings or numbers to send


-- Where the server is running = "localhost" osc.port = 9000 -- Send some messages osc.send("/", 1, "Hello", 4.5) osc.send("/Address", 10.0, 5.0) osc.send("/Address")