1# Network Sharing (For System Applications Only)
2
3## Introduction
4
5The Network Sharing module allows you to share your device's Internet connection with other connected devices by means of Wi-Fi hotspot, Bluetooth, and USB sharing. It also allows you to query the network sharing state and shared mobile data volume.
6
7> **NOTE**
8> To maximize the application running efficiency, most API calls are called asynchronously in callback or promise mode. The following code examples use the promise mode. For details about the APIs, see [API Reference](../reference/apis-network-kit/js-apis-net-sharing-sys.md).
9
10## Basic Concepts
11
12- Wi-Fi sharing: Shares the network through a Wi-Fi hotspot.
13- Bluetooth sharing: Shares the network through Bluetooth.
14- USB tethering: Shares the network using a USB flash drive.
15
16## **Constraints**
17
18- Programming language: JS
19- The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
20
21## When to Use
22
23Typical network sharing scenarios are as follows:
24
25- Enabling Network Sharing
26- Disabling network sharing
27- Obtaining the data traffic of the shared network
28
29The following describes the development procedure specific to each application scenario.
30
31## Available APIs
32
33For the complete list of APIs and example code, see [Network Sharing](../reference/apis-network-kit/js-apis-net-sharing-sys.md).
34
35| API                                                                  | Description                                                                                                   |
36| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
37| isSharingSupported(callback: AsyncCallback\<boolean>): void;    | Checks whether the system supports network sharing. This API uses an asynchronous callback to return the result.                                                      |
38| isSharing(callback: AsyncCallback\<boolean>): void;             | Checks whether network sharing is active. This API uses an asynchronous callback to return the result.                                                                  |
39| startSharing(type: SharingIfaceType, callback: AsyncCallback\<void>): void;  | Starts network sharing. This API uses an asynchronous callback to return the result.               |
40| stopSharing(type: SharingIfaceType, callback: AsyncCallback\<void>): void;  | Stops network sharing. This API uses an asynchronous callback to return the result.            |
41| getStatsRxBytes(callback: AsyncCallback\<number>): void;         | Obtains the received data traffic during network sharing, in KB. This API uses an asynchronous callback to return the result.                                                       |
42| getStatsTxBytes(callback: AsyncCallback\<number>): void;         | Obtains the sent data traffic during network sharing, in KB. This API uses an asynchronous callback to return the result.                                                       |
43| getStatsTotalBytes(callback: AsyncCallback\<number>): void;      | Obtains the total data traffic during network sharing, in KB. This API uses an asynchronous callback to return the result.                                                       |
44| getSharingIfaces(state: SharingIfaceState, callback: AsyncCallback\<Array\<string>>): void;  | Obtains the names of network interface cards (NICs) in the specified network sharing state.. This API uses an asynchronous callback to return the result.|
45| getSharingState(type: SharingIfaceType, callback: AsyncCallback\<SharingIfaceState>): void;  | Obtains the network sharing state of the specified type. This API uses an asynchronous callback to return the result. |
46| getSharableRegexes(type: SharingIfaceType, callback: AsyncCallback\<Array\<string>>): void;  | Obtains regular expressions of NICs of a specified type. This API uses an asynchronous callback to return the result.|
47| on(type: 'sharingStateChange', callback: Callback\<boolean>): void;        | Subscribes to network sharing state changes.                                                               |
48| off(type: 'sharingStateChange', callback?: Callback\<boolean>): void;      | Unsubscribes from network sharing state changes.                                                               |
49| unction on(type: 'interfaceSharingStateChange', callback: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void;    | Subscribes to network sharing state changes of the specified NIC.   |
50| off(type: 'interfaceSharingStateChange', callback?: Callback\<{ type: SharingIfaceType, iface: string, state: SharingIfaceState }>): void; | Unsubscribes from network sharing state changes of the specified NIC.            |
51| on(type: 'sharingUpstreamChange', callback: Callback\<NetHandle>): void;               | Subscribes to upstream NIC changes.                                                                        |
52| off(type: 'sharingUpstreamChange', callback?: Callback\<NetHandle>): void;             | Unsubscribes from upstream NIC changes.                                                                        |
53
54## Enabling Network Sharing
55
561. Import the **sharing** namespace from **@kit.NetworkKit**.
572. Subscribe to network sharing state changes.
583. Call **startSharing** to start network sharing of the specified type.
594. Return the callback for successfully starting network sharing.
60
61```ts
62// Import the sharing namespace from @kit.NetworkKit.
63import { sharing } from '@kit.NetworkKit';
64import { BusinessError } from '@kit.BasicServicesKit';
65
66// Subscribe to network sharing state changes.
67sharing.on('sharingStateChange', (data: boolean) => {
68  console.log(JSON.stringify(data));
69});
70
71// Call startSharing to start network sharing of the specified type.
72sharing.startSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
73  console.log('start wifi sharing successful');
74}).catch((error: BusinessError) => {
75  console.log('start wifi sharing failed');
76});
77```
78
79## Disabling network sharing
80
81### How to Develop
82
831. Import the **sharing** namespace from **@kit.NetworkKit**.
842. Subscribe to network sharing state changes.
853. Call **stopSharing** to stop network sharing of the specified type.
864. Return the callback for successfully stopping network sharing.
87
88```ts
89// Import the sharing namespace from @kit.NetworkKit.
90import { sharing } from '@kit.NetworkKit';
91import { BusinessError } from '@kit.BasicServicesKit';
92
93// Subscribe to network sharing state changes.
94sharing.on('sharingStateChange', (data: boolean) => {
95  console.log(JSON.stringify(data));
96});
97
98// Call stopSharing to stop network sharing of the specified type.
99sharing.stopSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
100  console.log('start wifi sharing successful');
101}).catch((error: BusinessError) => {
102  console.log('start wifi sharing failed');
103});
104```
105
106## Obtaining the data traffic of the shared network
107
108### How to Develop
109
1101. Import the **sharing** namespace from **@kit.NetworkKit**.
1112. Call **startSharing** to start network sharing of the specified type.
1123. Call **getStatsTotalBytes** to obtain the data traffic generated during data sharing.
1134. Call **stopSharing** to stop network sharing of the specified type and clear the data volume of network sharing.
114
115```ts
116// Import the sharing namespace from @kit.NetworkKit.
117import { sharing } from '@kit.NetworkKit';
118import { BusinessError } from '@kit.BasicServicesKit';
119
120// Call startSharing to start network sharing of the specified type.
121sharing.startSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
122  console.log('start wifi sharing successful');
123}).catch((error: BusinessError) => {
124  console.log('start wifi sharing failed');
125});
126
127// Call getStatsTotalBytes to obtain the data traffic generated during data sharing.
128sharing.getStatsTotalBytes().then((data: number) => {
129  console.log(JSON.stringify(data));
130}).catch((error: BusinessError) => {
131  console.log(JSON.stringify(error));
132});
133
134// Call stopSharing to stop network sharing of the specified type and clear the data volume of network sharing.
135sharing.stopSharing(sharing.SharingIfaceType.SHARING_WIFI).then(() => {
136  console.log('start wifi sharing successful');
137}).catch((error: BusinessError) => {
138  console.log('start wifi sharing failed');
139});
140
141// Call getStatsTotalBytes again. The data volume of network sharing has been cleared.
142sharing.getStatsTotalBytes().then((data: number) => {
143  console.log(JSON.stringify(data));
144}).catch((error: BusinessError) => {
145  console.log(JSON.stringify(error));
146});
147```
148