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