HarmonyOS Developer 开发指导
网络管理开发概述
网络管理模块主要提供以下功能:
- HTTP数据请求:通过HTTP发起一个数据请求。
- WebSocket连接:使用WebSocket建立服务器与客户端的双向连接。
- Socket连接:通过Socket进行数据传输。
约束与限制
使用网络管理模块的相关功能时,需要请求相应的权限。
权限名 | 说明 |
ohos.permission.GET_NETWORK_INFO | 获取网络连接信息。 |
ohos.permission.SET_NETWORK_INFO | 修改网络连接状态。 |
ohos.permission.INTERNET | 允许程序打开网络套接字,进行网络连接。 |
HTTP数据请求
场景介绍
应用通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。
接口说明
HTTP数据请求功能主要由http模块提供。
使用该功能需要申请ohos.permission.INTERNET权限。
权限申请请参考访问控制(权限)开发指导。
涉及的接口如下表,具体的接口说明请参考API文档。
接口名 | 功能描述 |
createHttp() | 创建一个http请求。 |
request() | 根据URL地址,发起HTTP网络请求。 |
destroy() | 中断请求任务。 |
on(type: 'headersReceive') | 订阅HTTP Response Header 事件。 |
off(type: 'headersReceive') | 取消订阅HTTP Response Header 事件。 |
开发步骤
- import需要的http模块。
- 创建一个HTTP请求,返回一个HttpRequest对象。
- (可选)订阅HTTP响应头。
- 根据URL地址,发起HTTP网络请求。
- (可选)处理HTTP响应头和HTTP网络请求的返回结果。
import http from '@ohos.net.http';
// 每一个httpRequest对应一个http请求任务,不可复用
let httpRequest = http.createHttp();
// 用于订阅http响应头,此接口会比request请求先返回。可以根据业务需要订阅此消息
// 从API 8开始,使用on('headersReceive', Callback)替代on('headerReceive', AsyncCallback)。 8+
httpRequest.on('headersReceive', (header) => {
console.info('header: ' + JSON.stringify(header));
});
httpRequest.request(
// 填写http请求的url地址,可以带参数也可以不带参数。URL地址需要开发者自定义。请求的参数可以在extraData中指定
"EXAMPLE_URL",
{
method: http.RequestMethod.POST, // 可选,默认为http.RequestMethod.GET
// 开发者根据自身业务需要添加header字段
header: {
'Content-Type': 'application/json'
},
// 当使用POST请求时此字段用于传递内容
extraData: {
"data": "data to send",
},
connectTimeout: 60000, // 可选,默认为60s
readTimeout: 60000, // 可选,默认为60s
}, (err, data) => {
if (!err) {
// data.result为http响应内容,可根据业务需要进行解析
console.info('Result:' + data.result);
console.info('code:' + data.responseCode);
// data.header为http响应头,可根据业务需要进行解析
console.info('header:' + JSON.stringify(data.header));
console.info('cookies:' + data.cookies); // 8+
} else {
console.info('error:' + JSON.stringify(err));
// 该请求不再使用,调用destroy方法主动销毁。
httpRequest.destroy();
}
}
);
WebSocket连接
场景介绍
使用WebSocket建立服务器与客户端的双向连接,需要先通过createWebSocket()方法创建WebSocket对象,然后通过connect()方法连接到服务器。当连接成功后,客户端会收到open事件的回调,之后客户端就可以通过send()方法与服务器进行通信。当服务器发信息给客户端时,客户端会收到message事件的回调。当客户端不要此连接时,可以通过调用close()方法主动断开连接,之后客户端会收到close事件的回调。
若在上述任一过程中发生错误,客户端会收到error事件的回调。
接口说明
WebSocket连接功能主要由webSocket模块提供。使用该功能需要申请ohos.permission.INTERNET权限。具体接口说明如下表。
接口名 | 功能描述 |
createWebSocket() | 创建一个WebSocket连接。 |
connect() | 根据URL地址,建立一个WebSocket连接。 |
send() | 通过WebSocket连接发送数据。 |
close() | 关闭WebSocket连接。 |
on(type: 'open') | 订阅WebSocket的打开事件。 |
off(type: 'open') | 取消订阅WebSocket的打开事件。 |
on(type: 'message') | 订阅WebSocket的接收到服务器消息事件。 |
off(type: 'message') | 取消订阅WebSocket的接收到服务器消息事件。 |
on(type: 'close') | 订阅WebSocket的关闭事件。 |
off(type: 'close') | 取消订阅WebSocket的关闭事件 |
on(type: 'error') | 订阅WebSocket的Error事件。 |
off(type: 'error') | 取消订阅WebSocket的Error事件。 |
开发步骤
- 导入需要的webSocket模块。
- 创建一个WebSocket连接,返回一个WebSocket对象。
- (可选)订阅WebSocket的打开、消息接收、关闭、Error事件。
- 根据URL地址,发起WebSocket连接。
- 使用完WebSocket连接之后,主动断开连接。
import webSocket from '@ohos.net.webSocket';
var defaultIpAddress = "ws://";
let ws = webSocket.createWebSocket();
ws.on('open', (err, value) => {
console.log("on open, status:" + JSON.stringify(value));
// 当收到on('open')事件时,可以通过send()方法与服务器进行通信
ws.send("Hello, server!", (err, value) => {
if (!err) {
console.log("Message sent successfully");
} else {
console.log("Failed to send the message. Err:" + JSON.stringify(err));
}
});
});
ws.on('message', (err, value) => {
console.log("on message, message:" + value);
// 当收到服务器的`bye`消息时(此消息字段仅为示意,具体字段需要与服务器协商),主动断开连接
if (value === 'bye') {
ws.close((err, value) => {
if (!err) {
console.log("Connection closed successfully");
} else {
console.log("Failed to close the connection. Err: " + JSON.stringify(err));
}
});
}
});
ws.on('close', (err, value) => {
console.log("on close, code is " + value.code + ", reason is " + value.reason);
});
ws.on('error', (err) => {
console.log("on error, error:" + JSON.stringify(err));
});
ws.connect(defaultIpAddress, (err, value) => {
if (!err) {
console.log("Connected successfully");
} else {
console.log("Connection failed. Err:" + JSON.stringify(err));
}
});
Socket连接
场景介绍
应用通过Socket进行数据传输,支持TCP和UDP两种协议。
接口说明
Socket连接主要由socket模块提供。具体接口说明如下表。
接口名 | 功能描述 |
constructUDPSocketInstance() | 创建一个UDPSocket对象。 |
constructTCPSocketInstance() | 创建一个TCPSocket对象。 |
bind() | 绑定IP地址和端口。 |
send() | 发送数据。 |
close() | 关闭连接。 |
getState() | 获取Socket状态。 |
connect() | 连接到指定的IP地址和端口(仅TCP支持) |
getRemoteAddress() | 获取对端Socket地址(仅TCP支持,需要先调用connect方法) |
on(type: 'message') | 订阅Socket连接的接收消息事件。 |
off(type: 'message') | 取消订阅Socket连接的接收消息事件。 |
on(type: 'close') | 订阅Socket连接的关闭事件。 |
off(type: 'close') | 取消订阅Socket连接的关闭事件。 |
on(type: 'error') | 订阅Socket连接的Error事件。 |
off(type: 'error') | 取消订阅Socket连接的Error事件。 |
on(type: 'listening') | 订阅UDPSocket连接的数据包消息事件(仅UDP支持)。 |
off(type: 'listening') | 取消订阅UDPSocket连接的数据包消息事件(仅UDP支持)。 |
on(type: 'connect') | 订阅TCPSocket的连接事件(仅TCP支持)。 |
off(type: 'connect') | 取消订阅TCPSocket的连接事件(仅TCP支持)。 |
开发步骤
UDP与TCP流程大体类似,下面以TCP为例:
- import需要的socket模块。
- 创建一个TCPSocket连接,返回一个TCPSocket对象。
- (可选)订阅TCPSocket相关的订阅事件。
- 绑定IP地址和端口,端口可以指定或由系统随机分配。
- 连接到指定的IP地址和端口。
- 发送数据。
- Socket连接使用完毕后,主动关闭。
import socket from '@ohos.net.socket'
// 创建一个TCPSocket连接,返回一个TCPSocket对象。
let tcp = socket.constructTCPSocketInstance();
// 订阅TCPSocket相关的订阅事件
tcp.on('message', value => {
console.log("on message")
let buffer = value.message
let dataView = new DataView(buffer)
let str = ""
for (let i = 0;i < dataView.byteLength; ++i) {
str += String.fromCharCode(dataView.getUint8(i))
}
console.log("on connect received:" + str)
});
tcp.on('connect', () => {
console.log("on connect")
});
tcp.on('close', () => {
console.log("on close")
});
// 绑定本地IP地址和端口。
let bindAddress = {
address: '192.168.xx.xx',
port: 1234, // 绑定端口,如1234
family: 1
};
tcp.bind(bindAddress, err => {
if (err) {
console.log('bind fail');
return;
}
console.log('bind success');
// 连接到指定的IP地址和端口。
let connectAddress = {
address: '192.168.xx.xx',
port: 5678, // 连接端口,如5678
family: 1
};
tcp.connect({
address: connectAddress, timeout: 6000
}, err => {
if (err) {
console.log('connect fail');
return;
}
console.log('connect success');
// 发送数据
tcp.send({
data: 'Hello, server!'
}, err => {
if (err) {
console.log('send fail');
return;
}
console.log('send success');
})
});
});
// 连接使用完毕后,主动关闭。取消相关事件的订阅。
setTimeout(() => {
tcp.close((err) => {
console.log('close socket.')
});
tcp.off('message');
tcp.off('connect');
tcp.off('close');
}, 30 * 1000);
IPC与RPC通信概述
基本概念
IPC(Inter-Process Communication)与RPC(Remote Procedure Call)机制用于实现跨进程通信,不同的是前者使用Binder驱动,用于设备内的跨进程通信,而后者使用软总线驱动,用于跨设备跨进程通信。IPC和RPC通常采用客户端-服务器(Client-Server)模型,服务请求方(Client)可获取提供服务提供方(Server)的代理 (Proxy),并通过此代理读写数据来实现进程间的数据通信。通常,Server会先注册系统能力(System Ability)到系统能力管理者(System Ability Manager,缩写SAMgr)中,SAMgr负责管理这些SA并向Client提供相关的接口。Client要和某个具体的SA通信,必须先从SAMgr中获取该SA的代理,然后使用代理和SA通信。下文使用Proxy表示服务请求方,Stub表示服务提供方。
约束与限制
单个设备上跨进程通信时,传输的数据量最大约为1MB,过大的数据量请使用匿名共享内存。
不支持把跨设备的Proxy对象传递回该Proxy对象所指向的Stub对象所在的设备。
IPC与RPC通信开发指导
场景介绍
IPC/RPC的主要工作是让运行在不同进程的Proxy和Stub互相通信,包括Proxy和Stub运行在不同设备的情况。
接口说明
表1 Native侧IPC接口
类/接口 | 方法 | 功能说明 |
sptr<IRemoteObject> AsObject() | 返回通信对象。派生类需要实现,Stub端返回RemoteObject对象本身,Proxy端返回代理对象。 | |
IRemoteStub | virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option) | 请求处理方法,派生类需要重写该方法用来处理Proxy的请求并返回结果。 |
IRemoteProxy | 业务Proxy类,派生自IRemoteProxy类。 |
开发步骤
Native侧开发步骤
- 定义IPC接口ITestAbility
SA接口继承IPC基类接口IRemoteBroker,接口里定义描述符、业务函数和消息码,其中业务函数在Proxy端和Stub端都需要实现。
class ITestAbility : public IRemoteBroker {
public:
// DECLARE_INTERFACE_DESCRIPTOR是必需的,入参需使用std::u16string;
DECLARE_INTERFACE_DESCRIPTOR("test.ITestAbility");
int TRANS_ID_PING_ABILITY = 1; // 定义消息码
virtual int TestPingAbility(const std::u16string &dummy) = 0; // 定义业务函数
};
- 定义和实现服务端TestAbilityStub
该类是和IPC框架相关的实现,需要继承 IRemoteStub<ITestAbility>。Stub端作为接收请求的一端,需重写OnRemoteRequest方法用于接收客户端调用。
class TestAbilityStub : public IRemoteStub<ITestAbility> {
public:
virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option) override;
int TestPingAbility(const std::u16string &dummy) override;
};
int TestServiceStub::OnRemoteRequest(uint32_t code,
MessageParcel &data, MessageParcel &reply, MessageOption &option)
{
switch (code) {
case TRANS_ID_PING_ABILITY: {
std::u16string dummy = data.ReadString16();
int result = TestPingAbility(dummy);
reply.WriteInt32(result);
return 0;
}
default:
return IPCObjectStub::OnRemoteRequest(code, data, reply, option);
}
}
- 定义服务端业务函数具体实现类TestAbility
class TestAbility : public TestAbilityStub {
public:
int TestPingAbility(const std::u16string &dummy);
}
int TestAbility::TestPingAbility(const std::u16string &dummy) {
return 0;
}
- 定义和实现客户端 TestAbilityProxy
该类是Proxy端实现,继承IRemoteProxy<ITestAbility>,调用SendRequest接口向Stub端发送请求,对外暴露服务端提供的能力。
class TestAbilityProxy : public IRemoteProxy<ITestAbility> {
public:
explicit TestAbilityProxy(const sptr<IRemoteObject> &impl);
int TestPingService(const std::u16string &dummy) override;
private:
static inline BrokerDelegator<TestAbilityProxy> delegator_; // 方便后续使用iface_cast宏
}
TestAbilityProxy::TestAbilityProxy(const sptr<IRemoteObject> &impl)
: IRemoteProxy<ITestAbility>(impl)
{
}
int TestAbilityProxy::TestPingService(const std::u16string &dummy){
MessageOption option;
MessageParcel dataParcel, replyParcel;
dataParcel.WriteString16(dummy);
int error = Remote()->SendRequest(TRANS_ID_PING_ABILITY, dataParcel, replyParcel, option);
int result = (error == ERR_NONE) ? replyParcel.ReadInt32() : -1;
return result;
}
- SA注册与启动
SA需要将自己的TestAbilityStub实例通过AddSystemAbility接口注册到SystemAbilityManager,设备内与分布式的注册参数不同。
// 注册到本设备内
auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
samgr->AddSystemAbility(saId, new TestAbility());
// 在组网场景下,会被同步到其他设备上
auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
ISystemAbilityManager::SAExtraProp saExtra;
saExtra.isDistributed = true; // 设置为分布式SA
int result = samgr->AddSystemAbility(saId, new TestAbility(), saExtra);
- SA获取与调用
通过SystemAbilityManager的GetSystemAbility方法可获取到对应SA的代理IRemoteObject,然后构造TestAbilityProxy即可。
// 获取本设备内注册的SA的proxy
sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(saId);
sptr<ITestAbility> testAbility = iface_cast<ITestAbility>(remoteObject); // 使用iface_cast宏转换成具体类型
// 获取其他设备注册的SA的proxy
sptr<ISystemAbilityManager> samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();
sptr<IRemoteObject> remoteObject = samgr->GetSystemAbility(saId, deviceId); // deviceId是指定设备的标识符
sptr<TestAbilityProxy> proxy(new TestAbilityProxy(remoteObject)); // 直接构造具体Proxy
远端状态订阅开发实例
IPC/RPC提供对远端Stub对象状态的订阅机制, 在远端Stub对象死亡时,可触发死亡通知告诉本地Proxy对象。这种状态通知订阅需要调用特定接口完成,当不再需要订阅时也需要调用特定接口取消。使用这种订阅机制的用户,需要实现死亡通知接口DeathRecipient并实现onRemoteDied方法清理资源。该方法会在远端Stub对象所在进程死亡或所在设备离开组网时被回调。值得注意的是,调用这些接口有一定的顺序。首先,需要Proxy订阅Stub死亡通知,若在订阅期间Stub状态正常,则在不再需要时取消订阅;若在订阅期间Stub所在进程退出或者所在设备退出组网,则会自动触发Proxy自定义的后续操作。
Native侧接口
接口名 | 功能描述 |
AddDeathRecipient(const sptr<DeathRecipient> &recipient); | 订阅远端Stub对象状态。 |
RemoveDeathRecipient(const sptr<DeathRecipient> &recipient); | 取消订阅远端Stub对象状态。 |
OnRemoteDied(const wptr<IRemoteObject> &object); | 当远端Stub对象死亡时回调。 |
参考代码
class TestDeathRecipient : public IRemoteObject::DeathRecipient {
public:
virtual void OnRemoteDied(const wptr<IRemoteObject>& remoteObject);
}
sptr<IRemoteObject::DeathRecipient> deathRecipient (new TestDeathRecipient());// 构造一个死亡通知对象
bool result = proxy->AddDeathRecipient(deathRecipient); // 注册死亡通知
result = proxy->RemoveDeathRecipient(deathRecipient); // 移除死亡通知
电话服务开发概述
电话服务系统提供了一系列的API用于拨打电话、获取无线蜂窝网络和SIM卡相关信息。
应用可以通过调用API来获取当前注册网络名称、网络服务状态、信号强度以及SIM卡的相关信息,具体可参考获取当前蜂窝网络信号信息开发指导。
直接拨打电话需要系统权限ohos.permission.PLACE_CALL,建议应用使用makeCall(),跳转到拨号界面,并显示拨号的号码,具体可参考跳转拨号界面开发指导。
约束与限制
搭载设备需要支持以下硬件:
可以进行独立蜂窝通信的Modem以及SIM卡。
跳转拨号界面
当应用需要跳转到拨号界面,并显示拨号的号码时,使用本业务。当开发者调用makeCall接口时,设备会自动跳转到拨号界面。和正常拨打电话一样,用户可以选择音频或视频呼叫,卡1或卡2拨出。
接口说明
call模块为开发者提供呼叫管理功能。observer模块为开发者提供订阅和取消订阅通话业务状态的功能。具体接口说明如下表。
功能分类 | 接口名 | 描述 | 所需权限 |
能力获取 | call.hasVoiceCapability() | 是否具有语音功能 | 无 |
跳转拨号界面 | call.makeCall() | 跳转到拨号界面,并显示拨号的号码 | 无 |
订阅通话业务状态变化 | observer.on('callStateChange') | 订阅通话业务状态变化 | ohos.permission.READ_CALL_LOG (获取通话号码需要该权限) |
取消订阅通话业务状态变化 | observer.off('callStateChange') | 取消订阅通话业务状态变化 | 无 |
开发步骤
- import需要的模块。
- 调用hasVoiceCapability()接口获取当前设备呼叫能力,如果支持继续下一步;如果不支持则无法发起呼叫。
- 跳转到拨号界面,并显示拨号的号码。
- (可选)订阅通话业务状态变化。
// import需要的模块
import call from '@ohos.telephony.call';
import observer from '@ohos.telephony.observer';
// 调用查询能力接口
let isSupport = call.hasVoiceCapability();
if (!isSupport) {
console.log("not support voice capability, return.");
}
// 如果设备支持呼叫能力,则继续跳转到拨号界面,并显示拨号的号码
call.makeCall("13xxxx", (err)=> {
if (!err) {
console.log("make call success.");
} else {
console.log("make call fail, err is:" + JSON.stringify(err));
}
});
// 订阅通话业务状态变化(可选)
observer.on("callStateChange", (data) => {
console.log("call state change, data is:" + JSON.stringify(data));
});
获取当前蜂窝网络信号信息
场景介绍
应用通常需要获取用户所在蜂窝网络下信号信息,以便获取当前驻网质量。开发者可以通过本业务,获取到用户指定SIM卡当前所在网络下的信号信息。
接口说明
radio模块提供了获取当前网络信号信息的方法。observer模块为开发者提供蜂窝网络状态订阅和取消订阅功能。具体接口说明如下表。
功能分类 | 接口名 | 描述 | 所需权限 |
信号强度信息 | radio.getSignalInformation() | 获取当前注册蜂窝网络信号强度信息 | 无 |
订阅蜂窝网络信号变化 | observer.on('signalInfoChange') | 订阅蜂窝网络信号变化 | 无 |
取消订阅蜂窝网络信号变化 | observer.off('signalInfoChange') | 取消订阅蜂窝网络信号变化 | 无 |
开发步骤
- import需要的模块。
- 调用getSignalInformation()方法,返回所有SignalInformation列表。
- 遍历SignalInformation数组,并分别根据不同的signalType得到不同制式的信号强度。
- 订阅蜂窝网络信号变化(可选)。
import radio from '@ohos.telephony.radio'
import observer from '@ohos.telephony.observer';
// 以获取卡1的信号强度为例
let slotId = 0;
radio.getSignalInformation(slotId, (err, data) => {
if (!err) {
console.log("get signal information success.");
// 遍历数组,输出不同网络制式下的信号强度
for (let j = 0; j < data.length; j++) {
console.log("type:" + data[j].signalType + ", level:" + data[j].signalLevel);
}
} else {
console.log("get signal information fail, err is:" + JSON.stringify(err));
}
});
// 订阅蜂窝网络信号变化(可选)
observer.on("signalInfoChange", (data) => {
console.log("signal info change, data is:" + JSON.stringify(data));
});