Wi-Fi Direct (P2P) 可讓具有適當硬體的裝置透過 Wi-Fi 直接相互連線,而不需使用中繼存取點。使用這些 API 時,只要每部裝置都支援 Wi-Fi P2P,您就可以探索及連線至其他裝置,然後用遠遠的高速連線進行通訊,比藍牙連線要長得多。這對於與使用者共用資料的應用程式而言非常實用,例如多人對戰遊戲或相片分享應用程式。
Wi-Fi P2P API 由以下幾個主要部分組成:
- 可讓您探索、要求及連線至對等點的方法,這些方法是在
WifiP2pManager
類別中定義。 - 允許您接收
WifiP2pManager
方法呼叫成功或失敗通知的事件監聽器。呼叫WifiP2pManager
方法時,每個方法都可以接收做為參數傳入的特定事件監聽器。 - 意圖會在 Wi-Fi P2P 架構偵測到特定事件時通知您,例如連線中斷或新發現的對等點。
您通常會同時使用這三個 API 主要元件。舉例來說,您可以提供 WifiP2pManager.ActionListener
呼叫 discoverPeers()
,以便 ActionListener.onSuccess()
和 ActionListener.onFailure()
方法通知您。如果 discoverPeers()
方法發現對等清單已變更,系統也會廣播 WIFI_P2P_PEERS_CHANGED_ACTION
意圖。
API 總覽
WifiP2pManager
類別提供各種方法,讓您與裝置上的 Wi-Fi 硬體互動,以便執行探索及連線至同類應用程式等操作。可執行的動作如下:
表 1. Wi-Fi P2P 方法
方法 | 說明 |
initialize()
|
使用 Wi-Fi 架構註冊應用程式。請先呼叫此方法,再呼叫任何其他 Wi-Fi P2P 方法。 |
connect()
|
針對具有指定設定的裝置啟動點對點連線。 |
cancelConnect()
|
取消任何進行中的點對點群組協商。 |
requestConnectInfo()
|
要求裝置的連線資訊。 |
createGroup()
|
建立將目前裝置設為群組擁有者的點對點群組。 |
removeGroup()
|
移除目前的點對點群組。 |
requestGroupInfo()
|
要求點對點群組資訊。 |
discoverPeers()
|
啟動對等互連探索。 |
requestPeers()
|
要求目前已發現的對等互連項目清單。 |
WifiP2pManager
方法可讓您傳入事件監聽器,這樣 Wi-Fi P2P 架構才能通知通話狀態。表 2 說明可用的事件監聽器介面,以及使用事件監聽器的對應 WifiP2pManager
方法呼叫。
表 2. Wi-Fi P2P 監聽器
事件監聽器介面 | 關聯動作 |
WifiP2pManager.ActionListener
|
connect() 、cancelConnect() 、createGroup() 、removeGroup() 和 discoverPeers() |
WifiP2pManager.ChannelListener
|
initialize()
|
WifiP2pManager.ConnectionInfoListener
|
requestConnectInfo()
|
WifiP2pManager.GroupInfoListener
|
requestGroupInfo()
|
WifiP2pManager.PeerListListener
|
requestPeers()
|
Wi-Fi P2P API 會定義在特定 Wi-Fi P2P 事件發生時 (例如發現新的對等互連或裝置 Wi-Fi 狀態變更) 時廣播的意圖。您可以建立處理這些意圖的廣播接收器,在應用程式中註冊接收這些意圖:
表 3. Wi-Fi P2P 意圖
意圖 | 說明 |
WIFI_P2P_CONNECTION_CHANGED_ACTION
|
在裝置的 Wi-Fi 連線狀態變更時廣播。 |
WIFI_P2P_PEERS_CHANGED_ACTION
|
在你撥打 discoverPeers() 時廣播。在應用程式中處理此意圖時,您通常會呼叫 requestPeers() 來取得最新的對等項目清單。 |
WIFI_P2P_STATE_CHANGED_ACTION
|
在裝置啟用或停用 Wi-Fi P2P 時播送。 |
WIFI_P2P_THIS_DEVICE_CHANGED_ACTION
|
在裝置詳細資料變更 (例如裝置名稱) 時廣播。 |
建立 Wi-Fi P2P 意圖的廣播接收器
廣播接收器可讓您接收由 Android 系統廣播的意圖,讓應用程式可以回應您感興趣的事件。建立廣播接收器以處理 Wi-Fi P2P 意圖的基本步驟如下:
建立可擴充
BroadcastReceiver
類別的類別。在類別的建構函式中,您需要使用WifiP2pManager
、WifiP2pManager.Channel
的參數,以及此廣播接收器註冊的活動。如此一來,廣播接收器就能傳送更新內容至活動,並視需要存取 Wi-Fi 硬體和通訊管道。請在廣播接收器中,透過
onReceive()
方法檢查您感興趣的意圖。根據收到的意圖執行任何必要動作。舉例來說,如果廣播接收器收到WIFI_P2P_PEERS_CHANGED_ACTION
意圖,您可以呼叫requestPeers()
方法,取得目前偵測到的對等點清單。
以下程式碼說明如何建立一般廣播接收器。廣播接收器使用 WifiP2pManager
物件和活動做為引數,並在廣播接收器收到意圖時,使用以下兩個類別正確執行必要動作:
Kotlin
/** * A BroadcastReceiver that notifies of important Wi-Fi p2p events. */ class WiFiDirectBroadcastReceiver( private val manager: WifiP2pManager, private val channel: WifiP2pManager.Channel, private val activity: MyWifiActivity ) : BroadcastReceiver() { override fun onReceive(context: Context, intent: Intent) { val action: String = intent.action when (action) { WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION -> { // Check to see if Wi-Fi is enabled and notify appropriate activity } WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION -> { // Call WifiP2pManager.requestPeers() to get a list of current peers } WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION -> { // Respond to new connection or disconnections } WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION -> { // Respond to this device's wifi state changing } } } }
Java
/** * A BroadcastReceiver that notifies of important Wi-Fi p2p events. */ public class WiFiDirectBroadcastReceiver extends BroadcastReceiver { private WifiP2pManager manager; private Channel channel; private MyWiFiActivity activity; public WiFiDirectBroadcastReceiver(WifiP2pManager manager, Channel channel, MyWifiActivity activity) { super(); this.manager = manager; this.channel = channel; this.activity = activity; } @Override public void onReceive(Context context, Intent intent) { String action = intent.getAction(); if (WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION.equals(action)) { // Check to see if Wi-Fi is enabled and notify appropriate activity } else if (WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION.equals(action)) { // Call WifiP2pManager.requestPeers() to get a list of current peers } else if (WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION.equals(action)) { // Respond to new connection or disconnections } else if (WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION.equals(action)) { // Respond to this device's wifi state changing } } }
在搭載 Android 10 以上版本的裝置上,下列廣播意圖並非固定式:
WIFI_P2P_CONNECTION_CHANGED_ACTION
- 應用程式可以使用
requestConnectionInfo()
、requestNetworkInfo()
或requestGroupInfo()
擷取目前的連線資訊。 WIFI_P2P_THIS_DEVICE_CHANGED_ACTION
- 應用程式可以使用
requestDeviceInfo()
擷取目前的連線資訊。
建立 Wi-Fi P2P 應用程式
如要建立 Wi-Fi P2P 應用程式,您需要為應用程式建立及註冊廣播接收器、探索對等點、連線至對等點,以及將資料傳輸至對等互連。以下各節將說明如何執行這項作業。
初始設定
使用 Wi-Fi P2P API 之前,您必須確保應用程式可以存取硬體,且裝置支援 Wi-Fi P2P 通訊協定。如果支援 Wi-Fi P2P,您可以取得 WifiP2pManager
的執行個體、建立並註冊廣播接收器,然後開始使用 Wi-Fi P2P API。
請要求取得使用裝置 Wi-Fi 硬體的權限,並宣告應用程式在 Android 資訊清單中有正確的 SDK 最低版本:
<uses-sdk android:minSdkVersion="14" /> <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" /> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- If your app targets Android 13 (API level 33) or higher, you must declare the NEARBY_WIFI_DEVICES permission. --> <uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" <!-- If your app derives location information from Wi-Fi APIs, don't include the "usesPermissionFlags" attribute. --> android:usesPermissionFlags="neverForLocation" /> <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" <!-- If any feature in your app relies on precise location information, don't include the "maxSdkVersion" attribute. --> android:maxSdkVersion="32" />
除了上述權限以外,下列 API 也需要啟用位置模式:
檢查 Wi-Fi P2P 是否開啟並受到支援。當系統收到
WIFI_P2P_STATE_CHANGED_ACTION
意圖時,建議您在廣播接收器中確認這一點。通知 Wi-Fi P2P 狀態的活動,並視情況做出回應:Kotlin
override fun onReceive(context: Context, intent: Intent) { ... val action: String = intent.action when (action) { WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION -> { val state = intent.getIntExtra(WifiP2pManager.EXTRA_WIFI_STATE, -1) when (state) { WifiP2pManager.WIFI_P2P_STATE_ENABLED -> { // Wifi P2P is enabled } else -> { // Wi-Fi P2P is not enabled } } } } ... }
Java
@Override public void onReceive(Context context, Intent intent) { ... String action = intent.getAction(); if (WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION.equals(action)) { int state = intent.getIntExtra(WifiP2pManager.EXTRA_WIFI_STATE, -1); if (state == WifiP2pManager.WIFI_P2P_STATE_ENABLED) { // Wifi P2P is enabled } else { // Wi-Fi P2P is not enabled } } ... }
在活動的
onCreate()
方法中,取得WifiP2pManager
的執行個體,並透過呼叫initialize()
使用 Wi-Fi P2P 架構註冊應用程式。這個方法會傳回WifiP2pManager.Channel
,用於將應用程式連線至 Wi-Fi P2P 架構。您也應使用WifiP2pManager
和WifiP2pManager.Channel
物件建立廣播接收器的執行個體,以及活動的參照。如此一來,廣播接收器就能通知您有趣的事件活動,並據此進行更新。可讓您視需要操控裝置的 Wi-Fi 狀態:Kotlin
val manager: WifiP2pManager? by lazy(LazyThreadSafetyMode.NONE) { getSystemService(Context.WIFI_P2P_SERVICE) as WifiP2pManager? } var channel: WifiP2pManager.Channel? = null var receiver: BroadcastReceiver? = null override fun onCreate(savedInstanceState: Bundle?) { ... channel = manager?.initialize(this, mainLooper, null) channel?.also { channel -> receiver = WiFiDirectBroadcastReceiver(manager, channel, this) } }
Java
WifiP2pManager manager; Channel channel; BroadcastReceiver receiver; ... @Override protected void onCreate(Bundle savedInstanceState){ ... manager = (WifiP2pManager) getSystemService(Context.WIFI_P2P_SERVICE); channel = manager.initialize(this, getMainLooper(), null); receiver = new WiFiDirectBroadcastReceiver(manager, channel, this); ... }
建立意圖篩選器並新增廣播接收器檢查的相同意圖:
Kotlin
val intentFilter = IntentFilter().apply { addAction(WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION) addAction(WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION) addAction(WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION) addAction(WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION) }
Java
IntentFilter intentFilter; ... @Override protected void onCreate(Bundle savedInstanceState){ ... intentFilter = new IntentFilter(); intentFilter.addAction(WifiP2pManager.WIFI_P2P_STATE_CHANGED_ACTION); intentFilter.addAction(WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION); intentFilter.addAction(WifiP2pManager.WIFI_P2P_CONNECTION_CHANGED_ACTION); intentFilter.addAction(WifiP2pManager.WIFI_P2P_THIS_DEVICE_CHANGED_ACTION); ... }
在活動的
onResume()
方法中註冊廣播接收器,然後在活動的onPause()
方法中取消註冊該接收器:Kotlin
/* register the broadcast receiver with the intent values to be matched */ override fun onResume() { super.onResume() receiver?.also { receiver -> registerReceiver(receiver, intentFilter) } } /* unregister the broadcast receiver */ override fun onPause() { super.onPause() receiver?.also { receiver -> unregisterReceiver(receiver) } }
Java
/* register the broadcast receiver with the intent values to be matched */ @Override protected void onResume() { super.onResume(); registerReceiver(receiver, intentFilter); } /* unregister the broadcast receiver */ @Override protected void onPause() { super.onPause(); unregisterReceiver(receiver); }
取得
WifiP2pManager.Channel
並設定廣播接收器後,應用程式即可發出 Wi-Fi P2P 方法呼叫並接收 Wi-Fi P2P 意圖。透過呼叫
WifiP2pManager
中的方法,使用 Wi-Fi P2P 功能實作應用程式。
下節將說明如何執行常用操作,例如探索和連線至對等互連項目。
探索同類應用程式
呼叫 discoverPeers()
以偵測在範圍內且可以連線的可用對等點。這個函式的呼叫並非同步;如果您建立 WifiP2pManager.ActionListener
,則會使用 onSuccess()
和 onFailure()
向應用程式傳送成功或失敗要求。onSuccess()
方法只會通知您探索程序成功,不會針對其中發現的實際對等點 (如果有的話) 提供任何相關資訊。以下程式碼範例說明如何設定這個屬性。
Kotlin
manager?.discoverPeers(channel, object : WifiP2pManager.ActionListener { override fun onSuccess() { ... } override fun onFailure(reasonCode: Int) { ... } })
Java
manager.discoverPeers(channel, new WifiP2pManager.ActionListener() { @Override public void onSuccess() { ... } @Override public void onFailure(int reasonCode) { ... } });
如果探索程序成功,並偵測到對等點,系統會廣播 WIFI_P2P_PEERS_CHANGED_ACTION
意圖,您可以在廣播接收器中監聽,以便取得對等互連清單。應用程式收到 WIFI_P2P_PEERS_CHANGED_ACTION
意圖時,您可以要求 requestPeers()
提供發現的對等互連項目清單。下列程式碼顯示設定方式。
Kotlin
override fun onReceive(context: Context, intent: Intent) { val action: String = intent.action when (action) { ... WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION -> { manager?.requestPeers(channel) { peers: WifiP2pDeviceList? -> // Handle peers list } } ... } }
Java
PeerListListener myPeerListListener; ... if (WifiP2pManager.WIFI_P2P_PEERS_CHANGED_ACTION.equals(action)) { // request available peers from the wifi p2p manager. This is an // asynchronous call and the calling activity is notified with a // callback on PeerListListener.onPeersAvailable() if (manager != null) { manager.requestPeers(channel, myPeerListListener); } }
requestPeers()
方法也為非同步性質,且可在 WifiP2pManager.PeerListListener
介面中定義的 onPeersAvailable()
提供對等點清單時通知您的活動。onPeersAvailable()
方法會提供 WifiP2pDeviceList
,您可以反覆執行疊代作業,找出要連線的對等點。
與同類應用程式交流互動
取得可能的對等點清單並選取要連線的裝置後,請呼叫 connect()
方法以連線至該裝置。這個方法呼叫需要使用 WifiP2pConfig
物件,其中包含要連結的裝置相關資訊。WifiP2pManager.ActionListener
可通知您連線成功或失敗。以下程式碼顯示如何與裝置建立連線。
Kotlin
val device: WifiP2pDevice = ... val config = WifiP2pConfig() config.deviceAddress = device.deviceAddress channel?.also { channel -> manager?.connect(channel, config, object : WifiP2pManager.ActionListener { override fun onSuccess() { //success logic } override fun onFailure(reason: Int) { //failure logic } } )}
Java
//obtain a peer from the WifiP2pDeviceList WifiP2pDevice device; WifiP2pConfig config = new WifiP2pConfig(); config.deviceAddress = device.deviceAddress; manager.connect(channel, config, new ActionListener() { @Override public void onSuccess() { //success logic } @Override public void onFailure(int reason) { //failure logic } });
轉移資料
建立連線後,即可透過通訊端在裝置之間傳輸資料。轉移資料的基本步驟如下:
- 建立
ServerSocket
。此通訊端會等待來自指定通訊埠的用戶端連線,並封鎖直到發生為止,因此請在背景執行緒中執行這項作業。 - 建立用戶端
Socket
。用戶端會使用伺服器通訊端的 IP 位址和通訊埠連線至伺服器裝置。 - 從用戶端將資料傳送至伺服器。當用戶端通訊端成功連線至伺服器通訊端時,您就能透過位元組串流將資料從用戶端傳送至伺服器。
- 伺服器通訊端會等待用戶端連線 (使用
accept()
方法)。這個呼叫會遭到封鎖,直到用戶端連線為止,因此請在另一個執行緒中呼叫此呼叫。連線發生時,伺服器裝置可以從用戶端接收資料。
以下範例從 Wi-Fi P2P 示範修改過,說明如何建立這個用戶端與伺服器通訊端通訊,並將 JPEG 圖片從用戶端轉移至與服務的伺服器。如需完整的實際範例,請編譯並執行示範。
Kotlin
class FileServerAsyncTask( private val context: Context, private var statusText: TextView ) : AsyncTask<Void, Void, String?>() { override fun doInBackground(vararg params: Void): String? { /** * Create a server socket. */ val serverSocket = ServerSocket(8888) return serverSocket.use { /** * Wait for client connections. This call blocks until a * connection is accepted from a client. */ val client = serverSocket.accept() /** * If this code is reached, a client has connected and transferred data * Save the input stream from the client as a JPEG file */ val f = File(Environment.getExternalStorageDirectory().absolutePath + "/${context.packageName}/wifip2pshared-${System.currentTimeMillis()}.jpg") val dirs = File(f.parent) dirs.takeIf { it.doesNotExist() }?.apply { mkdirs() } f.createNewFile() val inputstream = client.getInputStream() copyFile(inputstream, FileOutputStream(f)) serverSocket.close() f.absolutePath } } private fun File.doesNotExist(): Boolean = !exists() /** * Start activity that can handle the JPEG image */ override fun onPostExecute(result: String?) { result?.run { statusText.text = "File copied - $result" val intent = Intent(android.content.Intent.ACTION_VIEW).apply { setDataAndType(Uri.parse("file://$result"), "image/*") } context.startActivity(intent) } } }
Java
public static class FileServerAsyncTask extends AsyncTask { private Context context; private TextView statusText; public FileServerAsyncTask(Context context, View statusText) { this.context = context; this.statusText = (TextView) statusText; } @Override protected String doInBackground(Void... params) { try { /** * Create a server socket and wait for client connections. This * call blocks until a connection is accepted from a client */ ServerSocket serverSocket = new ServerSocket(8888); Socket client = serverSocket.accept(); /** * If this code is reached, a client has connected and transferred data * Save the input stream from the client as a JPEG file */ final File f = new File(Environment.getExternalStorageDirectory() + "/" + context.getPackageName() + "/wifip2pshared-" + System.currentTimeMillis() + ".jpg"); File dirs = new File(f.getParent()); if (!dirs.exists()) dirs.mkdirs(); f.createNewFile(); InputStream inputstream = client.getInputStream(); copyFile(inputstream, new FileOutputStream(f)); serverSocket.close(); return f.getAbsolutePath(); } catch (IOException e) { Log.e(WiFiDirectActivity.TAG, e.getMessage()); return null; } } /** * Start activity that can handle the JPEG image */ @Override protected void onPostExecute(String result) { if (result != null) { statusText.setText("File copied - " + result); Intent intent = new Intent(); intent.setAction(android.content.Intent.ACTION_VIEW); intent.setDataAndType(Uri.parse("file://" + result), "image/*"); context.startActivity(intent); } } }
在用戶端上,使用用戶端通訊端連線至伺服器通訊端,並傳輸資料。這個範例會在用戶端裝置的檔案系統中傳輸 JPEG 檔案。
Kotlin
val context = applicationContext val host: String val port: Int val len: Int val socket = Socket() val buf = ByteArray(1024) ... try { /** * Create a client socket with the host, * port, and timeout information. */ socket.bind(null) socket.connect((InetSocketAddress(host, port)), 500) /** * Create a byte stream from a JPEG file and pipe it to the output stream * of the socket. This data is retrieved by the server device. */ val outputStream = socket.getOutputStream() val cr = context.contentResolver val inputStream: InputStream = cr.openInputStream(Uri.parse("path/to/picture.jpg")) while (inputStream.read(buf).also { len = it } != -1) { outputStream.write(buf, 0, len) } outputStream.close() inputStream.close() } catch (e: FileNotFoundException) { //catch logic } catch (e: IOException) { //catch logic } finally { /** * Clean up any open sockets when done * transferring or if an exception occurred. */ socket.takeIf { it.isConnected }?.apply { close() } }
Java
Context context = this.getApplicationContext(); String host; int port; int len; Socket socket = new Socket(); byte buf[] = new byte[1024]; ... try { /** * Create a client socket with the host, * port, and timeout information. */ socket.bind(null); socket.connect((new InetSocketAddress(host, port)), 500); /** * Create a byte stream from a JPEG file and pipe it to the output stream * of the socket. This data is retrieved by the server device. */ OutputStream outputStream = socket.getOutputStream(); ContentResolver cr = context.getContentResolver(); InputStream inputStream = null; inputStream = cr.openInputStream(Uri.parse("path/to/picture.jpg")); while ((len = inputStream.read(buf)) != -1) { outputStream.write(buf, 0, len); } outputStream.close(); inputStream.close(); } catch (FileNotFoundException e) { //catch logic } catch (IOException e) { //catch logic } /** * Clean up any open sockets when done * transferring or if an exception occurred. */ finally { if (socket != null) { if (socket.isConnected()) { try { socket.close(); } catch (IOException e) { //catch logic } } } }