+ * 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 3fd756e99ce8a..6fac7a8e96cec 100644 --- a/wifi/java/android/net/wifi/nan/PublishConfig.java +++ b/wifi/java/android/net/wifi/nan/PublishConfig.java @@ -31,13 +31,14 @@ import java.util.Arrays; /** * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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 @@ public class PublishConfig implements Parcelable { /** * 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. + *
+ * 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. + *
+ * 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 @@ public class PublishConfig implements Parcelable { /** * 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. + *
+ * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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. + *
+ * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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. *
- * 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. + *
+ *+ * Optional. Empty by default. + *
+ * + * @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 @@ public class PublishConfig implements Parcelable { } /** - * 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. *- * 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. + *
+ * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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 @@ public class PublishConfig implements Parcelable { } /** - * 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]. + *
+ * 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 broadcast. * - * @param publishCount Number of publish packets to transmit. * @return The builder to facilitate chaining * {@code builder.setXXX(..).setXXX(..)}. */ @@ -385,14 +389,19 @@ public class PublishConfig implements Parcelable { } /** - * 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]. + *
+ * 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 @@ public class PublishConfig implements Parcelable { * * @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 fd19ddbb7f242..89a24b637cd32 100644 --- a/wifi/java/android/net/wifi/nan/SubscribeConfig.java +++ b/wifi/java/android/net/wifi/nan/SubscribeConfig.java @@ -38,6 +38,7 @@ import java.util.Arrays; * @hide PROPOSED_NAN_API */ public class SubscribeConfig implements Parcelable { + /** @hide */ @IntDef({ SUBSCRIBE_TYPE_PASSIVE, SUBSCRIBE_TYPE_ACTIVE }) @Retention(RetentionPolicy.SOURCE) @@ -45,7 +46,7 @@ public class SubscribeConfig implements Parcelable { } /** - * 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 class SubscribeConfig implements Parcelable { 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 @@ public class SubscribeConfig implements Parcelable { /** * 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 @@ public class SubscribeConfig implements Parcelable { } /** - * 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 @@ public class SubscribeConfig implements Parcelable { /** * 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. + *
+ * 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. + *
+ * 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 @@ public class SubscribeConfig implements Parcelable { } /** - * 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. + *
+ * 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 @@ public class SubscribeConfig implements Parcelable { } /** - * 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. + *
+ * 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 @@ public class SubscribeConfig implements Parcelable { * publishers) to determine whether they match - in addition to just * relying on the service name. *
- * 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. + *
+ *+ * Optional. Empty by default. + *
* * @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 @@ public class SubscribeConfig implements Parcelable { * subscriber to determine whether they match transmitted publish * packets - in addition to just relying on the service name. *- * 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. + *
+ * 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 @@ public class SubscribeConfig implements Parcelable { * 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 @@ public class SubscribeConfig implements Parcelable { /** * 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}. + *
+ * 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 broadcast. * - * @param subscribeCount Number of subscribe packets to transmit. * @return The builder to facilitate chaining * {@code builder.setXXX(..).setXXX(..)}. */ @@ -419,13 +425,17 @@ public class SubscribeConfig implements Parcelable { /** * 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}. + *
+ * 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 @@ public class SubscribeConfig implements Parcelable { * {@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 @@ public class SubscribeConfig implements Parcelable { * * @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 148307d704309..7dd879e88e2f6 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.Retention; 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 @@ public class WifiNanEventCallback { } /** - * 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 @@ public class WifiNanEventCallback { /** * 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 @@ public class WifiNanEventCallback { } /** - * 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[])}. + *
+ * 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 e8ede34a47603..a0d5987526713 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.lang.ref.WeakReference; 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)}. *
* The class provides access to: *
+ * 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. + *
+ * 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 must 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. + *
+ * 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 must terminate it using + * the {@link WifiNanSession#terminate()} API. + *
+ * Creating connections between NAN devices is managed by the standard + * {@link ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}. + * The {@link NetworkRequest} object should be constructed with: + *
+ * 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 @@ -309,9 +354,17 @@ public class WifiNanManager { } /** - * 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 must 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. + *
+ * 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 @@ -343,12 +396,13 @@ public class WifiNanManager { } /** - * 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. *
- * An application may then re-connect using + * An application may re-connect after a disconnect using * {@link WifiNanManager#connect(Looper, WifiNanEventCallback)} . */ public void disconnect() { @@ -377,6 +431,7 @@ public class WifiNanManager { } } + /** @hide */ @Override protected void finalize() throws Throwable { try { @@ -388,17 +443,29 @@ public class WifiNanManager { } /** - * 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}: + *
+ * 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)}. + *
+ * 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) { @@ -424,9 +491,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public void updatePublish(int sessionId, PublishConfig publishConfig) { if (VDBG) Log.v(TAG, "updatePublish(): config=" + publishConfig); @@ -447,17 +512,29 @@ public class WifiNanManager { } /** - * 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}: + *
+ * 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)}. + *
+ * 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) { @@ -486,9 +563,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public void updateSubscribe(int sessionId, SubscribeConfig subscribeConfig) { if (VDBG) { Log.v(TAG, "subscribe(): config=" + subscribeConfig); @@ -512,9 +587,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public void terminateSession(int sessionId) { if (DBG) Log.d(TAG, "Terminate NAN session #" + sessionId); @@ -536,9 +609,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public void sendMessage(int sessionId, int peerId, byte[] message, int messageId, int retryCount) { if (VDBG) { @@ -563,9 +634,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public void startRanging(int sessionId, RttManager.RttParams[] params, RttManager.RttListener listener) { if (VDBG) { @@ -596,9 +665,7 @@ public class WifiNanManager { } } - /** - * {@hide} - */ + /** @hide */ public String createNetworkSpecifier(@DataPathRole int role, int sessionId, int peerId, byte[] token) { if (VDBG) { @@ -669,20 +736,29 @@ public class WifiNanManager { } /** - * 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}. + *
+ * 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)} @@ -786,7 +862,7 @@ public class WifiNanManager { /** * 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 a0e3fbad36c9c..ccd7faee8476f 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.annotation.NonNull; 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}: + *
+ * 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 @@ public class WifiNanSession { mCloseGuard.close(); } + /** @hide */ @Override protected void finalize() throws Throwable { try { @@ -115,20 +124,31 @@ public class WifiNanSession { } /** - * 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. + *
+ * 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)}. + *
+ * 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 @@ public class WifiNanSession { } /** - * 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. + *
+ * 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)}. + *
+ * 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 @@ public class WifiNanSession { /** * 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 @@ public class WifiNanSession { } /** - * 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}. + *
+ * 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 f2337ddb043f1..8433b99315ce9 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java +++ b/wifi/java/android/net/wifi/nan/WifiNanSessionCallback.java @@ -24,17 +24,17 @@ import java.lang.annotation.RetentionPolicy; /** * 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. *
- * 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 class WifiNanSessionCallback { public @interface SessionReasonCodes { } + /** @hide */ @IntDef({ TERMINATE_REASON_DONE, TERMINATE_REASON_FAIL }) @Retention(RetentionPolicy.SOURCE) @@ -49,58 +50,57 @@ public class WifiNanSessionCallback { } /** - * 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 @@ public class WifiNanSessionCallback { } /** - * 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 @@ public class WifiNanSessionCallback { } /** - * 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)}. + *
+ * 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 @@ public class WifiNanSessionCallback { } /** - * 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 @@ public class WifiNanSessionCallback { /** * 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 @@ public class WifiNanSessionCallback { } /** - * 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). *
* 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. *
* 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 @@ public class WifiNanSessionCallback { } /** - * 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 2e6d7695fb443..d0e56c521525f 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.annotation.NonNull; 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 @@ public class WifiNanSubscribeSession extends WifiNanSession { } /** - * 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}: + *
Provides classes which allow applications to use Wi-Fi NAN to discover peers and create + connections to them.
+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).
+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)}
+ +Some APIs may require the following user permissions:
+Note: 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 + {@code <uses-feature>} + element in the manifest file:
++<manifest ...> + <uses-feature android:name="android.hardware.wifi.nan" /> + ... +</manifest> ++
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}:
++ getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_NAN) ++ +