Android - What is a PendingIntent ?

Question

I am new to Android development and I had to use a repeating alarm using AlarmManager. This is where I first had an opportunity to use a PendingIntent. However after reading through the documentation ( http://developer.android.com/reference/android/app/PendingIntent.html ), I am really confused as to what a PendingIntent really is.

My questions are:

Q1. In what way is a PendingIntent 'pending' ? Apologies for this question, but I'd like to have an intuitive understanding of what a PendingIntent means.

Q2. The documentation says:

A PendingIntent itself is simply a reference to a token maintained by the system describing the original data used to retrieve it. This means that, even if its owning application's process is killed, the PendingIntent itself will remain usable from other processes that have been given it. If the creating application later re-retrieves the same kind of PendingIntent (same operation, same Intent action, data, categories, and components, and same flags), it will receive a PendingIntent representing the same token if that is still valid, and can thus call cancel() to remove it.

How does,

reference to a token maintained by the system describing the original data

relate to my code here ?

pendingIntent = PendingIntent.getBroadcast(getApplicationContext(),0,photosIntent,0);
alarmManager.setRepeating(AlarmManager.ELAPSED_REALTIME,SystemClock.elapsedRealtime(),
                           10000, pendingIntent);

Q3. I also do not understand what follows in the documentation:

Because of this behavior, it is important to know when two Intents are considered to be the same for purposes of retrieving a PendingIntent. A common mistake people make is to create multiple PendingIntent objects with Intents that only vary in their "extra" contents, expecting to get a different PendingIntent each time. This does not happen. The parts of the Intent that are used for matching are the same ones defined by Intent.filterEquals. If you use two Intent objects that are equivalent as per Intent.filterEquals, then you will get the same PendingIntent for both of them.

What are the extra contents ? Does this refer to the request code & flag parameters in the getBroadcast(Context context, int requestCode, Intent intent, int flags) method ?

Any help on this would be most appreciated. My online searches have not given me the answers I was looking for. Also, thank you very much for your time.

Answer 1

Q1 - In what way is it "Pending"?

The system stores the values you store in PendingIntent and lets you (or another part of the framework) look them up later on, as if the component that looked them up had created a new Intent spontaneously with that information.

Q2 - how does "reference to a token" relate to my code here?

The Android Framework doesn't actually store the PendingIntent object you create; it hashes the "identifying information" for the intent (in this case, the action, data, type, class, and categories) and uses that to look up the rest of the information. The literal PendingIntent object you create doesn't get saved, the information it represents does.

Q3 - What are the "extra contents"?

The "extras" it's referring to here are the parcelable items you store via putExtra(). The requestCode and flags values are also saved and retrieved, but when the documentation refers to "extras" it means the literal getExtras() Bundle that Intents can use to carry additional information.