Merge "Prepare for exposing p2p API"

wifi/java/android/net/wifi/WpsConfiguration.java

@@ -46,16 +46,21 @@ public class WpsConfiguration implements Parcelable {
 
     public Setup setup;
 
+    /** @hide */
     public String BSSID;
 
     public String pin;
 
+    /** @hide */
     public IpAssignment ipAssignment;
 
+    /** @hide */
     public ProxySettings proxySettings;
 
+    /** @hide */
     public LinkProperties linkProperties;
 
+    /** @hide */
     public WpsConfiguration() {
         setup = Setup.INVALID;
         BSSID = null;
@@ -65,6 +70,7 @@ public class WpsConfiguration implements Parcelable {
         linkProperties = new LinkProperties();
     }
 
+    /** @hide */
     public String toString() {
         StringBuffer sbuf = new StringBuffer();
         sbuf.append(" setup: ").append(setup.toString());

wifi/java/android/net/wifi/p2p/WifiP2pConfig.java

@@ -27,11 +27,6 @@ import android.os.Parcel;
  */
 public class WifiP2pConfig implements Parcelable {
 
-    /**
-     * Device name
-     */
-    public String deviceName;
-
     /**
      * Device address
      */
@@ -53,6 +48,7 @@ public class WifiP2pConfig implements Parcelable {
 
     /**
      * Indicates whether the configuration is saved
+     * @hide
      */
     public enum Persist {
         SYSTEM_DEFAULT,
@@ -60,6 +56,7 @@ public class WifiP2pConfig implements Parcelable {
         NO
     }
 
+    /** @hide */
     public Persist persist = Persist.SYSTEM_DEFAULT;
 
     public WifiP2pConfig() {
@@ -110,7 +107,6 @@ public class WifiP2pConfig implements Parcelable {
 
     public String toString() {
         StringBuffer sbuf = new StringBuffer();
-        sbuf.append("Device: ").append(deviceName);
         sbuf.append("\n address: ").append(deviceAddress);
         sbuf.append("\n wps: ").append(wpsConfig);
         sbuf.append("\n groupOwnerIntent: ").append(groupOwnerIntent);
@@ -132,7 +128,6 @@ public class WifiP2pConfig implements Parcelable {
 
     /** Implement the Parcelable interface {@hide} */
     public void writeToParcel(Parcel dest, int flags) {
-        dest.writeString(deviceName);
         dest.writeString(deviceAddress);
         dest.writeParcelable(wpsConfig, flags);
         dest.writeInt(groupOwnerIntent);
@@ -144,7 +139,6 @@ public class WifiP2pConfig implements Parcelable {
         new Creator<WifiP2pConfig>() {
             public WifiP2pConfig createFromParcel(Parcel in) {
                 WifiP2pConfig config = new WifiP2pConfig();
-                config.deviceName = in.readString();
                 config.deviceAddress = in.readString();
                 config.wpsConfig = (WpsConfiguration) in.readParcelable(null);
                 config.groupOwnerIntent = in.readInt();

wifi/java/android/net/wifi/p2p/WifiP2pGroup.java

@@ -69,7 +69,7 @@ public class WifiP2pGroup implements Parcelable {
     }
 
     /**
-     * @param string formats supported include
+     * @param supplicantEvent formats supported include
      *
      *  P2P-GROUP-STARTED p2p-wlan0-0 [client|GO] ssid="DIRECT-W8" freq=2437
      *  [psk=2182b2e50e53f260d04f3c7b25ef33c965a3291b9b36b455a82d77fd82ca15bc|

wifi/java/android/net/wifi/p2p/WifiP2pInfo.java

@@ -34,9 +34,11 @@ public class WifiP2pInfo implements Parcelable {
 
     public InetAddress groupOwnerAddress;
 
-    public WifiP2pInfo() {
+    /** @hide */
+    WifiP2pInfo() {
     }
 
+    /** @hide */
     public String toString() {
         StringBuffer sbuf = new StringBuffer();
         sbuf.append("groupFormed: ").append(groupFormed)

wifi/java/android/net/wifi/p2p/WifiP2pManager.java

@@ -35,25 +35,64 @@ import com.android.internal.util.AsyncChannel;
 import com.android.internal.util.Protocol;
 
 /**
- * This class provides the API for managing Wi-Fi p2p
+ * This class provides the API for managing Wi-Fi peer-to-peer connectivity. This lets an
- * connectivity. Get an instance of this class by calling
+ * application discover available peers, setup connection to peers and query for the list of peers.
- * {@link android.content.Context#getSystemService(String)
+ * When a p2p connection is formed over wifi, the device continues to maintain the uplink
+ * connection over mobile or any other available network for internet connectivity on the device.
+ *
+ * <p> The API is asynchronous and response to a request from an application is sent in the form
+ * of a {@link android.os.Message} on a {@link android.os.Handler} that needs to be initialized
+ * by the application right at the beginning before any p2p operations are performed via
+ * {@link #initialize}.
+ *
+ * <p> An application can request for the current list of peers using {@link #requestPeers}. The
+ * {@link #RESPONSE_PEERS} message on the handler indicates that the peer list is available.
+ * Use {@link #peersInResponse} to extract the peer device list upon the receiving the
+ * {@link #RESPONSE_PEERS} message.
+ *
+ * <p> If an application needs to initiate a discovery, use {@link #discoverPeers} and listen
+ * to {@link #WIFI_P2P_PEERS_CHANGED_ACTION} intent action to initiate a request to fetch
+ * list of peers with {@link #requestPeers}. An initiated discovery request from an application
+ * stays active until the device starts connecting to a peer or forms a p2p group.
+ *
+ * <p> An application can initiate a connection request to a peer through {@link #connect}. See
+ * {@link WifiP2pConfig} for details on setting up the configuration. For communication with legacy
+ * Wi-Fi devices that do not support p2p, an app can create a group using {@link #createGroup}
+ * which creates an access point whose details can be fetched with {@link #requestGroupInfo}.
+ *
+ * <p> After a successful group formation through {@link #createGroup} or through {@link #connect},
+ * use {@link #requestConnectionInfo} to fetch the connection details. Connection information
+ * can be obtained with {@link #connectionInfoInResponse} on a {@link #RESPONSE_CONNECTION_INFO}
+ * message. The connection info {@link WifiP2pInfo} contains the address of the group owner
+ * {@link WifiP2pInfo#groupOwnerAddress} and a flag {@link #WifiP2pInfo#isGroupOwner} to indicate
+ * if the current device is a p2p group owner. A p2p client can thus communicate with
+ * the p2p group owner through a socket connection.
+ *
+ * <p> Android has no platform support for service discovery yet, so applications could
+ * run a service discovery protocol to discover services on the peer-to-peer netework.
+ *
+ * <p class="note"><strong>Note:</strong>
+ * Registering an application handler with {@link #initialize} requires the permissions
+ * {@link android.Manifest.permission#ACCESS_WIFI_STATE} and
+ * {@link android.Manifest.permission#CHANGE_WIFI_STATE} to perform any further peer-to-peer
+ * operations.
+ *
+ * Get an instance of this class by calling {@link android.content.Context#getSystemService(String)
  * Context.getSystemService(Context.WIFI_P2P_SERVICE)}.
  *
- * It deals with the following:
+ * {@see WifiP2pConfig}
- * <ul>
+ * {@see WifiP2pInfo}
- * <li>Wi-Fi peer discovery and connection setup. Allows applications to initiate a discovery to
+ * {@see WifiP2pGroup}
- * find available peers and then setup a connection </li>
+ * {@see WifiP2pDevice}
- * <li>Configuration and status query. Allows applications to fetch the current list
+ * {@see WifiP2pDeviceList}
- * of available and connected peers and query connection status </li>
- * <li>Intent actions that are broadcast to track operations
- * on a p2p connection</li>
- * </ul>
  * @hide
  */
 public class WifiP2pManager {
     /**
-     * Broadcast intent action to indicate whether Wi-Fi p2p is enabled or disabled.
+     * Broadcast intent action to indicate whether Wi-Fi p2p is enabled or disabled. An
+     * extra {@link #EXTRA_WIFI_STATE} provides the state information as int.
+     *
+     * @see #EXTRA_WIFI_STATE
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String WIFI_P2P_STATE_CHANGED_ACTION =
@@ -72,7 +111,6 @@ public class WifiP2pManager {
      * Wi-Fi p2p is disabled.
      *
      * @see #WIFI_P2P_STATE_CHANGED_ACTION
-     * @see #getWifiP2pState()
      */
     public static final int WIFI_P2P_STATE_DISABLED = 1;
 
@@ -80,14 +118,16 @@ public class WifiP2pManager {
      * Wi-Fi p2p is enabled.
      *
      * @see #WIFI_P2P_STATE_CHANGED_ACTION
-     * @see #getWifiP2pState()
      */
     public static final int WIFI_P2P_STATE_ENABLED = 2;
 
     /**
      * Broadcast intent action indicating that the state of Wi-Fi p2p connectivity
-     * has changed. One extra provides the new state
+     * has changed. One extra {@link #EXTRA_WIFI_P2P_INFO} provides the p2p connection info in
-     * in the form of a {@link android.net.NetworkInfo} object.
+     * the form of a {@link WifiP2pInfo} object. Another extra {@link #EXTRA_NETWORK_INFO} provides
+     * the network info in the form of a {@link android.net.NetworkInfo}.
+     *
+     * @see #EXTRA_WIFI_P2P_INFO
      * @see #EXTRA_NETWORK_INFO
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
@@ -124,7 +164,8 @@ public class WifiP2pManager {
     public static final String EXTRA_LINK_CAPABILITIES = "linkCapabilities";
 
     /**
-     * Broadcast intent action indicating that the available peer list has changed
+     * Broadcast intent action indicating that the available peer list has changed. Fetch
+     * the changed list of peers with {@link #requestPeers}
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String WIFI_P2P_PEERS_CHANGED_ACTION =
@@ -134,6 +175,7 @@ public class WifiP2pManager {
      * Activity Action: Pick a Wi-Fi p2p network to connect to.
      * <p>Input: Nothing.
      * <p>Output: Nothing.
+     * @hide
      */
     @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
     public static final String ACTION_PICK_WIFI_P2P_NETWORK =
@@ -141,47 +183,169 @@ public class WifiP2pManager {
 
     IWifiP2pManager mService;
 
-    /* AsyncChannel notifications to apps */
+    /**
-    public static final int HANDLER_CONNECTION = AsyncChannel.CMD_CHANNEL_HALF_CONNECTED;
+     * Message {@link android.os.Message#what} sent on the application handler specified
+     * at {@link #initialize} indicating the asynchronous channel has disconnected. An
+     * application could choose to reconnect with {@link #initialize}
+     */
     public static final int HANDLER_DISCONNECTION = AsyncChannel.CMD_CHANNEL_DISCONNECTED;
 
     private static final int BASE = Protocol.BASE_WIFI_P2P_MANAGER;
 
+    /** @hide */
     public static final int ENABLE_P2P                              = BASE + 1;
+    /** @hide */
     public static final int ENABLE_P2P_FAILED                       = BASE + 2;
+    /** @hide */
     public static final int ENABLE_P2P_SUCCEEDED                    = BASE + 3;
 
+    /** @hide */
     public static final int DISABLE_P2P                             = BASE + 4;
+    /** @hide */
     public static final int DISABLE_P2P_FAILED                      = BASE + 5;
+    /** @hide */
     public static final int DISABLE_P2P_SUCCEEDED                   = BASE + 6;
 
+    /** @hide */
     public static final int DISCOVER_PEERS                          = BASE + 7;
+
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #discoverPeers}
+     * operation failed.
+     * <p> The reason for failure could be one of {@link #P2P_UNSUPPORTED}, {@link #P2P_DISABLED}
+     * or {@link #ALREADY_IN_EFFECT}
+     */
     public static final int DISCOVER_PEERS_FAILED                   = BASE + 8;
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #discoverPeers}
+     * operation succeeded.
+     * <p> The application can register for {@link #WIFI_P2P_PEERS_CHANGED_ACTION} intent
+     * to listen for changes in the peer list as a result of the discovery process.
+     */
     public static final int DISCOVER_PEERS_SUCCEEDED                = BASE + 9;
 
+    /** @hide */
     public static final int CONNECT                                 = BASE + 10;
+
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #connect}
+     * operation failed.
+     * <p> The reason for failure could be one of {@link #P2P_UNSUPPORTED}, {@link #P2P_DISABLED}
+     * or {@link #ALREADY_IN_EFFECT}
+     */
     public static final int CONNECT_FAILED                          = BASE + 11;
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #connect}
+     * operation succeeded.
+     * <p> The application can register for {@link #WIFI_P2P_CONNECTION_CHANGED_ACTION} intent
+     * to listen for connectivity change as a result of the connect operation
+     */
     public static final int CONNECT_SUCCEEDED                       = BASE + 12;
 
+    /** @hide */
     public static final int CREATE_GROUP                            = BASE + 13;
+
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #createGroup}
+     * operation failed.
+     * <p> The reason for failure could be one of {@link #P2P_UNSUPPORTED}, {@link #P2P_DISABLED}
+     * or {@link #ALREADY_IN_EFFECT}
+     */
     public static final int CREATE_GROUP_FAILED                     = BASE + 14;
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #createGroup}
+     * operation succeeded.
+     * <p> The application can request the group details with {@link #requestGroupInfo}
+     */
     public static final int CREATE_GROUP_SUCCEEDED                  = BASE + 15;
 
+    /** @hide */
     public static final int REMOVE_GROUP                            = BASE + 16;
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #removeGroup}
+     * operation failed.
+     * <p> The reason for failure could be one of {@link #P2P_UNSUPPORTED}, {@link #P2P_DISABLED}
+     * or {@link #ALREADY_IN_EFFECT}
+     */
     public static final int REMOVE_GROUP_FAILED                     = BASE + 17;
+    /**
+     * Message {@link android.os.Message#what} value indicating that the {@link #removeGroup}
+     * operation succeeded.
+     */
     public static final int REMOVE_GROUP_SUCCEEDED                  = BASE + 18;
 
-    public static final int REQUEST_PEERS                           = BASE + 19;
+    /**
-    public static final int RESPONSE_PEERS                          = BASE + 20;
+     * Supported {@link android.os.Message#arg1} value on the following response messages:
-
+     * {@link #DISCOVER_PEERS_FAILED}, {@link #CONNECT_FAILED}, {@link #CREATE_GROUP_FAILED}
-    public static final int REQUEST_CONNECTION_INFO                 = BASE + 21;
+     * and {@link #REMOVE_GROUP_FAILED}
-    public static final int RESPONSE_CONNECTION_INFO                = BASE + 22;
+     *
-
+     * <p> This indicates that the reason for failure is because p2p is unsupported on the
-    /* arg1 values on response messages from the framework */
+     * device
+     */
     public static final int P2P_UNSUPPORTED     = 1;
 
+    /**
+     * Supported {@link android.os.Message#arg1} value on the following response messages:
+     * {@link #DISCOVER_PEERS_FAILED}, {@link #CONNECT_FAILED}, {@link #CREATE_GROUP_FAILED}
+     * and {@link #REMOVE_GROUP_FAILED}
+     *
+     * <p> This indicates that the reason for failure is because p2p is currently disabled
+     * by the user
+     */
+    public static final int P2P_DISABLED        = 2;
+
+    /**
+     * Supported {@link android.os.Message#arg1} value on the following response messages:
+     * {@link #DISCOVER_PEERS_FAILED}, {@link #CONNECT_FAILED}, {@link #CREATE_GROUP_FAILED}
+     * and {@link #REMOVE_GROUP_FAILED}
+     *
+     * <p> This indicates that the reason for failure is because the operation is already in
+     * effect
+     */
+    public static final int ALREADY_IN_EFFECT   = 3;
+
+
+    /** @hide */
+    public static final int REQUEST_PEERS                           = BASE + 19;
+    /**
+     * Message {@link android.os.Message#what} delivered on the application hander
+     * in response to a {@link #requestPeers} call from the application.
+     *
+     * <p> Extract a {@link WifiP2pDeviceList} object by calling {@link #peersInResponse}
+     * on the message object
+     */
+    public static final int RESPONSE_PEERS                          = BASE + 20;
+
+    /** @hide */
+    public static final int REQUEST_CONNECTION_INFO                 = BASE + 21;
+
+    /**
+     * Message {@link android.os.Message#what} delivered on the application hander
+     * in response to a {@link #requestConnectionInfo} call from the application.
+     *
+     * <p> Extract a {@link WifiP2pInfo} object by calling {@link #connectionInfoInResponse}
+     * on the message object
+     */
+    public static final int RESPONSE_CONNECTION_INFO                = BASE + 22;
+
+    /** @hide */
+    public static final int REQUEST_GROUP_INFO                      = BASE + 23;
+
+    /**
+     * Message {@link android.os.Message#what} delivered on the application hander
+     * in response to a {@link #requestGroupInfo} call from the application.
+     *
+     * <p> Extract a {@link WifiP2pGroup} object by calling {@link #groupInfoInResponse}
+     * on the message object
+     */
+
+    public static final int RESPONSE_GROUP_INFO                     = BASE + 24;
+
+    /** @hide */
     public static final int WPS_PBC                                 = BASE + 23;
+    /** @hide */
     public static final int WPS_PIN                                 = BASE + 24;
+    /** @hide */
     public static final int WPS_PIN_AVAILABLE                       = BASE + 25;
 
     /**
@@ -199,7 +363,8 @@ public class WifiP2pManager {
 
     /**
      * A channel that connects the application handler to the Wifi framework.
-     * All p2p operations are performed on a channel.
+     * Most p2p operations require a Channel as an argument. An instance of Channel is obtained
+     * by doing a call on {@link #initialize}
      */
     public class Channel {
         Channel(AsyncChannel c) {
@@ -210,10 +375,17 @@ public class WifiP2pManager {
 
     /**
      * Registers the application handler with the Wi-Fi framework. This function
-     * must be the first to be called before any p2p control or query operations can be performed.
+     * must be the first to be called before any p2p operations are performed.
+     *
+     * <p class="note"><strong>Note:</strong>
+     * The handler registered with the framework should only handle messages
+     * with {@link android.os.Message#what} values defined in this file. Adding application
+     * specific private {@link android.os.Message#what} types should be done on a seperate handler
+     *
      * @param srcContext is the context of the source
-     * @param srcHandler is the handler on which the source receives messages
+     * @param srcHandler is the handler on which the source will receive message responses
-     * @return Channel instance that is necessary for performing p2p operations
+     * asynchronously
+     * @return Channel instance that is necessary for performing any further p2p operations
      */
     public Channel initialize(Context srcContext, Handler srcHandler) {
         Messenger messenger = getMessenger();
@@ -229,6 +401,7 @@ public class WifiP2pManager {
         }
     }
 
+    /** @hide */
     public boolean isP2pSupported() {
         try {
             return mService.isP2pSupported();
@@ -240,6 +413,7 @@ public class WifiP2pManager {
     /**
      * Sends in a request to the system to enable p2p. This will pop up a dialog
      * to the user and upon authorization will enable p2p.
+     * @hide
      */
     public void enableP2p(Channel c) {
         if (c == null) return;
@@ -249,6 +423,7 @@ public class WifiP2pManager {
     /**
      * Sends in a request to the system to disable p2p. This will pop up a dialog
      * to the user and upon authorization will enable p2p.
+     * @hide
      */
     public void disableP2p(Channel c) {
         if (c == null) return;
@@ -256,7 +431,22 @@ public class WifiP2pManager {
     }
 
     /**
-     * Initiates peer discovery
+     * Initiate peer discovery. A discovery process involves scanning for available Wi-Fi peers
+     * for the purpose of establishing a connection.
+     *
+     * <p> The function call immediately returns after sending a discovery request
+     * to the framework. The application handler is notified of a success or failure to initiate
+     * discovery with {@link #DISCOVER_PEERS_SUCCEEDED} or {@link #DISCOVER_PEERS_FAILED}.
+     *
+     * <p> The discovery remains active until a connection is initiated or
+     * a p2p group is formed. Register for {@link #WIFI_P2P_PEERS_CHANGED_ACTION} intent to
+     * determine when the framework notifies of a change as peers are discovered.
+     *
+     * <p> Upon receiving a {@link #WIFI_P2P_PEERS_CHANGED_ACTION} intent, an application
+     * can request for the list of peers using {@link #requestPeers} which will deliver a
+     * {@link #RESPONSE_PEERS} message on the application handler. The application can then
+     * extract a {@link WifiP2pDeviceList} object by calling {@link #peersInResponse}
+     * on the message.
      */
     public void discoverPeers(Channel c) {
         if (c == null) return;
@@ -264,9 +454,23 @@ public class WifiP2pManager {
     }
 
     /**
-     * Start a p2p connection
+     * Start a p2p connection to a device with the specified configuration.
      *
-     * @param peer Configuration described in a {@link WifiP2pConfig} object.
+     * <p> The function call immediately returns after sending a connection request
+     * to the framework. The application handler is notified of a success or failure to initiate
+     * connectivity with {@link #CONNECT_SUCCEEDED} or {@link #CONNECT_FAILED}.
+     *
+     * <p> Register for {@link #WIFI_P2P_CONNECTION_CHANGED_ACTION} intent to
+     * determine when the framework notifies of a change in connectivity.
+     *
+     * <p> If the current device is not part of a p2p group, a connect request initiates
+     * a group negotiation with the peer.
+     *
+     * <p> If the current device is part of an existing p2p group or has created
+     * a p2p group with {@link #createGroup}, an invitation to join the group is sent to
+     * the peer device.
+     *
+     * @param config options as described in {@link WifiP2pConfig} class.
      */
     public void connect(Channel c, WifiP2pConfig config) {
         if (c == null) return;
@@ -274,8 +478,20 @@ public class WifiP2pManager {
     }
 
     /**
-     * Create a p2p group. This is essentially an access point that can accept
+     * Create a p2p group with the current device as the group owner. This essentially creates
-     * client connections.
+     * an access point that can accept connections from legacy clients as well as other p2p
+     * devices.
+     * <p> For p2p operation, this would normally not be used unless the current device needs
+     * to form a p2p connection with a legacy client
+     *
+     * <p> The function call immediately returns after sending a group creation request
+     * to the framework. The application handler is notified of a success or failure to create
+     * group with {@link #CREATE_GROUP_SUCCEEDED} or {@link #CREATE_GROUP_FAILED}.
+     *
+     * <p> Application can request for the group details with {@link #requestGroupInfo} which will
+     * deliver a {@link #RESPONSE_GROUP_INFO} message on the application handler. The application
+     * can then extract a {@link WifiP2pGroup} object by calling {@link #groupInfoInResponse}
+     * on the message.
      */
     public void createGroup(Channel c) {
         if (c == null) return;
@@ -283,8 +499,11 @@ public class WifiP2pManager {
     }
 
     /**
-     * Remove the current group. This also removes the p2p interface created
+     * Remove the current p2p group.
-     * during group formation.
+     *
+     * <p> The function call immediately returns after sending a group removal request
+     * to the framework. The application handler is notified of a success or failure to remove
+     * a group with {@link #REMOVE_GROUP_SUCCEEDED} or {@link #REMOVE_GROUP_FAILED}.
      */
     public void removeGroup(Channel c) {
         if (c == null) return;
@@ -292,8 +511,9 @@ public class WifiP2pManager {
     }
 
     /**
-     * Request the list of peers. This returns a RESPONSE_PEERS on the source
+     * Request the current list of peers. This returns a {@link #RESPONSE_PEERS} on the application
-     * handler.
+     * handler. The {@link #RESPONSE_PEERS} message on the handler indicates that the peer list is
+     * available. Use {@link #peersInResponse} to extract {@link WifiP2pDeviceList} from the message
      */
     public void requestPeers(Channel c) {
         if (c == null) return;
@@ -301,15 +521,18 @@ public class WifiP2pManager {
     }
 
     /**
-     * Fetch device list from a RESPONSE_PEERS message
+     * Upon receiving a {@link #RESPONSE_PEERS} on the application handler, an application
+     * can extract the peer device list using this function.
      */
     public WifiP2pDeviceList peersInResponse(Message msg) {
         return (WifiP2pDeviceList) msg.obj;
     }
 
     /**
-     * Request device connection info. This returns a RESPONSE_CONNECTION_INFO on
+     * Request device connection info. This returns a {@link #RESPONSE_CONNECTION_INFO} on
-     * the source handler.
+     * the application handler. The {@link #RESPONSE_CONNECTION_INFO} message on the handler
+     * indicates that connection info is available. Use {@link #connectionInfoInResponse} to
+     * extract {@link WifiP2pInfo} from the message.
      */
     public void requestConnectionInfo(Channel c) {
         if (c == null) return;
@@ -317,12 +540,31 @@ public class WifiP2pManager {
     }
 
     /**
-     * Fetch p2p connection status from a RESPONSE_CONNECTION_INFO message
+     * Upon receiving a {@link #RESPONSE_CONNECTION_INFO} on the application handler, an application
+     * can extract the connection info using this function.
      */
     public WifiP2pInfo connectionInfoInResponse(Message msg) {
         return (WifiP2pInfo) msg.obj;
     }
 
+    /**
+     * Request p2p group info. This returns a {@link #RESPONSE_GROUP_INFO} on
+     * the application handler. The {@link #RESPONSE_GROUP_INFO} message on the handler
+     * indicates that group info is available. Use {@link #groupInfoInResponse} to
+     * extract {@link WifiP2pGroup} from the message.
+     */
+    public void requestGroupInfo(Channel c) {
+        if (c == null) return;
+        c.mAsyncChannel.sendMessage(REQUEST_GROUP_INFO);
+    }
+
+    /**
+     * Upon receiving a {@link #RESPONSE_GROUP_INFO} on the application handler, an application
+     * can extract the group info using this function.
+     */
+    public WifiP2pGroup groupInfoInResponse(Message msg) {
+        return (WifiP2pGroup) msg.obj;
+    }
 
     /**
      * Get a reference to WifiP2pService handler. This is used to establish
@@ -339,7 +581,6 @@ public class WifiP2pManager {
         }
     }
 
-
     /**
      * Setup DNS connectivity on the current process to the connected Wi-Fi p2p peers
      *