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 事件監聽器
| Listener 介面 | 相關動作 |
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 Wi-Fi 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 Wi-Fi 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 -> { // Wi-Fi 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) { // Wi-Fi P2P is enabled } else { // Wi-Fi P2P is not enabled } } ... }在活動的
onCreate()方法中,取得WifiP2pManager的例項,並呼叫initialize(),向 Wi-Fi P2P 架構註冊應用程式。這個方法會傳回WifiP2pManager.Channel,用於將應用程式連結至 Wi-Fi P2P 架構。您也應使用WifiP2pManager和WifiP2pManager.Channel物件,以及活動參照,建立廣播接收器的例項。這項設定可讓廣播接收器通知活動相關事件,並據此更新活動。如有需要,您也可以使用這個 API 操控裝置的 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 Wi-Fi 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() 方法也是非同步的,當對等點清單可用時,可以使用 onPeersAvailable() 通知您的活動,該方法在 WifiP2pManager.PeerListListener 介面中定義。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
}
}
}
}