Network.yaml

id: network
name: Network
subtitle: Network Connections and Requests          
ordering:
    - HTTP Requests
    - Opening Links
functions:
#---------------------------------
# openURL
#---------------------------------
- category: function
  description: 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.
  examples:
  - example: |
      function touched(touch)
          openURL( 'http://twolivesleft.com' )
      end
  - example: |
      function touched(touch)
          -- Open in-app browser
          openURL( 'http://twolivesleft.com', true )
      end
  group: Opening Links
  id: openURL
  name: openURL( url )
  parameters:
  - description: string, the url to open
    name: url
  - description: boolean, open the url in an internal browser
    name: internal
  syntax: |
    openURL( url )
    openURL( url, internal )
#---------------------------------
      
#---------------------------------
# HTTP Callback Overview
#---------------------------------    
- category: overview
  description: |
    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 )
        
  group: HTTP Requests
  id: httpCallbackOverview
  name: HTTP Callback Overview
  related:
  - http.request
  - image
#---------------------------------
      
#---------------------------------
# http.request
#---------------------------------    
- category: function
  description: >
    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.
  examples:
  
  - example: |
      -- 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
      
  - example: |
      -- 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
      
  group: HTTP Requests
  id: http.request
  name: http.request( url, successFunction )
  parameters:
  - description: string, the url to submit the request
    name: url
  - description: function, the function to be called when the request succeeds.
      This function will be called with an argument representing the returned data.
    name: successFunction
  - description: function, the function to be called when the request fails. This
      function will be called with a string argument containing the error.
    name: failFunction
  - description: |
      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
    name: parameterTable
  related:
  - httpCallbackOverview
  - image
  syntax: |
    http.request( url, successFunction )
    http.request( url, successFunction, 
                       failFunction )
    http.request( url, success, fail, 
                  parameterTable )