דף זה תורגם על ידי Cloud Translation API.

סקירה כללית על Wi-Fi Aware

יכולות ה-Wi-Fi Aware מאפשרות למכשירים עם Android מגרסה 8.0 ואילך לגלות מכשירים אחרים ולהתחבר אליהם ישירות, ללא סוג אחר של קישוריות ביניהם. Wi-Fi Aware נקרא גם Neighbor Awareness Networking (NAN).

רשתות Wi-Fi Aware פועלות על ידי יצירת אשכולות עם מכשירים שכנים, או על ידי יצירת אשכול חדש אם המכשיר הוא הראשון באזור. התנהגות הקיבוץ הזו חלה על כל המכשיר ומנוהלת על ידי שירות המערכת Wi-Fi Aware. לאפליקציות אין שליטה על התנהגות הקיבוץ. אפליקציות משתמשות ב-API של Wi-Fi Aware כדי לתקשר עם שירות המערכת של Wi-Fi Aware, שמנהל את החומרה של Wi-Fi Aware במכשיר.

ממשקי ה-API של Wi-Fi Aware מאפשרים לאפליקציות לבצע את הפעולות הבאות:

גילוי מכשירים אחרים: לממשק ה-API יש מנגנון לאיתור מכשירים אחרים בקרבת מקום. התהליך מתחיל כשמכשיר אחד מפרסם שירות אחד או יותר שגלוי לכולם. לאחר מכן, כשמכשיר נרשם לשירות אחד או יותר ונכנס לטווח ה-Wi-Fi של בעל התוכן הדיגיטלי, המנוי מקבל התראה על כך שזוהה בעל תוכן דיגיטלי תואם. אחרי שהמנוי מאתר בעל תוכן דיגיטלי, הוא יכול לשלוח הודעה קצרה או ליצור חיבור לרשת עם המכשיר שזוהה. מכשירים יכולים להיות גם מוצגים וגם מנויים בו-זמנית.
יצירת חיבור לרשת: אחרי ששני מכשירים מזהים זה את זה, הם יכולים ליצור חיבור לרשת דו-כיווני של Wi-Fi Aware בלי נקודת גישה.

חיבורי רשת של Wi-Fi Aware תומכים בקצב תעבורה גבוה יותר למרחקים ארוכים יותר מאשר חיבורי Bluetooth. סוגי החיבורים האלה שימושיים לאפליקציות שמשתפות כמויות גדולות של נתונים בין משתמשים, כמו אפליקציות לשיתוף תמונות.

שיפורים ב-Android 13 ‏ (רמת API 33)

במכשירים עם Android מגרסה 13 ואילך (רמת API‏ 33 ואילך) שתומכים במצב תקשורת מיידית, אפליקציות יכולות להשתמש בשיטות PublishConfig.Builder.setInstantCommunicationModeEnabled() ו-SubscribeConfig.Builder.setInstantCommunicationModeEnabled() כדי להפעיל או להשבית את מצב התקשורת המיידית בסשן של גילוי בעל תוכן דיגיטלי או של מנויים. מצב התקשורת המיידית מזרז את החלפת ההודעות, גילוי השירותים וכל נתיב נתונים שהוגדר כחלק מסשן גילוי של בעל תוכן דיגיטלי או של מנויים. כדי לבדוק אם מכשיר תומך במצב תקשורת מיידית, משתמשים בשיטה isInstantCommunicationModeSupported().

שיפורים ב-Android 12 (רמת API 31)

ב-Android 12 (רמת API ‏31) נוספו כמה שיפורים ל-Wi-Fi Aware:

במכשירים עם Android 12 (רמת API 31) ואילך, אפשר להשתמש ב-callback‏ onServiceLost() כדי לקבל התראה כשהאפליקציה מאבדת שירות שגילתה כי השירות הפסיק לפעול או יצא מטווח.
תהליך ההגדרה של נתיבי הנתונים של Wi-Fi Aware פשוט יותר. בגרסאות קודמות נעשה שימוש בהודעות L2 כדי לספק את כתובת ה-MAC של הגורם שהתחיל את הבקשה, וכתוצאה מכך נוצרה זמן אחזור. במכשירים עם Android מגרסה 12 ואילך, אפשר להגדיר את המכשיר המגיב (השרת) לקבלת כל מכשיר אחר – כלומר, הוא לא צריך לדעת מראש את כתובת ה-MAC של המכשיר שהתחיל את ההתחברות. כך אפשר להאיץ את ההפעלה של נתיב הנתונים ולאפשר מספר קישורים מקצה לקצה באמצעות בקשת רשת אחת בלבד.
אפליקציות שפועלות ב-Android בגרסה 12 ואילך יכולות להשתמש ב-method‏ WifiAwareManager.getAvailableAwareResources() כדי לקבל את מספר נתיבי הנתונים הזמינים כרגע, לפרסם סשנים ולהירשם לסשנים. כך האפליקציה יכולה לקבוע אם יש מספיק משאבים זמינים כדי לבצע את הפונקציות הרצויות.

הגדרה ראשונית

כדי להגדיר את האפליקציה כך שתשתמש בגילוי וברשתות של Wi-Fi Aware:

מבקשים את ההרשאות הבאות במניפסט של האפליקציה:

<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" />
<!-- 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" />

בודקים אם המכשיר תומך ב-Wi-Fi Aware באמצעות ה-API‏ PackageManager, כפי שמתואר בהמשך:

Kotlin

context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE)

Java

context.getPackageManager().hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE);

בודקים אם התכונה Wi-Fi Aware זמינה כרגע. יכול להיות ש-Wi-Fi Aware קיים במכשיר, אבל יכול להיות שהוא לא זמין כרגע כי המשתמש השבית את ה-Wi-Fi או את המיקום. בהתאם ליכולות החומרה והקושחה שלהם, יכול להיות שמכשירים מסוימים לא יתמכו ב-Wi-Fi Aware אם נעשה בהם שימוש ב-Wi-Fi Direct, ב-SoftAP או בהצמדה. כדי לבדוק אם התכונה Wi-Fi Aware זמינה כרגע, צריך להפעיל את הפקודה isAvailable().

הזמינות של Wi-Fi Aware עשויה להשתנות בכל שלב. האפליקציה צריכה לרשום BroadcastReceiver כדי לקבל את ההודעה ACTION_WIFI_AWARE_STATE_CHANGED, שנשלחת בכל פעם שהזמינות משתנה. כשהאפליקציה מקבלת את כוונה השידור, היא צריכה לבטל את כל הסשנים הקיימים (בהנחה ששירות Wi-Fi Aware הופסק), ואז לבדוק את מצב הזמינות הנוכחי ולשנות את ההתנהגות שלה בהתאם. לדוגמה:
Kotlin
```
val wifiAwareManager = context.getSystemService(Context.WIFI_AWARE_SERVICE) as WifiAwareManager?
val filter = IntentFilter(WifiAwareManager.ACTION_WIFI_AWARE_STATE_CHANGED)
val myReceiver = object : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        // discard current sessions
        if (wifiAwareManager?.isAvailable) {
            ...
        } else {
            ...
        }
    }
}
context.registerReceiver(myReceiver, filter)
```
Java
```
WifiAwareManager wifiAwareManager = 
        (WifiAwareManager)context.getSystemService(Context.WIFI_AWARE_SERVICE)
IntentFilter filter =
        new IntentFilter(WifiAwareManager.ACTION_WIFI_AWARE_STATE_CHANGED);
BroadcastReceiver myReceiver = new BroadcastReceiver() {
    @Override
    public void onReceive(Context context, Intent intent) {
        // discard current sessions
        if (wifiAwareManager.isAvailable()) {
            ...
        } else {
            ...
        }
    }
};
context.registerReceiver(myReceiver, filter);
```

מידע נוסף זמין במאמר שידורים.

קבלת סשן

כדי להתחיל להשתמש ב-Wi-Fi Aware, האפליקציה צריכה לקבל WifiAwareSession על ידי קריאה ל-attach(). השיטה הזו מבצעת את הפעולות הבאות:

הפעלת החומרה של Wi-Fi Aware.
הצטרפות לאשכולות של Wi-Fi Aware או יצירת אשכולות כאלה.
יצירת סשן של Wi-Fi Aware עם מרחב שמות ייחודי שמשמש כמאגר לכל סשני הגילוי שנוצרים בתוכו.

אם האפליקציה מצורפת בהצלחה, המערכת מבצעת את הקריאה החוזרת (callback) onAttached(). פונקציית ה-callback הזו מספקת אובייקט WifiAwareSession שצריך להשתמש בו בכל פעולות הסשן הבאות. אפליקציה יכולה להשתמש בסשן כדי לפרסם שירות או להירשם לשירות.

האפליקציה צריכה להפעיל את attach() רק פעם אחת. אם האפליקציה קוראת ל-attach() כמה פעמים, היא מקבלת סשן שונה לכל קריאה, עם מרחב שמות משלה. האפשרות הזו יכולה להיות שימושית בתרחישים מורכבים, אבל בדרך כלל כדאי להימנע ממנה.

פרסום שירות

כדי להפוך שירות לזמין, צריך להפעיל את השיטה publish(), שמקבלת את הפרמטרים הבאים:

PublishConfig מציין את שם השירות ומאפייני תצורה אחרים, כמו מסנן ההתאמה.
DiscoverySessionCallback מציין את הפעולות לביצוע כשמתרחשים אירועים, למשל כשהמנוי מקבל הודעה.

הנה דוגמה:

Kotlin

val config: PublishConfig = PublishConfig.Builder()
        .setServiceName(AWARE_FILE_SHARE_SERVICE_NAME)
        .build()
awareSession.publish(config, object : DiscoverySessionCallback() {

    override fun onPublishStarted(session: PublishDiscoverySession) {
        ...
    }

    override fun onMessageReceived(peerHandle: PeerHandle, message: ByteArray) {
        ...
    }
})

Java

PublishConfig config = new PublishConfig.Builder()
    .setServiceName(“Aware_File_Share_Service_Name”)
    .build();

awareSession.publish(config, new DiscoverySessionCallback() {
    @Override
    public void onPublishStarted(PublishDiscoverySession session) {
        ...
    }
    @Override
    public void onMessageReceived(PeerHandle peerHandle, byte[] message) {
        ...
    }
}, null);

אם הפרסום מצליח, המערכת תקרא לפונקציית הקריאה החוזרת onPublishStarted().

אחרי הפרסום, כשמכשירים עם אפליקציות תואמות למנויים נכנסים לטווח ה-Wi-Fi של המכשיר שמפרסם את השירות, המנויים מגלים את השירות. כשמנוי מגלה בעל תוכן דיגיטלי, בעל התוכן הדיגיטלי לא מקבל התראה. עם זאת, אם המנוי שולח הודעה לבעל התוכן הדיגיטלי, בעל התוכן הדיגיטלי מקבל התראה. במקרה כזה, המערכת תקרא לפונקציית הקריאה החוזרת onMessageReceived(). אפשר להשתמש בארגומנט PeerHandle מהשיטה הזו כדי לשלוח הודעה חזרה למנויים או ליצור חיבור אליהם.

כדי להפסיק את פרסום השירות, צריך להתקשר למספר DiscoverySession.close(). סשנים של Discovery משויכים לרכיב ההורה שלהם WifiAwareSession. אם הסשן הראשי נסגר, גם סשני הגילוי המשויכים אליו נסגרים. אובייקטים שהוצאו משימוש נסגרים גם כן, אבל המערכת לא מבטיחה מתי סשנים מחוץ להיקף נסגרים, לכן מומלץ להפעיל את השיטות close() באופן מפורש.

הרשמה לשירות

כדי להירשם לשירות, צריך להפעיל את השיטה subscribe() עם הפרמטרים הבאים:

SubscribeConfig מציין את שם השירות שאליו רוצים להירשם ומאפייני תצורה אחרים, כמו מסנן התאמה.
DiscoverySessionCallback מציין את הפעולות שיתבצעו כשמתרחשים אירועים, למשל כשמתגלה בעל תוכן דיגיטלי.

הנה דוגמה:

Kotlin

val config: SubscribeConfig = SubscribeConfig.Builder()
        .setServiceName(AWARE_FILE_SHARE_SERVICE_NAME)
        .build()
awareSession.subscribe(config, object : DiscoverySessionCallback() {

    override fun onSubscribeStarted(session: SubscribeDiscoverySession) {
        ...
    }

    override fun onServiceDiscovered(
            peerHandle: PeerHandle,
            serviceSpecificInfo: ByteArray,
            matchFilter: List<ByteArray>
    ) {
        ...
    }
}, null)

Java

SubscribeConfig config = new SubscribeConfig.Builder()
    .setServiceName("Aware_File_Share_Service_Name")
    .build();

awareSession.subscribe(config, new DiscoverySessionCallback() {
    @Override
    public void onSubscribeStarted(SubscribeDiscoverySession session) {
        ...
    }

    @Override
    public void onServiceDiscovered(PeerHandle peerHandle,
            byte[] serviceSpecificInfo, List<byte[]> matchFilter) {
        ...
    }
}, null);

אם פעולת ההרשמה תצליח, המערכת תפנה ל-callback‏ onSubscribeStarted() באפליקציה. מכיוון שאפשר להשתמש בארגומנט SubscribeDiscoverySession ב-callback כדי לתקשר עם בעל תוכן דיגיטלי אחרי שהאפליקציה תזהה אותו, כדאי לשמור את ההפניה הזו. אפשר לעדכן את סשן ההרשמה בכל שלב על ידי קריאה לפונקציה updateSubscribe() בסשן הגילוי.

בשלב הזה, המינוי שלכם ממתין שפלטפורמות התוכן המתאימות ייכנסו לטווח ה-Wi-Fi. במקרה כזה, המערכת מריצה את שיטת ה-callback‏ onServiceDiscovered(). אפשר להשתמש בארגומנט PeerHandle מהקריאה החוזרת (callback) הזו כדי לשלוח הודעה או ליצור חיבור למפרסם הזה.

כדי לבטל את המינוי לשירות, צריך להתקשר למספר DiscoverySession.close(). סשנים של Discovery משויכים לרכיב ההורה שלהם WifiAwareSession. אם הסשן הראשי נסגר, גם סשני הגילוי המשויכים אליו נסגרים. אובייקטים שהוצאו משימוש נסגרים גם כן, אבל המערכת לא מבטיחה מתי סשנים מחוץ להיקף נסגרים, לכן מומלץ להפעיל את השיטות close() באופן מפורש.

שליחת הודעה

כדי לשלוח הודעה למכשיר אחר, צריך את האובייקטים הבאים:

DiscoverySession. האובייקט הזה מאפשר לכם לבצע קריאה ל-sendMessage(). האפליקציה מקבלת את המאפיין DiscoverySession על ידי פרסום שירות או הרשמה למינוי לשירות.
PeerHandle של המכשיר השני, כדי לנתב את ההודעה. האפליקציה מקבלת את הערך של PeerHandle של מכשיר אחר באחת משתי דרכים:
- האפליקציה מפרסמת שירות ומקבלת הודעה ממנוי. האפליקציה מקבלת את הערך של PeerHandle של המנוי מהפונקציה החוזרת onMessageReceived().
- האפליקציה נרשמת לשירות. לאחר מכן, כשהמערכת תזהה בעל תוכן דיגיטלי תואם, האפליקציה תקבל את הערך של PeerHandle של בעל התוכן הדיגיטלי מהקריאה החוזרת (callback) של onServiceDiscovered().

כדי לשלוח הודעה, צריך להתקשר למספר sendMessage(). לאחר מכן, יכול להיות שיתבצעו הקריאות החוזרות הבאות:

כשההודעה מתקבלת בהצלחה על ידי הצד השני, המערכת מפעילה את הקריאה החוזרת (callback) onMessageSendSucceeded() באפליקציה ששולחת.
כשהצד השני מקבל הודעה, המערכת מפעילה את הפונקציה החוזרת onMessageReceived() באפליקציה המתקבלת.

למרות ש-PeerHandle נדרש לתקשורת עם עמיתים, אל תסתמכו עליו כמזהה קבוע של עמיתים. האפליקציה יכולה להשתמש במזהים ברמה גבוהה יותר – שמוטמעים בשירות הגילוי עצמו או בהודעות הבאות. אפשר להטמיע מזהה בשירות הגילוי באמצעות השיטה setMatchFilter() או השיטה setServiceSpecificInfo() של PublishConfig או SubscribeConfig. השיטה setMatchFilter() משפיעה על החשיפה, בעוד שהשיטה setServiceSpecificInfo() לא משפיעה על החשיפה.

הטמעת מזהה בהודעה מחייבת שינוי של מערך הבייטים של ההודעה כך שיכלול מזהה (לדוגמה, כבייטים הראשונים).

יצירת חיבור

Wi-Fi Aware תומך ברשתות לקוח-שרת בין שני מכשירים עם Wi-Fi Aware.

כדי להגדיר את החיבור בין השרת ללקוח:

שימוש בגילוי של Wi-Fi Aware כדי לפרסם שירות (בשרתי) ולהירשם לשירות (בלקוח).
אחרי שהמנוי מוצא את בעל התוכן הדיגיטלי, הוא יכול לשלוח הודעה ממנו לבעל התוכן הדיגיטלי.
מפעילים ServerSocket במכשיר של בעל התוכן הדיגיטלי ומגדירים את היציאה שלו או מקבלים אותה:
Kotlin
```
val ss = ServerSocket(0)
val port = ss.localPort
```
Java
```
ServerSocket ss = new ServerSocket(0);
int port = ss.getLocalPort();
```

משתמשים ב-ConnectivityManager כדי לבקש רשת Wi-Fi Aware באתר החדשות באמצעות WifiAwareNetworkSpecifier, מציינים את סשן הגילוי ואת PeerHandle של המנוי, שקיבלתם מההודעה שהמנוי שידר:

Kotlin

val networkSpecifier = WifiAwareNetworkSpecifier.Builder(discoverySession, peerHandle)
    .setPskPassphrase("somePassword")
    .setPort(port)
    .build()
val myNetworkRequest = NetworkRequest.Builder()
    .addTransportType(NetworkCapabilities.TRANSPORT_WIFI_AWARE)
    .setNetworkSpecifier(networkSpecifier)
    .build()
val callback = object : ConnectivityManager.NetworkCallback() {
    override fun onAvailable(network: Network) {
        ...
    }

    override fun onCapabilitiesChanged(network: Network, networkCapabilities: NetworkCapabilities) {
        ...
    }

    override fun onLost(network: Network) {
        ...
    }
}

connMgr.requestNetwork(myNetworkRequest, callback);

Java

NetworkSpecifier networkSpecifier = new WifiAwareNetworkSpecifier.Builder(discoverySession, peerHandle)
    .setPskPassphrase("somePassword")
    .setPort(port)
    .build();
NetworkRequest myNetworkRequest = new NetworkRequest.Builder()
    .addTransportType(NetworkCapabilities.TRANSPORT_WIFI_AWARE)
    .setNetworkSpecifier(networkSpecifier)
    .build();
ConnectivityManager.NetworkCallback callback = new ConnectivityManager.NetworkCallback() {
    @Override
    public void onAvailable(Network network) {
        ...
    }

    @Override
    public void onCapabilitiesChanged(Network network, NetworkCapabilities networkCapabilities) {
        ...
    }

    @Override
    public void onLost(Network network) {
        ...
    }
};

ConnectivityManager connMgr.requestNetwork(myNetworkRequest, callback);

אחרי שבעל התוכן הדיגיטלי מבקש רשת, הוא צריך לשלוח הודעה למנויים.
אחרי שהמנוי יקבל את ההודעה מהבעלים של האתר, צריך לבקש רשת Wi-Fi Aware במכשיר המנוי באמצעות אותה שיטה שבה משתמשים באתר. לא מציינים יציאה כשיוצרים את NetworkSpecifier. שיטות ה-callback המתאימות נקראות כשהחיבור לרשת זמין, משתנה או נותק.

אחרי שמפעילים את השיטה onAvailable() במנויים, זמין אובייקט Network שדרכו אפשר לפתוח Socket כדי לתקשר עם ServerSocket באתר החדשות, אבל צריך לדעת את כתובת ה-IPv6 והיציאה של ServerSocket. אפשר לקבל את הפרטים האלה מהאובייקט NetworkCapabilities שסופק בקריאה החוזרת onCapabilitiesChanged():

Kotlin

val peerAwareInfo = networkCapabilities.transportInfo as WifiAwareNetworkInfo
val peerIpv6 = peerAwareInfo.peerIpv6Addr
val peerPort = peerAwareInfo.port
...
val socket = network.getSocketFactory().createSocket(peerIpv6, peerPort)

Java

WifiAwareNetworkInfo peerAwareInfo = (WifiAwareNetworkInfo) networkCapabilities.getTransportInfo();
Inet6Address peerIpv6 = peerAwareInfo.getPeerIpv6Addr();
int peerPort = peerAwareInfo.getPort();
...
Socket socket = network.getSocketFactory().createSocket(peerIpv6, peerPort);

כשמסיימים את החיבור לרשת, מקישים על unregisterNetworkCallback().

הערה: יצירת בקשת רשת וציון יכולות הרשת הנדרשות אינן ספציפיות ל-Wi-Fi Aware API. מידע נוסף על עבודה עם בקשות רשת זמין במאמר ConnectivityManager.

חיפוש שותפים בטווח וגילוי מבוסס-מיקום

מכשיר עם יכולות של מיקום לפי זמן אחזור (RTT) של Wi-Fi יכול למדוד ישירות את המרחק למכשירים אחרים ולהשתמש במידע הזה כדי להגביל את גילוי השירותים של Wi-Fi Aware.

ה-Wi-Fi RTT API מאפשר למדוד את המרחק ישירות למכשיר עמית עם תמיכה ב-Wi-Fi Aware באמצעות כתובת ה-MAC או PeerHandle שלו.

אפשר להגביל את הגילוי של Wi-Fi Aware כך שיזהה רק שירותים בתוך גדר גיאוגרפית מסוימת. לדוגמה, אפשר להגדיר גדר גיאוגרפית שמאפשרת לזהות מכשיר שמפרסם שירות "Aware_File_Share_Service_Name" שנמצא במרחק של 3 מטרים לפחות (מצוין כ-3,000 מ') ולא יותר מ-10 מטרים (מצוין כ-10,000 מ').

כדי להפעיל את הגדרת הגבולות הגיאוגרפיים, גם בעל התוכן הדיגיטלי וגם המנויים צריכים לבצע פעולות:

בעלי התוכן הדיגיטלי צריכים להפעיל את הטווח בשירות שפורסם באמצעות setRangingEnabled(true).

אם בעל התוכן הדיגיטלי לא מפעיל את הטווח, המערכת תתעלם מאילוצים של גדר גיאוגרפית שצוינו על ידי המנוי ותבצע חיפוש רגיל, בלי להתחשב במרחק.
המנוי צריך לציין גדר גיאוגרפי באמצעות שילוב כלשהו של setMinDistanceMm ו-setMaxDistanceMm.

בכל אחד מהערכים, מרחק לא מצוין פירושו שאין הגבלה. אם מציינים רק את המרחק המקסימלי, המשמעות היא שהמרחק המינימלי הוא 0. אם מציינים רק את המרחק המינימלי, המשמעות היא שאין מרחק מקסימלי.

כששירות עמית מתגלה בתוך גדר גיאוגרפית, מתבצעת הפעלה חוזרת של onServiceDiscoveredWithinRange, שמספקת את המרחק שנמדד מהמכשיר שלכם למכשיר של השותף. לאחר מכן אפשר להפעיל את ה-API הישיר של RTT ב-Wi-Fi לפי הצורך כדי למדוד את המרחק במועדים מאוחרים יותר.