網(wǎng)絡(luò)連接管理

說明：
開發(fā)前請熟悉鴻蒙開發(fā)指導(dǎo)文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]
本模塊首批接口從API version 8開始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨標(biāo)記接口的起始版本。

導(dǎo)入模塊

import connection from '@ohos.net.connection'

connection.getDefaultNet

getDefaultNet(callback: AsyncCallback): void

獲取默認(rèn)激活的數(shù)據(jù)網(wǎng)絡(luò)，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet(function (error, netHandle) {
    console.log(JSON.stringify(error))
    console.log(JSON.stringify(netHandle))
})

connection.getDefaultNet

getDefaultNet(): Promise

獲取默認(rèn)激活的數(shù)據(jù)網(wǎng)絡(luò)，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    console.log(JSON.stringify(netHandle))
})

connection.hasDefaultNet

hasDefaultNet(callback: AsyncCallback): void

檢查默認(rèn)數(shù)據(jù)網(wǎng)絡(luò)是否被激活，使用callback方式作為異步方法。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.hasDefaultNet(function (error, has) {
    console.log(JSON.stringify(error))
    console.log(has)
})

connection.hasDefaultNet

hasDefaultNet(): Promise

檢查默認(rèn)數(shù)據(jù)網(wǎng)絡(luò)是否被激活，使用Promise方式作為異步方法。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

返回值：

示例：

connection.hasDefaultNet().then(function (has) {
    console.log(has)
})

connection.getAllNets

getAllNets(callback: AsyncCallback>): void

獲取全部激活的數(shù)據(jù)網(wǎng)絡(luò)列表，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getAllNets(function (error, nets) {
    console.log(JSON.stringify(error))
    console.log(JSON.stringify(nets))
});

connection.getAllNets

getAllNets(): Promise>

獲取全部激活的數(shù)據(jù)網(wǎng)絡(luò)列表，使用promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

返回值：

示例：

connection.getAllNets().then(function (nets) {
    console.log(JSON.stringify(nets))
});

connection.getConnectionProperties

getConnectionProperties(netHandle: NetHandle, callback: AsyncCallback): void

獲取netHandle對應(yīng)的網(wǎng)絡(luò)的連接信息，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.getConnectionProperties(netHandle, function (error, info) {
        console.log(JSON.stringify(error))
        console.log(JSON.stringify(info))
    })
})

connection.getConnectionProperties

getConnectionProperties(netHandle: NetHandle): Promise

獲取netHandle對應(yīng)的網(wǎng)絡(luò)的連接信息，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.getConnectionProperties(netHandle).then(function (info) {
        console.log(JSON.stringify(info))
    })
})

connection.getNetCapabilities

getNetCapabilities(netHandle: NetHandle, callback: AsyncCallback): void

獲取netHandle對應(yīng)的網(wǎng)絡(luò)的能力信息，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.getNetCapabilities(netHandle, function (error, info) {
        console.log(JSON.stringify(error))
        console.log(JSON.stringify(info))
    })
})

connection.getNetCapabilities

getNetCapabilities(netHandle: NetHandle): Promise

獲取netHandle對應(yīng)的網(wǎng)絡(luò)的能力信息，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.getNetCapabilities(netHandle).then(function (info) {
        console.log(JSON.stringify(info))
    })
})

connection.reportNetConnected

reportNetConnected(netHandle: NetHandle, callback: AsyncCallback): void

報告網(wǎng)絡(luò)狀態(tài)已連接，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.reportNetConnected(netHandle, function (error) {
        console.log(JSON.stringify(error))
    });
});

connection.reportNetConnected

reportNetConnected(netHandle: NetHandle): Promise

報告網(wǎng)絡(luò)狀態(tài)已連接，使用promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.reportNetConnected(netHandle).then(function () {
        console.log(`report success`)
    });
});

connection.reportNetDisconnected

reportNetDisconnected(netHandle: NetHandle, callback: AsyncCallback): void

報告網(wǎng)絡(luò)狀態(tài)已斷開，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.reportNetDisconnected(netHandle, function (error) {
        console.log(JSON.stringify(error))
    });
});

connection.reportNetDisconnected

reportNetDisconnected(netHandle: NetHandle): Promise

報告網(wǎng)絡(luò)狀態(tài)已斷開，使用promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO 和 ohos.permission.INTERNET

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    connection.reportNetDisconnected(netHandle).then(function () {
        console.log(`report success`)
    });
});

connection.getAddressesByName

getAddressesByName(host: string, callback: AsyncCallback>): void

使用默認(rèn)網(wǎng)絡(luò)解析主機名以獲取所有IP地址，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

let host = "xxxx";
connection.getAddressesByName(host, function (error, addresses) {
    console.log(JSON.stringify(error))
    console.log(JSON.stringify(addresses))
})

connection.getAddressesByName

getAddressesByName(host: string): Promise>

使用默認(rèn)網(wǎng)絡(luò)解析主機名以獲取所有IP地址，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

let host = "xxxx";
connection.getAddressesByName(host).then(function (addresses) {
    console.log(JSON.stringify(addresses))
})

connection.createNetConnection

createNetConnection(netSpecifier?: NetSpecifier, timeout?: number): NetConnection

獲取一個netSpecifier指定的網(wǎng)絡(luò)的句柄。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

// 關(guān)注默認(rèn)網(wǎng)絡(luò)
let netConnection = connection.createNetConnection()

// 關(guān)注蜂窩網(wǎng)絡(luò)
let netConnectionCellular = connection.createNetConnection({
    netCapabilities: {
        bearerTypes: [NetBearType.BEARER_CELLULAR]
    }
})

NetConnection

網(wǎng)絡(luò)連接的句柄。

on('netAvailable')

on(type: 'netAvailable', callback: Callback): void

訂閱網(wǎng)絡(luò)可用事件。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.on('netAvailable', function (data) {
    console.log(JSON.stringify(data))
})

on('netCapabilitiesChange')

on(type: 'netCapabilitiesChange', callback: Callback<{ netHandle: NetHandle, netCap: NetCapabilities }>): void

訂閱網(wǎng)絡(luò)能力變化事件。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.on('netCapabilitiesChange', function (data) {
    console.log(JSON.stringify(data))
})

on('netConnectionPropertiesChange')

on(type: 'netConnectionPropertiesChange', callback: Callback<{ netHandle: NetHandle, connectionProperties: ConnectionProperties }>): void

訂閱網(wǎng)絡(luò)連接信息變化事件。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.on('netConnectionPropertiesChange', function (data) {
    console.log(JSON.stringify(data))
})

on('netBlockStatusChange')

on(type: 'netBlockStatusChange', callback: Callback<{ netHandle: NetHandle, blocked: boolean }>): void

訂閱網(wǎng)絡(luò)阻塞狀態(tài)事件，使用callback方式作為異步方法。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.on('netBlockStatusChange', function (data) {
    console.log(JSON.stringify(data))
})

on('netLost')

on(type: 'netLost', callback: Callback): void

訂閱網(wǎng)絡(luò)丟失事件。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

let netConnection1 = connection.createNetConnection()
netConnection1.on('netLost', function (data) {
    console.log(JSON.stringify(data))
})

on('netUnavailable')

on(type: 'netUnavailable', callback: Callback): void

訂閱網(wǎng)絡(luò)不可用事件。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.on('netUnavailable', function (data) {
    console.log(JSON.stringify(data))
})

register

register(callback: AsyncCallback): void

訂閱指定網(wǎng)絡(luò)狀態(tài)變化的通知。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.register(function (error) {
    console.log(JSON.stringify(error))
})

unregister

unregister(callback: AsyncCallback): void

取消訂閱默認(rèn)網(wǎng)絡(luò)狀態(tài)變化的通知。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

netConnection.unregister(function (error) {
    console.log(JSON.stringify(error))
})

NetHandle

數(shù)據(jù)網(wǎng)絡(luò)的句柄。

在調(diào)用NetHandle的方法之前，需要先獲取NetHandle對象。

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

屬性

getAddressesByName

getAddressesByName(host: string, callback: AsyncCallback>): void

使用對應(yīng)網(wǎng)絡(luò)解析主機名以獲取所有IP地址，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    let host = "xxxx";
    netHandle.getAddressesByName(host, function (error, addresses) {
        console.log(JSON.stringify(error))
        console.log(JSON.stringify(addresses))
    })
})

getAddressesByName

getAddressesByName(host: string): Promise>

使用對應(yīng)網(wǎng)絡(luò)解析主機名以獲取所有IP地址，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    let host = "xxxx";
    netHandle.getAddressesByName(host).then(function (addresses) {
        console.log(JSON.stringify(addresses))
    })
})

getAddressByName

getAddressByName(host: string, callback: AsyncCallback): void

使用對應(yīng)網(wǎng)絡(luò)解析主機名以獲取第一個IP地址，使用callback方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

示例：

connection.getDefaultNet().then(function (netHandle) {
    let host = "xxxx";
    netHandle.getAddressByName(host, function (error, address) {
        console.log(JSON.stringify(error))
        console.log(JSON.stringify(address))
    })
})

getAddressByName

getAddressByName(host: string): Promise

使用對應(yīng)網(wǎng)絡(luò)解析主機名以獲取第一個IP地址，使用Promise方式作為異步方法。

需要權(quán)限 ：ohos.permission.GET_NETWORK_INFO

系統(tǒng)能力 ：SystemCapability.Communication.NetManager.Core

參數(shù)：

返回值：

示例：

connection.getDefaultNet().then(function (netHandle) {
    let host = "xxxx";
    netHandle.getAddressByName(host).then(function (address) {
        console.log(JSON.stringify(address))
    })
})

NetSpecifier

提供承載數(shù)據(jù)網(wǎng)絡(luò)能力的實例。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

NetCapabilities

網(wǎng)絡(luò)的能力集。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

NetCap

網(wǎng)絡(luò)具體能力。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

NetBearType

網(wǎng)絡(luò)類型。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

ConnectionProperties

網(wǎng)絡(luò)連接信息。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

LinkAddress

網(wǎng)絡(luò)鏈路信息。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

RouteInfo

網(wǎng)絡(luò)路由信息。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

NetAddress

網(wǎng)絡(luò)地址。

系統(tǒng)能力 ：以下各項對應(yīng)的系統(tǒng)能力均為SystemCapability.Communication.NetManager.Core。

審核編輯 黃宇