Omówienie Wi-Fi Aware

Funkcje Wi-Fi Aware umożliwiają urządzeniom z Androidem w wersji 8.0 (poziom interfejsu API 26) i wyższych wykrywanie i łączenie się bezpośrednio ze sobą bez korzystania z innych typów połączeń. Wi-Fi Aware jest też nazywany Neighbor Awareness Networking (NAN).

Sieć Wi-Fi Aware działa poprzez tworzenie klastrów z sąsiednimi urządzeniami lub tworzenie nowego klastra, jeśli urządzenie jest pierwsze w danym obszarze. To zachowanie dotyczy całego urządzenia i jest zarządzane przez usługę systemową Wi-Fi Aware. Aplikacje nie mają kontroli nad tym zachowaniem. Aplikacje korzystają z interfejsów API Wi-Fi Aware, aby komunikować się z usługą systemową Wi-Fi Aware, która zarządza sprzętem Wi-Fi Aware na urządzeniu.

Interfejsy API Wi-Fi Aware umożliwiają aplikacjom wykonywanie tych operacji:

• Wykrywanie innych urządzeń: interfejs API zawiera mechanizm umożliwiający wykrywanie innych urządzeń w pobliżu. Proces rozpoczyna się, gdy jedno urządzenie opublikuje co najmniej jedną usługę możliwą do znalezienia. Gdy urządzenie zasubskrybuje co najmniej 1 usługę i wejdzie w zakres sieci Wi-Fi wydawcy, subskrybent otrzyma powiadomienie o wykryciu odpowiedniego wydawcy. Gdy subskrybent wykryje wydawcę, może wysłać krótką wiadomość lub nawiązać połączenie sieciowe z wykrytym urządzeniem. Urządzenia mogą jednocześnie pełnić rolę wydawców i subskrybentów.

• Tworzenie połączenia sieciowego: po wykryciu siebie nawzajem przez 2 urządzenia mogą one utworzyć dwukierunkowe połączenie sieciowe Wi-Fi Aware bez punktu dostępu.

Połączenia sieciowe Wi-Fi Aware obsługują wyższe przepływy danych na większe odległości niż połączenia Bluetooth. Tego typu połączenia są przydatne w przypadku aplikacji, które udostępniają duże ilości danych między użytkownikami, np. aplikacji do udostępniania zdjęć.

Ulepszenia w Androidzie 13 (poziom 33 interfejsu API)

Na urządzeniach z Androidem 13 (poziom interfejsu API 33) lub nowszym, które obsługują tryb komunikacji natychmiastowej, aplikacje mogą używać metod PublishConfig.Builder.setInstantCommunicationModeEnabled() i SubscribeConfig.Builder.setInstantCommunicationModeEnabled(), aby włączyć lub wyłączyć tryb komunikacji natychmiastowej w sesji odkrywania dla wydawcy lub subskrybenta. Tryb komunikacji natychmiastowej przyspiesza wymianę wiadomości, wykrywanie usług i jakiekolwiek ścieżki danych skonfigurowane w ramach sesji odkrywania wydawcy lub subskrybenta. Aby sprawdzić, czy urządzenie obsługuje tryb komunikacji błyskawicznej, użyj metody isInstantCommunicationModeSupported().

Uwaga: tryb komunikacji natychmiastowej zużywa dodatkową energię, dlatego pozostaje włączony tylko przez 30 sekund od momentu rozpoczęcia sesji wyszukiwania wydawcy lub subskrybenta.

Ulepszenia w Androidzie 12 (poziom 31 interfejsu API)

Android 12 (poziom API 31) wprowadza kilka ulepszeń funkcji Wi-Fi Aware:

• Na urządzeniach z Androidem 12 (poziom interfejsu API 31) lub nowszym możesz użyć wywołania zwrotnego onServiceLost(), aby otrzymywać powiadomienia, gdy aplikacja utraci wykrytą usługę z powodu jej zatrzymania lub wyjścia poza zasięg.
• Uproszczona została konfiguracja ścieżek danych Wi-Fi Aware. Wcześniejsze wersje używały przesyłania wiadomości L2 do udostępniania adresu MAC inicjatora, co powodowało opóźnienia. Na urządzeniach z Androidem 12 lub nowszym można skonfigurować serwer (odpowiadający) tak, aby akceptował dowolnego peera, czyli nie musiał znać adresu MAC inicjatora. Przyspiesza to konfigurowanie ścieżki danych i umożliwia tworzenie wielu połączeń punkt-punkt za pomocą tylko jednego żądania sieciowego.
• Aplikacje działające na Androidzie 12 lub nowszym mogą używać metody WifiAwareManager.getAvailableAwareResources() do uzyskiwania liczby obecnie dostępnych ścieżek danych, publikowania sesji i subskrybowania sesji. Dzięki temu aplikacja może określić, czy ma wystarczająco dużo dostępnych zasobów do wykonania żądanej funkcji.

Konfiguracja początkowa

Aby skonfigurować aplikację do korzystania z usług wykrywania i tworzenia sieci Wi-Fi Aware, wykonaj te czynności:

1. W pliku manifestu aplikacji poproś o te uprawnienia:

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

2. Sprawdź, czy urządzenie obsługuje Wi-Fi Aware, korzystając z interfejsu API PackageManager, jak pokazano poniżej:

   Kotlin

   context.packageManager.hasSystemFeature(PackageManager.FEATURE_WIFI_AWARE)

   Java

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

3. Sprawdź, czy Wi-Fi Aware jest obecnie dostępne. Wi-Fi Aware może być dostępne na urządzeniu, ale może być obecnie niedostępne, ponieważ użytkownik wyłączył Wi-Fi lub Lokalizację. W zależności od możliwości sprzętowych i oprogramowania niektóre urządzenia mogą nie obsługiwać Wi-Fi Aware, jeśli używane są Wi-Fi Direct, SoftAP lub tethering. Aby sprawdzić, czy funkcja Wi-Fi Aware jest obecnie dostępna, zadzwoń pod numerisAvailable().

   Dostępność Wi-Fi Aware może się zmieniać w dowolnym momencie. Aplikacja powinna zarejestrować BroadcastReceiver, aby otrzymywać ACTION_WIFI_AWARE_STATE_CHANGED, które jest wysyłane, gdy zmienia się dostępność. Gdy aplikacja otrzyma intencję rozgłoszenia, powinna odrzucić wszystkie istniejące sesje (zakładając, że usługa Wi-Fi Aware została przerwana), a następnie sprawdzić aktualny stan dostępności i odpowiednio dostosować swoje działanie. Przykład:

   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ęcej informacji znajdziesz w artykule Transmisje.

Uwaga: przed sprawdzeniem dostępności odbiornika transmisji radiowej należy go zarejestrować. W przeciwnym razie może być okres, w którym aplikacja uważa, że Wi-Fi Aware jest dostępne, ale nie jest powiadamiana o zmianach w dostępności.

Uzyskiwanie sesji

Aby zacząć korzystać z Wi-Fi Aware, aplikacja musi uzyskaćWifiAwareSession, wywołującattach(). Ta metoda:

• Włącza sprzęt Wi-Fi Aware.
• Dołącza do klastra Wi-Fi Aware lub tworzy taki klaster.
• Tworzy sesję Wi-Fi Aware z unikalnym przestrzenią nazw, która działa jako kontener dla wszystkich sesji wyszukiwania utworzonych w jej ramach.

Jeśli aplikacja zostanie pomyślnie dołączona, system wykona wywołanie onAttached(). Ten wywołanie zwrotne udostępnia obiekt WifiAwareSession, którego aplikacja powinna używać do wszystkich dalszych operacji dotyczących sesji. Aplikacja może użyć sesji do publikowania usługi lub subskrybowania usługi.

Aplikacja powinna wywoływać funkcję attach() tylko raz. Jeśli Twoja aplikacja wywołuje attach()kilka razy, w przypadku każdego wywołania otrzymuje inną sesję z własną przestrzenią nazw. Może to być przydatne w skomplikowanych sytuacjach, ale na ogół należy tego unikać.

Uwaga: dopóki istnieją aktywne sesje, system utrzymuje synchronizację z klasterem Wi-Fi Aware. Takie grupowanie zużywa zasoby i energię z baterii. Aby oszczędzać zasoby, wywołaj funkcję WifiAwareSession.close(), gdy sesja nie jest już potrzebna.

Publikowanie usługi

Aby usługa była możliwa do znalezienia, wywołaj metodę publish(), która przyjmuje te parametry:

• PublishConfig określa nazwę usługi oraz inne właściwości konfiguracji, takie jak filtr dopasowania.
• DiscoverySessionCallback określa działania, które mają być wykonywane po wystąpieniu zdarzeń, np. gdy subskrybent otrzyma wiadomość.

Oto przykład:

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);

Jeśli publikacja się powiedzie, zostanie wywołana metoda wywołania zwrotnego onPublishStarted().

Po opublikowaniu, gdy urządzenia z odpowiednimi aplikacjami subskrybentów znajdą się w zakresie sieci Wi-Fi urządzenia publikującego, subskrybenci mogą odkryć usługę. Gdy subskrybent odkryje wydawcę, ten nie otrzyma powiadomienia. Jeśli jednak subskrybent wyśle wiadomość do wydawcy, ten otrzyma powiadomienie. Wtedy wywoływana jest metoda wywołania zwrotnego onMessageReceived(). Argument PeerHandle tej metody umożliwia wysłanie wiadomości do subskrybenta lub utworzenie połączenia z nim.

Aby zatrzymać publikowanie usługi, zadzwoń pod numer DiscoverySession.close(). Sesje eksploracji są powiązane z kontem nadrzędnym WifiAwareSession. Jeśli sesja nadrzędna zostanie zamknięta, powiązane z nią sesje odkrywania również zostaną zamknięte. Porzucone obiekty są zamknięte, ale system nie gwarantuje, że sesje poza zakresem są zamknięte, dlatego zalecamy wywołanie metody close().

Subskrybowanie usługi

Aby zasubskrybować usługę, wywołaj metodę subscribe(), która przyjmuje te parametry:

• SubscribeConfig określa nazwę usługi, do której chcesz się zasubskrybować, oraz inne właściwości konfiguracji, takie jak filtr dopasowania.
• DiscoverySessionCallbackokreśla działania, które mają być wykonywane po wystąpieniu zdarzeń, np. po wykryciu wydawcy.

Oto przykład:

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);

Jeśli operacja subskrypcji się powiedzie, system wywoła w aplikacji funkcję onSubscribeStarted(). Ponieważ w funkcjach wywołania możesz używać argumentu SubscribeDiscoverySession do komunikacji z wydawcą po wykryciu przez aplikację wydawcy, zaoszczędź to odwołanie. W każdej chwili możesz zaktualizować sesję subskrypcji, wywołując funkcję updateSubscribe() w sesji odkrywania.

W tym momencie Twoja subskrypcja czeka na to, aż pasujący wydawcy znajdą się w zasięgu Wi-Fi. W takim przypadku system wykonuje metodę wywołania zwrotnego onServiceDiscovered(). Argument PeerHandle z tego wywołania zwrotnego umożliwia wysłanie wiadomości lub utworzenie połączenia z tym wydawcą.

Aby zrezygnować z subskrypcji usługi, zadzwoń pod numer DiscoverySession.close(). Sesje eksploracji są powiązane z kontem nadrzędnym WifiAwareSession. Jeśli sesja nadrzędna zostanie zamknięta, powiązane z nią sesje odkrywania również zostaną zamknięte. Porzucone obiekty są zamknięte, ale system nie gwarantuje, że sesje poza zakresem są zamknięte, dlatego zalecamy wywołanie metody close().

Wyślij wiadomość

Aby wysłać wiadomość na inne urządzenie, musisz mieć:

• DiscoverySession. Ten obiekt umożliwia wywołanie funkcji sendMessage(). Aplikacja otrzymuje DiscoverySession, gdy publikuje usługę lub subskrybuje usługę.

• PeerHandle drugiego urządzenia, aby przekierować wiadomość. Aplikacja uzyskuje dostęp do danych z innego urządzenia PeerHandle w jeden z 2 sposobów:

  • Twoja aplikacja publikuje usługę i otrzymuje wiadomość od subskrybenta. Aplikacja uzyskuje dane subskrybenta PeerHandle z pomocy wywołania zwrotnego onMessageReceived().
  • Twoja aplikacja subskrybuje usługę. Gdy wykryje pasującego wydawcę, aplikacja otrzyma jego PeerHandle z powrotem wywołania funkcji onServiceDiscovered().

Aby wysłać wiadomość, zadzwoń do sendMessage(). W tym przypadku mogą wystąpić następujące wywołania zwrotne:

• Gdy wiadomość zostanie pomyślnie odebrana przez drugą stronę, system wywoła onMessageSendSucceeded() wywołanie zwrotne w aplikacji wysyłającej.
• Gdy peer otrzyma wiadomość, system wywoła funkcję onMessageReceived() callback w aplikacji odbiorcy.

Uwaga: wiadomości są zwykle używane do przesyłania lekkich danych, ponieważ mogą nie zostać dostarczone (lub mogą zostać dostarczone w nieprawidłowym porządku lub więcej niż raz) i mają ograniczoną długość do około 255 bajtów. Aby określić dokładny limit długości, zadzwoń pod numergetMaxServiceSpecificInfoLength(). Aby zapewnić szybką dwukierunkową komunikację, aplikacja powinna utworzyć połączenie.

Chociaż PeerHandle jest wymagany do komunikacji z urządzeniami peer-to-peer, nie należy polegać na nim jako stałym identyfikatorze urządzeń peer-to-peer. Identyfikatory wyższego poziomu mogą być używane przez aplikację wbudowaną w usługę wyszukiwania lub w kolejnych wiadomościach. Identyfikator możesz osadzić w usłudze wyszukiwania za pomocą metody setMatchFilter() lub setServiceSpecificInfo() PublishConfig lub SubscribeConfig. Metoda setMatchFilter() wpływa na odkrywanie, a metoda setServiceSpecificInfo() nie ma na to wpływu.

Umieszczanie identyfikatora w wiadomości oznacza modyfikację tablicy bajtów wiadomości w celu uwzględnienia identyfikatora (np. jako pierwszych kilku bajtów).

Tworzenie połączenia

Wi-Fi Aware obsługuje sieć klient-serwer między dwoma urządzeniami z tą technologią.

Aby skonfigurować połączenie klienta z serwerem:

1. Użyj wykrywania Wi-Fi Aware, aby opublikować usługę (na serwerze) i zasubskrybować usługę (na kliencie).

2. Gdy subskrybent znajdzie wydawcę, wyślij wiadomość od subskrybenta do wydawcy.

3. Uruchom ServerSocket na urządzeniu wydawcy i ustaw lub pobierz jego port:

   Kotlin

   val ss = ServerSocket(0)
   val port = ss.localPort

   Java

   ServerSocket ss = new ServerSocket(0);
   int port = ss.getLocalPort();

4. Użyj ConnectivityManager, aby poprosić wydawcę o utworzenie sieci Wi-Fi Aware, używając WifiAwareNetworkSpecifier, określając sesję odkrywania i PeerHandle subskrybenta, które zostały uzyskane z wiadomości przesłanej przez subskrybenta:

   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);

5. Gdy wydawca poprosi sieć, ta wyśle wiadomość do subskrybenta.

6. Gdy subskrybent otrzyma wiadomość od wydawcy, poproś o utworzenie sieci Wi-Fi Aware na subskrybencie, używając tej samej metody co w przypadku wydawcy. Podczas tworzenia NetworkSpecifier nie określaj portu. Odpowiednie metody wywołania są wywoływane, gdy połączenie z siecią jest dostępne, zmienione lub utracone.

7. Gdy wywołana zostanie metoda onAvailable() subskrybenta, będzie dostępny obiekt Network, za pomocą którego możesz otworzyć obiekt Socket, aby komunikować się z ServerSocket w wydawcy. Musisz jednak znać adres IPv6 i port ServerSocket. Te informacje możesz uzyskać z obiektu NetworkCapabilities, który jest przekazywany w wywołaniu zwrotnym 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);

8. Po zakończeniu konfigurowania połączenia z siecią zadzwoń na numer unregisterNetworkCallback().

   Uwaga: tworzenie żądania sieci i określanie wymaganych funkcji sieci nie jest specyficzne dla interfejsu Wi-Fi Aware API. Więcej informacji o pracy z żądaniami sieciowymi znajdziesz w artykule ConnectivityManager
   .

Rangowanie rówieśników i lokalizacja w ramach usługi rozpoznawania

Urządzenie z funkcją lokalizacji Wi-Fi RTT może bezpośrednio mierzyć odległość do urządzeń w swojej sieci i wykorzystywać te informacje do ograniczania wykrywania usług z użyciem Wi-Fi Aware.

Interfejs Wi-Fi RTT API umożliwia bezpośrednie określenie zasięgu do urządzenia Wi-Fi Aware za pomocą adresu MAC lub identyfikatora PeerHandle.

Wykrywanie Wi-Fi Aware może być ograniczone do wykrywania tylko usług w określonym geoogrodzeniu. Możesz na przykład skonfigurować geofence, który umożliwia wykrywanie urządzenia publikującego usługę "Aware_File_Share_Service_Name" w odległości nie mniejszej niż 3 metry (określanej jako 3000 mm) i nie większej niż 10 metrów (określanej jako 10 000 mm).

Aby włączyć geofence, zarówno wydawca, jak i subskrybent muszą wykonać określone czynności:

• Wydawca musi włączyć zakresowanie w opublikowanej usłudze za pomocą funkcji setRangingEnabled(true).

  Jeśli wydawca nie włączy pomiaru zasięgu, wszystkie ograniczenia geofence określone przez subskrybenta są ignorowane, a wykrywanie odbywa się w normalny sposób, z pominięciem odległości.

• Subskrybent musi określić geofence, używając kombinacji funkcji setMinDistanceMm i setMaxDistanceMm.

  W przypadku obu wartości nieokreślona odległość oznacza brak limitu. Podanie tylko maksymalnej odległości oznacza, że minimalna odległość to 0. Określenie tylko minimalnej odległości oznacza brak maksymalnej odległości.

Gdy usługa peer zostanie wykryta w geoogrodzeniu, zostanie wywołana funkcja onServiceDiscoveredWithinRange, która podaje zmierzoną odległość do peera. Następnie można wywołać bezpośredni interfejs API RTT Wi-Fi w celu pomiaru odległości w późniejszych momentach.