Network

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,
                  statusCode,
                  responseHeaders )

-- Failure function format
function fail( error )

Related

http.request( url, successFunction ) top ↑

Syntax

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.

url

string, the url to submit the request
successFunction

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

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

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

Examples

-- Downloading data function setup() -- Request some data http.request( 'http://twolivesleft.com/hello.txt', didGetData, didNotGetData ) end -- Our callback function function didGetData( data, status, headers ) print( status..' : '..data ) 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( 'http://twolivesleft.com/logo.png', 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

Related

Opening Links

openURL( url ) top ↑

Syntax

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.

url

string, the url to open
internal

boolean, open the url in an internal browser

Examples

function touched(touch) openURL( 'http://twolivesleft.com' ) end
function touched(touch) -- Open in-app browser openURL( 'http://twolivesleft.com', 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 osc.host 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, ...)

Related

osc top ↑

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

port

int, the port used by the osc.send function
host

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

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

Related

osc.start top ↑

Syntax

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.

port

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

Examples

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

Returns

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

Related

osc.stop top ↑

Syntax

osc.stop()

Stops the OSC server.

Related

osc.listen top ↑

Syntax

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.

Examples

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

Related

osc.send top ↑

Syntax

osc.send(address, ...)

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

address

string, the OSC address to send the message to
...

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

Examples

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

Related