Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
OpenHarmony
Docs
提交
9f3f9030
D
Docs
项目概览
OpenHarmony
/
Docs
1 年多 前同步成功
通知
159
Star
292
Fork
28
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
D
Docs
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
未验证
提交
9f3f9030
编写于
11月 26, 2022
作者:
O
openharmony_ci
提交者:
Gitee
11月 26, 2022
浏览文件
操作
浏览文件
下载
差异文件
!11833 修改socket和HTTP说明文档
Merge pull request !11833 from liyufan/11730
上级
7e56da01
019405c4
变更
4
隐藏空白更改
内联
并排
Showing
4 changed file
with
1233 addition
and
495 deletion
+1233
-495
zh-cn/application-dev/reference/apis/Readme-CN.md
zh-cn/application-dev/reference/apis/Readme-CN.md
+0
-1
zh-cn/application-dev/reference/apis/js-apis-http.md
zh-cn/application-dev/reference/apis/js-apis-http.md
+169
-8
zh-cn/application-dev/reference/apis/js-apis-socket.md
zh-cn/application-dev/reference/apis/js-apis-socket.md
+1064
-0
zh-cn/application-dev/reference/apis/js-apis-tlsSocket.md
zh-cn/application-dev/reference/apis/js-apis-tlsSocket.md
+0
-486
未找到文件。
zh-cn/application-dev/reference/apis/Readme-CN.md
浏览文件 @
9f3f9030
...
...
@@ -182,7 +182,6 @@
-
[
@ohos.net.http (数据请求)
](
js-apis-http.md
)
-
[
@ohos.net.sharing (网络共享管理)
](
js-apis-net-sharing.md
)
-
[
@ohos.net.socket (Socket连接)
](
js-apis-socket.md
)
-
[
@ohos.net.tlsSocket (TLSSocket连接)
](
js-apis-tlsSocket.md
)
-
[
@ohos.net.webSocket (WebSocket连接)
](
js-apis-webSocket.md
)
-
[
@ohos.request (上传下载)
](
js-apis-request.md
)
...
...
zh-cn/application-dev/reference/apis/js-apis-http.md
浏览文件 @
9f3f9030
...
...
@@ -2,7 +2,7 @@
本模块提供HTTP数据请求能力。应用可以通过HTTP发起一个数据请求,支持常见的GET、POST、OPTIONS、HEAD、PUT、DELETE、TRACE、CONNECT方法。
>**说明:**
>**说明:**
>
>本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
>
...
...
@@ -38,8 +38,12 @@ httpRequest.request(
extraData
:
{
"
data
"
:
"
data to send
"
,
},
expectDataType
:
http
.
HttpDataType
.
STRING
,
// 可选,指定返回数据的类型
usingCache
:
true
,
// 可选,默认为true
priority
:
1
,
// 可选,默认为1
connectTimeout
:
60000
,
// 可选,默认为60000ms
readTimeout
:
60000
,
// 可选,默认为60000ms
usingProtocol
:
http
.
HttpProtocol
.
HTTP1_1
,
// 可选,协议类型默认值由系统自动指定
},
(
err
,
data
)
=>
{
if
(
!
err
)
{
// data.result为HTTP响应内容,可根据业务需要进行解析
...
...
@@ -78,7 +82,6 @@ import http from '@ohos.net.http';
let
httpRequest
=
http
.
createHttp
();
```
## HttpRequest
HTTP请求任务。在调用HttpRequest的方法前,需要先通过
[
createHttp\(\)
](
#httpcreatehttp
)
创建一个任务。
...
...
@@ -158,7 +161,6 @@ httpRequest.request("EXAMPLE_URL",
});
```
### request
request
\(
url: string, options? : HttpRequestOptions
\)
: Promise<HttpResponse
\>
...
...
@@ -226,7 +228,7 @@ on\(type: 'headerReceive', callback: AsyncCallback<Object\>\): void
订阅HTTP Response Header 事件。
>![](public_sys-resources/icon-note.gif) **说明:**
>![](public_sys-resources/icon-note.gif) **说明:**
>此接口已废弃,建议使用[on\('headersReceive'\)<sup>8+</sup>](#onheadersreceive8)替代。
**系统能力**
:SystemCapability.Communication.NetStack
...
...
@@ -250,14 +252,13 @@ httpRequest.on('headerReceive', (err, data) => {
});
```
### off\('headerReceive'\)
off
\(
type: 'headerReceive', callback?: AsyncCallback<Object
\>\)
: void
取消订阅HTTP Response Header 事件。
>![](public_sys-resources/icon-note.gif) **说明:**
>![](public_sys-resources/icon-note.gif) **说明:**
>
>1. 此接口已废弃,建议使用[off\('headersReceive'\)<sup>8+</sup>](#offheadersreceive8)替代。
>
...
...
@@ -301,14 +302,13 @@ httpRequest.on('headersReceive', (header) => {
});
```
### off\('headersReceive'\)<sup>8+</sup>
off
\(
type: 'headersReceive', callback?: Callback<Object
\>\)
: void
取消订阅HTTP Response Header 事件。
>![](public_sys-resources/icon-note.gif) **说明:**
>![](public_sys-resources/icon-note.gif) **说明:**
>可以指定传入on中的callback取消一个订阅,也可以不指定callback清空所有订阅。
**系统能力**
:SystemCapability.Communication.NetStack
...
...
@@ -359,9 +359,13 @@ httpRequest.once('headersReceive', (header) => {
| -------------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| method |
[
RequestMethod
](
#requestmethod
)
| 否 | 请求方式。 |
| extraData | string
\|
Object
\|
ArrayBuffer
<sup>
6+
</sup>
| 否 | 发送请求的额外数据。
<br
/>
- 当HTTP请求为POST、PUT等方法时,此字段为HTTP请求的content。
<br
/>
- 当HTTP请求为GET、OPTIONS、DELETE、TRACE、CONNECT等方法时,此字段为HTTP请求的参数补充,参数内容会拼接到URL中进行发送。
<sup>
6+
</sup><br
/>
- 开发者传入string对象,开发者需要自行编码,将编码后的string传入。
<sup>
6+
</sup>
|
| expectDataType
<sup>
9+
</sup>
|
[
HttpDataType
](
#httpdatatype9
)
| 否 | 指定返回数据的类型。如果设置了此参数,系统将优先返回指定的类型。 |
| usingCache
<sup>
9+
</sup>
| boolean | 否 | 是否使用缓存,默认为true。 |
| priority
<sup>
9+
</sup>
| number | 否 | 优先级,范围
\[
1,1000],默认是1。 |
| header | Object | 否 | HTTP请求头字段。默认{'Content-Type': 'application/json'}。 |
| readTimeout | number | 否 | 读取超时时间。单位为毫秒(ms),默认为60000ms。 |
| connectTimeout | number | 否 | 连接超时时间。单位为毫秒(ms),默认为60000ms。 |
| usingProtocol
<sup>
9+
</sup>
|
[
HttpProtocol
](
#httpprotocol9
)
| 否 | 使用协议。默认值由系统自动指定。 |
## RequestMethod
...
...
@@ -433,10 +437,149 @@ request方法回调函数的返回值类型。
| 参数名 | 类型 | 必填 | 说明 |
| -------------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| result | string
\|
Object
\|
ArrayBuffer
<sup>
6+
</sup>
| 是 | HTTP请求根据响应头中Content-type类型返回对应的响应格式内容:
<br
/>
- application/json:返回JSON格式的字符串,如需HTTP响应具体内容,需开发者自行解析
<br
/>
- application/octet-stream:ArrayBuffer
<br
/>
- 其他:string |
| resultType
<sup>
9+
</sup>
|
[
HttpDataType
](
#httpdatatype9
)
| 是 | 返回值类型。 |
| responseCode |
[
ResponseCode
](
#responsecode
)
\|
number | 是 | 回调函数执行成功时,此字段为
[
ResponseCode
](
#responsecode
)
。若执行失败,错误码将会从AsyncCallback中的err字段返回。错误码参考
[
Response错误码
](
#response常用错误码
)
。 |
| 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']; |
| cookies
<sup>
8+
</sup>
| Array
\<
string
\>
| 是 | 服务器返回的 cookies。 |
## http.createHttpResponseCache<sup>9+</sup>
createHttpResponseCache(cacheSize?: number): HttpResponseCache
创建一个默认的对象来存储HTTP访问请求的响应。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------- | ---- | ---------- |
| cacheSize | number | 否 | 缓存大小最大为10
\*
1024
\*
1024(10MB),默认最大。 |
**返回值:**
| 类型 | 说明 |
| :---------- | :----------------------------------------------------------- |
|
[
HttpResponseCache
](
#httpresponsecache9
)
| 返回一个存储HTTP访问请求响应的对象。 |
**示例:**
```
js
import
http
from
'
@ohos.net.http
'
;
let
httpResponseCache
=
http
.
createHttpResponseCache
();
```
## HttpResponseCache<sup>9+</sup>
存储HTTP访问请求响应的对象。
### flush<sup>9+</sup>
flush(callback: AsyncCallback
\<
void>): void
将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------- | ---- | ---------- |
| callback | AsyncCallback
\<
void> | 是 | 回调函数返回写入结果。 |
**示例:**
```
js
import
http
from
'
@ohos.net.http
'
;
let
httpResponseCache
=
http
.
createHttpResponseCache
();
httpResponseCache
.
flush
(
err
=>
{
if
(
err
)
{
console
.
log
(
'
flush fail
'
);
return
;
}
console
.
log
(
'
flush success
'
);
});
```
### flush<sup>9+</sup>
flush(): Promise
\<
void>
将缓存中的数据写入文件系统,以便在下一个HTTP请求中访问所有缓存数据,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 类型 | 说明 |
| --------------------------------- | ------------------------------------- |
| Promise
\<
void>> | 以Promise形式返回写入结果。 |
**示例:**
```
js
import
http
from
'
@ohos.net.http
'
;
let
httpResponseCache
=
http
.
createHttpResponseCache
();
http
.
flush
().
then
(()
=>
{
console
.
log
(
'
flush success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
flush fail
'
);
});
```
### delete<sup>9+</sup>
delete(callback: AsyncCallback
\<
void>): void
禁用缓存并删除其中的数据,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------- | ---- | ---------- |
| callback | AsyncCallback
\<
void> | 是 | 回调函数返回删除结果。|
**示例:**
```
js
import
http
from
'
@ohos.net.http
'
;
let
httpResponseCache
=
http
.
createHttpResponseCache
();
httpResponseCache
.
delete
(
err
=>
{
if
(
err
)
{
console
.
log
(
'
delete fail
'
);
return
;
}
console
.
log
(
'
delete success
'
);
});
```
### delete<sup>9+</sup>
delete(): Promise
\<
void>
禁用缓存并删除其中的数据,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 类型 | 说明 |
| --------------------------------- | ------------------------------------- |
| Promise
\<
void> | 以Promise形式返回删除结果。 |
**示例:**
```
js
import
http
from
'
@ohos.net.http
'
;
let
httpResponseCache
=
http
.
createHttpResponseCache
();
httpResponseCache
.
delete
().
then
()
=>
{
console
.
log
(
'
delete success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
delete fail
'
);
});
```
## Response常用错误码
| 错误码 | 说明 |
...
...
@@ -448,3 +591,21 @@ request方法回调函数的返回值类型。
| 6 | 无法解析主机。 |
| 7 | 无法连接代理或主机。 |
## HttpDataType<sup>9+</sup>
http的数据类型。
|
**HttpDataType 的合法值**
| 说明 |
| :------------------ | :----------- |
| STRING | 字符串类型。 |
| OBJECT | 对象类型。 |
| ARRAY_BUFFER | 二进制数组类型。|
## HttpProtocol<sup>9+</sup>
http协议版本。
|
**HttpProtocol 的合法值**
| 说明 |
| :----------------- | :----------- |
| HTTP1_1 | 协议http1.1 |
| HTTP2 | 协议http2 |
zh-cn/application-dev/reference/apis/js-apis-socket.md
浏览文件 @
9f3f9030
...
...
@@ -1453,3 +1453,1067 @@ TCPSocket连接的其他属性。
| sendBufferSize | number | 否 | 发送缓冲区大小(单位:Byte)。 |
| reuseAddress | boolean | 否 | 是否重用地址。默认为false。 |
| socketTimeout | number | 否 | 套接字超时时间,单位毫秒(ms)。 |
## socket.constructTLSSocketInstance<sup>9+</sup>
constructTLSSocketInstance(): TLSSocket
创建并返回一个TLSSocket对象。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| :--------------------------------- | :---------------------- |
|
[
TLSSocket
](
#tlssocket9
)
| 返回一个TLSSocket对象。 |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
```
## TLSSocket<sup>9+</sup>
TLSSocket连接。在调用TLSSocket的方法前,需要先通过
[
socket.constructTLSSocketInstance
](
#socketconstructtlssocketinstance9
)
创建TLSSocket对象。
### bind<sup>9+</sup>
bind
\(
address: NetAddress, callback: AsyncCallback<void
\>\)
: void
绑定IP地址和端口。使用callback方法作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------------------- | ---- | ------------------------------------------------------ |
| address |
[
NetAddress
](
#netaddress
)
| 是 | 目标地址信息,参考
[
NetAddress
](
#netaddress
)
。 |
| callback | AsyncCallback
\<
void
\>
| 是 | 回调函数。成功返回TLSSocket绑定本机的IP地址和端口的结果。 失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 201 | Permission denied. |
| 2303198 | Address already in use. |
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
```
### bind<sup>9+</sup>
bind
\(
address: NetAddress
\)
: Promise<void
\>
绑定IP地址和端口。使用Promise方法作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ---------------------------------- | ---- | ------------------------------------------------------ |
| address |
[
NetAddress
](
#netaddress
)
| 是 | 目标地址信息,参考
[
NetAddress
](
#netaddress
)
。 |
**返回值:**
| 类型 | 说明 |
| :-------------- | :------------------------------------------------------- |
| Promise
\<
void
\>
| 以Promise形式返回TLSSocket绑定本机的IP地址和端口的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 201 | Permission denied. |
| 2303198 | Address already in use. |
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
let
promise
=
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
});
promise
.
then
(()
=>
{
console
.
log
(
'
bind success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
bind fail
'
);
});
```
### getState<sup>9+</sup>
getState
\(
callback: AsyncCallback<SocketStateBase
\>\)
: void
在TLSSocket的bind成功之后,获取TLSSocket状态。使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------ | ---- | ---------- |
| callback | AsyncCallback
\<
[
SocketStateBase
](
#socketstatebase
)
> | 是 | 回调函数。成功返回TLSSocket状态,失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
let
promise
=
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
tls
.
getState
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
'
getState fail
'
);
return
;
}
console
.
log
(
'
getState success:
'
+
JSON
.
stringify
(
data
));
});
```
### getState<sup>9+</sup>
getState
\(\)
: Promise<SocketStateBase
\>
在TLSSocket的bind成功之后,获取TLSSocket状态。使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| :----------------------------------------------- | :----------------------------------------- |
| Promise
\<
[
SocketStateBase
](
#socketstatebase
)
> | 以Promise形式返回获取TLSSocket状态的结果。失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
let
promise
=
tls
.
getState
();
promise
.
then
(()
=>
{
console
.
log
(
'
getState success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
getState fail
'
);
});
```
### setExtraOptions<sup>9+</sup>
setExtraOptions
\(
options: TCPExtraOptions, callback: AsyncCallback<void
\>\)
: void
在TLSSocket的bind成功之后,设置TCPSocket连接的其他属性。使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| options |
[
TCPExtraOptions
](
#tcpextraoptions
)
| 是 | TCPSocket连接的其他属性,参考
[
TCPExtraOptions
](
#tcpextraoptions
)
。 |
| callback | AsyncCallback
\<
void
\>
| 是 | 回调函数。成功返回设置TCPSocket连接的其他属性的结果,失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
tls
.
setExtraOptions
({
keepAlive
:
true
,
OOBInline
:
true
,
TCPNoDelay
:
true
,
socketLinger
:
{
on
:
true
,
linger
:
10
},
receiveBufferSize
:
1000
,
sendBufferSize
:
1000
,
reuseAddress
:
true
,
socketTimeout
:
3000
,
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
setExtraOptions fail
'
);
return
;
}
console
.
log
(
'
setExtraOptions success
'
);
});
```
### setExtraOptions<sup>9+</sup>
setExtraOptions
\(
options: TCPExtraOptions
\)
: Promise<void
\>
在TLSSocket的bind成功之后,设置TCPSocket连接的其他属性,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| options |
[
TCPExtraOptions
](
#tcpextraoptions
)
| 是 | TCPSocket连接的其他属性,参考
[
TCPExtraOptions
](
#tcpextraoptions
)
。 |
**返回值:**
| 类型 | 说明 |
| :-------------- | :--------------------------------------------------- |
| Promise
\<
void
\>
| 以Promise形式返回设置TCPSocket连接的其他属性的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
tls
.
bind
({
address
:
'
192.168.xx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
let
promise
=
tls
.
setExtraOptions
({
keepAlive
:
true
,
OOBInline
:
true
,
TCPNoDelay
:
true
,
socketLinger
:
{
on
:
true
,
linger
:
10
},
receiveBufferSize
:
1000
,
sendBufferSize
:
1000
,
reuseAddress
:
true
,
socketTimeout
:
3000
,
});
promise
.
then
(()
=>
{
console
.
log
(
'
setExtraOptions success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
setExtraOptions fail
'
);
});
```
### connect<sup>9+</sup>
connect(options: TLSConnectOptions, callback: AsyncCallback
\<
void>): void
在TLSSocket上bind成功之后,进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------------------------| ----| --------------- |
| options |
[
TLSConnectOptions
](
#tlsconnectoptions9
)
| 是 | TLSSocket连接所需要的参数。|
| callback | AsyncCallback
\<
void> | 是 | 回调函数,成功无返回,失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303104 | Interrupted system call. |
| 2303109 | Bad file number. |
| 2303111 | Resource temporarily unavailable try again. |
| 2303113 | System permission denied. |
| 2303188 | Socket operation on non-socket. |
| 2303191 | Protocol wrong type for socket. |
| 2303198 | Address already in use. |
| 2303199 | Cannot assign requested address. |
| 2303210 | Connection timed out. |
| 2303501 | SSL is null. |
| 2303502 | Error in tls reading. |
| 2303503 | Error in tls writing |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
// Two way authentication
tls
.
bind
({
address
:
'
192.168.xxx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
let
Protocol
=
socket
.
Protocol
;
let
options
=
{
ALPNProtocols
:
[
"
spdy/1
"
,
"
http/1.1
"
],
address
:
{
address
:
"
192.168.xx.xxx
"
,
port
:
xxxx
,
family
:
1
,
},
secureOptions
:
{
key
:
"
xxxx
"
,
cert
:
"
xxxx
"
,
ca
:
[
"
xxxx
"
],
passwd
:
"
xxxx
"
,
protocols
:
[
Protocol
.
TLSv12
],
useRemoteCipherPrefer
:
true
,
signatureAlgorithms
:
rsa_pss_rsae_sha256
:
ECDSA
+
SHA25
,
cipherSuite
:
AES256
-
SHA256
,
},
};
tls
.
connect
(
options
,
(
err
,
data
)
=>
{
console
.
info
(
err
);
console
.
info
(
data
);
});
let
tlsOneWay
=
socket
.
constructTLSSocketInstance
();
// One way authentication
tlsOneWay
.
bind
({
address
:
'
192.168.xxx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
let
oneWayOptions
=
{
address
:
{
address
:
"
192.168.xxx.xxx
"
,
port
:
xxxx
,
family
:
1
,
},
secureOptions
:
{
ca
:
[
"
xxxx
"
,
"
xxxx
"
],
cipherSuite
:
AES256
-
SHA256
,
},
};
tlsOneWay
.
connect
(
options
,
(
err
,
data
)
=>
{
console
.
info
(
err
);
console
.
info
(
data
);
});
```
### connect<sup>9+</sup>
connect(options: TLSConnectOptions): Promise
\<
void>
在TLSSocket上bind成功之后,进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,该连接包括两种认证方式,单向认证与双向认证,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------| ----| --------------- |
| options |
[
TLSConnectOptions
](
#tlsconnectoptions9
)
| 是 | 连接所需要的参数。|
**返回值:**
| 类型 | 说明 |
| ------------------------------------------- | ----------------------------- |
| Promise
\<
void> | 以Promise形式返回,成功无返回,失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303104 | Interrupted system call. |
| 2303109 | Bad file number. |
| 2303111 | Resource temporarily unavailable try again. |
| 2303113 | System permission denied. |
| 2303188 | Socket operation on non-socket. |
| 2303191 | Protocol wrong type for socket. |
| 2303198 | Address already in use. |
| 2303199 | Cannot assign requested address. |
| 2303210 | Connection timed out. |
| 2303501 | SSL is null. |
| 2303502 | Error in tls reading. |
| 2303503 | Error in tls writing |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**示例:**
```
js
let
tls
=
socket
.
constructTLSSocketInstance
();
// Two way authentication
tls
.
bind
({
address
:
'
192.168.xxx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
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
:
"
xxxx
"
,
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
);
});
let
tlsOneWay
=
socket
.
constructTLSSocketInstance
();
// One way authentication
tlsOneWay
.
bind
({
address
:
'
192.168.xxx.xxx
'
,
port
:
xxxx
,
family
:
1
},
err
=>
{
if
(
err
)
{
console
.
log
(
'
bind fail
'
);
return
;
}
console
.
log
(
'
bind success
'
);
});
let
oneWayOptions
=
{
address
:
{
address
:
"
192.168.xxx.xxx
"
,
port
:
xxxx
,
family
:
1
,
},
secureOptions
:
{
ca
:
[
"
xxxx
"
,
"
xxxx
"
],
cipherSuite
:
AES256
-
SHA256
,
},
};
tlsOneWay
.
connect
(
oneWayOptions
).
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### getRemoteAddress<sup>9+</sup>
getRemoteAddress
\(
callback: AsyncCallback<NetAddress
\>\)
: void
在TLSSocket通信连接成功之后,获取对端Socket地址。使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------- | ---- | ---------- |
| callback | AsyncCallback
\<
[
NetAddress
](
#netaddress
)
> | 是 | 回调函数。成功返回对端的socket地址,失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getRemoteAddress
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
'
getRemoteAddress fail
'
);
return
;
}
console
.
log
(
'
getRemoteAddress success:
'
+
JSON
.
stringify
(
data
));
});
```
### getRemoteAddress<sup>9+</sup>
getRemoteAddress
\(\)
: Promise
\<
NetAddress>
在TLSSocket通信连接成功之后,获取对端Socket地址。使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| :------------------------------------------ | :------------------------------------------ |
| Promise
\<
[
NetAddress
](
#netaddress
)
> | 以Promise形式返回获取对端socket地址的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303188 | Socket operation on non-socket.|
| 2300002 | System internal error. |
**示例:**
```
js
let
promise
=
tls
.
getRemoteAddress
();
promise
.
then
(()
=>
{
console
.
log
(
'
getRemoteAddress success
'
);
}).
catch
(
err
=>
{
console
.
log
(
'
getRemoteAddress fail
'
);
});
```
### getCertificate<sup>9+</sup>
getCertificate(callback: AsyncCallback
\<
[
X509CertRawData
](
#x509certrawdata9
)
>): void
在TLSSocket通信连接成功之后,获取本地的数字证书,该接口只适用于双向认证时,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
[
X509CertRawData
](
#x509certrawdata9
)
> | 是 | 回调函数,成功返回本地的证书,失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303504 | Error looking up x509. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getCertificate
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getCertificate callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getCertificate callback =
"
+
data
);
}
});
```
### getCertificate<sup>9+</sup>
getCertificate():Promise
\<
[
X509CertRawData
](
#x509certrawdata9
)
>
在TLSSocket通信连接之后,获取本地的数字证书,该接口只适用于双向认证时,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
[
X509CertRawData
](
#x509certrawdata9
)
> | 以Promise形式返回本地的数字证书的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303504 | Error looking up x509. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getCertificate
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### getRemoteCertificate<sup>9+</sup>
getRemoteCertificate(callback: AsyncCallback
\<
[
X509CertRawData
](
#x509certrawdata9
)
>): void
在TLSSocket通信连接成功之后,获取服务端的数字证书,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
[
X509CertRawData
](
#x509certrawdata9
)
> | 是 | 回调函数,返回服务端的证书。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getRemoteCertificate
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getRemoteCertificate callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getRemoteCertificate callback =
"
+
data
);
}
});
```
### getRemoteCertificate<sup>9+</sup>
getRemoteCertificate():Promise
\<
[
X509CertRawData
](
#x509certrawdata9
)
>
在TLSSocket通信连接成功之后,获取服务端的数字证书,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
[
X509CertRawData
](
#x509certrawdata9
)
> | 以Promise形式返回服务端的数字证书的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getRemoteCertificate
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### getProtocol<sup>9+</sup>
getProtocol(callback: AsyncCallback
\<
string>): void
在TLSSocket通信连接成功之后,获取通信的协议版本,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
string> | 是 | 回调函数,返回通信的协议。失败返回错误码,错误信息。|
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getProtocol
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getProtocol callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getProtocol callback =
"
+
data
);
}
});
```
### getProtocol<sup>9+</sup>
getProtocol():Promise
\<
string>
在TLSSocket通信连接成功之后,获取通信的协议版本,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
string> | 以Promise形式返回通信的协议。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getProtocol
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### getCipherSuite<sup>9+</sup>
getCipherSuite(callback: AsyncCallback
\<
Array
\<
string>>): void
在TLSSocket通信连接成功之后,获取通信双方协商后的加密套件,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
Array
\<
string>> | 是 | 回调函数,返回通信双方支持的加密套件。 失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303502 | Error in tls reading. |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getCipherSuite
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getCipherSuite callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getCipherSuite callback =
"
+
data
);
}
});
```
### getCipherSuite<sup>9+</sup>
getCipherSuite(): Promise
\<
Array
\<
string>>
在TLSSocket通信连接成功之后,获取通信双方协商后的加密套件,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| ---------------------- | --------------------- |
| Promise
\<
Array
\<
string>> | 以Promise形式返回通信双方支持的加密套件。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303502 | Error in tls reading. |
| 2303505 | Error occurred in the tls system call. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getCipherSuite
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### getSignatureAlgorithms<sup>9+</sup>
getSignatureAlgorithms(callback: AsyncCallback
\<
Array
\<
string>>): void
在TLSSocket通信连接成功之后,获取通信双方协商后签名算法,该接口只适配双向认证模式下,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
Array
\<
string>> | 是 | 回调函数,返回双方支持的签名算法。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getSignatureAlgorithms
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getSignatureAlgorithms callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getSignatureAlgorithms callback =
"
+
data
);
}
});
```
### getSignatureAlgorithms<sup>9+</sup>
getSignatureAlgorithms(): Promise
\<
Array
\<
string>>
在TLSSocket通信连接成功之后,获取通信双方协商后的签名算法,该接口只适配双向认证模式下,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| ---------------------- | -------------------- |
| Promise
\<
Array
\<
string>> | 以Promise形式返回获取到的双方支持的签名算法。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
getSignatureAlgorithms
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### send<sup>9+</sup>
send(data: string, callback: AsyncCallback
\<
void>): void
在TLSSocket通信连接成功之后,向服务端发送消息,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -----------------------------| ---- | ---------------|
| data | string | 是 | 发送的数据内容。 |
| callback | AsyncCallback
\<
void> | 是 | 回调函数,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303501 | SSL is null. |
| 2303503 | Error in tls writing |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
send
(
"
xxxx
"
,
(
err
)
=>
{
if
(
err
)
{
console
.
log
(
"
send callback error =
"
+
err
);
}
else
{
console
.
log
(
"
send success
"
);
}
});
```
### send<sup>9+</sup>
send(data: string): Promise
\<
void>
在TLSSocket通信连接成功之后,向服务端发送消息,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -----------------------------| ---- | ---------------|
| data | string | 是 | 发送的数据内容。 |
**错误码:**
| 错误码ID | 错误信息 |
| 401 | Parameter error. |
| 2303501 | SSL is null. |
| 2303503 | Error in tls writing |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
void> | 以Promise形式返回,返回TLSSocket发送数据的结果。失败返回错误码,错误信息。 |
**示例:**
```
js
tls
.
send
(
"
xxxx
"
).
then
(()
=>
{
console
.
log
(
"
send success
"
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
### close<sup>9+</sup>
close(callback: AsyncCallback
\<
void>): void
在TLSSocket通信连接成功之后,断开连接,使用callback方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -----------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
void> | 是 | 回调函数,成功返回TLSSocket关闭连接的结果。 失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
close
((
err
)
=>
{
if
(
err
)
{
console
.
log
(
"
close callback error =
"
+
err
);
}
else
{
console
.
log
(
"
close success
"
);
}
});
```
### close<sup>9+</sup>
close(): Promise
\<
void>
在TLSSocket通信连接成功之后,断开连接,使用Promise方式作为异步方法。
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
void> | 以Promise形式返回,返回TLSSocket关闭连接的结果。失败返回错误码,错误信息。 |
**错误码:**
| 错误码ID | 错误信息 |
| 2303501 | SSL is null. |
| 2303505 | Error occurred in the tls system call. |
| 2303506 | Error clearing tls connection. |
| 2300002 | System internal error. |
**示例:**
```
js
tls
.
close
().
then
(()
=>
{
console
.
log
(
"
close success
"
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## TLSConnectOptions<sup>9+</sup>
TLS连接的操作。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| -------------- | ------------------------------------- | -------------- |
| address |
[
NetAddress
](
#netaddress
)
| 网关地址。 |
| secureOptions |
[
TLSSecureOptions
](
#tlssecureoptions9
)
| TLS安全相关操作。|
| ALPNProtocols | Array
\<
string> | ALPN协议。 |
## TLSSecureOptions<sup>9+</sup>
TLS安全相关操作,其中ca证书为必选参数,其他参数为可选参数。当本地证书cert和私钥key不为空时,开启双向验证模式。cert和key其中一项为空时,开启单向验证模式。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| --------------------- | ---------------------- | ----------------------------------- |
| ca | string
\|
Array
\<
string> | 服务端的ca证书,用于认证校验服务端的数字证书。|
| cert | string | 本地客户端的数字证书。 |
| key | string | 本地数字证书的私钥。 |
| passwd | string | 读取私钥的密码。 |
| protocols |
[
Protocol
](
#protocol9
)
\|
Array
\<
[
Protocol
](
#protocol9
)
> | TLS的协议版本。 |
| useRemoteCipherPrefer | boolean | 优先使用对等方的密码套件。 |
| signatureAlgorithms | string | 通信过程中的签名算法。 |
| cipherSuite | string | 通信过程中的加密套件。 |
## Protocol<sup>9+</sup>
TLS通信的协议版本。
**系统能力**
:SystemCapability.Communication.NetStack
|
**protocol 的合法值**
| 说明 |
| :------------------ | :------------------ |
| TLSv12 | 使用TLSv1.2协议通信。 |
| TLSv13 | 使用TLSv1.3协议通信。 |
## X509CertRawData<sup>9+</sup>
存储证书的数据。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| -------------- | ----------------------------- | -------------- |
| data | Uint8Array | 证书内容。 |
| encodingFormat | number | 编码格式der。 |
\ No newline at end of file
zh-cn/application-dev/reference/apis/js-apis-tlsSocket.md
已删除
100644 → 0
浏览文件 @
7e56da01
# TLSSocket
TLS Socket通信是对Socket通信的拓展。在Socket通信的基础上添加了一层安全性保护,提供了更高的安全性,分为三个子模块,包括密钥,证书,通信。
> **说明:**
>
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
## 导入模块
```
js
import
socket
from
'
@ohos.net.tlssocket
'
```
## socket.constructTLSSocketInstance
constructTLSSocketInstance(): TLSSocket
创建并返回一个TLSSocket对象。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**示例:**
```
js
let
tlssocket
=
socket
.
constructTLSSocketInstance
();
```
## tlssocket.connect
connect(options: TLSConnectOptions, callback: AsyncCallback
\<
void>): void
在TLSSocket上进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用callback方式作为异步方法。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------------------------| ----| --------------- |
| options |
[
TLSConnectOptions
](
#tlsconnectoptions
)
| 是 | 连接所需要的参数。|
| callback | AsyncCallback
\<
void> | 是 | 回调函数,成功无返回,失败返回对应错误码。 |
**示例:**
```
js
let
options
=
{
ALPNProtocols
:
[
"
spdy/1
"
,
"
http/1.1
"
],
address
:
{
address
:
"
xxx
"
,
port
:
"
xxxx
"
,
family
:
1
,
},
secureOptions
:
{
key
:
"
xxxx
"
,
cert
:
"
xxxx
"
,
ca
:
[
"
xxxx
"
],
passwd
:
"
xxxx
"
,
protocols
:
"
TlsV1_2
"
,
useRemoteCipherPrefer
:
true
,
signatureAlgorithms
:
SHA256
,
cipherSuites
:
AES256
-
SHA256
,
},
};
tlssocket
.
connect
(
options
,
(
err
,
data
)
=>
{
console
.
info
(
err
);
console
.
info
(
data
);
});
```
## tlssocket.connect
connect(options: TLSConnectOptions): Promise
\<
void>;
在TLSSocket上进行通信连接,并创建和初始化TLS会话,实现建立连接过程,启动与服务器的TLS/SSL握手,实现数据传输功能,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------| ----| --------------- |
| options |
[
TLSConnectOptions
](
#tlsconnectoptions
)
| 是 | 连接所需要的参数。|
**返回值:**
| 类型 | 说明 |
| ------------------------------------------- | ----------------------------- |
| Promise
\<
void> | 以Promise形式返回,成功无返回,失败返回对应错误码。 |
**示例:**
```
js
let
options
=
{
ALPNProtocols
:
[
"
spdy/1
"
,
"
http/1.1
"
],
address
:
{
address
:
"
xxxx
"
,
port
:
"
xxxx
"
,
family
:
1
,
},
secureOptions
:
{
key
:
"
xxxx
"
,
cert
:
"
xxxx
"
,
ca
:
[
"
xxxx
"
],
passwd
:
"
xxxx
"
,
protocols
:
"
TlsV1_2
"
,
useRemoteCipherPrefer
:
true
,
signatureAlgorithms
:
SHA256
,
cipherSuites
:
AES256
-
SHA256
,
},
};
tlssocket
.
connect
(
options
).
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.getCertificate
getCertificate(callback: AsyncCallback
\<
string>): void;
在TLSSocket通信连接之后,获取本地的数字证书,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
string> | 是 | 回调函数,返回本地的证书。|
**示例:**
```
js
tlssocket
.
getCertificate
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getCertificate callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getCertificate callback =
"
+
data
);
}
});
```
## tlssocket.getCertificate
getCertificate():Promise
\<
string>;
在TLSSocket通信连接之后,获取本地的数字证书,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
string> | 以Promise形式返回本地的数字证书。 |
**示例:**
```
js
tlssocket
.
getCertificate
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.getRemoteCertificate
getRemoteCertificate(callback: AsyncCallback
\<
string>): void;
在TLSSocket通信连接之后,获取对等方的数字证书,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
string> | 是 | 回调函数,返回对等方的证书。 |
**示例:**
```
js
tlssocket
.
getRemoteCertificate
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getRemoteCertificate callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getRemoteCertificate callback =
"
+
data
);
}
});
```
## tlssocket.getRemoteCertificate
getRemoteCertificate():Promise
\<
string>;
在TLSSocket通信连接之后,获取对等方的数字证书,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
string> | 以Promise形式返回对等方的数字证书。 |
**示例:**
```
js
tlssocket
.
getRemoteCertificate
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.getProtocol
getProtocol(callback: AsyncCallback
\<
string>): void;
在TLSSocket通信连接之后,获取通信的协议,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
string> | 是 | 回调函数,返回通信的协议。 |
**示例:**
```
js
tlssocket
.
getProtocol
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getProtocol callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getProtocol callback =
"
+
data
);
}
});
```
## tlssocket.getProtocol
getProtocol():Promise
\<
string>;
在TLSSocket通信连接之后,获取通信的协议,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
string> | 以Promise形式返回通信的协议。 |
**示例:**
```
js
tlssocket
.
getProtocol
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.getCipherSuites
getCipherSuites(callback: AsyncCallback
\<
Array
\<
string>>): void;
在TLSSocket通信连接之后,获取通信双方支持的加密套件,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
Array
\<
string>> | 是 | 回调函数,返回通信双方支持的加密套件。 |
**示例:**
```
js
tlssocket
.
getCipherSuites
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getCipherSuites callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getCipherSuites callback =
"
+
data
);
}
});
```
## tlssocket.getCipherSuites
getCipherSuites(): Promise
\<
Array
\<
string>>;
在TLSSocket通信连接之后,获取通信双方支持的加密套件,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| ---------------------- | --------------------- |
| Promise
\<
Array
\<
string>> | 以Promise形式返回通信双方支持的加密套件。 |
**示例:**
```
js
tlssocket
.
getCipherSuites
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.getSignatureAlgorithms
getSignatureAlgorithms(callback: AsyncCallback
\<
Array
\<
string>>): void;
在TLSSocket通信连接之后,获取通信双方支持的签名算法,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
Array
\<
string>> | 是 | 回调函数,返回双方支持的签名算法。 |
**示例:**
```
js
tlssocket
.
getSignatureAlgorithms
((
err
,
data
)
=>
{
if
(
err
)
{
console
.
log
(
"
getSignatureAlgorithms callback error =
"
+
err
);
}
else
{
console
.
log
(
"
getSignatureAlgorithms callback =
"
+
data
);
}
});
```
## tlssocket.getSignatureAlgorithms
getSignatureAlgorithms(): Promise
\<
Array
\<
string>>;
在TLSSocket通信连接之后,获取通信双方支持的签名算法,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| ---------------------- | -------------------- |
| Promise
\<
Array
\<
string>> | 以Promise形式返回获取到的双方支持的签名算法。 |
**示例:**
```
js
tlssocket
.
getSignatureAlgorithms
().
then
(
data
=>
{
console
.
info
(
data
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## tlssocket.close
close(callback: AsyncCallback
\<
void>): void;
在TLSSocket通信连接之后,断开连接,使用callback方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -----------------------------| ---- | ---------------|
| callback | AsyncCallback
\<
void> | 是 | 回调函数,返回TLSSocket关闭连接的结果。 |
**示例:**
```
js
tlssocket
.
close
((
err
)
=>
{
if
(
err
)
{
console
.
log
(
"
close callback error =
"
+
err
);
}
else
{
console
.
log
(
"
close success
"
);
}
});
```
## tlssocket.close
close(): Promise
\<
void>;
在TLSSocket通信连接之后,断开连接,使用Promise方式作为异步方法。
**需要权限**
:ohos.permission.INTERNET
**系统能力**
:SystemCapability.Communication.NetStack
**返回值:**
| 类型 | 说明 |
| -------------- | -------------------- |
| Promise
\<
void> | 以Promise形式返回,返回TLSSocket关闭连接的结果。 |
**示例:**
```
js
tlssocket
.
close
().
then
(()
=>
console
.
log
(
"
close success
"
);
}).
catch
(
err
=>
{
console
.
error
(
err
);
});
```
## TLSConnectOptions
TLS连接的操作。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| -------------- | ------------------------------------- | -------------- |
| address |
[
NetAddress
](
#netaddress
)
| 网关地址。 |
| secureOptions |
[
TLSSecureOptions
](
#tlssecureoptions
)
| TLS安全相关操作。|
| ALPNProtocols | Array
\<
string> | ALPN协议。 |
## NetAddress
网络地址。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| ------- | ------ | ---------------------------- |
| address | string | 地址。 |
| family | number | IPv4 = 1,IPv6 = 2,默认IPv4。 |
| port | number | 端口,取值范围
\[
0, 65535]。 |
## TLSSecureOptions
TLS安全相关操作。
**系统能力**
:SystemCapability.Communication.NetStack
| 参数名 | 类型 | 说明 |
| --------------------- | ---------------------- | ---------------------- |
| ca | string
\|
Array
\<
string> | ca证书。 |
| cert | string | 本地数字证书。 |
| key | string | 本地数字证书私钥。 |
| passwd | string | 密码。 |
| protocols | string | 协议名。 |
| useRemoteCipherPrefer | boolean | 优先使用对等方的密码套件。 |
| signatureAlgorithms | string | 设置签名算法。 |
| cipherSuites | string | 加密套件。 |
\ No newline at end of file
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录