Skip to content

Commit

Permalink
docs(connectivity_plus): Update documentation to address API changes (#…
Browse files Browse the repository at this point in the history 
…2719)
  • Loading branch information
@vbuberen
vbuberen committed Mar 17, 2024
1 parent 5913ac7 commit 59b9b34
Show file tree
Hide file tree
Showing 3 changed files with 55 additions and 53 deletions.
10 changes: 2 additions & 8 deletions docs/connectivity_plus/overview.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,8 @@ hide_title: true

## Connectivity Plus Overview

Connectivity plus is Flutter plugin that allows your apps to get information about
the network connectivity of the device, whether it's running on cellular or WiFi,
and if it has an internet connection or not.

:::note
Connectivity plus is going to replace the [original Connectivity plugin](https://pub.dev/packages/connectivity),
if you have been using it, it's better to switch to this one.
:::
Connectivity Plus is a Flutter plugin that allows your apps to get information about
currently active network types on a device, whether it's running on cellular, WiFi or other connection types.

### Get started

Expand Down
48 changes: 26 additions & 22 deletions docs/connectivity_plus/usage.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,25 +19,29 @@ Using Connectivity API, you can find out which type of connection the device is
```dart
import 'package:connectivity_plus/connectivity_plus.dart';
final connectivityResult = await (Connectivity().checkConnectivity());
if (connectivityResult == ConnectivityResult.mobile) {
// I am connected to a mobile network.
} else if (connectivityResult == ConnectivityResult.wifi) {
// I am connected to a wifi network.
} else if (connectivityResult == ConnectivityResult.ethernet) {
// I am connected to a ethernet network.
} else if (connectivityResult == ConnectivityResult.vpn) {
// I am connected to a vpn network.
final List<ConnectivityResult> connectivityResult = await (Connectivity().checkConnectivity());
// This condition is for demo purposes only to explain every connection type.
// Use conditions which work for your requirements.
if (connectivityResult.contains(ConnectivityResult.mobile)) {
// Mobile network available.
} else if (connectivityResult.contains(ConnectivityResult.wifi)) {
// Wi-fi is available.
// Note for Android:
// When both mobile and Wi-Fi are turned on system will return Wi-Fi only as active network type
} else if (connectivityResult.contains(ConnectivityResult.ethernet)) {
// Ethernet connection available.
} else if (connectivityResult.contains(ConnectivityResult.vpn)) {
// Vpn connection active.
// Note for iOS and macOS:
// There is no separate network interface type for [vpn].
// It returns [other] on any device (also simulator)
} else if (connectivityResult == ConnectivityResult.bluetooth) {
// I am connected to a bluetooth.
} else if (connectivityResult == ConnectivityResult.other) {
// I am connected to a network which is not in the above mentioned networks.
} else if (connectivityResult == ConnectivityResult.none) {
// I am not connected to any network.
} else if (connectivityResult.contains(ConnectivityResult.bluetooth)) {
// Bluetooth connection available.
} else if (connectivityResult.contains(ConnectivityResult.other)) {
// Connected to a network which is not in the above mentioned networks.
} else if (connectivityResult.contains(ConnectivityResult.none)) {
// No available network types
}
```

Expand All @@ -58,12 +62,12 @@ user's connectivity.
#### 1. Declare a StreamSubscription

``` dart
StreamSubscription<ConnectivityResult> _connectivitySubscription;
StreamSubscription<List<ConnectivityResult>> _connectivitySubscription;
```

#### 2. Listen to the Stream

Use `onConnectivityChanged` method that has a return type `Stream<ConnectivityResult>`,
Use `onConnectivityChanged` method that returns `Stream<List<ConnectivityResult>>`,
to register a listener.

:::note
Expand All @@ -75,13 +79,13 @@ The broadcast is only useful when your application is in the **foreground**.

``` dart
// Initialize a variable with [none] status to avoid nulls at startup
ConnectivityResult _connectivityResult = ConnectivityResult.none;
List<ConnectivityResult> _connectionStatus = [ConnectivityResult.none];
@override
void initState() {
super.initState();
_connectivitySubscription =
_connectivity.onConnectivityChanged.listen(_updateConnectionStatus);
Connectivity().onConnectivityChanged.listen(_updateConnectionStatus);
}
// Make sure to cancel subscription after you are done
Expand All @@ -95,9 +99,9 @@ dispose() {
The listener will update the connectivity status.

``` dart
Future<void> _updateConnectionStatus(ConnectivityResult result) async {
Future<void> _updateConnectionStatus(List<ConnectivityResult> result) async {
setState((){
_connectivityResult = result;
_connectionStatus = result;
});
}
```
Expand Down
50 changes: 27 additions & 23 deletions packages/connectivity_plus/connectivity_plus/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,7 @@
<center><a href="https://flutter.dev/docs/development/packages-and-plugins/favorites" target="_blank" rel="noreferrer noopener"><img src="../../../website/static/img/flutter-favorite-badge.png" width="100" alt="build"></a></center>
</p>

This plugin allows Flutter apps to discover network connectivity and configure
themselves accordingly. It can distinguish between cellular vs WiFi connection.
This plugin allows Flutter apps to discover network connectivity types that can be used.

> **Note**
>
Expand All @@ -25,38 +24,43 @@ themselves accordingly. It can distinguish between cellular vs WiFi connection.

## Usage

Sample usage to check current status:
Sample usage to check currently available connection types:

```dart
import 'package:connectivity_plus/connectivity_plus.dart';
final connectivityResult = await (Connectivity().checkConnectivity());
if (connectivityResult == ConnectivityResult.mobile) {
// I am connected to a mobile network.
} else if (connectivityResult == ConnectivityResult.wifi) {
// I am connected to a wifi network.
} else if (connectivityResult == ConnectivityResult.ethernet) {
// I am connected to a ethernet network.
} else if (connectivityResult == ConnectivityResult.vpn) {
// I am connected to a vpn network.
final List<ConnectivityResult> connectivityResult = await (Connectivity().checkConnectivity());
// This condition is for demo purposes only to explain every connection type.
// Use conditions which work for your requirements.
if (connectivityResult.contains(ConnectivityResult.mobile)) {
// Mobile network available.
} else if (connectivityResult.contains(ConnectivityResult.wifi)) {
// Wi-fi is available.
// Note for Android:
// When both mobile and Wi-Fi are turned on system will return Wi-Fi only as active network type
} else if (connectivityResult.contains(ConnectivityResult.ethernet)) {
// Ethernet connection available.
} else if (connectivityResult.contains(ConnectivityResult.vpn)) {
// Vpn connection active.
// Note for iOS and macOS:
// There is no separate network interface type for [vpn].
// It returns [other] on any device (also simulator)
} else if (connectivityResult == ConnectivityResult.bluetooth) {
// I am connected to a bluetooth.
} else if (connectivityResult == ConnectivityResult.other) {
// I am connected to a network which is not in the above mentioned networks.
} else if (connectivityResult == ConnectivityResult.none) {
// I am not connected to any network.
} else if (connectivityResult.contains(ConnectivityResult.bluetooth)) {
// Bluetooth connection available.
} else if (connectivityResult.contains(ConnectivityResult.other)) {
// Connected to a network which is not in the above mentioned networks.
} else if (connectivityResult.contains(ConnectivityResult.none)) {
// No available network types
}
```

> **Note**
>
> You should not be using the current network status for deciding whether you can reliably make a network connection. Always guard your app code against timeouts and errors that might come from the network layer.
You can also listen for network state changes by subscribing to the stream
exposed by connectivity plugin:
You can also listen for active connectivity types changes by subscribing to the stream
exposed by the plugin:

```dart
import 'package:connectivity_plus/connectivity_plus.dart';
Expand All @@ -65,8 +69,8 @@ import 'package:connectivity_plus/connectivity_plus.dart';
initState() {
super.initState();
subscription = Connectivity().onConnectivityChanged.listen((ConnectivityResult result) {
// Got a new connectivity status!
StreamSubscription<List<ConnectivityResult>> subscription = Connectivity().onConnectivityChanged.listen((List<ConnectivityResult> result) {
// Received changes in available connectivity types!
});
}
Expand All @@ -80,7 +84,7 @@ dispose() {

> **Note**
>
> Connectivity changes are no longer communicated to Android apps in the background starting with Android O (8.0). _You should always check for connectivity status when your app is resumed._ The broadcast is only useful when your application is in the foreground.
> Connectivity changes are no longer communicated to Android apps in the background starting with Android O (8.0). You should always check for connectivity status when your app is resumed._ The broadcast is only useful when your application is in the foreground.
## Limitations on the web platform

Expand Down

0 comments on commit 59b9b34

Please sign in to comment.