  Introduction
  ------------
  This is a sample Java application designed to showcase the functionality of 
  the Device Request feature and demonstrates how Device Cloud can be used to 
  control remote devices.

  Once the connection is established, the sample waits for incoming requests to
  process them. If the target is 'screenshot', the image 'image.png', located 
  inside the 'res' directory, will be uploaded to the specified directory in 
  Device Cloud.


  Main files
  ----------
    * com.etherios.connector.devicerequest.MainApp.java:
      Main application class. Instantiates and starts the Cloud Connector object.

    * com.etherios.connector.devicerequest.ConnectorEventsListener.java:
      Class that handles the connector events.

    * com.etherios.connector.devicerequest.DeviceRequestListener.java: 
      Class to manage the received device requests.

    * connector_config.txt:
      Cloud Connector general settings.


  Requirements
  ------------
  To run this example you will need:
    * A PC connected to the Internet to host and run the application.
    * A Device Cloud account.
      For further information on how to create a Device Cloud account go to
      the 'Creating a Device Cloud Account' topic of the Getting Started.


  Example setup
  -------------
    1) Ensure Cloud Connector is properly configured.
       This can be done editing the 'connector_config.txt' file which is 
       located in the 'res' folder of the project. Make sure that the 
       'vendor_id' field is filled with your account Vendor ID.
       
       For further information on how to configure the 'connector_config.txt'
       file, go to the 'Cloud Connector Configuration' topic of the
       Developer's Guide.

    2) Ensure the device is registered in your Device Cloud account.
       By default, it is registered automatically because the Device ID is 
       provisioned from Device Cloud. If you want to modify this behavior, 
       read the 'Device ID Type' section (Developer's Guide > Cloud Connector 
       Configuration > General Settings).

    3) The Application Descriptor needs the following API Permissions:

        java.util.PropertyPermission "*" "read,write"
        javax.microedition.io.AccessPointPermission "*"
        javax.microedition.io.Connector.file.read
        javax.microedition.io.Connector.file.write
        javax.microedition.io.SocketProtocolPermission "socket://:*"
        javax.microedition.io.SocketProtocolPermission "socket://*:*"
        javax.microedition.io.SSLProtocolPermission "ssl://:*"
        javax.microedition.io.SSLProtocolPermission "ssl://*:*"
        javax.microedition.location.LocationPermission "location" "location"

    4) The Etherios public certificate is imported to the device's keystore.
       For further information, read the 'Adding the Etherios Certificate to
       Your Device' topic inside 'Creating and Building a Java Project with 
       Cloud Connector support' of the Developer's Guide.


  Running the example
  -------------------
  The example is already configured, so all you need to do is to build and 
  launch the application. Refer to the general instructions about how to build, 
  run, and debug the examples for further information.

  To verify that the application is running successfully, follow these steps:

     1) Login into your Device Cloud account.

     2) Once logged in select the 'API Explorer' menu within the 'Documentation'
        tab.

     3) Click the 'SCI Targets' button to open the 'Select devices to be used in
        examples' dialog. Use the 'Add Targets' drop-down box to locate the 
        Device ID that corresponds to your device. Click the 'Add' button then 
        click 'OK' to exit the dialog.

        NOTE: if you do not know your Device ID you can locate it by navigating 
        to 'Device Management > Devices' and locating your device within the 
        list. The device's Device ID is displayed within the 'Device ID' column.

     4) Within the 'API Explorer' toolbar click on the 'Examples' drop-down 
        menu, then select 'SCI > Data Service > Send Request'. The SCI request 
        will be automatically generated.

     5) Replace the target with 'screenshot' and the payload with the path to 
        store the file in Device Cloud. For example, to store the screenshot in 
        the directory '<DeviceID>/captures/':

        <sci_request version="1.0">
          <data_service>
            <targets>
              <device id="000XXXXX-00000000-0XXXXXXX-XXXXXXXX"/>
            </targets>
            <requests>
              <device_request target_name="screenshot">
                captures
              </device_request>
            </requests>
          </data_service>
        </sci_request>

        Where 000XXXXX-00000000-0XXXXXXX-XXXXXXXX corresponds to the Device ID 
        of your device.

     6) Click the 'Send' button to send this request to the device. You should 
        see the following output message:

        Screenshot uploaded to 000XXXXX-00000000-0XXXXXXX-XXXXXXXX/captures/[date].png

        Where 000XXXXX-00000000-0XXXXXXX-XXXXXXXX corresponds to the Device ID 
        of your device and [date] to the date when the screen shot was captured.

     7) Observe the output displayed within the 'Web Services Responses' panel 
        on the right side of the page. Click on the response text to see the 
        entire response from the device. You should see something similar to the
        following:

        <sci_reply version="1.0">
          <data_service>
            <device id="000XXXXX-00000000-0XXXXXXX-XXXXXXXX">
            <requests>
              <device_request target_name="screenshot" status="0">Screenshot uploaded to 000XXXXX-00000000-0XXXXXXX-XXXXXXXX/captures/[date].png</device_request>
            </requests>
            </device>
          </data_service>
        </sci_reply>

        Where 000XXXXX-00000000-0XXXXXXX-XXXXXXXX corresponds to the Device ID 
        of your device and [date] to the date when the screen shot was captured.