Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Intent

The Intent API provides an inter-application broadcast message-passing framework.

Enabling the API

This API is part of the coreapi extension that is included automatically.

extensions: ["coreapi"]

JavaScript Usage

Be sure to review the JavaScript API Usage guide for important information about using this API in JavaScript.

Ruby Usage

Be sure to review the Ruby API Usage guide for important information about using this API in Ruby.

Methods

send(HASH params, CallBackHandler callback)

Sends an intent. The receiver of the intent can either be another RhoMobile application that is listening for this Intent characteristic or on Android can be a native Android application setup with an Intent-Filter that will trigger based on the parameters of this method.

Note: On Android, the callback should only be used when the intentType is set to START_ACTIVITY. On Android, the only valid way to pass private file from package directly to another application is set ‘uri’ parameter with content URI. In most cases it is also needed to add extension of exported file to ‘android:no_compression’ list at build.yml

build.yml:

android:
  no_compression: ['pdf','html','css']

JavaScript:

var params = {
    intentType: Rho.Intent.START_ACTIVITY,
    action: "ACTION_VIEW",
    uri: "content://com.rhomobile.sample/rhodata/apps/public/sample.pdf"
}
Rho.Intent.send(params);

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

params : HASH

A hash-map with intent parameters.

intentType : STRING

Type of Intent to send.

Possible Values :

Constant: Intent.BROADCAST (For Ruby use "::" instead of ".")
String:broadcast

Use the intent as broadcast intent.

Constant: Intent.START_ACTIVITY (For Ruby use "::" instead of ".")
String:startActivity

Use the intent to start a UI activity.
Platforms:
Android

Constant: Intent.START_SERVICE (For Ruby use "::" instead of ".")
String:startService

Use the intent to start a background service.
Platforms:
Android
permission : STRING

Permission used to send a broadcast intent.
Platforms:Android
action : STRING

Intent action. See Android docs. for possible values.

Use the Constant Value instead of the actual Constant Name. Ex: For the Constant ACTION_PICK use ‘android.intent.action.PICK’
Platforms:Android
categories : ARRAY

List of intent categories. See Android docs for possible values.

Use the Constant Value instead of the actual Constant Name. Ex: For the Constant CATEGORY_HOME use ‘android.intent.category.HOME’
Platforms:Android

Object : STRING

appName : STRING

Explicit name of the application on the device to run. The platform will determine what value to use.
- iOS it is BundleURLScheme of executed application.
- Android it is application package name.
- Windows it is the application/executable name. For shared runtime based applications, the application name is taken from the “Name” attribute from the Config.xml file. Hence use the application name which is mentioned in config.xml.
targetClass : STRING

Explicit name of the class in the application which will receive the intent. Must be specified if and only if ‘appName’ is defined.
Platforms:Android
uri : STRING

Open the application associated with the URI. Behavior may be different on different platforms and depend on installed software. For example, open URL with http:// prefix usually executes the Web Browser installed on system and open URL in executed browser.

For Android, this is similar to Intent.setData(). For example, if you were sending a Map Intent you would set this value to something like geo:47.6,-122.3
mimeType : STRING

MIME type of data defined in the intent. For example, for Plain Text I would use text/plain

For Android, this is similar to Intent.setType()
data : HASH

Data which will be sent within the intent.

For Android, this is similar to Intent.putExtra(). data should contain a HASH of Extra-String,Value pairs. The Value type of the Extra must be a string. Other object types are not supported at this time. For example:

Android:
```
intent.putExtra(Intent.EXTRA_TEXT, 'Here is the text I am passing to the Intent');
```
JavaScript:
```
var data = {"android.intent.extra.TEXT":"Here is the text I am passing to the Intent"}
```
Notice the use of the full constant string “android.intent.extra.TEXT” in place of Intent.EXTRA_TEXT

callback : CallBackHandler Optional

Async Callback Returning Parameters: HASH

responseCode : INTEGER

Response code passed to Android Activity.setResult() method. RESULT_OK = -1. Check Android Docs for more information. Other attributes like uri may be returned depending on the Intent that was triggered. Possible parameters include the same params that are used in this send(params) method
Platforms:Android

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Intent.send(HASH params, CallBackHandler callback)
- Ruby: Rho::Intent.send(HASH params, CallBackHandler callback)

startListening(CallBackHandler callback)

Start listening for custom intents.

For Android, this is how we have implemented Android Intent Filters. In order to listen for Intents you will have to update the AndroidManifest.erb file and add a special section to it. This file is now generated with RhoMobile Version 4.1 when you create a new project. The file is located in the root of project.

Add the following snippet to AndroidManifest.erb within the manifest tags

<receiver android:name='com.rho.intent.IntentReceiver'>
  <intent-filter>
    <action android:name="Intent.ACTION_BATTERY_CHANGED" />
  </intent-filter>
</receiver>

Notice that this looks very similar to a standard AndroidManifest.XML file section except the receiver is the common RhoMobile intent receiver. The intent-filter tags within this section are standard AndroidManifest.XML notation that you would put in for the Intent-Filters that you want to listen for. Consult the Android Docs for more information about Intent Filters. From your Android application, you would use the sendBroadcast() method with the appropriate parameters for this filter.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Parameters

callback : CallBackHandler Mandatory

Async Callback Returning Parameters: HASH

Synchronous Return:

Void : this method also supports async callbacks - check the Callback tab for callback return parameters.

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Intent.startListening(CallBackHandler callback)
- Ruby: Rho::Intent.startListening(CallBackHandler callback)

stopListening()

Stop listening for custom intents.

JavaScript Ruby Android iphone, ipod touch, ipad Windows Mobile, Windows CE, Windows Embedded

Synchronous Return:

Void

Method Access:

Class Method: This method can only be accessed via the API class object.
- JavaScript: Rho.Intent.stopListening()
- Ruby: Rho::Intent.stopListening()

Examples

Plot a location on a map

You can use the Intent API to use the default mapping program to plot locations.

JavaScript
Ruby

function sendGeo(){
  var intentParams = {action     : "android.intent.action.VIEW",
                      intentType : Rho.Intent.START_ACTIVITY,
                      uri        : "geo:37.422, -122.084"};

  Rho.Intent.send(intentParams);
}

def send_geo
  intent_params = {:action     => "android.intent.action.VIEW",
                   :intentType => Rho::Intent::START_ACTIVITY,
                   :uri        => "geo:37.422, -122.084"}

  Rho::Intent.send intent_params
end

Sending Extras

Sometimes you will want to send some extras along with an intent such as an SMS body or do a web search with a given string. Here is an example of an intent that will launch the default web browser and perform a search with the default search engine.

JavaScript
Ruby

function webSearch(){}
  var intentParams = {action     : "android.intent.action.WEB_SEARCH",
                      intentType : Rho.Intent.START_ACTIVITY,
                      data       : {query : "Rhomobile docs"}}

  Rho.Intent.send(intentParams)
}

def web_search
  intent_params = { :action     => "android.intent.action.WEB_SEARCH",
                    :intentType => Rho::Intent::START_ACTIVITY,
                    :data       => { :query => "Rhomobile docs" } }

  Rho::Intent.send intent_params
end