public final class NfcAdapter extends Object
Use the helper getDefaultAdapter(Context)
to get the default NFC
adapter for this Android device.
For more information about using NFC, read the Near Field Communication developer guide.
Modifier and Type | Class and Description |
---|---|
static interface |
NfcAdapter.CreateBeamUrisCallback |
static interface |
NfcAdapter.CreateNdefMessageCallback
A callback to be invoked when another NFC device capable of NDEF push (Android Beam)
is within range.
|
static interface |
NfcAdapter.OnNdefPushCompleteCallback
A callback to be invoked when the system successfully delivers your
NdefMessage
to another device. |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_ADAPTER_STATE_CHANGED
Broadcast Action: The state of the local NFC adapter has been
changed.
|
static String |
ACTION_HANDOVER_TRANSFER_DONE |
static String |
ACTION_HANDOVER_TRANSFER_STARTED |
static String |
ACTION_NDEF_DISCOVERED
Intent to start an activity when a tag with NDEF payload is discovered.
|
static String |
ACTION_TAG_DISCOVERED
Intent to start an activity when a tag is discovered.
|
static String |
ACTION_TAG_LEFT_FIELD
Broadcast to only the activity that handles ACTION_TAG_DISCOVERED
|
static String |
ACTION_TECH_DISCOVERED
Intent to start an activity when a tag is discovered and activities are registered for the
specific technologies on the tag.
|
static String |
EXTRA_ADAPTER_STATE
Used as an int extra field in
#ACTION_STATE_CHANGED
intents to request the current power state. |
static String |
EXTRA_HANDOVER_TRANSFER_STATUS |
static String |
EXTRA_HANDOVER_TRANSFER_URI |
static String |
EXTRA_ID
Optional extra containing a byte array containing the ID of the discovered tag for
the
ACTION_NDEF_DISCOVERED , ACTION_TECH_DISCOVERED , and
ACTION_TAG_DISCOVERED intents. |
static String |
EXTRA_NDEF_MESSAGES
Extra containing an array of
NdefMessage present on the discovered tag. |
static String |
EXTRA_TAG
Mandatory extra containing the
Tag that was discovered for the
ACTION_NDEF_DISCOVERED , ACTION_TECH_DISCOVERED , and
ACTION_TAG_DISCOVERED intents. |
static int |
HANDOVER_TRANSFER_STATUS_FAILURE |
static int |
HANDOVER_TRANSFER_STATUS_SUCCESS |
static int |
STATE_OFF |
static int |
STATE_ON |
static int |
STATE_TURNING_OFF |
static int |
STATE_TURNING_ON |
Modifier and Type | Method and Description |
---|---|
void |
attemptDeadServiceRecovery(Exception e)
NFC service dead - attempt best effort recovery
|
boolean |
disable()
Disable NFC hardware.
|
void |
disableForegroundDispatch(Activity activity)
Disable foreground dispatch to the given activity.
|
void |
disableForegroundNdefPush(Activity activity)
Deprecated.
|
boolean |
disableNdefPush()
Disable NDEF Push feature.
|
void |
dispatch(Tag tag)
Inject a mock NFC tag.
|
boolean |
enable()
Enable NFC hardware.
|
void |
enableForegroundDispatch(Activity activity,
PendingIntent intent,
IntentFilter[] filters,
String[][] techLists)
Enable foreground dispatch to the given Activity.
|
void |
enableForegroundNdefPush(Activity activity,
NdefMessage message)
Deprecated.
|
boolean |
enableNdefPush()
Enable NDEF Push feature.
|
int |
getAdapterState()
Return the state of this NFC Adapter.
|
Context |
getContext() |
static NfcAdapter |
getDefaultAdapter()
Deprecated.
|
static NfcAdapter |
getDefaultAdapter(Context context)
Helper to get the default NFC Adapter.
|
static NfcAdapter |
getNfcAdapter(Context context)
Returns the NfcAdapter for application context,
or throws if NFC is not available.
|
INfcAdapterExtras |
getNfcAdapterExtrasInterface() |
INfcAdapter |
getService()
Returns the binder interface to the service.
|
INfcTag |
getTagService()
Returns the binder interface to the tag service.
|
boolean |
isEnabled()
Return true if this NFC Adapter has any features enabled.
|
boolean |
isNdefPushEnabled()
Return true if the NDEF Push (Android Beam) feature is enabled.
|
void |
setBeamPushUris(Uri[] uris,
Activity activity)
Set one or more
Uri s to send using Android Beam (TM). |
void |
setBeamPushUrisCallback(NfcAdapter.CreateBeamUrisCallback callback,
Activity activity)
Set a callback that will dynamically generate one or more
Uri s
to send using Android Beam (TM). |
void |
setNdefPushMessage(NdefMessage message,
Activity activity,
Activity... activities)
Set a static
NdefMessage to send using Android Beam (TM). |
void |
setNdefPushMessageCallback(NfcAdapter.CreateNdefMessageCallback callback,
Activity activity,
Activity... activities)
Set a callback that dynamically generates NDEF messages to send using Android Beam (TM).
|
void |
setOnNdefPushCompleteCallback(NfcAdapter.OnNdefPushCompleteCallback callback,
Activity activity,
Activity... activities)
Set a callback on successful Android Beam (TM).
|
void |
setP2pModes(int initiatorModes,
int targetModes) |
public static final String ACTION_NDEF_DISCOVERED
The system inspects the first NdefRecord
in the first NdefMessage
and
looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the
intent will contain the URI in its data field. If a MIME record is found the intent will
contain the MIME type in its type field. This allows activities to register
IntentFilter
s targeting specific content on tags. Activities should register the
most specific intent filters possible to avoid the activity chooser dialog, which can
disrupt the interaction with the tag as the user interacts with the screen.
If the tag has an NDEF payload this intent is started before
ACTION_TECH_DISCOVERED
. If any activities respond to this intent neither
ACTION_TECH_DISCOVERED
or ACTION_TAG_DISCOVERED
will be started.
The MIME type or data URI of this intent are normalized before dispatch - so that MIME, URI scheme and URI host are always lower-case.
public static final String ACTION_TECH_DISCOVERED
To receive this intent an activity must include an intent filter
for this action and specify the desired tech types in a
manifest meta-data
entry. Here is an example manfiest entry:
<activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter"> <!-- Add a technology filter --> <intent-filter> <action android:name="android.nfc.action.TECH_DISCOVERED" /> </intent-filter> <meta-data android:name="android.nfc.action.TECH_DISCOVERED" android:resource="@xml/filter_nfc" /> </activity>
The meta-data XML file should contain one or more tech-list
entries
each consisting or one or more tech
entries. The tech
entries refer
to the qualified class name implementing the technology, for example "android.nfc.tech.NfcA".
A tag matches if any of the
tech-list
sets is a subset of Tag.getTechList()
. Each
of the tech-list
s is considered independently and the
activity is considered a match is any single tech-list
matches the tag that was
discovered. This provides AND and OR semantics for filtering desired techs. Here is an
example that will match any tag using NfcF
or any tag using NfcA
,
MifareClassic
, and Ndef
:
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2"> <!-- capture anything using NfcF --> <tech-list> <tech>android.nfc.tech.NfcF</tech> </tech-list> <!-- OR --> <!-- capture all MIFARE Classics with NDEF payloads --> <tech-list> <tech>android.nfc.tech.NfcA</tech> <tech>android.nfc.tech.MifareClassic</tech> <tech>android.nfc.tech.Ndef</tech> </tech-list> </resources>
This intent is started after ACTION_NDEF_DISCOVERED
and before
ACTION_TAG_DISCOVERED
. If any activities respond to ACTION_NDEF_DISCOVERED
this intent will not be started. If any activities respond to this intent
ACTION_TAG_DISCOVERED
will not be started.
public static final String ACTION_TAG_DISCOVERED
This intent will not be started when a tag is discovered if any activities respond to
ACTION_NDEF_DISCOVERED
or ACTION_TECH_DISCOVERED
for the current tag.
public static final String ACTION_TAG_LEFT_FIELD
public static final String EXTRA_TAG
Tag
that was discovered for the
ACTION_NDEF_DISCOVERED
, ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.public static final String EXTRA_NDEF_MESSAGES
NdefMessage
present on the discovered tag.
This extra is mandatory for ACTION_NDEF_DISCOVERED
intents,
and optional for ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.
When this extra is present there will always be at least one
NdefMessage
element. Most NDEF tags have only one NDEF message,
but we use an array for future compatibility.
public static final String EXTRA_ID
ACTION_NDEF_DISCOVERED
, ACTION_TECH_DISCOVERED
, and
ACTION_TAG_DISCOVERED
intents.public static final String ACTION_ADAPTER_STATE_CHANGED
For example, NFC has been turned on or off.
Always contains the extra field #EXTRA_STATE
public static final String EXTRA_ADAPTER_STATE
#ACTION_STATE_CHANGED
intents to request the current power state. Possible values are:
STATE_OFF
,
STATE_TURNING_ON
,
STATE_ON
,
STATE_TURNING_OFF
,public static final int STATE_OFF
public static final int STATE_TURNING_ON
public static final int STATE_ON
public static final int STATE_TURNING_OFF
public static final String ACTION_HANDOVER_TRANSFER_STARTED
public static final String ACTION_HANDOVER_TRANSFER_DONE
public static final String EXTRA_HANDOVER_TRANSFER_STATUS
public static final int HANDOVER_TRANSFER_STATUS_SUCCESS
public static final int HANDOVER_TRANSFER_STATUS_FAILURE
public static final String EXTRA_HANDOVER_TRANSFER_URI
public static NfcAdapter getNfcAdapter(Context context)
public static NfcAdapter getDefaultAdapter(Context context)
Most Android devices will only have one NFC Adapter (NFC Controller).
This helper is the equivalent of:
NfcManager manager = (NfcManager) context.getSystemService(Context.NFC_SERVICE); NfcAdapter adapter = manager.getDefaultAdapter();
context
- the calling application's context@Deprecated public static NfcAdapter getDefaultAdapter()
getDefaultAdapter(Context)
getDefaultAdapter(Context)
instead.This method was deprecated at API level 10 (Gingerbread MR1) because a context is required for many NFC API methods. Those methods will fail when called on an NfcAdapter object created from this method.
public Context getContext()
public INfcAdapter getService()
public INfcTag getTagService()
public void attemptDeadServiceRecovery(Exception e)
public boolean isEnabled()
If this method returns false, the NFC hardware is guaranteed not to generate or respond to any NFC communication over its NFC radio.
Applications can use this to check if NFC is enabled. Applications can request Settings UI allowing the user to toggle NFC using:
startActivity(new Intent(Settings.ACTION_NFC_SETTINGS))
Settings.ACTION_NFC_SETTINGS
public int getAdapterState()
Returns one of STATE_ON
, STATE_TURNING_ON
,
STATE_OFF
, STATE_TURNING_OFF
.
isEnabled()
is equivalent to
getAdapterState()
== STATE_ON
public boolean enable()
This call is asynchronous. Listen for
ACTION_ADAPTER_STATE_CHANGED
broadcasts to find out when the
operation is complete.
If this returns true, then either NFC is already on, or
a ACTION_ADAPTER_STATE_CHANGED
broadcast will be sent
to indicate a state transition. If this returns false, then
there is some problem that prevents an attempt to turn
NFC on (for example we are in airplane mode and NFC is not
toggleable in airplane mode on this platform).
public boolean disable()
No NFC features will work after this call, and the hardware will not perform or respond to any NFC communication.
This call is asynchronous. Listen for
ACTION_ADAPTER_STATE_CHANGED
broadcasts to find out when the
operation is complete.
If this returns true, then either NFC is already off, or
a ACTION_ADAPTER_STATE_CHANGED
broadcast will be sent
to indicate a state transition. If this returns false, then
there is some problem that prevents an attempt to turn
NFC off.
public void setBeamPushUris(Uri[] uris, Activity activity)
Uri
s to send using Android Beam (TM). Every
Uri you provide must have either scheme 'file' or scheme 'content'.
For the data provided through this method, Android Beam tries to switch to alternate transports such as Bluetooth to achieve a fast transfer speed. Hence this method is very suitable for transferring large files such as pictures or songs.
The receiving side will store the content of each Uri in
a file and present a notification to the user to open the file
with a Intent
with action
Intent.ACTION_VIEW
.
If multiple URIs are sent, the Intent
will refer
to the first of the stored files.
This method may be called at any time before Activity.onDestroy()
,
but the URI(s) are only made available for Android Beam when the
specified activity(s) are in resumed (foreground) state. The recommended
approach is to call this method during your Activity's
Activity.onCreate(android.os.Bundle)
- see sample
code below. This method does not immediately perform any I/O or blocking work,
so is safe to call on your main thread.
setBeamPushUris(android.net.Uri[], android.app.Activity)
and setBeamPushUrisCallback(android.nfc.NfcAdapter.CreateBeamUrisCallback, android.app.Activity)
have priority over both setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
and
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
.
If setBeamPushUris(android.net.Uri[], android.app.Activity)
is called with a null Uri array,
and/or setBeamPushUrisCallback(android.nfc.NfcAdapter.CreateBeamUrisCallback, android.app.Activity)
is called with a null callback,
then the Uri push will be completely disabled for the specified activity(s).
Code example:
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this); if (nfcAdapter == null) return; // NFC not available on this device nfcAdapter.setBeamPushUris(new Uri[] {uri1, uri2}, this); }And that is it. Only one call per activity is necessary. The Android OS will automatically release its references to the Uri(s) and the Activity object when it is destroyed if you follow this pattern.
If your Activity wants to dynamically supply Uri(s),
then set a callback using setBeamPushUrisCallback(android.nfc.NfcAdapter.CreateBeamUrisCallback, android.app.Activity)
instead
of using this method.
Do not pass in an Activity that has already been through
Activity.onDestroy()
. This is guaranteed if you call this API
during Activity.onCreate(android.os.Bundle)
.
If this device does not support alternate transports such as Bluetooth or WiFI, calling this method does nothing.
Requires the android.Manifest.permission#NFC
permission.
uris
- an array of Uri(s) to push over Android Beamactivity
- activity for which the Uri(s) will be pushedpublic void setBeamPushUrisCallback(NfcAdapter.CreateBeamUrisCallback callback, Activity activity)
Uri
s
to send using Android Beam (TM). Every Uri the callback provides
must have either scheme 'file' or scheme 'content'.
For the data provided through this callback, Android Beam tries to switch to alternate transports such as Bluetooth to achieve a fast transfer speed. Hence this method is very suitable for transferring large files such as pictures or songs.
The receiving side will store the content of each Uri in
a file and present a notification to the user to open the file
with a Intent
with action
Intent.ACTION_VIEW
.
If multiple URIs are sent, the Intent
will refer
to the first of the stored files.
This method may be called at any time before Activity.onDestroy()
,
but the URI(s) are only made available for Android Beam when the
specified activity(s) are in resumed (foreground) state. The recommended
approach is to call this method during your Activity's
Activity.onCreate(android.os.Bundle)
- see sample
code below. This method does not immediately perform any I/O or blocking work,
so is safe to call on your main thread.
setBeamPushUris(android.net.Uri[], android.app.Activity)
and setBeamPushUrisCallback(android.nfc.NfcAdapter.CreateBeamUrisCallback, android.app.Activity)
have priority over both setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
and
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
.
If setBeamPushUris(android.net.Uri[], android.app.Activity)
is called with a null Uri array,
and/or setBeamPushUrisCallback(android.nfc.NfcAdapter.CreateBeamUrisCallback, android.app.Activity)
is called with a null callback,
then the Uri push will be completely disabled for the specified activity(s).
Code example:
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this); if (nfcAdapter == null) return; // NFC not available on this device nfcAdapter.setBeamPushUrisCallback(callback, this); }And that is it. Only one call per activity is necessary. The Android OS will automatically release its references to the Uri(s) and the Activity object when it is destroyed if you follow this pattern.
Do not pass in an Activity that has already been through
Activity.onDestroy()
. This is guaranteed if you call this API
during Activity.onCreate(android.os.Bundle)
.
If this device does not support alternate transports such as Bluetooth or WiFI, calling this method does nothing.
Requires the android.Manifest.permission#NFC
permission.
callback
- callback, or null to disableactivity
- activity for which the Uri(s) will be pushedpublic void setNdefPushMessage(NdefMessage message, Activity activity, Activity... activities)
NdefMessage
to send using Android Beam (TM).
This method may be called at any time before Activity.onDestroy()
,
but the NDEF message is only made available for NDEF push when the
specified activity(s) are in resumed (foreground) state. The recommended
approach is to call this method during your Activity's
Activity.onCreate(android.os.Bundle)
- see sample
code below. This method does not immediately perform any I/O or blocking work,
so is safe to call on your main thread.
Only one NDEF message can be pushed by the currently resumed activity.
If both setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
and
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
are set, then
the callback will take priority.
If neither setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
or
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
have been called for your activity, then
the Android OS may choose to send a default NDEF message on your behalf,
such as a URI for your application.
If setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
is called with a null NDEF message,
and/or setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
is called with a null callback,
then NDEF push will be completely disabled for the specified activity(s).
This also disables any default NDEF message the Android OS would have
otherwise sent on your behalf for those activity(s).
If you want to prevent the Android OS from sending default NDEF
messages completely (for all activities), you can include a
<meta-data>
element inside the <application>
element of your AndroidManifest.xml file, like this:
<application ...> <meta-data android:name="android.nfc.disable_beam_default" android:value="true" /> </application>
The API allows for multiple activities to be specified at a time,
but it is strongly recommended to just register one at a time,
and to do so during the activity's Activity.onCreate(android.os.Bundle)
. For example:
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this); if (nfcAdapter == null) return; // NFC not available on this device nfcAdapter.setNdefPushMessage(ndefMessage, this); }And that is it. Only one call per activity is necessary. The Android OS will automatically release its references to the NDEF message and the Activity object when it is destroyed if you follow this pattern.
If your Activity wants to dynamically generate an NDEF message,
then set a callback using setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
instead
of a static message.
Do not pass in an Activity that has already been through
Activity.onDestroy()
. This is guaranteed if you call this API
during Activity.onCreate(android.os.Bundle)
.
For sending large content such as pictures and songs,
consider using setBeamPushUris(android.net.Uri[], android.app.Activity)
, which switches to alternate transports
such as Bluetooth to achieve a fast transfer rate.
Requires the android.Manifest.permission#NFC
permission.
message
- NDEF message to push over NFC, or null to disableactivity
- activity for which the NDEF message will be pushedactivities
- optional additional activities, however we strongly recommend
to only register one at a time, and to do so in that activity's
Activity.onCreate(android.os.Bundle)
public void setNdefPushMessageCallback(NfcAdapter.CreateNdefMessageCallback callback, Activity activity, Activity... activities)
This method may be called at any time before Activity.onDestroy()
,
but the NDEF message callback can only occur when the
specified activity(s) are in resumed (foreground) state. The recommended
approach is to call this method during your Activity's
Activity.onCreate(android.os.Bundle)
- see sample
code below. This method does not immediately perform any I/O or blocking work,
so is safe to call on your main thread.
Only one NDEF message can be pushed by the currently resumed activity.
If both setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
and
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
are set, then
the callback will take priority.
If neither setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
or
setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
have been called for your activity, then
the Android OS may choose to send a default NDEF message on your behalf,
such as a URI for your application.
If setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
is called with a null NDEF message,
and/or setNdefPushMessageCallback(android.nfc.NfcAdapter.CreateNdefMessageCallback, android.app.Activity, android.app.Activity...)
is called with a null callback,
then NDEF push will be completely disabled for the specified activity(s).
This also disables any default NDEF message the Android OS would have
otherwise sent on your behalf for those activity(s).
If you want to prevent the Android OS from sending default NDEF
messages completely (for all activities), you can include a
<meta-data>
element inside the <application>
element of your AndroidManifest.xml file, like this:
<application ...> <meta-data android:name="android.nfc.disable_beam_default" android:value="true" /> </application>
The API allows for multiple activities to be specified at a time,
but it is strongly recommended to just register one at a time,
and to do so during the activity's Activity.onCreate(android.os.Bundle)
. For example:
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this); if (nfcAdapter == null) return; // NFC not available on this device nfcAdapter.setNdefPushMessageCallback(callback, this); }And that is it. Only one call per activity is necessary. The Android OS will automatically release its references to the callback and the Activity object when it is destroyed if you follow this pattern.
Do not pass in an Activity that has already been through
Activity.onDestroy()
. This is guaranteed if you call this API
during Activity.onCreate(android.os.Bundle)
.
For sending large content such as pictures and songs,
consider using setBeamPushUris(android.net.Uri[], android.app.Activity)
, which switches to alternate transports
such as Bluetooth to achieve a fast transfer rate.
Requires the android.Manifest.permission#NFC
permission.
callback
- callback, or null to disableactivity
- activity for which the NDEF message will be pushedactivities
- optional additional activities, however we strongly recommend
to only register one at a time, and to do so in that activity's
Activity.onCreate(android.os.Bundle)
public void setOnNdefPushCompleteCallback(NfcAdapter.OnNdefPushCompleteCallback callback, Activity activity, Activity... activities)
This method may be called at any time before Activity.onDestroy()
,
but the callback can only occur when the
specified activity(s) are in resumed (foreground) state. The recommended
approach is to call this method during your Activity's
Activity.onCreate(android.os.Bundle)
- see sample
code below. This method does not immediately perform any I/O or blocking work,
so is safe to call on your main thread.
The API allows for multiple activities to be specified at a time,
but it is strongly recommended to just register one at a time,
and to do so during the activity's Activity.onCreate(android.os.Bundle)
. For example:
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); NfcAdapter nfcAdapter = NfcAdapter.getDefaultAdapter(this); if (nfcAdapter == null) return; // NFC not available on this device nfcAdapter.setOnNdefPushCompleteCallback(callback, this); }And that is it. Only one call per activity is necessary. The Android OS will automatically release its references to the callback and the Activity object when it is destroyed if you follow this pattern.
Do not pass in an Activity that has already been through
Activity.onDestroy()
. This is guaranteed if you call this API
during Activity.onCreate(android.os.Bundle)
.
Requires the android.Manifest.permission#NFC
permission.
callback
- callback, or null to disableactivity
- activity for which the NDEF message will be pushedactivities
- optional additional activities, however we strongly recommend
to only register one at a time, and to do so in that activity's
Activity.onCreate(android.os.Bundle)
public void enableForegroundDispatch(Activity activity, PendingIntent intent, IntentFilter[] filters, String[][] techLists)
This will give give priority to the foreground activity when
dispatching a discovered Tag
to an application.
If any IntentFilters are provided to this method they are used to match dispatch Intents
for both the ACTION_NDEF_DISCOVERED
and
ACTION_TAG_DISCOVERED
. Since ACTION_TECH_DISCOVERED
relies on meta data outside of the IntentFilter matching for that dispatch Intent is handled
by passing in the tech lists separately. Each first level entry in the tech list represents
an array of technologies that must all be present to match. If any of the first level sets
match then the dispatch is routed through the given PendingIntent. In other words, the second
level is ANDed together and the first level entries are ORed together.
If you pass null
for both the filters
and techLists
parameters
that acts a wild card and will cause the foreground activity to receive all tags via the
ACTION_TAG_DISCOVERED
intent.
This method must be called from the main thread, and only when the activity is in the
foreground (resumed). Also, activities must call disableForegroundDispatch(android.app.Activity)
before
the completion of their Activity.onPause()
callback to disable foreground dispatch
after it has been enabled.
Requires the android.Manifest.permission#NFC
permission.
activity
- the Activity to dispatch tointent
- the PendingIntent to start for the dispatchfilters
- the IntentFilters to override dispatching for, or null to always dispatchtechLists
- the tech lists used to perform matching for dispatching of the
ACTION_TECH_DISCOVERED
intentIllegalStateException
- if the Activity is not currently in the foregroundpublic void disableForegroundDispatch(Activity activity)
After calling enableForegroundDispatch(android.app.Activity, android.app.PendingIntent, android.content.IntentFilter[], java.lang.String[][])
, an activity
must call this method before its Activity.onPause()
callback
completes.
This method must be called from the main thread.
Requires the android.Manifest.permission#NFC
permission.
activity
- the Activity to disable dispatch toIllegalStateException
- if the Activity has already been paused@Deprecated public void enableForegroundNdefPush(Activity activity, NdefMessage message)
setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
insteadYou must explicitly call this method every time the activity is
resumed, and you must call disableForegroundNdefPush(android.app.Activity)
before
your activity completes Activity.onPause()
.
Strongly recommend to use the new setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
instead: it automatically hooks into your activity life-cycle,
so you do not need to call enable/disable in your onResume/onPause.
For NDEF push to function properly the other NFC device must support either NFC Forum's SNEP (Simple Ndef Exchange Protocol), or Android's "com.android.npp" (Ndef Push Protocol). This was optional on Gingerbread level Android NFC devices, but SNEP is mandatory on Ice-Cream-Sandwich and beyond.
This method must be called from the main thread.
Requires the android.Manifest.permission#NFC
permission.
activity
- foreground activitymessage
- a NDEF Message to push over NFCIllegalStateException
- if the activity is not currently in the foreground@Deprecated public void disableForegroundNdefPush(Activity activity)
setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
insteadAfter calling enableForegroundNdefPush(android.app.Activity, android.nfc.NdefMessage)
, an activity
must call this method before its Activity.onPause()
callback
completes.
Strongly recommend to use the new setNdefPushMessage(android.nfc.NdefMessage, android.app.Activity, android.app.Activity...)
instead: it automatically hooks into your activity life-cycle,
so you do not need to call enable/disable in your onResume/onPause.
This method must be called from the main thread.
Requires the android.Manifest.permission#NFC
permission.
activity
- the Foreground activityIllegalStateException
- if the Activity has already been pausedpublic boolean enableNdefPush()
This API is for the Settings application.
public boolean disableNdefPush()
This API is for the Settings application.
public boolean isNdefPushEnabled()
This function will return true only if both NFC is enabled, and the NDEF Push feature is enabled.
Note that if NFC is enabled but NDEF Push is disabled then this device can still receive NDEF messages, it just cannot send them.
Applications cannot directly toggle the NDEF Push feature, but they
can request Settings UI allowing the user to toggle NDEF Push using
startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS))
Example usage in an Activity that requires NDEF Push:
protected void onResume() { super.onResume(); if (!nfcAdapter.isEnabled()) { startActivity(new Intent(Settings.ACTION_NFC_SETTINGS)); } else if (!nfcAdapter.isNdefPushEnabled()) { startActivity(new Intent(Settings.ACTION_NFCSHARING_SETTINGS)); } }
Settings.ACTION_NFCSHARING_SETTINGS
public void dispatch(Tag tag)
Used for testing purposes.
Requires the
android.Manifest.permission#WRITE_SECURE_SETTINGS
permission.
public void setP2pModes(int initiatorModes, int targetModes)
public INfcAdapterExtras getNfcAdapterExtrasInterface()