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 # API实现 23│ └─js # JS API实现 24│ ├─builtin # 小型系统JS API实现 25│ └─napi # 标准系统JS API实现 26│ ├─http # http API 27│ ├─socket # socket API 28│ └─websocket # websocket API 29├─interfaces # JS 接口定义 30├─test # 测试 31└─utils # 工具 32``` 33 34## 接口说明 35 36### Http接口说明 37 38| 类型 | 接口 | 功能说明 | 39| ---- | ---- | ---- | 40| ohos.net.socket | function createHttp(): HttpRequest | 返回一个HttpRequest对象 | 41| ohos.net.http.HttpRequest | on(type: "headerReceive", callback: AsyncCallback\<Object>): void | 监听收到Http头的事件 | 42| ohos.net.http.HttpRequest | once(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件，只监听一次 | 43| ohos.net.http.HttpRequest | off(type: "headerReceive", callback: AsyncCallback\<Object>): void | 取消监听收到Http头的事件 | 44| ohos.net.http.HttpRequest | on(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件 | 45| ohos.net.http.HttpRequest | once(type: "headerReceive", callback: Callback\<Object>): void | 监听收到Http头的事件，只监听一次 | 46| ohos.net.http.HttpRequest | off(type: "headerReceive", callback: Callback\<Object>): void | 取消监听收到Http头的事件 | 47| ohos.net.http.HttpRequest | request(url: string, callback: AsyncCallback\<[HttpResponse](#httpresponse)>): void | 用**GET**方法请求一个域名，调用callback | 48| ohos.net.http.HttpRequest | request(url: string, options: [HttpRequestOptions](#httprequestoptions), callback: AsyncCallback\<[HttpResponse](#httpresponse)>): void | 请求一个域名，options中携带请求参数，调用callback | 49| ohos.net.http.HttpRequest | request(url: string, options?: [HttpRequestOptions](#httprequestoptions): Promise\<[HttpResponse](#httpresponse)> | 请求一个域名，options中携带请求参数(可选)，返回Promise | 50 51#### HttpRequestOptions 52 53发起请求可选参数的类型和取值范围。 54 55| 参数 | 类型 | 必填 | 说明 | 56| -------------- | ------------------------------------ | ---- | ---------------------------------------------------------- | 57| method | [RequestMethod](#requestmethod) | 否 | 请求方式。 | 58| extraData | string | Object | ArrayBuffer<sup>8+</sup> | 否 | 发送请求的额外数据。<br />- 当HTTP请求为POST、PUT等方法时，此字段为HTTP请求的content，支持类型为string和ArrayBuffer<sup>8+</sup>。<br />- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时，此字段为HTTP请求的参数补充，参数内容会拼接到URL中进行发送，支持类型为string和Object。<br />- 开发者传入string对象，开发者需要自行编码，将编码后的string传入。<sup>8+</sup> | 59| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 | 60| readTimeout | number | 否 | 读取超时时间。单位为毫秒（ms），默认为60000ms。 | 61| connectTimeout | number | 否 | 连接超时时间。单位为毫秒（ms），默认为60000ms。 | 62 63#### RequestMethod 64 65HTTP 请求方法。 66 67| **method 的合法值** | 说明 | 68| :------------------ | :------------------ | 69| OPTIONS | HTTP 请求 OPTIONS。 | 70| GET | HTTP 请求 GET。 | 71| HEAD | HTTP 请求 HEAD。 | 72| POST | HTTP 请求 POST。 | 73| PUT | HTTP 请求 PUT。 | 74| DELETE | HTTP 请求 DELETE。 | 75| TRACE | HTTP 请求 TRACE。 | 76| CONNECT | HTTP 请求 CONNECT。 | 77 78#### ResponseCode 79 80发起请求返回的响应码。 81 82| 变量 | 值 | 说明 | 83| ----------------- | ---- | ------------------------------------------------------------ | 84| OK | 200 | 请求成功。一般用于GET与POST请求。 | 85| CREATED | 201 | 已创建。成功请求并创建了新的资源。 | 86| ACCEPTED | 202 | 已接受。已经接受请求，但未处理完成。 | 87| NOT_AUTHORITATIVE | 203 | 非授权信息。请求成功。 | 88| NO_CONTENT | 204 | 无内容。服务器成功处理，但未返回内容。 | 89| RESET | 205 | 重置内容。 | 90| PARTIAL | 206 | 部分内容。服务器成功处理了部分GET请求。 | 91| MULT_CHOICE | 300 | 多种选择。 | 92| MOVED_PERM | 301 | 永久移动。请求的资源已被永久的移动到新URI，返回信息会包括新的URI，浏览器会自动定向到新URI。 | 93| MOVED_TEMP | 302 | 临时移动。 | 94| SEE_OTHER | 303 | 查看其它地址。 | 95| NOT_MODIFIED | 304 | 未修改。 | 96| USE_PROXY | 305 | 使用代理。 | 97| BAD_REQUEST | 400 | 客户端请求的语法错误，服务器无法理解。 | 98| UNAUTHORIZED | 401 | 请求要求用户的身份认证。 | 99| PAYMENT_REQUIRED | 402 | 保留，将来使用。 | 100| FORBIDDEN | 403 | 服务器理解请求客户端的请求，但是拒绝执行此请求。 | 101| NOT_FOUND | 404 | 服务器无法根据客户端的请求找到资源（网页）。 | 102| BAD_METHOD | 405 | 客户端请求中的方法被禁止。 | 103| NOT_ACCEPTABLE | 406 | 服务器无法根据客户端请求的内容特性完成请求。 | 104| PROXY_AUTH | 407 | 请求要求代理的身份认证。 | 105| CLIENT_TIMEOUT | 408 | 请求时间过长，超时。 | 106| CONFLICT | 409 | 服务器完成客户端的PUT请求是可能返回此代码，服务器处理请求时发生了冲突。 | 107| GONE | 410 | 客户端请求的资源已经不存在。 | 108| LENGTH_REQUIRED | 411 | 服务器无法处理客户端发送的不带Content-Length的请求信息。 | 109| PRECON_FAILED | 412 | 客户端请求信息的先决条件错误。 | 110| ENTITY_TOO_LARGE | 413 | 由于请求的实体过大，服务器无法处理，因此拒绝请求。 | 111| REQ_TOO_LONG | 414 | 请求的URI过长（URI通常为网址），服务器无法处理。 | 112| UNSUPPORTED_TYPE | 415 | 服务器无法处理请求的格式。 | 113| INTERNAL_ERROR | 500 | 服务器内部错误，无法完成请求。 | 114| NOT_IMPLEMENTED | 501 | 服务器不支持请求的功能，无法完成请求。 | 115| BAD_GATEWAY | 502 | 充当网关或代理的服务器，从远端服务器接收到了一个无效的请求。 | 116| UNAVAILABLE | 503 | 由于超载或系统维护，服务器暂时的无法处理客户端的请求。 | 117| GATEWAY_TIMEOUT | 504 | 充当网关或代理的服务器，未及时从远端服务器获取请求。 | 118| VERSION | 505 | 服务器请求的HTTP协议的版本。 | 119 120#### HttpResponse 121 122request方法回调函数的返回值类型。 123 124| 参数名 | 类型 | 必填 | 说明 | 125| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 126| result | string | Object |ArrayBuffer<sup>8+</sup> | 是 | Http请求根据响应头中Content-type类型返回对应的响应格式内容：<br />- application/json：返回JSON格式的字符串，如需Http响应具体内容，需开发者自行解析<br />- application/octet-stream：ArrayBuffer<br />- 其他：string | 127| responseCode | [ResponseCode](#responsecode) | number | 是 | 回调函数执行成功时，此字段为[ResponseCode](#responsecode)。若执行失败，错误码将会从AsyncCallback中的err字段返回。错误码如下：<br />- 200：通用错误<br />- 202：参数错误<br />- 300：I/O错误 | 128| 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']； | 129| cookies<sup>8+</sup> | string | 是 | 服务器返回的 cookies。 | 130 131#### 示例 132 133```javascript 134import http from "@ohos.net.http" 135let httpRequest = http.createHttp() 136httpRequest.request("www.example.com", function (err, data) { 137 console.log(JSON.stringify(err)) 138 console.log(JSON.stringify(data)) 139}) 140``` 141 142### socket接口说明 143 144| 类型 | 接口 | 功能说明 | 145| ---- | ---- | ---- | 146| ohos.net.socket | function constructUDPSocketInstance(): UDPSocket | 返回一个UDPSocket对象 | 147| ohos.net.socket | function constructUDPSocketInstance(): TCPSocket | 返回一个TCPSocket对象 | 148| ohos.net.socket.UDPSocket | bind(address: [NetAddress](#netaddress), callback: AsyncCallback\<void>): void | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方式作为异步方法。 | 149| ohos.net.socket.UDPSocket | bind(address: [NetAddress](#netaddress)): Promise\<void> | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方式作为异步方法。 | 150| ohos.net.socket.UDPSocket | send(options: [UDPSendOptions](#udpsendoptions), callback: AsyncCallback\<void>): void | 通过UDPSocket连接发送数据。使用callback方式作为异步方法。 | 151| ohos.net.socket.UDPSocket | send(options: [UDPSendOptions](#udpsendoptions)): Promise\<void> | 通过UDPSocket连接发送数据。使用Promise方式作为异步方法。 | 152| ohos.net.socket.UDPSocket | close(callback: AsyncCallback\<void>): void | 关闭UDPSocket连接。使用callback方式作为异步方法。 | 153| ohos.net.socket.UDPSocket | close(): Promise\<void> | 关闭UDPSocket连接。使用Promise方式作为异步方法。 | 154| ohos.net.socket.UDPSocket | getState(callback: AsyncCallback\<[SocketStateBase](#socketstatebase)>): void | 获取UDPSocket状态。使用callback方式作为异步方法。 | 155| ohos.net.socket.UDPSocket | getState(): Promise\<[SocketStateBase](#socketstatebase)> | 获取UDPSocket状态。使用Promise方式作为异步方法。 | 156| ohos.net.socket.UDPSocket | setExtraOptions(options: [UDPExtraOptions](#udpextraoptions), callback: AsyncCallback\<void>): void | 设置UDPSocket连接的其他属性。使用callback方式作为异步方法。 | 157| ohos.net.socket.UDPSocket | setExtraOptions(options: [UDPExtraOptions](#udpextraoptions)): Promise\<void> | 设置UDPSocket连接的其他属性。使用Promise方式作为异步方法。 | 158| ohos.net.socket.UDPSocket | on(type: 'message', callback: Callback\<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 | 159| ohos.net.socket.UDPSocket | off(type: 'message', callback?: Callback\<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 取消订阅UDPSocket连接的接收消息事件。使用callback方式作为异步方法。 | 160| ohos.net.socket.UDPSocket | on(type: 'listening' | 'close', callback: Callback\<void>): void | 订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 | 161| ohos.net.socket.UDPSocket | off(type: 'listening' | 'close', callback?: Callback\<void>): void | 取消订阅UDPSocket连接的数据包消息事件或关闭事件。使用callback方式作为异步方法。 | 162| ohos.net.socket.UDPSocket | on(type: 'error', callback?: ErrorCallback): void | 订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 | 163| ohos.net.socket.UDPSocket | off(type: 'error', callback?: ErrorCallback): void | 取消订阅UDPSocket连接的error事件。使用callback方式作为异步方法。 | 164| ohos.net.socket.TCPSocket | bind(address: [NetAddress](#netaddress), callback: AsyncCallback\<void>): void | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用callback方法作为异步方法。 | 165| ohos.net.socket.TCPSocket | bind(address [NetAddress](#netaddress)): Promise\<void> | 绑定IP地址和端口，端口可以指定或由系统随机分配。使用Promise方法作为异步方法。 | 166| ohos.net.socket.TCPSocket | connect(options: [TCPConnectOptions](#tcpconnectoptions), callback: AsyncCallback\<void>): void | 连接到指定的IP地址和端口。使用callback方法作为异步方法。 | 167| ohos.net.socket.TCPSocket | connect(options: [TCPConnectOptions](#tcpconnectoptions)): Promise\<void> | 连接到指定的IP地址和端口。使用Promise方法作为异步方法。 | 168| ohos.net.socket.TCPSocket | send(options: [TCPSendOptions](#tcpsendoptions), callback: AsyncCallback\<void>): void | 通过TCPSocket连接发送数据。使用callback方式作为异步方法。 | 169| ohos.net.socket.TCPSocket | send(options: [TCPSendOptions](#tcpsendoptions)): Promise\<void> | 通过TCPSocket连接发送数据。使用Promise方式作为异步方法。 | 170| ohos.net.socket.TCPSocket | close(callback: AsyncCallback\<void>): void | 关闭TCPSocket连接。使用Promise方式作为异步方法。 | 171| ohos.net.socket.TCPSocket | close(): Promise\<void> | 关闭TCPSocket连接。使用Promise方式作为异步方法。 | 172| ohos.net.socket.TCPSocket | getRemoteAddress(callback: AsyncCallback\<[NetAddress](#netaddress)>): void | 获取对端Socket地址。使用callback方式作为异步方法。 | 173| ohos.net.socket.TCPSocket | getRemoteAddress(): Promise\<[NetAddress](#netaddress)> | 获取对端Socket地址。使用Promise方式作为异步方法。 | 174| ohos.net.socket.TCPSocket | getState(callback: AsyncCallback\<[SocketStateBase](#socketstatebase)>): void | 获取TCPSocket状态。使用callback方式作为异步方法。 | 175| ohos.net.socket.TCPSocket | getState(): Promise\<[SocketStateBase](#socketstatebase)> | 获取TCPSocket状态。使用Promise方式作为异步方法。 | 176| ohos.net.socket.TCPSocket | setExtraOptions(options: [TCPExtraOptions](#tcpextraoptions), callback: AsyncCallback<void>): void | 设置TCPSocket连接的其他属性。使用callback方式作为异步方法。 | 177| ohos.net.socket.TCPSocket | setExtraOptions(options: [TCPExtraOptions](#tcpextraoptions)): Promise<void> | 设置TCPSocket连接的其他属性。使用Promise方式作为异步方法。 | 178| ohos.net.socket.TCPSocket | on(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 | 179| ohos.net.socket.TCPSocket | off(type: 'message', callback: Callback<{message: ArrayBuffer, remoteInfo: [SocketRemoteInfo](#socketremoteinfo)}>): void | 取消订阅TCPSocket连接的接收消息事件。使用callback方式作为异步方法。 | 180| ohos.net.socket.TCPSocket | on(type: 'connect' | 'close', callback: Callback<void>): void | 订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 | 181| ohos.net.socket.TCPSocket | off(type: 'connect' | 'close', callback: Callback<void>): void | 取消订阅TCPSocket的连接事件或关闭事件。使用callback方式作为异步方法。 | 182| ohos.net.socket.TCPSocket | on(type: 'error', callback?: ErrorCallback): void | 订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 | 183| ohos.net.socket.TCPSocket | off(type: 'error', callback?: ErrorCallback): void | 取消订阅TCPSocket连接的error事件。使用callback方式作为异步方法。 | 184 185 186#### NetAddress 187 188目标地址信息。 189 190| 参数名 | 类型 | 必填 | 说明 | 191| ------- | ------ | ---- | ------------------------------------------------------------ | 192| address | string | 是 | 本地绑定的ip地址。 | 193| port | number | 否 | 端口号 ，范围0~65535。如果不指定系统随机分配端口。 | 194| family | number | 否 | 网络协议类型，可选类型：<br />- 1：IPv4<br />- 2：IPv6<br />默认为1。 | 195 196#### UDPSendOptions 197 198UDPSocket发送参数。 199 200| 参数名 | 类型 | 必填 | 说明 | 201| ------- | ---------------------------------- | ---- | -------------- | 202| data | string | 是 | 发送的数据。 | 203| address | [NetAddress](#netaddress) | 是 | 目标地址信息。 | 204 205#### UDPExtraOptions 206 207UDPSocket连接的其他属性。 208 209| 参数名 | 类型 | 必填 | 说明 | 210| ----------------- | ------- | ---- | -------------------------------- | 211| broadcast | boolean | 否 | 是否可以发送广播。默认为false。 | 212| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | 213| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | 214| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | 215| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | 216 217#### SocketStateBase 218 219Socket的状态信息。 220 221| 参数名 | 类型 | 必填 | 说明 | 222| ----------- | ------- | ---- | ---------- | 223| isBound | boolean | 是 | 是否绑定。 | 224| isClose | boolean | 是 | 是否关闭。 | 225| isConnected | boolean | 是 | 是否连接。 | 226 227#### SocketRemoteInfo 228 229Socket的连接信息。 230 231| 参数名 | 类型 | 必填 | 说明 | 232| ------- | ------ | ---- | ------------------------------------------------------------ | 233| address | string | 是 | 本地绑定的ip地址。 | 234| family | string | 是 | 网络协议类型，可选类型：<br />- IPv4<br />- IPv6<br />默认为IPv4。 | 235| port | number | 是 | 端口号，范围0~65535。 | 236| size | number | 是 | 服务器响应信息的字节长度。 | 237 238#### TCPConnectOptions 239 240TCPSocket连接的参数。 241 242| 参数名 | 类型 | 必填 | 说明 | 243| ------- | ---------------------------------- | ---- | -------------------------- | 244| address | [NetAddress](#netaddress) | 是 | 绑定的地址以及端口。 | 245| timeout | number | 否 | 超时时间，单位毫秒（ms）。 | 246 247#### TCPSendOptions 248 249TCPSocket发送请求的参数。 250 251| 参数名 | 类型 | 必填 | 说明 | 252| -------- | ------ | ---- | ------------------------------------------------------------ | 253| data | string | 是 | 发送的数据。 | 254| encoding | string | 否 | 字符编码(UTF-8，UTF-16BE，UTF-16LE，UTF-16，US-AECII，ISO-8859-1)，默认为UTF-8。 | 255 256#### TCPExtraOptions 257 258TCPSocket连接的其他属性。 259 260| 参数名 | 类型 | 必填 | 说明 | 261| ----------------- | ------- | ---- | ------------------------------------------------------------ | 262| keepAlive | boolean | 否 | 是否保持连接。默认为false。 | 263| OOBInline | boolean | 否 | 是否为OOB内联。默认为false。 | 264| TCPNoDelay | boolean | 否 | TCPSocket连接是否无时延。默认为false。 | 265| socketLinger | Object | 是 | socket是否继续逗留。<br />- on：是否逗留（true：逗留；false：不逗留）。<br />- linger：逗留时长，单位毫秒（ms），取值范围为0~65535。<br />当入参on设置为true时，才需要设置。 | 266| receiveBufferSize | number | 否 | 接收缓冲区大小（单位：Byte）。 | 267| sendBufferSize | number | 否 | 发送缓冲区大小（单位：Byte）。 | 268| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 | 269| socketTimeout | number | 否 | 套接字超时时间，单位毫秒（ms）。 | 270 271#### 示例 272 273```javascript 274import socket from "@ohos.net.socket" 275let tcp = socket.constructTCPSocketInstance() 276tcp.on("message", function (data) { 277 console.log(JSON.stringify(data)) 278}) 279tcp.bind({ 280 address: "127.0.0.1", 281 family: 1, 282 port: 0 283}) 284tcp.connect({ 285 address: { 286 address: "127.0.0.1", 287 family: 1, 288 port: 8888 289 } 290}) 291tcp.send({ 292 data: "Hello World" 293}) 294 295let udp = socket.constructUDPSocketInstance() 296udp.bind({ 297 address: "127.0.0.1", 298 family: 1, 299 port: 0 300}) 301udp.send({ 302 address: { 303 address: "127.0.0.1", 304 family: 1, 305 port: 9999 306 }, 307 data: "Hello World" 308}) 309``` 310 311## 相关仓 312 313[网络管理子系统](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) 314 315**communication_netstack** 316 317[communication_netmanager_base](https://gitee.com/openharmony/communication_netmanager_base) 318 319[communication_netmanager_ext](https://gitee.com/openharmony/communication_netmanager_ext) 320
