12 Star 20 Fork 213

OpenHarmony / communication_netstack

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
README_zh.md 31.52 KB
一键复制 编辑 原始数据 按行查看 历史

Net Stack

简介

网络协议栈介绍:

网络协议栈模块作为电话子系统可裁剪部件,主要分为HTTP和socket模块;如图1:Http接口架构图;如图2:socket接口架构图;

图 1 Http接口架构图

net_conn_manager_arch_zh

图 2 socket接口架构图

net_conn_manager_arch_zh

目录

/foundation/communication/netstack
├─figures                            # 架构图
├─frameworks                         # 接口实现
│  ├─js                              # JS API实现
│  │   ├─builtin                     # 小型系统JS API实现
│  │   │   ├── http_request          # http请求实现目录
│  │   │   └── test                  # 测试代码
│  │   └─napi                        # 标准系统JS API实现
│  │       ├─fetch                   # fetch API
│  │       ├─http                    # http API
│  │       ├─socket                  # socket API
│  │       ├─tls                     # tls socket API
│  │       └─websocket               # websocket API
│  └─native                          # native接口
│    └─tls_socket                    # tls socket native实现
├─interfaces                         # 接口定义
│  ├─innerkits                       # native接口
│  │  └─tls_socket                   # tls socket native接口
│  └─kits                            # JS接口
│     └─js                           # 本地.d.ts文件
├─test                               # 测试代码目录
└─utils                              # 公共功能
   ├─common_utils                    # 共通库目录
   ├─log                             # 日志实现目录
   └─napi_utils                      # 公用NAPI代码目录

接口说明

Http接口说明

类型 接口 功能说明
ohos.net.socket function createHttp(): HttpRequest 返回一个HttpRequest对象
ohos.net.http.HttpRequest on(type: "headerReceive", callback: AsyncCallback<Object>): void 监听收到Http头的事件
ohos.net.http.HttpRequest once(type: "headerReceive", callback: Callback<Object>): void 监听收到Http头的事件,只监听一次
ohos.net.http.HttpRequest off(type: "headerReceive", callback: AsyncCallback<Object>): void 取消监听收到Http头的事件
ohos.net.http.HttpRequest on(type: "headerReceive", callback: Callback<Object>): void 监听收到Http头的事件
ohos.net.http.HttpRequest once(type: "headerReceive", callback: Callback<Object>): void 监听收到Http头的事件,只监听一次
ohos.net.http.HttpRequest off(type: "headerReceive", callback: Callback<Object>): void 取消监听收到Http头的事件
ohos.net.http.HttpRequest request(url: string, callback: AsyncCallback<HttpResponse>): void GET方法请求一个域名,调用callback
ohos.net.http.HttpRequest request(url: string, options: HttpRequestOptions, callback: AsyncCallback<HttpResponse>): void 请求一个域名,options中携带请求参数,调用callback
ohos.net.http.HttpRequest request(url: string, options?: HttpRequestOptions: Promise<HttpResponse> 请求一个域名,options中携带请求参数(可选),返回Promise

HttpRequestOptions

发起请求可选参数的类型和取值范围。

参数 类型 必填 说明
method RequestMethod 请求方式,默认为GET。
extraData string6+ | Object6+ | ArrayBuffer8+ 发送请求的额外数据,默认无此字段。
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content,以UTF-8编码形式作为请求体。6+
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求参数的补充。开发者需传入Encode编码后的string类型参数,Object类型的参数无需预编码,参数内容会拼接到URL中进行发送;ArrayBuffer类型的参数不会做拼接处理。6+
expectDataType9+ HttpDataType 指定返回数据的类型,默认无此字段。如果设置了此参数,系统将优先返回指定的类型。
usingCache9+ boolean 是否使用缓存,默认为true。
priority9+ number 优先级,范围[1,1000],默认是1。
header Object HTTP请求头字段。默认{'Content-Type': 'application/json'}。
readTimeout number 读取超时时间。单位为毫秒(ms),默认为60000ms。
设置为0表示不会出现超时情况。
connectTimeout number 连接超时时间。单位为毫秒(ms),默认为60000ms。
usingProtocol9+ HttpProtocol 使用协议。默认值由系统自动指定。
usingProxy10+ boolean | Object 是否使用HTTP代理,默认为false,不使用代理。
- 当usingProxy为布尔类型true时,使用默认网络代理。
- 当usingProxy为object类型时,使用指定网络代理。
caPath10+ string 如果设置了此参数,系统将使用用户指定路径的CA证书,否则将使用系统预设CA证书。

RequestMethod

HTTP 请求方法。

method 的合法值 说明
OPTIONS HTTP 请求 OPTIONS。
GET HTTP 请求 GET。
HEAD HTTP 请求 HEAD。
POST HTTP 请求 POST。
PUT HTTP 请求 PUT。
DELETE HTTP 请求 DELETE。
TRACE HTTP 请求 TRACE。
CONNECT HTTP 请求 CONNECT。

ResponseCode

发起请求返回的响应码。

变量 说明
OK 200 请求成功。一般用于GET与POST请求。
CREATED 201 已创建。成功请求并创建了新的资源。
ACCEPTED 202 已接受。已经接受请求,但未处理完成。
NOT_AUTHORITATIVE 203 非授权信息。请求成功。
NO_CONTENT 204 无内容。服务器成功处理,但未返回内容。
RESET 205 重置内容。
PARTIAL 206 部分内容。服务器成功处理了部分GET请求。
MULT_CHOICE 300 多种选择。
MOVED_PERM 301 永久移动。请求的资源已被永久的移动到新URI,返回信息会包括新的URI,浏览器会自动定向到新URI。
MOVED_TEMP 302 临时移动。
SEE_OTHER 303 查看其它地址。
NOT_MODIFIED 304 未修改。
USE_PROXY 305 使用代理。
BAD_REQUEST 400 客户端请求的语法错误,服务器无法理解。
UNAUTHORIZED 401 请求要求用户的身份认证。
PAYMENT_REQUIRED 402 保留,将来使用。
FORBIDDEN 403 服务器理解请求客户端的请求,但是拒绝执行此请求。
NOT_FOUND 404 服务器无法根据客户端的请求找到资源(网页)。
BAD_METHOD 405 客户端请求中的方法被禁止。
NOT_ACCEPTABLE 406 服务器无法根据客户端请求的内容特性完成请求。
PROXY_AUTH 407 请求要求代理的身份认证。
CLIENT_TIMEOUT 408 请求时间过长,超时。
CONFLICT 409 服务器完成客户端的PUT请求是可能返回此代码,服务器处理请求时发生了冲突。
GONE 410 客户端请求的资源已经不存在。
LENGTH_REQUIRED 411 服务器无法处理客户端发送的不带Content-Length的请求信息。
PRECON_FAILED 412 客户端请求信息的先决条件错误。
ENTITY_TOO_LARGE 413 由于请求的实体过大,服务器无法处理,因此拒绝请求。
REQ_TOO_LONG 414 请求的URI过长(URI通常为网址),服务器无法处理。
UNSUPPORTED_TYPE 415 服务器无法处理请求的格式。
INTERNAL_ERROR 500 服务器内部错误,无法完成请求。
NOT_IMPLEMENTED 501 服务器不支持请求的功能,无法完成请求。
BAD_GATEWAY 502 充当网关或代理的服务器,从远端服务器接收到了一个无效的请求。
UNAVAILABLE 503 由于超载或系统维护,服务器暂时的无法处理客户端的请求。
GATEWAY_TIMEOUT 504 充当网关或代理的服务器,未及时从远端服务器获取请求。
VERSION 505 服务器请求的HTTP协议的版本。

HttpResponse

request方法回调函数的返回值类型。

参数名 类型 必填 说明
result string | Object |ArrayBuffer8+ Http请求根据响应头中Content-type类型返回对应的响应格式内容:
- application/json:返回JSON格式的字符串,如需Http响应具体内容,需开发者自行解析
- application/octet-stream:ArrayBuffer
- 其他:string
responseCode ResponseCode | number 回调函数执行成功时,此字段为ResponseCode。若执行失败,错误码将会从AsyncCallback中的err字段返回。错误码如下:
- 200:通用错误
- 202:参数错误
- 300:I/O错误
header Object 发起http请求返回来的响应头。当前返回的是JSON格式字符串,如需具体字段内容,需开发者自行解析。常见字段及解析方式如下:
- Content-Type:header['Content-Type'];
- Status-Line:header['Status-Line'];
- Date:header.Date/header['Date'];
- Server:header.Server/header['Server'];
cookies8+ string 服务器返回的 cookies。

HttpDataType

http的数据类型。

名称 说明
STRING 0 字符串类型。
OBJECT 1 对象类型。
ARRAY_BUFFER 2 二进制数组类型。

HttpProtocol

http协议版本。

名称 说明
HTTP1_1 协议http1.1
HTTP2 协议http2

示例

import http from "@ohos.net.http"
let httpRequest = http.createHttp()
httpRequest.request("www.example.com", function (err, data) {
    console.log(JSON.stringify(err))
    console.log(JSON.stringify(data))
})

socket接口说明

类型 接口 功能说明
ohos.net.socket function constructUDPSocketInstance(): UDPSocket 返回一个UDPSocket对象
ohos.net.socket function constructUDPSocketInstance(): TCPSocket 返回一个TCPSocket对象
ohos.net.socket function constructTLSSocketInstance(): TLSSocket 返回一个TLSSocket对象
ohos.net.socket.UDPSocket bind(address: NetAddress, callback: AsyncCallback<void>): void 绑定IP地址和端口,端口可以指定或由系统随机分配。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket bind(address: NetAddress): Promise<void> 绑定IP地址和端口,端口可以指定或由系统随机分配。使用Promise方式作为异步方法。
ohos.net.socket.UDPSocket send(options: UDPSendOptions, callback: AsyncCallback<void>): void 通过UDPSocket连接发送数据。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket send(options: UDPSendOptions): Promise<void> 通过UDPSocket连接发送数据。使用Promise方式作为异步方法。
ohos.net.socket.UDPSocket close(callback: AsyncCallback<void>): void 关闭UDPSocket连接。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket close(): Promise<void> 关闭UDPSocket连接。使用Promise方式作为异步方法。
ohos.net.socket.UDPSocket getState(callback: AsyncCallback<SocketStateBase>): void 获取UDPSocket状态。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket getState(): Promise<SocketStateBase> 获取UDPSocket状态。使用Promise方式作为异步方法。
ohos.net.socket.UDPSocket setExtraOptions(options: UDPExtraOptions, callback: AsyncCallback<void>): void 设置UDPSocket连接的其他属性。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket setExtraOptions(options: UDPExtraOptions): Promise<void> 设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。
ohos.net.socket.UDPSocket on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void 订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket off(type: 'message', callback?: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void 取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket on(type: 'listening' | 'close', callback: Callback<void>): void 订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket off(type: 'listening' | 'close', callback?: Callback<void>): void 取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket on(type: 'error', callback?: ErrorCallback): void 订阅UDPSocket连接的error事件。使用callback方式作为异步方法。
ohos.net.socket.UDPSocket off(type: 'error', callback?: ErrorCallback): void 取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket bind(address: NetAddress, callback: AsyncCallback<void>): void 绑定IP地址和端口,端口可以指定或由系统随机分配。使用callback方法作为异步方法。
ohos.net.socket.TCPSocket bind(address NetAddress): Promise<void> 绑定IP地址和端口,端口可以指定或由系统随机分配。使用Promise方法作为异步方法。
ohos.net.socket.TCPSocket connect(options: TCPConnectOptions, callback: AsyncCallback<void>): void 连接到指定的IP地址和端口。使用callback方法作为异步方法。
ohos.net.socket.TCPSocket connect(options: TCPConnectOptions): Promise<void> 连接到指定的IP地址和端口。使用Promise方法作为异步方法。
ohos.net.socket.TCPSocket send(options: TCPSendOptions, callback: AsyncCallback<void>): void 通过TCPSocket连接发送数据。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket send(options: TCPSendOptions): Promise<void> 通过TCPSocket连接发送数据。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket close(callback: AsyncCallback<void>): void 关闭TCPSocket连接。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket close(): Promise<void> 关闭TCPSocket连接。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket getRemoteAddress(callback: AsyncCallback<NetAddress>): void 获取对端Socket地址。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket getRemoteAddress(): Promise<NetAddress> 获取对端Socket地址。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket getState(callback: AsyncCallback<SocketStateBase>): void 获取TCPSocket状态。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket getState(): Promise<SocketStateBase> 获取TCPSocket状态。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket setExtraOptions(options: TCPExtraOptions, callback: AsyncCallback): void 设置TCPSocket连接的其他属性。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket setExtraOptions(options: TCPExtraOptions): Promise 设置TCPSocket连接的其他属性。使用Promise方式作为异步方法。
ohos.net.socket.TCPSocket on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void 订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket off(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: SocketRemoteInfo}>): void 取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket on(type: 'connect' | 'close', callback: Callback): void 订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket off(type: 'connect' | 'close', callback: Callback): void 取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket on(type: 'error', callback?: ErrorCallback): void 订阅TCPSocket连接的error事件。使用callback方式作为异步方法。
ohos.net.socket.TCPSocket off(type: 'error', callback?: ErrorCallback): void 取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。
ohos.net.socket.TLSSocket connect(options: TLSConnectOptions, callback: AsyncCallback<void>): void 在TLSSocket上进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket connect(options: TLSConnectOptions): Promise<void> 在TLSSocket上进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket getCertificate(callback: AsyncCallback<X509CertRawData>): void 在TLSSocket通信连接之后,获取本地的数字证书,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket getCertificate():Promise<X509CertRawData> 在TLSSocket通信连接之后,获取本地的数字证书,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket getRemoteCertificate(callback: AsyncCallback<X509CertRawData>): void 在TLSSocket通信连接之后,获取对等方的数字证书,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket getRemoteCertificate(): Promise<X509CertRawData> 在TLSSocket通信连接之后,获取对等方的数字证书,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket getProtocol(callback: AsyncCallback<string>): void 在TLSSocket通信连接之后,获取通信的协议,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket getProtocol(): Promise<string> 在TLSSocket通信连接之后,获取通信的协议,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket getCipherSuite(callback: AsyncCallback<Array<string>>): void 在TLSSocket通信连接之后,获取通信双方支持的加密套件,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket getCipherSuite(): Promise<Array<string>> 在TLSSocket通信连接之后,获取通信双方支持的加密套件,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket getSignatureAlgorithms(callback: AsyncCallback<Array<string>>): void 在TLSSocket通信连接之后,获取通信双方支持的签名算法,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket getSignatureAlgorithms(): Promise<Array<string>> 在TLSSocket通信连接之后,获取通信双方支持的签名算法,使用Promise方式作为异步方法。
ohos.net.socket.TLSSocket send(data: string, callback: AsyncCallback<void>): void 在TLSSocket通信连接之后,向服务端发送消息,使用callback方式作为异步方法。
ohos.net.socket.TLSSocket send(data: string): Promise<void> 在TLSSocket通信连接之后,向服务端发送消息,使用Promise方式作为异步方法。

NetAddress

目标地址信息。

参数名 类型 必填 说明
address string 本地绑定的ip地址。
port number 端口号 ,范围0~65535。如果不指定系统随机分配端口。
family number 网络协议类型,可选类型:
- 1:IPv4
- 2:IPv6
默认为1。

UDPSendOptions

UDPSocket发送参数。

参数名 类型 必填 说明
data string 发送的数据。
address NetAddress 目标地址信息。

UDPExtraOptions

UDPSocket连接的其他属性。

参数名 类型 必填 说明
broadcast boolean 是否可以发送广播。默认为false。
receiveBufferSize number 接收缓冲区大小(单位:Byte)。
sendBufferSize number 发送缓冲区大小(单位:Byte)。
reuseAddress boolean 是否重用地址。默认为false。
socketTimeout number 套接字超时时间,单位毫秒(ms)。

SocketStateBase

Socket的状态信息。

参数名 类型 必填 说明
isBound boolean 是否绑定。
isClose boolean 是否关闭。
isConnected boolean 是否连接。

SocketRemoteInfo

Socket的连接信息。

参数名 类型 必填 说明
address string 本地绑定的ip地址。
family string 网络协议类型,可选类型:
- IPv4
- IPv6
默认为IPv4。
port number 端口号,范围0~65535。
size number 服务器响应信息的字节长度。

TCPConnectOptions

TCPSocket连接的参数。

参数名 类型 必填 说明
address NetAddress 绑定的地址以及端口。
timeout number 超时时间,单位毫秒(ms)。

TCPSendOptions

TCPSocket发送请求的参数。

参数名 类型 必填 说明
data string 发送的数据。
encoding string 字符编码(UTF-8,UTF-16BE,UTF-16LE,UTF-16,US-AECII,ISO-8859-1),默认为UTF-8。

TCPExtraOptions

TCPSocket连接的其他属性。

参数名 类型 必填 说明
keepAlive boolean 是否保持连接。默认为false。
OOBInline boolean 是否为OOB内联。默认为false。
TCPNoDelay boolean TCPSocket连接是否无时延。默认为false。
socketLinger Object socket是否继续逗留。
- on:是否逗留(true:逗留;false:不逗留)。
- linger:逗留时长,单位毫秒(ms),取值范围为0~65535。
当入参on设置为true时,才需要设置。
receiveBufferSize number 接收缓冲区大小(单位:Byte)。
sendBufferSize number 发送缓冲区大小(单位:Byte)。
reuseAddress boolean 是否重用地址。默认为false。
socketTimeout number 套接字超时时间,单位毫秒(ms)。

TLSConnectOptions

TLS连接的操作。

参数名 类型 说明
address NetAddress 网关地址。
secureOptions TLSSecureOptions TLS安全相关操作。
ALPNProtocols Array<string> ALPN协议。

TLSSecureOptions

TLS安全相关操作。

参数名 类型 说明
ca string | Array<string> ca证书。
cert string 本地数字证书。
key string 本地数字证书私钥。
passwd string 密码。
protocols Protocol | Array<Protocol>; 协议名。
useRemoteCipherPrefer boolean 优先使用对等方的密码套件。
signatureAlgorithms string 设置签名算法。
cipherSuite string 加密套件。

X509CertRawData

参数名 类型 说明
data Uint8Array 证书内容。
encodingFormat number 编码格式pem。

Protocol

TLS通信的协议。

protocol 的合法值 说明
TLSv12 使用TLSv1.2协议通信。
TLSv13 使用TLSv1.3协议通信。

示例

import socket from "@ohos.net.socket"
let tcp = socket.constructTCPSocketInstance()
tcp.on("message", function (data) {
  console.log(JSON.stringify(data))
})
tcp.bind({
  address: "127.0.0.1",
  family: 1,
  port: 0
})
tcp.connect({
  address: {
    address: "127.0.0.1",
    family: 1,
    port: 8888
  }
})
tcp.send({
  data: "Hello World"
})

let udp = socket.constructUDPSocketInstance()
udp.bind({
  address: "127.0.0.1",
  family: 1,
  port: 0
})
udp.send({
  address: {
    address: "127.0.0.1",
    family: 1,
    port: 9999
  },
  data: "Hello World"
})

let tls = socket.constructTLSSocketInstance();
let Protocol = socket.Protocol;
let options = {
            ALPNProtocols: ["spdy/1", "http/1.1"],
            address: {
                address: "xxxx",
                port: "xxxx",
                family: 1,
            },
            secureOptions: {
                key: "xxxx",
                cert: "xxxx",
                ca: ["xxxx"],
                passwd: "123456",
                protocols: [Protocol.TLSv12],
                useRemoteCipherPrefer: true,
                signatureAlgorithms: rsa_pss_rsae_sha256:ECDSA+SHA25,
                cipherSuite: AES256-SHA256,
            },
};
tls.connect(options).then(data => {
  console.info(data);
}).catch(err => {
  console.error(err);
});
tls.getProtocol((err, data) => {
  if (err) {
    console.log("getProtocol callback error = " + err);
  } else {
    console.log("getProtocol callback = " + data);
  }
});
let data = "Hello Word";
tls.send(data, (err, data) => {
  if (err) {
    console.log("send callback error = " + err);
  } else {
    console.log("send callback = " + data);
  }
});

相关仓

网络管理子系统

communication_netstack

communication_netmanager_base

communication_netmanager_ext

1
https://gitee.com/openharmony/communication_netstack.git
git@gitee.com:openharmony/communication_netstack.git
openharmony
communication_netstack
communication_netstack
master

搜索帮助