> For the complete documentation index, see [llms.txt](https://0xa1mn.gitbook.io/cyber-explained/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://0xa1mn.gitbook.io/cyber-explained/technologies/android-application/intents.md).

# Intents

### What is Intents ?

Each activity is started or activated with an [`Intent`](https://developer.android.com/reference/android/content/Intent.html), which is a message object that makes a request to the Android runtime to start an activity or other app component in your app or in some other app.

When your app is first started from the device home screen, the Android runtime sends an `Intent` to your app to start your app's main activity (the one defined with the MAIN action and the LAUNCHER category in the `AndroidManifest.xml` file). To start another activity in your app, or to request that some other activity available on the device perform an action, you build your own intent and call the `startActivity()` method to send the intent.

In addition to starting an activity, an intent can also be used to pass data between one activity and another. When you create an intent to start a new activity, you can include information about the data you want that new activity to operate on. So, for example, an email `Activity` that displays a list of messages can send an `Intent` to the `Activity` that displays that message. The display activity needs data about the message to display, and you can include that data in the intent.

In this chapter you learn about using intents with activities, but intents can also be used to start services or broadcast receivers. You learn how to use those app components in another practical.

### Intent types <a href="#intent-types" id="intent-types"></a>

Intents can be *explicit* or *implicit*:

* *Explicit intent:* You specify the receiving activity (or other component) using the activity's fully qualified class name. You use explicit intents to start components in your own app (for example, to move between screens in the UI), because you already know the package and class name of that component.
* *Implicit intent:* You do *not* specify a specific activity or other component to receive the intent. Instead, you declare a general action to perform, and the Android system matches your request to an activity or other component that can handle the requested action. You learn more about using implicit intents in another practical.

### Intent objects and fields <a href="#intent-objects-and-fields" id="intent-objects-and-fields"></a>

For an explicit `Intent`, the key fields include the following:

* The `Activity` *class* (for an explicit `Intent`). This is the class name of the `Activity` or other component that should receive the `Intent`; for example, `com.example.SampleActivity.class`. Use the `Intent` constructor or the `setComponent()`, `setComponentName()`, or `setClassName()` methods to specify the class.
* The `Intent` *data.* The `Intent` data field contains a reference to the data you want the receiving `Activity` to operate on as a Uri object.
* `Intent` *extras.* These are key-value pairs that carry information the receiving `Activity` requires to accomplish the requested action.
* `Intent` [*flags*](https://developer.android.com/reference/android/content/Intent.html#setFlags\(int\))*.* These are additional bits of metadata, defined by the `Intent` class. The flags may instruct the Android system how to launch an `Activity` or how to treat it after it's launched.

For an implicit `Intent`, you may need to also define the `Intent` action and category. You learn more about `Intent` actions and categories in another chapter.

### Starting an Activity with an explicit Intent <a href="#starting-an-activity-with-an-explicit-intent" id="starting-an-activity-with-an-explicit-intent"></a>

To start a specific `Activity` from another `Activity`, use an explicit `Intent` and the [`startActivity()`](https://developer.android.com/reference/android/app/Activity.html#startActivity\(android.content.Intent,%20android.os.Bundle\)) method. An explicit `Intent` includes the fully qualified class name for the `Activity` or other component in the `Intent` object. All the other `Intent` fields are optional, and `null` by default.

For example, if you want to start the `ShowMessageActivity` to show a specific message in an email app, use code like this:

```
Intent messageIntent = new Intent(this, ShowMessageActivity.class);
startActivity(messageIntent);
```

The intent constructor takes two arguments for an explicit `Intent`:

* An application context. In this example, the `Activity` class provides the context (`this`).
* The specific component to start (`ShowMessageActivity.class`).

Use the `startActivity()` method with the new `Intent` object as the only argument. The `startActivity()` method sends the `Intent` to the Android system, which launches the `ShowMessageActivity` class on behalf of your app. The new `Activity` appears on the screen, and the originating `Activity` is paused.

The started `Activity` remains on the screen until the user taps the Back button on the device, at which time that `Activity` closes and is reclaimed by the system, and the originating `Activity` is resumed. You can also manually close the started `Activity` in response to a user action (such as a `Button` click) with the [`finish()`](https://developer.android.com/reference/android/app/Activity.html#finish\(\)) method:

```
public void closeActivity (View view) {
    finish();
}
```

### Passing data from one Activity to another <a href="#passing-data-from-one-activity-to-another" id="passing-data-from-one-activity-to-another"></a>

In addition to simply starting one `Activity` from another `Activity`, you also use an `Intent` to *pass information* from one `Activity` to another. The `Intent` object you use to start an `Activity` can include `Intent` *data* (the URI of an object to act on), or `Intent` *extras*, which are bits of additional data the `Activity` might need.

In the first (sending) `Activity`, you:

1. Create the `Intent` object.
2. Put data or extras into that `Intent`.
3. Start the new `Activity` with `startActivity()`.

In the second (receiving) `Activity`, you:

1. Get the `Intent` object the `Activity` was started with.
2. Retrieve the data or extras from the `Intent` object.

### When to use Intent data or Intent extras <a href="#when-to-use-intent-data-or-intent-extras" id="when-to-use-intent-data-or-intent-extras"></a>

You can use either `Intent` data or `Intent` extras to pass data from one `Activity` to another. There are several key differences between data and extras that determine which you should use.

The `Intent` *data* can hold only one piece of information: a URI representing the location of the data you want to operate on. That URI could be a web page URL (`http://`), a telephone number (`tel://`), a geographic location (`geo://`) or any other custom URI you define.

Use the `Intent` data field:

* When you only have one piece of information you need to send to the started `Activity`.
* When that information is a data location that can be represented by a URI.

Intent *extras* are for any other arbitrary data you want to pass to the started `Activity`. `Intent` extras are stored in a [`Bundle`](https://developer.android.com/reference/android/os/Bundle.html) object as key and value pairs. A `Bundle` is a map, optimized for Android, in which a key is a string, and a value can be any primitive or object type (objects must implement the [`Parcelable`](https://developer.android.com/reference/android/os/Parcelable.html) interface). To put data into the `Intent` extras you can use any of the [`Intent`](https://developer.android.com/reference/android/content/Intent.html) class `putExtra()` methods, or create your own `Bundle` and put it into the `Intent` with [`putExtras()`](https://developer.android.com/reference/android/content/Intent.html#putExtras\(android.os.Bundle\)).

Use the `Intent` extras:

* If you want to pass more than one piece of information to the started `Activity`.
* If any of the information you want to pass is not expressible by a URI.

`Intent` data and extras are not exclusive; you can use data for a URI and extras for any additional information the started `Activity` needs to process the data in that URI.

### Add data to the Intent <a href="#add-data-to-the-intent" id="add-data-to-the-intent"></a>

To add data to an explicit `Intent` from the originating `Activity`, create the `Intent` object as you did before:

```
Intent messageIntent = new Intent(this, ShowMessageActivity.class);
```

Use the [`setData()`](https://developer.android.com/reference/android/content/Intent.html#setData\(android.net.Uri\)) method with a Uri object to add that URI to the `Intent`. Some examples of using `setData()` with URIs:

```
// A web page URL
messageIntent.setData(Uri.parse("http://www.google.com")); 
// a Sample file URI
messageIntent.setData(Uri.fromFile(new File("/sdcard/sample.jpg")));
// A sample content: URI for your app's data model
messageIntent.setData(Uri.parse("content://mysample.provider/data")); 
// Custom URI 
messageIntent.setData(Uri.parse("custom:" + dataID + buttonId));
```

Keep in mind that the data field can only contain a single URI; if you call `setData()` multiple times only the last value is used. Use `Intent` extras to include additional information (including URIs.)

After you've added the data, you can start the `Activity` with the `Intent` as usual:

```
startActivity(messageIntent);
```

### Add extras to the Intent <a href="#add-extras-to-the-intent" id="add-extras-to-the-intent"></a>

To add `Intent` extras to an explicit `Intent` from the originating `Activity`:

1. Determine the keys to use for the information you want to put into the extras, or define your own. Each piece of information needs its own unique key.
2. Use the `putExtra()` methods to add your key/value pairs to the `Intent` extras. Optionally you can create a [`Bundle`](https://developer.android.com/reference/android/os/Bundle.html) object, add your data to the `Bundle`, and then add the `Bundle` to the `Intent`.

The [`Intent`](https://developer.android.com/reference/android/content/Intent.html) class includes extra keys you can use, defined as constants that begin with the word `EXTRA_`. For example, you could use [`Intent.EXTRA_EMAIL`](https://developer.android.com/reference/android/content/Intent.html#EXTRA_EMAIL) to indicate an array of email addresses (as strings), or [`Intent.EXTRA_REFERRER`](https://developer.android.com/reference/android/content/Intent.html#EXTRA_REFERRER) to specify information about the originating `Activity` that sent the `Intent`.

You can also define your own `Intent` extra keys. Conventionally you define `Intent` extra keys as static variables with names that begin with `EXTRA_`. To guarantee that the key is unique, the string value for the key itself should be prefixed with your app's fully qualified class name. For example:

```
public final static String EXTRA_MESSAGE = 
                                        "com.example.mysampleapp.MESSAGE";
public final static String EXTRA_POSITION_X = "com.example.mysampleapp.X";
public final static String EXTRA_POSITION_Y = "com.example.mysampleapp.Y";
```

Create an `Intent` object (if one does not already exist):

```
Intent messageIntent = new Intent(this, ShowMessageActivity.class);
```

Use a `putExtra()` method with a key to put data into the `Intent` extras. The `Intent` class defines many `putExtra()` methods for different kinds of data:

```
messageIntent.putExtra(EXTRA_MESSAGE, "this is my message");
messageIntent.putExtra(EXTRA_POSITION_X, 100);
messageIntent.putExtra(EXTRA_POSITION_Y, 500);
```

Alternately, you can create a new `Bundle` and populate that `Bundle` with your `Intent` extras. [`Bundle`](https://developer.android.com/reference/android/os/Bundle.html) defines many "put" methods for different kinds of primitive data as well as objects that implement Android's [`Parcelable`](https://developer.android.com/reference/android/os/Parcelable.html) interface or Java's [`Serializable`](https://developer.android.com/reference/java/io/Serializable.html).

```
Bundle extras = new Bundle();
extras.putString(EXTRA_MESSAGE, "this is my message");
extras.putInt(EXTRA_POSITION_X, 100);
extras.putInt(EXTRA_POSITION_Y, 500);
```

After you've populated the `Bundle`, add it to the `Intent` with the [`putExtras()`](https://developer.android.com/reference/android/content/Intent.html#putExtras\(android.os.Bundle\)) method (note the "s" in `Extras`):

```
messageIntent.putExtras(extras);
```

Start the `Activity` with the `Intent` as usual:

```
startActivity(messageIntent);
```