HarmonyOS Developer 开发指导

丶龙八夷
发布于 2023-3-31 16:38
浏览
0收藏

网络管理开发概述

网络管理模块主要提供以下功能:

约束与限制

使用网络管理模块的相关功能时,需要请求相应的权限。

权限名

说明

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 事件。

开发步骤

  1. import需要的http模块。
  2. 创建一个HTTP请求,返回一个HttpRequest对象。
  3. (可选)订阅HTTP响应头。
  4. 根据URL地址,发起HTTP网络请求。
  5. (可选)处理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事件。

开发步骤

  1. 导入需要的webSocket模块。
  2. 创建一个WebSocket连接,返回一个WebSocket对象。
  3. (可选)订阅WebSocket的打开、消息接收、关闭、Error事件。
  4. 根据URL地址,发起WebSocket连接。
  5. 使用完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为例:

  1. import需要的socket模块。
  2. 创建一个TCPSocket连接,返回一个TCPSocket对象。
  3. (可选)订阅TCPSocket相关的订阅事件。
  4. 绑定IP地址和端口,端口可以指定或由系统随机分配。
  5. 连接到指定的IP地址和端口。
  6. 发送数据。
  7. 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接口

类/接口

方法

功能说明

​IRemoteBroker​

sptr<IRemoteObject> AsObject()

返回通信对象。派生类需要实现,Stub端返回RemoteObject对象本身,Proxy端返回代理对象。

IRemoteStub

virtual int OnRemoteRequest(uint32_t code, MessageParcel &data, MessageParcel &reply, MessageOption &option)

请求处理方法,派生类需要重写该方法用来处理Proxy的请求并返回结果。

IRemoteProxy

业务Proxy类,派生自IRemoteProxy类。

开发步骤

Native侧开发步骤

  1. 定义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; // 定义业务函数
};
  1. 定义和实现服务端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);
    }
}
  1. 定义服务端业务函数具体实现类TestAbility

class TestAbility : public TestAbilityStub {
public:
    int TestPingAbility(const std::u16string &dummy);
}

int TestAbility::TestPingAbility(const std::u16string &dummy) {
    return 0;
}
  1. 定义和实现客户端 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;
 }
  1. 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);
  1. 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')

取消订阅通话业务状态变化

开发步骤

  1. import需要的模块。
  2. 调用hasVoiceCapability()接口获取当前设备呼叫能力,如果支持继续下一步;如果不支持则无法发起呼叫。
  3. 跳转到拨号界面,并显示拨号的号码。
  4. (可选)订阅通话业务状态变化。

// 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')

取消订阅蜂窝网络信号变化

开发步骤

  1. import需要的模块。
  2. 调用getSignalInformation()方法,返回所有SignalInformation列表。
  3. 遍历SignalInformation数组,并分别根据不同的signalType得到不同制式的信号强度。
  4. 订阅蜂窝网络信号变化(可选)。

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




文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/cellular-network-signal-info-0000001427902352-V3​

标签
已于2023-3-31 16:38:21修改
收藏
回复
举报
回复
    相关推荐