README_zh.md
1# Net Stack
2
3## 简介
4
5网络协议栈介绍：
6
7 网络协议栈模块作为电话子系统可裁剪部件，主要分为HTTP和socket模块；如图1：Http接口架构图；如图2：socket接口架构图；
8
9**图 1** Http接口架构图
10
11
12
13**图 2** socket接口架构图
14
15
16
17## 目录
18
19```
20/foundation/communication/netstack
21├─figures # 架构图
22├─frameworks # 接口实现
23│ ├─js # JS API实现
24│ │ ├─builtin # 小型系统JS API实现
25│ │ │ ├── http_request # http请求实现目录
26│ │ │ └── test # 测试代码
27│ │ └─napi # 标准系统JS API实现
28│ │ ├─fetch # fetch API
29│ │ ├─http # http API
30│ │ ├─socket # socket API
31│ │ ├─tls # tls socket API
32│ │ └─websocket # websocket API
33│ └─native # native接口
34│ └─tls_socket # tls socket native实现
35├─interfaces # 接口定义
36│ ├─innerkits # native接口
37│ │ └─tls_socket # tls socket native接口
38│ └─kits # JS接口
39│ └─js # 本地.d.ts文件
40├─test # 测试代码目录
41└─utils # 公共功能
42 ├─common_utils # 共通库目录
43 ├─log # 日志实现目录
44 └─napi_utils # 公用NAPI代码目录
45```
46
47## 接口说明
48
49### Http接口说明
50
51| 类型 | 接口 | 功能说明 |
52| ---- | ---- | ---- |
53| ohos.net.socket | function createHttp(): HttpRequest | 返回一个HttpRequest对象 |
54| ohos.net.http.HttpRequest | on(type: "headerReceive", callback: AsyncCallback\<Object>): void | 监听收到Http头的事件 |
55| ohos.net.http.HttpRequest | once(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件，只监听一次 |
56| ohos.net.http.HttpRequest | off(type: "headerReceive", callback: AsyncCallback\<Object>): void | 取消监听收到Http头的事件 |
57| ohos.net.http.HttpRequest | on(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件 |
58| ohos.net.http.HttpRequest | once(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件，只监听一次 |
59| ohos.net.http.HttpRequest | off(type: "headerReceive", callback: Callback\<Object>): void | 取消监听收到Http头的事件 |
60| ohos.net.http.HttpRequest | request(url: string, callback: AsyncCallback\<[HttpResponse](#httpresponse)>): void | 用**GET**方法请求一个域名，调用callback |
61| ohos.net.http.HttpRequest | request(url: string, options: [HttpRequestOptions](#httprequestoptions), callback: AsyncCallback\<[HttpResponse](#httpresponse)>): void | 请求一个域名，options中携带请求参数，调用callback |
62| ohos.net.http.HttpRequest | request(url: string, options?: [HttpRequestOptions](#httprequestoptions): Promise\<[HttpResponse](#httpresponse)> | 请求一个域名，options中携带请求参数(可选)，返回Promise |
63
64#### HttpRequestOptions
65
66发起请求可选参数的类型和取值范围。
67
68| 参数 | 类型 | 必填 | 说明 |
69| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
70| method | [RequestMethod](#requestmethod) | 否 | 请求方式，默认为GET。 |
71| extraData | string<sup>6+</sup> \| Object<sup>6+</sup> \| ArrayBuffer<sup>8+</sup> | 否 | 发送请求的额外数据，默认无此字段。<br />- 当HTTP请求为POST、PUT等方法时，此字段为HTTP请求的content，以UTF-8编码形式作为请求体。<sup>6+</sup><br />- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时，此字段为HTTP请求参数的补充。开发者需传入Encode编码后的string类型参数，Object类型的参数无需预编码，参数内容会拼接到URL中进行发送；ArrayBuffer类型的参数不会做拼接处理。<sup>6+</sup> |
72| expectDataType<sup>9+</sup> | [HttpDataType](#httpdatatype) | 否 | 指定返回数据的类型，默认无此字段。如果设置了此参数，系统将优先返回指定的类型。 |
73| usingCache<sup>9+</sup> | boolean | 否 | 是否使用缓存，默认为true。 |
74| priority<sup>9+</sup> | number | 否 | 优先级，范围[1,1000]，默认是1。 |
75| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 |
76| readTimeout | number | 否 | 读取超时时间。单位为毫秒（ms），默认为60000ms。<br />设置为0表示不会出现超时情况。 |
77| connectTimeout | number | 否 | 连接超时时间。单位为毫秒（ms），默认为60000ms。 |
78| usingProtocol<sup>9+</sup> | [HttpProtocol](#httpprotocol) | 否 | 使用协议。默认值由系统自动指定。 |
79| usingProxy<sup>10+</sup> | boolean \| Object | 否 | 是否使用HTTP代理，默认为false，不使用代理。<br />- 当usingProxy为布尔类型true时，使用默认网络代理。<br />- 当usingProxy为object类型时，使用指定网络代理。 |
80| caPath<sup>10+</sup> | string | 否 | 如果设置了此参数，系统将使用用户指定路径的CA证书，否则将使用系统预设CA证书。 |
81
82#### RequestMethod
83
84HTTP 请求方法。
85
86| **method 的合法值** | 说明 |
87| :------------------ | :------------------ |
88| OPTIONS | HTTP 请求 OPTIONS。 |
89| GET | HTTP 请求 GET。 |
90| HEAD | HTTP 请求 HEAD。 |
91| POST | HTTP 请求 POST。 |
92| PUT | HTTP 请求 PUT。 |
93| DELETE | HTTP 请求 DELETE。 |
94| TRACE | HTTP 请求 TRACE。 |
95| CONNECT | HTTP 请求 CONNECT。 |
96
97#### ResponseCode
98
99发起请求返回的响应码。
100
101| 变量 | 值 | 说明 |
102| ----------------- | ---- | ------------------------------------------------------------ |
103| OK | 200 | 请求成功。一般用于GET与POST请求。 |
104| CREATED | 201 | 已创建。成功请求并创建了新的资源。 |
105| ACCEPTED | 202 | 已接受。已经接受请求，但未处理完成。 |
106| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 |
107| NO_CONTENT | 204 | 无内容。服务器成功处理，但未返回内容。 |
108| RESET | 205 | 重置内容。 |
109| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 |
110| MULT_CHOICE | 300 | 多种选择。 |
111| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。 |
112| MOVED_TEMP | 302 | 临时移动。 |
113| SEE_OTHER | 303 | 查看其它地址。 |
114| NOT_MODIFIED | 304 | 未修改。 |
115| USE_PROXY | 305 | 使用代理。 |
116| BAD_REQUEST | 400 | 客户端请求的语法错误，服务器无法理解。 |
117| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 |
118| PAYMENT_REQUIRED | 402 | 保留，将来使用。 |
119| FORBIDDEN | 403 | 服务器理解请求客户端的请求，但是拒绝执行此请求。 |
120| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源（网页）。 |
121| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 |
122| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 |
123| PROXY_AUTH | 407 | 请求要求代理的身份认证。 |
124| CLIENT_TIMEOUT | 408 | 请求时间过长，超时。 |
125| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突。 |
126| GONE | 410 | 客户端请求的资源已经不存在。 |
127| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 |
128| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 |
129| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大，服务器无法处理，因此拒绝请求。 |
130| REQ_TOO_LONG | 414 | 请求的URI过长（URI通常为网址），服务器无法处理。 |
131| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 |
132| INTERNAL_ERROR | 500 | 服务器内部错误，无法完成请求。 |
133| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能，无法完成请求。 |
134| BAD_GATEWAY | 502 | 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 |
135| UNAVAILABLE | 503 | 由于超载或系统维护，服务器暂时的无法处理客户端的请求。 |
136| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器，未及时从远端服务器获取请求。 |
137| VERSION | 505 | 服务器请求的HTTP协议的版本。 |
138
139#### HttpResponse
140
141request方法回调函数的返回值类型。
142
143| 参数名 | 类型 | 必填 | 说明 |
144| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
145| result | string | Object |ArrayBuffer<sup>8+</sup> | 是 | Http请求根据响应头中Content-type类型返回对应的响应格式内容：<br />- application/json：返回JSON格式的字符串，如需Http响应具体内容，需开发者自行解析<br />- application/octet-stream：ArrayBuffer<br />- 其他：string |
146| responseCode | [ResponseCode](#responsecode) | number | 是 | 回调函数执行成功时，此字段为[ResponseCode](#responsecode)。若执行失败，错误码将会从AsyncCallback中的err字段返回。错误码如下：<br />- 200：通用错误<br />- 202：参数错误<br />- 300：I/O错误 |
147| header | Object | 是 | 发起http请求返回来的响应头。当前返回的是JSON格式字符串，如需具体字段内容，需开发者自行解析。常见字段及解析方式如下：<br/>- Content-Type：header['Content-Type']；<br />- Status-Line：header['Status-Line']；<br />- Date：header.Date/header['Date']；<br />- Server：header.Server/header['Server']； |
148| cookies<sup>8+</sup> | string | 是 | 服务器返回的 cookies。 |
149#### HttpDataType
150
151http的数据类型。
152
153| 名称 | 值 | 说明 |
154| ------------------ | -- | ----------- |
155| STRING | 0 | 字符串类型。 |
156| OBJECT | 1 | 对象类型。 |
157| ARRAY_BUFFER | 2 | 二进制数组类型。|
158
159#### HttpProtocol
160http协议版本。
161
162| 名称 | 说明 |
163| :-------- | :----------- |
164| HTTP1_1 | 协议http1.1 |
165| HTTP2 | 协议http2 |
166#### 示例
167
168```javascript
169import http from "@ohos.net.http"
170let httpRequest = http.createHttp()
171httpRequest.request("www.example.com", function (err, data) {
172 console.log(JSON.stringify(err))
173 console.log(JSON.stringify(data))
174})
175```
176
177### socket接口说明
178
179| 类型 | 接口 | 功能说明 |
180| ---- | ---- | ---- |
181| ohos.net.socket | function constructUDPSocketInstance(): UDPSocket | 返回一个UDPSocket对象 |
182| ohos.net.socket | function constructUDPSocketInstance(): TCPSocket | 返回一个TCPSocket对象 |
183| ohos.net.socket | function constructTLSSocketInstance(): TLSSocket | 返回一个TLSSocket对象 |
184| ohos.net.socket.UDPSocket | bind(address: [NetAddress](#netaddress), callback: AsyncCallback\<void>): void | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方式作为异步方法。 |
185| ohos.net.socket.UDPSocket | bind(address: [NetAddress](#netaddress)): Promise\<void> | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方式作为异步方法。 |
186| ohos.net.socket.UDPSocket | send(options: [UDPSendOptions](#udpsendoptions), callback: AsyncCallback\<void>): void | 通过UDPSocket连接发送数据。使用callback方式作为异步方法。 |
187| ohos.net.socket.UDPSocket | send(options: [UDPSendOptions](#udpsendoptions)): Promise\<void> | 通过UDPSocket连接发送数据。使用Promise方式作为异步方法。 |
188| ohos.net.socket.UDPSocket | close(callback: AsyncCallback\<void>): void | 关闭UDPSocket连接。使用callback方式作为异步方法。 |
189| ohos.net.socket.UDPSocket | close(): Promise\<void> | 关闭UDPSocket连接。使用Promise方式作为异步方法。 |
190| ohos.net.socket.UDPSocket | getState(callback: AsyncCallback\<[SocketStateBase](#socketstatebase)>): void | 获取UDPSocket状态。使用callback方式作为异步方法。 |
191| ohos.net.socket.UDPSocket | getState(): Promise\<[SocketStateBase](#socketstatebase)> | 获取UDPSocket状态。使用Promise方式作为异步方法。 |
192| ohos.net.socket.UDPSocket | setExtraOptions(options: [UDPExtraOptions](#udpextraoptions), callback: AsyncCallback\<void>): void | 设置UDPSocket连接的其他属性。使用callback方式作为异步方法。 |
193| ohos.net.socket.UDPSocket | setExtraOptions(options: [UDPExtraOptions](#udpextraoptions)): Promise\<void> | 设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。 |
194| ohos.net.socket.UDPSocket | on(type: 'message', callback: Callback\<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 |
195| ohos.net.socket.UDPSocket | off(type: 'message', callback?: Callback\<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 |
196| ohos.net.socket.UDPSocket | on(type: 'listening' | 'close', callback: Callback\<void>): void | 订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 |
197| ohos.net.socket.UDPSocket | off(type: 'listening' | 'close', callback?: Callback\<void>): void | 取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 |
198| ohos.net.socket.UDPSocket | on(type: 'error', callback?: ErrorCallback): void | 订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 |
199| ohos.net.socket.UDPSocket | off(type: 'error', callback?: ErrorCallback): void | 取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 |
200| ohos.net.socket.TCPSocket | bind(address: [NetAddress](#netaddress), callback: AsyncCallback\<void>): void | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方法作为异步方法。 |
201| ohos.net.socket.TCPSocket | bind(address [NetAddress](#netaddress)): Promise\<void> | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方法作为异步方法。 |
202| ohos.net.socket.TCPSocket | connect(options: [TCPConnectOptions](#tcpconnectoptions), callback: AsyncCallback\<void>): void | 连接到指定的IP地址和端口。使用callback方法作为异步方法。 |
203| ohos.net.socket.TCPSocket | connect(options: [TCPConnectOptions](#tcpconnectoptions)): Promise\<void> | 连接到指定的IP地址和端口。使用Promise方法作为异步方法。 |
204| ohos.net.socket.TCPSocket | send(options: [TCPSendOptions](#tcpsendoptions), callback: AsyncCallback\<void>): void | 通过TCPSocket连接发送数据。使用callback方式作为异步方法。 |
205| ohos.net.socket.TCPSocket | send(options: [TCPSendOptions](#tcpsendoptions)): Promise\<void> | 通过TCPSocket连接发送数据。使用Promise方式作为异步方法。 |
206| ohos.net.socket.TCPSocket | close(callback: AsyncCallback\<void>): void | 关闭TCPSocket连接。使用Promise方式作为异步方法。 |
207| ohos.net.socket.TCPSocket | close(): Promise\<void> | 关闭TCPSocket连接。使用Promise方式作为异步方法。 |
208| ohos.net.socket.TCPSocket | getRemoteAddress(callback: AsyncCallback\<[NetAddress](#netaddress)>): void | 获取对端Socket地址。使用callback方式作为异步方法。 |
209| ohos.net.socket.TCPSocket | getRemoteAddress(): Promise\<[NetAddress](#netaddress)> | 获取对端Socket地址。使用Promise方式作为异步方法。 |
210| ohos.net.socket.TCPSocket | getState(callback: AsyncCallback\<[SocketStateBase](#socketstatebase)>): void | 获取TCPSocket状态。使用callback方式作为异步方法。 |
211| ohos.net.socket.TCPSocket | getState(): Promise\<[SocketStateBase](#socketstatebase)> | 获取TCPSocket状态。使用Promise方式作为异步方法。 |
212| ohos.net.socket.TCPSocket | setExtraOptions(options: [TCPExtraOptions](#tcpextraoptions), callback: AsyncCallback<void>): void | 设置TCPSocket连接的其他属性。使用callback方式作为异步方法。 |
213| ohos.net.socket.TCPSocket | setExtraOptions(options: [TCPExtraOptions](#tcpextraoptions)): Promise<void> | 设置TCPSocket连接的其他属性。使用Promise方式作为异步方法。 |
214| ohos.net.socket.TCPSocket | on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 |
215| ohos.net.socket.TCPSocket | off(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 |
216| ohos.net.socket.TCPSocket | on(type: 'connect' | 'close', callback: Callback<void>): void | 订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 |
217| ohos.net.socket.TCPSocket | off(type: 'connect' | 'close', callback: Callback<void>): void | 取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 |
218| ohos.net.socket.TCPSocket | on(type: 'error', callback?: ErrorCallback): void | 订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 |
219| ohos.net.socket.TCPSocket | off(type: 'error', callback?: ErrorCallback): void | 取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 |
220| ohos.net.socket.TLSSocket | connect(options: [TLSConnectOptions](#tlsconnectoptions), callback: AsyncCallback\<void>): void | 在TLSSocket上进行通信连接，并创建和初始化TLS会话，实现建立连接过程，启动与服务器的TLS/SSL握手，实现数据传输功能，使用callback方式作为异步方法。 |
221| ohos.net.socket.TLSSocket | connect(options: [TLSConnectOptions](#tlsconnectoptions)): Promise\<void> | 在TLSSocket上进行通信连接，并创建和初始化TLS会话，实现建立连接过程，启动与服务器的TLS/SSL握手，实现数据传输功能，使用Promise方式作为异步方法。 |
222| ohos.net.socket.TLSSocket | getCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata)>): void | 在TLSSocket通信连接之后，获取本地的数字证书，使用callback方式作为异步方法。 |
223| ohos.net.socket.TLSSocket | getCertificate():Promise\<[X509CertRawData](#x509certrawdata)> | 在TLSSocket通信连接之后，获取本地的数字证书，使用Promise方式作为异步方法。 |
224| ohos.net.socket.TLSSocket | getRemoteCertificate(callback: AsyncCallback\<[X509CertRawData](#x509certrawdata)>): void | 在TLSSocket通信连接之后，获取对等方的数字证书，使用callback方式作为异步方法。 |
225| ohos.net.socket.TLSSocket | getRemoteCertificate(): Promise\<[X509CertRawData](#x509certrawdata)> | 在TLSSocket通信连接之后，获取对等方的数字证书，使用Promise方式作为异步方法。 |
226| ohos.net.socket.TLSSocket | getProtocol(callback: AsyncCallback\<string>): void | 在TLSSocket通信连接之后，获取通信的协议，使用callback方式作为异步方法。 |
227| ohos.net.socket.TLSSocket | getProtocol(): Promise\<string> | 在TLSSocket通信连接之后，获取通信的协议，使用Promise方式作为异步方法。 |
228| ohos.net.socket.TLSSocket | getCipherSuite(callback: AsyncCallback\<Array\<string>>): void | 在TLSSocket通信连接之后，获取通信双方支持的加密套件，使用callback方式作为异步方法。 |
229| ohos.net.socket.TLSSocket | getCipherSuite(): Promise\<Array\<string>> | 在TLSSocket通信连接之后，获取通信双方支持的加密套件，使用Promise方式作为异步方法。 |
230| ohos.net.socket.TLSSocket | getSignatureAlgorithms(callback: AsyncCallback\<Array\<string>>): void | 在TLSSocket通信连接之后，获取通信双方支持的签名算法，使用callback方式作为异步方法。 |
231| ohos.net.socket.TLSSocket | getSignatureAlgorithms(): Promise\<Array\<string>> | 在TLSSocket通信连接之后，获取通信双方支持的签名算法，使用Promise方式作为异步方法。 |
232| ohos.net.socket.TLSSocket | send(data: string, callback: AsyncCallback\<void>): void | 在TLSSocket通信连接之后，向服务端发送消息，使用callback方式作为异步方法。 |
233| ohos.net.socket.TLSSocket | send(data: string): Promise\<void> | 在TLSSocket通信连接之后，向服务端发送消息，使用Promise方式作为异步方法。 |
234
235#### NetAddress
236
237目标地址信息。
238
239| 参数名 | 类型 | 必填 | 说明 |
240| ------- | ------ | ---- | ------------------------------------------------------------ |
241| address | string | 是 | 本地绑定的ip地址。 |
242| port | number | 否 | 端口号 ，范围0~65535。如果不指定系统随机分配端口。 |
243| family | number | 否 | 网络协议类型，可选类型：<br />- 1：IPv4<br />- 2：IPv6<br />默认为1。 |
244
245#### UDPSendOptions
246
247UDPSocket发送参数。
248
249| 参数名 | 类型 | 必填 | 说明 |
250| ------- | ---------------------------------- | ---- | -------------- |
251| data | string | 是 | 发送的数据。 |
252| address | [NetAddress](#netaddress) | 是 | 目标地址信息。 |
253
254#### UDPExtraOptions
255
256UDPSocket连接的其他属性。
257
258| 参数名 | 类型 | 必填 | 说明 |
259| ----------------- | ------- | ---- | -------------------------------- |
260| broadcast | boolean | 否 | 是否可以发送广播。默认为false。 |
261| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 |
262| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 |
263| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 |
264| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 |
265
266#### SocketStateBase
267
268Socket的状态信息。
269
270| 参数名 | 类型 | 必填 | 说明 |
271| ----------- | ------- | ---- | ---------- |
272| isBound | boolean | 是 | 是否绑定。 |
273| isClose | boolean | 是 | 是否关闭。 |
274| isConnected | boolean | 是 | 是否连接。 |
275
276#### SocketRemoteInfo
277
278Socket的连接信息。
279
280| 参数名 | 类型 | 必填 | 说明 |
281| ------- | ------ | ---- | ------------------------------------------------------------ |
282| address | string | 是 | 本地绑定的ip地址。 |
283| family | string | 是 | 网络协议类型，可选类型：<br />- IPv4<br />- IPv6<br />默认为IPv4。 |
284| port | number | 是 | 端口号，范围0~65535。 |
285| size | number | 是 | 服务器响应信息的字节长度。 |
286
287#### TCPConnectOptions
288
289TCPSocket连接的参数。
290
291| 参数名 | 类型 | 必填 | 说明 |
292| ------- | ---------------------------------- | ---- | -------------------------- |
293| address | [NetAddress](#netaddress) | 是 | 绑定的地址以及端口。 |
294| timeout | number | 否 | 超时时间，单位毫秒（ms）。 |
295
296#### TCPSendOptions
297
298TCPSocket发送请求的参数。
299
300| 参数名 | 类型 | 必填 | 说明 |
301| -------- | ------ | ---- | ------------------------------------------------------------ |
302| data | string | 是 | 发送的数据。 |
303| encoding | string | 否 | 字符编码(UTF-8，UTF-16BE，UTF-16LE，UTF-16，US-AECII，ISO-8859-1)，默认为UTF-8。 |
304
305#### TCPExtraOptions
306
307TCPSocket连接的其他属性。
308
309| 参数名 | 类型 | 必填 | 说明 |
310| ----------------- | ------- | ---- | ------------------------------------------------------------ |
311| keepAlive | boolean | 否 | 是否保持连接。默认为false。 |
312| OOBInline | boolean | 否 | 是否为OOB内联。默认为false。 |
313| TCPNoDelay | boolean | 否 | TCPSocket连接是否无时延。默认为false。 |
314| socketLinger | Object | 是 | socket是否继续逗留。<br />- on：是否逗留（true：逗留；false：不逗留）。<br />- linger：逗留时长，单位毫秒（ms），取值范围为0~65535。<br />当入参on设置为true时，才需要设置。 |
315| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 |
316| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 |
317| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 |
318| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 |
319
320#### TLSConnectOptions
321
322TLS连接的操作。
323
324| 参数名 | 类型 | 说明 |
325| -------------- | ------------------------------------- | -------------- |
326| address | [NetAddress](#netaddress) | 网关地址。 |
327| secureOptions | [TLSSecureOptions](#tlssecureoptions) | TLS安全相关操作。|
328| ALPNProtocols | Array\<string> | ALPN协议。 |
329
330#### TLSSecureOptions
331
332TLS安全相关操作。
333
334| 参数名 | 类型 | 说明 |
335| --------------------- | ---------------------- | ---------------------- |
336| ca | string \| Array\<string> | ca证书。 |
337| cert | string | 本地数字证书。 |
338| key | string | 本地数字证书私钥。 |
339| passwd | string | 密码。 |
340| protocols | [Protocol](#protocol) \| Array\<[Protocol](#protocol)>;| 协议名。 |
341| useRemoteCipherPrefer | boolean | 优先使用对等方的密码套件。 |
342| signatureAlgorithms | string | 设置签名算法。 |
343| cipherSuite | string | 加密套件。 |
344
345#### X509CertRawData
346
347| 参数名 | 类型 | 说明 |
348| -------------- | ----------------------------- | -------------- |
349| data | Uint8Array | 证书内容。 |
350| encodingFormat | number | 编码格式pem。 |
351
352#### Protocol
353
354TLS通信的协议。
355
356| **protocol 的合法值** | 说明 |
357| :------------------ | :------------------ |
358| TLSv12 | 使用TLSv1.2协议通信。 |
359| TLSv13 | 使用TLSv1.3协议通信。 |
360
361#### 示例
362
363```javascript
364import socket from "@ohos.net.socket"
365let tcp = socket.constructTCPSocketInstance()
366tcp.on("message", function (data) {
367 console.log(JSON.stringify(data))
368})
369tcp.bind({
370 address: "127.0.0.1",
371 family: 1,
372 port: 0
373})
374tcp.connect({
375 address: {
376 address: "127.0.0.1",
377 family: 1,
378 port: 8888
379 }
380})
381tcp.send({
382 data: "Hello World"
383})
384
385let udp = socket.constructUDPSocketInstance()
386udp.bind({
387 address: "127.0.0.1",
388 family: 1,
389 port: 0
390})
391udp.send({
392 address: {
393 address: "127.0.0.1",
394 family: 1,
395 port: 9999
396 },
397 data: "Hello World"
398})
399
400let tls = socket.constructTLSSocketInstance();
401let Protocol = socket.Protocol;
402let options = {
403 ALPNProtocols: ["spdy/1", "http/1.1"],
404 address: {
405 address: "xxxx",
406 port: "xxxx",
407 family: 1,
408 },
409 secureOptions: {
410 key: "xxxx",
411 cert: "xxxx",
412 ca: ["xxxx"],
413 passwd: "123456",
414 protocols: [Protocol.TLSv12],
415 useRemoteCipherPrefer: true,
416 signatureAlgorithms: rsa_pss_rsae_sha256:ECDSA+SHA25,
417 cipherSuite: AES256-SHA256,
418 },
419};
420tls.connect(options).then(data => {
421 console.info(data);
422}).catch(err => {
423 console.error(err);
424});
425tls.getProtocol((err, data) => {
426 if (err) {
427 console.log("getProtocol callback error = " + err);
428 } else {
429 console.log("getProtocol callback = " + data);
430 }
431});
432let data = "Hello Word";
433tls.send(data, (err, data) => {
434 if (err) {
435 console.log("send callback error = " + err);
436 } else {
437 console.log("send callback = " + data);
438 }
439});
440```
441
442## 相关仓
443
444[网络管理子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E7%BD%91%E7%BB%9C%E7%AE%A1%E7%90%86%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
445
446**communication_netstack**
447
448[communication_netmanager_base](https://gitee.com/openharmony/communication_netmanager_base)
449
450[communication_netmanager_ext](https://gitee.com/openharmony/communication_netmanager_ext)
451
