From 4ca4daf63b0dffb8d8d9ada0a3fe69e558845d3f Mon Sep 17 00:00:00 2001 From: mayunteng Date: Wed, 19 Apr 2023 09:27:50 +0000 Subject: [PATCH] modify cooperate mdfile Signed-off-by: mayunteng Change-Id: Ie6513321e6dea0f24e0d5e286cf69543bd5e3770 --- .../reference/apis/js-apis-cooperate.md | 267 +++++++++++------- .../errorcodes/errorcode-devicestatus.md | 27 ++ 2 files changed, 190 insertions(+), 104 deletions(-) mode change 100755 => 100644 zh-cn/application-dev/reference/apis/js-apis-cooperate.md create mode 100644 zh-cn/application-dev/reference/errorcodes/errorcode-devicestatus.md diff --git a/zh-cn/application-dev/reference/apis/js-apis-cooperate.md b/zh-cn/application-dev/reference/apis/js-apis-cooperate.md old mode 100755 new mode 100644 index c9a89d39b1..0fd6866bc2 --- a/zh-cn/application-dev/reference/apis/js-apis-cooperate.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cooperate.md @@ -1,4 +1,4 @@ -# @ohos.multimodalInput.inputDeviceCooperate (键鼠穿越) +# @ohos.cooperate (键鼠穿越) 键鼠穿越功能模块，提供两台或多台设备组网协同后键鼠共享能力，实现键鼠输入设备的跨设备协同操作。 @@ -11,113 +11,160 @@ ## 导入模块 ```js -import inputDeviceCooperate from '@ohos.multimodalInput.inputDeviceCooperate' +import cooperate from '@ohos.cooperate' ``` -## inputDeviceCooperate.enable +## cooperate.prepare -enable(enable: boolean, callback: AsyncCallback<void>): void +prepare(callback: AsyncCallback): void; -开启、关闭键鼠穿越，使用AsyncCallback异步方式返回结果。 +准备键鼠穿越，使用AsyncCallback异步方式返回结果。 -**系统能力**: SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**: SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | --------------------------- | -| enable | boolean | 是 | 键鼠穿越使能状态。 | -| callback | AsyncCallback<void> | 是 |回调函数，异步返回键鼠穿越开启、关闭结果。 | - - +| callback | AsyncCallback<void> | 是 |回调函数，异步返回准备键鼠穿越的结果。 | **示例**： ```js try { - inputDeviceCooperate.enable(true, (error) => { + cooperate.prepare((error) => { if (error) { - console.log(`Keyboard mouse crossing enable failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + console.log(`Keyboard mouse crossing prepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); return; } - console.log(`Keyboard mouse crossing enable success.`); + console.log(`Keyboard mouse crossing prepare success.`); }); } catch (error) { - console.log(`Keyboard mouse crossing enable failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + console.log(`Keyboard mouse crossing prepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` -## inputDeviceCooperate.enable +## cooperate.prepare -enable(enable: boolean): Promise<void> +prepare(): Promise<void> -开启、关闭键鼠穿越，使用Promise异步方式返回结果。 +准备键鼠穿越，使用Promise异步方式返回结果。 +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate -**系统能力**： SystemCapability.MultimodalInput.Input.Cooperator +**返回值**： -**参数**： +| 参数 | 说明 | +| ------------------- | ------------------------------- | +| Promise<void> | Promise对象，异步返回准备键鼠穿越的结果。 | -| 参数名 | 类型 | 必填 | 说明 | -| --------- | ------- | ---- | ------------------------------------------------------------------- | -| enable | boolean | 是 | 键鼠穿越使能状态。 | +**示例**： -**返回值**： +```js +try { + cooperate.prepare().then(() => { + console.log(`Keyboard mouse crossing prepare success.`); + }, (error) => { + console.log(`Keyboard mouse crossing prepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + }); +} catch (error) { + console.log(`Keyboard mouse crossing prepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); +} +``` -| 参数 | 说明 | -| ------------------- | ------------------------------- | -| Promise<void> | Promise对象，异步返回键鼠穿越开启、关闭结果。 | +## cooperate.unprepare + +unprepare(callback: AsyncCallback): void; + +取消准备键鼠穿越，使用AsyncCallback异步方式返回结果。 + +**系统能力**: SystemCapability.Msdp.DeviceStatus.Cooperate + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | ------------------------------------------ | +| callback | AsyncCallback | 是 | 回调函数，异步返回取消准备键鼠穿越的结果。 | **示例**： ```js try { - inputDeviceCooperate.enable(true).then(() => { - console.log(`Keyboard mouse crossing enable success.`); + cooperate.unprepare((error) => { + if (error) { + console.log(`Keyboard mouse crossing unprepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + return; + } + console.log(`Keyboard mouse crossing unprepare success.`); + }); +} catch (error) { + console.log(`Keyboard mouse crossing unprepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); +} +``` + + + +## cooperate.unprepare + +unprepare(): Promise; + +取消准备键鼠穿越，使用Promise异步方式返回结果。 + +**系统能力**: SystemCapability.Msdp.DeviceStatus.Cooperate + +**返回值**： + +| 参数 | 说明 | +| ------------- | --------------------------------------------- | +| Promise | Promise对象，异步返回取消准备键鼠穿越的结果。 | + +```js +try { + cooperate.unprepare().then(() => { + console.log(`Keyboard mouse crossing unprepare success.`); }, (error) => { - console.log(`Keyboard mouse crossing enable failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + console.log(`Keyboard mouse crossing unprepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); }); } catch (error) { - console.log(`Keyboard mouse crossing enable failed, error: ${JSON.stringify(error, [`code`, `message`])}`); + console.log(`Keyboard mouse crossing unprepare failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` -## inputDeviceCooperate.start -start(sinkDeviceDescriptor: string, srcInputDeviceId: number, callback: AsyncCallback\): void + +## cooperate.activate + +activate(targetNetworkId: string, inputDeviceId: number, callback: AsyncCallback): void; 启动键鼠穿越，使用AsyncCallback异步方式返回结果。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ---------------------------- | -| sinkDeviceDescriptor | string | 是 | 键鼠穿越目标设备描述符。 | -| srcInputDeviceId | number | 是 | 键鼠穿越待穿越外设标识符。 | -| callback | AsyncCallback\ | 是 | 回调函数，异步返回键鼠穿越启动、停止状态。| +| targetNetworkId | string | 是 | 键鼠穿越目标设备描述符。 | +| inputDeviceId | number | 是 | 待穿越输入设备标识符。 | +| callback | AsyncCallback\ | 是 | 回调函数，异步返回启动键鼠穿越的结果。 | **错误码：** -以下错误码的详细介绍请参见[ohos.multimodalinput错误码](../errorcodes/errorcode-multimodalinput.md)。 +以下错误码的详细介绍请参见[ohos.devicestatus错误码](../errorcodes/errorcode-devicestatus.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | -| 4400001 | 当调用键鼠穿越接口传入无效的设备描述符参数时，系统会产生此错误码。 | -| 4400002 | 当调用键鼠穿越接口时穿越状态异常，系统会产生此错误码。 | +| 20900001 | 当调用键鼠穿越接口时穿越状态异常，系统会产生此错误码。 | **示例**： ```js -let sinkDeviceDescriptor = "descriptor"; -let srcInputDeviceId = 0; +let targetNetworkId = "networkId"; +let inputDeviceId = 0; try { - inputDeviceCooperate.start(sinkDeviceDescriptor, srcInputDeviceId, (error) => { + cooperate.activate(targetNetworkId, inputDeviceId, (error) => { if (error) { console.log(`Start Keyboard mouse crossing failed, error: ${JSON.stringify(error, [`code`, `message`])}`); return; @@ -129,20 +176,20 @@ try { } ``` -## inputDeviceCooperate.start +## cooperate.activate -start(sinkDeviceDescriptor: string, srcInputDeviceId: number): Promise\ +activate(targetNetworkId: string, inputDeviceId: number): Promise; 启动键鼠穿越，使用Promise异步方式返回结果。 -**系统能力**: SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**: SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ---------------------------- | -| sinkDeviceDescriptor | string | 是 | 键鼠穿越目标设备描述符。 | -| srcInputDeviceId | number | 是 | 键鼠穿越待穿越外设标识符。 | +| targetNetworkId | string | 是 | 键鼠穿越目标设备描述符。 | +| inputDeviceId | number | 是 | 待穿越输入设备标识符 | @@ -150,24 +197,23 @@ start(sinkDeviceDescriptor: string, srcInputDeviceId: number): Promise\ | 参数名 | 说明 | | ---------------------- | ------------------------------- | -| Promise\ | Promise对象，异步返回键鼠穿越启动、关闭结果。 | +| Promise\ | Promise对象，异步返回启动键鼠穿越结果。 | **错误码：** -以下错误码的详细介绍请参见[ohos.multimodalinput错误码](../errorcodes/errorcode-multimodalinput.md)。 +以下错误码的详细介绍请参见[ohos.devicestatus错误码](../errorcodes/errorcode-devicestatus.md)。 | 错误码ID | 错误信息 | | -------- | ---------------------------------------- | -| 4400001 | 当调用键鼠穿越接口传入无效的设备描述符参数时，系统会产生此错误码。 | -| 4400002 | 当调用键鼠穿越接口时穿越状态异常，系统会产生此错误码。 | +| 20900001 | 当调用键鼠穿越接口时穿越状态异常，系统会产生此错误码。 | **示例**： ```js -let sinkDeviceDescriptor = "descriptor"; -let srcInputDeviceId = 0; +let targetNetworkId = "networkId"; +let inputDeviceId = 0; try { - inputDeviceCooperate.start(sinkDeviceDescriptor, srcInputDeviceId).then(() => { + cooperate.activate(targetNetworkId, inputDeviceId).then(() => { console.log(`Start Keyboard mouse crossing success.`); }, (error) => { console.log(`Start Keyboard mouse crossing failed, error: ${JSON.stringify(error, [`code`, `message`])}`); @@ -177,19 +223,20 @@ try { } ``` -## inputDeviceCooperate.stop +## cooperate.deactivate -stop(callback: AsyncCallback\): void +deactivate(isUnchained: boolean, callback: AsyncCallback): void; 停止键鼠穿越，使用AsyncCallback异步方式返回结果。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ---------------------------- | -| callback | AsyncCallback\ | 是 | 回调函数，异步返回停止键鼠穿越结果。 | +| isUnchained | boolean | 是 | 是否关闭跨设备链路 | +| callback | AsyncCallback\ | 是 | 回调函数，异步返回停止键鼠穿越的结果。 | @@ -197,7 +244,7 @@ stop(callback: AsyncCallback\): void ```js try { - inputDeviceCooperate.stop((error) => { + cooperate.deactivate(false, (error) => { if (error) { console.log(`Stop Keyboard mouse crossing failed, error: ${JSON.stringify(error, [`code`, `message`])}`); return; @@ -209,13 +256,21 @@ try { } ``` -## inputDeviceCooperate.stop +## cooperate.deactivate -stop(): Promise\ +deactivate(isUnchained: boolean): Promise; 停止键鼠穿越，使用Promise异步方式返回结果。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ------- | ---- | ------------------ | +| isUnchained | boolean | 是 | 是否关闭跨设备链路 | + + **返回值**： @@ -223,11 +278,13 @@ stop(): Promise\ | -------- | ---------------------------- | | Promise\ | Promise对象，异步返回停止键鼠穿越结果。 | + + **示例**： ```js try { - inputDeviceCooperate.stop().then(() => { + cooperate.deactivate(false).then(() => { console.log(`Stop Keyboard mouse crossing success.`); }, (error) => { console.log(`Stop Keyboard mouse crossing failed, error: ${JSON.stringify(error, [`code`, `message`])}`); @@ -237,27 +294,27 @@ try { } ``` -## inputDeviceCooperate.getState +## cooperate.getCrossingSwitchState -getState(deviceDescriptor: string, callback: AsyncCallback<{ state: boolean }>): void +getCrossingSwitchState(networkId: string, callback: AsyncCallback): void; -获取键鼠穿越开关的状态，使用AsyncCallback异步方式返回结果。 +获取目标设备键鼠穿越开关的状态，使用AsyncCallback异步方式返回结果。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | --------- | ---- | ---------------------------- | -| deviceDescriptor | string | 是 | 键鼠穿越目标设备描述符。 | -| callback | AsyncCallback<{ state: boolean }> | 是 | 回调函数，异步返回键鼠穿越开关状态。 | +| networkId | string | 是 | 键鼠穿越目标设备描述符。 | +| callback | AsyncCallback | 是 | 回调函数，异步返回目标设备的键鼠穿越开关状态 | **示例**： ```js -let deviceDescriptor = "descriptor"; +let deviceDescriptor = "networkId"; try { - inputDeviceCooperate.getState(deviceDescriptor, (error, data) => { + cooperate.getCrossingSwitchState(deviceDescriptor, (error, data) => { if (error) { console.log(`Get the status failed, error: ${JSON.stringify(error, [`code`, `message`])}`); return; @@ -269,19 +326,19 @@ try { } ``` -## inputDeviceCooperate.getState +## cooperate.getCrossingSwitchState -getState(deviceDescriptor: string): Promise<{ state: boolean }> +getCrossingSwitchState(networkId: string): Promise; -获取键鼠穿越开关的状态，使用Promise异步方式返回结果。 +获取目标设备键鼠穿越开关的状态，使用Promise异步方式返回结果。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | --------- | ---- | ---------------------------- | -| deviceDescriptor | string | 是 | 键鼠穿越目标设备描述符。 | +| networkId | string | 是 | 键鼠穿越目标设备描述符。 | @@ -289,16 +346,16 @@ getState(deviceDescriptor: string): Promise<{ state: boolean }> | 参数 | 说明 | | ------------------- | ------------------------------- | -| Promise<{ state: boolean }>| Promise对象，异步返回键鼠穿越开关状态。 | +| Promise | Promise对象，异步返回目标设备的键鼠穿越开关状态 | **示例**： ```js -let deviceDescriptor = "descriptor"; +let deviceDescriptor = "networkId"; try { - inputDeviceCooperate.getState(deviceDescriptor).then((data) => { + cooperate.getCrossingSwitchState(deviceDescriptor).then((data) => { console.log(`Get the status success, data: ${JSON.stringify(data)}`); }, (error) => { console.log(`Get the status failed, error: ${JSON.stringify(error, [`code`, `message`])}`); @@ -308,20 +365,20 @@ try { } ``` -## on('cooperation') +## on('cooperate') -on(type: 'cooperation', callback: AsyncCallback<{ deviceDescriptor: string, eventMsg: EventMsg }>): void +on(type: 'cooperate', callback: Callback<{ networkId: string, msg: CooperateMsg }>): void; 注册监听键鼠穿越状态。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ---------------------------- | -| type | string | 是 | 注册类型，取值”cooperation“。 | -| callback | AsyncCallback<{ deviceDescriptor: string, eventMsg: [EventMsg](#eventmsg) }> | 是 | 回调函数，异步返回键鼠穿越事件。 | +| type | string | 是 | 监听类型，取值为”cooperate“ | +| callback | Callback<{ networkId: string, msg: [CooperateMsg](#CooperateMsg) }> | 是 | 回调函数，异步返回键鼠穿越状态消息 | @@ -329,7 +386,7 @@ on(type: 'cooperation', callback: AsyncCallback<{ deviceDescriptor: string, even ```js try { - inputDeviceCooperate.on('cooperation', (data) => { + cooperate.on('cooperate', (data) => { console.log(`Keyboard mouse crossing event: ${JSON.stringify(data)}`); }); } catch (error) { @@ -337,19 +394,19 @@ try { } ``` -## off('cooperation') +## off('cooperate') -off(type: 'cooperation', callback?: AsyncCallback\): void +off(type: 'cooperate', callback?: Callback): void; -关闭监听键鼠穿越状态。 +取消监听键鼠穿越状态。 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ---------------------------- | ---- | ---------------------------- | -| type | string | 是 | 注册类型，取值“cooperation”。 | +| type | string | 是 | 监听类型，取值为“cooperate” | | callback | AsyncCallback\ | 否 | 需要取消注册的回调函数，若无此参数，则取消当前应用注册的所有回调函数。 | @@ -363,8 +420,8 @@ function callback(event) { return false; } try { - inputDeviceCooperate.on('cooperation', callback); - inputDeviceCooperate.off("cooperation", callback); + cooperate.on('cooperate', callback); + cooperate.off("cooperate", callback); } catch (error) { console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } @@ -376,23 +433,25 @@ function callback(event) { return false; } try { - inputDeviceCooperate.on('cooperation', callback); - inputDeviceCooperate.off("cooperation"); + cooperate.on('cooperate', callback); + cooperate.off("cooperate"); } catch (error) { console.log(`Execute failed, error: ${JSON.stringify(error, [`code`, `message`])}`); } ``` -## EventMsg +## CooperateMsg -键鼠穿越事件。 +键鼠穿越状态通知消息 -**系统能力**：SystemCapability.MultimodalInput.Input.Cooperator +**系统能力**：SystemCapability.Msdp.DeviceStatus.Cooperate -| 名称 | 值 | 说明 | -| -------- | --------- | ----------------- | -| MSG_COOPERATE_INFO_START | 200 | 键鼠穿越消息，表示键鼠穿越开始。 | -| MSG_COOPERATE_INFO_SUCCESS | 201 | 键鼠穿越消息，表示键鼠穿越成功。 | -| MSG_COOPERATE_INFO_FAIL | 202 | 键鼠穿越消息，表示键鼠穿越失败。 | -| MSG_COOPERATE_STATE_ON | 500 | 键鼠穿越状态，表示键鼠穿越状态开启。 | -| MSG_COOPERATE_STATE_OFF | 501 | 键鼠穿越状态，表示键鼠穿越状态关闭。 | +| 名称 | 值 | 说明 | +| -------- | ----------------- | ----------------- | +| COOPERATE_PREPARE | 0 | 键鼠穿越消息，表示键鼠穿越准备。 | +| COOPERATE_UNPREPARE | 1 | 键鼠穿越消息，表示键鼠穿越取消准备。 | +| COOPERATE_ACTIVATE | 2 | 键鼠穿越消息，表示键鼠穿越启动。 | +| COOPERATE_ACTIVATE_SUCCESS | 3 | 键鼠穿越状态，表示键鼠穿越启动成功。 | +| COOPERATE_ACTIVATE_FAIL | 4 | 键鼠穿越状态，表示键鼠穿越启动失败。 | +| COOPERATE_DEACTIVATE_SUCCESS | 5 | 键鼠穿越状态，表示键鼠穿越停止成功。 | +| COOPERATE_DEACTIVATE_FAIL | 6 | 键鼠穿越状态，表示键鼠穿越停止失败。 | diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-devicestatus.md b/zh-cn/application-dev/reference/errorcodes/errorcode-devicestatus.md new file mode 100644 index 0000000000..4dfcde11d5 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-devicestatus.md @@ -0,0 +1,27 @@ +# 键鼠穿越管理错误码 + +> **说明：** +> +> 以下仅介绍本模块特有错误码，通用错误码请参考[通用错误码说明文档](errorcode-universal.md)。 + +## 20900001 操作输入设备失败 + +**错误信息** + +Failed to operate the input device. + +**错误描述** + +当调用键鼠穿越接口时穿越状态异常，系统会产生此错误码。 + +**可能原因** + +1. 发起键鼠穿越时，本机键鼠穿越为穿出状态。 +2. 关闭键鼠穿越时，本机键鼠穿越为自由态。 +3. 发起关闭键鼠穿越时，本机键鼠穿越状态正在切换中。 + +**处理步骤** + +1. 发起键鼠穿越时，请检查本机键鼠穿越状态是否为非穿出状态。 +2. 关闭键鼠穿越时，请检查本机键鼠穿越状态是否为非自由态。 +3. 发起关闭键鼠穿越时，请检查本机键鼠穿越状态是否在切换中。 \ No newline at end of file -- GitLab