[NAN] Udpate NAN API documentation, clean-up visibility
am: 2e37b06dde
Change-Id: Iba3682d9ce1a3d2d1bd07636ef7c633d8e7ed847
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 467eb89..e9b6041 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -3156,7 +3156,7 @@
/**
* Use with {@link #getSystemService} to retrieve a
* {@link android.net.wifi.nan.WifiNanManager} for handling management of
- * Wi-Fi NAN discovery and connections.
+ * Wi-Fi NAN.
*
* @see #getSystemService
* @see android.net.wifi.nan.WifiNanManager
diff --git a/core/java/android/content/pm/PackageManager.java b/core/java/android/content/pm/PackageManager.java
index e8f0845..a6f6220 100644
--- a/core/java/android/content/pm/PackageManager.java
+++ b/core/java/android/content/pm/PackageManager.java
@@ -2040,8 +2040,7 @@
/**
* Feature for {@link #getSystemAvailableFeatures} and
- * {@link #hasSystemFeature}: The device supports Wi-Fi Aware (NAN)
- * networking.
+ * {@link #hasSystemFeature}: The device supports Wi-Fi NAN.
*
* @hide PROPOSED_NAN_API
*/
diff --git a/wifi/java/android/net/wifi/nan/ConfigRequest.java b/wifi/java/android/net/wifi/nan/ConfigRequest.java
index cd47359..4063af0 100644
--- a/wifi/java/android/net/wifi/nan/ConfigRequest.java
+++ b/wifi/java/android/net/wifi/nan/ConfigRequest.java
@@ -23,9 +23,9 @@
/**
* Defines a request object to configure a Wi-Fi NAN network. Built using
* {@link ConfigRequest.Builder}. Configuration is requested using
- * {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback, ConfigRequest)}
- * . Note that the actual achieved configuration may be different from the
- * requested configuration - since multiple applications may request different
+ * {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback, ConfigRequest)}.
+ * Note that the actual achieved configuration may be different from the
+ * requested configuration - since different applications may request different
* configurations.
*
* @hide PROPOSED_NAN_API
@@ -155,6 +155,7 @@
* @param o Object to compare to.
* @return true if configuration objects have the same on-the-air
* configuration, false otherwise.
+ *
* @hide
*/
public boolean equalsOnTheAir(Object o) {
@@ -186,7 +187,7 @@
}
/**
- * Validates that the contents of the ConfigRequest are valid. Otherwise
+ * Verifies that the contents of the ConfigRequest are valid. Otherwise
* throws an IllegalArgumentException.
*
* @hide
@@ -229,11 +230,13 @@
private boolean mEnableIdentityChangeCallback = false;
/**
- * Specify whether 5G band support is required in this request.
+ * Specify whether 5G band support is required in this request. Disabled by default.
*
* @param support5gBand Support for 5G band is required.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
+ *
* @hide PROPOSED_NAN_SYSTEM_API
*/
public Builder setSupport5gBand(boolean support5gBand) {
@@ -242,12 +245,14 @@
}
/**
- * Specify the Master Preference requested. The permitted range is 0 to
+ * Specify the Master Preference requested. The permitted range is 0 (the default) to
* 255 with 1 and 255 excluded (reserved).
*
* @param masterPreference The requested master preference
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
+ *
* @hide PROPOSED_NAN_SYSTEM_API
*/
public Builder setMasterPreference(int masterPreference) {
@@ -268,13 +273,15 @@
* The Cluster ID is generated randomly for new NAN networks. Specify
* the lower range of the cluster ID. The upper range is specified using
* the {@link ConfigRequest.Builder#setClusterHigh(int)}. The permitted
- * range is 0 to the value specified by
- * {@link ConfigRequest.Builder#setClusterHigh(int)}. Equality is
+ * range is 0 (the default) to the value specified by
+ * {@link ConfigRequest.Builder#setClusterHigh(int)}. Equality of Low and High is
* permitted which restricts the Cluster ID to the specified value.
*
* @param clusterLow The lower range of the generated cluster ID.
+ *
* @return The builder to facilitate chaining
* {@code builder.setClusterLow(..).setClusterHigh(..)}.
+ *
* @hide PROPOSED_NAN_SYSTEM_API
*/
public Builder setClusterLow(int clusterLow) {
@@ -294,12 +301,14 @@
* the lower upper of the cluster ID. The lower range is specified using
* the {@link ConfigRequest.Builder#setClusterLow(int)}. The permitted
* range is the value specified by
- * {@link ConfigRequest.Builder#setClusterLow(int)} to 0xFFFF. Equality
- * is permitted which restricts the Cluster ID to the specified value.
+ * {@link ConfigRequest.Builder#setClusterLow(int)} to 0xFFFF (the default). Equality of
+ * Low and High is permitted which restricts the Cluster ID to the specified value.
*
* @param clusterHigh The upper range of the generated cluster ID.
+ *
* @return The builder to facilitate chaining
* {@code builder.setClusterLow(..).setClusterHigh(..)}.
+ *
* @hide PROPOSED_NAN_SYSTEM_API
*/
public Builder setClusterHigh(int clusterHigh) {
@@ -315,13 +324,15 @@
}
/**
- * Indicate whether or not we want to enable the callback to the
- * listener on the event when the NAN device identity is changed. A
- * device identity is it's Discovery MAC address. Depending on use-case
- * we may want to perform some activity (e.g. re-publish). In other
- * use-cases (typically where we're silent) there's no reason to be
- * woken up repeatedly. Note that the MAC address is randomized at
- * regular intervals - so do not enable unless specifically required.
+ * Indicate whether or not we want to enable the
+ * {@link WifiNanEventCallback#onIdentityChanged(byte[])} callback. A
+ * device identity is its Discovery MAC address which is randomized at regular intervals.
+ * An application may need to know the MAC address, e.g. when using OOB (out-of-band)
+ * discovery together with NAN connections.
+ * <p>
+ * The callbacks are disabled by default since it may result in additional wake-ups
+ * of the host -
+ * increasing power.
*
* @param enableIdentityChangeCallback Enable the callback informing
* listener when identity is changed.
diff --git a/wifi/java/android/net/wifi/nan/PublishConfig.java b/wifi/java/android/net/wifi/nan/PublishConfig.java
index 3fd756e..6fac7a8 100644
--- a/wifi/java/android/net/wifi/nan/PublishConfig.java
+++ b/wifi/java/android/net/wifi/nan/PublishConfig.java
@@ -31,13 +31,14 @@
/**
* Defines the configuration of a NAN publish session. Built using
- * {@link PublishConfig.Builder}. Publish is done using
- * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} or
+ * {@link PublishConfig.Builder}. A publish session is created using
+ * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} or updated using
* {@link WifiNanPublishSession#updatePublish(PublishConfig)}.
*
* @hide PROPOSED_NAN_API
*/
public class PublishConfig implements Parcelable {
+ /** @hide */
@IntDef({
PUBLISH_TYPE_UNSOLICITED, PUBLISH_TYPE_SOLICITED })
@Retention(RetentionPolicy.SOURCE)
@@ -45,58 +46,44 @@
}
/**
- * Defines an unsolicited publish session - i.e. a publish session where
- * publish packets are transmitted over-the-air. Configuration is done using
- * {@link PublishConfig.Builder#setPublishType(int)}.
+ * Defines an unsolicited publish session - a publish session where the publisher is
+ * advertising itself by broadcasting on-the-air. An unsolicited publish session is paired
+ * with an passive subscribe session {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE}.
+ * Configuration is done using {@link PublishConfig.Builder#setPublishType(int)}.
*/
public static final int PUBLISH_TYPE_UNSOLICITED = 0;
/**
- * Defines a solicited publish session - i.e. a publish session where
- * publish packets are not transmitted over-the-air and the device listens
- * and matches to transmitted subscribe packets. Configuration is done using
+ * Defines a solicited publish session - a publish session which is silent, waiting for a
+ * matching active subscribe session - and responding to it in unicast. A
+ * solicited publish session is paired with an active subscribe session
+ * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE}. Configuration is done using
* {@link PublishConfig.Builder#setPublishType(int)}.
*/
public static final int PUBLISH_TYPE_SOLICITED = 1;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mServiceName;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mServiceSpecificInfo;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mTxFilter;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mRxFilter;
- /**
- * @hide
- */
+ /** @hide */
public final int mPublishType;
- /**
- * @hide
- */
+ /** @hide */
public final int mPublishCount;
- /**
- * @hide
- */
+ /** @hide */
public final int mTtlSec;
- /**
- * @hide
- */
+ /** @hide */
public final boolean mEnableTerminateNotification;
private PublishConfig(byte[] serviceName, byte[] serviceSpecificInfo,
@@ -198,7 +185,7 @@
}
/**
- * Validates that the contents of the PublishConfig are valid. Otherwise
+ * Verifies that the contents of the PublishConfig are valid. Otherwise
* throws an IllegalArgumentException.
*
* @hide
@@ -251,13 +238,16 @@
/**
* Specify the service name of the publish session. The actual on-air
* value is a 6 byte hashed representation of this string.
- *
- * Per spec: The Service Name is a UTF-8 encoded string from 1 to 255 bytes in length.
+ * <p>
+ * The Service Name is a UTF-8 encoded string from 1 to 255 bytes in length.
* The only acceptable single-byte UTF-8 symbols for a Service Name are alphanumeric
* values (A-Z, a-z, 0-9), the hyphen ('-'), and the period ('.'). All valid multi-byte
* UTF-8 characters are acceptable in a Service Name.
+ * <p>
+ * Must be called - an empty ServiceName is not valid.
*
* @param serviceName The service name for the publish session.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -272,12 +262,15 @@
/**
* Specify service specific information for the publish session. This is
* a free-form byte array available to the application to send
- * additional information as part of the discovery operation - i.e. it
+ * additional information as part of the discovery operation - it
* will not be used to determine whether a publish/subscribe match
* occurs.
+ * <p>
+ * Optional. Empty by default.
*
* @param serviceSpecificInfo A byte-array for the service-specific
* information field.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -287,13 +280,16 @@
}
/**
- * Specify service specific information for the publish session - same
- * as {@link PublishConfig.Builder#setServiceSpecificInfo(byte[])}
- * but obtaining the data from a String.
+ * Specify service specific information for the publish session - a simple wrapper
+ * of {@link PublishConfig.Builder#setServiceSpecificInfo(byte[])}
+ * obtaining the data from a String.
+ * <p>
+ * Optional. Empty by default.
*
* @param serviceSpecificInfoStr The service specific information string
* to be included (as a byte array) in the publish
* information.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -303,18 +299,20 @@
}
/**
- * The transmit filter for an active publish session
+ * Specify the transmit filter for an active publish session
* {@link PublishConfig.Builder#setPublishType(int)} and
- * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}. Included in
- * transmitted publish packets and used by receivers (subscribers) to
- * determine whether they match - in addition to just relying on the
- * service name.
+ * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}. Used to determine discovery - both
+ * Service Name and filters have to match for discovery to be triggered.
* <p>
- * Format is an LV byte array - the {@link LvBufferUtils} utility class
- * is available to form and parse.
+ * Format is an LV byte array: a single byte Length field followed by L bytes (the value of
+ * the Length field) of a value blob.
+ * </p>
+ * <p>
+ * Optional. Empty by default.
+ * </p>
*
- * @param txFilter The byte-array containing the LV formatted transmit
- * filter.
+ * @param txFilter The byte-array containing the LV formatted transmit filter.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -324,18 +322,19 @@
}
/**
- * The transmit filter for a passive publish session
+ * Specify the receive filter for a passive publish session
* {@link PublishConfig.Builder#setPublishType(int)} and
- * {@link PublishConfig#PUBLISH_TYPE_SOLICITED}. Used by the publisher
- * to determine whether they match transmitted subscriber packets
- * (active subscribers) - in addition to just relying on the service
- * name.
+ * {@link PublishConfig#PUBLISH_TYPE_SOLICITED}. Used to determine discovery - both
+ * Service Name and filters have to match for discovery to be triggered.
* <p>
- * Format is an LV byte array - the {@link LvBufferUtils} utility class
- * is available to form and parse.
+ * Format is an LV byte array: a single byte Length field followed by L bytes (the value of
+ * the Length field) of a value blob.
+ * <p>
+ * Optional. Empty by default.
*
* @param rxFilter The byte-array containing the LV formatted receive
* filter.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -345,15 +344,15 @@
}
/**
- * Sets the type of the publish session: solicited (aka active - publish
+ * Specify the type of the publish session: solicited (aka active - publish
* packets are transmitted over-the-air), or unsolicited (aka passive -
* no publish packets are transmitted, a match is made against an active
* subscribe session whose packets are transmitted over-the-air).
*
- * @param publishType Publish session type: solicited (
- * {@link PublishConfig#PUBLISH_TYPE_SOLICITED}) or
- * unsolicited (
- * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED}).
+ * @param publishType Publish session type:
+ * {@link PublishConfig#PUBLISH_TYPE_SOLICITED} or
+ * {@link PublishConfig#PUBLISH_TYPE_UNSOLICITED} (the default).
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -366,13 +365,18 @@
}
/**
- * Sets the number of times a solicited (
+ * Sets the number of times an unsolicited (configured using
* {@link PublishConfig.Builder#setPublishType(int)}) publish session
- * will transmit a packet. When the count is reached an event will be
+ * will be broadcast. When the count is reached an event will be
* generated for {@link WifiNanSessionCallback#onSessionTerminated(int)}
- * with reason={@link WifiNanSessionCallback#TERMINATE_REASON_DONE}.
+ * with {@link WifiNanSessionCallback#TERMINATE_REASON_DONE} [unless
+ * {@link #setEnableTerminateNotification(boolean)} disables the callback].
+ * <p>
+ * Optional. 0 by default - indicating the session doesn't terminate on its own.
+ * Session will be terminated when {@link WifiNanSession#terminate()} is called.
*
- * @param publishCount Number of publish packets to transmit.
+ * @param publishCount Number of publish packets to broadcast.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -385,14 +389,19 @@
}
/**
- * Sets the time interval (in seconds) a solicited (
- * {@link PublishConfig.Builder#setPublishCount(int)}) publish session
- * will be alive - i.e. transmitting a packet. When the TTL is reached
+ * Sets the time interval (in seconds) an unsolicited (
+ * {@link PublishConfig.Builder#setPublishType(int)}) publish session
+ * will be alive - broadcasting a packet. When the TTL is reached
* an event will be generated for
- * {@link WifiNanSessionCallback#onSessionTerminated(int)} with reason=
- * {@link WifiNanSessionCallback#TERMINATE_REASON_DONE}.
+ * {@link WifiNanSessionCallback#onSessionTerminated(int)} with
+ * {@link WifiNanSessionCallback#TERMINATE_REASON_DONE} [unless
+ * {@link #setEnableTerminateNotification(boolean)} disables the callback].
+ * <p>
+ * Optional. 0 by default - indicating the session doesn't terminate on its own.
+ * Session will be terminated when {@link WifiNanSession#terminate()} is called.
*
* @param ttlSec Lifetime of a publish session in seconds.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -411,6 +420,7 @@
*
* @param enable If true the terminate callback will be called when the
* publish is terminated. Otherwise it will not be called.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
diff --git a/wifi/java/android/net/wifi/nan/SubscribeConfig.java b/wifi/java/android/net/wifi/nan/SubscribeConfig.java
index fd19ddb..89a24b6 100644
--- a/wifi/java/android/net/wifi/nan/SubscribeConfig.java
+++ b/wifi/java/android/net/wifi/nan/SubscribeConfig.java
@@ -38,6 +38,7 @@
* @hide PROPOSED_NAN_API
*/
public class SubscribeConfig implements Parcelable {
+ /** @hide */
@IntDef({
SUBSCRIBE_TYPE_PASSIVE, SUBSCRIBE_TYPE_ACTIVE })
@Retention(RetentionPolicy.SOURCE)
@@ -45,7 +46,7 @@
}
/**
- * Defines a passive subscribe session - i.e. a subscribe session where
+ * Defines a passive subscribe session - a subscribe session where
* subscribe packets are not transmitted over-the-air and the device listens
* and matches to transmitted publish packets. Configuration is done using
* {@link SubscribeConfig.Builder#setSubscribeType(int)}.
@@ -53,12 +54,13 @@
public static final int SUBSCRIBE_TYPE_PASSIVE = 0;
/**
- * Defines an active subscribe session - i.e. a subscribe session where
+ * Defines an active subscribe session - a subscribe session where
* subscribe packets are transmitted over-the-air. Configuration is done
* using {@link SubscribeConfig.Builder#setSubscribeType(int)}.
*/
public static final int SUBSCRIBE_TYPE_ACTIVE = 1;
+ /** @hide */
@IntDef({
MATCH_STYLE_FIRST_ONLY, MATCH_STYLE_ALL })
@Retention(RetentionPolicy.SOURCE)
@@ -67,59 +69,43 @@
/**
* Specifies that only the first match of a set of identical matches (same
- * publish) will be reported to the subscriber.
+ * publish) will be reported to the subscriber. Configuration is done using
+ * {@link SubscribeConfig.Builder#setMatchStyle(int)}.
*/
public static final int MATCH_STYLE_FIRST_ONLY = 0;
/**
* Specifies that all matches of a set of identical matches (same publish)
- * will be reported to the subscriber.
+ * will be reported to the subscriber. Configuration is done using
+ * {@link SubscribeConfig.Builder#setMatchStyle(int)}.
*/
public static final int MATCH_STYLE_ALL = 1;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mServiceName;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mServiceSpecificInfo;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mTxFilter;
- /**
- * @hide
- */
+ /** @hide */
public final byte[] mRxFilter;
- /**
- * @hide
- */
+ /** @hide */
public final int mSubscribeType;
- /**
- * @hide
- */
+ /** @hide */
public final int mSubscribeCount;
- /**
- * @hide
- */
+ /** @hide */
public final int mTtlSec;
- /**
- * @hide
- */
+ /** @hide */
public final int mMatchStyle;
- /**
- * @hide
- */
+ /** @hide */
public final boolean mEnableTerminateNotification;
private SubscribeConfig(byte[] serviceName, byte[] serviceSpecificInfo, byte[] txFilter,
@@ -226,7 +212,7 @@
}
/**
- * Validates that the contents of the SubscribeConfig are valid. Otherwise
+ * Verifies that the contents of the SubscribeConfig are valid. Otherwise
* throws an IllegalArgumentException.
*
* @hide
@@ -284,13 +270,16 @@
/**
* Specify the service name of the subscribe session. The actual on-air
* value is a 6 byte hashed representation of this string.
- *
- * Per spec: The Service Name is a UTF-8 encoded string from 1 to 255 bytes in length.
+ * <p>
+ * The Service Name is a UTF-8 encoded string from 1 to 255 bytes in length.
* The only acceptable single-byte UTF-8 symbols for a Service Name are alphanumeric
* values (A-Z, a-z, 0-9), the hyphen ('-'), and the period ('.'). All valid multi-byte
* UTF-8 characters are acceptable in a Service Name.
+ * <p>
+ * Must be called - an empty ServiceName is not valid.
*
* @param serviceName The service name for the subscribe session.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -303,14 +292,17 @@
}
/**
- * Specify service specific information for the subscribe session. This
- * is a free-form byte array available to the application to send
+ * Specify service specific information for the subscribe session. This is
+ * a free-form byte array available to the application to send
* additional information as part of the discovery operation - i.e. it
* will not be used to determine whether a publish/subscribe match
* occurs.
+ * <p>
+ * Optional. Empty by default.
*
* @param serviceSpecificInfo A byte-array for the service-specific
* information field.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -320,14 +312,16 @@
}
/**
- * Specify service specific information for the subscribe session - same
- * as
- * {@link SubscribeConfig.Builder#setServiceSpecificInfo(byte[])}
- * but obtaining the data from a String.
+ * Specify service specific information for the subscribe session - a simple wrapper
+ * of {@link SubscribeConfig.Builder#setServiceSpecificInfo(byte[])}
+ * obtaining the data from a String.
+ * <p>
+ * Optional. Empty by default.
*
* @param serviceSpecificInfoStr The service specific information string
* to be included (as a byte array) in the subscribe
* information.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -344,11 +338,16 @@
* publishers) to determine whether they match - in addition to just
* relying on the service name.
* <p>
- * Format is an LV byte array - the {@link LvBufferUtils} utility class
- * is available to form and parse.
+ * Format is an LV byte array: a single byte Length field followed by L bytes (the value of
+ * the Length field) of a value blob.
+ * </p>
+ * <p>
+ * Optional. Empty by default.
+ * </p>
*
* @param txFilter The byte-array containing the LV formatted transmit
* filter.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -364,11 +363,14 @@
* subscriber to determine whether they match transmitted publish
* packets - in addition to just relying on the service name.
* <p>
- * Format is an LV byte array - the {@link LvBufferUtils} utility class
- * is available to form and parse.
+ * Format is an LV byte array: a single byte Length field followed by L bytes (the value of
+ * the Length field) of a value blob.
+ * <p>
+ * Optional. Empty by default.
*
* @param rxFilter The byte-array containing the LV formatted receive
* filter.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -383,9 +385,10 @@
* transmitted, a match is made against a solicited/active publish
* session whose packets are transmitted over-the-air).
*
- * @param subscribeType Subscribe session type: active (
- * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE}) or passive
- * ( {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE} ).
+ * @param subscribeType Subscribe session type:
+ * {@link SubscribeConfig#SUBSCRIBE_TYPE_ACTIVE} or
+ * {@link SubscribeConfig#SUBSCRIBE_TYPE_PASSIVE}.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -399,13 +402,16 @@
/**
* Sets the number of times an active (
- * {@link SubscribeConfig.Builder#setSubscribeType(int)}) subscribe
- * session will transmit a packet. When the count is reached an event
- * will be generated for
- * {@link WifiNanSessionCallback#onSessionTerminated(int)} with reason=
- * {@link WifiNanSessionCallback#TERMINATE_REASON_DONE}.
+ * {@link SubscribeConfig.Builder#setSubscribeType(int)}) subscribe session
+ * will broadcast. When the count is reached an event will be
+ * generated for {@link WifiNanSessionCallback#onSessionTerminated(int)}
+ * with {@link WifiNanSessionCallback#TERMINATE_REASON_DONE}.
+ * <p>
+ * Optional. 0 by default - indicating the session doesn't terminate on its own.
+ * Session will be terminated when {@link WifiNanSession#terminate()} is called.
*
- * @param subscribeCount Number of subscribe packets to transmit.
+ * @param subscribeCount Number of subscribe packets to broadcast.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -419,13 +425,17 @@
/**
* Sets the time interval (in seconds) an active (
- * {@link SubscribeConfig.Builder#setSubscribeType(int)}) subscribe
- * session will be alive - i.e. transmitting a packet. When the TTL is
- * reached an event will be generated for
- * {@link WifiNanSessionCallback#onSessionTerminated(int)} with reason=
+ * {@link SubscribeConfig.Builder#setSubscribeType(int)}) subscribe session
+ * will be alive - i.e. broadcasting a packet. When the TTL is reached
+ * an event will be generated for
+ * {@link WifiNanSessionCallback#onSessionTerminated(int)} with
* {@link WifiNanSessionCallback#TERMINATE_REASON_DONE}.
+ * <p>
+ * Optional. 0 by default - indicating the session doesn't terminate on its own.
+ * Session will be terminated when {@link WifiNanSession#terminate()} is called.
*
* @param ttlSec Lifetime of a subscribe session in seconds.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
@@ -444,7 +454,7 @@
* {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])}
* ). The options are: only report the first match and ignore the rest
* {@link SubscribeConfig#MATCH_STYLE_FIRST_ONLY} or report every single
- * match {@link SubscribeConfig#MATCH_STYLE_ALL}.
+ * match {@link SubscribeConfig#MATCH_STYLE_ALL} (the default).
*
* @param matchStyle The reporting style for the discovery match.
* @return The builder to facilitate chaining
@@ -466,6 +476,7 @@
*
* @param enable If true the terminate callback will be called when the
* subscribe is terminated. Otherwise it will not be called.
+ *
* @return The builder to facilitate chaining
* {@code builder.setXXX(..).setXXX(..)}.
*/
diff --git a/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java b/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java
index 148307d..7dd879e 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java
@@ -22,14 +22,15 @@
import java.lang.annotation.RetentionPolicy;
/**
- * Base class for NAN events callbacks. Should be extended by applications
- * wanting notifications. These are callbacks applying to the NAN connection as
- * a whole - not to specific publish or subscribe sessions - for that see
- * {@link WifiNanSessionCallback}.
+ * Base class for NAN events callbacks. Should be extended by applications and set when calling
+ * {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback)}. These are callbacks
+ * applying to the NAN connection as a whole - not to specific publish or subscribe sessions -
+ * for that see {@link WifiNanSessionCallback}.
*
* @hide PROPOSED_NAN_API
*/
public class WifiNanEventCallback {
+ /** @hide */
@IntDef({
REASON_INVALID_ARGS, REASON_ALREADY_CONNECTED_INCOMPAT_CONFIG, REASON_OTHER
})
@@ -38,31 +39,29 @@
}
/**
- * Failure reason flag for {@link WifiNanEventCallback} callbacks. Indicates
- * invalid argument in the requested operation.
+ * Indicates invalid argument in the requested operation. Failure reason flag for
+ * {@link WifiNanEventCallback#onConnectFail(int)}.
*/
public static final int REASON_INVALID_ARGS = 1000;
/**
- * Failure reason flag for {@link WifiNanEventCallback} callbacks. Indicates
- * that a {@link ConfigRequest} passed in
+ * Indicates that a {@link ConfigRequest} passed in
* {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback, ConfigRequest)}
- * couldn't be applied since other connections already exist with an
- * incompatible configurations.
+ * couldn't be applied since other connections already exist with an incompatible
+ * configurations. Failure reason flag for {@link WifiNanEventCallback#onConnectFail(int)}.
*/
public static final int REASON_ALREADY_CONNECTED_INCOMPAT_CONFIG = 1001;
/**
- * Failure reason flag for {@link WifiNanEventCallback} callbacks. Indicates
- * an unspecified error occurred during the operation.
+ * Indicates an unspecified error occurred during the operation. Failure reason flag for
+ * {@link WifiNanEventCallback#onConnectFail(int)}.
*/
- public static final int REASON_OTHER = 1003;
+ public static final int REASON_OTHER = 1002;
/**
* Called when NAN connect operation
* {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback)}
- * is completed. Doesn't necessarily mean that have joined or started a NAN
- * cluster. An indication is provided by {@link #onIdentityChanged(byte[])}.
+ * is completed and that we can now start discovery sessions or connections.
*/
public void onConnectSuccess() {
/* empty */
@@ -70,8 +69,7 @@
/**
* Called when NAN connect operation
- * {@code WifiNanManager#connect(android.os.Looper, WifiNanEventCallback)}
- * failed.
+ * {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback)} failed.
*
* @param reason Failure reason code, see
* {@code WifiNanEventCallback.REASON_*}.
@@ -81,12 +79,25 @@
}
/**
- * Called when NAN identity has changed and after {@link #onConnectSuccess()}. Call may be
- * due to joining a cluster, starting a cluster, or discovery interface change. The
- * implication is that peers you've been communicating with may no longer recognize you and
- * you need to re-establish your identity.
- * @param mac The MAC address of the NAN discovery interface. Depending on the permission
- * model may be all 0's.
+ * Called when NAN identity (the MAC address representing our NAN discovery interface) has
+ * changed. Change may be due to device joining a cluster, starting a cluster, or discovery
+ * interface change (addresses are randomized at regular intervals). The implication is that
+ * peers you've been communicating with may no longer recognize you and you need to
+ * re-establish your identity - e.g. by starting a discovery session. This actual MAC address
+ * of the interface may also be useful if the application uses alternative (non-NAN)
+ * discovery but needs to set up a NAN connection. The provided NAN discovery interface MAC
+ * address can then be used in
+ * {@link WifiNanManager#createNetworkSpecifier(int, byte[], byte[])}.
+ * <p>
+ * This callback is only called if the NAN connection enables it using
+ * {@link ConfigRequest.Builder#setEnableIdentityChangeCallback(boolean)} in
+ * {@link WifiNanManager#connect(android.os.Looper, WifiNanEventCallback, ConfigRequest)}
+ * . It is disabled by default since it may result in additional wake-ups of the host -
+ * increasing power.
+ *
+ * @param mac The MAC address of the NAN discovery interface. The application must have the
+ * {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} to get the actual MAC address,
+ * otherwise all 0's will be provided.
*/
public void onIdentityChanged(byte[] mac) {
/* empty */
diff --git a/wifi/java/android/net/wifi/nan/WifiNanManager.java b/wifi/java/android/net/wifi/nan/WifiNanManager.java
index ff6198e..e035333 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanManager.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanManager.java
@@ -52,17 +52,67 @@
import java.util.Arrays;
/**
- * This class provides the primary API for managing Wi-Fi NAN operation:
- * including discovery and data-links. Get an instance of this class by calling
+ * This class provides the primary API for managing Wi-Fi NAN operations:
+ * discovery and peer-to-peer data connections. Get an instance of this class by calling
* {@link android.content.Context#getSystemService(String)
* Context.getSystemService(Context.WIFI_NAN_SERVICE)}.
* <p>
* The class provides access to:
* <ul>
- * <li>Configure a NAN connection and register for events.
- * <li>Create publish and subscribe sessions.
- * <li>Create NAN network specifier to be used to create a NAN network.
+ * <li>Initialize a NAN cluster (peer-to-peer synchronization). Refer to
+ * {@link #connect(Looper, WifiNanEventCallback)}.
+ * <li>Create discovery sessions (publish or subscribe sessions).
+ * Refer to {@link #publish(PublishConfig, WifiNanSessionCallback)} and
+ * {@link #subscribe(SubscribeConfig, WifiNanSessionCallback)}.
+ * <li>Create a NAN network specifier to be used with
+ * {@link ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}
+ * to set-up a NAN connection with a peer. Refer to
+ * {@link WifiNanSession#createNetworkSpecifier(int, int, byte[])} and
+ * {@link #createNetworkSpecifier(int, byte[], byte[])}.
* </ul>
+ * <p>
+ * NAN may not be usable when Wi-Fi is disabled (and other conditions). To validate that
+ * the functionality is available use the {@link #isUsageEnabled()} function. To track
+ * changes in NAN usability register for the {@link #WIFI_NAN_STATE_CHANGED_ACTION} broadcast.
+ * Note that this broadcast is not sticky - you should register for it and then check the
+ * above API to avoid a race condition.
+ * <p>
+ * An application must use {@link #connect(Looper, WifiNanEventCallback)} to initialize a NAN
+ * cluster - before making any other NAN operation. NAN cluster membership is a device-wide
+ * operation - the API guarantees that the device is in a cluster or joins a NAN cluster (or
+ * starts one if none can be found). Information about connection success (or failure) are
+ * returned in callbacks of {@link WifiNanEventCallback}. Proceed with NAN discovery or
+ * connection setup only after receiving confirmation that NAN connection succeeded -
+ * {@link WifiNanEventCallback#onConnectSuccess()}.
+ * When an application is finished using NAN it <b>must</b> use the {@link #disconnect()} API
+ * to indicate to the NAN service that the device may disconnect from the NAN cluster. The
+ * device will actually disconnect from the NAN cluster once the last application disconnects.
+ * <p>
+ * Once a NAN connection is confirmed use the
+ * {@link #publish(PublishConfig, WifiNanSessionCallback)} or
+ * {@link #subscribe(SubscribeConfig, WifiNanSessionCallback)} to create publish or subscribe
+ * NAN discovery sessions. Events are called on the provided callback object
+ * {@link WifiNanSessionCallback}. Specifically, the
+ * {@link WifiNanSessionCallback#onPublishStarted(WifiNanPublishSession)} and
+ * {@link WifiNanSessionCallback#onSubscribeStarted(WifiNanSubscribeSession)} return
+ * {@link WifiNanPublishSession} and {@link WifiNanSubscribeSession} objects respectively on
+ * which additional session operations can be performed, e.g. updating the session
+ * {@link WifiNanPublishSession#updatePublish(PublishConfig)} and
+ * {@link WifiNanSubscribeSession#updateSubscribe(SubscribeConfig)}. Sessions can also be
+ * used to send messages using the {@link WifiNanSession#sendMessage(int, byte[], int)} APIs.
+ * When an application is finished with a discovery session it <b>must</b> terminate it using
+ * the {@link WifiNanSession#terminate()} API.
+ * <p>
+ * Creating connections between NAN devices is managed by the standard
+ * {@link ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}.
+ * The {@link NetworkRequest} object should be constructed with:
+ * <ul>
+ * <li>{@link NetworkRequest.Builder#addTransportType(int)} of
+ * {@link android.net.NetworkCapabilities#TRANSPORT_WIFI_NAN}.
+ * <li>{@link NetworkRequest.Builder#setNetworkSpecifier(String)} using
+ * {@link #createNetworkSpecifier(int, byte[], byte[])} or
+ * {@link WifiNanSession#createNetworkSpecifier(int, int, byte[])}.
+ * </ul>
*
* @hide PROPOSED_NAN_API
*/
@@ -126,52 +176,37 @@
*/
public static final int NETWORK_SPECIFIER_TYPE_2D = 7;
- /**
- * @hide
- */
+ /** @hide */
public static final int NETWORK_SPECIFIER_TYPE_MAX_VALID = NETWORK_SPECIFIER_TYPE_2D;
- /**
- * @hide
- */
-
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_TYPE = "type";
- /**
- * @hide
- */
-
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_ROLE = "role";
- /**
- * @hide
- */
-
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_CLIENT_ID = "client_id";
- /**
- * @hide
- */
+
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_SESSION_ID = "session_id";
- /**
- * @hide
- */
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_PEER_ID = "peer_id";
- /**
- * @hide
- */
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_PEER_MAC = "peer_mac";
- /**
- * @hide
- */
+ /** @hide */
public static final String NETWORK_SPECIFIER_KEY_TOKEN = "token";
/**
* Broadcast intent action to indicate whether Wi-Fi NAN is enabled or
* disabled. An extra {@link #EXTRA_WIFI_STATE} provides the state
- * information as int.
+ * information as int using {@link #WIFI_NAN_STATE_DISABLED} and
+ * {@link #WIFI_NAN_STATE_ENABLED} constants. This broadcast is <b>not</b> sticky,
+ * use the {@link #isUsageEnabled()} API after registering the broadcast to check the current
+ * state of Wi-Fi NAN.
*
* @see #EXTRA_WIFI_STATE
*/
@@ -179,7 +214,7 @@
public static final String WIFI_NAN_STATE_CHANGED_ACTION = "android.net.wifi.nan.STATE_CHANGED";
/**
- * The lookup key for an int that indicates whether Wi-Fi NAN is enabled or
+ * The lookup key for an int value indicating whether Wi-Fi NAN is enabled or
* disabled. Retrieve it with
* {@link android.content.Intent#getIntExtra(String,int)}.
*
@@ -202,6 +237,7 @@
*/
public static final int WIFI_NAN_STATE_ENABLED = 2;
+ /** @hide */
@IntDef({
WIFI_NAN_DATA_PATH_ROLE_INITIATOR, WIFI_NAN_DATA_PATH_ROLE_RESPONDER})
@Retention(RetentionPolicy.SOURCE)
@@ -209,18 +245,21 @@
}
/**
- * Data-path creation role is that of INITIATOR. Used in
- * {@link #createNetworkSpecifier(int, byte[], byte[])} and
- * {@link WifiNanSession#createNetworkSpecifier(int, int, byte[])}.
+ * Connection creation role is that of INITIATOR. Used to create a network specifier string
+ * when requesting a NAN network.
+ *
+ * @see WifiNanSession#createNetworkSpecifier(int, int, byte[])
+ * @see #createNetworkSpecifier(int, byte[], byte[])
*/
public static final int WIFI_NAN_DATA_PATH_ROLE_INITIATOR = 0;
/**
- * Data-path creation role is that of RESPONDER. Used in
- * {@link #createNetworkSpecifier(int, byte[], byte[])} and
- * {@link WifiNanSession#createNetworkSpecifier(int, int, byte[])}.
+ * Connection creation role is that of RESPONDER. Used to create a network specifier string
+ * when requesting a NAN network.
+ *
+ * @see WifiNanSession#createNetworkSpecifier(int, int, byte[])
+ * @see #createNetworkSpecifier(int, byte[], byte[])
*/
-
public static final int WIFI_NAN_DATA_PATH_ROLE_RESPONDER = 1;
private final Context mContext;
@@ -241,9 +280,7 @@
@GuardedBy("mLock")
private SparseArray<RttManager.RttListener> mRangingListeners = new SparseArray<>();
- /**
- * {@hide}
- */
+ /** @hide */
public WifiNanManager(Context context, IWifiNanManager service) {
mContext = context;
mService = service;
@@ -254,7 +291,7 @@
* happens when a connection is made. {@link #WIFI_NAN_STATE_CHANGED_ACTION} broadcast will be
* triggered.
*
- * @hide PROPOSED_NAN_SYSTEM_API
+ * @hide
*/
public void enableUsage() {
try {
@@ -269,7 +306,7 @@
* connections and sessions will be terminated. {@link #WIFI_NAN_STATE_CHANGED_ACTION} broadcast
* will be triggered.
*
- * @hide PROPOSED_NAN_SYSTEM_API
+ * @hide
*/
public void disableUsage() {
try {
@@ -280,7 +317,8 @@
}
/**
- * Returns the current status of NAN API: whether or not usage is enabled.
+ * Returns the current status of NAN API: whether or not usage is enabled. To track changes
+ * in the state of NAN API register for the {@link #WIFI_NAN_STATE_CHANGED_ACTION} broadcast.
*
* @return A boolean indicating whether the app can use the NAN API (true)
* or not (false).
@@ -294,8 +332,15 @@
}
/**
- * Connect to the Wi-Fi NAN service - enabling the application to execute
- * {@link WifiNanManager} APIs.
+ * Connect to the Wi-Fi NAN service - enabling the application to create discovery session or
+ * create connection to peers. The device will connect to an existing cluster if it can find
+ * one or create a new cluster (if it is the first to enable NAN in its vicinity). Results
+ * (e.g. successful connection to a cluster) are provided to the {@code callback} object.
+ * An application <b>must</b> call {@link #disconnect()} when done with the Wi-Fi NAN
+ * connection.
+ * <p>
+ * Note: a NAN cluster is a shared resource - if the device is already connected to a cluster
+ * than this function will simply indicate success immediately.
*
* @param looper The Looper on which to execute all callbacks related to the
* connection - including all sessions opened as part of this
@@ -307,9 +352,17 @@
}
/**
- * Connect to the Wi-Fi NAN service - enabling the application to execute
- * {@link WifiNanManager} APIs. Allows requesting a specific configuration
- * using {@link ConfigRequest} structure. Limited to privileged access.
+ * Connect to the Wi-Fi NAN service - enabling the application to create discovery session or
+ * create connection to peers. The device will connect to an existing cluster if it can find
+ * one or create a new cluster (if it is the first to enable NAN in its vicinity). Results
+ * (e.g. successful connection to a cluster) are provided to the {@code callback} object.
+ * An application <b>must</b> call {@link #disconnect()} when done with the Wi-Fi NAN
+ * connection. Allows requesting a specific configuration using {@link ConfigRequest}. If not
+ * necessary (default configuration should usually work) use the
+ * {@link #connect(Looper, WifiNanEventCallback)} method instead.
+ * <p>
+ * Note: a NAN cluster is a shared resource - if the device is already connected to a cluster
+ * than this function will simply indicate success immediately.
*
* @param looper The Looper on which to execute all callbacks related to the
* connection - including all sessions opened as part of this
@@ -341,12 +394,13 @@
}
/**
- * Disconnect from the Wi-Fi NAN service and destroy all outstanding
- * operations - i.e. all publish and subscribes are terminated, any
- * outstanding data-link is shut-down, and all requested NAN configurations
- * are cancelled.
+ * Disconnect from the Wi-Fi NAN service and, if no other applications are connected to NAN,
+ * also disconnect from the NAN cluster. This method destroys all outstanding operations -
+ * i.e. all publish and subscribes are terminated, and any outstanding data-links are
+ * shut-down. However, it is good practice to terminate these discovery sessions and
+ * connections explicitly before a disconnect.
* <p>
- * An application may then re-connect using
+ * An application may re-connect after a disconnect using
* {@link WifiNanManager#connect(Looper, WifiNanEventCallback)} .
*/
public void disconnect() {
@@ -375,6 +429,7 @@
}
}
+ /** @hide */
@Override
protected void finalize() throws Throwable {
try {
@@ -386,17 +441,29 @@
}
/**
- * Request a NAN publish session. The actual publish session is provided by
- * the
- * {@link WifiNanSessionCallback#onPublishStarted(WifiNanPublishSession)}
- * callback. Other results of the publish session operation will result in
- * callbacks to the indicated callback: {@link WifiNanSessionCallback
- * NanSessionCallback.on*}.
+ * Issue a request to the NAN service to create a new NAN publish discovery session, using
+ * the specified {@code publishConfig} configuration. The results of the publish operation
+ * are routed to the callbacks of {@link WifiNanSessionCallback}:
+ * <ul>
+ * <li>{@link WifiNanSessionCallback#onPublishStarted(WifiNanPublishSession)} is called
+ * when the publish session is created and provides a handle to the session. Further
+ * operations on the publish session can be executed on that object.
+ * <li>{@link WifiNanSessionCallback#onSessionConfigFail(int)} is called if the publish
+ * operation failed.
+ * </ul>
+ * <p>
+ * Other results of the publish session operations will also be routed to callbacks
+ * on the {@code callback} object. The resulting publish session can be modified using
+ * {@link WifiNanPublishSession#updatePublish(PublishConfig)}.
+ * <p>
+ * An application must use the {@link WifiNanSession#terminate()} to terminate the publish
+ * discovery session once it isn't needed. This will free resources as well terminate
+ * any on-air transmissions.
*
* @param publishConfig The {@link PublishConfig} specifying the
- * configuration of the publish session.
- * @param callback The {@link WifiNanSessionCallback} derived objects to be
- * used for the event callbacks specified by {@code events}.
+ * configuration of the requested publish session.
+ * @param callback A {@link WifiNanSessionCallback} derived object to be used for session
+ * event callbacks.
*/
public void publish(@NonNull PublishConfig publishConfig,
@NonNull WifiNanSessionCallback callback) {
@@ -422,9 +489,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public void updatePublish(int sessionId, PublishConfig publishConfig) {
if (VDBG) Log.v(TAG, "updatePublish(): config=" + publishConfig);
@@ -445,17 +510,29 @@
}
/**
- * Request a NAN subscribe session. The actual subscribe session is provided
- * by the
- * {@link WifiNanSessionCallback#onSubscribeStarted(WifiNanSubscribeSession)}
- * callback. Other results of the subscribe session operation will result in
- * callbacks to the indicated callback: {@link WifiNanSessionCallback
- * NanSessionCallback.on*}
+ * Issue a request to the NAN service to create a new NAN subscribe discovery session, using
+ * the specified {@code subscribeConfig} configuration. The results of the subscribe
+ * operation are routed to the callbacks of {@link WifiNanSessionCallback}:
+ * <ul>
+ * <li>{@link WifiNanSessionCallback#onSubscribeStarted(WifiNanSubscribeSession)} is called
+ * when the subscribe session is created and provides a handle to the session. Further
+ * operations on the subscribe session can be executed on that object.
+ * <li>{@link WifiNanSessionCallback#onSessionConfigFail(int)} is called if the subscribe
+ * operation failed.
+ * </ul>
+ * <p>
+ * Other results of the subscribe session operations will also be routed to callbacks
+ * on the {@code callback} object. The resulting subscribe session can be modified using
+ * {@link WifiNanSubscribeSession#updateSubscribe(SubscribeConfig)}.
+ * <p>
+ * An application must use the {@link WifiNanSession#terminate()} to terminate the
+ * subscribe discovery session once it isn't needed. This will free resources as well
+ * terminate any on-air transmissions.
*
* @param subscribeConfig The {@link SubscribeConfig} specifying the
- * configuration of the subscribe session.
- * @param callback The {@link WifiNanSessionCallback} derived objects to be
- * used for the event callbacks specified by {@code events}.
+ * configuration of the requested subscribe session.
+ * @param callback A {@link WifiNanSessionCallback} derived object to be used for session
+ * event callbacks.
*/
public void subscribe(@NonNull SubscribeConfig subscribeConfig,
@NonNull WifiNanSessionCallback callback) {
@@ -484,9 +561,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public void updateSubscribe(int sessionId, SubscribeConfig subscribeConfig) {
if (VDBG) {
Log.v(TAG, "subscribe(): config=" + subscribeConfig);
@@ -510,9 +585,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public void terminateSession(int sessionId) {
if (DBG) Log.d(TAG, "Terminate NAN session #" + sessionId);
@@ -534,9 +607,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public void sendMessage(int sessionId, int peerId, byte[] message, int messageId,
int retryCount) {
if (VDBG) {
@@ -561,9 +632,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public void startRanging(int sessionId, RttManager.RttParams[] params,
RttManager.RttListener listener) {
if (VDBG) {
@@ -594,9 +663,7 @@
}
}
- /**
- * {@hide}
- */
+ /** @hide */
public String createNetworkSpecifier(@DataPathRole int role, int sessionId, int peerId,
byte[] token) {
if (VDBG) {
@@ -667,20 +734,29 @@
}
/**
- * Create a {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} for a
- * WiFi NAN data-path connection to the specified peer. The peer MAC cannot be obtained
- * through {@link WifiNanManager} services - but could be obtained out-of-bound - it refers
- * to the MAC address of the NAN discovery interface of the peer NAN device.
+ * Create a {@link NetworkRequest.Builder#setNetworkSpecifier(String)} for a
+ * WiFi NAN connection to the specified peer. The
+ * {@link NetworkRequest.Builder#addTransportType(int)} should be set to
+ * {@link android.net.NetworkCapabilities#TRANSPORT_WIFI_NAN}.
+ * <p>
+ * This API is targeted for applications which can obtain the peer MAC address using OOB
+ * (out-of-band) discovery. NAN discovery does not provide the MAC address of the peer -
+ * when using NAN discovery use the alternative network specifier method -
+ * {@link WifiNanSession#createNetworkSpecifier(int, int, byte[])}.
*
* @param role The role of this device:
* {@link WifiNanManager#WIFI_NAN_DATA_PATH_ROLE_INITIATOR} or
* {@link WifiNanManager#WIFI_NAN_DATA_PATH_ROLE_RESPONDER}
- * @param peer The MAC address of the peer's NAN discovery interface. A null is permitted
- * for a RESPONDER - which implies that any peer can connect.
- * @param token An arbitrary token (message) to be passed to the peer as part of the
- * data-path setup process. On the RESPONDER a null token is permitted and
- * matches any peer token - an empty token requires the peer token to be empty
- * as well.
+ * @param peer The MAC address of the peer's NAN discovery interface. On a RESPONDER this
+ * value is used to gate the acceptance of a connection request from only that
+ * peer. A RESPONDER may specified a null - indicating that it will accept
+ * connection requests from any device.
+ * @param token An arbitrary token (message) to be used to match connection initiation request
+ * to a responder setup. A RESPONDER is set up with a {@code token} which must
+ * be matched by the token provided by the INITIATOR. A null token is permitted
+ * on the RESPONDER and matches any peer token. An empty ({@code ""}) token is
+ * not the same as a null token and requires the peer token to be empty as well.
+ *
* @return A string to be used to construct
* {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to {@link
* android.net.ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}
@@ -784,7 +860,7 @@
/**
* Constructs a {@link WifiNanEventCallback} using the specified looper.
- * I.e. all callbacks will delivered on the thread of the specified looper.
+ * All callbacks will delivered on the thread of the specified looper.
*
* @param looper The looper on which to execute the callbacks.
*/
diff --git a/wifi/java/android/net/wifi/nan/WifiNanPublishSession.java b/wifi/java/android/net/wifi/nan/WifiNanPublishSession.java
index a0e3fba..ccd7fae 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanPublishSession.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanPublishSession.java
@@ -20,30 +20,37 @@
import android.util.Log;
/**
- * A representation of a NAN publish session. Created when
- * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} is
- * executed. The object can be used to stop and re-start (re-configure) the
- * publish session.
+ * A class representing a NAN publish session. Created when
+ * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} is called and a
+ * discovery session is created and returned in
+ * {@link WifiNanSessionCallback#onPublishStarted(WifiNanPublishSession)}. See baseline
+ * functionality of all discovery sessions in {@link WifiNanSession}. This object allows updating
+ * an existing/running publish discovery session using {@link #updatePublish(PublishConfig)}.
*
* @hide PROPOSED_NAN_API
*/
public class WifiNanPublishSession extends WifiNanSession {
private static final String TAG = "WifiNanPublishSession";
- /**
- * {@hide}
- */
+ /** @hide */
public WifiNanPublishSession(WifiNanManager manager, int sessionId) {
super(manager, sessionId);
}
/**
- * Re-configure the publish session. Note that the
+ * Re-configure the currently active publish session. The
* {@link WifiNanSessionCallback} is not replaced - the same listener used
- * at creation is still used.
+ * at creation is still used. The results of the configuration are returned using
+ * {@link WifiNanSessionCallback}:
+ * <ul>
+ * <li>{@link WifiNanSessionCallback#onSessionConfigSuccess()}: configuration update
+ * succeeded.
+ * <li>{@link WifiNanSessionCallback#onSessionConfigFail(int)}: configuration update
+ * failed. The publish discovery session is still running using its previous
+ * configuration (i.e. update failure does not terminate the session).
+ * </ul>
*
- * @param publishConfig The configuration ({@link PublishConfig}) of the
- * publish session.
+ * @param publishConfig The new discovery publish session configuration ({@link PublishConfig}).
*/
public void updatePublish(@NonNull PublishConfig publishConfig) {
if (mTerminated) {
diff --git a/wifi/java/android/net/wifi/nan/WifiNanSession.java b/wifi/java/android/net/wifi/nan/WifiNanSession.java
index f0a8368..5c118b5 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanSession.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanSession.java
@@ -26,9 +26,18 @@
import java.lang.ref.WeakReference;
/**
- * A representation of a single publish or subscribe NAN session. This object
+ * A class representing a single publish or subscribe NAN session. This object
* will not be created directly - only its child classes are available:
- * {@link WifiNanPublishSession} and {@link WifiNanSubscribeSession}.
+ * {@link WifiNanPublishSession} and {@link WifiNanSubscribeSession}. This class provides
+ * functionality common to both publish and subscribe discovery sessions:
+ * <ul>
+ * <li>Sending messages: {@link #sendMessage(int, byte[], int)} or
+ * {@link #sendMessage(int, byte[], int, int)} methods.
+ * <li>Creating a network-specifier when requesting a NAN connection:
+ * {@link #createNetworkSpecifier(int, int, byte[])}.
+ * </ul>
+ * The {@link #terminate()} method must be called to terminate discovery sessions once they are
+ * no longer needed.
*
* @hide PROPOSED_NAN_API
*/
@@ -37,28 +46,22 @@
private static final boolean DBG = false;
private static final boolean VDBG = false; // STOPSHIP if true
+ /**
+ * The maximum permitted retry count when sending messages using
+ * {@link #sendMessage(int, byte[], int, int)}.
+ */
public static final int MAX_SEND_RETRY_COUNT = 5;
- /**
- * @hide
- */
+ /** @hide */
protected WeakReference<WifiNanManager> mMgr;
-
- /**
- * @hide
- */
+ /** @hide */
protected final int mSessionId;
-
- /**
- * @hide
- */
+ /** @hide */
protected boolean mTerminated = false;
private final CloseGuard mCloseGuard = CloseGuard.get();
- /**
- * {@hide}
- */
+ /** @hide */
public WifiNanSession(WifiNanManager manager, int sessionId) {
if (VDBG) Log.v(TAG, "New client created: manager=" + manager + ", sessionId=" + sessionId);
@@ -69,10 +72,15 @@
}
/**
- * Terminate the current publish or subscribe session - i.e. stop
- * transmitting packet on-air (for an active session) or listening for
+ * Terminate the publish or subscribe session - free any resources, and stop
+ * transmitting packets on-air (for an active session) or listening for
* matches (for a passive session). The session may not be used for any
- * additional operations are termination.
+ * additional operations after termination.
+ * <p>
+ * This operation must be done on a session which is no longer needed. Otherwise system
+ * resources will continue to be utilized until the application terminates. The only
+ * exception is a session for which we received a termination callback,
+ * {@link WifiNanSessionCallback#onSessionTerminated(int)}.
*/
public void terminate() {
WifiNanManager mgr = mMgr.get();
@@ -102,6 +110,7 @@
mCloseGuard.close();
}
+ /** @hide */
@Override
protected void finalize() throws Throwable {
try {
@@ -115,20 +124,31 @@
}
/**
- * Sends a message to the specified destination. Message transmission is part of the current
- * discovery session - i.e. executed subsequent to a publish/subscribe
+ * Sends a message to the specified destination. NAN messages are transmitted in the context
+ * of a discovery session - executed subsequent to a publish/subscribe
* {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} event.
+ * <p>
+ * NAN messages are not guaranteed delivery. Callbacks on {@link WifiNanSessionCallback}
+ * indicate message was transmitted successfully,
+ * {@link WifiNanSessionCallback#onMessageSendSuccess(int)}, or transmission failed
+ * (possibly after several retries) -
+ * {@link WifiNanSessionCallback#onMessageSendFail(int, int)}.
+ * <p>
+ * The peer will get a callback indicating a message was received using
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])}.
*
* @param peerId The peer's ID for the message. Must be a result of an
- * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} event.
+ * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} or
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])} events.
* @param message The message to be transmitted.
* @param messageId An arbitrary integer used by the caller to identify the message. The same
- * integer ID will be returned in the callbacks indicated message send success or
- * failure.
+ * integer ID will be returned in the callbacks indicating message send success or
+ * failure. The {@code messageId} is not used internally by the NAN service - it
+ * can be arbitrary and non-unique.
* @param retryCount An integer specifying how many additional service-level (as opposed to PHY
* or MAC level) retries should be attempted if there is no ACK from the receiver
* (note: no retransmissions are attempted in other failure cases). A value of 0
- * indicates no retries. Max possible value is {@link #MAX_SEND_RETRY_COUNT}.
+ * indicates no retries. Max permitted value is {@link #MAX_SEND_RETRY_COUNT}.
*/
public void sendMessage(int peerId, @Nullable byte[] message, int messageId, int retryCount) {
if (mTerminated) {
@@ -146,18 +166,29 @@
}
/**
- * Sends a message to the specified destination. Message transmission is part of the current
- * discovery session - i.e. executed subsequent to a publish/subscribe
- * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} event. This is
- * equivalent to {@link #sendMessage(int, byte[], int, int)} with a {@code retryCount} of
+ * Sends a message to the specified destination. NAN messages are transmitted in the context
+ * of a discovery session - executed subsequent to a publish/subscribe
+ * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} event.
+ * <p>
+ * NAN messages are not guaranteed delivery. Callbacks on {@link WifiNanSessionCallback}
+ * indicate message was transmitted successfully,
+ * {@link WifiNanSessionCallback#onMessageSendSuccess(int)}, or transmission failed
+ * (possibly after several retries) -
+ * {@link WifiNanSessionCallback#onMessageSendFail(int, int)}.
+ * <p>
+ * The peer will get a callback indicating a message was received using
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])}.
+ * Equivalent to {@link #sendMessage(int, byte[], int, int)} with a {@code retryCount} of
* 0.
*
* @param peerId The peer's ID for the message. Must be a result of an
- * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} event.
+ * {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} or
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])} events.
* @param message The message to be transmitted.
* @param messageId An arbitrary integer used by the caller to identify the message. The same
- * integer ID will be returned in the callbacks indicated message send success or
- * failure.
+ * integer ID will be returned in the callbacks indicating message send success or
+ * failure. The {@code messageId} is not used internally by the NAN service - it
+ * can be arbitrary and non-unique.
*/
public void sendMessage(int peerId, @Nullable byte[] message, int messageId) {
sendMessage(peerId, message, messageId, 0);
@@ -166,7 +197,7 @@
/**
* Start a ranging operation with the specified peers. The peer IDs are obtained from an
* {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} or
- * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])} operation - i.e. can only
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])} operation - can only
* range devices which are part of an ongoing discovery session.
*
* @param params RTT parameters - each corresponding to a specific peer ID (the array sizes
@@ -192,25 +223,37 @@
}
/**
- * Create a {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} for a
- * WiFi NAN data-path connection to the specified peer. The peer ID is in the context of a
- * previous match or received message in this session.
+ * Create a {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} for a
+ * WiFi NAN connection to the specified peer. The
+ * {@link android.net.NetworkRequest.Builder#addTransportType(int)} should be set to
+ * {@link android.net.NetworkCapabilities#TRANSPORT_WIFI_NAN}.
+ * <p>
+ * This method should be used when setting up a connection with a peer discovered through NAN
+ * discovery or communication (in such scenarios the MAC address of the peer is shielded by
+ * an opaque peer ID handle). If a NAN connection is needed to a peer discovered using other
+ * OOB (out-of-band) mechanism then use the alternative
+ * {@link WifiNanManager#createNetworkSpecifier(int, byte[], byte[])} method - which uses the
+ * peer's MAC address.
*
* @param role The role of this device:
* {@link WifiNanManager#WIFI_NAN_DATA_PATH_ROLE_INITIATOR} or
* {@link WifiNanManager#WIFI_NAN_DATA_PATH_ROLE_RESPONDER}
* @param peerId The peer ID obtained through
* {@link WifiNanSessionCallback#onMatch(int, byte[], byte[])} or
- * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])}. On the RESPONDER a
- * value of 0 is permitted which matches any peer.
- * @param token An arbitrary token (message) to be passed to the peer as part of the
- * data-path setup process. On the RESPONDER a null token is permitted and
- * matches any peer token - an empty token requires the peer token to be empty
- * as well.
+ * {@link WifiNanSessionCallback#onMessageReceived(int, byte[])}. On a RESPONDER this
+ * value is used to gate the acceptance of a connection request from only that
+ * peer. A RESPONDER may specified a 0 - indicating that it will accept
+ * connection requests from any device.
+ * @param token An arbitrary token (message) to be used to match connection initiation request
+ * to a responder setup. A RESPONDER is set up with a {@code token} which must
+ * be matched by the token provided by the INITIATOR. A null token is permitted
+ * on the RESPONDER and matches any peer token. An empty ({@code ""}) token is
+ * not the same as a null token and requires the peer token to be empty as well.
+ *
* @return A string to be used to construct
- * {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to {@link
- * android.net.ConnectivityManager#requestNetwork(NetworkRequest,
- * ConnectivityManager.NetworkCallback)} [or other varieties of that API].
+ * {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to
+ * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,android.net.ConnectivityManager.NetworkCallback)}
+ * [or other varieties of that API].
*/
public String createNetworkSpecifier(@WifiNanManager.DataPathRole int role, int peerId,
@Nullable byte[] token) {
diff --git a/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java b/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java
index f2337dd..8433b99 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java
@@ -24,17 +24,17 @@
/**
* Base class for NAN session events callbacks. Should be extended by
- * applications wanting notifications. The callbacks are registered when a
+ * applications wanting notifications. The callbacks are set when a
* publish or subscribe session is created using
* {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} or
* {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanSessionCallback)} .
- * These are callbacks applying to a specific NAN session.
* <p>
- * A single callback is registered at session creation - it cannot be replaced.
+ * A single callback is set at session creation - it cannot be replaced.
*
* @hide PROPOSED_NAN_API
*/
public class WifiNanSessionCallback {
+ /** @hide */
@IntDef({
REASON_NO_RESOURCES, REASON_INVALID_ARGS, REASON_NO_MATCH_SESSION,
REASON_TX_FAIL, REASON_OTHER })
@@ -42,6 +42,7 @@
public @interface SessionReasonCodes {
}
+ /** @hide */
@IntDef({
TERMINATE_REASON_DONE, TERMINATE_REASON_FAIL })
@Retention(RetentionPolicy.SOURCE)
@@ -49,58 +50,57 @@
}
/**
- * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
* Indicates no resources to execute the requested operation.
+ * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
*/
public static final int REASON_NO_RESOURCES = 0;
/**
- * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
* Indicates invalid argument in the requested operation.
+ * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
*/
public static final int REASON_INVALID_ARGS = 1;
/**
+ * Indicates a message is transmitted without a match (a discovery) or received message
+ * from peer occurring first.
* Failure reason flag for {@link WifiNanSessionCallback} callbacks.
- * Indicates a message is transmitted without a match (i.e. a discovery)
- * occurring first.
*/
public static final int REASON_NO_MATCH_SESSION = 2;
/**
- * Failure reason flag for
- * {@link WifiNanSessionCallback#onMessageSendFail(int, int)} callback.
* Indicates transmission failure: this may be due to local transmission
- * failure or to no ACK received - i.e. remote device didn't receive the
- * sent message.
+ * failure or to no ACK received - remote device didn't receive the
+ * sent message. Failure reason flag for
+ * {@link WifiNanSessionCallback#onMessageSendFail(int, int)} callback.
*/
public static final int REASON_TX_FAIL = 3;
/**
- * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
* Indicates an unspecified error occurred during the operation.
+ * Failure reason flag for {@link WifiNanSessionCallback} callbacks.
*/
public static final int REASON_OTHER = 4;
/**
- * Failure reason flag for
- * {@link WifiNanSessionCallback#onSessionTerminated(int)} callback.
- * Indicates that publish or subscribe session is done - i.e. all the
+ * Indicates that publish or subscribe session is done - all the
* requested operations (per {@link PublishConfig} or
- * {@link SubscribeConfig}) have been executed.
+ * {@link SubscribeConfig}) have been executed. Failure reason flag for
+ * {@link WifiNanSessionCallback#onSessionTerminated(int)} callback.
*/
public static final int TERMINATE_REASON_DONE = 100;
/**
- * Failure reason flag for
- * {@link WifiNanSessionCallback#onSessionTerminated(int)} callback.
* Indicates that publish or subscribe session is terminated due to a
* failure.
+ * Failure reason flag for
+ * {@link WifiNanSessionCallback#onSessionTerminated(int)} callback.
*/
public static final int TERMINATE_REASON_FAIL = 101;
/**
- * Called when a publish operation is started successfully.
+ * Called when a publish operation is started successfully in response to a
+ * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} operation.
*
* @param session The {@link WifiNanPublishSession} used to control the
* discovery session.
@@ -110,7 +110,8 @@
}
/**
- * Called when a subscribe operation is started successfully.
+ * Called when a subscribe operation is started successfully in response to a
+ * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanSessionCallback)} operation.
*
* @param session The {@link WifiNanSubscribeSession} used to control the
* discovery session.
@@ -120,16 +121,24 @@
}
/**
- * Called when a session update configuration (publish or subscribe update)
- * succeeds.
+ * Called when a publish or subscribe discovery session configuration is update request
+ * succeeds. Called in response to {@link WifiNanPublishSession#updatePublish(PublishConfig)}
+ * or {@link WifiNanSubscribeSession#updateSubscribe(SubscribeConfig)}.
*/
public void onSessionConfigSuccess() {
/* empty */
}
/**
- * Called when a session configuration (publish or subscribe setup or
- * update) fails.
+ * Called when a publish or subscribe discovery session cannot be created:
+ * {@link WifiNanManager#publish(PublishConfig, WifiNanSessionCallback)} or
+ * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanSessionCallback)},
+ * or when a configuration update fails:
+ * {@link WifiNanPublishSession#updatePublish(PublishConfig)} or
+ * {@link WifiNanSubscribeSession#updateSubscribe(SubscribeConfig)}.
+ * <p>
+ * For discovery session updates failure leaves the session running with its previous
+ * configuration - the discovery session is not terminated.
*
* @param reason The failure reason using
* {@code WifiNanSessionCallback.REASON_*} codes.
@@ -139,7 +148,10 @@
}
/**
- * Called when a session (publish or subscribe) terminates.
+ * Called when a discovery session (publish or subscribe) terminates. Termination may be due
+ * to user-request (either directly through {@link WifiNanSession#terminate()} or
+ * application-specified expiration, e.g. {@link PublishConfig.Builder#setPublishCount(int)}
+ * or {@link SubscribeConfig.Builder#setTtlSec(int)}) or due to a failure.
*
* @param reason The termination reason using
* {@code WifiNanSessionCallback.TERMINATE_*} codes.
@@ -150,12 +162,12 @@
/**
* Called when a discovery (publish or subscribe) operation results in a
- * match - i.e. when a peer is discovered.
+ * match - when a peer is discovered.
*
* @param peerId The ID of the peer matching our discovery operation.
* @param serviceSpecificInfo The service specific information (arbitrary
* byte array) provided by the peer as part of its discovery
- * packet.
+ * configuration.
* @param matchFilter The filter (Tx on advertiser and Rx on listener) which
* resulted in this match.
*/
@@ -164,29 +176,31 @@
}
/**
- * Called when a message is transmitted successfully - i.e. when we know
- * that it was received successfully (corresponding to an ACK being
- * received).
+ * Called in response to {@link WifiNanSession#sendMessage(int, byte[], int)} when a message
+ * is transmitted successfully - when it was received successfully by the peer
+ * (corresponds to an ACK being received).
* <p>
* Note that either this callback or
* {@link WifiNanSessionCallback#onMessageSendFail(int, int)} will be
* received - never both.
+ *
+ * @param messageId The arbitrary message ID specified when sending the message.
*/
public void onMessageSendSuccess(@SuppressWarnings("unused") int messageId) {
/* empty */
}
/**
- * Called when a message transmission fails - i.e. when no ACK is received.
- * The hardware will usually attempt to re-transmit several times - this
- * event is received after all retries are exhausted. There is a possibility
- * that message was received by the destination successfully but the ACK was
- * lost
+ * Called when message transmission fails - when no ACK is received from the peer.
+ * Retries when ACKs are not received are done by hardware, MAC, and in the NAN stack (using
+ * the {@link WifiNanSession#sendMessage(int, byte[], int, int)} method) - this
+ * event is received after all retries are exhausted.
* <p>
* Note that either this callback or
* {@link WifiNanSessionCallback#onMessageSendSuccess(int)} will be received
- * - never both
+ * - never both.
*
+ * @param messageId The arbitrary message ID specified when sending the message.
* @param reason The failure reason using
* {@code WifiNanSessionCallback.REASON_*} codes.
*/
@@ -196,7 +210,9 @@
}
/**
- * Called when a message is received from a discovery session peer.
+ * Called when a message is received from a discovery session peer - in response to the
+ * peer's {@link WifiNanSession#sendMessage(int, byte[], int)} or
+ * {@link WifiNanSession#sendMessage(int, byte[], int, int)}.
*
* @param peerId The ID of the peer sending the message.
* @param message A byte array containing the message.
diff --git a/wifi/java/android/net/wifi/nan/WifiNanSubscribeSession.java b/wifi/java/android/net/wifi/nan/WifiNanSubscribeSession.java
index 2e6d769..d0e56c5 100644
--- a/wifi/java/android/net/wifi/nan/WifiNanSubscribeSession.java
+++ b/wifi/java/android/net/wifi/nan/WifiNanSubscribeSession.java
@@ -20,10 +20,12 @@
import android.util.Log;
/**
- * A representation of a NAN subscribe session. Created when
- * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanSessionCallback)} is
- * executed. The object can be used to stop and re-start (re-configure) the
- * subscribe session.
+ * A class representing a NAN subscribe session. Created when
+ * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanSessionCallback)} is called and a
+ * discovery session is created and returned in
+ * {@link WifiNanSessionCallback#onSubscribeStarted(WifiNanSubscribeSession)}. See baseline
+ * functionality of all discovery sessions in {@link WifiNanSession}. This object allows updating
+ * an existing/running subscribe discovery session using {@link #updateSubscribe(SubscribeConfig)}.
*
* @hide PROPOSED_NAN_API
*/
@@ -38,12 +40,20 @@
}
/**
- * Re-configure the subscribe session. Note that the
+ * Re-configure the currently active subscribe session. The
* {@link WifiNanSessionCallback} is not replaced - the same listener used
- * at creation is still used.
+ * at creation is still used. The results of the configuration are returned using
+ * {@link WifiNanSessionCallback}:
+ * <ul>
+ * <li>{@link WifiNanSessionCallback#onSessionConfigSuccess()}: configuration update
+ * succeeded.
+ * <li>{@link WifiNanSessionCallback#onSessionConfigFail(int)}: configuration update
+ * failed. The subscribe discovery session is still running using its previous
+ * configuration (i.e. update failure does not terminate the session).
+ * </ul>
*
- * @param subscribeConfig The configuration ({@link SubscribeConfig}) of the
- * subscribe session.
+ * @param subscribeConfig The new discovery subscribe session configuration
+ * ({@link SubscribeConfig}).
*/
public void updateSubscribe(@NonNull SubscribeConfig subscribeConfig) {
if (mTerminated) {
diff --git a/wifi/java/android/net/wifi/nan/package.html b/wifi/java/android/net/wifi/nan/package.html
new file mode 100644
index 0000000..ae3cf6c
--- /dev/null
+++ b/wifi/java/android/net/wifi/nan/package.html
@@ -0,0 +1,43 @@
+<HTML>
+<BODY>
+<p>Provides classes which allow applications to use Wi-Fi NAN to discover peers and create
+ connections to them.</p>
+<p>Using the Wi-Fi NAN APIs, applications can advertise services, discover peers which are
+ advertising services, and connect to them.
+ Wi-Fi NAN is independent of Wi-Fi infrastructure (i.e. a device may or may
+ not be associated with an AP concurrent to using Wi-Fi NAN). </p>
+<p>The primary entry point to Wi-Fi NAN capabilities is the
+ {@link android.net.wifi.nan.WifiNanManager} class, which is acquired by calling
+ {@link android.content.Context#getSystemService(String)
+ Context.getSystemService(Context.WIFI_NAN_SERVICE)}</p>
+
+<p>Some APIs may require the following user permissions:</p>
+<ul>
+ <li>{@link android.Manifest.permission#ACCESS_WIFI_STATE}</li>
+ <li>{@link android.Manifest.permission#CHANGE_WIFI_STATE}</li>
+ <li>{@link android.Manifest.permission#ACCESS_COARSE_LOCATION}</li>
+</ul>
+
+<p class="note"><strong>Note:</strong> Not all Android-powered devices support Wi-Fi NAN
+ functionality.
+ If your application only works with Wi-Fi NAN (i.e. it should only be installed on devices which
+ support Wi-Fi NAN), declare so with a <a
+ href="{@docRoot}guide/topics/manifest/uses-feature-element.html">
+ {@code <uses-feature>}</a>
+ element in the manifest file:</p>
+<pre>
+<manifest ...>
+ <uses-feature android:name="android.hardware.wifi.nan" />
+ ...
+</manifest>
+</pre>
+<p>Alternatively, if you application does not require Wi-Fi NAN but can take advantage of it if
+ available, you can perform
+ the check at run-time in your code using {@link
+ android.content.pm.PackageManager#hasSystemFeature(String)} with {@link
+ android.content.pm.PackageManager#FEATURE_WIFI_NAN}:</p>
+<pre>
+ getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_NAN)
+</pre>
+</BODY>
+</HTML>