Network.xml

<?xml version = "1.0"?>
<?xml-stylesheet type="text/xsl" href="pb_help.xsl"?>
<API>
    <MODULE name="Network" parent="Rho">
        <HELP_OVERVIEW>This API class allows you to interact with either the WAN or WiFI network of the device.</HELP_OVERVIEW>
        <MORE_HELP>
## Enabling the API
This API is part of the `coreapi` extension that is included automatically.
    :::ruby
    extensions: ["coreapi"]

## JavaScript Usage
Be sure to review the [JavaScript API Usage](/guide/api_js) guide for important information about using this API in JavaScript.

## Ruby Usage
Be sure to review the [Ruby API Usage](/guide/api_ruby) guide for important information about using this API in Ruby.
        </MORE_HELP>
      
        <TEMPLATES>
        </TEMPLATES>

        <PROPERTIES access="STATIC" generateAccessors="false">
            <ALIASES>
                <ALIAS new="ssl_verify_peer" existing="verifyPeerCertificate" deprecated="true"/>
                <ALIAS new="http_command" existing="httpVerb" deprecated="true"/>
            </ALIASES>

            <PROPERTY name="url" type="STRING">
                <DESC>URL of the request. This should be fully formatted URL like http://domain.com/</DESC>
            </PROPERTY>

            <PROPERTY name="authType" type="STRING">
                <DESC>Type of authentication used for this request. Check the list of available options below. Leaving blank will result in no authentication type.</DESC>
                <VALUES>
                    <VALUE constName="AUTH_BASIC" value ="basic">
                        <DESC>Basic Authentication Type. uses authUser and authPassword.</DESC>
                    </VALUE>
                    <VALUE constName="AUTH_DIGEST" value ="digest">
                        <DESC>Digest Authentication Type. uses authUser and authPassword.</DESC>
                    </VALUE>
                </VALUES>
            </PROPERTY>
            <PROPERTY name="authUser" type="STRING">
                <DESC>User name for basic authentication. You must also specify `authType='basic'` or `authType='digest'`</DESC>
            </PROPERTY>
            <PROPERTY name="authPassword" type="STRING">
                <DESC>Password for basic authentication. You must also specify `authType='basic' or `authType='digest'`</DESC>
            </PROPERTY>
            <PROPERTY name="verifyPeerCertificate" type="BOOLEAN" default="true">
                <DESC>Verify SSL certificates. When set to false it will allow untrusted certificates.</DESC>
                <PLATFORM>WM, CE, Android, iOS, Win32</PLATFORM>
            </PROPERTY>
            <PROPERTY name="httpVerb" type="STRING">
                <DESC>HTTP verb to be used in the network request.</DESC>
            </PROPERTY>
            <PROPERTY name="headers" type="HASH">
                <DESC>List of HTTP headers to be used in the network  request.</DESC>
            </PROPERTY>

            <PROPERTY name="responseTimeout" type="INTEGER" default="30" generateAccessors="true">
                <DESC>Timeout of network requests in seconds. This property has module scope. Do not pass it as hash parameter to methods, use property accessors instead.</DESC>
            </PROPERTY>
        </PROPERTIES>

        <METHODS  access="STATIC">
            <ALIASES>
            </ALIASES>

            <METHOD name="cancel" hasCallback="optional" runInThread="none">
                <DESC>Cancel the request identified by callback. If callback is not specified then all requests will be canceled.
                > Note: for JS API: The method cancels all Rho.Network requests and does not accept args.</DESC>
            </METHOD>

            <METHOD name="downloadFile" hasCallback="optional">
                <DESC>Download a file to the specified filename. Note: if 'overwriteFile' flag is default or false, the HEAD request to the server will be performed before actual download to retrieve 'last-modified' header which is used to support resuming interrupted download. If targeted server doesn't support HEAD requests, 'overwriteFile' should be set to true.</DESC>
                <PARAMS>
                    <PARAM name="propertyMap" type="HASH" propertyHash="true">
                        <DESC>Properties to be used in this request.</DESC>
                        <PARAMS>
                            <PARAM name="url" type="STRING">
                                <DESC>URL of file to be downloaded. HTTP and HTTPS protocols are supported.</DESC>
                            </PARAM>
                            <PARAM name="filename" type="STRING">
                                <DESC>The path and name of the file to be uploaded.</DESC>
                            </PARAM>
                            <PARAM name="overwriteFile" type="BOOLEAN" default="false">
                                <DESC>OverWriteFile will overwrite the destination file if it already exists.</DESC>
                            </PARAM>
                            <PARAM name="createFolders" type="BOOLEAN" default="false">
                                <DESC>CreateFolders can automatically create the directory path.</DESC>
                            </PARAM>
                        </PARAMS>
                    </PARAM>
                </PARAMS>

                <RETURN type="HASH">
                    <PARAMS>
                        <PARAM name="body" type="STRING">
                            <DESC>The body of the HTTP response.</DESC>
                        </PARAM>
                        <PARAM name="headers" type="HASH">
                            <DESC>A hash containing the response headers.</DESC>
                        </PARAM>
                        <PARAM name="cookies" type="STRING">
                            <DESC>The server cookies, parsed and usable for subsequent requests.</DESC>
                        </PARAM>
                        <PARAM name="http_error" type="INTEGER">
                            <DESC>HTTP error code if response code was not 200.</DESC>
                        </PARAM>
                        <PARAM name="fileExists" type="BOOLEAN">
                            <DESC>When overwriteFile is false and file exists, when error return and this flag set to true.</DESC>
                        </PARAM>
                    </PARAMS>
                </RETURN>
            </METHOD>

            <METHOD name="get" hasCallback="optional">
                <DESC>Perform a HTTP GET request.

> Note: This method will perform a POST if you send a body with it. If performing a GET, do not add a body to the call.</DESC>
                <PARAMS>
                    <PARAM name="propertyMap" type="HASH" propertyHash="true">
                        <DESC>Properties map.</DESC>
                    </PARAM>
                </PARAMS>
                <RETURN type="HASH">
                    <PARAMS>
                        <PARAM name="body" type="STRING">
                            <DESC>The body of the HTTP response.</DESC>
                        </PARAM>
                        <PARAM name="headers" type="HASH">
                            <DESC>A hash containing the response headers.</DESC>
                        </PARAM>
                        <PARAM name="cookies" type="STRING">
                            <DESC>The server cookies, parsed and usable for subsequent requests.</DESC>
                        </PARAM>
                        <PARAM name="http_error" type="INTEGER">
                            <DESC>HTTP error code if response code was not 200.</DESC>
                        </PARAM>
                    </PARAMS>
                </RETURN>
            </METHOD>

            <METHOD name="post" hasCallback="optional">
                <DESC>Perform a HTTP Post.</DESC>
                <PARAMS>
                    <PARAM name="propertyMap" type="HASH" propertyHash="true">
                        <DESC>The properties for the Network module can be used in this hash along with the following:</DESC>
                        <PARAMS>
                            <PARAM name="body" type="STRING">
                                <DESC>The message body of the HTTP request.</DESC>
                            </PARAM>
                        </PARAMS>
                    </PARAM>
                </PARAMS>
                <RETURN type="HASH">
                    <PARAMS>
                        <PARAM name="body" type="STRING">
                            <DESC>The body of the HTTP response.</DESC>
                        </PARAM>
                        <PARAM name="headers" type="HASH">
                            <DESC>A hash containing the response headers.</DESC>
                        </PARAM>
                        <PARAM name="cookies" type="STRING">
                            <DESC>The server cookies, parsed and usable for subsequent requests.</DESC>
                        </PARAM>
                        <PARAM name="http_error" type="INTEGER">
                            <DESC>HTTP error code if response code was not 200.</DESC>
                        </PARAM>
                    </PARAMS>
                </RETURN>
            </METHOD>

            <METHOD name="uploadFile" hasCallback="optional">
                <DESC>Upload the specified file using HTTP POST.</DESC>
                <PARAMS>
                    <PARAM name="propertyMap" type="HASH" propertyHash="true">
                        <DESC>The properties for the Network module can be used in this hash along with the following:</DESC>
                        <PARAMS>
                            <PARAM name="filename" type="STRING">
                                <DESC>The path and name of the file to be uploaded.</DESC>
                            </PARAM>
                            <PARAM name="body" type="STRING">
                                <DESC>The message body of the HTTP request.</DESC>
                            </PARAM>
                            <PARAM name="fileContentType" type="STRING">
                                <DESC>Content-Type header for the file, defaults to "application/octet-stream".</DESC>
                            </PARAM>
                            <PARAM name="multipart" type="ARRAY">
                                <DESC>Array of hashes containing file information.</DESC>
                                <PARAM type="HASH">
                                    <DESC>Multipart properties.</DESC>
                                    <PARAMS>
                                        <PARAM name="filename" type="STRING">
                                            <DESC>The path and name of the file to be uploaded.</DESC>
                                        </PARAM>
                                        <PARAM name="contentType" type="STRING">
                                            <DESC>Content-Type header, defaults to "application/octet-stream".</DESC>
                                        </PARAM>
                                        <PARAM name="filenameBase" type="STRING">
                                            <DESC>Base directory containing the :filename.</DESC>
                                        </PARAM>
                                        <PARAM name="name" type="STRING">
                                            <DESC>File type, defaults to "blob".</DESC>
                                        </PARAM>
                                    </PARAMS>
                                </PARAM>
                            </PARAM>
                        </PARAMS>
                    </PARAM>
                </PARAMS>
                <RETURN type="HASH">
                    <PARAMS>
                        <PARAM name="body" type="STRING">
                            <DESC>The body of the HTTP response.</DESC>
                        </PARAM>
                        <PARAM name="headers" type="HASH">
                            <DESC>A hash containing the response headers.</DESC>
                        </PARAM>
                        <PARAM name="cookies" type="STRING">
                            <DESC>The server cookies, parsed and usable for subsequent requests.</DESC>
                        </PARAM>
                        <PARAM name="http_error" type="INTEGER">
                            <DESC>HTTP error code if response code was not 200.</DESC>
                        </PARAM>
                    </PARAMS>
                </RETURN>
            </METHOD>

            <METHOD name="hasNetwork">
                <DESC>Returns true if the device is connected to a network. Not supported on Windows CE.</DESC>
                <PLATFORM>WM, Android, iOS</PLATFORM>
                <MORE_HELP>Not supported on Windows CE</MORE_HELP>
                <RETURN  type="BOOLEAN"/>
            </METHOD>
            <METHOD name="hasWifiNetwork">
                <DESC>Returns true if the device is connected to a WiFi network. Not supported on Windows CE.</DESC>
                <PLATFORM>WM, Android, iOS</PLATFORM>
                <MORE_HELP>Not supported on Windows CE</MORE_HELP>
                <RETURN  type="BOOLEAN"/>
            </METHOD>
            <METHOD name="hasCellNetwork">
                <DESC>Returns true if the device is connected to a cell network. Not supported on Windows CE.</DESC>
                <PLATFORM>WM, Android, iOS</PLATFORM>
                <MORE_HELP>Not supported on Windows CE</MORE_HELP>
                <RETURN  type="BOOLEAN"/>
            </METHOD>

            <METHOD name="startStatusNotify" hasCallback="mandatory" runInThread="none">
                <DESC>Start network status notifications. Notifications are sent when WiFi or Cell network appear / disappear. To check real Internet connectivity use detectConnection method. Not supported on Windows CE.</DESC>
                <PLATFORM>WM, Android, iOS</PLATFORM>
                <MORE_HELP>Not supported on Windows CE</MORE_HELP>
                <PARAMS>
                    <PARAM name="pollInterval" type="INTEGER" default="20" productException="eb">
                        <DESC>The network status polling period for systems that can not notify network status change immediately. In seconds. Currently applies to iOS only as immediate status notification is not available on this platform.</DESC>
                    </PARAM>
                </PARAMS>
                <CALLBACK type="HASH">
                    <DESC>Network status notification information.</DESC>
                    <PARAMS>
                        <PARAM name="current_status" type="STRING">
                            <DESC>Current status of network connection. Can be "connected" or "disconnected".</DESC>
                        </PARAM>
                        <PARAM name="prev_status" type="STRING">
                            <DESC>Previous status of network connection. Can be "connected", "disconnected" or "unknown"."</DESC>
                        </PARAM>
                    </PARAMS>
                </CALLBACK>
            </METHOD>

            <METHOD name="stopStatusNotify">
                <DESC>Stop network status notifications. Not supported on Windows CE.</DESC>
                <PLATFORM>WM, Android, iOS</PLATFORM>
                <MORE_HELP>Not supported on Windows CE</MORE_HELP>
            </METHOD>

            <METHOD name="detectConnection" hasCallback="mandatory" runInThread="none">
                <VER_INTRODUCED>4.0.0</VER_INTRODUCED>
                <DESC>Begins polling the specified host on the specified URL to check if there is a network connection available. The connection status is reported back via the provided callback. Note that callback will be called only if connection status has changed compared to previous polling. Multiple concurrent detectionConnection is not supported.</DESC>
                <PARAMS>
                    <PARAM name="propertyMap" type="HASH" propertyHash="true">
                        <DESC>Properties map.</DESC>
                        <PARAMS>
                            <PARAM name="host" type="STRING" default="www.symbol.com">
                                <DESC>When detecting a network connection, this is the URL or IP address of the server to attempt to connect to.</DESC>
                            </PARAM>
                            <PARAM name="port" type="INTEGER" default="80">
                                <DESC>When detecting a network connection, this is the port on the host to connect to.</DESC>
                            </PARAM>
                            <PARAM name="pollInterval" type="INTEGER" default="30000">
                                <DESC>The time, in milliseconds, between each check for a connection. Note that the actual connection report interval will be the sum of the poll interval and the detection timeout.  The minimum allowed value is 5000ms.</DESC>
                            </PARAM>
                            <PARAM name="detectionTimeout" type="INTEGER" default="1000">
                                <DESC>The amount of time to attempt to connect to the specified URL before giving up and assuming 'disconnected'.  Value is specified in milliseconds.</DESC>
                            </PARAM>
                        </PARAMS>
                    </PARAM>
                </PARAMS>
                <CALLBACK  type="HASH">
                    <DESC>Information related to the connection to the specified URL.</DESC>
                    <PARAMS>
                        <PARAM name="connectionInformation" type="STRING">
                            <DESC>Whether the device is connected to the specified host and port.  Either 'Connected' or 'Disconnected'.</DESC>
                        </PARAM>
                        <PARAM name="failureMessage" type="STRING">
                            <DESC>If the device is disconnected this field will contain information about why the connection failed.</DESC>
                        </PARAM>
                    </PARAMS>
                </CALLBACK>
            </METHOD>

            <METHOD name="stopDetectingConnection" hasCallback="optional">
                <VER_INTRODUCED>4.0.0</VER_INTRODUCED>
                <DESC>Ceases network detection. Callback is no longer supported; it has been made optional to preserve backward compatibility.</DESC>
            </METHOD>

            <METHOD name="connectWan" hasCallback="mandatory">
                <DESC>Connects the device to a Wide Area Network. The connection destination must be first configured through the Connection Manager (on the device) and the destination name provided to this method. If a connection is already established, you must first call disconnectWan before attempting another connection. A list of available connection destinations is written to the log file when either connectWan or disconnectWan are first specified. Specify the connection as 'Internet' to use the default internet connection defined on the device. If the specified destination does not exist no connection attempt will be made and an entry will be made in the log file.</DESC>
                <PLATFORM>WM</PLATFORM>
                <APPLIES>This method only applies to platforms with the Windows Mobile connection manager</APPLIES>
                <VER_INTRODUCED>1.0.3</VER_INTRODUCED>
                <PARAMS>
                    <PARAM name="connectionDestination" type="STRING">
                        <DESC>The connection in the Windows Connection manager to use, specify 'Internet' to use the default internet connection.</DESC>
                    </PARAM>
                </PARAMS>
                <CALLBACK  type="HASH">
                    <DESC>Notifies the user whenever any parameter associated with data connectivity changes.  This callback is called when the connectWan method is first called (for the initial state) and again whenever any of the associated parameters change.</DESC>
                    <PARAMS>
                        <PARAM name="phoneSignalStrength" type="STRING">
                            <DESC>The signal strength of the phone as a percentage of maximum strength. Returned as a number between 0 and 100. If there is no phone service this field will be 0.</DESC>
                        </PARAM>
                        <PARAM name="networkOperator" type="STRING">
                            <DESC>The name of the current network operator associated with the SIM card.</DESC>
                        </PARAM>
                        <PARAM name="connectionTypeAvailable" type="STRING">
                            <DESC>The current data connection type available to RhoElements as provided by the Network. Values can be 'Unavailable', GPRS, 1XRTT, EVDO, EDGE, UMTS, EVDV or HSDPA.</DESC>
                        </PARAM>
                        <PARAM name="connectionTypeConnected" type="STRING">
                            <DESC>The data connection type to which the device is currently connected. The values returned are identical to connectionTypeAvailable, with the exception that 'Not Connected' replaces 'Unavailable'.</DESC>
                        </PARAM>
                        <PARAM name="connectionManagerMessage" type="STRING">
                            <DESC>This is the last received status from the Connection Manager. Do NOT use this parameter to determine if you are able to physically send / receive data to a remote host, it only provides an indication of whether the Connection Manager believes the connection is available. To determine if you are connected to a remote host use the detectConnection method.</DESC>
                        </PARAM>
                    </PARAMS>
                </CALLBACK>
            </METHOD>

            <METHOD name="disconnectWan" hasCallback="none" runInThread="separate">
                <VER_INTRODUCED>1.0.3</VER_INTRODUCED>
                <DESC>Disconnects the current WAN connection. DisconnectWan will only affect connections established by RhoElements so if you have not previously called connectWan this function will have no effect.</DESC>
                <PLATFORM>WM</PLATFORM>
                <APPLIES>This method only applies to platforms with the Windows connection manager</APPLIES>
            </METHOD>

        </METHODS>

        <VER_INTRODUCED>1.0.0</VER_INTRODUCED>
         <PLATFORM>WM, CE, Win32, Android, iOS, WP8</PLATFORM>
       <REMARKS>
            <REMARK title="Detecting a connection through proxies">
                <DESC><![CDATA[
Because the detectConnection method is protocol agnostic, it will not communicate through HTTP proxies to reach a specified URL. In order to determine if you are connected when sitting behind a proxy you should call the method to attempt to connect to your proxy on the appropriate port. A successful connection to the proxy should be taken to assume the device is connected to a network. When configuring your WAN connection bear in mind that the proxy settings defined in the RhoElements configuration file will take precedence.
                ]]></DESC>
            </REMARK>
            <REMARK title="Detecting a connection over WAN">
                <DESC><![CDATA[
When detecting a network connection over WAN bear in mind if you specify a low networkPollInterval your device will frequently have an active data connection and may prevent the device occasionally from accepting incoming calls.
                    ]]></DESC>
            </REMARK>
            <REMARK title="Preventing access to the device (WEH / WM)">
                <DESC><![CDATA[
Receiving phone calls or texts whilst running RhoElements will cause the start button to be displayed on Windows Embedded Handheld devices, potentially offering users access to the operating system. It is recommended to set the following registry keys to disable Operating System access on Windows Embedded Handheld as required. The registry keys will be applied after a warm boot, omit them entirely to restore the Start and 'X' icons.

<pre>
[HKEY_LOCAL_MACHINE\Software\Microsoft\Shell\BubbleTiles]   Location in Registry
"HardwareStartKeyEnabled"=dword:00000001                    Prevents the Start icon from appearing in the bottom left
"HardwareDoneKeyEnabled"=dword:00000001                     Prevents the 'X' icon from appearing in the bottom right
</pre>

                    ]]></DESC>
            </REMARK>
            <REMARK title="SSL Connection Failure in iOS Platform">
                <DESC><![CDATA[
Due to a limitation in curl for iOS, an appropriate timeout is not used in 'select' system calls for a curl SSL conection. To avoid this SSL connection issue, it is recommended that the iOS native Network library be used instead of curl. To do this, add the two lines below to the rhoconfig.txt file. 

For more information, please refer to <a href="https://developer.apple.com/library/ios/documentation/NetworkingInternetWeb/Conceptual/NetworkingOverview/CommonPitfalls/CommonPitfalls.html">Avoiding Common Networking Mistakes</a> in the Apple developer reference.

<pre>
ios_net_curl = 0
ios_direct_local_requests = 0
</pre>
                    ]]></DESC>
            </REMARK>
        </REMARKS>
        <EXAMPLES >
           <EXAMPLE title="Request a notification from the system when network availability changes">
              <SECTIONS>
              <SECTION>
               <DESC>When you need to be notified of changes in the status of the network (connected / disconnected), use Network.startStatusNotify.</DESC>
               <CODE>
                <RUBY>
           <![CDATA[
  def start_status_notify
    # Request the system to check every 3 seconds and call us back if there is a change in network connectivity
    Rho::Network.startStatusNotify(3000, url_for(:action => :status_notify_callback))
    Alert.show_popup "Started network status notifications"
  end

  # This is our notification that the status of the network changed. old_status and new_status can be "disconnected" or "connected"
  def status_notify_callback
    Alert.show_popup("Network status changed from #{@params["prev_status"]} to #{@params["current_status"]}")
  end


  def stop_status_notify
    # Stop network status notifications
    Rho::Network.stopStatusNotify
    Alert.show_popup "Stopped network status notifications"
  end
                   ]]>
                 </RUBY>
                <JAVASCRIPT>
           <![CDATA[
    function status_notify_callback(params) {
      alert("Network status changed from "+params["prev_status"]+" to "+params["current_status"]);
    }

    function start_status_notify() {
      # Request the system to check every 3 seconds and call us back if there is a change in network connectivity
      Rho.Network.startStatusNotify(3000, status_notify_callback);
    }

    function stop_status_notify() {
      // Stop network status notifications
      Rho.Network.stopStatusNotify();
    }

                   ]]>
                 </JAVASCRIPT>
               </CODE>
               </SECTION>
           </SECTIONS>

           </EXAMPLE>
            <EXAMPLE title="Check whether the network is available">
              <SECTIONS>

              <SECTION>
               <DESC>You can check whether the mobile, WiFi or other network is available. This can be useful for example if you only want to perform large data transfers on WiFi and avoid doing them while on the cell network.</DESC>
               <CODE>
                <RUBY>
           <![CDATA[
    # check the network availability for...
    # Cell network
    cell_network = Rho::Network.hasCellNetwork
    # Wi-Fi
    wifi_network = Rho::Network.hasWifiNetwork
    # Any network
    network = Rho::Network.hasNetwork
                   ]]>
                 </RUBY>
                <JAVASCRIPT>
           <![CDATA[
    function network_availability() {
      // shows the network availability for...
      // Cell network
      var cell_network = Rho.Network.hasCellNetwork()
      // Wi-Fi network
      var wifi_network = Rho.Network.hasWifiNetwork()
      // Any network
      var network = Rho.Network.hasNetwork()

      alert("Cell network: "+cell_network+"\nWi-Fi network: "+wifi_network+"\nNetwork: "+network);
    }
                   ]]>
                 </JAVASCRIPT>
               </CODE>
               </SECTION>
           </SECTIONS>
           </EXAMPLE>
          <EXAMPLE title="Download file and save it to permanent storage">
              <SECTIONS>
               <SECTION>
               <DESC>Download any file from an external server and store it in your device.</DESC>
               <CODE>
                <RUBY>
           <![CDATA[
  def download_file
      #Download a file to the specified filename.
      downloadfileProps = Hash.new
      downloadfileProps["url"]='http://www.google.com/images/icons/product/chrome-48.png'
      downloadfileProps["filename"] = Rho::Application.publicFolder+"/images/sample.png"
      downloadfileProps["overwriteFile"] = true
      Rho::Network.downloadFile(downloadfileProps, url_for(:action => :download_file_callback))
  end

  def download_file_callback
    if @params["status"] == "ok"
        Alert.show_popup "Download Success,path is /public/images/sample.png "
    else
        Alert.show_popup "Download Failed"
    end
  end

                   ]]>
                 </RUBY>
                <JAVASCRIPT>
           <![CDATA[
function download_file_callback(params) {
  if (params["status"] == "ok") {
    alert("Download Succeeded, path is /public/images/sample.png");
  } else {
    alert("Download Failed");
  }
}

function download_file() {
  // Download a file to the specified filename. Be careful with the overwriteFile parameter!
  downloadfileProps = {
    url: "http://www.google.com/images/icons/product/chrome-48.png",
    filename: Rho.Application.publicFolder+"/images/sample.png",
    overwriteFile: true
  };
  Rho.Network.downloadFile(downloadfileProps, download_file_callback);
}
                   ]]>
                 </JAVASCRIPT>
               </CODE>
               </SECTION>
           </SECTIONS>
           </EXAMPLE>
            <EXAMPLE title="Upload files via HTTP POST">
              <SECTIONS>
               <SECTION>
               <DESC>You can upload any file to an external server via HTTP POST and be notified whether the transfer succeeded or not.</DESC>
               <CODE>
                <RUBY>
           <![CDATA[
  def upload_file
    # Upload the specified file using HTTP POST.
    uploadfileProps = Hash.new
    uploadfileProps['url'] = "http://www.example.com"
    uploadfileProps['filename'] = Rho::Application.publicFolder+"/images/backButton.png"
    uploadfileProps['body'] = "uploading file"
    uploadfileProps['fileContentType']="image/png"
    Rho::Network.uploadFile(uploadfileProps, url_for(:action => :upload_file_callback))
  end

  def upload_file_callback
    if @params['status'] == "ok"
        Alert.show_popup "Upload Succeeded."
    else
        Alert.show_popup "Upload Failed."
    end
  end
                   ]]>
                 </RUBY>
                <JAVASCRIPT>
           <![CDATA[
function upload_file_callback(params) {
  // Check the result of the upload and act accordingly
  if (params["status"] == "ok") {
    alert("Upload Succeeded.");
  } else {
    alert("Upload Failed.");
  }
}

function upload_file() {
    // Upload the specified file using HTTP POST.
    uploadfileProps = {
      url: "http://www.example.com",
      filename: Rho.Application.publicFolder+"/images/backButton.png",
      body: "uploading file",
      fileContentType: "image/png"
    };

    Rho.Network.uploadFile(uploadfileProps, upload_file_callback);
}
                   ]]>
                 </JAVASCRIPT>
               </CODE>
               </SECTION>
            </SECTIONS>
            </EXAMPLE>
            <EXAMPLE title="Network POST Using Ruby's Lambda">
                <SECTIONS>
                    <SECTION>
                        <DESC>You can also define network request callbacks with this API using Ruby's lambda functions, similar to how you would use a JavaScript anonymous function for a callback. Simply define your callback, using lambda, in place of the callback parameter in the method call as such.</DESC>
                        <CODE>
                            <RUBY><![CDATA[
Rho::Network.post(
  {
    url:      url,
    headers:  { 'Content-Type' => 'application/json', 'Accept' => 'application/json' },
    body:     json
  },
  lambda do |response; body, headers, cookies, http_status|

    body = response['body']
    headers = response['headers']
    cookies = response['cookies']
    http_status = response['http_status']

    app_info "TESTING got POST callback"
    app_info "body = #{body.inspect}"
    app_info "headers = #{headers.inspect}"
    app_info "cookies = #{cookies.inspect}"
    app_info "http_error = #{http_error.class} #{http_error.inspect}"
    app_info "testing lambda context, url = '#{url}'"
  end
)
                                ]]>
                            </RUBY>
                        </CODE>
                </SECTION>
                </SECTIONS>
            </EXAMPLE>
        </EXAMPLES>
    </MODULE>
</API>