From b68ed2876c3a0c73366ef7c557c616724ed5c9ed Mon Sep 17 00:00:00 2001 From: Etan Cohen Date: Tue, 20 Sep 2016 09:23:33 -0700 Subject: [PATCH] [NAN] Method renames based on API council feedback - Fix tenses throughout - connect -> attach - disconnect/terminate -> destroy - IsUsable -> IsAvailable Note: pure rename operation - no functional changes (cherry-pick of commit 34a0342ab515762f3fc594ffbc4784e56e79ccbf) Bug: 31470256 Test: unit tests + integration (sl4a) test Change-Id: I0f275c590c63109b7196622cfc5001082e3eb5a2 --- .../android/net/wifi/nan/ConfigRequest.java | 2 +- .../android/net/wifi/nan/PublishConfig.java | 6 +- .../android/net/wifi/nan/SubscribeConfig.java | 8 +- .../wifi/nan/WifiNanDiscoveryBaseSession.java | 43 +++++---- .../nan/WifiNanDiscoverySessionCallback.java | 40 ++++---- .../net/wifi/nan/WifiNanEventCallback.java | 28 +++--- .../android/net/wifi/nan/WifiNanManager.java | 96 +++++++++---------- .../nan/WifiNanPublishDiscoverySession.java | 6 +- .../android/net/wifi/nan/WifiNanSession.java | 30 +++--- .../nan/WifiNanSubscribeDiscoverySession.java | 6 +- 10 files changed, 134 insertions(+), 131 deletions(-) diff --git a/wifi/java/android/net/wifi/nan/ConfigRequest.java b/wifi/java/android/net/wifi/nan/ConfigRequest.java index 78e40526ba5b7..3501ae84283c6 100644 --- a/wifi/java/android/net/wifi/nan/ConfigRequest.java +++ b/wifi/java/android/net/wifi/nan/ConfigRequest.java @@ -23,7 +23,7 @@ import android.os.Parcelable; /** * 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.Handler, ConfigRequest, WifiNanEventCallback)}. + * {@link WifiNanManager#attach(android.os.Handler, WifiNanEventCallback)}. * Note that the actual achieved configuration may be different from the * requested configuration - since different applications may request different * configurations. diff --git a/wifi/java/android/net/wifi/nan/PublishConfig.java b/wifi/java/android/net/wifi/nan/PublishConfig.java index f988c0b03ca52..cfa2300572c94 100644 --- a/wifi/java/android/net/wifi/nan/PublishConfig.java +++ b/wifi/java/android/net/wifi/nan/PublishConfig.java @@ -32,7 +32,7 @@ import java.util.Arrays; /** * Defines the configuration of a NAN publish session. Built using * {@link PublishConfig.Builder}. A publish session is created using - * {@link WifiNanManager#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or updated using + * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or updated using * {@link WifiNanPublishDiscoverySession#updatePublish(PublishConfig)}. * * @hide PROPOSED_NAN_API @@ -323,7 +323,7 @@ public final class PublishConfig implements Parcelable { * {@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 WifiNanDiscoveryBaseSession#terminate()} is + * Session will be terminated when {@link WifiNanDiscoveryBaseSession#destroy()} is * called. * * @param publishCount Number of publish packets to broadcast. @@ -349,7 +349,7 @@ public final class PublishConfig implements Parcelable { * {@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 WifiNanDiscoveryBaseSession#terminate()} is + * Session will be terminated when {@link WifiNanDiscoveryBaseSession#destroy()} is * called. * * @param ttlSec Lifetime of a publish session in seconds. diff --git a/wifi/java/android/net/wifi/nan/SubscribeConfig.java b/wifi/java/android/net/wifi/nan/SubscribeConfig.java index 47f9398b642f2..569c6b436eefd 100644 --- a/wifi/java/android/net/wifi/nan/SubscribeConfig.java +++ b/wifi/java/android/net/wifi/nan/SubscribeConfig.java @@ -32,7 +32,7 @@ import java.util.Arrays; /** * Defines the configuration of a NAN subscribe session. Built using * {@link SubscribeConfig.Builder}. Subscribe is done using - * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} or + * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} or * {@link WifiNanSubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. * * @hide PROPOSED_NAN_API @@ -354,7 +354,7 @@ public final class SubscribeConfig implements Parcelable { * with {@link WifiNanDiscoverySessionCallback#TERMINATE_REASON_DONE}. *

* Optional. 0 by default - indicating the session doesn't terminate on its own. - * Session will be terminated when {@link WifiNanDiscoveryBaseSession#terminate()} is + * Session will be terminated when {@link WifiNanDiscoveryBaseSession#destroy()} is * called. * * @param subscribeCount Number of subscribe packets to broadcast. @@ -379,7 +379,7 @@ public final class SubscribeConfig implements Parcelable { * {@link WifiNanDiscoverySessionCallback#TERMINATE_REASON_DONE}. *

* Optional. 0 by default - indicating the session doesn't terminate on its own. - * Session will be terminated when {@link WifiNanDiscoveryBaseSession#terminate()} is + * Session will be terminated when {@link WifiNanDiscoveryBaseSession#destroy()} is * called. * * @param ttlSec Lifetime of a subscribe session in seconds. @@ -399,7 +399,7 @@ public final class SubscribeConfig implements Parcelable { * Sets the match style of the subscription - how are matches from a * single match session (corresponding to the same publish action on the * peer) reported to the host (using the - * {@link WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(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} (the default). diff --git a/wifi/java/android/net/wifi/nan/WifiNanDiscoveryBaseSession.java b/wifi/java/android/net/wifi/nan/WifiNanDiscoveryBaseSession.java index c2f373595ff59..50951f6d7e20b 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanDiscoveryBaseSession.java +++ b/wifi/java/android/net/wifi/nan/WifiNanDiscoveryBaseSession.java @@ -17,6 +17,7 @@ package android.net.wifi.nan; import android.annotation.Nullable; +import android.annotation.SystemApi; import android.net.wifi.RttManager; import android.util.Log; @@ -35,7 +36,7 @@ import java.lang.ref.WeakReference; *

  • Creating a network-specifier when requesting a NAN connection: * {@link #createNetworkSpecifier(int, int, byte[])}. * - * The {@link #terminate()} method must be called to terminate discovery sessions once they are + * The {@link #destroy()} method must be called to destroy discovery sessions once they are * no longer needed. * * @hide PROPOSED_NAN_API @@ -79,24 +80,24 @@ public class WifiNanDiscoveryBaseSession { mClientId = clientId; mSessionId = sessionId; - mCloseGuard.open("terminate"); + mCloseGuard.open("destroy"); } /** - * Terminate the publish or subscribe session - free any resources, and stop + * Destroy 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 after termination. + * additional operations after its destruction. *

    * 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 + * resources will continue to be utilized until the application exits. The only * exception is a session for which we received a termination callback, * {@link WifiNanDiscoverySessionCallback#onSessionTerminated(int)}. */ - public void terminate() { + public void destroy() { WifiNanManager mgr = mMgr.get(); if (mgr == null) { - Log.w(TAG, "terminate: called post GC on WifiNanManager"); + Log.w(TAG, "destroy: called post GC on WifiNanManager"); return; } mgr.terminateSession(mClientId, mSessionId); @@ -127,7 +128,7 @@ public class WifiNanDiscoveryBaseSession { try { if (!mTerminated) { mCloseGuard.warnIfOpen(); - terminate(); + destroy(); } } finally { super.finalize(); @@ -137,20 +138,21 @@ public class WifiNanDiscoveryBaseSession { /** * 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 WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} event. + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} event. *

    * NAN messages are not guaranteed delivery. Callbacks on * {@link WifiNanDiscoverySessionCallback} indicate message was transmitted successfully, - * {@link WifiNanDiscoverySessionCallback#onMessageSendSuccess(int)}, or transmission failed + * {@link WifiNanDiscoverySessionCallback#onMessageSent(int)}, or transmission failed * (possibly after several retries) - - * {@link WifiNanDiscoverySessionCallback#onMessageSendFail(int, int)}. + * {@link WifiNanDiscoverySessionCallback#onMessageSendFailed(int, int)}. *

    * The peer will get a callback indicating a message was received using * {@link WifiNanDiscoverySessionCallback#onMessageReceived(int, byte[])}. * * @param peerId The peer's ID for the message. Must be a result of an - * {@link WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} or - * {@link WifiNanDiscoverySessionCallback#onMessageReceived(int, byte[])} events. + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} + * or + * {@link WifiNanDiscoverySessionCallback#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 indicating message send success or @@ -179,13 +181,13 @@ public class WifiNanDiscoveryBaseSession { /** * 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 WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} event. + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} event. *

    * NAN messages are not guaranteed delivery. Callbacks on * {@link WifiNanDiscoverySessionCallback} indicate message was transmitted successfully, - * {@link WifiNanDiscoverySessionCallback#onMessageSendSuccess(int)}, or transmission failed + * {@link WifiNanDiscoverySessionCallback#onMessageSent(int)}, or transmission failed * (possibly after several retries) - - * {@link WifiNanDiscoverySessionCallback#onMessageSendFail(int, int)}. + * {@link WifiNanDiscoverySessionCallback#onMessageSendFailed(int, int)}. *

    * The peer will get a callback indicating a message was received using * {@link WifiNanDiscoverySessionCallback#onMessageReceived(int, byte[])}. @@ -193,8 +195,9 @@ public class WifiNanDiscoveryBaseSession { * 0. * * @param peerId The peer's ID for the message. Must be a result of an - * {@link WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} or - * {@link WifiNanDiscoverySessionCallback#onMessageReceived(int, byte[])} events. + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} + * or + * {@link WifiNanDiscoverySessionCallback#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 indicating message send success or @@ -207,7 +210,7 @@ public class WifiNanDiscoveryBaseSession { /** * Start a ranging operation with the specified peers. The peer IDs are obtained from an - * {@link WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} or + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} or * {@link WifiNanDiscoverySessionCallback#onMessageReceived(int, byte[])} operation - can only * range devices which are part of an ongoing discovery session. * @@ -250,7 +253,7 @@ public class WifiNanDiscoveryBaseSession { * {@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 WifiNanDiscoverySessionCallback#onMatch(int, byte[], byte[])} or + * {@link WifiNanDiscoverySessionCallback#onServiceDiscovered(int, byte[], byte[])} or * {@link WifiNanDiscoverySessionCallback#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 diff --git a/wifi/java/android/net/wifi/nan/WifiNanDiscoverySessionCallback.java b/wifi/java/android/net/wifi/nan/WifiNanDiscoverySessionCallback.java index 685e1524a27a8..43a2d3ce28955 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanDiscoverySessionCallback.java +++ b/wifi/java/android/net/wifi/nan/WifiNanDiscoverySessionCallback.java @@ -26,8 +26,8 @@ import java.lang.annotation.RetentionPolicy; * Base class for NAN session events callbacks. Should be extended by * applications wanting notifications. The callbacks are set when a * publish or subscribe session is created using - * {@link WifiNanManager#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or - * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} . + * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or + * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} . *

    * A single callback is set at session creation - it cannot be replaced. * @@ -72,7 +72,7 @@ public class WifiNanDiscoverySessionCallback { * Indicates transmission failure: this may be due to local transmission * failure or to no ACK received - remote device didn't receive the * sent message. Failure reason flag for - * {@link WifiNanDiscoverySessionCallback#onMessageSendFail(int, int)} callback. + * {@link WifiNanDiscoverySessionCallback#onMessageSendFailed(int, int)} callback. */ public static final int REASON_TX_FAIL = 3; @@ -100,7 +100,7 @@ public class WifiNanDiscoverySessionCallback { /** * Called when a publish operation is started successfully in response to a - * {@link WifiNanManager#publish(PublishConfig, WifiNanDiscoverySessionCallback)} operation. + * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} operation. * * @param session The {@link WifiNanPublishDiscoverySession} used to control the * discovery session. @@ -111,7 +111,7 @@ public class WifiNanDiscoverySessionCallback { /** * Called when a subscribe operation is started successfully in response to a - * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} operation. + * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} operation. * * @param session The {@link WifiNanSubscribeDiscoverySession} used to control the * discovery session. @@ -121,19 +121,19 @@ public class WifiNanDiscoverySessionCallback { } /** - * Called when a publish or subscribe discovery session configuration is update request + * Called when a publish or subscribe discovery session configuration update request * succeeds. Called in response to * {@link WifiNanPublishDiscoverySession#updatePublish(PublishConfig)} or * {@link WifiNanSubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. */ - public void onSessionConfigSuccess() { + public void onSessionConfigUpdated() { /* empty */ } /** * Called when a publish or subscribe discovery session cannot be created: - * {@link WifiNanManager#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or - * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)}, + * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or + * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)}, * or when a configuration update fails: * {@link WifiNanPublishDiscoverySession#updatePublish(PublishConfig)} or * {@link WifiNanSubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. @@ -144,13 +144,13 @@ public class WifiNanDiscoverySessionCallback { * @param reason The failure reason using * {@code WifiNanDiscoverySessionCallback.REASON_*} codes. */ - public void onSessionConfigFail(@SessionReasonCodes int reason) { + public void onSessionConfigFailed(@SessionReasonCodes int reason) { /* empty */ } /** * Called when a discovery session (publish or subscribe) terminates. Termination may be due - * to user-request (either directly through {@link WifiNanDiscoveryBaseSession#terminate()} or + * to user-request (either directly through {@link WifiNanDiscoveryBaseSession#destroy()} or * application-specified expiration, e.g. {@link PublishConfig.Builder#setPublishCount(int)} * or {@link SubscribeConfig.Builder#setTtlSec(int)}) or due to a failure. * @@ -163,31 +163,31 @@ public class WifiNanDiscoverySessionCallback { /** * Called when a discovery (publish or subscribe) operation results in a - * match - when a peer is discovered. + * service discovery. * * @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 * configuration. * @param matchFilter The filter (Tx on advertiser and Rx on listener) which - * resulted in this match. + * resulted in this service discovery. */ - public void onMatch(int peerId, byte[] serviceSpecificInfo, byte[] matchFilter) { + public void onServiceDiscovered(int peerId, byte[] serviceSpecificInfo, byte[] matchFilter) { /* empty */ } /** * Called in response to {@link WifiNanDiscoveryBaseSession#sendMessage(int, byte[], int)} - * when a message is transmitted successfully - when it was received successfully by the peer - * (corresponds to an ACK being received). + * when a message is transmitted successfully - i.e. when it was received successfully by the + * peer (corresponds to an ACK being received). *

    * Note that either this callback or - * {@link WifiNanDiscoverySessionCallback#onMessageSendFail(int, int)} will be + * {@link WifiNanDiscoverySessionCallback#onMessageSendFailed(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) { + public void onMessageSent(@SuppressWarnings("unused") int messageId) { /* empty */ } @@ -198,14 +198,14 @@ public class WifiNanDiscoverySessionCallback { * event is received after all retries are exhausted. *

    * Note that either this callback or - * {@link WifiNanDiscoverySessionCallback#onMessageSendSuccess(int)} will be received + * {@link WifiNanDiscoverySessionCallback#onMessageSent(int)} will be received * - never both. * * @param messageId The arbitrary message ID specified when sending the message. * @param reason The failure reason using * {@code WifiNanDiscoverySessionCallback.REASON_*} codes. */ - public void onMessageSendFail(@SuppressWarnings("unused") int messageId, + public void onMessageSendFailed(@SuppressWarnings("unused") int messageId, @SessionReasonCodes int reason) { /* empty */ } diff --git a/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java b/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java index 28c5ca29ea435..9c3acefb690e5 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java +++ b/wifi/java/android/net/wifi/nan/WifiNanEventCallback.java @@ -23,7 +23,7 @@ import java.lang.annotation.RetentionPolicy; /** * Base class for NAN events callbacks. Should be extended by applications and set when calling - * {@link WifiNanManager#connect(android.os.Handler, WifiNanEventCallback)}. These are callbacks + * {@link WifiNanManager#attach(android.os.Handler, WifiNanEventCallback)}. These are callbacks * applying to the NAN connection as a whole - not to specific publish or subscribe sessions - * for that see {@link WifiNanDiscoverySessionCallback}. * @@ -40,44 +40,44 @@ public class WifiNanEventCallback { /** * Indicates invalid argument in the requested operation. Failure reason flag for - * {@link WifiNanEventCallback#onConnectFail(int)}. + * {@link WifiNanEventCallback#onAttachFailed(int)}. */ public static final int REASON_INVALID_ARGS = 1000; /** * Indicates that a {@link ConfigRequest} passed in - * {@link WifiNanManager#connect(android.os.Handler, ConfigRequest, WifiNanEventCallback)} + * {@link WifiNanManager#attach(android.os.Handler, ConfigRequest, WifiNanEventCallback)} * couldn't be applied since other connections already exist with an incompatible - * configurations. Failure reason flag for {@link WifiNanEventCallback#onConnectFail(int)}. + * configurations. Failure reason flag for {@link WifiNanEventCallback#onAttachFailed(int)}. */ public static final int REASON_ALREADY_CONNECTED_INCOMPAT_CONFIG = 1001; /** * Indicates an unspecified error occurred during the operation. Failure reason flag for - * {@link WifiNanEventCallback#onConnectFail(int)}. + * {@link WifiNanEventCallback#onAttachFailed(int)}. */ public static final int REASON_OTHER = 1002; /** - * Called when NAN connect operation - * {@link WifiNanManager#connect(android.os.Handler, WifiNanEventCallback)} + * Called when NAN attach operation + * {@link WifiNanManager#attach(android.os.Handler, WifiNanEventCallback)} * is completed and that we can now start discovery sessions or connections. * - * @param session The NAN connection on which we can execute further NAN operations - e.g. + * @param session The NAN object on which we can execute further NAN operations - e.g. * discovery, connections. */ - public void onConnectSuccess(WifiNanSession session) { + public void onAttached(WifiNanSession session) { /* empty */ } /** - * Called when NAN connect operation - * {@link WifiNanManager#connect(android.os.Handler, WifiNanEventCallback)} failed. + * Called when NAN attach operation + * {@link WifiNanManager#attach(android.os.Handler, WifiNanEventCallback)} failed. * * @param reason Failure reason code, see * {@code WifiNanEventCallback.REASON_*}. */ - public void onConnectFail(@EventReasonCodes int reason) { + public void onAttachFailed(@EventReasonCodes int reason) { /* empty */ } @@ -90,11 +90,11 @@ public class WifiNanEventCallback { * 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[])}. + * {@link WifiNanSession#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.Handler, ConfigRequest, WifiNanEventCallback)} + * {@link WifiNanManager#attach(android.os.Handler, ConfigRequest, WifiNanEventCallback)} * . It is disabled by default since it may result in additional wake-ups of the host - * increasing power. * diff --git a/wifi/java/android/net/wifi/nan/WifiNanManager.java b/wifi/java/android/net/wifi/nan/WifiNanManager.java index b300d81db4cbc..79bf946ba731d 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanManager.java +++ b/wifi/java/android/net/wifi/nan/WifiNanManager.java @@ -56,7 +56,7 @@ import java.util.Arrays; * 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 + * the functionality is available use the {@link #isAvailable()} function. To track * changes in NAN usability register for the {@link #ACTION_WIFI_NAN_STATE_CHANGED} 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(Handler, WifiNanEventCallback)} to initialize a NAN + * An application must use {@link #attach(Handler, 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 + * starts one if none can be found). Information about attach 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(WifiNanSession)}. When an application is - * finished using NAN it must use the {@link WifiNanSession#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. + * connection setup only after receiving confirmation that NAN attach succeeded - + * {@link WifiNanEventCallback#onAttached(WifiNanSession)}. When an application is + * finished using NAN it must use the {@link WifiNanSession#destroy()} API + * to indicate to the NAN service that the device may detach from the NAN cluster. The + * device will actually disable NAN once the last application detaches. *

    - * Once a NAN connection is confirmed use the + * Once a NAN attach is confirmed use the * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} or * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} to * create publish or subscribe NAN discovery sessions. Events are called on the provided @@ -99,7 +99,7 @@ import java.util.Arrays; * be used to send messages using the * {@link WifiNanDiscoveryBaseSession#sendMessage(int, byte[], int)} APIs. When an application * is finished with a discovery session it must terminate it using the - * {@link WifiNanDiscoveryBaseSession#terminate()} API. + * {@link WifiNanDiscoveryBaseSession#destroy()} API. *

    * Creating connections between NAN devices is managed by the standard * {@link ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}. @@ -201,7 +201,7 @@ public class WifiNanManager { * disabled. An extra {@link #EXTRA_WIFI_STATE} provides the state * information as int using {@link #WIFI_NAN_STATE_DISABLED} and * {@link #WIFI_NAN_STATE_ENABLED} constants. This broadcast is not sticky, - * use the {@link #isUsageEnabled()} API after registering the broadcast to check the current + * use the {@link #isAvailable()} API after registering the broadcast to check the current * state of Wi-Fi NAN. * * @see #EXTRA_WIFI_STATE @@ -274,9 +274,9 @@ public class WifiNanManager { } /** - * Enable the usage of the NAN API. Doesn't actually turn on NAN cluster formation - that only - * happens when a connection is made. {@link #ACTION_WIFI_NAN_STATE_CHANGED} broadcast will be - * triggered. + * Enable the usage of the NAN API. Doesn't actually turn on NAN cluster formation - that + * only happens when an attach is attempted. {@link #ACTION_WIFI_NAN_STATE_CHANGED} broadcast + * will be triggered. * * @hide */ @@ -289,7 +289,7 @@ public class WifiNanManager { } /** - * Disable the usage of the NAN API. All attempts to connect() will be rejected. All open + * Disable the usage of the NAN API. All attempts to attach() will be rejected. All open * connections and sessions will be terminated. {@link #ACTION_WIFI_NAN_STATE_CHANGED} broadcast * will be triggered. * @@ -304,13 +304,13 @@ public class WifiNanManager { } /** - * Returns the current status of NAN API: whether or not usage is enabled. To track changes + * Returns the current status of NAN API: whether or not NAN is available. To track changes * in the state of NAN API register for the {@link #ACTION_WIFI_NAN_STATE_CHANGED} broadcast. * - * @return A boolean indicating whether the app can use the NAN API (true) - * or not (false). + * @return A boolean indicating whether the app can use the NAN API at this time (true) or + * not (false). */ - public boolean isUsageEnabled() { + public boolean isAvailable() { try { return mService.isUsageEnabled(); } catch (RemoteException e) { @@ -319,49 +319,49 @@ public class WifiNanManager { } /** - * 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 + * Attach to the Wi-Fi NAN service - enabling the application to create discovery session or + * create connection to peers. The device will attach 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 WifiNanSession#disconnect()} when done with the - * Wi-Fi NAN connection. + * (e.g. successful attach to a cluster) are provided to the {@code callback} object. + * An application must call {@link WifiNanSession#destroy()} when done with the + * Wi-Fi NAN object. *

    - * Note: a NAN cluster is a shared resource - if the device is already connected to a cluster + * Note: a NAN cluster is a shared resource - if the device is already attached to a cluster * than this function will simply indicate success immediately. * * @param handler The Handler on whose thread to execute all callbacks related to the - * connection - including all sessions opened as part of this - * connection. If a null is provided then the application's main thread will be used. + * attach request - including all sessions opened as part of this + * attach. If a null is provided then the application's main thread will be used. * @param callback A callback extended from {@link WifiNanEventCallback}. */ - public void connect(@Nullable Handler handler, @NonNull WifiNanEventCallback callback) { - connect(handler, null, callback); + public void attach(@Nullable Handler handler, @NonNull WifiNanEventCallback callback) { + attach(handler, null, callback); } /** - * 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 + * Attach to the Wi-Fi NAN service - enabling the application to create discovery session or + * create connection to peers. The device will attach 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 WifiNanSession#disconnect()} when done with the - * Wi-Fi NAN connection. Allows requesting a specific configuration using + * (e.g. successful attach to a cluster) are provided to the {@code callback} object. + * An application must call {@link WifiNanSession#destroy()} when done with the + * Wi-Fi NAN object. Allows requesting a specific configuration using * {@link ConfigRequest}. If not necessary (default configuration should usually work) use - * the {@link #connect(Handler, WifiNanEventCallback)} method instead. + * the {@link #attach(Handler, WifiNanEventCallback)} method instead. *

    - * Note: a NAN cluster is a shared resource - if the device is already connected to a cluster + * Note: a NAN cluster is a shared resource - if the device is already attached to a cluster * than this function will simply indicate success immediately. * * @param handler The Handler on whose thread to execute all callbacks related to the - * connection - including all sessions opened as part of this - * connection. If a null is provided then the application's main thread will be used. + * attach request - including all sessions opened as part of this + * attach. If a null is provided then the application's main thread will be used. * @param configRequest The requested NAN configuration. * @param callback A callback extended from {@link WifiNanEventCallback}. */ - public void connect(@Nullable Handler handler, @Nullable ConfigRequest configRequest, + public void attach(@Nullable Handler handler, @Nullable ConfigRequest configRequest, @NonNull WifiNanEventCallback callback) { if (VDBG) { Log.v(TAG, - "connect(): handler=" + handler + ", callback=" + callback + ", configRequest=" + "attach(): handler=" + handler + ", callback=" + callback + ", configRequest=" + configRequest); } @@ -675,12 +675,12 @@ public class WifiNanManager { switch (msg.what) { case CALLBACK_CONNECT_SUCCESS: - originalCallback.onConnectSuccess( + originalCallback.onAttached( new WifiNanSession(mgr, mBinder, mLooper, msg.arg1)); break; case CALLBACK_CONNECT_FAIL: mNanManager.clear(); - originalCallback.onConnectFail(msg.arg1); + originalCallback.onAttachFailed(msg.arg1); break; case CALLBACK_IDENTITY_CHANGED: originalCallback.onIdentityChanged((byte[]) msg.obj); @@ -834,10 +834,10 @@ public class WifiNanManager { onProxySessionStarted(msg.arg1); break; case CALLBACK_SESSION_CONFIG_SUCCESS: - mOriginalCallback.onSessionConfigSuccess(); + mOriginalCallback.onSessionConfigUpdated(); break; case CALLBACK_SESSION_CONFIG_FAIL: - mOriginalCallback.onSessionConfigFail(msg.arg1); + mOriginalCallback.onSessionConfigFailed(msg.arg1); if (mSession == null) { /* * creation failed (as opposed to update @@ -850,16 +850,16 @@ public class WifiNanManager { onProxySessionTerminated(msg.arg1); break; case CALLBACK_MATCH: - mOriginalCallback.onMatch( + mOriginalCallback.onServiceDiscovered( msg.arg1, msg.getData().getByteArray(MESSAGE_BUNDLE_KEY_MESSAGE), msg.getData().getByteArray(MESSAGE_BUNDLE_KEY_MESSAGE2)); break; case CALLBACK_MESSAGE_SEND_SUCCESS: - mOriginalCallback.onMessageSendSuccess(msg.arg1); + mOriginalCallback.onMessageSent(msg.arg1); break; case CALLBACK_MESSAGE_SEND_FAIL: - mOriginalCallback.onMessageSendFail(msg.arg1, msg.arg2); + mOriginalCallback.onMessageSendFailed(msg.arg1, msg.arg2); break; case CALLBACK_MESSAGE_RECEIVED: mOriginalCallback.onMessageReceived(msg.arg1, (byte[]) msg.obj); diff --git a/wifi/java/android/net/wifi/nan/WifiNanPublishDiscoverySession.java b/wifi/java/android/net/wifi/nan/WifiNanPublishDiscoverySession.java index c1731bbfd8177..83ff7008e0484 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanPublishDiscoverySession.java +++ b/wifi/java/android/net/wifi/nan/WifiNanPublishDiscoverySession.java @@ -21,7 +21,7 @@ import android.util.Log; /** * A class representing a NAN publish session. Created when - * {@link WifiNanManager#publish(PublishConfig, WifiNanDiscoverySessionCallback)} is called and a + * {@link WifiNanSession#publish(PublishConfig, WifiNanDiscoverySessionCallback)} is called and a * discovery session is created and returned in * {@link WifiNanDiscoverySessionCallback#onPublishStarted(WifiNanPublishDiscoverySession)}. See * baseline functionality of all discovery sessions in {@link WifiNanDiscoveryBaseSession}. This @@ -44,9 +44,9 @@ public class WifiNanPublishDiscoverySession extends WifiNanDiscoveryBaseSession * at creation is still used. The results of the configuration are returned using * {@link WifiNanDiscoverySessionCallback}: *

    diff --git a/wifi/java/android/net/wifi/nan/WifiNanSession.java b/wifi/java/android/net/wifi/nan/WifiNanSession.java index f9e6017955520..21cc159bf2464 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanSession.java +++ b/wifi/java/android/net/wifi/nan/WifiNanSession.java @@ -57,23 +57,23 @@ public class WifiNanSession { mClientId = clientId; mTerminated = false; - mCloseGuard.open("disconnect"); + mCloseGuard.open("destroy"); } /** - * 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. + * Destroy the Wi-Fi NAN service session and, if no other applications are attached to NAN, + * also disable NAN. 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 destroy these discovery sessions and connections explicitly before a + * session-wide destroy. *

    - * An application may re-connect after a disconnect using - * {@link WifiNanManager#connect(Handler, WifiNanEventCallback)} . + * An application may re-attach after a destroy using + * {@link WifiNanManager#attach(Handler, WifiNanEventCallback)} . */ - public void disconnect() { + public void destroy() { WifiNanManager mgr = mMgr.get(); if (mgr == null) { - Log.w(TAG, "disconnect: called post GC on WifiNanManager"); + Log.w(TAG, "destroy: called post GC on WifiNanManager"); return; } mgr.disconnect(mClientId, mBinder); @@ -88,7 +88,7 @@ public class WifiNanSession { try { if (!mTerminated) { mCloseGuard.warnIfOpen(); - disconnect(); + destroy(); } } finally { super.finalize(); @@ -103,7 +103,7 @@ public class WifiNanSession { *

  • {@link WifiNanDiscoverySessionCallback#onPublishStarted(WifiNanPublishDiscoverySession)} * 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. - *
  • {@link WifiNanDiscoverySessionCallback#onSessionConfigFail(int)} is called if the + *
  • {@link WifiNanDiscoverySessionCallback#onSessionConfigFailed(int)} is called if the * publish operation failed. * *

    @@ -111,7 +111,7 @@ public class WifiNanSession { * on the {@code callback} object. The resulting publish session can be modified using * {@link WifiNanPublishDiscoverySession#updatePublish(PublishConfig)}. *

    - * An application must use the {@link WifiNanDiscoveryBaseSession#terminate()} to + * An application must use the {@link WifiNanDiscoveryBaseSession#destroy()} to * terminate the publish discovery session once it isn't needed. This will free * resources as well terminate any on-air transmissions. * @@ -142,7 +142,7 @@ public class WifiNanSession { *

  • {@link WifiNanDiscoverySessionCallback#onSubscribeStarted(WifiNanSubscribeDiscoverySession)} * 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. - *
  • {@link WifiNanDiscoverySessionCallback#onSessionConfigFail(int)} is called if the + *
  • {@link WifiNanDiscoverySessionCallback#onSessionConfigFailed(int)} is called if the * subscribe operation failed. * *

    @@ -150,7 +150,7 @@ public class WifiNanSession { * on the {@code callback} object. The resulting subscribe session can be modified using * {@link WifiNanSubscribeDiscoverySession#updateSubscribe(SubscribeConfig)}. *

    - * An application must use the {@link WifiNanDiscoveryBaseSession#terminate()} to + * An application must use the {@link WifiNanDiscoveryBaseSession#destroy()} to * terminate the subscribe discovery session once it isn't needed. This will free * resources as well terminate any on-air transmissions. * diff --git a/wifi/java/android/net/wifi/nan/WifiNanSubscribeDiscoverySession.java b/wifi/java/android/net/wifi/nan/WifiNanSubscribeDiscoverySession.java index b8d77aa1f8e48..7aa97c6fcd8c7 100644 --- a/wifi/java/android/net/wifi/nan/WifiNanSubscribeDiscoverySession.java +++ b/wifi/java/android/net/wifi/nan/WifiNanSubscribeDiscoverySession.java @@ -21,7 +21,7 @@ import android.util.Log; /** * A class representing a NAN subscribe session. Created when - * {@link WifiNanManager#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} is called + * {@link WifiNanSession#subscribe(SubscribeConfig, WifiNanDiscoverySessionCallback)} is called * and a discovery session is created and returned in * {@link WifiNanDiscoverySessionCallback#onSubscribeStarted(WifiNanSubscribeDiscoverySession)}. * See baseline functionality of all discovery sessions in {@link WifiNanDiscoveryBaseSession}. @@ -46,9 +46,9 @@ public class WifiNanSubscribeDiscoverySession extends WifiNanDiscoveryBaseSessio * at creation is still used. The results of the configuration are returned using * {@link WifiNanDiscoverySessionCallback}: *