|
38 | 38 | * <p> |
39 | 39 | * {@link Tag} is an immutable object that represents the state of a NFC tag at |
40 | 40 | * the time of discovery. It can be used as a handle to {@link TagTechnology} classes |
41 | | - * to perform advanced operations, or directly queried for its ID ({@link #getId} and the |
42 | | - * set of technologies it contains ({@link #getTechList}). Arrays passed to and |
43 | | - * returned by this class are *not* cloned, so be careful not to modify them. |
| 41 | + * to perform advanced operations, or directly queried for its ID via {@link #getId} and the |
| 42 | + * set of technologies it contains via {@link #getTechList}. Arrays passed to and |
| 43 | + * returned by this class are <em>not</em> cloned, so be careful not to modify them. |
44 | 44 | * <p> |
45 | 45 | * A new tag object is created every time a tag is discovered (comes into range), even |
46 | 46 | * if it is the same physical tag. If a tag is removed and then returned into range, then |
47 | 47 | * only the most recent tag object can be successfully used to create a {@link TagTechnology}. |
48 | 48 | * |
49 | 49 | * <h3>Tag Dispatch</h3> |
50 | 50 | * When a tag is discovered, a {@link Tag} object is created and passed to a |
51 | | - * single application via the {@link NfcAdapter#EXTRA_TAG} extra in a |
52 | | - * {@link Context#startActivity} {@link android.content.Intent}. A four stage dispatch is used to select the |
53 | | - * most appropriate application to handle the tag. The Android OS executes each stage in order, |
54 | | - * and completes dispatch as soon as a single matching application is found. If there are multiple |
55 | | - * matching applications found at any one stage then the Android Activity Chooser dialog is shown |
56 | | - * to allow the user to select the application. |
| 51 | + * single activity via the {@link NfcAdapter#EXTRA_TAG} extra in an |
| 52 | + * {@link android.content.Intent} via {@link Context#startActivity}. A four stage dispatch is used |
| 53 | + * to select the |
| 54 | + * most appropriate activity to handle the tag. The Android OS executes each stage in order, |
| 55 | + * and completes dispatch as soon as a single matching activity is found. If there are multiple |
| 56 | + * matching activities found at any one stage then the Android activity chooser dialog is shown |
| 57 | + * to allow the user to select the activity to receive the tag. |
| 58 | + * |
| 59 | + * <p>The Tag dispatch mechanism was designed to give a high probability of dispatching |
| 60 | + * a tag to the correct activity without showing the user an activity chooser dialog. |
| 61 | + * This is important for NFC interactions because they are very transient -- if a user has to |
| 62 | + * move the Android device to choose an application then the connection will likely be broken. |
| 63 | + * |
57 | 64 | * <h4>1. Foreground activity dispatch</h4> |
58 | | - * A foreground activity that has called {@link NfcAdapter#enableForegroundDispatch} is |
59 | | - * given priority. See the documentation on {#link NfcAdapter#enableForegroundDispatch} for |
| 65 | + * A foreground activity that has called |
| 66 | + * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} is |
| 67 | + * given priority. See the documentation on |
| 68 | + * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} for |
60 | 69 | * its usage. |
61 | 70 | * <h4>2. NDEF data dispatch</h4> |
62 | | - * If the tag contains NDEF data, then {@link Context#startActivity} is called with |
63 | | - * {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and a data URI determined from the |
64 | | - * first NDEF Record in the first NDEF Message in the Tag. This allows NDEF tags to be given |
65 | | - * priority dispatch to applications that can handle the content. |
| 71 | + * If the tag contains NDEF data the system inspects the first {@link NdefRecord} in the first |
| 72 | + * {@link NdefMessage}. If the record is a URI, SmartPoster, or MIME data |
| 73 | + * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_NDEF_DISCOVERED}. For URI |
| 74 | + * and SmartPoster records the URI is put into the intent's data field. For MIME records the MIME |
| 75 | + * type is put in the intent's type field. This allows activities to register to be launched only |
| 76 | + * when data they know how to handle is present on a tag. This is the preferred method of handling |
| 77 | + * data on a tag since NDEF data can be stored on many types of tags and doesn't depend on a |
| 78 | + * specific tag technology. |
66 | 79 | * See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain |
67 | | - * NDEF data, or if no application is registered |
68 | | - * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI then dispatch moves |
69 | | - * to stage 3. |
| 80 | + * NDEF data, or if no activity is registered |
| 81 | + * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI or MIME type then dispatch |
| 82 | + * moves to stage 3. |
70 | 83 | * <h4>3. Tag Technology dispatch</h4> |
71 | 84 | * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to |
72 | | - * dispatch the tag to an application that can handle the technologies present on the tag. |
| 85 | + * dispatch the tag to an activity that can handle the technologies present on the tag. |
73 | 86 | * Technologies are defined as sub-classes of {@link TagTechnology}, see the package |
74 | | - * {@link android.nfc.tech}. The Android OS looks for an application that can handle one or |
75 | | - * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED for more detail. |
| 87 | + * {@link android.nfc.tech}. The Android OS looks for an activity that can handle one or |
| 88 | + * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED} for more detail. |
76 | 89 | * <h4>4. Fall-back dispatch</h4> |
77 | | - * If no application has been matched, then {@link Context#startActivity} is called with |
| 90 | + * If no activity has been matched then {@link Context#startActivity} is called with |
78 | 91 | * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism. |
79 | 92 | * See {@link NfcAdapter#ACTION_TAG_DISCOVERED}. |
80 | 93 | * |
81 | | - * <p> |
82 | | - * <i>The Tag dispatch mechanism was designed to give a high probability of dispatching |
83 | | - * a tag to the correct application without showing the user an Application Chooser dialog. |
84 | | - * This is important for NFC interactions because they are very transient - if a user has to |
85 | | - * move the Android device to choose an application then the connection is broken.</i> |
86 | | - * |
87 | 94 | * <h3>NFC Tag Background</h3> |
88 | 95 | * An NFC tag is a passive NFC device, powered by the NFC field of this Android device while |
89 | | - * it is in range. Tag's can come in many forms, such as stickers, cards, key fob, or |
| 96 | + * it is in range. Tag's can come in many forms, such as stickers, cards, key fobs, or |
90 | 97 | * even embedded in a more sophisticated device. |
91 | 98 | * <p> |
92 | 99 | * Tags can have a wide range of capabilities. Simple tags just offer read/write semantics, |
93 | 100 | * and contain some one time |
94 | 101 | * programmable areas to make read-only. More complex tags offer math operations |
95 | 102 | * and per-sector access control and authentication. The most sophisticated tags |
96 | | - * contain operating environments such as Javacard, allowing complex interactions with the |
97 | | - * applets executing on the tag. Use {@link TagTechnology} classes to access a broad |
| 103 | + * contain operating environments allowing complex interactions with the |
| 104 | + * code executing on the tag. Use {@link TagTechnology} classes to access a broad |
98 | 105 | * range of capabilities available in NFC tags. |
99 | 106 | * <p> |
100 | 107 | */ |
|
0 commit comments