diff --git a/CODEOWNERS b/CODEOWNERS index 9a1d61d16ef420d826e30e51578f82be8db8db2f..b8953a55a47188713210861b2229e5610df8dd9c 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -275,6 +275,8 @@ zh-cn/application-dev/reference/apis/js-apis-application-StartOptions.md @little zh-cn/application-dev/reference/apis/js-apis-application-staticSubscriberExtensionAbility.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen zh-cn/application-dev/reference/apis/js-apis-application-Want.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen zh-cn/application-dev/reference/apis/js-apis-application-WindowExtensionAbility.md @zhangqiang183 @ge-yafang @zhouyaoying @zxg-gitee +zh-cn/application-dev/application-models/windowextensionability.md @zhangqiang183 @ge-yafang @zhouyaoying @zxg-gitee +zh-cn/application-dev/reference/apis/js-apis-inner-application-windowExtensionContext.md @ge-yafang @zhouyaoying @zxg-gitee zh-cn/application-dev/reference/apis/js-apis-appmanager.md @littlejerry1 @RayShih @gwang2008 @chengxingzhen zh-cn/application-dev/reference/apis/js-apis-arraylist.md @gongjunsong @ge-yafang @flyingwolf @BlackStone zh-cn/application-dev/reference/apis/js-apis-audio.md @liuyuehua1 @zengyawen @magekkkk @currydavids @@ -476,6 +478,7 @@ zh-cn/application-dev/reference/apis/js-apis-wifiext.md @cheng_guohong @RayShih zh-cn/application-dev/reference/apis/js-apis-window.md @zhangqiang183 @ge-yafang @zhouyaoying @zxg-gitee zh-cn/application-dev/reference/apis/js-apis-windowAnimationManager.md @zhangqiang183 @ge-yafang @wind_zj @zxg-gitee zh-cn/application-dev/reference/apis/js-apis-worker.md @gongjunsong @ge-yafang @flyingwolf @BlackStone +zh-cn/application-dev/reference/apis/js-apis-taskpool.md @gongjunsong @ge-yafang @flyingwolf @BlackStone zh-cn/application-dev/reference/apis/js-apis-workScheduler.md @chenmingJay @ningningW @tangtiantian2021 @nan-xiansen @iceice1001 zh-cn/application-dev/reference/apis/js-apis-WorkSchedulerExtensionAbility.md @chenmingJay @ningningW @tangtiantian2021 @nan-xiansen @iceice1001 zh-cn/application-dev/reference/apis/js-apis-xml.md @gongjunsong @ge-yafang @flyingwolf @BlackStone diff --git a/en/application-dev/reference/native-lib/third_party_napi/napi.md b/en/application-dev/reference/native-lib/third_party_napi/napi.md index d555b935351b675e35777f01b58789650a54de57..c14804bfc2316d4573b67a9a1b9254319c2bcc9c 100644 --- a/en/application-dev/reference/native-lib/third_party_napi/napi.md +++ b/en/application-dev/reference/native-lib/third_party_napi/napi.md @@ -2,124 +2,124 @@ ## Introduction -Node-API provides APIs to encapsulate JavaScript capabilities as a native plug-in. It is independent of the underlying JavaScript and is maintained as part of Node.js. +Node-API (NAPI) provides APIs to encapsulate JavaScript capabilities as a native plug-in. It is independent of the underlying JavaScript and is maintained as part of Node.js. ## Supported Capabilities -Node-API eliminates the differences between underlying JavaScript engines and provides a set of stable interfaces. +NAPI eliminates the differences between underlying JavaScript engines and provides a set of stable interfaces. -The OpenHarmony Native API (NAPI) component optimizes the Node-API interface implementation and provides connection to underlying engines such as ArkJS. Currently, some APIs in the [Node-API](https://nodejs.org/docs/v14.9.0/api/n-api.html) standard library are supported. +The OpenHarmony Native API component optimizes the NAPI interface implementation and provides connection to underlying engines such as ArkJS. Currently, some APIs in the [Node-API](https://nodejs.org/docs/v14.9.0/api/n-api.html) standard library are supported. -## Extended Symbols of NAPI +## Symbols Extended by the OpenHarmony API Component -|Type|Symbol|Remarks| +|Type|Symbol|Description| | --- | --- | --- | |FUNC|napi_run_script_path|Runs a JavaScript file.| -**Symbols Exported from the Standard Library** +** Symbols Exported from the NAPI Library** -|Type|Symbol|Remarks| +|Type|Symbol|Description| | --- | --- | --- | -|FUNC|napi_module_register|| -|FUNC|napi_get_last_error_info|| -|FUNC|napi_throw|| -|FUNC|napi_throw_error|| -|FUNC|napi_throw_type_error|| -|FUNC|napi_throw_range_error|| -|FUNC|napi_is_error|| -|FUNC|napi_create_error|| -|FUNC|napi_create_type_error|| -|FUNC|napi_create_range_error|| -|FUNC|napi_get_and_clear_last_exception|| -|FUNC|napi_is_exception_pending|| -|FUNC|napi_fatal_error|| -|FUNC|napi_open_handle_scope|| -|FUNC|napi_close_handle_scope|| -|FUNC|napi_open_escapable_handle_scope|| -|FUNC|napi_close_escapable_handle_scope|| -|FUNC|napi_escape_handle|| -|FUNC|napi_create_reference|| -|FUNC|napi_delete_reference|| -|FUNC|napi_reference_ref|| -|FUNC|napi_reference_unref|| -|FUNC|napi_get_reference_value|| -|FUNC|napi_create_array|| -|FUNC|napi_create_array_with_length|| -|FUNC|napi_create_arraybuffer|| -|FUNC|napi_create_external|| -|FUNC|napi_create_external_arraybuffer|| -|FUNC|napi_create_object|| -|FUNC|napi_create_symbol|| -|FUNC|napi_create_typedarray|| -|FUNC|napi_create_dataview|| -|FUNC|napi_create_int32|| -|FUNC|napi_create_uint32|| -|FUNC|napi_create_int64|| -|FUNC|napi_create_double|| -|FUNC|napi_create_string_latin1|| -|FUNC|napi_create_string_utf8|| -|FUNC|napi_get_array_length|| -|FUNC|napi_get_arraybuffer_info|| -|FUNC|napi_get_prototype|| -|FUNC|napi_get_typedarray_info|| -|FUNC|napi_get_dataview_info|| -|FUNC|napi_get_value_bool|| -|FUNC|napi_get_value_double|| -|FUNC|napi_get_value_external|| -|FUNC|napi_get_value_int32|| -|FUNC|napi_get_value_int64|| -|FUNC|napi_get_value_string_latin1|| -|FUNC|napi_get_value_string_utf8|| -|FUNC|napi_get_value_uint32|| -|FUNC|napi_get_boolean|| -|FUNC|napi_get_global|| -|FUNC|napi_get_null|| -|FUNC|napi_get_undefined|| -|FUNC|napi_coerce_to_bool|| -|FUNC|napi_coerce_to_number|| -|FUNC|napi_coerce_to_object|| -|FUNC|napi_coerce_to_string|| -|FUNC|napi_typeof|| -|FUNC|napi_instanceof|| -|FUNC|napi_is_array|| -|FUNC|napi_is_arraybuffer|| -|FUNC|napi_is_typedarray|| -|FUNC|napi_is_dataview|| -|FUNC|napi_is_date|| -|FUNC|napi_strict_equals|| -|FUNC|napi_get_property_names|| -|FUNC|napi_set_property|| -|FUNC|napi_get_property|| -|FUNC|napi_has_property|| -|FUNC|napi_delete_property|| -|FUNC|napi_has_own_property|| -|FUNC|napi_set_named_property|| -|FUNC|napi_get_named_property|| -|FUNC|napi_has_named_property|| -|FUNC|napi_set_element|| -|FUNC|napi_get_element|| -|FUNC|napi_has_element|| -|FUNC|napi_delete_element|| -|FUNC|napi_define_properties|| -|FUNC|napi_call_function|| -|FUNC|napi_create_function|| -|FUNC|napi_get_cb_info|| -|FUNC|napi_get_new_target|| -|FUNC|napi_new_instance|| -|FUNC|napi_define_class|| -|FUNC|napi_wrap|| -|FUNC|napi_unwrap|| -|FUNC|napi_remove_wrap|| -|FUNC|napi_create_async_work|| -|FUNC|napi_delete_async_work|| -|FUNC|napi_queue_async_work|| -|FUNC|napi_cancel_async_work|| -|FUNC|napi_get_node_version|| -|FUNC|napi_get_version|| -|FUNC|napi_create_promise|| -|FUNC|napi_resolve_deferred|| -|FUNC|napi_reject_deferred|| -|FUNC|napi_is_promise|| -|FUNC|napi_run_script|| -|FUNC|napi_get_uv_event_loop|| \ No newline at end of file +|FUNC|napi_module_register|Registers the NAPI native module.| +|FUNC|napi_get_last_error_info|Obtains the **napi_extended_error_info** structure, which contains the latest error information.| +|FUNC|napi_throw|Throws a JavaScript value.| +|FUNC|napi_throw_error|Throws a JavaScript **Error** with text information.| +|FUNC|napi_throw_type_error|Throws a JavaScript **TypeError** with text information.| +|FUNC|napi_throw_range_error|Throws a JavaScript **RangeError** with text information.| +|FUNC|napi_is_error|Checks whether **napi_value** indicates an error object.| +|FUNC|napi_create_error|Creates and obtains a JavaScript **Error** with text information.| +|FUNC|napi_create_type_error|Creates and obtains a JavaScript **TypeError** with text information.| +|FUNC|napi_create_range_error|Creates and obtains a JavaScript **RangeError** with text information.| +|FUNC|napi_get_and_clear_last_exception|Obtains and clears the latest exception.| +|FUNC|napi_is_exception_pending|Checks whether an exception occurs.| +|FUNC|napi_fatal_error|Raises a fatal error to terminate the process immediately.| +|FUNC|napi_open_handle_scope|Creates a context environment.| +|FUNC|napi_close_handle_scope|Closes the context environment. After the context environment is closed, all references declared in it are closed.| +|FUNC|napi_open_escapable_handle_scope|Creates an escapable handle scope from which the declared values can be returned to the parent scope.| +|FUNC|napi_close_escapable_handle_scope|Closes the escapable handle scope passed in.| +|FUNC|napi_escape_handle|Promotes the handle to the input JavaScript object so that it is valid for the lifespan of its parent scope.| +|FUNC|napi_create_reference|Creates a reference for an **Object** to extend its lifespan. The caller needs to manage the reference lifespan.| +|FUNC|napi_delete_reference|Deletes the reference passed in.| +|FUNC|napi_reference_ref|Increments the reference count for the reference passed in and returns the count.| +|FUNC|napi_reference_unref|Decrements the reference count for the reference passed in and returns the count.| +|FUNC|napi_get_reference_value|Obtains the JavaScript **Object** associated with the reference.| +|FUNC|napi_create_array|Creates and obtains a JavaScript **Array**.| +|FUNC|napi_create_array_with_length|Creates and obtains a JavaScript **Array** of the specified length.| +|FUNC|napi_create_arraybuffer|Creates and obtains a JavaScript **ArrayBuffer** of the specified size.| +|FUNC|napi_create_external|Allocates a JavaScript value with external data.| +|FUNC|napi_create_external_arraybuffer|Allocates a JavaScript **ArrayBuffer** with external data.| +|FUNC|napi_create_object|Creates a default JavaScript **Object**.| +|FUNC|napi_create_symbol|Create a JavaScript **Symbol**.| +|FUNC|napi_create_typedarray|Creates a JavaScript **TypeArray** from an existing **ArrayBuffer**.| +|FUNC|napi_create_dataview|Creates a JavaScript **DataView** from an existing **ArrayBuffer**.| +|FUNC|napi_create_int32|Creates a JavaScript **Number** from C **int32_t** data.| +|FUNC|napi_create_uint32|Creates a JavaScript **Number** from C **uint32_t** data.| +|FUNC|napi_create_int64|Creates a JavaScript **Number** from C **int64_t** data.| +|FUNC|napi_create_double|Creates a JavaScript **Number** from C **double** data.| +|FUNC|napi_create_string_latin1|Creates a JavaScript **String** from an ISO-8859-1-encoded C string.| +|FUNC|napi_create_string_utf8|Creates a JavaScript **String** from a UTF8-encoded C string.| +|FUNC|napi_get_array_length|Obtains the length of an array.| +|FUNC|napi_get_arraybuffer_info|Obtains the underlying data buffer of the **ArrayBuffer** and its length.| +|FUNC|napi_get_prototype|Obtains the prototype of the specified JavaScript **Object**.| +|FUNC|napi_get_typedarray_info|Obtains properties of the specified **TypedArray**.| +|FUNC|napi_get_dataview_info|Obtains properties of the specified **DataView**.| +|FUNC|napi_get_value_bool|Obtains the C Boolean equivalent of the given JavaScript **Boolean**.| +|FUNC|napi_get_value_double|Obtains the C double equivalent of the given JavaScript **Number**.| +|FUNC|napi_get_value_external|Obtains the external data pointer previously passed through **napi_create_external()**.| +|FUNC|napi_get_value_int32|Obtains the C int32 equivalent of the given JavaScript **Number**.| +|FUNC|napi_get_value_int64|Obtains the C int64 equivalent of the given JavaScript **Number**.| +|FUNC|napi_get_value_string_latin1|Obtains the ISO-8859-1-encoded string corresponding to the given JavaScript value.| +|FUNC|napi_get_value_string_utf8|Obtains the UTF8-encoded string corresponding to the given JavaScript value.| +|FUNC|napi_get_value_uint32|Obtains the C uint32 equivalent of the given JavaScript **Number**.| +|FUNC|napi_get_boolean|Obtains the JavaScript Boolean object based on the given C Boolean value.| +|FUNC|napi_get_global|Obtains the **global** object.| +|FUNC|napi_get_null|Obtains the **null** object.| +|FUNC|napi_get_undefined|Obtains the **undefined** object.| +|FUNC|napi_coerce_to_bool|Forcibly converts the given JavaScript value to a JavaScript Boolean value.| +|FUNC|napi_coerce_to_number|Forcibly converts the given JavaScript value to a JavaScript number.| +|FUNC|napi_coerce_to_object|Forcibly converts the given JavaScript value to a JavaScript object.| +|FUNC|napi_coerce_to_string|Forcibly converts the given JavaScript value to a JavaScript string.| +|FUNC|napi_typeof|Obtains the JavaScript type of the given JavaScript value.| +|FUNC|napi_instanceof|Checks whether the given object is an instance of the specified constructor.| +|FUNC|napi_is_array|Checks whether the given JavaScript value is an array.| +|FUNC|napi_is_arraybuffer|Checks whether the given JavaScript value is a `ArrayBuffer`.| +|FUNC|napi_is_typedarray|Checks whether the given JavaScript value is a **TypedArray**.| +|FUNC|napi_is_dataview|Checks whether the given JavaScript value is a **DataView**.| +|FUNC|napi_is_date|Checks whether the given JavaScript value is a JavaScript **Date** object.| +|FUNC|napi_strict_equals|Checks whether two JavaScript values are strictly equal.| +|FUNC|napi_get_property_names|Obtains the names of the enumerable properties of **Object** in an array of strings.| +|FUNC|napi_set_property|Sets a property for the given **Object**.| +|FUNC|napi_get_property|Obtains the requested property of the given **Object**.| +|FUNC|napi_has_property|Checks whether the given **Object** has the specified property.| +|FUNC|napi_delete_property|Deletes the **key** property from the given **Object**.| +|FUNC|napi_has_own_property|Checks whether the given **Object** has the own property named **key**.| +|FUNC|napi_set_named_property|Sets a property with the specified name for the given **Object**.| +|FUNC|napi_get_named_property|Obtains the property with the specified name in the given **Object**.| +|FUNC|napi_has_named_property|Checks whether the given **Object** has the property with the specified name.| +|FUNC|napi_set_element|Sets an element at the specified index of the given **Object**.| +|FUNC|napi_get_element|Obtains the element at the specified index of the given **Object**.| +|FUNC|napi_has_element|Obtains the element if the given **Object** has an element at the specified index.| +|FUNC|napi_delete_element|Deletes the element at the specified index of the given **Object**.| +|FUNC|napi_define_properties|Defines multiple properties for the given **Object**.| +|FUNC|napi_call_function|Calls a JavaScript function in a native method, that is, native call JavaScript.| +|FUNC|napi_create_function|Creates a native method for JavaScript to call.| +|FUNC|napi_get_cb_info|Obtains detailed information about the call, such as the parameters and **this** pointer, from the given callback info.| +|FUNC|napi_get_new_target|Obtains the **new.target** of the constructor call.| +|FUNC|napi_new_instance|Creates an instance based on the given constructor.| +|FUNC|napi_define_class|Defines a JavaScript class corresponding to the C++ class.| +|FUNC|napi_wrap|Wraps a native instance in a JavaScript object.| +|FUNC|napi_unwrap|Obtains the native instance that was previously wrapped in a JavaScript object.| +|FUNC|napi_remove_wrap|Obtains the native instance that was previously wrapped in a JavaScript object and removes the wrapping.| +|FUNC|napi_create_async_work|Creates a work object that executes logic asynchronously.| +|FUNC|napi_delete_async_work|Releases an asynchronous work object.| +|FUNC|napi_queue_async_work|Adds an asynchronous work object to the queue so that it can be scheduled for execution.| +|FUNC|napi_cancel_async_work|Cancels the queued asynchronous work if it has not been started.| +|FUNC|napi_get_node_version|Obtains the current Node-API version.| +|FUNC|napi_get_version|Obtains the latest Node-API version supported when the Node.js runtime.| +|FUNC|napi_create_promise|Creates a deferred object and a JavaScript promise.| +|FUNC|napi_resolve_deferred|Resolves a deferred object that is associated with a JavaScript promise.| +|FUNC|napi_reject_deferred|Rejects a deferred object that is associated with a JavaScript promise.| +|FUNC|napi_is_promise|Checks whether the given JavaScript value is a promise object.| +|FUNC|napi_run_script|Executes a string of JavaScript code.| +|FUNC|napi_get_uv_event_loop|Obtains the current libuv loop instance.| diff --git a/en/release-notes/changelogs/OpenHarmony_3.2.10.1/changelogs-distributeddatamgr.md b/en/release-notes/changelogs/OpenHarmony_3.2.10.1/changelogs-distributeddatamgr.md index df20e8b95ca67a47f89edf2fd6d6f4efa957bb07..3689b5c62fa100173b4b5579a38f5763b6535d23 100644 --- a/en/release-notes/changelogs/OpenHarmony_3.2.10.1/changelogs-distributeddatamgr.md +++ b/en/release-notes/changelogs/OpenHarmony_3.2.10.1/changelogs-distributeddatamgr.md @@ -79,8 +79,8 @@ function getRdbStoreV9(context: Context, config: StoreConfigV9, version: number) ``` The APIs are migrated from **@ohos.data.rdb.d.ts** to **@ohos.data.relationalStore.d.ts**. ``` -function getRdbStore(context: Context, config: StoreConfig, version: number, callback: AsyncCallback): void; -function getRdbStore(context: Context, config: StoreConfig, version: number): Promise; +function getRdbStore(context: Context, config: StoreConfig, callback: AsyncCallback): void; +function getRdbStore(context: Context, config: StoreConfig): Promise; ``` **Adaptation Guide** diff --git a/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-useriam.md b/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-useriam.md new file mode 100644 index 0000000000000000000000000000000000000000..a3abb3143332e234f4583eaffc95aed632cb5260 --- /dev/null +++ b/en/release-notes/changelogs/OpenHarmony_3.2.10.5/changelogs-useriam.md @@ -0,0 +1,17 @@ +# User IAM Subsystem ChangeLog + +## cl.useriam.1 API9 Authentication Result Code Class Name Change + +The name of the authentication result code class of user IAM API version 9 is changed from **ResultCode** to **UserAuthResultCode**. + +**Change Impacts** + +Applications developed based on earlier versions are not affected. For the applications developed from this version, the class name of the error code needs to be adapted. Otherwise, the service logic is affected. + +**Key API/Component Changes** + +N/A + +**Adaptation Guide** + +Change the class name for invoking the authentication result code from **ResultCode** to **UserAuthResultCode**. diff --git a/zh-cn/application-dev/application-models/Readme-CN.md b/zh-cn/application-dev/application-models/Readme-CN.md index 8cb463f4095fc47edbac1dfa6f969a116226ba9f..c2832d868702c9a10eef9ad2fb46377028bf34bb 100644 --- a/zh-cn/application-dev/application-models/Readme-CN.md +++ b/zh-cn/application-dev/application-models/Readme-CN.md @@ -20,6 +20,7 @@ - [DataShareExtensionAbility（仅对系统应用开放）](datashareextensionability.md) - [FormExtensionAbility（服务卡片）](widget-development-stage.md) - [StaticSubscriberExtensionAbility](static-subscriber-extension-ability.md) + - [WindowExtensionAbility](windowextensionability.md) - [AbilityStage组件容器](abilitystage.md) - [应用上下文Context](application-context-stage.md) - 信息传递载体Want diff --git a/zh-cn/application-dev/media/audio-capturer.md b/zh-cn/application-dev/media/audio-capturer.md index 2b06e586ff7e1fc6f8c2749d019f78f72efdf56b..542f5793ce8789c068c6f0203f08f308a711f56f 100644 --- a/zh-cn/application-dev/media/audio-capturer.md +++ b/zh-cn/application-dev/media/audio-capturer.md @@ -72,7 +72,7 @@ AudioCapturer提供了用于获取原始音频文件的方法。开发者可以 } await audioCapturer.start(); - let state = audioCapturer.state; + state = audioCapturer.state; if (state == audio.AudioState.STATE_RUNNING) { console.info('AudioRecLog: Capturer started'); } else { @@ -112,6 +112,7 @@ AudioCapturer提供了用于获取原始音频文件的方法。开发者可以 let numBuffersToCapture = 150; // 循环写入150次 while (numBuffersToCapture) { + let bufferSize = await audioCapturer.getBuffersize(); let buffer = await audioCapturer.read(bufferSize, true); if (typeof(buffer) == undefined) { console.info('AudioRecLog: read buffer failed'); diff --git a/zh-cn/application-dev/reference/apis/Readme-CN.md b/zh-cn/application-dev/reference/apis/Readme-CN.md index 20709bfbe3b5d4a797a81a5288095ad9727df1a1..4c5f786f6875f4c5f88669806d6a0baa1adfb275 100755 --- a/zh-cn/application-dev/reference/apis/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis/Readme-CN.md @@ -20,15 +20,9 @@ - [@ohos.application.StaticSubscriberExtensionAbility (StaticSubscriberExtensionAbility)](js-apis-application-staticSubscriberExtensionAbility.md) - Stage模型能力的接口(待停用) - [@ohos.application.Ability (Ability)](js-apis-application-ability.md) - - [@ohos.application.AbilityConstant (AbilityConstant)](js-apis-application-abilityConstant.md) - [@ohos.application.AbilityLifecycleCallback (AbilityLifecycleCallback)](js-apis-application-abilityLifecycleCallback.md) - - [@ohos.application.AbilityStage (AbilityStage)](js-apis-application-abilityStage.md) - - [@ohos.application.context (Context)](js-apis-application-context.md) - [@ohos.application.EnvironmentCallback (EnvironmentCallback)](js-apis-application-environmentCallback.md) - - [@ohos.application.ExtensionAbility (ExtensionAbility)](js-apis-application-extensionAbility.md) - [@ohos.application.FormExtension (FormExtension)](js-apis-application-formExtension.md) - - [@ohos.application.ServiceExtensionAbility (ServiceExtensionAbility)](js-apis-application-serviceExtensionAbility.md) - - [@ohos.application.StartOptions (StartOptions)](js-apis-application-startOptions.md) - FA模型能力的接口 - [@ohos.ability.ability (Ability)](js-apis-ability-ability.md) - [@ohos.ability.featureAbility (FeatureAbility模块)](js-apis-ability-featureAbility.md) @@ -341,6 +335,7 @@ - [@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)](js-apis-EnterpriseAdminExtensionAbility.md) - [@ohos.enterprise.adminManager (企业设备管理)](js-apis-enterprise-adminManager.md) - [@ohos.enterprise.dateTimeManager (系统时间管理)](js-apis-enterprise-dateTimeManager.md) + - [@ohos.enterprise.deviceControl (设备控制管理)](js-apis-enterprise-deviceControl.md) - 语言基础类库 - [@ohos.buffer (Buffer)](js-apis-buffer.md) diff --git a/zh-cn/application-dev/reference/apis/js-apis-appAccount.md b/zh-cn/application-dev/reference/apis/js-apis-appAccount.md index f7515a6528fb17cf94f2a8c86b339eaac4e1799e..139641fa905f04c7408df671ca8531993cdd3fce 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-appAccount.md +++ b/zh-cn/application-dev/reference/apis/js-apis-appAccount.md @@ -198,18 +198,23 @@ createAccountImplicitly(owner: string, callback: AuthCallback): void **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; - function onResultCallback(code, result) { console.log("resultCode: " + code); console.log("result: " + JSON.stringify(result)); } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err) => { + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { console.log("startAbility err: " + JSON.stringify(err)); - }); + }) } try { @@ -252,18 +257,23 @@ createAccountImplicitly(owner: string, options: CreateAccountImplicitlyOptions, **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; - function onResultCallback(code, result) { console.log("resultCode: " + code); console.log("result: " + JSON.stringify(result)); } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err) => { + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { console.log("startAbility err: " + JSON.stringify(err)); - }); + }) } let options = { @@ -1346,7 +1356,7 @@ auth(name: string, owner: string, authType: string, callback: AuthCallback): voi **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; + function onResultCallback(code, authResult) { console.log("resultCode: " + code); @@ -1354,10 +1364,17 @@ auth(name: string, owner: string, authType: string, callback: AuthCallback): voi } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err) => { - console.log("startAbility err: " + JSON.stringify(err)); - }); + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { + console.log("startAbility err: " + JSON.stringify(err)); + }) } try { @@ -1402,7 +1419,7 @@ auth(name: string, owner: string, authType: string, options: {[key: string]: Obj **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; + function onResultCallback(code, authResult) { console.log("resultCode: " + code); @@ -1410,10 +1427,17 @@ auth(name: string, owner: string, authType: string, options: {[key: string]: Obj } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err) => { - console.log("startAbility err: " + JSON.stringify(err)); - }); + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { + console.log("startAbility err: " + JSON.stringify(err)); + }) } let options = { @@ -2802,7 +2826,7 @@ addAccountImplicitly(owner: string, authType: string, options: {[key: string]: a **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; + function onResultCallback(code, result) { console.log("resultCode: " + code); @@ -2810,10 +2834,17 @@ addAccountImplicitly(owner: string, authType: string, options: {[key: string]: a } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { console.log("startAbility err: " + JSON.stringify(err)); - }); + }) } appAccountManager.addAccountImplicitly("com.example.accountjsdemo", "getSocialData", {}, { @@ -3750,18 +3781,23 @@ authenticate(name: string, owner: string, authType: string, options: {[key: stri **示例：** ```js - import featureAbility from '@ohos.ability.featureAbility'; - function onResultCallback(code, result) { console.log("resultCode: " + code); console.log("result: " + JSON.stringify(result)); } function onRequestRedirectedCallback(request) { - let abilityStartSetting = {want: request}; - featureAbility.startAbility(abilityStartSetting, (err)=>{ - console.log("startAbility err: " + JSON.stringify(err)); - }); + let wantInfo = { + deviceId: '', + bundleName: 'com.example.accountjsdemo', + action: 'ohos.want.action.viewData', + entities: ['entity.system.default'], + } + this.context.startAbility(wantInfo).then(() => { + console.log("startAbility successfully"); + }).catch((err) => { + console.log("startAbility err: " + JSON.stringify(err)); + }) } appAccountManager.authenticate("LiSi", "com.example.accountjsdemo", "getSocialData", {}, { @@ -4520,10 +4556,13 @@ getAuthenticatorInfo(owner: string): Promise<AuthenticatorInfo> | KEY_REQUIRED_LABELS9+ | "requiredLabels" | 表示键名，必需的标签。 | | KEY_BOOLEAN_RESULT9+ | "booleanResult" | 表示键名，布尔返回值。 | -## ResultCode8+ +## ResultCode(deprecated) 表示返回码的枚举。 +> **说明：**
+> 从API version 8开始支持，从API version 9开始废弃。建议查看[错误码文档](../errorcodes/errorcode-app-account.md)替代。 + **系统能力：** 以下各项对应的系统能力均为SystemCapability.Account.AppAccount。 | 名称 | 值 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-call.md b/zh-cn/application-dev/reference/apis/js-apis-call.md index 9d149f4c237e36173ea328f2a58a7e8223376be8..78c21552f22004a4eec28c0c42844ac14faf3a99 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-call.md +++ b/zh-cn/application-dev/reference/apis/js-apis-call.md @@ -4,7 +4,7 @@ 如需订阅通话状态请使用[`observer.on('callStateChange')`](js-apis-observer.md#observeroncallstatechange)。 ->**说明：** +>**说明：** > >本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 @@ -20,7 +20,7 @@ dial\(phoneNumber: string, callback: AsyncCallback\): void 拨打电话。使用callback异步回调。 -**需要权限**：ohos.permission.PLACE\_CALL，该权限为系统权限 +**需要权限**：ohos.permission.PLACE_CALL **系统能力**：SystemCapability.Telephony.CallManager @@ -46,7 +46,7 @@ dial\(phoneNumber: string, options: DialOptions, callback: AsyncCallback 拨打电话，可设置通话参数。使用Promise异步回调。 -**需要权限**：ohos.permission.PLACE\_CALL，该权限为系统权限 +**需要权限**：ohos.permission.PLACE_CALL **系统能力**：SystemCapability.Telephony.CallManager @@ -105,6 +105,133 @@ promise.then(data => { }); ``` + +## call.dialCall9+ + +dialCall\(phoneNumber: string, callback: AsyncCallback\): void + +拨打电话。使用callback异步回调。 + +**系统接口：** 此接口为系统接口。 + +**需要权限**：ohos.permission.PLACE_CALL + +**系统能力**：SystemCapability.Telephony.CallManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ---------------------------- | ---- | --------------------------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true为成功，false为失败。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + +**示例：** + +```js +call.dialCall("138xxxxxxxx", (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.dialCall9+ + +dialCall\(phoneNumber: string, options: DialCallOptions, callback: AsyncCallback\): void + +拨打电话，可设置通话参数。使用callback异步回调。 + +**系统接口：** 此接口为系统接口。 + +**需要权限**：ohos.permission.PLACE_CALL + +**系统能力**：SystemCapability.Telephony.CallManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ----------------------------------- | ---- | ------------------------------------ | +| phoneNumber | string | 是 | 电话号码。 | +| options | [DialCallOptions](#dialcalloptions9)| 是 | 通话参数，携带呼叫的其他配置信息。 | +| callback | AsyncCallback<boolean> | 是 | 回调函数，返回true为成功，false为失败。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + +**示例：** + +```js +call.dialCall("138xxxxxxxx", { + accountId: 0, + videoState: 0, + dialScene: 0, + dialType: 0, +}, (err, data) => { + console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); +}); +``` + + +## call.dialCall9+ + +dialCall\(phoneNumber: string, options?: DialCallOptions\): Promise + +拨打电话，可设置通话参数。使用Promise异步回调。 + +**系统接口：** 此接口为系统接口。 + +**需要权限**：ohos.permission.PLACE_CALL + +**系统能力**：SystemCapability.Telephony.CallManager + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ----------------------------------- | ---- | -------------------------------------- | +| phoneNumber | string | 是 | 电话号码。 | +| options | [DialCallOptions](#dialcalloptions9)| 否 | 通话参数，选择为语音通话还是视频通话。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + +**示例：** + +```js +try { + call.dialCall('138xxxxxxxx'); + console.log(`dialCall success, promise: data->${JSON.stringify(data)}`); +} catch (error) { + console.log(`dialCall fail, promise: err->${JSON.stringify(error)}`); +} +``` + + ## call.makeCall7+ makeCall(phoneNumber: string, callback: AsyncCallback\): void @@ -120,11 +247,21 @@ makeCall(phoneNumber: string, callback: AsyncCallback\): void | phoneNumber | string | 是 | 电话号码。 | | callback | AsyncCallback<void> | 是 | 以callback形式异步返回跳转拨号界面的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js -call.makeCall("138xxxxxxxx", err => { - console.log(`makeCall callback: err->${JSON.stringify(err)}`); +call.makeCall("138xxxxxxxx", err => { + console.log(`makeCall callback: err->${JSON.stringify(err)}`); }); ``` @@ -149,14 +286,24 @@ makeCall(phoneNumber: string): Promise\ | ------------------- | --------------------------------- | | Promise<void> | 以Promise形式异步返回拨号的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js -let promise = call.makeCall("138xxxxxxxx"); -promise.then(() => { - console.log(`makeCall success`); -}).catch(err => { - console.error(`makeCall fail, promise: err->${JSON.stringify(err)}`); +let promise = call.makeCall("138xxxxxxxx"); +promise.then(() => { + console.log(`makeCall success`); +}).catch(err => { + console.error(`makeCall fail, promise: err->${JSON.stringify(err)}`); }); ``` @@ -291,6 +438,16 @@ isEmergencyPhoneNumber\(phoneNumber: string, callback: AsyncCallback\) | phoneNumber | string | 是 | 电话号码。 | | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示是紧急电话号码，返回false表示不是紧急电话号码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -316,6 +473,16 @@ isEmergencyPhoneNumber\(phoneNumber: string, options: EmergencyNumberOptions, ca | options | [EmergencyNumberOptions](#emergencynumberoptions7) | 是 | 电话号码参数。 | | callback | AsyncCallback<boolean> | 是 | 回调函数。返回true表示是紧急电话号码，返回false表示不是紧急电话号码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -346,6 +513,16 @@ isEmergencyPhoneNumber\(phoneNumber: string, options?: EmergencyNumberOptions\): | ---------------------- | --------------------------------------------------- | | Promise<boolean> | 以Promise形式异步返回判断是否是紧急电话号码的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -374,6 +551,16 @@ formatPhoneNumber\(phoneNumber: string, callback: AsyncCallback\): void | phoneNumber | string | 是 | 电话号码。 | | callback | AsyncCallback<string> | 是 | 回调函数，返回格式化电话号码的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -400,6 +587,16 @@ formatPhoneNumber\(phoneNumber: string, options: NumberFormatOptions, callback: | options | [NumberFormatOptions](#numberformatoptions7) | 是 | 格式化参数，如国家码。 | | callback | AsyncCallback<string> | 是 | 回调函数，返回格式化电话号码的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -434,6 +631,16 @@ formatPhoneNumber\(phoneNumber: string, options?: NumberFormatOptions\): Promise | --------------------- | ------------------------------------------- | | Promise<string> | 以Promise形式异步返回格式化电话号码的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -465,6 +672,16 @@ formatPhoneNumberToE164\(phoneNumber: string, countryCode: string, callback: Asy | countryCode | string | 是 | 国家码，支持所有国家码，如：中国（CN）。 | | callback | AsyncCallback<string> | 是 | 回调函数，返回将电话号码格式化为E.164表示形式的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -499,6 +716,16 @@ formatPhoneNumberToE164\(phoneNumber: string, countryCode: string\): Promise\): void 如果来电铃声响起，设备将停止铃声。否则，此方法不起作用。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -528,6 +755,16 @@ muteRinger\(callback: AsyncCallback\): void | ----------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -543,7 +780,7 @@ muteRinger\(\): Promise 如果来电铃声响起，设备将停止铃声。否则，此方法不起作用。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -555,6 +792,17 @@ muteRinger\(\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -573,7 +821,7 @@ answer\(callId: number, callback: AsyncCallback\): void 接听来电。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -586,6 +834,17 @@ answer\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。可以通过订阅callDetailsChange事件获得。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -601,7 +860,7 @@ answer(callId?: number\): Promise 接听来电。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -619,6 +878,17 @@ answer(callId?: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -637,7 +907,7 @@ hangup\(callId: number, callback: AsyncCallback\): void 挂断电话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -650,6 +920,17 @@ hangup\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫id。可以通过订阅callDetailsChange事件获得。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -665,7 +946,7 @@ answer\(callback: AsyncCallback\): void 接听来电。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -677,6 +958,17 @@ answer\(callback: AsyncCallback\): void | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -692,7 +984,7 @@ hangup\(callId?: number\): Promise 挂断电话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -710,6 +1002,17 @@ hangup\(callId?: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -728,7 +1031,7 @@ hangup\(callback: AsyncCallback\): void 挂断电话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -740,6 +1043,18 @@ hangup\(callback: AsyncCallback\): void | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + + **示例：** ```js @@ -755,7 +1070,7 @@ reject(callId: number, callback: AsyncCallback\): void 拒绝来电。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -768,6 +1083,18 @@ reject(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。可以通过订阅callDetailsChange事件获得。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + + **示例：** ```js @@ -783,7 +1110,7 @@ reject\(callId: number, options: RejectMessageOptions, callback: AsyncCallback 拒绝来电。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -834,6 +1172,17 @@ reject(callId?: number, options?: RejectMessageOptions\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -855,7 +1204,7 @@ reject\(callback: AsyncCallback\): void 拒绝来电。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -867,6 +1216,17 @@ reject\(callback: AsyncCallback\): void | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -882,7 +1242,7 @@ reject\(options: RejectMessageOptions, callback: AsyncCallback\): void 拒绝来电。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -895,6 +1255,17 @@ reject\(options: RejectMessageOptions, callback: AsyncCallback\): void | options | [RejectMessageOptions](#rejectmessageoptions7) | 是 | 拒绝消息选项。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -913,7 +1284,7 @@ holdCall\(callId: number, callback: AsyncCallback\): void 保持通话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -926,6 +1297,17 @@ holdCall\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -941,7 +1323,7 @@ holdCall\(callId: number\): Promise 保持通话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -959,6 +1341,17 @@ holdCall\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -976,7 +1369,7 @@ unHoldCall\(callId: number, callback: AsyncCallback\): void 取消保持通话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -989,6 +1382,17 @@ unHoldCall\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1004,7 +1408,7 @@ unHoldCall\(callId: number\): Promise 取消保持通话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -1022,6 +1426,17 @@ unHoldCall\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1039,7 +1454,7 @@ switchCall\(callId: number, callback: AsyncCallback\): void 切换呼叫。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -1052,6 +1467,17 @@ switchCall\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1067,7 +1493,7 @@ switchCall\(callId: number\): Promise 切换呼叫。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.ANSWER_CALL @@ -1085,6 +1511,17 @@ switchCall\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1102,7 +1539,7 @@ combineConference\(callId: number, callback: AsyncCallback\): void 合并通话，将两通电话合并成会议电话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1113,6 +1550,16 @@ combineConference\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1128,7 +1575,7 @@ combineConference\(callId: number\): Promise 合并通话，将两通电话合并成会议电话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1144,6 +1591,16 @@ combineConference\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1161,7 +1618,7 @@ getMainCallId\(callId: number, callback: AsyncCallback\): void 获取主呼叫Id。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1172,6 +1629,17 @@ getMainCallId\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<number> | 是 | 回调函数。返回主呼叫Id。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + + **示例：** ```js @@ -1187,7 +1655,7 @@ getMainCallId\(callId: number\): Promise 获取主呼叫Id。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1203,6 +1671,16 @@ getMainCallId\(callId: number\): Promise | ------------------- | ------------------------------- | | Promise<void> | 以Promise形式异步返回主呼叫Id。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1220,7 +1698,7 @@ getSubCallIdList\(callId: number, callback: AsyncCallback\>\): vo 获取子呼叫Id列表。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1231,6 +1709,16 @@ getSubCallIdList\(callId: number, callback: AsyncCallback\>\): vo | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback\> | 是 | 回调函数。返回子呼叫Id列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1246,7 +1734,7 @@ getSubCallIdList\(callId: number\): Promise\> 获取子呼叫Id列表。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1262,6 +1750,16 @@ getSubCallIdList\(callId: number\): Promise\> | ----------------------------- | ----------------------------------- | | Promise<Array> | 以Promise形式异步返回子呼叫Id列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1279,7 +1777,7 @@ getCallIdListForConference\(callId: number, callback: AsyncCallback> | 是 | 回调函数。返回会议的呼叫Id列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1305,7 +1813,7 @@ getCallIdListForConference\(callId: number\): Promise\> 获取会议的呼叫Id列表。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1321,6 +1829,16 @@ getCallIdListForConference\(callId: number\): Promise\> | ----------------------------- | --------------------------------------- | | Promise<Array> | 以Promise形式异步返回会议的呼叫Id列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1338,7 +1856,7 @@ getCallWaitingStatus\(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<[CallWaitingStatus](#callwaitingstatus7)\> | 是 | 回调函数。
返回呼叫等待状态。
- 0：禁用呼叫等待
- 1：启用呼叫等待 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1366,7 +1895,7 @@ getCallWaitingStatus\(slotId: number\): Promise 获取呼叫等待状态。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.GET_TELEPHONY_STATE @@ -1384,6 +1913,17 @@ getCallWaitingStatus\(slotId: number\): Promise | ------------------------------------------------------- | ------------------------------------------------------------ | | Promise<[CallWaitingStatus](#callwaitingstatus7)> | 以Promise形式异步返回呼叫等待状态。
- 0：禁用呼叫等待
- 1：启用呼叫等待 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1401,7 +1941,7 @@ setCallWaiting\(slotId: number, activate: boolean, callback: AsyncCallback- false：禁用呼叫等待
- true：启用呼叫等待 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1430,7 +1981,7 @@ setCallWaiting\(slotId: number, activate: boolean\): Promise 设置呼叫等待。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1449,6 +2000,17 @@ setCallWaiting\(slotId: number, activate: boolean\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1466,7 +2028,7 @@ startDTMF\(callId: number, character: string, callback: AsyncCallback\): 启动双音多频。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1478,6 +2040,16 @@ startDTMF\(callId: number, character: string, callback: AsyncCallback\): | character | string | 是 | DTMF码。 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1493,7 +2065,7 @@ startDTMF\(callId: number, character: string\): Promise 启动双音多频。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1510,6 +2082,16 @@ startDTMF\(callId: number, character: string\): Promise | ------------------- | ----------------------- | | Promise<void> | 以Promise形式异步返回。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1527,7 +2109,7 @@ stopDTMF\(callId: number, callback: AsyncCallback\): void 停止双音多频。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1538,6 +2120,16 @@ stopDTMF\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1553,7 +2145,7 @@ stopDTMF\(callId: number\): Promise 停止双音多频。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1569,6 +2161,16 @@ stopDTMF\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1586,7 +2188,7 @@ isInEmergencyCall\(callback: AsyncCallback\): void 判断是否正在处于紧急呼叫。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1598,6 +2200,17 @@ isInEmergencyCall\(callback: AsyncCallback\): void | -------- | ---------------------------- | ---- | ---------- | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1613,7 +2226,7 @@ isInEmergencyCall\(\): Promise 判断是否正在处于紧急呼叫。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1625,6 +2238,17 @@ isInEmergencyCall\(\): Promise | ---------------------- | --------------------------- | | Promise<boolean> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1642,7 +2266,7 @@ on\(type: 'callDetailsChange', callback: Callback\): void 订阅callDetailsChange事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1655,6 +2279,17 @@ on\(type: 'callDetailsChange', callback: Callback\): void | type | string | 是 | 通话时监听通话详情的变化。 | | callback | Callback<[CallAttributeOptions](#callattributeoptions7)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1669,7 +2304,7 @@ on\(type: 'callEventChange', callback: Callback\): void 订阅callEventChange事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1682,6 +2317,17 @@ on\(type: 'callEventChange', callback: Callback\): void | type | string | 是 | 通话时监听通话事件的变化。 | | callback | Callback<[CallEventOptions](#calleventoptions8)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1696,7 +2342,7 @@ on\(type: 'callDisconnectedCause', callback: Callback): vo 订阅callDisconnectedCause事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1709,6 +2355,17 @@ on\(type: 'callDisconnectedCause', callback: Callback): vo | type | string | 是 | 通话时监听断开连接的原因。 | | callback | Callback<[DisconnectedDetails](#disconnecteddetails9)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1723,7 +2380,7 @@ on\(type: 'mmiCodeResult', callback: Callback\): void 订阅mmiCodeResult事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1736,6 +2393,17 @@ on\(type: 'mmiCodeResult', callback: Callback\): void | type | string | 是 | 通话时监听MMI码结果。 | | callback | Callback<[MmiCodeResults](#mmicoderesults9)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1750,7 +2418,7 @@ off\(type: 'callDetailsChange', callback?: Callback\): vo 取消订阅callDetailsChange事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1763,6 +2431,17 @@ off\(type: 'callDetailsChange', callback?: Callback\): vo | type | string | 是 | 通话结束时取消监听通话详情的变化。 | | callback | Callback<[CallAttributeOptions](#callattributeoptions7)> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1777,7 +2456,7 @@ off\(type: 'callEventChange', callback?: Callback\): void 取消订阅callEventChange事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1790,6 +2469,17 @@ off\(type: 'callEventChange', callback?: Callback\): void | type | string | 是 | 通话结束时取消监听通话事件的变化。 | | callback | Callback<[CallEventOptions](#calleventoptions8)> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1804,7 +2494,7 @@ off\(type: 'callDisconnectedCause', callback?: Callback\): 取消订阅callDisconnectedCause事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1817,6 +2507,17 @@ off\(type: 'callDisconnectedCause', callback?: Callback\): | type | 'callDisconnectedCause' | 是 | 调用断开连接的原因。 | | callback | Callback**<**[DisconnectedDetails](#disconnecteddetails9)> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1831,7 +2532,7 @@ off\(type: 'mmiCodeResult', callback?: Callback\): void 取消订阅mmiCodeResult事件。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -1844,6 +2545,17 @@ off\(type: 'mmiCodeResult', callback?: Callback\): void | type | 'mmiCodeResult' | 是 | MMI码结果。 | | callback | Callback<[MmiCodeResults](#mmicoderesults9)> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1858,7 +2570,7 @@ isNewCallAllowed\(callback: AsyncCallback\): void 判断是否允许再拨打一通新电话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1868,6 +2580,16 @@ isNewCallAllowed\(callback: AsyncCallback\): void | -------- | ---------------------------- | ---- | ---------- | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1883,7 +2605,7 @@ isNewCallAllowed\(\): Promise 判断是否允许再拨打一通新电话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1893,6 +2615,16 @@ isNewCallAllowed\(\): Promise | ---------------------- | --------------------------- | | Promise<boolean> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1910,7 +2642,7 @@ separateConference\(callId: number, callback: AsyncCallback\): void 分离会议电话。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1921,6 +2653,16 @@ separateConference\(callId: number, callback: AsyncCallback\): void | callId | number | 是 | 呼叫Id。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1936,7 +2678,7 @@ separateConference\(callId: number\): Promise 分离会议电话。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -1952,6 +2694,16 @@ separateConference\(callId: number\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1969,7 +2721,7 @@ getCallRestrictionStatus\(slotId: number, type: CallRestrictionType, callback: A 获取呼叫限制状态。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.GET_TELEPHONY_STATE @@ -1983,6 +2735,17 @@ getCallRestrictionStatus\(slotId: number, type: CallRestrictionType, callback: A | type | [CallRestrictionType](#callrestrictiontype8) | 是 | 呼叫限制类型。 | | callback | AsyncCallback<[RestrictionStatus](#restrictionstatus8)> | 是 | 回调函数。返回限制状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1998,7 +2761,7 @@ getCallRestrictionStatus\(slotId: number, type: CallRestrictionType\): Promise 设置呼叫限制状态。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2087,6 +2872,17 @@ setCallRestriction\(slotId: number, info: CallRestrictionInfo\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2109,7 +2905,7 @@ getCallTransferInfo\(slotId: number, type: CallTransferType, callback: AsyncCall 获取呼叫转移信息。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.GET_TELEPHONY_STATE @@ -2123,6 +2919,17 @@ getCallTransferInfo\(slotId: number, type: CallTransferType, callback: AsyncCall | type | [CallTransferType](#calltransfertype8) | 是 | 呼叫转移类型。 | | callback | AsyncCallback<[CallTransferResult](#calltransferresult8)> | 是 | 回调函数。返回呼叫转移信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2138,7 +2945,7 @@ getCallTransferInfo\(slotId: number, type: CallTransferType): Promise 设置呼叫转移信息。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2227,6 +3056,17 @@ setCallTransfer\(slotId: number, info: CallTransferInfo): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2249,7 +3089,7 @@ isRinging\(callback: AsyncCallback\): void 判断是否正在响铃。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2261,6 +3101,17 @@ isRinging\(callback: AsyncCallback\): void | -------- | ---------------------------- | ---- | ---------- | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2276,7 +3127,7 @@ isRinging\(\): Promise 判断是否正在响铃。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2288,6 +3139,17 @@ isRinging\(\): Promise | ---------------------- | --------------------------- | | Promise<boolean> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2305,7 +3167,7 @@ setMuted\(callback: AsyncCallback\): void 设置通话中的静音。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2315,6 +3177,16 @@ setMuted\(callback: AsyncCallback\): void | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2330,7 +3202,7 @@ setMuted\(\): Promise 设置通话中的静音。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2340,6 +3212,16 @@ setMuted\(\): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2357,7 +3239,7 @@ cancelMuted(callback: AsyncCallback): void 取消通话中的静音。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2367,6 +3249,16 @@ cancelMuted(callback: AsyncCallback): void | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2382,7 +3274,7 @@ cancelMuted(): Promise 取消通话中的静音。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2392,6 +3284,16 @@ cancelMuted(): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2409,7 +3311,7 @@ setAudioDevice\(device: AudioDevice, callback: AsyncCallback\): void 设置通话音频设备。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2420,6 +3322,16 @@ setAudioDevice\(device: AudioDevice, callback: AsyncCallback\): void | device | [AudioDevice](#audiodevice8) | 是 | 音频设备。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2435,7 +3347,7 @@ setAudioDevice\(device: AudioDevice, options: AudioDeviceOptions, callback: Asyn 设置通话音频设备。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2447,6 +3359,16 @@ setAudioDevice\(device: AudioDevice, options: AudioDeviceOptions, callback: Asyn | options | [AudioDeviceOptions](#audiodeviceoptions9) | 是 | 音频设备参数。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2465,7 +3387,7 @@ setAudioDevice(device: AudioDevice, options?: AudioDeviceOptions): Promise, callback: Asy 加入会议。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2514,6 +3446,16 @@ joinConference(mainCallId: number, callNumberList: Array, callback: Asy | callNumberList | Array | 是 | 呼叫号码列表。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2531,7 +3473,7 @@ joinConference(mainCallId: number, callNumberList: Array): Promise): Promise 更新Ims呼叫模式。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2611,6 +3573,16 @@ updateImsCallMode(callId: number, mode: ImsCallMode): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2628,7 +3600,7 @@ enableImsSwitch(slotId: number, callback: AsyncCallback): void 启用Ims开关。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2641,6 +3613,17 @@ enableImsSwitch(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2655,7 +3638,7 @@ enableImsSwitch(slotId: number): Promise 启用Ims开关。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2673,6 +3656,17 @@ enableImsSwitch(slotId: number): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2690,7 +3684,7 @@ disableImsSwitch(slotId: number, callback: AsyncCallback): void 禁用Ims开关。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2703,6 +3697,17 @@ disableImsSwitch(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2717,7 +3722,7 @@ disableImsSwitch(slotId: number): Promise 禁用Ims开关。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **需要权限**：ohos.permission.SET_TELEPHONY_STATE @@ -2735,6 +3740,17 @@ disableImsSwitch(slotId: number): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2752,7 +3768,7 @@ isImsSwitchEnabled(slotId: number, callback: AsyncCallback): void 判断Ims开关是否启用。使用callback异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2763,6 +3779,16 @@ isImsSwitchEnabled(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2777,7 +3803,7 @@ isImsSwitchEnabled(slotId: number): Promise 判断Ims开关是否启用。使用Promise异步回调。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：SystemCapability.Telephony.CallManager @@ -2793,6 +3819,16 @@ isImsSwitchEnabled(slotId: number): Promise | ------------------- | --------------------------- | | Promise<void> | 以Promise形式异步返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2810,13 +3846,26 @@ promise.then(data => { **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 +| 名称 | 类型 | 必填 | 说明 | +| ------------------------ | ---------------------------------- | ---- | ----------------------------------------------------------------------------------------------- | +| extras | boolean | 否 | 根据extras的值判断是否为视频通话，默认为语音通话。
- true：视频通话。
- false：语音通话。 | +| accountId 8+ | number | 否 | 帐户Id。
- 0：卡槽1
- 1：卡槽2
此接口为系统接口。 | +| videoState 8+ | [VideoStateType](#videostatetype7) | 否 | 视频状态类型。此接口为系统接口。 | +| dialScene 8+ | [DialScene](#dialscene8) | 否 | 拨号场景。此接口为系统接口。 | +| dialType 8+ | [DialType](#dialtype8) | 否 | 拨号类型。此接口为系统接口。 | + +## DialCallOptions9+ + +拨打电话的可选参数。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 + | 名称 | 类型 | 必填 | 说明 | | ------------------------ | ---------------------------------- | ---- | ------------------------------------------------------------ | -| extras | boolean | 否 | 根据extras的值判断是否为视频通话，默认为语音通话。
- true：视频通话。
- false：语音通话。 | -| accountId 8+ | number | 否 | 帐户Id。
- 0：卡槽1
- 1：卡槽2
此接口为系统接口。 | -| videoState 8+ | [VideoStateType](#videostatetype7) | 否 | 视频状态类型。此接口为系统接口。 | -| dialScene 8+ | [DialScene](#dialscene8) | 否 | 拨号场景。此接口为系统接口。 | -| dialType 8+ | [DialType](#dialtype8) | 否 | 拨号类型。此接口为系统接口。 | +| accountId 9+ | number | 否 | 帐户Id。
- 0：卡槽1
- 1：卡槽2
此接口为系统接口。| +| videoState 9+ | [VideoStateType](#videostatetype7) | 否 | 视频状态类型。此接口为系统接口。 | +| dialScene 9+ | [DialScene](#dialscene8) | 否 | 拨号场景。此接口为系统接口。 | +| dialType 9+ | [DialType](#dialtype8) | 否 | 拨号类型。此接口为系统接口。 | ## CallState @@ -2855,7 +3904,7 @@ promise.then(data => { IP多媒体系统调用模式。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2871,7 +3920,7 @@ IP多媒体系统调用模式。 音频设备。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2887,7 +3936,7 @@ IP多媒体系统调用模式。 呼叫限制类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2906,7 +3955,7 @@ IP多媒体系统调用模式。 呼叫转移信息。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2924,7 +3973,7 @@ IP多媒体系统调用模式。 呼叫转移类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2939,7 +3988,7 @@ IP多媒体系统调用模式。 设置呼叫转移类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2954,7 +4003,7 @@ IP多媒体系统调用模式。 调用属性选项。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2975,7 +4024,7 @@ IP多媒体系统调用模式。 会议状态。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -2990,7 +4039,7 @@ IP多媒体系统调用模式。 通话类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3005,7 +4054,7 @@ IP多媒体系统调用模式。 视频状态类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3018,7 +4067,7 @@ IP多媒体系统调用模式。 详细的呼叫状态。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3038,7 +4087,7 @@ IP多媒体系统调用模式。 呼叫限制信息。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3052,7 +4101,7 @@ IP多媒体系统调用模式。 呼叫限制模式。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3065,7 +4114,7 @@ IP多媒体系统调用模式。 呼叫事件的可选参数。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3077,7 +4126,7 @@ IP多媒体系统调用模式。 呼叫能力事件Id。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3090,7 +4139,7 @@ IP多媒体系统调用模式。 拨号场景。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3104,7 +4153,7 @@ IP多媒体系统调用模式。 拨号类型。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3118,7 +4167,7 @@ IP多媒体系统调用模式。 拒绝消息可选参数。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3130,7 +4179,7 @@ IP多媒体系统调用模式。 呼叫转移结果。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3147,7 +4196,7 @@ IP多媒体系统调用模式。 呼叫等待状态。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3160,7 +4209,7 @@ IP多媒体系统调用模式。 限制状态。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3173,7 +4222,7 @@ IP多媒体系统调用模式。 转移状态。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3186,7 +4235,7 @@ IP多媒体系统调用模式。 通话结束原因。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3199,7 +4248,7 @@ IP多媒体系统调用模式。 断开连接的详细信息。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3289,7 +4338,7 @@ IP多媒体系统调用模式。 MMI码结果。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3302,7 +4351,7 @@ MMI码结果。 MMI码结果。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 @@ -3315,7 +4364,7 @@ MMI码结果。 音频设备选项。 -此接口为系统接口。 +**系统接口：** 此接口为系统接口。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CallManager。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md index 64c706d77b7de28ef13e9a4da2580cd076ea0607..ba5f0890e965eae69492c42dfc7014a059c85161 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md +++ b/zh-cn/application-dev/reference/apis/js-apis-cryptoFramework.md @@ -1,2651 +1,2683 @@ -# @ohos.security.cryptoFramework (加解密算法库框架) - -为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。 - -> **说明：** -> -> 本模块首批接口从API version 9开始支持。 - -## 导入模块 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" -``` - -## Result - - 表示执行结果的枚举。 - - **系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 值 | 说明 | -| ------------------------------------- | -------- | ---------------------------- | -| INVALID_PARAMS | 401 | 非法入参。 | -| NOT_SUPPORT | 801 | 操作不支持。 | -| ERR_OUT_OF_MEMORY | 17620001 | 内存错误。 | -| ERR_RUNTIME_ERROR | 17620002 | 运行时外部错误。 | -| ERR_CRYPTO_OPERATION | 17630001 | 调用三方算法库API出错。 | - -## DataBlob - -buffer数组。 - - **系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ---- | ---------- | ---- | ---- | ------ | -| data | Uint8Array | 是 | 是 | 数据。 | - - -## cryptoFramework.createMac - -createMac(algName : string) : Mac - -生成Mac实例，用于进行消息认证码的计算与操作 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512 | - -**返回值**： - -| 类型 | 说明 | -| ---- | --------------------------------------- | -| Mac | 返回由输入算法指定生成的[Mac](#mac)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - // 参数选择请参考上述算法支持范围 - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Mac - -Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过[createMac](#cryptoframeworkcreatemac)构造Mac实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------- | -| algName | string | 是 | 否 | 代表指定的摘要算法名 | - -### init - -init(key : SymKey, callback : AsyncCallback\) : void; - -使用对称密钥初始化Mac计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ------------ | -| key | [SymKey](#symkey) | 是 | 共享对称密钥 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { - if (err) { - console.error("[Callback] err: " + err.code); - } - mac.init(symKey, (err1, ) => { - if (err1) { - console.error("[Callback] err: " + err1.code); - } - }); -}); -``` - -### init - -init(key : SymKey) : Promise\; - -使用对称密钥初始化Mac计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------ | -| key | [SymKey](#symkey) | 是 | 共享对称密钥 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); - -``` - -### update - -update(input : DataBlob, callback : AsyncCallback\) : void; - -传入消息进行Mac更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| input | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var KeyBlob; -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { - if (err) { - console.error("[Callback] err: " + err.code); - } - mac.init(symKey, (err1, ) => { - if (err1) { - console.error("[Callback] err: " + err1.code); - } - let blob; - mac.update(blob, (err2, data) => { - if (err2) { - console.error("[Callback] err: " + err2.code); - } - }); - }); -}); -``` - -### update - -update(input : DataBlob) : Promise\; - -传入消息进行Mac更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| input | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); - -``` - -### doFinal - -doFinal(callback : AsyncCallback\) : void; - -返回Mac的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------- | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var KeyBlob; -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { - if (err) { - console.error("[Callback] err: " + err.code); - } - mac.init(symKey, (err1, ) => { - if (err1) { - console.error("[Callback] err: " + err1.code); - } - let blob; - mac.update(blob, (err2, ) => { - if (err2) { - console.error("[Callback] err: " + err2.code); - } - mac.doFinal((err3, macOutput) => { - if (err3) { - console.error("[Callback] err: " + err3.code); - } else { - console.error("[Promise]: HMAC result: " + macOutput); - } - }); - }); - }); -}); -``` - -### doFinal - -doFinal() : Promise\ - -返回Mac的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).then(() => { - var PromiseMacDoFinal = mac.doFinal(); - return PromiseMacDoFinal; -}).then(macOutput => { - console.error("[Promise]: HMAC result: " + macOutput.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### getMacLength - -getMacLength() : number - -获取Mac消息认证码的长度（字节数） - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------ | ------------------------- | -| number | 返回mac计算结果的字节长度 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var mac; -try { - mac = cryptoFramework.createMac("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Mac algName is: " + mac.algName); - -var KeyBlob; -var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); -var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); -promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; -}).then(() => { - let blob; - var promiseMacUpdate = mac.update(blob); - return promiseMacUpdate; -}).then(() => { - var PromiseMacDoFinal = mac.doFinal(); - return PromiseMacDoFinal; -}).then(macOutput => { - console.error("[Promise]: HMAC result: " + macOutput.data); - let macLen = mac.getMacLength(); - console.error("MAC len: " + macLen); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -## cryptoFramework.createMd - -createMd(algName : string) : Md - -生成Md实例，用于进行消息摘要的计算与操作 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定摘要算法，支持算法范围：SHA1/SHA224/SHA256/SHA384/SHA512/MD5 | - -**返回值**： - -| 类型 | 说明 | -| ---- | ------------------------------------- | -| Md | 返回由输入算法指定生成的[Md](#md)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - // 参数选择请参考上述算法支持范围 - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Md - -Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过[createMd](#cryptoframeworkcreatemd)构造Md实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------- | -| algName | string | 是 | 否 | 代表指定的摘要算法名 | - -### update - -update(input : DataBlob, callback : AsyncCallback\) : void; - -传入消息进行Md更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| input | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -md.update(blob, (err,) => { - if (err) { - console.error("[Callback] err: " + err.code); - } -}); -``` - -### update - -update(input : DataBlob) : Promise\; - -传入消息进行Md更新计算 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| input | DataBlob | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - // do something -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### digest - -digest(callback : AsyncCallback\) : void - -返回Md的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------- | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -md.update(blob, (err,) => { - if (err) { - console.error("[Callback] err: " + err.code); - } - md.digest((err1, mdOutput) => { - if (err1) { - console.error("[Callback] err: " + err1.code); - } else { - console.error("[Callback]: MD result: " + mdOutput); - } - }); -}); -``` - -### digest - -digest() : Promise\ - -返回Md的计算结果 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - var PromiseMdDigest = md.digest(); - return PromiseMdDigest; -}).then(mdOutput => { - console.error("[Promise]: MD result: " + mdOutput.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### getMdLength - -getMdLength() : number - -获取Md消息摘要长度（字节数） - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ------ | ------------------------ | -| number | 返回md计算结果的字节长度 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var md; -try { - md = cryptoFramework.createMd("SHA256"); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -console.error("Md algName is: " + md.algName); - -let blob; -var promiseMdUpdate = md.update(blob); -promiseMdUpdate.then(() => { - var PromiseMdDigest = md.digest(); - return PromiseMdDigest; -}).then(mdOutput => { - console.error("[Promise]: MD result: " + mdOutput.data); - let mdLen = md.getMdLength(); - console.error("MD len: " + mdLen); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -## cryptoFramework.createRandom - -createRandom() : Random - -生成Random实例，用于进行随机数的计算与设置种子 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值**： - -| 类型 | 说明 | -| ------ | --------------------------------------------- | -| Random | 返回由输入算法指定生成的[Random](#random)对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------ | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -try { - var rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -``` - -## Random - -Random类，调用Random方法可以进行随机数计算。调用前，需要通过[createRandom](#cryptoframeworkcreaterandom)构造Random实例。 - -### generateRandom - -generateRandom(len : number, callback: AsyncCallback\) : void; - -生成指定长度的随机数 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | -------------------- | -| len | number | 是 | 表示生成随机数的长度 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} -rand.generateRandom(12, (err, randData) => { - if (err) { - console.error("[Callback] err: " + err.code); - } else { - console.error("[Callback]: generate random result: " + randData.data); - } -}); -``` - -### generateRandom - -generateRandom(len : number) : Promise\; - -生成指定长度的随机数 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | -------------------- | -| len | number | 是 | 表示生成随机数的长度 | - -**返回值：** - -| 类型 | 说明 | -| ------------------ | ----------- | -| Promise\<[DataBlob](#datablob)> | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17630001 | crypto operation error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} - -var promiseGenerateRand = rand.generateRandom(12); -promiseGenerateRand.then(randData => { - console.error("[Promise]: rand result: " + randData.data); -}).catch(error => { - console.error("[Promise]: error: " + error.message); -}); -``` - -### setSeed - -setSeed(seed : DataBlob) : void; - -设置指定的种子 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------- | ---- | ---------- | -| seed | DataBlob | 是 | 设置的种子 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ----------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -var rand; -try { - rand = cryptoFramework.createRandom(); -} catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); -} - -rand.generateRandom(12, (err, randData) => { - if (err) { - console.error("[Callback] err: " + err.code); - } else { - console.error("[Callback]: generate random result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - } -}); -``` - -## ParamsSpec - -加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入[init()](#init-2)方法。
适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在[init()](#init-2)中传入null即可）。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| -------- | ------ | ---- | ---- | ----------------------- | -| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | - -> **说明：** -> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 - -## IvParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## GcmParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于GCM模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节 | -| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | -| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。
采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾16字节作为解密时[init()](#init-2)方法的入参[GcmParamsSpec](#gcmparamsspec)中的的authTag | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## CcmParamsSpec - -加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CCM模式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | -| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 | -| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | -| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。
采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾12字节作为解密时[init()](#init-2)方法的入参[CcmParamsSpec](#ccmparamsspec)中的authTag | - -> **说明：** -> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 - -## CryptoMode - -表示加解密操作的枚举。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 值 | 说明 | -| ------------ | ---- | ---------------- | -| ENCRYPT_MODE | 0 | 表示进行加密操作 | -| DECRYPT_MODE | 1 | 表示进行解密操作 | - -## Key - -密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入[Cipher](#cipher)实例的[init()](#init-2)方法。
密钥可以通过密钥生成器来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取16进制形式的密钥内容。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -import cryptoFramework from "@ohos.security.cryptoFramework" -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 -let encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -## SymKey - -对称密钥，是[Key](#key)的子类，在对称加解密时需要将其对象传入[Cipher](#cipher)实例的[init()](#init-2)方法使用。
对称密钥可以通过对称密钥生成器[SymKeyGenerator](#symkeygenerator)来生成。 - -### clearMem - -clearMem() : void - -以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**示例：** - -```js -import cryptoFramework from "@ohos.security.cryptoFramework" -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 -let encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出密钥内容 -key.clearMem(); -encodedKey = key.getEncoded(); -console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全零 -``` - -## PubKey - -公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。
公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 -console.info("key format:" + key.format); -console.info("key algName:" + key.algName); -var encodedKey = key.getEncoded(); -console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -## PriKey - -私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。
私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| format | string | 是 | 否 | 密钥的格式。 | -| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | - -### getEncoded - -getEncoded() : DataBlob - -以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------- | ------------------------ | -| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | - -**示例：** - -```js -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 -console.info("key format:" + key.format); -console.info("key algName:" + key.algName); -var encodedKey = key.getEncoded(); -console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); -``` - -### clearMem - -clearMem() : void - -以同步方法，将系统底层内存中的的密钥内容清零。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**示例：** - -```js -let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 -key.clearMem(); -``` - -## KeyPair - -非对称密钥对，包含：公钥与私钥，。
可以通过非对称密钥生成器AsyKeyGenerator来生成。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ------------ | -| priKey | [PriKey](#prikey) | 是 | 否 | 私钥。 | -| pubKey | [PubKey](#pubkey) | 是 | 否 | 公钥。 | - - -## cryptoFramework.createSymKeyGenerator - -createSymKeyGenerator(algName : string) : SymKeyGenerator - -通过指定算法名称的字符串，获取相应的对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 待生成对称密钥生成器的算法名称。
具体取值详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中的“字符串参数”。 | - -**返回值：** - -| 类型 | 说明 | -| ----------------------------------- | -------------------------- | -| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); -``` - -## SymKeyGenerator - -对称密钥生成器。
在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ------------------------------ | -| algName | string | 是 | 否 | 对称密钥生成器指定的算法名称。 | - -### generateSymKey - -generateSymKey(callback : AsyncCallback\) : void - -异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | -| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symAlgName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); -symKeyGenerator.generateSymKey((err, symKey) => { - if (err) { - console.error(`Generate symKey failed, ${err.code}, ${err.message}`); - } else { - console.info(`Generate symKey success, algName: ${symKey.algName}`); - } -}) -``` - -### generateSymKey - -generateSymKey() : Promise\ - -异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| --------------------------- | --------------------------------- | -| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symAlgName = 'AES128'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); -symKeyGenerator.generateSymKey() -.then(symKey => { - console.info(`Generate symKey success, algName: ${symKey.algName}`); -}, error => { - console.error(`Generate symKey failed, ${error.code}, ${error.message}`); -}) -``` - -### convertKey - -convertKey(key : DataBlob, callback : AsyncCallback\) : void - -异步根据指定数据生成对称密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | -| key | [DataBlob](#datablob) | 是 | 指定的对称密钥材料。 | -| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - -let symAlgName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); -let keyMaterialBlob = genKeyMaterialBlob(); -symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => { - if (err) { - console.error(`Convert symKey failed, ${err.code}, ${err.message}`); - } else { - console.info(`Convert symKey success, algName: ${symKey.algName}`); - } -}) -``` - -### convertKey - -convertKey(key : DataBlob) : Promise\ - -异步根据指定数据生成对称密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| key | [DataBlob](#datablob) | 是 | 指定的密钥材料数据。 | - -**返回值：** - -| 类型 | 说明 | -| --------------------------- | --------------------------------- | -| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------- | -| 17620001 | memory error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - -let symAlgName = '3DES192'; -let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); -let keyMaterialBlob = genKeyMaterialBlob(); -symKeyGenerator.convertKey(keyMaterialBlob) -.then(symKey => { - console.info(`Convert symKey success, algName: ${symKey.algName}`); -}, error => { - console.error(`Convert symKey failed, ${error.code}, ${error.message}`); -}) -``` - -## cryptoFramework.createAsyKeyGenerator - -createAsyKeyGenerator(algName : string) : AsyKeyGenerator - -通过指定算法名称的字符串，获取相应的非对称密钥生成器实例。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | -------------------------------- | -| algName | string | 是 | 待生成对称密钥生成器的算法名称。 | - -**返回值：** - -| 类型 | 说明 | -| --------------- | ---------------------------- | -| [AsyKeyGenerator](#asykeygenerator) | 返回非对称密钥生成器的对象。 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -``` - -## AsyKeyGenerator - -非对称密钥生成器。在使用该类的方法前，需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | -------------------------------- | -| algName | string | 是 | 否 | 非对称密钥生成器指定的算法名称。 | - -### generateKeyPair - -generateKeyPair(callback : AsyncCallback\) : void; - -异步获取非对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------- | ---- | ------------------------------ | -| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -asyKeyGenerator.generateKeyPair((err, keyPair) => { - if (err) { - console.error("generateKeyPair: error."); - return; - } - console.info("generateKeyPair: success."); -}) -``` - - -### generateKeyPair - -generateKeyPair() : Promise\ - -异步获取该非对称密钥生成器随机生成的密钥，通过Promise获取结果。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**返回值：** - -| 类型 | 说明 | -| ----------------- | --------------------------------- | -| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -let keyGenPromise = asyKeyGenerator.generateKeyPair(); -keyGenPromise.then( keyPair => { - console.info("generateKeyPair success."); -}).catch(error => { - console.error("generateKeyPair error."); -}); -``` - -### convertKey - -convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void - -异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明** - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------- | ---- | ------------------------------ | -| pubKey | [DataBlob](#datablob) | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null。 | -| priKey | [DataBlob](#datablob) | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null。 | -| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" -let pubKey; // X.509规范、DER格式的公钥数据，此处省略数据。 -let priKey; // PKCS#8规范、DER格式的私钥数据，此处省略数据。 -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => { - if (err) { - console.error("convertKey: error."); - return; - } - console.info("convertKey: success."); -}) -``` - -### convertKey - -convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ - -异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明** - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------------- | -| pubKey | DataBlob | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null | -| priKey | DataBlob | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null | - -**返回值：** - -| 类型 | 说明 | -| ----------------- | --------------------------------- | -| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); -let pubKey; // pubKey为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 -let priKey; // priKey为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 -let keyGenPromise = asyKeyGenerator.convertKey(pubKey, priKey); -keyGenPromise.then( keyPair => { - console.info("convertKey success."); -}).catch(error => { - console.error("convertKey error."); -}); -``` - -**密钥转换说明** - -1. 非对称密钥（RSA、ECC）的公钥和私钥调用getEncoded()方法后，分别返回X.509格式和PKCS#8格式的二进制数据，此数据可用于跨应用传输或持久化存储。 -2. 当调用convertKey方法将外来二进制数据转换为算法库非对称密钥对象时，公钥应满足ASN.1语法、X.509规范、DER编码格式，私钥应满足ASN.1语法、PKCS#8规范、DER编码格式。 -3. convertKey方法中，公钥和密钥二进制数据非必选项，可单独传入公钥或私钥的数据，生成对应只包含公钥或私钥的KeyPair对象。 - -## cryptoFramework.createCipher - -createCipher(transformation : string) : Cipher - -通过指定算法名称，获取相应的[Cipher](#cipher)实例。
支持的规格详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------------- | ------ | ---- | ------------------------------------------------------------ | -| transformation | string | 是 | 待生成Cipher的算法名称（含密钥长度）、加密模式以及填充方法的组合。
具体取值详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“字符串参数”。 | - -> **说明：** -> 1. 目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。
开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。 -> 2. 使用RSA进行非对称加解密时，必须创建两个Cipher对象分别进行加密和解密操作，而不能对同一个Cipher对象进行加解密。对称加解密没有此要求（即只要算法规格一样，可以对同一个Cipher对象进行加解密操作）。 - -**返回值：** - -| 类型 | 说明 | -| ----------------- | ------------------------ | -| [Cipher](#cipher) | 返回加解密生成器的对象。 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let cipherAlgName = '3DES192|ECB|PKCS7'; -var cipher; -try { - cipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${cipher.algName}`); -} catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); -} -``` - -## Cipher - -提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。
完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 - -一次完整的加/解密流程在对称加密和非对称加密中略有不同： - -- 对称加解密：init为必选，update为可选（且允许多次update加/解密大数据），doFinal为必选；doFinal结束后可以重新init开始新一轮加/解密流程。 -- RSA非对称加解密：init为必选，不支持update操作，doFinal为必选（允许连续多次doFinal加/解密大数据）；RSA不支持重复init，切换加解密模式或填充方式时，需要重新创建Cipher对象。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| algName | string | 是 | 否 | 加解密生成器指定的算法名称。 | - -### init - -init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void - -初始化加解密的[cipher](#cipher)对象，通过注册回调函数获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------- | ---- | ------------------------------------------------------------ | -| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | -| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | -| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | -| callback | AsyncCallback\ | 是 | 回调函数。当初始化成功，err为undefined，否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | --------------------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error.| - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symKey; // 此处省略生成对称密钥的过程 -let cipher; // 此处省略生成cipher实例的过程 - -cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => { - if (err) { - console.error(`Failed to init cipher, ${err.code}, ${err.message}`); - } else { - console.info(`Init cipher success`); - // 此处进行update等后续操作 - } -}) -``` - -### init - -init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\ - -初始化加解密的cipher对象，通过Promise获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------------------------- | ---- | ------------------------------------------------------------ | -| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | -| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | -| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | -------------------------------------- | -| Promise\ | Promise对象。无返回结果的Promise对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error.| - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; -let symKey; // 此处省略生成对称密钥的过程 -let cipher; // 此处省略生成cipher实例的过程 -cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null) -.then(() => { - console.info(`Init cipher success`); - // 此处进行update等后续操作 -}, error => { - console.error(`Failed to init cipher, ${error.code}, ${error.message}`); -}) -``` - -### update - -update(data : DataBlob, callback : AsyncCallback\) : void - -分段更新加密或者解密数据操作，通过注册回调函数获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 - -> **说明：** -> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） -> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。 -> 3. RSA非对称加解密不支持update操作。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当更新加/解密数据成功，err为undefined，data为此次更新的加/解密结果DataBlob；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -let cipher; // 此处省略生成cipher实例的过程 -// 此处省略init()过程 -let plainText = {data : stringToUint8Array('this is test!')}; -cipher.update(plainText, (err, output) => { // 加密过程举例 - if (err) { - console.error(`Failed to update cipher`); - } else { - console.info(`Update cipher success`); - if (output != null) { - // 拼接output.data到密文 - } - // 此处进行doFinal等后续操作 - } -}) -``` - -### update - -update(data : DataBlob) : Promise\ - -分段更新加密或者解密数据操作，通过通过Promise获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 - -> **说明：** -> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） -> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。 -> 3. RSA非对称加解密不支持update操作。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------- | ------------------------------------------------ | -| Promise\<[DataBlob](#datablob)> | Promise对象，返回此次更新的加/解密结果DataBlob。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -let cipher; // 此处省略生成cipher实例的过程 -// 此处省略init()过程 -let plainText = {data : stringToUint8Array('this is test!')}; -cipher.update(plainText) -.then((output) => { - console.info(`Update cipher success.`); - if (output != null) { - // 拼接output.data到密文 - } - // 此处进行doFinal等后续操作 -}, error => { - console.info(`Update cipher failed.`); -}) -``` - -### doFinal - -doFinal(data : DataBlob, callback : AsyncCallback\) : void - -（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： - -- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 -- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 - -（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 - -> **说明：** -> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 -> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。在对称加解密中允许为null，但不允许传入{data : Uint8Array(空) }。 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当最终加/解密数据成功，err为undefined，data为剩余数据的加/解密结果DataBlob；否则为错误对象。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ----------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -let cipher; // 此处省略生成cipher实例的过程 -let data; // 此处省略准备待加密/解密数据的过程 -// 此处省略init()和update()过程 -cipher.doFinal(data, (err, output) => { - if (err) { - console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`); - } else { - console.info(`Finalize cipher success`); - if (output != null) { - // 拼接output.data得到完整的明文/密文(及authTag) - } - } -}) -``` - -### doFinal - -doFinal(data : DataBlob) : Promise\ - -（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过Promise获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： - -- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 -- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 - -（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 - -> **说明：** -> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 -> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ---- | --------------------- | ---- | -------------------- | -| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data参数允许为null，但不允许传入{data : Uint8Array(空) } | - -**返回值：** - -| 类型 | 说明 | -| ------------------------------- | ------------------------------------------------ | -| Promise\<[DataBlob](#datablob)> | Promise对象，返回剩余数据的加/解密结果DataBlob。 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | -------------------------------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**示例：** - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -let cipher; // 此处省略生成cipher实例的过程 -let data; // 此处省略准备待加密/解密数据的过程 -// 此处省略init()和update()过程 -cipher.doFinal(data) -.then(output => { - console.info(`Finalize cipher success`); - if (output != null) { - // 拼接output.data得到完整的明文/密文(及authTag) - } -}, error => { - console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`); -}) -``` - -**使用RSA加密的callback完整示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); -let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); -rsaGenerator.generateKeyPair(function (err, keyPair) { - let pubKey = keyPair.pubKey; - cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) { - let plainText = "this is cipher text"; - let input = {data : stringToUint8Array(plainText) }; - cipher.doFinal(input, function (err, data) { - AlertDialog.show({ message : "EncryptOutPut is " + data.data} ); - }); - }); -}); -``` - -**使用RSA加密的promise完整示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); -let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); -let keyGenPromise = rsaGenerator.generateKeyPair(); -keyGenPromise.then(rsaKeyPair => { - let pubKey = rsaKeyPair.pubKey; - return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // 传入私钥和DECRYPT_MODE可初始化解密模式 -}).then(() => { - let plainText = "this is cipher text"; - let input = { data : stringToUint8Array(plainText) }; - return cipher.doFinal(input); -}).then(dataBlob => { - console.info("EncryptOutPut is " + dataBlob.data); -}); -``` - -> **说明：** -> 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 - -## cryptoFramework.createSign - -createSign(algName : string) : Sign - -Sign实例生成 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | - -**返回值**： - -| 类型 | 说明 | -| ---- | -------------------------------- | -| Sign | 返回由输入算法指定生成的Sign对象 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); - -let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256") -``` - -## Sign - -Sign类，使用Sign方法之前需要创建该类的实例进行操作，通过createSign(algName : string) : Sign方法构造此实例。Sign类不支持重复初始化，当业务方需要使用新密钥签名时，需要重新创建新Sign对象并调用init初始化。 - -业务方使用时，在createSign时确定签名的模式，调用init接口设置密钥。 - -当待签名数据较短时，可在init初始化后直接调用sign接口传入原文数据进行签名。 - -当待签名数据较长时，可通过update接口分段传入切分后的原文数据，最后调用sign接口对整体原文数据进行签名。 - -当使用update分段传入原文时，sign接口支持传null，业务方可在循环中调用update接口，循环结束后调用sign进行签名。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| algName | string | 是 | 否 | 签名指定的算法名称。 | - -### init - -init(priKey : PriKey, callback : AsyncCallback\) : void - -使用私钥初始化Sign对象，Callback形式，Sign类暂不支持重复init - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------------- | -| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### init - -init(priKey : PriKey) : Promise\ - -使用私钥初始化Sign对象，Promise形式，Sign类暂不支持重复init - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------- | -| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob, callback : AsyncCallback\) : void - -追加待签名数据，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob) : Promise\; - -追加待签名数据，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### sign - -sign(data : DataBlob, callback : AsyncCallback\) : void - -对数据进行签名，返回签名结果，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| callback | AsyncCallback\<[DataBlob](#datablob) > | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### sign - -sign(data : DataBlob) : Promise\ - -对数据进行签名，返回签名结果，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - -let globalKeyPair; -let SignMessageBlob; -let plan1 = "This is Sign test plan1"; // The first segment of data. -let plan2 = "This is Sign test plan2"; // The second segment of fata. -let input1 = { data : stringToUint8Array(plan1) }; -let input2 = { data : stringToUint8Array(plan2) }; - -function signMessageCallback() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); - rsaGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - signer.init(priKey, function (err, data) { - signer.update(input1, function (err, data) { // add first segment of data - signer.sign(input2, function (err, data) { // add second segment of data, sign input1 and input2 - SignMessageBlob = data; - AlertDialog.show({message : "res" + SignMessageBlob.data}); - }); - }); - }); - }); -} -``` - -**promise示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - -let globalKeyPair; -let SignMessageBlob; -let plan1 = "This is Sign test plan1"; // The first segment of data. -let plan2 = "This is Sign test plan2"; // The second segment of fata. -let input1 = { data : stringToUint8Array(plan1) }; -let input2 = { data : stringToUint8Array(plan2) }; - -function signMessagePromise() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); - let keyGenPromise = rsaGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - return signer.init(priKey); - }).then(() => { - return signer.update(input1); // add first segment of data - }).then(() => { - return signer.sign(input2); // add second segment of data, sign input1 and input2 - }).then(dataBlob => { - SignMessageBlob = dataBlob; - console.info("sign output is " + SignMessageBlob.data); - AlertDialog.show({message : "output" + SignMessageBlob.data}); - }); -} -``` - -## cryptoFramework.createVerify - -createVerify(algName : string) : Verify - -Verify实例生成 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------------------------------------ | -| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | - -**返回值**： - -| 类型 | 说明 | -| ------ | ---------------------------------- | -| Verify | 返回由输入算法指定生成的Verify对象 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); - -let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256") -``` - -## Verify - -Verify类，使用Verify方法之前需要创建该类的实例进行操作，通过createVerify(algName : string) : Verify方法构造此实例。 - -Verify类不支持重复初始化，当业务方需要使用新密钥验签时，需要重新创建新Verify对象并调用init初始化。 - -业务方使用时，在createVerify时确定验签的模式，调用init接口设置密钥。 - -当签名数据较短时，可在init初始化后直接调用verify接口传入签名数据和原文进行验签。 - -当签名数据较长时，可通过update接口分段传入签名数据，最后调用verify接口对整体签名数据进行验签。 - -当使用update分段传入签名数据时，verify接口的签名数据支持传null，业务方可在循环中调用update接口，循环结束后调用verify传入原文进行验签。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| algName | string | 是 | 否 | 验签指定的算法名称。 | - - - -### init - -init(pubKey : PubKey, callback : AsyncCallback\) : void - -传入公钥初始化Verify对象，Callback形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------------------------- | -| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### init - -init(pubKey : PubKey) : Promise\ - -传入公钥初始化Verify对象，Promise形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ---- | ---- | ---------------------------- | -| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob, callback : AsyncCallback\) : void - -追加待验签数据，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob)| 是 | 传入的消息 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### update - -update(data : DataBlob) : Promise\; - -追加待验签数据，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | - -**返回值：** - -| 类型 | 说明 | -| -------------- | ----------- | -| Promise\ | Promise对象 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### verify - -verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void - -对数据进行验签，返回验签结果，callback方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | -------------------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | -| callback | AsyncCallback\ | 是 | 回调函数 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### verify - -verify(data : DataBlob, signatureData : DataBlob) : Promise\ - -对数据进行验签，返回验签结果，promise方式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------------- | -------- | ---- | ---------- | -| data | [DataBlob](#datablob) | 是 | 传入的消息 | -| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | - -**返回值：** - -| 类型 | 说明 | -| ----------------- | ---------------------------- | -| Promise\ | 异步返回值，代表验签是否通过 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 -let input1 = null; -let input2 = null; -let signMessageBlob = null; // 签名后的数据，此处省略 -let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25"); -verifyer.init(globalKeyPair.pubKey, function (err, data) { - verifyer.update(input1, function(err, data) { - verifyer.verify(input2, signMessageBlob, function(err, data) { - console.info("verify result is " + data); - }) - }); -}) -``` - -**promise示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 -let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); -let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); -let input1 = null; -let input2 = null; -let signMessageBlob = null; // 签名后的数据，此处省略 -verifyInitPromise.then(() => { - return verifyer.update(input1); -}).then(() => { - return verifyer.verify(input2, signMessageBlob); -}).then(res => { - console.log("Verify result is " + res); -}); -``` - -## cryptoFramework.createKeyAgreement - -createKeyAgreement(algName : string) : KeyAgreement - -KeyAgreement实例生成 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------- | ------ | ---- | ------------------------------- | -| algName | string | 是 | 指定密钥协商算法：目前仅支持ECC | - -**返回值**： - -| 类型 | 说明 | -| ------------ | ---------------------------------------- | -| KeyAgreement | 返回由输入算法指定生成的KeyAgreement对象 | - -**示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); - -``` - -## KeyAgreement - -KeyAgreement类，使用密钥协商方法之前需要创建该类的实例进行操作，通过createKeyAgreement(algName : string) : KeyAgreement方法构造此实例。 - -### 属性 - -**系统能力：** SystemCapability.Security.CryptoFramework - -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ------- | ------ | ---- | ---- | ---------------------------- | -| algName | string | 是 | 否 | 密钥协商指定的算法名称。 | - -### generateSecret - -generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void - -基于传入的私钥与公钥进行密钥协商，返回共享秘密，Callback形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------ | ---- | ---------------------- | -| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | -| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | -| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 异步接受共享秘密的回调 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -### generateSecret - -generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\ - -基于传入的私钥与公钥进行密钥协商，返回共享秘密，Promise形式 - -**系统能力：** SystemCapability.Security.CryptoFramework - -**参数：** - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ---------------------- | -| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | -| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | - -**返回值：** - -| 类型 | 说明 | -| ------------------ | -------- | -| Promise\<[DataBlob](#datablob)> | 共享秘密 | - -**错误码：** - -| 错误码ID | 错误信息 | -| -------- | ---------------------- | -| 17620001 | memory error. | -| 17620002 | runtime error. | -| 17630001 | crypto operation error. | - -**callback示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 -let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); -keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) { - if (err) { - console.error("keyAgreement error."); - return; - } - console.info("keyAgreement output is " + secret.data); -}); -``` - -**promise示例：** - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 -let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); -let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey); -keyAgreementPromise.then((secret) => { - console.info("keyAgreement output is " + secret.data); -}).catch((error) => { - console.error("keyAgreement error."); -}); -``` +# @ohos.security.cryptoFramework (加解密算法库框架) + +为屏蔽底层硬件和算法库，向上提供统一的密码算法库加解密相关接口。 + +> **说明：** +> +> 本模块首批接口从API version 9开始支持。 + +## 导入模块 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" +``` + +## Result + + 表示执行结果的枚举。 + + **系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 值 | 说明 | +| ------------------------------------- | -------- | ---------------------------- | +| INVALID_PARAMS | 401 | 非法入参。 | +| NOT_SUPPORT | 801 | 操作不支持。 | +| ERR_OUT_OF_MEMORY | 17620001 | 内存错误。 | +| ERR_RUNTIME_ERROR | 17620002 | 运行时外部错误。 | +| ERR_CRYPTO_OPERATION | 17630001 | 调用三方算法库API出错。 | + +## DataBlob + +buffer数组。 + + **系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---- | ---------- | ---- | ---- | ------ | +| data | Uint8Array | 是 | 是 | 数据。 | + + +## cryptoFramework.createMac + +createMac(algName : string) : Mac + +生成Mac实例，用于进行消息认证码的计算与操作。
支持的规格详见框架概述“[HMAC消息认证码算法规格](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定摘要算法，支持算法请参考“[HMAC算法支持范围](../../security/cryptoFramework-overview.md#hmac消息认证码算法规格)”一节 | + +**返回值**： + +| 类型 | 说明 | +| ---- | --------------------------------------- | +| Mac | 返回由输入算法指定生成的[Mac](#mac)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + // 参数选择请参考上述算法支持范围 + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Mac + +Mac类，调用Mac方法可以进行MAC（Message Authentication Code）加密计算。调用前，需要通过[createMac](#cryptoframeworkcreatemac)构造Mac实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------- | +| algName | string | 是 | 否 | 代表指定的摘要算法名 | + +### init + +init(key : SymKey, callback : AsyncCallback\) : void; + +使用对称密钥初始化Mac计算 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ------------ | +| key | [SymKey](#symkey) | 是 | 共享对称密钥 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { + if (err) { + console.error("[Callback] err: " + err.code); + } + mac.init(symKey, (err1, ) => { + if (err1) { + console.error("[Callback] err: " + err1.code); + } + }); +}); +``` + +### init + +init(key : SymKey) : Promise\; + +使用对称密钥初始化Mac计算 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------ | +| key | [SymKey](#symkey) | 是 | 共享对称密钥 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); + +``` + +### update + +update(input : DataBlob, callback : AsyncCallback\) : void; + +传入消息进行Mac更新计算 + +> **说明：** +> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| input | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var KeyBlob; +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { + if (err) { + console.error("[Callback] err: " + err.code); + } + mac.init(symKey, (err1, ) => { + if (err1) { + console.error("[Callback] err: " + err1.code); + } + let blob; + mac.update(blob, (err2, data) => { + if (err2) { + console.error("[Callback] err: " + err2.code); + } + }); + }); +}); +``` + +### update + +update(input : DataBlob) : Promise\; + +传入消息进行Mac更新计算 + +> **说明：** +> Hmac算法多次调用update更新的代码示例详见开发指导“[使用消息认证码操作](../../security/cryptoFramework-guidelines.md#使用消息认证码操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| input | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); + +``` + +### doFinal + +doFinal(callback : AsyncCallback\) : void; + +返回Mac的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------- | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var KeyBlob; +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { + if (err) { + console.error("[Callback] err: " + err.code); + } + mac.init(symKey, (err1, ) => { + if (err1) { + console.error("[Callback] err: " + err1.code); + } + let blob; + mac.update(blob, (err2, ) => { + if (err2) { + console.error("[Callback] err: " + err2.code); + } + mac.doFinal((err3, macOutput) => { + if (err3) { + console.error("[Callback] err: " + err3.code); + } else { + console.error("[Promise]: HMAC result: " + macOutput); + } + }); + }); + }); +}); +``` + +### doFinal + +doFinal() : Promise\ + +返回Mac的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; +}).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### getMacLength + +getMacLength() : number + +获取Mac消息认证码的长度（字节数） + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------- | +| number | 返回mac计算结果的字节长度 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var mac; +try { + mac = cryptoFramework.createMac("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Mac algName is: " + mac.algName); + +var KeyBlob; +var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); +var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); +promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; +}).then(() => { + let blob; + var promiseMacUpdate = mac.update(blob); + return promiseMacUpdate; +}).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; +}).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); + let macLen = mac.getMacLength(); + console.error("MAC len: " + macLen); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +## cryptoFramework.createMd + +createMd(algName : string) : Md + +生成Md实例，用于进行消息摘要的计算与操作。
支持的规格详见框架概述“[MD消息摘要算法规格](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定摘要算法，支持算法请参考“[MD算法支持范围](../../security/cryptoFramework-overview.md#md消息摘要算法规格)”一节 | + +**返回值**： + +| 类型 | 说明 | +| ---- | ------------------------------------- | +| Md | 返回由输入算法指定生成的[Md](#md)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + // 参数选择请参考上述算法支持范围 + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Md + +Md类，调用Md方法可以进行MD（Message Digest）摘要计算。调用前，需要通过[createMd](#cryptoframeworkcreatemd)构造Md实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------- | +| algName | string | 是 | 否 | 代表指定的摘要算法名 | + +### update + +update(input : DataBlob, callback : AsyncCallback\) : void; + +传入消息进行Md更新计算 + +> **说明：** +> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| input | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +md.update(blob, (err,) => { + if (err) { + console.error("[Callback] err: " + err.code); + } +}); +``` + +### update + +update(input : DataBlob) : Promise\; + +传入消息进行Md更新计算 + +> **说明：** +> Md算法多次调用update更新的代码示例详见开发指导“[使用摘要操作](../../security/cryptoFramework-guidelines.md#使用摘要操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| input | DataBlob | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + // do something +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### digest + +digest(callback : AsyncCallback\) : void + +返回Md的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------- | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +md.update(blob, (err,) => { + if (err) { + console.error("[Callback] err: " + err.code); + } + md.digest((err1, mdOutput) => { + if (err1) { + console.error("[Callback] err: " + err1.code); + } else { + console.error("[Callback]: MD result: " + mdOutput); + } + }); +}); +``` + +### digest + +digest() : Promise\ + +返回Md的计算结果 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; +}).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### getMdLength + +getMdLength() : number + +获取Md消息摘要长度（字节数） + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ------ | ------------------------ | +| number | 返回md计算结果的字节长度 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var md; +try { + md = cryptoFramework.createMd("SHA256"); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +console.error("Md algName is: " + md.algName); + +let blob; +var promiseMdUpdate = md.update(blob); +promiseMdUpdate.then(() => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; +}).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); + let mdLen = md.getMdLength(); + console.error("MD len: " + mdLen); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +## cryptoFramework.createRandom + +createRandom() : Random + +生成Random实例，用于进行随机数的计算与设置种子。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值**： + +| 类型 | 说明 | +| ------ | --------------------------------------------- | +| Random | 返回由输入算法指定生成的[Random](#random)对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------ | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +try { + var rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +``` + +## Random + +Random类，调用Random方法可以进行随机数计算。调用前，需要通过[createRandom](#cryptoframeworkcreaterandom)构造Random实例。 + +### generateRandom + +generateRandom(len : number, callback: AsyncCallback\) : void; + +生成指定长度的随机数 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | -------------------- | +| len | number | 是 | 表示生成随机数的长度 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} +rand.generateRandom(12, (err, randData) => { + if (err) { + console.error("[Callback] err: " + err.code); + } else { + console.error("[Callback]: generate random result: " + randData.data); + } +}); +``` + +### generateRandom + +generateRandom(len : number) : Promise\; + +生成指定长度的随机数 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | -------------------- | +| len | number | 是 | 表示生成随机数的长度 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | ----------- | +| Promise\<[DataBlob](#datablob)> | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17630001 | crypto operation error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} + +var promiseGenerateRand = rand.generateRandom(12); +promiseGenerateRand.then(randData => { + console.error("[Promise]: rand result: " + randData.data); +}).catch(error => { + console.error("[Promise]: error: " + error.message); +}); +``` + +### setSeed + +setSeed(seed : DataBlob) : void; + +设置指定的种子 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------- | ---- | ---------- | +| seed | DataBlob | 是 | 设置的种子 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ----------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +var rand; +try { + rand = cryptoFramework.createRandom(); +} catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); +} + +rand.generateRandom(12, (err, randData) => { + if (err) { + console.error("[Callback] err: " + err.code); + } else { + console.error("[Callback]: generate random result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + } +}); +``` + +## ParamsSpec + +加解密参数，在进行对称加解密时需要构造其子类对象，并将子类对象传入[init()](#init-2)方法。
适用于需要iv等参数的对称加解密模式（对于无iv等参数的模式如ECB模式，无需构造，在[init()](#init-2)中传入null即可）。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 是 | 指明对称加解密参数的算法模式。可选值如下:
- "IvParamsSpec": 适用于CBC\|CTR\|OFB\|CFB模式
- "GcmParamsSpec": 适用于GCM模式
- "CcmParamsSpec": 适用于CCM模式 | + +> **说明：** +> 由于[init()](#init-2)的params参数是ParamsSpec类型（父类），而实际需要传入具体的子类对象（如IvParamsSpec），因此在构造子类对象时应设置其父类ParamsSpec的algName参数，使算法库在init()时知道传入的是哪种子类对象。 + +## IvParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CBC、CTR、OFB、CFB这些仅使用iv作为参数的加解密模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ---- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv。常见取值如下：
- AES的CBC\|CTR\|OFB\|CFB模式：iv长度为16字节
- 3DES的CBC\|OFB\|CFB模式：iv长度为8字节 | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## GcmParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于GCM模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为12字节 | +| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | +| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为16字节。
采用GCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾16字节作为解密时[init()](#init-2)方法的入参[GcmParamsSpec](#gcmparamsspec)中的的authTag | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## CcmParamsSpec + +加解密参数[ParamsSpec](#paramsspec)的子类，用于在对称加解密时作为[init()](#init-2)方法的参数。
适用于CCM模式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | +| iv | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数iv，长度为7字节 | +| aad | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数aad，长度为8字节 | +| authTag | [DataBlob](#datablob) | 是 | 是 | 指明加解密参数authTag，长度为12字节。
采用CCM模式加密时，需要获取[doFinal()](#dofinal-2)输出的[DataBlob](#datablob)，取出其末尾12字节作为解密时[init()](#init-2)方法的入参[CcmParamsSpec](#ccmparamsspec)中的authTag | + +> **说明：** +> 传入[init()](#init-2)方法前需要指定其algName属性（来源于父类[ParamsSpec](#paramsspec)）。 + +## CryptoMode + +表示加解密操作的枚举。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 值 | 说明 | +| ------------ | ---- | ---------------- | +| ENCRYPT_MODE | 0 | 表示进行加密操作 | +| DECRYPT_MODE | 1 | 表示进行解密操作 | + +## Key + +密钥（父类），在运行密码算法（如加解密）时需要提前生成其子类对象，并传入[Cipher](#cipher)实例的[init()](#init-2)方法。
密钥可以通过密钥生成器来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取16进制形式的密钥内容。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +import cryptoFramework from "@ohos.security.cryptoFramework" +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 +let encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +## SymKey + +对称密钥，是[Key](#key)的子类，在对称加解密时需要将其对象传入[Cipher](#cipher)实例的[init()](#init-2)方法使用。
对称密钥可以通过对称密钥生成器[SymKeyGenerator](#symkeygenerator)来生成。 + +### clearMem + +clearMem() : void + +以同步方法，将系统底层内存中的的密钥内容清零。建议在不再使用对称密钥实例时，调用本函数，避免内存中密钥数据存留过久。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**示例：** + +```js +import cryptoFramework from "@ohos.security.cryptoFramework" +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用对称密钥生成器 生成的密钥，此处省略生成过程 +let encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出密钥内容 +key.clearMem(); +encodedKey = key.getEncoded(); +console.info("key hex:" + uint8ArrayToShowStr(encodedKey.data)); // 输出全零 +``` + +## PubKey + +公钥，是Key的子类，在非对称加解密、验签、密钥协商时需要将其对象作为输入使用。
公钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取二进制形式的密钥内容。公钥格式满足ASN.1语法、X.509规范、DER编码格式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 +console.info("key format:" + key.format); +console.info("key algName:" + key.algName); +var encodedKey = key.getEncoded(); +console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +## PriKey + +私钥，是Key的子类，在非对称加解密、签名、密钥协商时需要将其作为输入使用。
私钥可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| format | string | 是 | 否 | 密钥的格式。 | +| algName | string | 是 | 否 | 密钥对应的算法名（含长度）。 | + +### getEncoded + +getEncoded() : DataBlob + +以同步方法，获取二进制形式的密钥内容。私钥格式满足ASN.1语法，PKCS#8规范、DER编码方式。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------- | ------------------------ | +| [DataBlob](#datablob) | 用于查看密钥的具体内容。 | + +**示例：** + +```js +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 +console.info("key format:" + key.format); +console.info("key algName:" + key.algName); +var encodedKey = key.getEncoded(); +console.info("key encoded:" + uint8ArrayToShowStr(encodedKey.data)); +``` + +### clearMem + +clearMem() : void + +以同步方法，将系统底层内存中的的密钥内容清零。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**示例：** + +```js +let key; // key为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 +key.clearMem(); +``` + +## KeyPair + +非对称密钥对，包含：公钥与私钥。
可以通过非对称密钥生成器AsyKeyGenerator来生成。 + +> **说明：** +> +> KeyPair对象中的pubKey对象和priKey对象，作为KeyPair对象中的一个参数存在，当离开KeyPair对象作用域时，其内部对象可能被析构。
业务方使用时应持有KeyPair对象的引用，而非内部pubKey或priKey对象的引用。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------ | +| priKey | [PriKey](#prikey) | 是 | 否 | 私钥。 | +| pubKey | [PubKey](#pubkey) | 是 | 否 | 公钥。 | + + +## cryptoFramework.createSymKeyGenerator + +createSymKeyGenerator(algName : string) : SymKeyGenerator + +通过指定算法名称的字符串，获取相应的对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 待生成对称密钥生成器的算法名称。
具体取值详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节中的“字符串参数”。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------- | -------------------------- | +| [SymKeyGenerator](#symkeygenerator) | 返回对称密钥生成器的对象。 | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); +``` + +## SymKeyGenerator + +对称密钥生成器。
在使用该类的方法前，需要先使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)方法构建一个symKeyGenerator实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ------------------------------ | +| algName | string | 是 | 否 | 对称密钥生成器指定的算法名称。 | + +### generateSymKey + +generateSymKey(callback : AsyncCallback\) : void + +异步获取对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); +symKeyGenerator.generateSymKey((err, symKey) => { + if (err) { + console.error(`Generate symKey failed, ${err.code}, ${err.message}`); + } else { + console.info(`Generate symKey success, algName: ${symKey.algName}`); + } +}) +``` + +### generateSymKey + +generateSymKey() : Promise\ + +异步获取该对称密钥生成器随机生成的密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。
目前支持使用OpenSSL的RAND_priv_bytes()作为底层能力生成随机密钥。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | --------------------------------- | +| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symAlgName = 'AES128'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); +symKeyGenerator.generateSymKey() +.then(symKey => { + console.info(`Generate symKey success, algName: ${symKey.algName}`); +}, error => { + console.error(`Generate symKey failed, ${error.code}, ${error.message}`); +}) +``` + +### convertKey + +convertKey(key : DataBlob, callback : AsyncCallback\) : void + +异步根据指定数据生成对称密钥，通过注册回调函数获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------- | ---- | ------------------------------------------------------------ | +| key | [DataBlob](#datablob) | 是 | 指定的对称密钥材料。 | +| callback | AsyncCallback\<[SymKey](#symkey)> | 是 | 回调函数。当生成对称密钥成功，err为undefined，data为获取到的SymKey；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); +let keyMaterialBlob = genKeyMaterialBlob(); +symKeyGenerator.convertKey(keyMaterialBlob, (err, symKey) => { + if (err) { + console.error(`Convert symKey failed, ${err.code}, ${err.message}`); + } else { + console.info(`Convert symKey success, algName: ${symKey.algName}`); + } +}) +``` + +### convertKey + +convertKey(key : DataBlob) : Promise\ + +异步根据指定数据生成对称密钥，通过Promise获取结果。
必须在使用[createSymKeyGenerator](#cryptoframeworkcreatesymkeygenerator)创建对称密钥生成器后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| key | [DataBlob](#datablob) | 是 | 指定的密钥材料数据。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------- | --------------------------------- | +| Promise\<[SymKey](#symkey)> | Promise对象，返回对称密钥SymKey。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------- | +| 17620001 | memory error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + +let symAlgName = '3DES192'; +let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); +let keyMaterialBlob = genKeyMaterialBlob(); +symKeyGenerator.convertKey(keyMaterialBlob) +.then(symKey => { + console.info(`Convert symKey success, algName: ${symKey.algName}`); +}, error => { + console.error(`Convert symKey failed, ${error.code}, ${error.message}`); +}) +``` + +## cryptoFramework.createAsyKeyGenerator + +createAsyKeyGenerator(algName : string) : AsyKeyGenerator + +通过指定算法名称的字符串，获取相应的非对称密钥生成器实例。
支持的规格详见框架概述“[密钥生成规格](../../security/cryptoFramework-overview.md#密钥生成规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | -------------------------------- | +| algName | string | 是 | 待生成对称密钥生成器的算法名称。 | + +**返回值：** + +| 类型 | 说明 | +| --------------- | ---------------------------- | +| [AsyKeyGenerator](#asykeygenerator) | 返回非对称密钥生成器的对象。 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +``` + +## AsyKeyGenerator + +非对称密钥生成器。在使用该类的方法前，需要先使用createAsyKeyGenerator()方法构建一个AsyKeyGenerator实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | -------------------------------- | +| algName | string | 是 | 否 | 非对称密钥生成器指定的算法名称。 | + +### generateKeyPair + +generateKeyPair(callback : AsyncCallback\) : void; + +异步获取非对称密钥生成器随机生成的密钥，通过注册回调函数获取结果。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | ------------------------------ | +| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +asyKeyGenerator.generateKeyPair((err, keyPair) => { + if (err) { + console.error("generateKeyPair: error."); + return; + } + console.info("generateKeyPair: success."); +}) +``` + + +### generateKeyPair + +generateKeyPair() : Promise\ + +异步获取该非对称密钥生成器随机生成的密钥，通过Promise获取结果。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------- | +| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +let keyGenPromise = asyKeyGenerator.generateKeyPair(); +keyGenPromise.then( keyPair => { + console.info("generateKeyPair success."); +}).catch(error => { + console.error("generateKeyPair error."); +}); +``` + +### convertKey + +convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void + +异步获取指定数据生成非对称密钥，通过注册回调函数获取结果。详情请看下方**密钥转换说明** + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------- | ---- | ------------------------------ | +| pubKey | [DataBlob](#datablob) | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null。 | +| priKey | [DataBlob](#datablob) | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null。 | +| callback | AsyncCallback\<[KeyPair](#keypair)> | 是 | 回调函数，用于获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" +let pubKey; // X.509规范、DER格式的公钥数据，此处省略数据。 +let priKey; // PKCS#8规范、DER格式的私钥数据，此处省略数据。 +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +asyKeyGenerator.convertKey(pubKey, priKey, (err, keyPair) => { + if (err) { + console.error("convertKey: error."); + return; + } + console.info("convertKey: success."); +}) +``` + +### convertKey + +convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ + +异步获取指定数据生成非对称密钥，通过Promise获取结果。详情请看下方**密钥转换说明** + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------------- | +| pubKey | DataBlob | 是 | 指定的公钥材料。如果公钥不需要转换，可直接传入null | +| priKey | DataBlob | 是 | 指定的私钥材料。如果私钥不需要转换，可直接传入null | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | --------------------------------- | +| Promise\<[KeyPair](#keypair)> | 使用Promise的方式获取非对称密钥。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); +let pubKey; // pubKey为使用非对称密钥生成器生成的非对称密钥的公钥对象，此处省略生成过程 +let priKey; // priKey为使用非对称密钥生成器生成的非对称密钥的私钥对象，此处省略生成过程 +let keyGenPromise = asyKeyGenerator.convertKey(pubKey, priKey); +keyGenPromise.then( keyPair => { + console.info("convertKey success."); +}).catch(error => { + console.error("convertKey error."); +}); +``` + +**密钥转换说明** + +1. 非对称密钥（RSA、ECC）的公钥和私钥调用getEncoded()方法后，分别返回X.509格式和PKCS#8格式的二进制数据，此数据可用于跨应用传输或持久化存储。 +2. 当调用convertKey方法将外来二进制数据转换为算法库非对称密钥对象时，公钥应满足ASN.1语法、X.509规范、DER编码格式，私钥应满足ASN.1语法、PKCS#8规范、DER编码格式。 +3. convertKey方法中，公钥和密钥二进制数据非必选项，可单独传入公钥或私钥的数据，生成对应只包含公钥或私钥的KeyPair对象。 + +## cryptoFramework.createCipher + +createCipher(transformation : string) : Cipher + +通过指定算法名称，获取相应的[Cipher](#cipher)实例。
支持的规格详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------------- | ------ | ---- | ------------------------------------------------------------ | +| transformation | string | 是 | 待生成Cipher的算法名称（含密钥长度）、加密模式以及填充方法的组合。
具体取值详见框架概述“[加解密规格](../../security/cryptoFramework-overview.md#加解密规格)”一节中的“字符串参数”。 | + +> **说明：** +> 1. 目前对称加解密中，PKCS5和PKCS7的实现相同，其padding长度和分组长度保持一致（即PKCS5和PKCS7在3DES中均按照8字节填充，在AES中均按照16字节填充），另有NoPadding表示不填充。
开发者需要自行了解密码学不同分组模式的差异，以便选择合适的参数规格。例如选择ECB和CBC模式时，建议启用填充，否则必须确保明文长度是分组大小的整数倍；选择其他模式时，可以不启用填充，此时密文长度和明文长度一致（即可能不是分组大小的整数倍）。 +> 2. 使用RSA进行非对称加解密时，必须创建两个Cipher对象分别进行加密和解密操作，而不能对同一个Cipher对象进行加解密。对称加解密没有此要求（即只要算法规格一样，可以对同一个Cipher对象进行加解密操作）。 + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ------------------------ | +| [Cipher](#cipher) | 返回加解密生成器的对象。 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let cipherAlgName = '3DES192|ECB|PKCS7'; +var cipher; +try { + cipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${cipher.algName}`); +} catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); +} +``` + +## Cipher + +提供加解密的算法操作功能，按序调用本类中的[init()](#init-2)、[update()](#update-4)、[doFinal()](#dofinal-2)方法，可以实现对称加密/对称解密/非对称加密/非对称解密。
完整的加解密流程示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 + +一次完整的加/解密流程在对称加密和非对称加密中略有不同： + +- 对称加解密：init为必选，update为可选（且允许多次update加/解密大数据），doFinal为必选；doFinal结束后可以重新init开始新一轮加/解密流程。 +- RSA非对称加解密：init为必选，不支持update操作，doFinal为必选（允许连续多次doFinal加/解密大数据）；RSA不支持重复init，切换加解密模式或填充方式时，需要重新创建Cipher对象。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| algName | string | 是 | 否 | 加解密生成器指定的算法名称。 | + +### init + +init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void + +初始化加解密的[cipher](#cipher)对象，通过注册回调函数获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------- | ---- | ------------------------------------------------------------ | +| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | +| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | +| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | +| callback | AsyncCallback\ | 是 | 回调函数。当初始化成功，err为undefined，否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error.| + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symKey; // 此处省略生成对称密钥的过程 +let cipher; // 此处省略生成cipher实例的过程 + +cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null, (err, ) => { + if (err) { + console.error(`Failed to init cipher, ${err.code}, ${err.message}`); + } else { + console.info(`Init cipher success`); + // 此处进行update等后续操作 + } +}) +``` + +### init + +init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\ + +初始化加解密的cipher对象，通过Promise获取结果。
必须在使用[createCipher](#cryptoframeworkcreatecipher)创建[Cipher](#cipher)实例后，才能使用本函数。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------- | ---- | ------------------------------------------------------------ | +| opMode | [CryptoMode](#cryptomode) | 是 | 加密或者解密模式。 | +| key | [Key](#key) | 是 | 指定加密或解密的密钥。 | +| params | [ParamsSpec](#paramsspec) | 是 | 指定加密或解密的参数，对于ECB等没有参数的算法模式，可以传入null。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | -------------------------------------- | +| Promise\ | Promise对象。无返回结果的Promise对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error.| + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; +let symKey; // 此处省略生成对称密钥的过程 +let cipher; // 此处省略生成cipher实例的过程 +cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, symKey, null) +.then(() => { + console.info(`Init cipher success`); + // 此处进行update等后续操作 +}, error => { + console.error(`Failed to init cipher, ${error.code}, ${error.message}`); +}) +``` + +### update + +update(data : DataBlob, callback : AsyncCallback\) : void + +分段更新加密或者解密数据操作，通过注册回调函数获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 + +> **说明：** +> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，采用多次update的方式传入数据。
AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 +> 3. RSA非对称加解密不支持update操作。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当更新加/解密数据成功，err为undefined，data为此次更新的加/解密结果DataBlob；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +let cipher; // 此处省略生成cipher实例的过程 +// 此处省略init()过程 +let plainText = {data : stringToUint8Array('this is test!')}; +cipher.update(plainText, (err, output) => { // 加密过程举例 + if (err) { + console.error(`Failed to update cipher`); + } else { + console.info(`Update cipher success`); + if (output != null) { + // 拼接output.data到密文 + } + // 此处进行doFinal等后续操作 + } +}) +``` + +### update + +update(data : DataBlob) : Promise\ + +分段更新加密或者解密数据操作，通过通过Promise获取加/解密数据。
必须在对[Cipher](#cipher)实例使用[init()](init-2)初始化后，才能使用本函数。 + +> **说明：** +> 1. 在进行对称加解密操作的时候，如果开发者对各个分组模式不够熟悉，建议对每次update和doFinal的结果都判断是否为null，并在结果不为null时取出其中的数据进行拼接，形成完整的密文/明文。这是因为选择的分组模式等各项规格都可能对update和[doFinal](#dofinal-2)结果产生影响。
（例如对于ECB和CBC模式，不论update传入的数据是否为分组长度的整数倍，都会以分组作为基本单位进行加/解密，并输出本次update新产生的加/解密分组结果。
可以理解为，update只要凑满一个新的分组就会有输出，如果没有凑满则此次update输出为null，把当前还没被加/解密的数据留着，等下一次update/doFinal传入数据的时候，拼接起来继续凑分组。
最后doFinal的时候，会把剩下的还没加/解密的数据，根据[createCipher](#cryptoframeworkcreatecipher)时设置的padding模式进行填充，补齐到分组的整数倍长度，再输出剩余加解密结果。
而对于可以将分组密码转化为流模式实现的模式，还可能出现密文长度和明文长度相同的情况等。） +> 2. 根据数据量，可以不调用update（即[init](#init-2)完成后直接调用[doFinal](#dofinal-2)）或多次调用update。
算法库目前没有对update（单次或累计）的数据量设置大小限制，建议对于大数据量的对称加解密，可以采用多次update的方式传入数据。
AES使用多次update操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 +> 3. RSA非对称加解密不支持update操作。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data不能为null，也不允许传入{data : Uint8Array(空) } | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | ------------------------------------------------ | +| Promise\<[DataBlob](#datablob)> | Promise对象，返回此次更新的加/解密结果DataBlob。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +let cipher; // 此处省略生成cipher实例的过程 +// 此处省略init()过程 +let plainText = {data : stringToUint8Array('this is test!')}; +cipher.update(plainText) +.then((output) => { + console.info(`Update cipher success.`); + if (output != null) { + // 拼接output.data到密文 + } + // 此处进行doFinal等后续操作 +}, error => { + console.info(`Update cipher failed.`); +}) +``` + +### doFinal + +doFinal(data : DataBlob, callback : AsyncCallback\) : void + +（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过注册回调函数获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： + +- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 +- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 + +（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过注册回调函数获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 + +> **说明：** +> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 +> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 +> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 +> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。在对称加解密中允许为null，但不允许传入{data : Uint8Array(空) }。 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 回调函数。当最终加/解密数据成功，err为undefined，data为剩余数据的加/解密结果DataBlob；否则为错误对象。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ----------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +let cipher; // 此处省略生成cipher实例的过程 +let data; // 此处省略准备待加密/解密数据的过程 +// 此处省略init()和update()过程 +cipher.doFinal(data, (err, output) => { + if (err) { + console.error(`Failed to finalize cipher, ${err.code}, ${err.message}`); + } else { + console.info(`Finalize cipher success`); + if (output != null) { + // 拼接output.data得到完整的明文/密文(及authTag) + } + } +}) +``` + +### doFinal + +doFinal(data : DataBlob) : Promise\ + +（1）在对称加解密中，doFinal加/解密（分组模式产生的）剩余数据和本次传入的数据，最后结束加密或者解密数据操作，通过Promise获取加密或者解密数据。
如果数据量较小，可以在doFinal中一次性传入数据，而不使用update；如果在本次加解密流程中，已经使用[update](#update-4)传入过数据，可以在doFinal的data参数处传入null。
根据对称加解密的模式不同，doFinal的输出有如下区别： + +- 对于GCM和CCM模式的对称加密：一次加密流程中，如果将每一次update和doFinal的结果拼接起来，会得到“密文+authTag”，即末尾的16字节（GCM模式）或12字节（CCM模式）是authTag，而其余部分均为密文。（也就是说，如果doFinal的data参数传入null，则doFinal的结果就是authTag）
authTag需要填入解密时的[GcmParamsSpec](#gcmparamsspec)或[CcmParamsSpec](#ccmparamsspec)；密文则作为解密时的入参data。 +- 对于其他模式的对称加解密、GCM和CCM模式的对称解密：一次加/解密流程中，每一次update和doFinal的结果拼接起来，得到完整的明文/密文。 + +（2）在RSA非对称加解密中，doFinal加/解密本次传入的数据，通过Promise获取加密或者解密数据。如果数据量较大，可以多次调用doFinal，拼接结果得到完整的明文/密文。 + +> **说明：** +> 1. 对称加解密中，调用doFinal标志着一次加解密流程已经完成，即[Cipher](#cipher)实例的状态被清除，因此当后续开启新一轮加解密流程时，需要重新调用[init()](init-2)并传入完整的参数列表进行初始化
（比如即使是对同一个Cipher实例，采用同样的对称密钥，进行加密然后解密，则解密中调用init的时候仍需填写params参数，而不能直接省略为null）。 +> 2. 如果遇到解密失败，需检查加解密数据和[init](#init-2)时的参数是否匹配，包括GCM模式下加密得到的authTag是否填入解密时的GcmParamsSpec等。 +> 3. doFinal的结果可能为null，因此使用.data字段访问doFinal结果的具体数据前，请记得先判断结果是否为null，避免产生异常。 +> 4. RSA非对称加解密时多次doFinal操作的示例代码详见开发指导“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---- | --------------------- | ---- | -------------------- | +| data | [DataBlob](#datablob) | 是 | 加密或者解密的数据。data参数允许为null，但不允许传入{data : Uint8Array(空) } | + +**返回值：** + +| 类型 | 说明 | +| ------------------------------- | ------------------------------------------------ | +| Promise\<[DataBlob](#datablob)> | Promise对象，返回剩余数据的加/解密结果DataBlob。 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**示例：** + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +let cipher; // 此处省略生成cipher实例的过程 +let data; // 此处省略准备待加密/解密数据的过程 +// 此处省略init()和update()过程 +cipher.doFinal(data) +.then(output => { + console.info(`Finalize cipher success`); + if (output != null) { + // 拼接output.data得到完整的明文/密文(及authTag) + } +}, error => { + console.error(`Failed to finalize cipher, ${error.code}, ${error.message}`); +}) +``` + +**使用RSA加密的callback完整示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); +let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); +rsaGenerator.generateKeyPair(function (err, keyPair) { + let pubKey = keyPair.pubKey; + cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) { + let plainText = "this is cipher text"; + let input = {data : stringToUint8Array(plainText) }; + cipher.doFinal(input, function (err, data) { + AlertDialog.show({ message : "EncryptOutPut is " + data.data} ); + }); + }); +}); +``` + +**使用RSA加密的promise完整示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); +let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); +let keyGenPromise = rsaGenerator.generateKeyPair(); +keyGenPromise.then(rsaKeyPair => { + let pubKey = rsaKeyPair.pubKey; + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); // 传入私钥和DECRYPT_MODE可初始化解密模式 +}).then(() => { + let plainText = "this is cipher text"; + let input = { data : stringToUint8Array(plainText) }; + return cipher.doFinal(input); +}).then(dataBlob => { + console.info("EncryptOutPut is " + dataBlob.data); +}); +``` + +> **说明：** +> 更多加解密流程的完整示例可参考开发指导中的“[使用加解密操作](../../security/cryptoFramework-guidelines.md#使用加解密操作)”一节。 + +## cryptoFramework.createSign + +createSign(algName : string) : Sign + +Sign实例生成。
支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | + +**返回值**： + +| 类型 | 说明 | +| ---- | -------------------------------- | +| Sign | 返回由输入算法指定生成的Sign对象 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let signer1 = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); + +let singer2 = cryptoFramework.createSign("RSA1024|PSS|SHA256|MGF1_SHA256") +``` + +## Sign + +Sign类，使用Sign方法之前需要创建该类的实例进行操作，通过createSign(algName : string) : Sign方法构造此实例。Sign类不支持重复初始化，当业务方需要使用新密钥签名时，需要重新创建新Sign对象并调用init初始化。 + +业务方使用时，在createSign时确定签名的模式，调用init接口设置密钥。 + +当待签名数据较短时，可在init初始化后直接调用sign接口传入原文数据进行签名。 + +当待签名数据较长时，可通过update接口分段传入切分后的原文数据，最后调用sign接口对整体原文数据进行签名。 + +当使用update分段传入原文时，sign接口支持传null，业务方可在循环中调用update接口，循环结束后调用sign进行签名。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| algName | string | 是 | 否 | 签名指定的算法名称。 | + +### init + +init(priKey : PriKey, callback : AsyncCallback\) : void + +使用私钥初始化Sign对象，Callback形式，Sign类暂不支持重复init + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------------- | +| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### init + +init(priKey : PriKey) : Promise\ + +使用私钥初始化Sign对象，Promise形式，Sign类暂不支持重复init + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------- | +| priKey | [PriKey](#prikey) | 是 | 用于Sign的初始化 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob, callback : AsyncCallback\) : void + +追加待签名数据，callback方式 + +> **说明：** +> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob) : Promise\; + +追加待签名数据，promise方式 + +> **说明：** +> Sign多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### sign + +sign(data : DataBlob, callback : AsyncCallback\) : void + +对数据进行签名，返回签名结果，callback方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| callback | AsyncCallback\<[DataBlob](#datablob) > | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### sign + +sign(data : DataBlob) : Promise\ + +对数据进行签名，返回签名结果，promise方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +let globalKeyPair; +let SignMessageBlob; +let plan1 = "This is Sign test plan1"; // The first segment of data. +let plan2 = "This is Sign test plan2"; // The second segment of fata. +let input1 = { data : stringToUint8Array(plan1) }; +let input2 = { data : stringToUint8Array(plan2) }; + +function signMessageCallback() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); + rsaGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + signer.init(priKey, function (err, data) { + signer.update(input1, function (err, data) { // add first segment of data + signer.sign(input2, function (err, data) { // add second segment of data, sign input1 and input2 + SignMessageBlob = data; + AlertDialog.show({message : "res" + SignMessageBlob.data}); + }); + }); + }); + }); +} +``` + +**promise示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +let globalKeyPair; +let SignMessageBlob; +let plan1 = "This is Sign test plan1"; // The first segment of data. +let plan2 = "This is Sign test plan2"; // The second segment of fata. +let input1 = { data : stringToUint8Array(plan1) }; +let input2 = { data : stringToUint8Array(plan2) }; + +function signMessagePromise() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); + let keyGenPromise = rsaGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + return signer.init(priKey); + }).then(() => { + return signer.update(input1); // add first segment of data + }).then(() => { + return signer.sign(input2); // add second segment of data, sign input1 and input2 + }).then(dataBlob => { + SignMessageBlob = dataBlob; + console.info("sign output is " + SignMessageBlob.data); + AlertDialog.show({message : "output" + SignMessageBlob.data}); + }); +} +``` + +## cryptoFramework.createVerify + +createVerify(algName : string) : Verify + +Verify实例生成。
支持的规格详见框架概述“[签名验签规格](../../security/cryptoFramework-overview.md#签名验签规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------------------------------------ | +| algName | string | 是 | 指定签名算法：RSA或ECC，使用RSA PKCS1模式时需要设置摘要，使用RSA PSS模式时需要设置摘要和掩码摘要 | + +**返回值**： + +| 类型 | 说明 | +| ------ | ---------------------------------- | +| Verify | 返回由输入算法指定生成的Verify对象 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let verifyer1 = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); + +let verifyer2 = cryptoFramework.createVerify("RSA1024|PSS|SHA256|MGF1_SHA256") +``` + +## Verify + +Verify类，使用Verify方法之前需要创建该类的实例进行操作，通过createVerify(algName : string) : Verify方法构造此实例。 + +Verify类不支持重复初始化，当业务方需要使用新密钥验签时，需要重新创建新Verify对象并调用init初始化。 + +业务方使用时，在createVerify时确定验签的模式，调用init接口设置密钥。 + +当签名数据较短时，可在init初始化后直接调用verify接口传入签名数据和原文进行验签。 + +当签名数据较长时，可通过update接口分段传入签名数据，最后调用verify接口对整体签名数据进行验签。 + +当使用update分段传入签名数据时，verify接口的签名数据支持传null，业务方可在循环中调用update接口，循环结束后调用verify传入原文进行验签。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| algName | string | 是 | 否 | 验签指定的算法名称。 | + + + +### init + +init(pubKey : PubKey, callback : AsyncCallback\) : void + +传入公钥初始化Verify对象，Callback形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------------------------- | +| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### init + +init(pubKey : PubKey) : Promise\ + +传入公钥初始化Verify对象，Promise形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---- | ---- | ---------------------------- | +| pubKey | [PubKey](#pubkey) | 是 | 公钥对象，用于Verify的初始化 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob, callback : AsyncCallback\) : void + +追加待验签数据，callback方式 + +> **说明：** +> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob)| 是 | 传入的消息 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### update + +update(data : DataBlob) : Promise\; + +追加待验签数据，promise方式 + +> **说明：** +> Verify多次调用update的代码示例详见开发指导“[使用签名验签操作](../../security/cryptoFramework-guidelines.md#使用签名验签操作)”。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ----------- | +| Promise\ | Promise对象 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### verify + +verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void + +对数据进行验签，返回验签结果，callback方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------------------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | +| callback | AsyncCallback\ | 是 | 回调函数 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### verify + +verify(data : DataBlob, signatureData : DataBlob) : Promise\ + +对数据进行验签，返回验签结果，promise方式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------------- | -------- | ---- | ---------- | +| data | [DataBlob](#datablob) | 是 | 传入的消息 | +| signatureData | [DataBlob](#datablob) | 是 | 签名数据 | + +**返回值：** + +| 类型 | 说明 | +| ----------------- | ---------------------------- | +| Promise\ | 异步返回值，代表验签是否通过 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 +let input1 = null; +let input2 = null; +let signMessageBlob = null; // 签名后的数据，此处省略 +let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA25"); +verifyer.init(globalKeyPair.pubKey, function (err, data) { + verifyer.update(input1, function(err, data) { + verifyer.verify(input2, signMessageBlob, function(err, data) { + console.info("verify result is " + data); + }) + }); +}) +``` + +**promise示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 +let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); +let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); +let input1 = null; +let input2 = null; +let signMessageBlob = null; // 签名后的数据，此处省略 +verifyInitPromise.then(() => { + return verifyer.update(input1); +}).then(() => { + return verifyer.verify(input2, signMessageBlob); +}).then(res => { + console.log("Verify result is " + res); +}); +``` + +## cryptoFramework.createKeyAgreement + +createKeyAgreement(algName : string) : KeyAgreement + +KeyAgreement实例生成。
支持的规格详见框架概述“[密钥协商规格](../../security/cryptoFramework-overview.md#密钥协商规格)”一节。 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ------------------------------- | +| algName | string | 是 | 指定密钥协商算法：目前仅支持ECC | + +**返回值**： + +| 类型 | 说明 | +| ------------ | ---------------------------------------- | +| KeyAgreement | 返回由输入算法指定生成的KeyAgreement对象 | + +**示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); + +``` + +## KeyAgreement + +KeyAgreement类，使用密钥协商方法之前需要创建该类的实例进行操作，通过createKeyAgreement(algName : string) : KeyAgreement方法构造此实例。 + +### 属性 + +**系统能力：** SystemCapability.Security.CryptoFramework + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ------- | ------ | ---- | ---- | ---------------------------- | +| algName | string | 是 | 否 | 密钥协商指定的算法名称。 | + +### generateSecret + +generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void + +基于传入的私钥与公钥进行密钥协商，返回共享秘密，Callback形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------ | ---- | ---------------------- | +| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | +| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | +| callback | AsyncCallback\<[DataBlob](#datablob)> | 是 | 异步接受共享秘密的回调 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +### generateSecret + +generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\ + +基于传入的私钥与公钥进行密钥协商，返回共享秘密，Promise形式 + +**系统能力：** SystemCapability.Security.CryptoFramework + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------------- | +| priKey | [PriKey](#prikey) | 是 | 设置密钥协商的私钥输入 | +| pubKey | [PubKey](#pubkey) | 是 | 设置密钥协商的公钥输入 | + +**返回值：** + +| 类型 | 说明 | +| ------------------ | -------- | +| Promise\<[DataBlob](#datablob)> | 共享秘密 | + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ---------------------- | +| 17620001 | memory error. | +| 17620002 | runtime error. | +| 17630001 | crypto operation error. | + +**callback示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 +let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); +keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey, function (err, secret) { + if (err) { + console.error("keyAgreement error."); + return; + } + console.info("keyAgreement output is " + secret.data); +}); +``` + +**promise示例：** + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; // globalKeyPair为使用非对称密钥生成器生成的非对称密钥对象，此处省略生成过程 +let keyAgreement = cryptoFramework.createKeyAgreement("ECC256"); +let keyAgreementPromise = keyAgreement.generateSecret(globalKeyPair.priKey, globalKeyPair.pubKey); +keyAgreementPromise.then((secret) => { + console.info("keyAgreement output is " + secret.data); +}).catch((error) => { + console.error("keyAgreement error."); +}); +``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-fs.md b/zh-cn/application-dev/reference/apis/js-apis-file-fs.md index a0271c550005f13ed9f863c593649fa55da5d611..681f8f13142d5328a67f8566a0bcc173897d4e21 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-file-fs.md +++ b/zh-cn/application-dev/reference/apis/js-apis-file-fs.md @@ -1559,6 +1559,239 @@ symlinkSync(target: string, srcPath: string): void fs.symlinkSync(srcFile, dstFile); ``` +## fs.listFile +listFile(path: string, options?: { + recursion?: boolean; + listNum?: number; + filter?: Filter; +}): Promise; + +列出文件夹下所有文件名，支持递归列出所有文件名（包含子目录下），支持文件过滤，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | path | string | 是 | 文件夹的应用沙箱路径。 | + | options | Object | 否 | 文件过滤选项。 | + +**options参数说明：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | recursion | boolean | 否 | 是否递归子目录下文件名，默认为false。 | + | listNum | number | 否 | 列出文件名数量。当设置0时，列出所有文件，默认为0。 | + | filter | [Filter](#filter) | 否 | 文件过滤选项。当前仅支持后缀名匹配、文件名模糊查询、文件大小过滤、最近修改时间过滤。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------- | ---------- | + | Promise<string[]> | Promise对象。返回文件名数组。 | + +**示例：** + + ```js + let options = { + "recursion": false, + "listNum": 0, + "filter": { + "suffix": [".png", ".jpg", ".jpeg"], + "displayName": ["%abc", "efg%"], + "fileSizeOver": 1024, + "lastModifiedAfter": new Date().getTime(), + } + }; + fs.listFile(pathDir, options).then((filenames) => { + console.info("listFile succeed"); + for (let i = 0; i < filenames.size; i++) { + console.info("fileName: %s", filenames[i]); + } + }).catch((err) => { + console.info("list file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## fs.listFile +listFile(path: string, options?: { + recursion?: boolean; + listNum?: number; + filter?: Filter; +}, callback: AsyncCallback): void; + +列出文件夹下所有文件名，支持递归列出所有文件名（包含子目录下），支持文件过滤，使用Callback异步回调。 + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | path | string | 是 | 文件夹的应用沙箱路径。 | + | options | Object | 否 | 文件过滤选项。 | + | callback | AsyncCallback<string[]> | 是 | 异步列出文件名数组之后的回调。 | + +**options参数说明：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | recursion | boolean | 否 | 是否递归子目录下文件名，默认为false。 | + | listNum | number | 否 | 列出文件名数量。当设置0时，列出所有文件，默认为0。 | + | filter | [Filter](#filter) | 否 | 文件过滤选项。当前仅支持后缀名匹配、文件名模糊查询、文件大小过滤、最近修改时间过滤。 | + +**示例：** + + ```js + let options = { + "recursion": false, + "listNum": 0, + "filter": { + "suffix": [".png", ".jpg", ".jpeg"], + "displayName": ["%abc", "efg%"], + "fileSizeOver": 1024, + "lastModifiedAfter": new Date().getTime(), + } + }; + fs.listFile(pathDir, options, (err, filenames) => { + if (err) { + console.info("list file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("listFile succeed"); + for (let i = 0; i < filenames.size; i++) { + console.info("filename: %s", filenames[i]); + } + } + }); + ``` + +## listFileSync + +listFileSync(path: string, options?: { + recursion?: boolean; + listNum?: number; + filter?: Filter; +}): string[]; + +以同步方式列出文件夹下所有文件名，支持递归列出所有文件名（包含子目录下），支持文件过滤。 + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | path | string | 是 | 文件夹的应用沙箱路径。 | + | options | Object | 否 | 文件过滤选项。 | + +**options参数说明：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | recursion | boolean | 否 | 是否递归子目录下文件名，默认为false。 | + | listNum | number | 否 | 列出文件名数量。当设置0时，列出所有文件，默认为0。 | + | filter | [Filter](#filter) | 否 | 文件过滤选项。当前仅支持后缀名匹配、文件名模糊查询、文件大小过滤、最近修改时间过滤。 | + +**返回值：** + + | 类型 | 说明 | + | --------------------- | ---------- | + | string[] | 返回文件名数组。 | + +**示例：** + + ```js + let options = { + "recursion": false, + "listNum": 0, + "filter": { + "suffix": [".png", ".jpg", ".jpeg"], + "displayName": ["%abc", "efg%"], + "fileSizeOver": 1024, + "lastModifiedAfter": new Date().getTime(), + } + }; + let filenames = fs.listFileSync(pathDir, options); + console.info("listFile succeed"); + for (let i = 0; i < filenames.size; i++) { + console.info("filename: %s", filenames[i]); + } + ``` +## moveFile + +moveFile(src: string, dest: string, mode?: number): Promise; + +移动文件，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | src | string | 是 | 源文件的应用沙箱路径。 | + | dest | string | 是 | 目的文件的应用沙箱路径。 | + | mode | number | 否 | 移动模式。若mode为0，移动位置存在同名文件时，强制移动覆盖。若mode为1，移动位置存在同名文件时，抛出异常。默认为0。 | + +**示例：** + + ```js + fs.moveFile(srcPath, destPath, 0).then(() => { + console.info("move file succeed"); + }).catch((err) => { + console.info("move file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +## moveFile + +moveFile(src: string, dest: string, mode?: number, callback: AsyncCallback): void; + +移动文件，使用Callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | src | string | 是 | 源文件的应用沙箱路径。 | + | dest | string | 是 | 目的文件的应用沙箱路径。 | + | mode | number | 否 | 移动模式。若mode为0，移动位置存在同名文件时，强制移动覆盖。若mode为1，移动位置存在同名文件时，抛出异常。默认为0。 | + | callback | AsyncCallback<void> | 是 | 异步移动文件之后的回调。 | + +**示例：** + + ```js + fs.moveFile(srcPath, destPath, 0, (err) => { + if (err) { + console.info("move file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.info("move file succeed"); + } + }); + ``` + +## moveFileSync + +moveFile(src: string, dest: string, mode?: number): void; + +以同步方式移动文件。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------ | ------ | ---- | --------------------------- | + | src | string | 是 | 源文件的应用沙箱路径。 | + | dest | string | 是 | 目的文件的应用沙箱路径。 | + | mode | number | 否 | 移动模式。若mode为0，移动位置存在同名文件时，强制移动覆盖。若mode为1，移动位置存在同名文件时，抛出异常。默认为0。 | + +**示例：** + + ```js + fs.moveFileSync(srcPath, destPath, 0); + console.info("move file succeed"); + ``` + ## fs.mkdtemp mkdtemp(prefix: string): Promise<string> @@ -2353,6 +2586,104 @@ readSync(buffer: ArrayBuffer, options?: { offset?: number; length?: number; }): | ---- | ------ | ---- | ---- | ------- | | fd | number | 是 | 否 | 打开的文件描述符。 | +### lock + +lock(exclusive?: boolean): Promise; + +文件阻塞式施加共享锁或独占锁，使用Promise异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | exclusive | boolean | 否 | 是否施加独占锁，默认false。 | + +**返回值：** + + | 类型 | 说明 | + | ---------------------------------- | ------ | + | Promise<void> | Promise对象。无返回值。 | + +**示例：** + + ```js + let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + file.lock(true).then(() => { + console.log("lock file successful"); + }).catch((err) => { + console.info("lock file failed with error message: " + err.message + ", error code: " + err.code); + }); + ``` + +### lock + +lock(exclusive?: boolean, callback: AsyncCallback): void; + +文件阻塞式施加共享锁或独占锁，使Callback异步回调。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | exclusive | boolean | 否 | 是否施加独占锁，默认false。 | + | callback | AsyncCallback<void> | 是 | 异步文件上锁之后的回调。 | + +**示例：** + + ```js + let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + file.lock(true, (err) => { + if (err) { + console.info("lock file failed with error message: " + err.message + ", error code: " + err.code); + } else { + console.log("lock file successful"); + } + }); + ``` + +### tryLock + +tryLock(exclusive?: boolean): void; + +文件非阻塞式施加共享锁或独占锁。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**参数：** + + | 参数名 | 类型 | 必填 | 说明 | + | ------- | ----------- | ---- | ---------------------------------------- | + | exclusive | boolean | 否 | 是否施加独占锁，默认false。 | + +**示例：** + + ```js + let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + file.tryLock(true); + console.log("lock file successful"); + ``` + +### unlock + +unlock(): void; + +以同步方式给文件解锁。 + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +**示例：** + + ```js + let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); + file.tryLock(true); + file.unlock(); + console.log("unlock file successful"); + ``` + ## OpenMode open接口flags参数常量。文件打开标签。 @@ -2371,3 +2702,18 @@ open接口flags参数常量。文件打开标签。 | DIR | number | 0o200000 | 如果path不指向目录，则出错。 | | NOFOLLOW | number | 0o400000 | 如果path指向符号链接，则出错。 | | SYNC | number | 0o4010000 | 以同步IO的方式打开文件。 | + +## Filter + +**系统能力**：SystemCapability.FileManagement.File.FileIO + +文件过滤配置项类型，支持listFile接口使用。 + +| 名称 | 类型 | 说明 | +| ----------- | --------------- | ------------------ | +| suffix | Array<string> | 文件后缀名完全匹配，各个关键词OR关系。 | +| displayName | Array<string> | 文件名模糊匹配，各个关键词OR关系。 | +| mimeType | Array<string> | mime类型完全匹配，各个关键词OR关系。 | +| fileSizeOver | number | 文件大小匹配，大于等于指定大小的文件。 | +| lastModifiedAfter | number | 文件最近修改时间匹配，在指定时间点及之后的文件。 | +| excludeMedia | boolean | 是否排除Media中已有的文件。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-hash.md b/zh-cn/application-dev/reference/apis/js-apis-file-hash.md index a38e3189c58e52af35f5dae9a9ab3a7d136c1a7a..911dac45c0fa4c0496587f491cf8f653872ac760 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-file-hash.md +++ b/zh-cn/application-dev/reference/apis/js-apis-file-hash.md @@ -92,6 +92,7 @@ hash(path: string, algorithm: string, callback: AsyncCallback<string>): vo **示例：** ```js + let filePath = pathDir + "/test.txt"; Hash.hash(filePath, "sha256", (err, str) => { if (err) { console.info("calculate file hash failed with error message: " + err.message + ", error code: " + err.code); diff --git a/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md b/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md index 4922e899d6e91946b7c4435df269340d5ad017c8..553c844ce0e0ff128b4d740b1e710f3fcad2e3c9 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md +++ b/zh-cn/application-dev/reference/apis/js-apis-file-statvfs.md @@ -35,7 +35,7 @@ getFreeSize(path:string):Promise<number> ```js let path = "/dev"; - statfs.getFreeSize(path).then((number) => { + statvfs.getFreeSize(path).then((number) => { console.info("getFreeSize promise successfully, Size: " + number); }).catch((err) => { console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code); @@ -61,7 +61,7 @@ getFreeSize(path:string, callback:AsyncCallback<number>): void ```js let path = "/dev"; - statfs.getFreeSize(path, (err, number) => { + statvfs.getFreeSize(path, (err, number) => { if (err) { console.info("getFreeSize failed with error message: " + err.message + ", error code: " + err.code); } else { @@ -94,7 +94,7 @@ getTotalSize(path: string): Promise<number> ```js let path = "/dev"; - statfs.getTotalSize(path).then((number) => { + statvfs.getTotalSize(path).then((number) => { console.info("getTotalSize promise successfully, Size: " + number); }).catch((err) => { console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code); @@ -120,7 +120,7 @@ getTotalSize(path: string, callback: AsyncCallback<number>): void ```js let path = "/dev"; - statfs.getTotalSize(path, (err, number) => { + statvfs.getTotalSize(path, (err, number) => { if (err) { console.info("getTotalSize with error message: " + err.message + ", error code: " + err.code); } else { diff --git a/zh-cn/application-dev/reference/apis/js-apis-fileio.md b/zh-cn/application-dev/reference/apis/js-apis-fileio.md index d91ab75f45afb008773622da895263bfbd783315..204537e9f0ff89cf89040682b07c8448cee57370 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-fileio.md +++ b/zh-cn/application-dev/reference/apis/js-apis-fileio.md @@ -3436,20 +3436,3 @@ isSymbolicLink(): boolean let dir = fileio.opendirSync(pathDir); let isSymbolicLink = dir.readSync().isSymbolicLink(); ``` - -## Filter9+ - -**系统接口**：此接口为系统接口。 - -**系统能力**：SystemCapability.FileManagement.File.FileIO - -文件过滤器配置项。 - -| 名称 | 类型 | 说明 | -| ----------- | --------------- | ------------------ | -| suffix | Array<string> | 文件后缀名，各个关键词OR关系。 | -| displayName | Array<string> | 文件名模糊匹配，各个关键词OR关系。 | -| mimeType | Array<string> | mime类型匹配，各个关键词OR关系。 | -| fileSizeOver | number | 文件大小匹配，大于等于指定大小的文件。 | -| lastModifiedAfter | Date | 修改时间匹配，在指定时间点后的文件。 | -| excludeMedia | Boolean | 是否排除Media中已有的文件。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-hichecker.md b/zh-cn/application-dev/reference/apis/js-apis-hichecker.md index 93c400c740ac864e64e7c65119e5fbde8e1ea693..b66101c41937973184db2f07fdbb06184173d37e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hichecker.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hichecker.md @@ -46,11 +46,11 @@ addCheckRule(rule: bigint): void ```js try { // 添加一条规则 - hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);} + hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // 添加多条规则 - hichecker.addCheckRule( - hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); -catch (err) { + // hichecker.addCheckRule( + // hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +} catch (err) { console.error(`code: ${err.code}, message: ${err.message}`); } ``` @@ -76,9 +76,9 @@ try { // 删除一条规则 hichecker.removeCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // 删除多条规则 - hichecker.removeCheckRule( - hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); -catch (err) { + // hichecker.removeCheckRule( + // hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH); +} catch (err) { console.error(`code: ${err.code}, message: ${err.message}`); } ``` @@ -113,7 +113,7 @@ try { // 查询是否包含 hichecker.containsCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true; hichecker.containsCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // return false; -catch (err) { +} catch (err) { console.error(`code: ${err.code}, message: ${err.message}`); } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-hidebug.md b/zh-cn/application-dev/reference/apis/js-apis-hidebug.md index 72e7c8ffa90f0f1aafb8685973b196dbb62e7ab1..66306729dc0da5f124d69eb0f9865c17b4259048 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-hidebug.md +++ b/zh-cn/application-dev/reference/apis/js-apis-hidebug.md @@ -297,7 +297,7 @@ import hidebug from '@ohos.hidebug' try { hidebug.startJsCpuProfiling("cpu_profiling"); - ... + // ... hidebug.stopJsCpuProfiling(); } catch (error) { console.info(error.code) @@ -326,7 +326,7 @@ import hidebug from '@ohos.hidebug' try { hidebug.startJsCpuProfiling("cpu_profiling"); - ... + // ... hidebug.stopJsCpuProfiling(); } catch (error) { console.info(error.code) diff --git a/zh-cn/application-dev/reference/apis/js-apis-observer.md b/zh-cn/application-dev/reference/apis/js-apis-observer.md index f1884f4831d2675b461808e02ae5baa1b4263cdb..f3d1b051fc1eab8f70b8af83f950ae70427582ec 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-observer.md +++ b/zh-cn/application-dev/reference/apis/js-apis-observer.md @@ -30,6 +30,17 @@ on\(type: \'networkStateChange\', callback: Callback\): void; | type | string | 是 | 网络状态变化事件 | | callback | Callback\<[NetworkState](js-apis-radio.md#networkstate)\> | 是 | 回调函数。参考radio的[NetworkState](js-apis-radio.md#networkstate) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -57,6 +68,17 @@ on\(type: \'networkStateChange\', options: { slotId: number }, callback: Callbac | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | Callback\<[NetworkState](js-apis-radio.md#networkstate)\> | 是 | 回调函数。参考radio的[NetworkState](js-apis-radio.md#networkstate) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -85,6 +107,14 @@ off\(type: \'networkStateChange\', callback?: Callback\): void; | type | string | 是 | 网络状态变化事件 | | callback | Callback\<[NetworkState](js-apis-radio.md#networkstate)\> | 否 | 回调函数。参考radio的[NetworkState](js-apis-radio.md#networkstate) | +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -112,6 +142,17 @@ on\(type: \'signalInfoChange\', callback: Callback\>): | type | string | 是 | 信号状态变化事件 | | callback | Callback\> | 是 | 回调函数。参考radio的[SignalInformation](js-apis-radio.md#signalinformation) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -137,6 +178,17 @@ on\(type: \'signalInfoChange\', options: { slotId: number }, callback: Callback< | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | Callback\> | 是 | 回调函数。参考radio的[SignalInformation](js-apis-radio.md#signalinformation) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -165,6 +217,16 @@ off\(type: \'signalInfoChange\', callback?: Callback\> | type | string | 是 | 信号状态变化事件 | | callback | Callback\> | 否 | 回调函数。参考radio的[SignalInformation](js-apis-radio.md#signalinformation) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -193,6 +255,16 @@ on(type: 'callStateChange', callback: Callback\<{ state: CallState, number: stri | type | string | 是 | 通话状态变化事件 | | callback | Callback\<{ state: [CallState](js-apis-call.md#callstate), number: string }\> | 是 | 回调函数，参考call的[CallState](js-apis-call.md#callstate)
number：电话号码 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -218,6 +290,16 @@ on(type: 'callStateChange', options: { slotId: number }, callback: Callback<{ st | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | Callback\<{ state: [CallState](js-apis-call.md#callstate), number: string }\> | 是 | 回调函数，参考call的[CallState](js-apis-call.md#callstate)
number：电话号码 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -246,6 +328,16 @@ off(type: 'callStateChange', callback?: Callback<{ state: CallState, number: str | type | string | 是 | 通话状态变化事件 | | callback | Callback\<{ state: [CallState](js-apis-call.md#callstate), number: string }\> | 否 | 回调函数，参考call的[CallState](js-apis-call.md#callstate)
number：电话号码 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -274,6 +366,16 @@ on\(type: 'cellularDataConnectionStateChange', callback: Callback\<{ state: Data | type | string | 是 | 蜂窝数据链路连接状态事件 | | callback | Callback\<{ state: [DataConnectState](js-apis-telephony-data.md#dataconnectstate), network: [RatType](js-apis-radio.md#radiotechnology) }\> | 是 | 回调函数，参考data的[DataConnectState](js-apis-telephony-data.md#dataconnectstate)，radio的[RadioTechnology](js-apis-radio.md#radiotechnology)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -299,6 +401,16 @@ on\(type: 'cellularDataConnectionStateChange', options: { slotId: number }, call | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | Callback\<{ state: [DataConnectState](js-apis-telephony-data.md#dataconnectstate), network: [RatType](js-apis-radio.md#radiotechnology) }\> | 是 | 回调函数，参考data的[DataConnectState](js-apis-telephony-data.md#dataconnectstate)，radio的[RadioTechnology](js-apis-radio.md#radiotechnology)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -327,6 +439,16 @@ off\(type: 'cellularDataConnectionStateChange', callback?: Callback\<{ state: D | type | string | 是 | 蜂窝数据链路连接状态事件 | | callback | Callback\<{ state: [DataConnectState](js-apis-telephony-data.md#dataconnectstate), network: [RatType](js-apis-radio.md#radiotechnology) }\> | 否 | 回调函数，参考data的[DataConnectState](js-apis-telephony-data.md#dataconnectstate)，radio的[RadioTechnology](js-apis-radio.md#radiotechnology)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -355,6 +477,16 @@ on\(type: 'cellularDataFlowChange', callback: Callback\\): void; | type | string | 是 | 蜂窝数据业务的上下行数据流状态状态事件 | | callback | Callback\<[DataFlowType](js-apis-telephony-data.md#dataflowtype)\> | 是 | 回调函数，参考data的[DataFlowType](js-apis-telephony-data.md#dataflowtype)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -380,6 +512,16 @@ on\(type: 'cellularDataFlowChange', options: { slotId: number }, callback: Call | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | Callback\<[DataFlowType](js-apis-telephony-data.md#dataflowtype)\> | 是 | 回调函数，参考data的[DataFlowType](js-apis-telephony-data.md#dataflowtype)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -408,6 +550,16 @@ off\(type: 'cellularDataFlowChange', callback?: Callback\\): void | type | string | 是 | 蜂窝数据业务的上下行数据流状态事件 | | callback | Callback\<[DataFlowType](js-apis-telephony-data.md#dataflowtype)\> | 否 | 回调函数，参考data的[DataFlowType](js-apis-telephony-data.md#dataflowtype)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -436,6 +588,16 @@ on\(type: 'simStateChange', callback: Callback\\): void; | type | string | 是 | sim状态更改事件 | | callback | Callback\<[SimStateData](#simstatedata7)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -461,6 +623,16 @@ on\(type: 'simStateChange', options: { slotId: number }, callback: Callback\- 0：卡槽1
- 1：卡槽2 | | callback | Callback\<[SimStateData](#simstatedata7)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -489,6 +661,16 @@ off\(type: 'simStateChange', callback?: Callback\\): void; | type | string | 是 | sim状态更改事件 | | callback | Callback\<[SimStateData](#simstatedata7)\> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js diff --git a/zh-cn/application-dev/reference/apis/js-apis-radio.md b/zh-cn/application-dev/reference/apis/js-apis-radio.md index a95004670962fcf0b72b05d240f66aa385ce3998..e4b9820b11024bba97664856f3fa020da0af66a2 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-radio.md +++ b/zh-cn/application-dev/reference/apis/js-apis-radio.md @@ -30,6 +30,17 @@ getRadioTech\(slotId: number, callback: AsyncCallback<\{psRadioTech: RadioTechno | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<{psRadioTech: [RadioTechnology](#radiotechnology), csRadioTech:[RadioTechnology](#radiotechnology)}\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -62,6 +73,17 @@ getRadioTech\(slotId: number\): Promise<\{psRadioTech: RadioTechnology, csRadioT | ------------------------------------------------------------ | ----------------------------------------------- | | Promise<{psRadioTech: [RadioTechnology](#radiotechnology), csRadioTech: [RadioTechnology](#radiotechnology)}> | 以Promise形式返回获取当前接入的CS域和PS域技术。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -91,6 +113,17 @@ getNetworkState\(callback: AsyncCallback\): void | -------- | ---------------------------------------------- | ---- | ---------- | | callback | AsyncCallback\<[NetworkState](#networkstate)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -117,6 +150,17 @@ getNetworkState\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[NetworkState](#networkstate)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -149,6 +193,17 @@ getNetworkState\(slotId?: number\): Promise | ---------------------------------------- | --------------------------- | | Promise\<[NetworkState](#networkstate)\> | 以Promise形式返回网络状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -177,6 +232,16 @@ getNetworkSelectionMode\(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[NetworkSelectionMode](#networkselectionmode)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -207,6 +272,16 @@ getNetworkSelectionMode\(slotId: number\): Promise | -------------------------------------------------------- | ------------------------------- | | Promise\<[NetworkSelectionMode](#networkselectionmode)\> | 以Promise形式返回当前选网模式。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -235,6 +310,16 @@ getISOCountryCodeForNetwork\(slotId: number, callback: AsyncCallback\): | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。返回国家码，例如：CN（中国）。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -265,6 +350,16 @@ getISOCountryCodeForNetwork\(slotId: number\): Promise | ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回注册网络所在国家的ISO国家码，例如CN（中国）。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -292,6 +387,16 @@ getPrimarySlotId\(callback: AsyncCallback\\): void | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | callback | AsyncCallback\ | 是 | 回调函数 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -315,6 +420,16 @@ getPrimarySlotId\(\): Promise\ | ----------------------------------------------------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回获取设备主卡所在卡槽的索引号的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -342,6 +457,16 @@ getSignalInformation\(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\\> | 是 | 回调函数，返回[SignalInformation](#signalinformation)对象的数组。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -372,6 +497,16 @@ getSignalInformation\(slotId: number\): Promise\> | ----------------------------------------------------------- | ------------------------------------------------------------ | | Promise\\> | 以Promise形式返回网络信号强度[SignalInformation](#signalinformation)对象的数组。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -509,6 +644,17 @@ isRadioOn\(callback: AsyncCallback\): void | -------- | ------------------------ | ---- | ------------------------------------------------------- | | callback | AsyncCallback\ | 是 | 回调函数。
- true：Radio打开
- false：Radio关闭 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -535,6 +681,17 @@ isRadioOn\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。
- true：Radio打开
- false：Radio关闭 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -567,6 +724,17 @@ isRadioOn\(slotId?: number\): Promise | ------------------ | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回判断Radio是否打开的结果。
- true：Radio打开
- false：Radio关闭 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -595,6 +763,16 @@ getOperatorName\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数，返回运营商名称，例如：中国移动。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -625,6 +803,16 @@ getOperatorName\(slotId: number\): Promise | ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回运营商名称，例如：中国移动。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -656,6 +844,18 @@ setPrimarySlotId(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -690,6 +890,18 @@ setPrimarySlotId\(slotId: number\): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -720,6 +932,17 @@ getIMEI(callback: AsyncCallback): void | -------- | ----------------------- | ---- | ------------------------------------------ | | callback | AsyncCallback\ | 是 | 回调函数，如果IMEI不存在，则返回空字符串。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -748,6 +971,17 @@ getIMEI(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数，如果IMEI不存在，则返回空字符串。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -782,6 +1016,17 @@ getIMEI(slotId?: number): Promise | ----------------- | ------------------------------------------ | | Promise\ | 以Promise形式异步返回IMEI；如果IMEI不存在，则返回空字符串。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -812,6 +1057,17 @@ getMEID(callback: AsyncCallback): void | -------- | ----------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -840,6 +1096,17 @@ getMEID(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -874,6 +1141,17 @@ getMEID(slotId?: number): Promise | ----------------- | --------------------------------------- | | Promise\ | 以Promise形式返回设备的指定卡槽的MEID。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -904,6 +1182,17 @@ getUniqueDeviceId(callback: AsyncCallback): void | -------- | ----------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -932,6 +1221,17 @@ getUniqueDeviceId(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -966,6 +1266,17 @@ getUniqueDeviceId(slotId?: number): Promise | ----------------- | --------------------------------------------- | | Promise\ | 以Promise形式返回设备的指定卡槽的唯一设备ID。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -996,6 +1307,17 @@ sendUpdateCellLocationRequest\(callback: AsyncCallback\): void | -------- | --------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1023,6 +1345,17 @@ sendUpdateCellLocationRequest\(slotId: number, callback: AsyncCallback\): | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1056,6 +1389,17 @@ sendUpdateCellLocationRequest\(slotId?: number): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1086,6 +1430,17 @@ getCellInformation(callback: AsyncCallback>): void | -------- | ------------------------------------------------------------ | ---- | ------------------------ | | callback | AsyncCallback\\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1114,6 +1469,17 @@ getCellInformation(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1148,6 +1514,17 @@ getCellInformation(slotId?: number): Promise\> | ------------------------------------------------------- | ----------------------- | | Promise\\> | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1179,6 +1556,17 @@ setNetworkSelectionMode\(options: NetworkSelectionModeOptions, callback: AsyncCa | options | [NetworkSelectionModeOptions](#networkselectionmodeoptions) | 是 | 网络选择模式选项。 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1223,6 +1611,17 @@ setNetworkSelectionMode\(options: NetworkSelectionModeOptions\): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1265,6 +1664,17 @@ getNetworkSearchInformation\(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[NetworkSearchResult](#networksearchresult)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1297,6 +1707,17 @@ getNetworkSearchInformation\(slotId: number\): Promise | ------------------------------------------------------ | ----------------------- | | Promise\<[NetworkSearchResult](#networksearchresult)\> | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1324,6 +1745,16 @@ getNrOptionMode(callback: AsyncCallback): void | -------- | ----------------------------------------------- | ---- | ---------- | | callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1350,6 +1781,16 @@ getNrOptionMode(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[NrOptionMode](#nroptionmode8)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1382,6 +1823,16 @@ getNrOptionMode(slotId?: number): Promise | ----------------------------------------- | ----------------------- | | Promise\<[NrOptionMode](#nroptionmode8)\> | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1412,6 +1863,17 @@ turnOnRadio(callback: AsyncCallback): void | -------- | --------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1440,6 +1902,17 @@ turnOnRadio(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1474,6 +1947,17 @@ turnOnRadio(slotId?: number): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1504,6 +1988,17 @@ turnOffRadio(callback: AsyncCallback): void | -------- | --------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1532,6 +2027,17 @@ turnOffRadio(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1566,6 +2072,17 @@ turnOffRadio(slotId?: number): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1598,6 +2115,17 @@ setPreferredNetwork\(slotId: number, networkMode: PreferredNetworkMode, callback | networkMode | [PreferredNetworkMode](#preferrednetworkmode8) | 是 | 设置首选网络模式。 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1631,6 +2159,17 @@ setPreferredNetwork(slotId: number, networkMode: PreferredNetworkMode): Promise< | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1656,11 +2195,22 @@ getPreferredNetwork\(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------------------------------- | ---- | -------------------------------------- | +| slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[PreferredNetworkMode](#preferrednetworkmode8)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1693,6 +2243,17 @@ getPreferredNetwork(slotId: number): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1724,6 +2285,17 @@ getImsRegInfo(slotId: number, imsType: ImsServiceType, callback: AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1757,6 +2329,17 @@ getImsRegInfo(slotId: number, imsType: ImsServiceType): Promise | ------------------------------------- | ----------------------- | | Promise\<[ImsRegInfo](#imsreginfo9)\> | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1789,6 +2372,17 @@ on(type: 'imsRegStateChange', slotId: number, imsType: ImsServiceType, callback: | imsType | [ImsServiceType](#imsservicetype9) | 是 | IMS服务类型。 | | callback | Callback<[ImsRegInfo](#imsreginfo9)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1818,6 +2412,17 @@ off(type: 'imsRegStateChange', slotId: number, imsType: ImsServiceType, callback | imsType | [ImsServiceType](#imsservicetype9) | 是 | IMS服务类型。 | | callback | Callback<[ImsRegInfo](#imsreginfo9)> | 否 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1855,11 +2460,11 @@ radio.off('imsRegStateChange', 0, radio.ImsServiceType.TYPE_VIDEO, data => { **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CoreService。 -| 名称 | 类型 | 必填 | 说明 | -| ----------- | --------------------------- | ---- | ----------------- | -| signalType | [NetworkType](#networktype) | 是 | 网络信号强度类型。 | -| signalLevel | number | 是 | 网络信号强度等级。 | - +| 名称 | 类型 | 必填 | 说明 | +| --------------- | --------------------------- | ---- | ------------------ | +| signalType | [NetworkType](#networktype) | 是 | 网络信号强度类型。 | +| signalLevel | number | 是 | 网络信号强度等级。 | +| dBm9+| number | 是 | 网络信号强度。 | ## NetworkType diff --git a/zh-cn/application-dev/reference/apis/js-apis-rpc.md b/zh-cn/application-dev/reference/apis/js-apis-rpc.md index e6683dd673247346780a300625e06cb221ec1c4f..1c9fd94d4d1606edad006c7ce6550151cb365688 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-rpc.md +++ b/zh-cn/application-dev/reference/apis/js-apis-rpc.md @@ -2391,6 +2391,8 @@ readException(): void **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -2411,6 +2413,11 @@ readException(): void "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendMessageRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageSequence.create(); let reply = rpc.MessageSequence.create(); @@ -4839,6 +4846,8 @@ readException(): void **系统能力**：SystemCapability.Communication.IPC.Core **示例：** + + 获取服务 ```ts import FA from "@ohos.ability.featureAbility"; @@ -4860,6 +4869,11 @@ readException(): void "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendMessageRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); let reply = rpc.MessageParcel.create(); @@ -5640,6 +5654,8 @@ asObject(): IRemoteObject **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -5660,7 +5676,11 @@ asObject(): IRemoteObject "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); - + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的asObject接口方法获取代理或远端对象 + + ```ts class TestProxy { remote: rpc.RemoteObject; constructor(remote) { @@ -5802,7 +5822,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult> -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -5826,7 +5846,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption): Promise<RequestResult> -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -5850,7 +5870,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -5870,7 +5890,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6052,7 +6072,7 @@ isObjectDead(): boolean sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6073,6 +6093,8 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6093,6 +6115,11 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); let reply = rpc.MessageParcel.create(); @@ -6115,7 +6142,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption): Promise<RequestResult> -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6136,6 +6163,8 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6156,6 +6185,11 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendMessageRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageSequence.create(); let reply = rpc.MessageSequence.create(); @@ -6186,7 +6220,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult> -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6207,6 +6241,8 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6227,6 +6263,11 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); let reply = rpc.MessageParcel.create(); @@ -6255,7 +6296,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendMessageRequest返回后的某个时机执行回调，回复内容在RequestResult的reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendMessageRequest返回后的某个时机执行回调，回复内容在RequestResult的reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6270,6 +6311,8 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, | callback | AsyncCallback<RequestResult> | 是 | 接收发送结果的回调。 | **示例：** + + 获取服务 ```ts import FA from "@ohos.ability.featureAbility"; @@ -6304,6 +6347,11 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, result.reply.reclaim(); } FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendMessageRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageSequence.create(); let reply = rpc.MessageSequence.create(); @@ -6323,7 +6371,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -6339,6 +6387,8 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6372,6 +6422,11 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me result.reply.reclaim(); } FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的sendRequest接口方法发送消息 + + ```ts let option = new rpc.MessageOption(); let data = rpc.MessageParcel.create(); let reply = rpc.MessageParcel.create(); @@ -6410,6 +6465,8 @@ getLocalInterface(interface: string): IRemoteBroker **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6430,6 +6487,11 @@ getLocalInterface(interface: string): IRemoteBroker "abilityName":"com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的getLocalInterface接口方法查询接口对象 + + ```ts try { let broker = proxy.getLocalInterface("testObject"); console.log("RpcClient: getLocalInterface is " + broker); @@ -6463,6 +6525,8 @@ queryLocalInterface(interface: string): IRemoteBroker **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6483,6 +6547,11 @@ queryLocalInterface(interface: string): IRemoteBroker "abilityName":"com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的queryLocalInterface接口获取接口对象 + + ```ts let broker = proxy.queryLocalInterface("testObject"); console.log("RpcClient: queryLocalInterface is " + broker); ``` @@ -6512,6 +6581,8 @@ registerDeathRecipient(recipient: DeathRecipient, flags: number): void **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6532,6 +6603,11 @@ registerDeathRecipient(recipient: DeathRecipient, flags: number): void "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的registerDeathRecipient接口注册死亡回调 + + ```ts class MyDeathRecipient { onRemoteDied() { console.log("server died"); @@ -6539,7 +6615,7 @@ registerDeathRecipient(recipient: DeathRecipient, flags: number): void } let deathRecipient = new MyDeathRecipient(); try { - proxy.registerDeathRecippient(deathRecipient, 0); + proxy.registerDeathRecipient(deathRecipient, 0); } catch(error) { console.info("proxy register deathRecipient fail, errorCode " + error.code); console.info("proxy register deathRecipient fail, errorMessage " + error.message); @@ -6571,6 +6647,8 @@ addDeathRecipient(recipient: DeathRecipient, flags: number): boolean **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6591,13 +6669,18 @@ addDeathRecipient(recipient: DeathRecipient, flags: number): boolean "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的addDeathRecippient接口方法新增死亡回调 + + ```ts class MyDeathRecipient { onRemoteDied() { console.log("server died"); } } let deathRecipient = new MyDeathRecipient(); - proxy.addDeathRecippient(deathRecipient, 0); + proxy.addDeathRecipient(deathRecipient, 0); ``` ### unregisterDeathRecipient9+ @@ -6625,6 +6708,8 @@ unregisterDeathRecipient(recipient: DeathRecipient, flags: number): boolean **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6645,6 +6730,11 @@ unregisterDeathRecipient(recipient: DeathRecipient, flags: number): boolean "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的unregisterDeathRecipient接口方法注销死亡回调 + + ```ts class MyDeathRecipient { onRemoteDied() { console.log("server died"); @@ -6685,6 +6775,8 @@ removeDeathRecipient(recipient: DeathRecipient, flags: number): boolean **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6705,6 +6797,11 @@ removeDeathRecipient(recipient: DeathRecipient, flags: number): boolean "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的removeDeathRecipient接口方法去注册死亡回调 + + ```ts class MyDeathRecipient { onRemoteDied() { console.log("server died"); @@ -6740,6 +6837,8 @@ getDescriptor(): string **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6760,6 +6859,10 @@ getDescriptor(): string "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的getDescriptor接口方法获取对象的接口描述符 + + ```ts try { let descriptor = proxy.getDescriptor(); console.log("RpcClient: descriptor is " + descriptor); @@ -6787,6 +6890,8 @@ getInterfaceDescriptor(): string **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6807,6 +6912,11 @@ getInterfaceDescriptor(): string "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的getInterfaceDescriptor接口方法查询当前代理对象接口的描述符 + + ```ts let descriptor = proxy.getInterfaceDescriptor(); console.log("RpcClient: descriptor is " + descriptor); ``` @@ -6827,6 +6937,8 @@ isObjectDead(): boolean **示例：** + 获取服务 + ```ts import FA from "@ohos.ability.featureAbility"; let proxy; @@ -6847,6 +6959,11 @@ isObjectDead(): boolean "abilityName": "com.ohos.server.EntryAbility", }; FA.connectAbility(want, connect); + ``` + + 上述onConnect回调函数中的proxy对象需要等ability异步连接成功后才会被赋值，然后才可调用proxy对象的isObjectDead接口方法判断当前对象是否已经死亡 + + ```ts let isDead = proxy.isObjectDead(); console.log("RpcClient: isObjectDead is " + isDead); ``` @@ -7452,7 +7569,7 @@ RemoteObject构造函数。 sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): boolean -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -7518,7 +7635,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption): Promise<SendRequestResult> -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -7588,7 +7705,7 @@ sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: Me sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption): Promise<RequestResult> -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则期约立即兑现，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则期约将在sendMessageRequest返回时兑现，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -7644,7 +7761,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, options: MessageOption, callback: AsyncCallback<RequestResult>): void -以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendMessageRequest返回时收到回调，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageSequence消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendMessageRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core @@ -7694,7 +7811,7 @@ sendMessageRequest(code: number, data: MessageSequence, reply: MessageSequence, sendRequest(code: number, data: MessageParcel, reply: MessageParcel, options: MessageOption, callback: AsyncCallback<SendRequestResult>): void -以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 +以同步或异步方式向对端进程发送MessageParcel消息。如果为选项设置了异步模式，则立即收到回调，reply报文里没有内容，具体回复需要在业务侧的回调中获取。如果为选项设置了同步模式，则将在sendRequest返回时收到回调，回复内容在reply报文里。 **系统能力**：SystemCapability.Communication.IPC.Core diff --git a/zh-cn/application-dev/reference/apis/js-apis-runninglock.md b/zh-cn/application-dev/reference/apis/js-apis-runninglock.md index c98c19d58950f4320a1559d1fdf5bc937a26b4c0..30d0bcbeb7b252ffa55dc0441f134c2d7d584301 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-runninglock.md +++ b/zh-cn/application-dev/reference/apis/js-apis-runninglock.md @@ -476,7 +476,7 @@ RunningLock锁的类型。 **系统能力：** SystemCapability.PowerManager.PowerManager.Core -| 名称 | 值 | 说明 | -| ------------------------ | ---- | -------------------------------------- | -| BACKGROUND | 1 | 阻止系统休眠的锁。 | -| PROXIMITY_SCREEN_CONTROL | 2 | 通过接近或者远离状态来控制亮灭屏的锁。 | +| 名称 | 值 | 说明 | +| --------------------------------- | ---- | ------------------------------------------------------------ | +| BACKGROUND(deprecated) | 1 | 阻止系统休眠的锁。
**说明：** 从API version 7开始支持，从API version 10开始废弃。 | +| PROXIMITY_SCREEN_CONTROL | 2 | 通过接近或者远离状态来控制亮灭屏的锁。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-sensor.md b/zh-cn/application-dev/reference/apis/js-apis-sensor.md index 1394bad4ec55496863c60344f9134b7fa3a2db67..282bab54a75a6fb77c5fe7a8ac5e1457b319b4bf 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-sensor.md +++ b/zh-cn/application-dev/reference/apis/js-apis-sensor.md @@ -3477,7 +3477,7 @@ try { | 名称 | 类型 | 可读 | 可写 | 说明 | | --------------- | -------- | ---------------------- | ---------------------- | ---------------------- | | sensorName | string | 是 | 是 | 传感器名称。 | -| venderName | string | 是 | 是 | 传感器供应商。 | +| vendorName | string | 是 | 是 | 传感器供应商。 | | firmwareVersion | string | 是 | 是 | 传感器固件版本。 | | hardwareVersion | string | 是 | 是 | 传感器硬件版本。 | | sensorId | number | 是 | 是 | 传感器类型id。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-settings.md b/zh-cn/application-dev/reference/apis/js-apis-settings.md index 3c92903dd4b91ad78982c2693358ac314e7338dd..1f020cc283bc5bfc9c08d621254730d90c1a167a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-settings.md +++ b/zh-cn/application-dev/reference/apis/js-apis-settings.md @@ -185,121 +185,6 @@ import settings from '@ohos.settings'; | WIFI_STATUS | string | 是 | 是 | Wi-Fi是否可用。
值为true表示Wi-Fi可用；
值为false表示Wi-Fi不可用。 | | WIFI_WATCHDOG_STATUS | string | 是 | 是 | Wi-Fi的WatchDog是否可用。
值为true表示可用；
值为false表示不可用。 | -## setting.getURI - -getURI(name: string, callback: AsyncCallback\): void - -获取数据项的URI。使用callback异步回调。 - -**系统能力**：SystemCapability.Applications.settings.Core - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ---------------------- | ---- | ------------------------------------------------------------ | -| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | -| callback | AsyncCallback\ | 是 | 回调函数。获取数据项的URI。 | - -**示例**： - -```js -settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri) => { - console.log(`callback:uri -> ${JSON.stringify(uri)}`) -}) -``` - -## setting.getURI - -getURI(name: string): Promise\ - -获取数据项的URI。使用Promise异步回调。 - -**系统能力**：SystemCapability.Applications.settings.Core - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ------ | ------ | ---- | ------------------------------------------------------------ | -| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | - -**返回值**： - -| 类型 | 说明 | -| ---------------- | ------------------------------------ | -| Promise\ | Promise对象。返回获取的数据项的URI。 | - -**示例**： - -```js -settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri) => { - console.log(`promise:uri -> ${JSON.stringify(uri)}`) -}) -``` - -## setting.getValue - -getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback\): void - -获取数据库中指定数据项的值。使用callback异步回调。 - -**系统能力**：SystemCapability.Applications.settings.Core - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | -| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | -| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | -| callback | AsyncCallback\ | 是 | 使用callback方式获取数据项的值。 | - -**示例**： - -```js -import featureAbility from '@ohos.ability.featureAbility'; - -let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); -let helper = featureAbility.acquireDataAbilityHelper(uri); -settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => { - if (err) { - console.error(`Failed to get the setting. ${err.message} `); - return; - } - console.log(`callback:value -> ${JSON.stringify(value)}`) -}); -``` - -## setting.getValue - -getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise\ - -获取数据库中指定数据项的值。使用Promise异步回调。 - -**系统能力**：SystemCapability.Applications.settings.Core - -**参数**： - -| 参数名 | 类型 | 必填 | 说明 | -| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | -| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | -| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | - -**返回值**： - -| 类型 | 说明 | -| ---------------- | ----------------------------------- | -| Promise\ | Promise对象。返回获得的数据项的值。 | - -**示例**： - -```js -import featureAbility from '@ohos.ability.featureAbility'; - -let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); -let helper = featureAbility.acquireDataAbilityHelper(uri); -settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => { - console.log(`promise:value -> ${JSON.stringify(value)}`) -}); -``` ## settings.setValue @@ -504,12 +389,154 @@ getUriSync(name: string): string let urivar = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); ``` -## settings.getValueSync8+ +## setting.getURI(deprecated) + +getURI(name: string, callback: AsyncCallback\): void + +获取数据项的URI。使用callback异步回调。 + +> **说明：** +> +> 从 API version 7开始支持，从API version 9开始废弃。 + +**系统能力**：SystemCapability.Applications.settings.Core + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | ------------------------------------------------------------ | +| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | +| callback | AsyncCallback\ | 是 | 回调函数。获取数据项的URI。 | + +**示例**： + +```js +settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS, (uri) => { + console.log(`callback:uri -> ${JSON.stringify(uri)}`) +}) +``` + +## setting.getURI(deprecated) + +getURI(name: string): Promise\ + +获取数据项的URI。使用Promise异步回调。 + +> **说明：** +> +> 从 API version 7开始支持，从API version 9开始废弃。 + +**系统能力**：SystemCapability.Applications.settings.Core + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ------------------------------------------------------------ | +| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------- | ------------------------------------ | +| Promise\ | Promise对象。返回获取的数据项的URI。 | + +**示例**： + +```js +settings.getURI(settings.display.SCREEN_BRIGHTNESS_STATUS).then((uri) => { + console.log(`promise:uri -> ${JSON.stringify(uri)}`) +}) +``` + +## setting.getValue(deprecated) + +getValue(dataAbilityHelper: DataAbilityHelper, name: string, callback: AsyncCallback\): void + +获取数据库中指定数据项的值。使用callback异步回调。 + +> **说明：** +> +> 从 API version 7开始支持，从API version 9开始废弃。 + +**模型约束**：此接口仅可在FA模型下使用。 + +**系统能力**：SystemCapability.Applications.settings.Core + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | +| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | +| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | +| callback | AsyncCallback\ | 是 | 使用callback方式获取数据项的值。 | + +**示例**： + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); +let helper = featureAbility.acquireDataAbilityHelper(uri); +settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, (err, value) => { + if (err) { + console.error(`Failed to get the setting. ${err.message} `); + return; + } + console.log(`callback:value -> ${JSON.stringify(value)}`) +}); +``` + +## setting.getValue(deprecated) + +getValue(dataAbilityHelper: DataAbilityHelper, name: string): Promise\ + +获取数据库中指定数据项的值。使用Promise异步回调。 + +> **说明：** +> +> 从 API version 7开始支持，从API version 9开始废弃。 + +**模型约束**：此接口仅可在FA模型下使用。 + +**系统能力**：SystemCapability.Applications.settings.Core + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| ----------------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | +| dataAbilityHelper | [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 是 | 数据管理辅助类。 | +| name | string | 是 | 数据项的名称。数据项名称分为以下两种：
- 上述任意一个数据库中已存在的数据项。
- 开发者自行添加的数据项。 | + +**返回值**： + +| 类型 | 说明 | +| ---------------- | ----------------------------------- | +| Promise\ | Promise对象。返回获得的数据项的值。 | + +**示例**： + +```js +import featureAbility from '@ohos.ability.featureAbility'; + +let uri = settings.getUriSync(settings.display.SCREEN_BRIGHTNESS_STATUS); +let helper = featureAbility.acquireDataAbilityHelper(uri); +settings.getValue(helper, settings.display.SCREEN_BRIGHTNESS_STATUS).then((value) => { + console.log(`promise:value -> ${JSON.stringify(value)}`) +}); +``` + +## settings.getValueSync(deprecated) getValueSync(dataAbilityHelper: DataAbilityHelper, name: string, defValue: string): string 获取数据项的值。此方法相较getValue为同步方法。 +> **说明：** +> +> 从 API version 8开始支持，从API version 9开始废弃。 + +**模型约束**：此接口仅可在FA模型下使用。 + **系统能力**：SystemCapability.Applications.settings.Core **参数**： @@ -537,7 +564,7 @@ let helper = featureAbility.acquireDataAbilityHelper(uri); let value = settings.getValueSync(helper, settings.display.SCREEN_BRIGHTNESS_STATUS, '10'); ``` -## settings.setValueSync8+ +## settings.setValueSync(deprecated) setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): boolean @@ -545,6 +572,12 @@ setValueSync(dataAbilityHelper: DataAbilityHelper, name: string, value: string): 如果数据库中已经存在该数据项，则setValueSync方法将更新该数据项的值；如果数据库中尚未存在该数据项，则setValueSync方法将向数据库中插入该数据项。 +> **说明：** +> +> 从 API version 8开始支持，从API version 9开始废弃。 + +**模型约束**：此接口仅可在FA模型下使用。 + **需要权限**：ohos.permission.MANAGE_SECURE_SETTINGS，仅系统应用可用。 **系统能力**：SystemCapability.Applications.settings.Core diff --git a/zh-cn/application-dev/reference/apis/js-apis-sim.md b/zh-cn/application-dev/reference/apis/js-apis-sim.md index b4902e0826bce301aaa807ab161d6a386a79dcfd..2b2def039972e6044e70c0b7afed2fae469204a5 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-sim.md +++ b/zh-cn/application-dev/reference/apis/js-apis-sim.md @@ -132,6 +132,17 @@ hasOperatorPrivileges(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -160,6 +171,17 @@ hasOperatorPrivileges(slotId: number): Promise | :----------------- | :---------------------------------------------------------- | | Promise\ | 以Promise形式返回检查应用（调用者）是否已被授予运营商权限。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -186,6 +208,17 @@ getISOCountryCodeForSim\(slotId: number, callback: AsyncCallback\): voi | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。返回国家码，例如：CN（中国）。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -215,6 +248,17 @@ getISOCountryCodeForSim\(slotId: number\): Promise | ----------------- | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回获取指定卡槽SIM卡的ISO国家码，例如：CN（中国）。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -242,6 +286,17 @@ getSimOperatorNumeric\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -271,6 +326,17 @@ getSimOperatorNumeric\(slotId: number\): Promise | ----------------- | ------------------------------------------------ | | Promise\ | 以Promise形式返回获取指定卡槽SIM卡的归属PLMN号。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -298,6 +364,17 @@ getSimSpn\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -327,6 +404,17 @@ getSimSpn\(slotId: number\): Promise | ----------------- | ----------------------------------------- | | Promise\ | 以Promise形式返回获取指定卡槽SIM卡的SPN。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -354,6 +442,17 @@ getSimState\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[SimState](#simstate)\> | 是 | 回调函数。参考[SimState](#simstate)。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -383,6 +482,17 @@ getSimState\(slotId: number\): Promise | -------------------------------- | ------------------------------------------ | | Promise\<[SimState](#simstate)\> | 以Promise形式返回获取指定卡槽的SIM卡状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -409,6 +519,17 @@ getCardType\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[CardType](#cardtype7)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -438,6 +559,17 @@ getCardType\(slotId: number\): Promise | ----------------- | ------------------------------------------------------------ | | Promise\<[CardType](#cardtype7)\> | 以Promise形式返回指定卡槽SIM卡的卡类型。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -465,6 +597,17 @@ hasSimCard\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -494,6 +637,17 @@ hasSimCard\(slotId: number\): Promise | --------------------- | ---------------------------------- | | Promise<boolean> | 以Promise形式返回指定卡槽是否插卡，如果插卡返回true。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -524,6 +678,19 @@ getSimAccountInfo(slotId: number, callback: AsyncCallback): voi | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\<[IccAccountInfo](#iccaccountinfo7)\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -557,6 +724,19 @@ getSimAccountInfo(slotId: number): Promise | -------------------------------------------- | ------------------------------------------ | | Promise<[IccAccountInfo](#iccaccountinfo7)\> | 以Promise形式返回指定卡槽SIM卡的账户信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -586,6 +766,18 @@ getActiveSimAccountInfoList(callback: AsyncCallback>): vo | -------- | ----------------------------------------------------------- | ---- | ---------- | | callback | AsyncCallback\\> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -613,6 +805,18 @@ getActiveSimAccountInfoList(): Promise>; | ---------------------------------------------------- | ---------------------------------------------- | | Promise\> | 以Promise形式返回活跃卡槽SIM卡的账户信息列表。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -643,6 +847,19 @@ setDefaultVoiceSlotId(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | SIM卡槽ID：
- 0：卡槽1
- 1：卡槽2
- -1：清除默认配置 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301001 | SIM card is not activated. | + **示例：** ```js @@ -676,6 +893,19 @@ setDefaultVoiceSlotId(slotId: number): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301001 | SIM card is not activated. | + **示例：** ```js @@ -707,6 +937,18 @@ setShowName\(slotId: number, name: string, callback: AsyncCallback\): voi | name | string | 是 | SIM卡名称。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -741,6 +983,18 @@ setShowName\(slotId: number, name: string\): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -772,6 +1026,18 @@ getShowName(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<string> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -805,6 +1071,18 @@ getShowName(slotId: number): Promise | --------------------- | -------------------------------------- | | Promise<string> | 以Promise形式返回指定卡槽SIM卡的名称。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -836,6 +1114,18 @@ setShowNumber\(slotId: number, number: string, callback: AsyncCallback\): | number | string | 是 | SIM卡号码。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -871,6 +1161,18 @@ setShowNumber\(slotId: number, number: string\): Promise\ | -------------- | ------------------------------- | | Promise | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -902,6 +1204,18 @@ getShowNumber(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<string> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -935,6 +1249,18 @@ getShowNumber(slotId: number): Promise | --------------------- | --------------------------------- | | Promise<string> | 以Promise形式返回指定卡槽的号码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -965,6 +1291,18 @@ activateSim(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -998,6 +1336,18 @@ activateSim(slotId: number): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1028,6 +1378,18 @@ deactivateSim(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1061,6 +1423,18 @@ deactivateSim(slotId: number): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1092,6 +1466,19 @@ setLockState(slotId: number, options: LockInfo, callback: AsyncCallback | 是 | 回调函数。 | | options | [LockInfo](#lockinfo8) | 是 | 锁信息。
- lockType: [LockType](#locktype8)
- password: string
- state: [LockState](#lockstate8) | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1131,6 +1518,19 @@ setLockState(slotId: number, options: LockInfo): Promise | ---------------------------------------------------- | -------------------------------------------- | | Promise<[LockStatusResponse](#lockstatusresponse7)\> | 以Promise形式返回获取指定卡槽SIM卡的锁状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1167,6 +1567,19 @@ getLockState(slotId: number, lockType: LockType, callback: AsyncCallback | 是 | 回调函数。 | | options | [LockType](#locktype8) | 是 | 锁类型。
- 1: PIN锁
- 2: PIN2锁 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1201,6 +1614,19 @@ getLockState(slotId: number, lockType: LockType): Promise | ---------------------------------- | -------------------------------------------- | | Promise<[LockState](#lockstate8)\> | 以Promise形式返回获取指定卡槽SIM卡的锁状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1233,6 +1659,19 @@ alterPin(slotId: number, newPin: string, oldPin: string, callback: AsyncCallback | newPin | string | 是 | 新密码。 | | oldPin | string | 是 | 旧密码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1268,6 +1707,19 @@ alterPin(slotId: number, newPin: string, oldPin: string): Promise | 以Promise形式返回指定卡槽SIM卡的Pin是否成功。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1300,6 +1752,19 @@ alterPin2(slotId: number, newPin2: string, oldPin2: string, callback: AsyncCallb | newPin2 | string | 是 | 新密码。 | | oldPin2 | string | 是 | 旧密码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1335,6 +1800,19 @@ alterPin2(slotId: number, newPin2: string, oldPin2: string): Promise | 以Promise形式返回指定卡槽SIM卡的Pin是否成功。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1366,6 +1844,19 @@ unlockPin(slotId: number, pin: string, callback: AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1401,6 +1892,19 @@ unlockPin(slotId: number, pin: string): Promise<LockStatusResponse\> | ---------------------------------------------------- | -------------------------------------------------- | | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | 以Promise形式返回获取指定卡槽的SIM卡锁状态的响应。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1434,6 +1938,19 @@ unlockPuk(slotId: number, newPin: string, puk: string, callback: AsyncCallback | 以Promise形式返回获取指定卡槽的SIM卡锁状态的响应。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1504,6 +2034,19 @@ unlockPin2(slotId: number, pin2: string, callback: AsyncCallback | ----------------------------------------------------- | -------------------------------------------------- | | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | 以Promise形式返回获取指定卡槽的SIM卡锁状态的响应。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1572,6 +2128,19 @@ unlockPuk2(slotId: number, newPin2: string, puk2: string, callback: AsyncCallbac | puk2 | string | 是 | SIM卡密码的解锁密码。 | | callback | AsyncCallback<[LockStatusResponse](#lockstatusresponse7)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1609,6 +2178,19 @@ unlockPuk2(slotId: number, newPin2: string, puk2: string): Promise<LockStatus | ---------------------------------------------------- | -------------------------------------------------- | | Promise\<[LockStatusResponse](#lockstatusresponse7)\> | 以Promise形式返回获取指定卡槽的SIM卡锁状态的响应。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1661,6 +2243,18 @@ getSimIccId(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1694,6 +2288,18 @@ getSimIccId(slotId: number): Promise | ---------------- | ------------------------------------------- | | Promise | 以Promise形式返回获取指定卡槽SIM卡的ICCID。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1724,6 +2330,18 @@ getVoiceMailIdentifier(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1757,6 +2375,18 @@ getVoiceMailIdentifier(slotId: number): Promise | ---------------- | ------------------------------------------------- | | Promise | 以Promise形式返回获取指定卡槽SIM卡的alpha标识符。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1787,6 +2417,18 @@ getVoiceMailNumber(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1820,6 +2462,18 @@ getVoiceMailNumber(slotId: number): Promise | ---------------- | ------------------------------------------------ | | Promise | 以Promise形式返回获取指定卡槽SIM卡的语音信箱号。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1831,6 +2485,7 @@ promise.then(data => { }); ``` + ## sim.setVoiceMailInfo8+ setVoiceMailInfo(slotId: number, mailName: string, mailNumber: string, callback: AsyncCallback): void @@ -1852,6 +2507,19 @@ setVoiceMailInfo(slotId: number, mailName: string, mailNumber: string, callback: | mailNumber | string | 是 | 邮件号码 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1887,6 +2555,19 @@ setVoiceMailInfo(slotId: number, mailName: string, mailNumber: string): Promise< | -------------- | ----------------------- | | Promise | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -1917,6 +2598,18 @@ getSimTelephoneNumber(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1950,6 +2643,18 @@ getSimTelephoneNumber(slotId: number): Promise | ---------------- | -------------------------------------------- | | Promise | 以Promise形式返回获取指定卡槽SIM卡的MSISDN。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1980,6 +2685,18 @@ getSimGid1(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2013,6 +2730,18 @@ getSimGid1(slotId: number): Promise | ---------------- | ------------------------------------------------- | | Promise | 以Promise形式返回获取指定卡槽SIM卡的标识符级别1。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2043,6 +2772,18 @@ getIMSI(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2076,6 +2817,18 @@ getIMSI(slotId: number): Promise | ---------------- | ------------------------------------------- | | Promise | 以Promise形式返回获取的国际移动用户识别码。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2106,6 +2859,18 @@ getOperatorConfigs(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2139,6 +2904,18 @@ getOperatorConfigs(slotId: number): Promise> | --------------------------------------------------- | ----------------------------- | | Promise> | 以Promise形式返回运营商配置。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2170,6 +2947,19 @@ queryIccDiallingNumbers(slotId: number, type: ContactType, callback: AsyncCallba | type | [ContactType](#contacttype8) | 是 | 联系人类型。
- 1 : GENERAL_CONTACT
- 2 : FIXED_DIALING | | callback | AsyncCallback> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2202,7 +2992,20 @@ queryIccDiallingNumbers(slotId: number, type: ContactType): Promise> | 以Promise形式返回Icc拨号号码。 | +| Promise> | 以Promise形式返回Icc拨号号码。| + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | **示例：** @@ -2236,6 +3039,19 @@ addIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dialli | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | 是 | 拨号号码信息。 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2276,6 +3092,19 @@ addIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dialli | -------------- | --------------------------- | | Promise | 以Promise形式返回添加结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2312,6 +3141,19 @@ delIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dialli | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | 是 | 拨号号码信息。 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2353,6 +3195,19 @@ delIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dialli | -------------- | --------------------------- | | Promise | 以Promise形式返回删除结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2389,6 +3244,19 @@ updateIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dia | diallingNumbers | [DiallingNumbersInfo](#diallingnumbersinfo8) | 是 | 拨号号码信息。 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2430,6 +3298,19 @@ updateIccDiallingNumbers(slotId: number, type: ContactType, diallingNumbers: Dia | -------------- | ----------------------------- | | Promise | 以Promise形式返回更新的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2466,6 +3347,18 @@ sendEnvelopeCmd(slotId: number, cmd: string, callback: AsyncCallback): vo | cmd | string | 是 | 命令。 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2500,6 +3393,18 @@ sendEnvelopeCmd(slotId: number, cmd: string): Promise | -------------- | --------------------------- | | Promise | 以Promise形式返回发送结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2531,6 +3436,18 @@ sendTerminalResponseCmd(slotId: number, cmd: string, callback: AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2565,6 +3482,18 @@ sendTerminalResponseCmd(slotId: number, cmd: string): Promise | -------------- | --------------------------- | | Promise | 以Promise形式返回发送结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -2576,6 +3505,7 @@ promise.then(data => { }); ``` + ## sim.unlockSimLock8+ unlockSimLock(slotId: number, lockInfo: PersoLockInfo, callback: AsyncCallback): void @@ -2596,6 +3526,19 @@ unlockSimLock(slotId: number, lockInfo: PersoLockInfo, callback: AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2634,6 +3577,19 @@ unlockSimLock(slotId: number, lockInfo: PersoLockInfo): Promise | 以Promise形式返回锁状态。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301002 | SIM card operation error. | + **示例：** ```js @@ -2664,12 +3620,32 @@ getOpKey(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 801 | Capability not supported. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js -sim.getOpKey(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); -}); +try { + sim.getOpKey(0, (err, data) => { + if (err) { + console.log("getOpKey failed, err: " + JSON.stringify(err)); + } else { + console.log('getOpKey successfully, data: ' + JSON.stringify(data)); + } + }); +} catch (err) { + console.log("getOpKey err: " + JSON.stringify(err)); +} ``` @@ -2693,15 +3669,27 @@ getOpKey(slotId: number): Promise | ---------------- | ----------------------------------------- | | Promise | 以Promise形式返回指定卡槽中SIM卡的opkey。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 801 | Capability not supported. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js -let promise = sim.getOpKey(0); -promise.then(data => { +try { + let data = sim.getOpKey(0); console.log(`getOpKey success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { - console.log(`getOpKey failed, promise: err->${JSON.stringify(err)}`); -}); +} catch (error) { + console.log(`getOpKey failed, promise: err->${JSON.stringify(error)}`); +} ``` ## sim.getOpName9+ @@ -2719,12 +3707,32 @@ getOpName(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 801 | Capability not supported. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js -sim.getOpName(0, (err, data) => { - console.log(`callback: err->${JSON.stringify(err)}, data->${JSON.stringify(data)}`); -}); +try { + sim.getOpName(0, (err, data) => { + if (err) { + console.log("getOpName failed, err: " + JSON.stringify(err)); + } else { + console.log('getOpName successfully, data: ' + JSON.stringify(data)); + } + }); +} catch (err) { + console.log("getOpName err: " + JSON.stringify(err)); +} ``` @@ -2748,15 +3756,27 @@ getOpName(slotId: number): Promise | ---------------- | ------------------------------------------ | | Promise | 以Promise形式返回指定卡槽中SIM卡的OpName。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 801 | Capability not supported. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js -let promise = sim.getOpName(0); -promise.then(data => { +try { + let data = sim.getOpName(0); console.log(`getOpName success, promise: data->${JSON.stringify(data)}`); -}).catch(err => { - console.log(`getOpName failed, promise: err->${JSON.stringify(err)}`); -}); +} catch (error) { + console.log(`getOpName failed, promise: err->${JSON.stringify(error)}`); +} ``` ## SimState @@ -2947,8 +3967,8 @@ Icc账户信息。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Telephony.CoreService。 -| 名称 | 值 | 说明 | -| ------------------------------------------------------- | ---------------------------------------------------- | -------------------- | +| 名称 | 值 | 说明 | +| ------------------------------------------------------- | ------------------------------------------------------ | -------------------- | | KEY_VOICE_MAIL_NUMBER_STRING | "voice_mail_number_string" | 语音邮件号码。 | | KEY_IMS_SWITCH_ON_BY_DEFAULT_BOOL | "ims_switch_on_by_default_bool" | 固定拨号。 | | KEY_HIDE_IMS_SWITCH_BOOL | "hide_ims_switch_bool" | 是否隐藏ims开关。 | @@ -2961,7 +3981,7 @@ Icc账户信息。 | KEY_IMS_PREFER_FOR_EMERGENCY_BOOL | "ims_prefer_for_emergency_bool" | IMS紧急首选项。 | | KEY_CALL_WAITING_SERVICE_CLASS_INT | "call_waiting_service_class_int" | 呼叫等待服务。 | | KEY_CALL_TRANSFER_VISIBILITY_BOOL | "call_transfer_visibility_bool" | 呼叫转移可见性。 | -| KEY_IMS_CALL_DISCONNECT_REASONINFO_MAPPING_STRING_ARRAY | "ims_call_disconnect_reasoninfo_mapping_string_array" | IMS呼叫结束原因列表。| +| KEY_IMS_CALL_DISCONNECT_REASON_INFO_MAPPING_STRING_ARRAY| "ims_call_disconnect_reason_info_mapping_string_array" | IMS呼叫结束原因列表。| | KEY_FORCE_VOLTE_SWITCH_ON_BOOL | "force_volte_switch_on_bool" | 强制VOLTE开关。 | | KEY_ENABLE_OPERATOR_NAME_CUST_BOOL | "enable_operator_name_cust_bool" | 是否显示运营商名称。 | | KEY_OPERATOR_NAME_CUST_STRING | "operator_name_cust_string" | 运营商名称。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-sms.md b/zh-cn/application-dev/reference/apis/js-apis-sms.md index 47fe20e28b4f71f1a1ac75577538a7c8288867fe..9d92f570c3639794f016f4b6426dc940b2b34ce8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-sms.md +++ b/zh-cn/application-dev/reference/apis/js-apis-sms.md @@ -177,6 +177,18 @@ setDefaultSmsSlotId\(slotId: number, callback: AsyncCallback<void>\): void | slotId | number | 是 | SIM卡槽ID。
- 0：卡槽1
- 1：卡槽2
- -1：清除默认配置 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -210,6 +222,18 @@ setDefaultSmsSlotId\(slotId: number\): Promise<void> | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -241,6 +265,17 @@ setSmscAddr\(slotId: number, smscAddr: string, callback: AsyncCallback\): | smscAddr | string | 是 | 短信服务中心地址。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -277,6 +312,17 @@ setSmscAddr\(slotId: number, smscAddr: string\): Promise\ | ------------------- | ------------------------------- | | Promise<void> | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -310,6 +356,17 @@ getSmscAddr\(slotId: number, callback: AsyncCallback\): void | slotId | number | 是 | SIM卡槽ID：
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<string> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -344,6 +401,17 @@ getSmscAddr\(slotId: number\): Promise | --------------------- | --------------------------------------------- | | Promise<string> | 以Promise形式返回获取短信服务中心地址的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -394,6 +462,17 @@ splitMessage(content: string, callback: AsyncCallback>): void | content | string | 是 | 指示短消息内容，不能为null。 | | callback | AsyncCallback> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -428,6 +507,17 @@ splitMessage(content: string): Promise> | ----------------------- | ----------------------------------- | | Promise> | 以Promise形式返回多个片段的的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -459,6 +549,17 @@ addSimMessage(options: SimMessageOptions, callback: AsyncCallback): void | options | [SimMessageOptions](#simmessageoptions7) | 是 | SIM卡消息选项。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -498,6 +599,17 @@ addSimMessage(options: SimMessageOptions): Promise | ------------------- | ----------------------------- | | Promise<void> | 以Promise形式返回添加的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -535,6 +647,17 @@ delSimMessage(slotId: number, msgIndex: number, callback: AsyncCallback): | msgIndex | number | 是 | 消息索引。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -571,6 +694,17 @@ delSimMessage(slotId: number, msgIndex: number): Promise | ------------------- | ----------------------------- | | Promise<void> | 以Promise形式返回删除的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -603,6 +737,17 @@ updateSimMessage(options: UpdateSimMessageOptions, callback: AsyncCallback | ------------------- | ----------------------------- | | Promise<void> | 以Promise形式返回更新的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -680,6 +836,17 @@ getAllSimMessages(slotId: number, callback: AsyncCallback- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -714,6 +881,17 @@ getAllSimMessages(slotId: number): Promise> | ------------------------------------------------------- | ---------------------------------- | | PromiseArray<[SimShortMessage](#simshortmessage7)\>> | 以Promise形式返回获取的SIM短消息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -745,6 +923,17 @@ setCBConfig(options: CBConfigOptions, callback: AsyncCallback): void | options | [CBConfigOptions](#cbconfigoptions7) | 是 | 小区广播配置选项。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -785,6 +974,17 @@ setCBConfig(options: CBConfigOptions): Promise | ------------------- | ----------------------------- | | Promise<void> | 以Promise形式返回设置的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -822,6 +1022,16 @@ getSmsSegmentsInfo(slotId: number, message: string, force7bit: boolean, callback | force7bit | boolean | 是 | 是否使用7 bit编码。 | | callback | AsyncCallback<[SmsSegmentsInfo](#smssegmentsinfo8)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -856,6 +1066,16 @@ getSmsSegmentsInfo(slotId: number, message: string, force7bit: boolean): Promise | ------------------------------------------------------- | ----------------------------- | | Promise<[SmsSegmentsInfo](#smssegmentsinfo8)> | 以Promise形式返回短信段信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -885,6 +1105,16 @@ isImsSmsSupported(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | SIM卡槽ID：
- 0：卡槽1
- 1：卡槽2 | | callback | AsyncCallback<boolean> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -917,6 +1147,16 @@ isImsSmsSupported(slotId: number): Promise | ---------------------- | ----------------------- | | Promise<boolean> | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -945,6 +1185,17 @@ getImsShortMessageFormat(callback: AsyncCallback): void | -------- | --------------------------- | ---- | ---------- | | callback | AsyncCallback<string> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -970,6 +1221,17 @@ getImsShortMessageFormat(): Promise | --------------------- | -------------------------- | | Promise<string> | 以Promise形式返回SMS格式。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -998,6 +1260,16 @@ decodeMms(mmsFilePathName: string | Array, callback: AsyncCallback | 是 | 彩信文件路径名。 | | callback | AsyncCallback<[MmsInformation](#mmsinformation8)> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1030,6 +1302,16 @@ decodeMms(mmsFilePathName: string | Array): Promise | --------------------------------------------------------- | --------------------------- | | Promise<<[MmsInformation](#mmsinformation8)>> | 以Promise形式返回彩信信息。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1059,6 +1341,16 @@ encodeMms(mms: MmsInformation, callback: AsyncCallback>): void | mms | [MmsInformation](#mmsinformation8) | 是 | 彩信信息。 | | callback | AsyncCallback<Array> | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -1099,6 +1391,16 @@ encodeMms(mms: MmsInformation): Promise> | ----------------------------- | ----------------------------------- | | Promise<Array> | 以Promise形式返回彩信编码后的结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js diff --git a/zh-cn/application-dev/reference/apis/js-apis-telephony-data.md b/zh-cn/application-dev/reference/apis/js-apis-telephony-data.md index 9438e4a886f6fc1a02b2bbf179f0afd672e3de1a..3b47746d554cb7d47e7d0ac83c9089ca2990dda9 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-telephony-data.md +++ b/zh-cn/application-dev/reference/apis/js-apis-telephony-data.md @@ -98,6 +98,19 @@ setDefaultCellularDataSlotId(slotId: number, callback: AsyncCallback\): v | slotId | number | 是 | SIM卡槽ID。
- 0：卡槽1。
- 1：卡槽2。
- -1：清除默认配置。 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301001 | SIM card is not activated. | + **示例：** ```js @@ -130,6 +143,19 @@ setDefaultCellularDataSlotId(slotId: number): Promise\ | --------------- | ------------------------------- | | Promise\ | 以Promise形式异步返回设置结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300004 | Do not have sim card. | +| 8300999 | Unknown error code. | +| 8301001 | SIM card is not activated. | + **示例：** ```js @@ -251,6 +277,17 @@ isCellularDataEnabled(callback: AsyncCallback\): void | -------- | ------------------------ | ---- | ------------------------------------------------------------ | | callback | AsyncCallback\ | 是 | 回调函数。
true：蜂窝数据业务已启用。
false：蜂窝数据业务已禁用。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -275,6 +312,17 @@ isCellularDataEnabled(): Promise\ | ------------------ | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回检查蜂窝数据业务是否启用。
true：蜂窝数据业务已启用。
false：蜂窝数据业务已禁用。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -303,6 +351,17 @@ isCellularDataRoamingEnabled(slotId: number, callback: AsyncCallback\) | slotId | number | 是 | 卡槽ID。
0：卡槽1。
1：卡槽2。 | | callback | AsyncCallback\ | 是 | 回调函数。
true：蜂窝数据业务已启用漫游。
false：蜂窝数据业务已禁用漫游。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -333,6 +392,17 @@ isCellularDataRoamingEnabled(slotId: number): Promise\ | ------------------ | ------------------------------------------------------------ | | Promise\ | 以Promise形式返回检查蜂窝数据业务是否启用漫游。
true：蜂窝数据业务已启用漫游。
false：蜂窝数据业务已禁用漫游。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -362,6 +432,17 @@ enableCellularData(callback: AsyncCallback): void | -------- | --------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -388,6 +469,17 @@ enableCellularData(): Promise | --------------- | ----------------------- | | Promise\ | 以Promise形式返回结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -417,6 +509,17 @@ disableCellularData(callback: AsyncCallback): void | -------- | --------------------- | ---- | ---------- | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -443,6 +546,17 @@ disableCellularData(): Promise | --------------- | --------------------------- | | Promise\ | 以Promise形式返回禁用结果。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -473,6 +587,17 @@ enableCellularDataRoaming(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
0：卡槽1。
1：卡槽2。 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -505,6 +630,17 @@ enableCellularDataRoaming(slotId: number): Promise | --------------- | ------------------------- | | Promise\ | 以Promise形式返回启用结果 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -535,6 +671,17 @@ disableCellularDataRoaming(slotId: number, callback: AsyncCallback): void | slotId | number | 是 | 卡槽ID。
0：卡槽1。
1：卡槽2。 | | callback | AsyncCallback\ | 是 | 回调函数。 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js @@ -567,6 +714,17 @@ disableCellularDataRoaming(slotId: number): Promise | --------------- | ------------------------- | | Promise\ | 以Promise形式返回禁用结果 | +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | -------------------------------------------- | +| 201 | Permission denied. | +| 401 | Parameter error. | +| 8300001 | Invalid parameter value. | +| 8300002 | Operation failed. Cannot connect to service. | +| 8300003 | System internal error. | +| 8300999 | Unknown error code. | + **示例：** ```js diff --git a/zh-cn/application-dev/reference/apis/js-apis-uri.md b/zh-cn/application-dev/reference/apis/js-apis-uri.md index 6cc9eef1eec4ebd8bc4a69a2cf7a1814150d1100..e26fa93fa16ac7e99705c433b2fc1c3088b69e23 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-uri.md +++ b/zh-cn/application-dev/reference/apis/js-apis-uri.md @@ -226,9 +226,9 @@ checkIsAbsolute(): boolean ```js const uriInstance = new uri.URI('https://username:password@www.qwer.com:8080?query=pppppp'); -console.log(uriInstance.checkIsAbsolute()); // true +console.log(`${uriInstance.checkIsAbsolute()}`); // true const uriInstance1 = new uri.URI('xxx.com/suppliers.htm'); -console.log(uriInstance1.checkIsAbsolute()); // false +console.log(`${uriInstance1.checkIsAbsolute()}`); // false ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-window.md b/zh-cn/application-dev/reference/apis/js-apis-window.md index e80202ae57e2d9f1059041bc6888c02ca9a9245a..13d2b49d54e55971c00592b354cee425c9f55c29 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-window.md +++ b/zh-cn/application-dev/reference/apis/js-apis-window.md @@ -4572,7 +4572,7 @@ try { console.error('Failed to set the aspect ratio of window. Cause:' + JSON.stringify(err)); return; } - console.error('Failed to set the aspect ratio of window. Cause:' + JSON.stringify(err)); + console.info('Succeeded in setting the aspect ratio of window.'); }); } catch (exception) { console.error('Failed to set the aspect ratio of window. Cause: ' + JSON.stringify(exception)); diff --git a/zh-cn/application-dev/reference/arkui-ts/figures/TabBarStyle.jpeg b/zh-cn/application-dev/reference/arkui-ts/figures/TabBarStyle.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..870c385e4600b1ddc9f92fd929be59022c3ef781 Binary files /dev/null and b/zh-cn/application-dev/reference/arkui-ts/figures/TabBarStyle.jpeg differ diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepper.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepper.md index fd1a49a370bc272652fe1b5152f1730e7c5addb4..d760fd4e4108b59cbc51164f0ee5ba4ffc9d3425 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepper.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepper.md @@ -34,10 +34,10 @@ Stepper(value?: { index?: number }) | 名称 | 描述 | | -------- | -------- | -| onFinish(callback: () => void) | 步骤导航器最后一个StepperItem的nextLabel被点击时触发该回调 。 | +| onFinish(callback: () => void) | 步骤导航器最后一个StepperItem的nextLabel被点击时，并且ItemState属性为Normal时，触发该回调 。 | | onSkip(callback: () => void) | 当前显示的StepperItem状态为ItemState.Skip时，nextLabel被点击时触发该回调。 | -| onChange(callback: (prevIndex?: number, index?: number) => void) | 点击当前StepperItem的prevLabel或nextLabel进行步骤切换时触发该回调。
- prevIndex：切换前的步骤页索引值。
- index：切换后的步骤页（前一页或者下一页）索引值。 | -| onNext(callback: (index?: number, pendingIndex?: number) => void) | 点击StepperItem的nextLabel切换下一步骤时触发该回调。
- index：当前步骤页索引值。
- pendingIndex：下一步骤页索引值。 | +| onChange(callback: (prevIndex?: number, index?: number) => void) | 点击当前StepperItem的prevLabel进行步骤切换时触发该回调；或点击当前StepperItem的nextLabel，当前页面不为步骤导航器最后一个StepperItem且ItemState属性为Normal时，触发该回调。
- prevIndex：切换前的步骤页索引值。
- index：切换后的步骤页（前一页或者下一页）索引值。 | +| onNext(callback: (index?: number, pendingIndex?: number) => void) | 点击StepperItem的nextLabel切换下一步骤时，当前页面不为步骤导航器最后一个StepperItem且ItemState属性为Normal时，触发该回调。
- index：当前步骤页索引值。
- pendingIndex：下一步骤页索引值。 | | onPrevious(callback: (index?: number, pendingIndex?: number) => void) | 点击StepperItem的prevLabel切换上一步骤时触发该回调。
- index：当前步骤页索引值。
- pendingIndex：上一步骤页索引值。 | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md index 9141c2052e93f441f40ae1aefa21837d9eb19ff6..16eca00028f791c505086f8f54d8d305cc3e8f74 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-stepperitem.md @@ -33,7 +33,7 @@ StepperItem() | Normal | 0 |正常状态，右侧文本按钮正常显示，可点击进入下一个StepperItem。 | | Disabled | 1 |不可用状态，右侧文本按钮灰度显示，不可点击进入下一个StepperItem。 | | Waiting | 2 | 等待状态，右侧文本按钮不显示，显示等待进度条，不可点击进入下一个StepperItem。 | -| Skip | 3 |跳过状态，右侧文本按钮显示“跳过”，此时可在Stepper的onSkip回调中自定义相关逻辑。 | +| Skip | 3 |跳过状态，右侧文本按钮默认显示“跳过”，此时可在Stepper的onSkip回调中自定义相关逻辑。 | ## 示例 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-text.md b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-text.md index 79498c8d67311ba7ff356a9c90e8358c80dd6c1d..5431ce7579ab88a9d4972bd4fde5c47b5ae5179d 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-text.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-text.md @@ -28,15 +28,15 @@ Text(content?: string | Resource) | 名称 | 参数类型 | 描述 | | ----------------------- | ----------------------------------- | ------------------------------------------- | -| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | 设置文本在水平方向的对齐方式。
默认值：TextAlign.Start | +| textAlign | [TextAlign](ts-appendix-enums.md#textalign) | 设置文本段落在水平方向的对齐方式
默认值：TextAlign.Start
说明：
文本段落宽度占满Text组件宽度；可通过[align](ts-universal-attributes-location.md)属性控制文本段落在垂直方向上的位置。 | | textOverflow | {overflow: [TextOverflow](ts-appendix-enums.md#textoverflow)} | 设置文本超长时的显示方式。
默认值：{overflow: TextOverflow.Clip}
**说明：**
文本截断是按字截断。例如，英文以单词为最小单位进行截断，若需要以字母为单位进行截断，可在字母间添加零宽空格：\u200B。
需配合`maxLines`使用，单独设置不生效。 | | maxLines | number | 设置文本的最大行数。
默认值：Infinity
**说明：**
默认情况下，文本是自动折行的，如果指定此参数，则文本最多不会超过指定的行。如果有多余的文本，可以通过 `textOverflow`来指定截断方式。 | | lineHeight | string \| number \| [Resource](ts-types.md#resource) | 设置文本的文本行高，设置值不大于0时，不限制文本行高，自适应字体大小，Length为number类型时单位为fp。 | | decoration | {
type: [TextDecorationType](ts-appendix-enums.md#textdecorationtype),
color?: [ResourceColor](ts-types.md#resourcecolor)
} | 设置文本装饰线样式及其颜色。
默认值：{
type: TextDecorationType.None,
color：Color.Black
} | | baselineOffset | number \| string | 设置文本基线的偏移量，默认值0。 | | letterSpacing | number \| string | 设置文本字符间距。 | -| minFontSize | number \| string \| [Resource](ts-types.md#resource) | 设置文本最小显示字号。 | -| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | 设置文本最大显示字号。 | +| minFontSize | number \| string \| [Resource](ts-types.md#resource) | 设置文本最小显示字号。
需配合maxFontSize以及maxline或布局大小限制使用，单独设置不生效。 | +| maxFontSize | number \| string \| [Resource](ts-types.md#resource) | 设置文本最大显示字号。
需配合minFontSize以及maxline或布局大小限制使用，单独设置不生效。 | | textCase | [TextCase](ts-appendix-enums.md#textcase) | 设置文本大小写。
默认值：TextCase.Normal | | copyOption9+ | [CopyOptions](ts-appendix-enums.md#copyoptions9) | 组件支持设置文本是否可复制粘贴。
默认值：CopyOptions.None | diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-griditem.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-griditem.md index b0b5e850a53ded55096e78a46609d02caa284381..f4f82074eaf4218b0b25402aa70cfdb119eb004f 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-griditem.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-griditem.md @@ -25,7 +25,7 @@ GridItem() | rowEnd | number | 指定当前元素终点行号。 | | columnStart | number | 指定当前元素起始列号。 | | columnEnd | number | 指定当前元素终点列号。 | -| forceRebuild | boolean | 设置在触发组件build时是否重新创建此节点。
默认值：false | +| forceRebuild(deprecated) | boolean | 设置在触发组件build时是否重新创建此节点。
从API version9开始废弃。GridItem会根据自身属性和子组件变化自行决定是否需要重新创建，无需设置。
默认值：false | | selectable8+ | boolean | 当前GridItem元素是否可以被鼠标框选。
>  **说明：**
> 外层Grid容器的鼠标框选开启时，GridItem的框选才生效。
默认值：true | @@ -67,7 +67,7 @@ struct GridItemExample { .width('100%') .height('100%') .textAlign(TextAlign.Center) - }.forceRebuild(false) + } }, item => item) GridItem() { diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md index 1c61f55bd76dd289c0ee6cef06bde7ac990fd8e3..8a2612b58f05f0642f203113e8f6ab60746b4256 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabcontent.md @@ -24,12 +24,45 @@ TabContent() | 名称 | 参数类型 | 描述 | | -------- | -------- | -------- | | tabBar | string \| Resource \| {
icon?: string \| Resource,
text?: string \| Resource
}
\| [CustomBuilder](ts-types.md)8+ | 设置TabBar上显示内容。
CustomBuilder: 构造器，内部可以传入组件（API8版本以上适用）。
>  **说明：**
> 如果icon采用svg格式图源，则要求svg图源删除其自有宽高属性值。如采用带有自有宽高属性的svg图源，icon大小则是svg本身内置的宽高属性值大小。 | +| tabBar9+ | [SubTabBarStyle](#subtabbarstyle) \| [BottomTabBarStyle](#bottomtabbarstyle) | 设置TabBar上显示内容。
SubTabBarStyle: 子页签样式，参数为文字。
BottomTabBarStyle: 底部页签和侧边页签样式，参数为文字和图片。 | > **说明：** > - TabContent组件不支持设置通用宽度属性，其宽度默认撑满Tabs父组件。 > - TabContent组件不支持设置通用高度属性，其高度由Tabs父组件高度与TabBar组件高度决定。 > - TabContent组件不支持[触摸热区设置](ts-universal-attributes-touch-target.md)。 +## SubTabBarStyle9+ + +子页签样式。 + +### constructor9+ + +constructor(content: string | Resource) + +SubTabBarStyle的构造函数。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | +| content | string \| [Resource](ts-types.md#resource) | 是 | 页签内的文字内容。 | + +## BottomTabBarStyle9+ + +底部页签和侧边页签样式。 + +### constructor9+ + +constructor(icon: string | Resource, text: string | Resource) + +BottomTabBarStyle的构造函数。 + +**参数：** + +| 参数名 | 参数类型 | 必填 | 参数描述 | +| -------- | -------- | -------- | -------- | +| icon | string \| [Resource](ts-types.md#resource) | 是 | 页签内的图片内容。 | +| text | string \| [Resource](ts-types.md#resource) | 是 | 页签内的文字内容。 | ## 示例 @@ -193,4 +226,102 @@ struct TabContentExample { } ``` -![tabContent](figures/tabContent2.gif) \ No newline at end of file +![tabContent](figures/tabContent2.gif) + +示例3： + +```ts +// xxx.ets +@Entry +@Component +struct TabBarStyleExample { + build() { + Column({ space: 5 }) { + Text("子页签样式") + Column() { + Tabs({ barPosition: BarPosition.Start }) { + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Pink) + }.tabBar(new SubTabBarStyle('Pink')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Yellow) + }.tabBar(new SubTabBarStyle('Yellow')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Blue) + }.tabBar(new SubTabBarStyle('Blue')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Green) + }.tabBar(new SubTabBarStyle('Green')) + } + .vertical(false) + .scrollable(true) + .barMode(BarMode.Fixed) + .onChange((index: number) => { + console.info(index.toString()) + }) + .width('100%') + .backgroundColor(0xF1F3F5) + }.width('100%').height(200) + Text("底部页签样式") + Column() { + Tabs({ barPosition: BarPosition.End }) { + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Pink) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'pink')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Yellow) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Yellow')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Blue) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Blue')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Green) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Green')) + } + .vertical(false) + .scrollable(true) + .barMode(BarMode.Fixed) + .onChange((index: number) => { + console.info(index.toString()) + }) + .width('100%') + .backgroundColor(0xF1F3F5) + }.width('100%').height(200) + Text("侧边页签样式") + Column() { + Tabs({ barPosition: BarPosition.Start }) { + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Pink) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'pink')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Yellow) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Yellow')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Blue) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Blue')) + + TabContent() { + Column().width('100%').height('100%').backgroundColor(Color.Green) + }.tabBar(new BottomTabBarStyle($r('sys.media.ohos_app_icon'), 'Green')) + } + .vertical(true).scrollable(true).barMode(BarMode.Fixed) + .onChange((index: number) => { + console.info(index.toString()) + }) + .width('100%') + .backgroundColor(0xF1F3F5) + }.width('100%').height(400) + } + } +} +``` + +![tabbarStyle](figures/TabBarStyle.jpeg) diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md index c90880b34b81165fc0ee143c7a510a379bd8462d..47d0b607cd3925d36c86a35043630b0a5e21f174 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-tabs.md @@ -43,7 +43,7 @@ Tabs(value?: {barPosition?: BarPosition, index?: number, controller?: [TabsContr | barMode | BarMode | TabBar布局模式，具体描述见BarMode枚举说明。
默认值：BarMode.Fixed | | barWidth | number \| Length8+ | TabBar的宽度值。 | | barHeight | number \| Length8+ | TabBar的高度值。 | -| animationDuration | number | TabContent滑动动画时长。
默认值：200 | +| animationDuration | number | TabContent滑动动画时长。不设置时，点击切换页签无动画，滑动切换有动画；设置时，点击切换和滑动切换都有动画。
默认值：200 | ## BarMode枚举说明 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md index d1d36aa5c3b4725a38ae9a7b7d58b8adaa63dc54..7147691fa04e476bfbc23c9d900d7dc80d4c2387 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-text-style.md @@ -14,7 +14,7 @@ | 名称 | 参数类型 | 描述 | | -----------| ---------------------------------------- | ------------------------------------ | | fontColor | [ResourceColor](ts-types.md#resourcecolor) | 设置字体颜色。 | -| fontSize | [Length](ts-types.md#length) | 设置字体大小，Length为number类型时，使用fp单位。字体默认大小10。不支持设置百分比字符串。 | +| fontSize | [Length](ts-types.md#length) | 设置字体大小，Length为number类型时，使用fp单位。字体默认大小16。不支持设置百分比字符串。 | | fontStyle | [FontStyle](ts-appendix-enums.md#fontstyle) | 设置字体样式。
默认值：FontStyle.Normal | | fontWeight | number \| [FontWeight](ts-appendix-enums.md#fontweight) \| string | 设置文本的字体粗细，number类型取值[100, 900]，取值间隔为100，默认为400，取值越大，字体越粗。string类型仅支持number类型取值的字符串形式，例如"400"，以及"bold"、"bolder"、"lighter"、"regular"、"medium"，分别对应FontWeight中相应的枚举值。
默认值：FontWeight.Normal | | fontFamily | string \| [Resource](ts-types.md#resource) | 设置字体列表。默认字体'HarmonyOS Sans'，且当前只支持这种字体。| diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-telephony.md b/zh-cn/application-dev/reference/errorcodes/errorcode-telephony.md new file mode 100644 index 0000000000000000000000000000000000000000..a80ec138f93e6fad1ab340ee77506a0250ca3642 --- /dev/null +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-telephony.md @@ -0,0 +1,172 @@ +# 电话子系统错误码 + +## 8300001 输入参数不在处理范围内 + +**错误信息** + +The input parameter value is out of range. + +**错误描述** + +输入参数不在处理范围内，如slotId无效等，将无法进行相应的操作。 + +**可能原因** + +输入参数无效。 + +**处理步骤** + +请输入正确的有效参数。 + + + +## 8300002 服务连接失败 + +**错误信息** + +Operation failed. Cannot connect to service. + +**错误描述** + +操作失败。无法连接到服务。 + +**可能原因** + +服务启动失败，IPC连接失败等。 + +**处理步骤** + +本次操作异常，请稍后重试。 + + + +## 8300003 系统内部错误 + +**错误信息** + +System internal error. + +**错误描述** + +系统内部错误。 + +**可能原因** + +网络异常，数据读写失败等。 + +**处理步骤** + +本次操作异常，请稍后重试。 + + +## 8300004 未识别SIM卡 + +**错误信息** + +Do not have sim card. + +**错误描述** + +没有识别到sim卡。 + +**可能原因** + +未插入SIM卡或未正常插入SIM卡。 + +**处理步骤** + +请插卡或重新拔插SIM卡。 + + +## 8300999 未知错误 + +**错误信息** + +Unknown error code. + +**错误描述** + +未知的错误。 + +**可能原因** + +系统内部出现了意料之外的错误，可能是由于底层的错误码不在处理范围内。 + +**处理步骤** + +操作异常，请稍后再试。 + + +## 8301001 SIM卡未激活 + +**错误信息** + +SIM card is not activated. + +**错误描述** + +SIM卡未激活。 + +**可能原因** + +没有激活SIM卡。 + +**处理步骤** + +请激活SIM卡。 + + +## 8301002 SIM卡读取数据或者更新数据失败 + +**错误信息** + +SIM card operation error. + +**错误描述** + +SIM卡读取数据或者更新数据失败。 + +**可能原因** + +SIM不支持该操作，或者SIM卡已损坏。 + +**处理步骤** + +请联系SIM卡运营商，或者更换SIM卡。 + + +## 8301003 随卡配置错误 + +**错误信息** + +Operator config error. + +**错误描述** + +随卡配置错误。 + +**可能原因** + +未预置对应SIM卡的随卡配置文件。 + +**处理步骤** + +请检查是否插入正确的SIM卡。 + +## 8401001 UT连接失败 + +**错误信息** + +UT is not connected. + +**错误描述** + +UT未连接 + +**可能原因** + +当前运营商不支持从Wifi下发UT请求，但是当前手机Wifi已连上。 + +**处理步骤** + +断开wifi，再重发UT请求。 diff --git a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md index 064758811a255d6c69f41a060319a409be3f7d94..8730841330b4dfbbad2a5adf3731dd7698efae52 100644 --- a/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md +++ b/zh-cn/application-dev/reference/js-service-widget-ui/js-service-widget-syntax-hml.md @@ -94,40 +94,6 @@ HML（OpenHarmony Markup Language）是一套类HTML的标记语言，通过组 } ``` - 也可以使用want格式绑定参数跳转到目标应用，want定义了Ability名称、Bundle名称、携带的参数字段等。 - - | 选择器 | 类型 | 默认值 | 样例描述 | - | ------ | ------ | -------- | ---------------------------------------- | - | action | string | "router" | 事件类型。
- "router"：用于应用跳转。
- "message"：自定义点击事件。 | - | want | [Want](../apis/js-apis-app-ability-want.md) | - | 跳转目标应用的信息，参考want格式表。 | - - -```json - { - "data": { - "mainAbility": "xxx.xxx.xxx" - }, - "actions": { - "routerEventName1": { - "action": "router", - "want": { - "bundleName": "com.example.myapplication", - "abilityName": "EntryAbility" - } - }, - "routerEventName2": { - "action": "router", - "want": { - "action": "xxx.intent.action.DIAL", - "uri": "tel:12345678" - } - } - } - } -``` - -在API Version 8，want参数需要在app.js或app.ets文件的onCreate方法中调用[featureAbility.getWant](../apis/js-apis-ability-featureAbility.md)接口接收相关参数。 - - 消息事件格式 | 选择器 | 样例 | 默认值 | 样例描述 | diff --git a/zh-cn/application-dev/security/accesstoken-guidelines.md b/zh-cn/application-dev/security/accesstoken-guidelines.md index c9a6502960194c4e74c142a123eaee03099f8c9d..6bbe9eb17b78c86ba3c0b257e90a553a7f67d263 100644 --- a/zh-cn/application-dev/security/accesstoken-guidelines.md +++ b/zh-cn/application-dev/security/accesstoken-guidelines.md @@ -206,12 +206,13 @@ 通过调用[requestPermissionsFromUser()](../reference/apis/js-apis-inner-app-context.md#contextrequestpermissionsfromuser7)接口向用户动态申请授权。 ```js -// Ability的onWindowStageCreate()生命周期 -onWindowStageCreate() { - let context = this.context; +import featureAbility from '@ohos.ability.featureAbility'; + +reqPermissions() { + let context = featureAbility.getContext(); let array:Array = ["ohos.permission.PERMISSION2"]; //requestPermissionsFromUser会判断权限的授权状态来决定是否唤起弹窗 - context.requestPermissionsFromUser(array).then(function(data) { + context.requestPermissionsFromUser(array, 1).then(function(data) { console.log("data:" + JSON.stringify(data)); console.log("data permissions:" + JSON.stringify(data.permissions)); console.log("data result:" + JSON.stringify(data.authResults)); diff --git a/zh-cn/application-dev/security/cryptoFramework-guidelines.md b/zh-cn/application-dev/security/cryptoFramework-guidelines.md index 0c697abe1d3eef3718759ba8107e2e2e68a12ebc..934a986b4b775e0c2b55da87764323584516ca2e 100644 --- a/zh-cn/application-dev/security/cryptoFramework-guidelines.md +++ b/zh-cn/application-dev/security/cryptoFramework-guidelines.md @@ -1,1113 +1,1606 @@ -# 加解密算法库框架开发指导 - -> **说明** -> -> 本开发指导基于API version 9，OH SDK版本3.2.7以上，适用于JS语言开发 - -## 使用密钥对象生成与转换操作 - -**场景说明** - -使用密钥生成操作中，典型的场景有： - -1. 随机生成算法库密钥对象。该对象可用于后续的加解密等操作。 -2. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。 -3. 获取算法库密钥对象的二进制数据，用于存储或传输。 -> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -以上场景涉及的常用接口如下表所示： - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|根据algName设置的非对称密钥规格，创建非对称密钥生成器对象| -|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|根据algName设置的对称密钥规格，创建对称密钥生成器对象| -|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\) : void|使用callback方式，随机生成非对称密钥对象KeyPair| -|AsyKeyGenerator|generateKeyPair() : Promise\|使用Promise方式，随机生成非对称密钥对象KeyPair| -|SymKeyGenerator|generateSymKey(callback : AsyncCallback\) : void|使用callback方式，随机生成对称密钥对象SymKey| -|SymKeyGenerator|generateSymKey() : Promise\|使用Promise方式，随机生成对称密钥对象SymKey| -| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void | 使用callback方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | -| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ | 使用Promise方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | -| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\) : void| 使用callback方式，根据指定的二进制数据，生成对称密钥对象SymKey | -| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\| 使用Promise方式，根据指定的二进制数据，生成对称密钥对象SymKey | -| Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） | - -**开发步骤** - -示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3） - -1. 创建非对称密钥生成器； -2. 通过非对称密钥生成器随机生成非对称密钥； -3. 获取密钥对象的二进制数据； - -以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function generateAsyKey() { - // 创建非对称密钥生成器 - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - // 通过非对称密钥生成器，随机生成非对称密钥 - let keyGenPromise = rsaGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - let pubKey = globalKeyPair.pubKey; - let priKey = globalKeyPair.priKey; - // 获取非对称密钥的二进制数据 - pkBlob = pubKey.getEncoded(); - skBlob = priKey.getEncoded(); - AlertDialog.show({ message : "pk bin data" + pkBlob.data} ); - AlertDialog.show({ message : "sk bin data" + skBlob.data} ); - }) -} -``` - -示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3） - -1. 创建对称密钥生成器； -2. 通过对称密钥生成器随机生成对称密钥； -3. 获取算法库密钥对象的二进制数据； - -以使用Promise方式随机生成AES密钥（256位）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -function testGenerateAesKey() { - // 创建对称密钥生成器 - let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256'); - // 通过密钥生成器随机生成对称密钥 - let promiseSymKey = symKeyGenerator.generateSymKey(); - promiseSymKey.then( key => { - // 获取对称密钥的二进制数据，输出长度为256bit的字节流 - let encodedKey = key.getEncoded(); - console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); - }) -} -``` - -示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2） - -1. 获取RSA公钥或私钥二进制数据，公钥需满足ASN.1语法、X.509规范、DER编码格式，私钥需满足ASN.1语法、PKCS#8规范、DER编码格式。 -2. 创建AsyKeyGenerator对象，调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -function convertAsyKey() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024"); - let pkval = new Uint8Array([48,129,159,48,13,6,9,42,134,72,134,247,13,1,1,1,5,0,3,129,141,0,48,129,137,2,129,129,0,174,203,113,83,113,3,143,213,194,79,91,9,51,142,87,45,97,65,136,24,166,35,5,179,42,47,212,79,111,74,134,120,73,67,21,19,235,80,46,152,209,133,232,87,192,140,18,206,27,106,106,169,106,46,135,111,118,32,129,27,89,255,183,116,247,38,12,7,238,77,151,167,6,102,153,126,66,28,253,253,216,64,20,138,117,72,15,216,178,37,208,179,63,204,39,94,244,170,48,190,21,11,73,169,156,104,193,3,17,100,28,60,50,92,235,218,57,73,119,19,101,164,192,161,197,106,105,73,2,3,1,0,1]); - let pkBlob = {data : pkval}; - rsaGenerator.convertKey(pkBlob, null, function(err, keyPair) { - if (keyPair == null) { - AlertDialog.show({message : "Convert keypair fail"}); - } - AlertDialog.show({message : "Convert KeyPair success"}); - }) -} -``` - -**说明** - - 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式； - -示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3） - -1. 获取ECC二进制密钥数据，封装成DataBlob对象。 -2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 - -```javascript -function convertEccAsyKey() { - let pubKeyArray = new Uint8Array([4,196,55,233,100,227,224,38,38,5,128,81,53,112,129,7,59,189,116,105,182,87,190,85,31,248,172,116,213,7,206,85,190,65,169,193,138,173,232,187,74,54,78,251,29,131,192,223,251,227,170,138,80,7,98,193,216,168,235,114,255,188,70,134,104]); - let priKeyArray = new Uint8Array([255,70,89,220,189,19,41,157,175,173,83,60,74,216,195,96,24,181,231,23,112,247,150,126,15,155,24,79,33,97,31,225]); - let pubKeyBlob = { data: pubKeyArray }; - let priKeyBlob = { data: priKeyArray }; - let generator = cryptoFrameWork.createAsyKeyGenerator("ECC256"); - generator.convertKey(pubKeyBlob, priKeyBlob, (error, data) => { - if (error) { - AlertDialog.show({message : "Convert keypair fail"}); - } - AlertDialog.show({message : "Convert KeyPair success"}); - }) -} -``` - -示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3） - -1. 创建对称密钥生成器； -2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象； -3. 获取算法库密钥对象的二进制数据； - -以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例： - -```javascript -import cryptoFramework from '@ohos.security.cryptoFramework'; - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - -function testConvertAesKey() { - // 生成对称密钥生成器 - let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); - // 根据用户指定的数据，生成对称密钥 - let keyMaterialBlob = genKeyMaterialBlob(); - try { - symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { - if (error) { // 业务逻辑执行错误通过callback的第一个参数返回错误信息 - console.error(`convertKey error, ${error.code}, ${error.message}`); - return; - } - console.info(`key algName: ${key.algName}`); - console.info(`key format: ${key.format}`); - let encodedKey = key.getEncoded(); // 获取对称密钥的二进制数据，输出长度为192bit的字节流 - console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); - }) - } catch (error) { // 参数检查的错误以同步的方式立即抛出异常 - console.error(`convertKey failed, ${error.code}, ${error.message}`); - return; - } -} -``` - -## 使用加解密操作 - -**场景说明** - -在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有： -1. 使用对称密钥的加解密操作 -2. 使用非对称密钥的加解密操作 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -以上场景设计的常用接口如下表所示： - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createCipher(transformation : string) : Cipher|根据transformation设置的算法参数创建Cipher对象| -|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Cipher对象| -|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\|使用Promise方式设置密钥并初始化Cipher对象| -|Cipher|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加加解密数据| -|Cipher|update(data : DataBlob) : Promise\|使用Promise方式添加加解密数据| -|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式结束对所有数据的加解密| -|Cipher|doFinal(data : DataBlob) : Promise\|使用Promise方式结束对所有数据的加解密| - -**开发步骤** - -示例1：使用对称密钥的加解密操作 - -1. 创建对称密钥生成器。 -2. 通过密钥生成器生成对称密钥。 -3. 创建加解密生成器。 -4. 通过加解密生成器加密或解密数据。 - -以AES GCM以Promise方式加解密为例： - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -var globalCipher; -var globalGcmParams; -var globalKey; -var globalCipherText; - -function genGcmParamsSpec() { - let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes - let dataIv = new Uint8Array(arr); - let ivBlob = {data : dataIv}; - - arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes - let dataAad = new Uint8Array(arr); - let aadBlob = {data : dataAad}; - - arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes - let dataTag = new Uint8Array(arr); - let tagBlob = {data : dataTag}; - let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; - return gcmParamsSpec; -} - -// 可理解的字符串转成字节流 -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -// 字节流转成可理解的字符串 -function uint8ArrayToString(array) { - let arrayString = ''; - for (let i = 0; i < array.length; i++) { - arrayString += String.fromCharCode(array[i]); - } - return arrayString; -} - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - - -// AES GCM模式示例，自动生成密钥（promise写法） -function testAesGcm() { - return new Promise((resolve, reject) => { - setTimeout(() => { - resolve('testAesGcm'); - }, 10) - }).then(() => { - // 生成对称密钥生成器 - let symAlgName = 'AES128'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); - if (symKeyGenerator == null) { - console.error('createSymKeyGenerator failed'); - return; - } - console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); - // 通过密钥生成器随机生成128位长度的对称密钥 - let promiseSymKey = symKeyGenerator.generateSymKey(); - // 构造参数 - globalGcmParams = genGcmParamsSpec(); - - // 生成加解密生成器 - let cipherAlgName = 'AES128|GCM|PKCS7'; - try { - globalCipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${globalCipher.algName}`); - } catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); - return; - } - return promiseSymKey; - }).then(key => { - let encodedKey = key.getEncoded(); - console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); - globalKey = key; - return key; - }).then(key => { - // 初始化加解密操作环境:开始加密 - let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; - let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init - return promiseInit; - }).then(() => { - let plainText = {data : stringToUint8Array('this is test!')}; - let promiseUpdate = globalCipher.update(plainText); // update - return promiseUpdate; - }).then(updateOutput => { - globalCipherText = updateOutput; - let promiseFinal = globalCipher.doFinal(null); // doFinal - return promiseFinal; - }).then(authTag => { - // 获取加密后的认证信息 - globalGcmParams.authTag = authTag; - return; - }).then(() => { - // 初始化加解密操作环境:开始解密 - let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; - let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init - return promiseInit; - }).then(() => { - let promiseUpdate = globalCipher.update(globalCipherText); // update - return promiseUpdate; - }).then(updateOutput => { - console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); - let promiseFinal = globalCipher.doFinal(null); // doFinal - return promiseFinal; - }).then(finalOutput => { - if (finalOutput == null) { - console.info('GCM finalOutput is null'); - } - }).catch(error => { - console.error(`catch error, ${error.code}, ${error.message}`); - }) -} -``` - -以3DES ECB以callback方式加解密（采用已有数据生成密钥）为例： - -```js -import cryptoFramework from '@ohos.security.cryptoFramework'; - -var globalCipher; -var globalGcmParams; -var globalKey; -var globalCipherText; - -// 可理解的字符串转成字节流 -function stringToUint8Array(str) { - let arr = []; - for (let i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - return new Uint8Array(arr); -} - -// 字节流以16进制输出 -function uint8ArrayToShowStr(uint8Array) { - return Array.prototype.map - .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) - .join(''); -} - -// 字节流转成可理解的字符串 -function uint8ArrayToString(array) { - let arrayString = ''; - for (let i = 0; i < array.length; i++) { - arrayString += String.fromCharCode(array[i]); - } - return arrayString; -} - -function genKeyMaterialBlob() { - let arr = [ - 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, - 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, - 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) - let keyMaterial = new Uint8Array(arr); - return {data : keyMaterial}; -} - -// 3DES ECB模式示例，采用已有数据生成密钥（callback写法） -function test3DesEcb() { - // 生成对称密钥生成器 - let symAlgName = '3DES192'; - let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); - if (symKeyGenerator == null) { - console.error('createSymKeyGenerator failed'); - return; - } - console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); - - // 生成加解密生成器 - let cipherAlgName = '3DES192|ECB|PKCS7'; - try { - globalCipher = cryptoFramework.createCipher(cipherAlgName); - console.info(`cipher algName: ${globalCipher.algName}`); - } catch (error) { - console.error(`createCipher failed, ${error.code}, ${error.message}`); - return; - } - - // 根据指定的数据，生成对称密钥 - let keyMaterialBlob = genKeyMaterialBlob(); - try { - symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { - if (error) { - console.error(`convertKey error, ${error.code}, ${error.message}`); - return; - } - console.info(`key algName: ${key.algName}`); - console.info(`key format: ${key.format}`); - let encodedKey = key.getEncoded(); - console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); - globalKey = key; - - // 初始化加解密操作环境:开始加密 - let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; - // init - globalCipher.init(mode, key, null, (err, ) => { - let plainText = {data : stringToUint8Array('this is test!')}; - // update - globalCipher.update(plainText, (err, updateOutput) => { - globalCipherText = updateOutput; - //doFinal - globalCipher.doFinal(null, (err, finalOutput) => { - if (error) { - console.error(`doFinal error, ${error.code}, ${error.message}`); - return; - } - if (finalOutput != null) { - globalCipherText = Array.from(globalCipherText.data); - finalOutput = Array.from(finalOutput.data); - globalCipherText = globalCipherText.concat(finalOutput); - globalCipherText = new Uint8Array(globalCipherText); - globalCipherText = {data : globalCipherText}; - } - // 初始化加解密操作环境:开始解密 - let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; - // init - globalCipher.init(mode, globalKey, null, (err, ) => { - // update - globalCipher.update(globalCipherText, (err, updateOutput) => { - console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); - // doFinal - globalCipher.doFinal(null, (error, finalOutput) => { - if (finalOutput != null) { - console.info("decrypt plainText:" + uint8ArrayToString(finalOutput.data)); - } - }) - }) - }) - }) - }) - }) - }) - } catch (error) { - console.error(`convertKey failed, ${error.code}, ${error.message}`); - return; - } -} -``` - -示例2：使用非对称密钥的加解密操作 - -1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 -2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 -3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文。 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let plan = "This is cipher test."; - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - -function encryptMessageProMise() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); - let keyGenPromise = rsaGenerator.generateKeyPair(); - keyGenPromise.then(rsaKeyPair => { - let pubKey = rsaKeyPair.pubKey; - return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); - }).then(() => { - let input = { data : stringToUint8Array(plan) }; - return cipher.doFinal(input); - }).then(dataBlob => { - console.info("EncryptOutPut is " + dataBlob.data); - }); -} - -function encryptMessageCallback() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); - rsaGenerator.generateKeyPair(function (err, keyPair) { - let pubKey = keyPair.pubKey; - cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) { - let input = {data : stringToUint8Array(plan) }; - cipher.doFinal(input, function (err, data) { - console.info("EncryptOutPut is " + data.data); - }) - }) - }) -} -``` - -**说明** - -1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 -2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念章节。 -3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 - -## 使用签名验签操作 - -**场景说明** - -当需要判断接收的数据是否被篡改且是否为指定对象发送的数据时，可以使用签名验签操作。使用签名验签操作中，典型的场景有： -1. 使用RSA签名验签操作 -2. 使用ECC签名验签操作 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createSign(algName : string) : Sign|根据String设置的参数创建Sign对象| -|Sign|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Sign对象| -|Sign|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Sign对象| -|Sign|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加签名数据| -|Sign|update(data : DataBlob) : Promise\|用Promise方式添加签名数据| -|Sign|sign(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式签名所有数据| -|Sign|sign(data : DataBlob) : Promise\|使用Promise方式签名所有数据| -|cryptoFramework|function createVerify(algName : string) : Verify|根据String设置的参数创建Verify对象| -|Verify|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Verify对象| -|Verify|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Verify对象| -|Verify|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加验签数据| -|Verify|update(data : DataBlob) : Promise\|用Promise方式添加验签数据| -|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void|使用callback方式验签所有数据| -|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\|使用Promise方式验签所有数据| - -**开发步骤** - -示例1：使用RSA签名验签操作 -1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 -2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 -3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。 -4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 -5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - -let globalKeyPair; -let SignMessageBlob; -let plan1 = "This is Sign test plan1"; -let plan2 = "This is Sign test plan1"; -let input1 = { data : stringToUint8Array(plan1) }; -let input2 = { data : stringToUint8Array(plan2) }; - -function signMessagePromise() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); - let keyGenPromise = rsaGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - return signer.init(priKey); - }).then(() => { - return signer.update(input1); - }).then(() => { - return signer.sign(input2); - }).then(dataBlob => { - SignMessageBlob = dataBlob; - console.info("sign output is " + SignMessageBlob.data); - }); -} - -function verifyMessagePromise() { - let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); - let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); - verifyInitPromise.then(() => { - return verifyer.update(input1); - }).then(() => { - return verifyer.verify(input2, SignMessageBlob); - }).then(res => { - console.log("Verify result is " + res); - }); -} - -function signMessageCallback() { - let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); - let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); - rsaGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - signer.init(priKey, function (err, data) { - signer.update(input1, function (err, data) { - signer.sign(input2, function (err, data) { - SignMessageBlob = data; - console.info("sign output is " + SignMessageBlob.data); - }); - }); - }); - }); -} - -function verifyMessageCallback() { - let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); - verifyer.init(globalKeyPair.pubKey, function (err, data) { - verifyer.update(input1, function(err, data) { - verifyer.verify(input2, SignMessageBlob, function(err, data) { - console.info("verify result is " + data); - }); - }); - }) -} -``` - -示例2：使用ECDSA操作 -1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 -2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 -3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。 -4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 -5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpArray = new Uint8Array(arr); - return tmpArray; -} - -let globalKeyPair; -let SignMessageBlob; -let plan1 = "This is Sign test plan1"; -let plan2 = "This is Sign test plan1"; -let input1 = { data : stringToUint8Array(plan1) }; -let input2 = { data : stringToUint8Array(plan2) }; - -function signMessagePromise() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let signer = cryptoFramework.createSign("ECC256|SHA256"); - let keyGenPromise = eccGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - return signer.init(priKey); - }).then(() => { - return signer.update(input1); - }).then(() => { - return signer.sign(input2); - }).then(dataBlob => { - SignMessageBlob = dataBlob; - console.info("sign output is " + SignMessageBlob.data); - }); -} - -function verifyMessagePromise() { - let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); - let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); - verifyInitPromise.then(() => { - return verifyer.update(input1); - }).then(() => { - return verifyer.verify(input2, SignMessageBlob); - }).then(res => { - console.log("Verify result is " + res); - }); -} - -function signMessageCallback() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let signer = cryptoFramework.createSign("ECC256|SHA256"); - eccGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - let priKey = globalKeyPair.priKey; - signer.init(priKey, function (err, data) { - signer.update(input1, function (err, data) { - signer.sign(input2, function (err, data) { - SignMessageBlob = data; - console.info("sign output is " + SignMessageBlob.data); - }); - }); - }); - }); -} - -function verifyMessageCallback() { - let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); - verifyer.init(globalKeyPair.pubKey, function (err, data) { - verifyer.update(input1, function(err, data) { - verifyer.verify(input2, SignMessageBlob, function(err, data) { - console.info("verify result is " + data); - }); - }); - }) -} -``` - -## 使用摘要操作 - -**场景说明** - -用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） - -使用摘要操作的主要场景为： - -用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | -------------------------------------------------- | -| cryptoFramework | function createMd(algName : string) : Md; | 指定摘要算法，生成摘要操作实例Md | -| Md | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受用户输入数据，通过Callback的方式，异步更新摘要 | -| Md | update(input : DataBlob) : Promise\; | 接受用户输入数据，通过Promise的方式，异步更新摘要 | -| Md | digest(callback : AsyncCallback\) : void; | 通过Callback的方式，返回结果 | -| Md | digest() : Promise\; | 通过Promise的方式，返回结果 | -| Md | getMdLength() : number; | 获取摘要的长度（由指定的摘要算法决定） | -| Md | readonly algName : string; | 获取当前设置的摘要算法名 | - -**开发步骤** - -1. 设置算法，通过接口`createMd`生成摘要操作实例 -2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复 -3. 通过接口`digest`，返回摘要计算结果 -4. 获取当前摘要算法名与摘要计算长度 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// turn string into uint8Arr -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -// generate dataBlob with given length -function GenDataBlob(dataBlobLen) { - var dataBlob; - if (dataBlobLen == 12) { - dataBlob = {data: stringToUint8Array("my test data")}; - } else { - console.error("GenDataBlob: dataBlobLen is invalid"); - dataBlob = {data: stringToUint8Array("my test data")}; - } - return dataBlob; -} - -// md with promise async -function doMdByPromise(algName) { - var md; - try { - md = cryptoFramework.createMd(algName); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Promise]: Md algName is: " + md.algName); - var promiseMdUpdate = md.update(GenDataBlob(12)); - promiseMdUpdate.then(() => { - var PromiseMdDigest = md.digest(); - return PromiseMdDigest; - }).then(mdOutput => { - console.error("[Promise]: MD result: " + mdOutput.data); - var mdLen = md.getMdLength(); - console.error("[Promise]: MD len: " + mdLen); - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// md with callback async -function doMdByCallback(algName) { - var md; - try { - md = cryptoFramework.createMd(algName); - } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Callback]: Md algName is: " + md.algName); - md.update(GenDataBlob(12), (err,) => { - if (err) { - console.error("[Callback]: err: " + err.code); - } - md.digest((err1, mdOutput) => { - if (err1) { - console.error("[Callback]: err: " + err1.code); - } else { - console.error("[Callback]: MD result: " + mdOutput.data); - var mdLen = md.getMdLength(); - console.error("[Callback]: MD len: " + mdLen); - } - }); - }); -} -``` - -## 使用密钥协商操作 - -**场景说明** - -使用密钥协商操作中，典型的场景有： - -通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -|实例名|接口名|描述| -|---|---|---| -|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|根据String设置的参数创建KeyAgreement对象| -|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void|使用callback方式进行密钥协商| -|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\|使用Promise方式进行密钥协商| - -**开发步骤** - -1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 -2. 基于ECC密钥的私钥及公钥执行ECDH操作。 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -let globalKeyPair; - -function ecdhPromise() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); - let keyGenPromise = eccGenerator.generateKeyPair(); - keyGenPromise.then( keyPair => { - globalKeyPair = keyPair; - return eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey); - }).then((secret) => { - console.info("ecdh output is " + secret.data); - }).catch((error) => { - console.error("ecdh error."); - }); -} - -function ecdhCallback() { - let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); - let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); - eccGenerator.generateKeyPair(function (err, keyPair) { - globalKeyPair = keyPair; - eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey, function (err, secret) { - if (err) { - console.error("ecdh error."); - return; - } - console.info("ecdh output is " + secret.data); - }); - }); -} -``` - -## 使用消息认证码操作 - -**场景说明** - -消息认证码操作主要应用于身份认证的场景： - -Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为 - -用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | --------------------------------------------------- | -| cryptoFramework | function createMac(algName : string) : Mac; | 指定摘要算法，生成消息认证码实例Mac | -| Mac | init(key : SymKey, callback : AsyncCallback\) : void; | 接收输入对称密钥，通过Callback的方式，异步初始化MAC | -| Mac | init(key : SymKey) : Promise\; | 接收输入对称密钥，通过Promise的方式，异步初始化MAC | -| Mac | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受输入数据，通过Callback的方式，异步更新MAC | -| Mac | update(input : DataBlob) : Promise\; | 接受输入数据，通过Promise的方式，异步更新MAC | -| Mac | doFinal(callback : AsyncCallback\) : void; | 通过Callback的方式，返回MAC计算结果 | -| Mac | doFinal() : Promise\; | 通过Promise的方式，返回MAC计算结果 | -| Mac | getMacLength() : number; | 获取MAC的长度（由指定的摘要算法决定） | -| Mac | readonly algName : string; | 获取当前设置的摘要算法名 | - -**开发步骤** - -1. 设置算法，通过接口`createMac`生成消息认证码操作实例 -2. 接受输入对称密钥，通过接口`init`，初始化Mac -3. 接受数据，通过接口`update`，更新Mac，此步骤可重复 -4. 通过接口`doFinal`，返回Mac计算结果 -5. 获取当前摘要算法名与Mac计算长度 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// turn string into uint8Arr -function stringToUint8Array(str) { - var arr = []; - for (var i = 0, j = str.length; i < j; ++i) { - arr.push(str.charCodeAt(i)); - } - var tmpUint8Array = new Uint8Array(arr); - return tmpUint8Array; -} - -// generate blob with this func -function GenDataBlob(dataBlobLen) { - var dataBlob; - if (dataBlobLen == 12) { - dataBlob = {data: stringToUint8Array("my test data")}; - } else { - console.error("GenDataBlob: dataBlobLen is invalid"); - dataBlob = {data: stringToUint8Array("my test data")}; - } - return dataBlob; -} - -// process by promise -function doHmacByPromise(algName) { - var mac; - try { - mac = cryptoFramework.createMac(algName); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - console.error("[Promise]: Mac algName is: " + mac.algName); - var KeyBlob = { - data : stringToUint8Array("12345678abcdefgh") - } - var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); - var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); - promiseConvertKey.then(symKey => { - var promiseMacInit = mac.init(symKey); - return promiseMacInit; - }).then(() => { - var promiseMacUpdate = mac.update(GenDataBlob(12)); - return promiseMacUpdate; - }).then(() => { - var PromiseMacDoFinal = mac.doFinal(); - return PromiseMacDoFinal; - }).then(macOutput => { - console.error("[Promise]: HMAC result: " + macOutput.data); - var macLen = mac.getMacLength(); - console.error("[Promise]: MAC len: " + macLen); - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// process by callback -function doHmacByCallback(algName) { - var mac; - try { - mac = cryptoFramework.createMac(algName); - } catch (error) { - AlertDialog.show({message: "[Callback]: error code: " + error.code + ", message is: " + error.message}); - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - var KeyBlob = { - data : stringToUint8Array("12345678abcdefgh") - } - var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); - symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { - if (err) { - console.error("[Callback]: err: " + err.code); - } - mac.init(symKey, (err1, ) => { - if (err1) { - console.error("[Callback]: err: " + err1.code); - } - mac.update(GenDataBlob(12), (err2, ) => { - if (err2) { - console.error("[Callback]: err: " + err2.code); - } - mac.doFinal((err3, macOutput) => { - if (err3) { - console.error("[Callback]: err: " + err3.code); - } else { - console.error("[Callback]: HMAC result: " + macOutput.data); - var macLen = mac.getMacLength(); - console.error("[Callback]: MAC len: " + macLen); - } - }); - }); - }); - }); -} -``` - - - -## 使用随机数操作 - -**场景说明** - -使用随机数操作的主要场景为： - -- 用户生成随机数Random实例，输入随机数生成的长度（字节），生成指定长度的随机数。 -- 用户使用生成的随机数作为参数，进行种子设置。 - -**接口及参数说明** - -详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 - -| 实例名 | 接口名 | 描述 | -| --------------- | ------------------------------------------------------------ | ---------------------------------------------- | -| cryptoFramework | function createRandom() : Random; | 生成随机数Random实例 | -| Random | generateRandom(len : number, callback: AsyncCallback\) : void; | 接受输入长度，通过Callback，异步生成随机数 | -| Random | generateRandom(len : number) : Promise\; | 接受输入长度，通过Promise，异步生成随机数 | -| Random | setSeed(seed : DataBlob) : void; | 接受输入Blob，设置种子 | - -**开发步骤** - -1. 通过接口`createRandom`生成随机数操作实例 -2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数 -3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子 - -```javascript -import cryptoFramework from "@ohos.security.cryptoFramework" - -// process by promise -function doRandByPromise(len) { - var rand; - try { - rand = cryptoFramework.createRandom(); - } catch (error) { - console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); - } - var promiseGenerateRand = rand.generateRandom(len); - promiseGenerateRand.then(randData => { - console.error("[Promise]: rand result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - }).catch(error => { - console.error("[Promise]: error: " + error.message); - }); -} - -// process by callback -function doRandByCallback(len) { - var rand; - try { - rand = cryptoFramework.createRandom(); - } catch (error) { - console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); - } - rand.generateRandom(len, (err, randData) => { - if (err) { - console.error("[Callback]: err: " + err.code); - } else { - console.error("[Callback]: generate random result: " + randData.data); - try { - rand.setSeed(randData); - } catch (error) { - console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); - } - } - }); -} -``` +# 加解密算法库框架开发指导 + +> **说明** +> +> 本开发指导基于API version 9，OH SDK版本3.2.7以上，适用于JS语言开发 + +## 使用密钥对象生成与转换操作 + +**场景说明** + +使用密钥生成操作中，典型的场景有： + +1. 随机生成算法库密钥对象。该对象可用于后续的加解密等操作。 +2. 根据指定数据生成算法库密钥对象（也就是将外部或存储的二进制数据转换为算法库的密钥对象）。该对象可用于后续的加解密等操作。 +3. 获取算法库密钥对象的二进制数据，用于存储或传输。 +> **说明**：密钥对象Key包括对称密钥SymKey和非对称密钥（公钥PubKey和私钥PriKey），其中公钥和私钥组成密钥对KeyPair。密钥之间的具体关系可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +以上场景涉及的常用接口如下表所示： + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createAsyKeyGenerator(algName : string) : AsyKeyGenerator|根据algName设置的非对称密钥规格，创建非对称密钥生成器对象| +|cryptoFramework|createSymKeyGenerator(algName : string) : SymKeyGenerator|根据algName设置的对称密钥规格，创建对称密钥生成器对象| +|AsyKeyGenerator|generateKeyPair(callback : AsyncCallback\) : void|使用callback方式，随机生成非对称密钥对象KeyPair| +|AsyKeyGenerator|generateKeyPair() : Promise\|使用Promise方式，随机生成非对称密钥对象KeyPair| +|SymKeyGenerator|generateSymKey(callback : AsyncCallback\) : void|使用callback方式，随机生成对称密钥对象SymKey| +|SymKeyGenerator|generateSymKey() : Promise\|使用Promise方式，随机生成对称密钥对象SymKey| +| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob, callback : AsyncCallback\) : void | 使用callback方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | +| AsyKeyGenerator | convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\ | 使用Promise方式，根据指定的公钥和私钥二进制数据生成KeyPair对象
（允许公钥/私钥为null，即只传入单一公钥或私钥，生成只携带公钥或私钥的KeyPair对象） | +| SymKeyGenerator | convertKey(key : DataBlob, callback : AsyncCallback\) : void| 使用callback方式，根据指定的二进制数据，生成对称密钥对象SymKey | +| SymKeyGenerator |convertKey(pubKey : DataBlob, priKey : DataBlob) : Promise\| 使用Promise方式，根据指定的二进制数据，生成对称密钥对象SymKey | +| Key | getEncoded() : DataBlob; | 获取Key密钥对象的二进制数据（Key的子类实例包括对称密钥SymKey、公钥PubKey、私钥PriKey） | + +**开发步骤** + +示例1：随机生成非对称密钥KeyPair，并获得二进制数据（场景1、3） + +1. 创建非对称密钥生成器； +2. 通过非对称密钥生成器随机生成非对称密钥； +3. 获取密钥对象的二进制数据； + +以使用Promise方式随机生成RSA密钥（1024位，素数个数为2）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function generateAsyKey() { + // 创建非对称密钥生成器 + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + // 通过非对称密钥生成器，随机生成非对称密钥 + let keyGenPromise = rsaGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + let pubKey = globalKeyPair.pubKey; + let priKey = globalKeyPair.priKey; + // 获取非对称密钥的二进制数据 + pkBlob = pubKey.getEncoded(); + skBlob = priKey.getEncoded(); + AlertDialog.show({ message : "pk bin data" + pkBlob.data} ); + AlertDialog.show({ message : "sk bin data" + skBlob.data} ); + }) +} +``` + +示例2：随机生成对称密钥SymKey，并获得二进制数据（场景1、3） + +1. 创建对称密钥生成器； +2. 通过对称密钥生成器随机生成对称密钥； +3. 获取算法库密钥对象的二进制数据； + +以使用Promise方式随机生成AES密钥（256位）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +function testGenerateAesKey() { + // 创建对称密钥生成器 + let symKeyGenerator = cryptoFramework.createSymKeyGenerator('AES256'); + // 通过密钥生成器随机生成对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + promiseSymKey.then( key => { + // 获取对称密钥的二进制数据，输出长度为256bit的字节流 + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + }) +} +``` + +示例3：根据指定的RSA非对称密钥二进制数据，生成KeyPair对象（场景2） + +1. 获取RSA公钥或私钥二进制数据，公钥需满足ASN.1语法、X.509规范、DER编码格式，私钥需满足ASN.1语法、PKCS#8规范、DER编码格式。 +2. 创建AsyKeyGenerator对象，调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +function convertAsyKey() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024"); + let pkval = new Uint8Array([48,129,159,48,13,6,9,42,134,72,134,247,13,1,1,1,5,0,3,129,141,0,48,129,137,2,129,129,0,174,203,113,83,113,3,143,213,194,79,91,9,51,142,87,45,97,65,136,24,166,35,5,179,42,47,212,79,111,74,134,120,73,67,21,19,235,80,46,152,209,133,232,87,192,140,18,206,27,106,106,169,106,46,135,111,118,32,129,27,89,255,183,116,247,38,12,7,238,77,151,167,6,102,153,126,66,28,253,253,216,64,20,138,117,72,15,216,178,37,208,179,63,204,39,94,244,170,48,190,21,11,73,169,156,104,193,3,17,100,28,60,50,92,235,218,57,73,119,19,101,164,192,161,197,106,105,73,2,3,1,0,1]); + let pkBlob = {data : pkval}; + rsaGenerator.convertKey(pkBlob, null, function(err, keyPair) { + if (keyPair == null) { + AlertDialog.show({message : "Convert keypair fail"}); + } + AlertDialog.show({message : "Convert KeyPair success"}); + }) +} +``` + +**说明** + + 当前convertKey操作，公钥只支持转换满足X.509规范的DER格式，私钥只支持PKCS#8规范的DER格式； + +示例4：根据指定的ECC非对称密钥二进制数据，生成KeyPair对象（场景2、3） + +1. 获取ECC二进制密钥数据，封装成DataBlob对象。 +2. 调用convertKey方法，传入公钥二进制和私钥二进制（二者非必选项，可只传入其中一个），转换为KeyPair对象。 + +```javascript +function convertEccAsyKey() { + let pubKeyArray = new Uint8Array([48,89,48,19,6,7,42,134,72,206,61,2,1,6,8,42,134,72,206,61,3,1,7,3,66,0,4,83,96,142,9,86,214,126,106,247,233,92,125,4,128,138,105,246,162,215,71,81,58,202,121,26,105,211,55,130,45,236,143,55,16,248,75,167,160,167,106,2,152,243,44,68,66,0,167,99,92,235,215,159,239,28,106,124,171,34,145,124,174,57,92]); + let priKeyArray = new Uint8Array([48,49,2,1,1,4,32,115,56,137,35,207,0,60,191,90,61,136,105,210,16,27,4,171,57,10,61,123,40,189,28,34,207,236,22,45,223,10,189,160,10,6,8,42,134,72,206,61,3,1,7]); + let pubKeyBlob = { data: pubKeyArray }; + let priKeyBlob = { data: priKeyArray }; + let generator = cryptoFrameWork.createAsyKeyGenerator("ECC256"); + generator.convertKey(pubKeyBlob, priKeyBlob, (error, data) => { + if (error) { + AlertDialog.show({message : "Convert keypair fail"}); + } + AlertDialog.show({message : "Convert KeyPair success"}); + }) +} +``` + +示例5：根据指定的对称密钥二进制数据，生成SymKey对象（场景2、3） + +1. 创建对称密钥生成器； +2. 通过对称密钥生成器，根据指定的对称密钥二进制数据，生成SymKey对象； +3. 获取算法库密钥对象的二进制数据； + +以使用callback方式生成3DES密钥（3DES密钥只能为192位）为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + +function testConvertAesKey() { + // 生成对称密钥生成器 + let symKeyGenerator = cryptoFramework.createSymKeyGenerator('3DES192'); + // 根据用户指定的数据，生成对称密钥 + let keyMaterialBlob = genKeyMaterialBlob(); + try { + symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { + if (error) { // 业务逻辑执行错误通过callback的第一个参数返回错误信息 + console.error(`convertKey error, ${error.code}, ${error.message}`); + return; + } + console.info(`key algName: ${key.algName}`); + console.info(`key format: ${key.format}`); + let encodedKey = key.getEncoded(); // 获取对称密钥的二进制数据，输出长度为192bit的字节流 + console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); + }) + } catch (error) { // 参数检查的错误以同步的方式立即抛出异常 + console.error(`convertKey failed, ${error.code}, ${error.message}`); + return; + } +} +``` + +## 使用加解密操作 + +**场景说明** + +在数据存储或传输场景中，可以使用加解密操作用于保证数据的机密性，防止敏感数据泄露。使用加解密操作中，典型的场景有： +1. 使用对称密钥的加解密操作 +2. 使用非对称密钥的加解密操作 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
由于密码算法的复杂性，在选取不同规格和参数时，开发差异较大，无法通过代码示例一一列举，请仔细阅读API参考资料中的相关接口，确保使用正确。 + +以上场景设计的常用接口如下表所示： + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createCipher(transformation : string) : Cipher|根据transformation设置的算法参数创建Cipher对象| +|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Cipher对象| +|Cipher|init(opMode : CryptoMode, key : Key, params : ParamsSpec) : Promise\|使用Promise方式设置密钥并初始化Cipher对象| +|Cipher|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加加解密数据| +|Cipher|update(data : DataBlob) : Promise\|使用Promise方式添加加解密数据| +|Cipher|doFinal(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式结束对所有数据的加解密| +|Cipher|doFinal(data : DataBlob) : Promise\|使用Promise方式结束对所有数据的加解密| + +**开发步骤** + +示例1：使用对称密钥的加解密操作 + +1. 创建对称密钥生成器。 +2. 通过密钥生成器生成对称密钥。 +3. 创建加解密生成器。 +4. 通过加解密生成器加密或解密数据。 + +以AES GCM以Promise方式加解密为例： + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; + +function genGcmParamsSpec() { + let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes + let dataIv = new Uint8Array(arr); + let ivBlob = {data : dataIv}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes + let dataAad = new Uint8Array(arr); + let aadBlob = {data : dataAad}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes + let dataTag = new Uint8Array(arr); + let tagBlob = {data : dataTag}; // GCM的authTag在加密时从doFinal结果中获取，在解密时填入init函数的params参数中 + + let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; + return gcmParamsSpec; +} + +// 可理解的字符串转成字节流 +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + + +// AES GCM模式示例，自动生成密钥（promise写法） +function testAesGcm() { + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve('testAesGcm'); + }, 10) + }).then(() => { + // 生成对称密钥生成器 + let symAlgName = 'AES128'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + // 通过密钥生成器随机生成128位长度的对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + // 构造参数 + globalGcmParams = genGcmParamsSpec(); + + // 生成加解密生成器 + let cipherAlgName = 'AES128|GCM|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + return promiseSymKey; + }).then(key => { + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + return key; + }).then(key => { + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init + return promiseInit; + }).then(() => { + let plainText = {data : stringToUint8Array('this is test!')}; + let promiseUpdate = globalCipher.update(plainText); // update + return promiseUpdate; + }).then(updateOutput => { + globalCipherText = updateOutput; + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(authTag => { + // GCM模式需要从doFinal的输出中取出加密后的认证信息并填入globalGcmParams，在解密时传入init() + globalGcmParams.authTag = authTag; + return; + }).then(() => { + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init + return promiseInit; + }).then(() => { + let promiseUpdate = globalCipher.update(globalCipherText); // update + return promiseUpdate; + }).then(updateOutput => { + console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(finalOutput => { + if (finalOutput == null) { // 使用finalOutput.data前，先判断结果是否为null + console.info('GCM finalOutput is null'); + } + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +以3DES ECB以callback方式加解密（采用已有数据生成密钥）为例： + +```js +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; + +// 可理解的字符串转成字节流 +function stringToUint8Array(str) { + let arr = []; + for (let i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + return new Uint8Array(arr); +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function genKeyMaterialBlob() { + let arr = [ + 0xba, 0x3d, 0xc2, 0x71, 0x21, 0x1e, 0x30, 0x56, + 0xad, 0x47, 0xfc, 0x5a, 0x46, 0x39, 0xee, 0x7c, + 0xba, 0x3b, 0xc2, 0x71, 0xab, 0xa0, 0x30, 0x72]; // keyLen = 192 (24 bytes) + let keyMaterial = new Uint8Array(arr); + return {data : keyMaterial}; +} + +// 3DES ECB模式示例，采用已有数据生成密钥（callback写法） +function test3DesEcb() { + // 生成对称密钥生成器 + let symAlgName = '3DES192'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + + // 生成加解密生成器 + let cipherAlgName = '3DES192|ECB|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + + // 根据指定的数据，生成对称密钥 + let keyMaterialBlob = genKeyMaterialBlob(); + try { + symKeyGenerator.convertKey(keyMaterialBlob, (error, key) => { + if (error) { + console.error(`convertKey error, ${error.code}, ${error.message}`); + return; + } + console.info(`key algName: ${key.algName}`); + console.info(`key format: ${key.format}`); + let encodedKey = key.getEncoded(); + console.info('key getEncoded hex: ' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + // init + globalCipher.init(mode, key, null, (err, ) => { + let plainText = {data : stringToUint8Array('this is test!')}; + // update + globalCipher.update(plainText, (err, updateOutput) => { + globalCipherText = updateOutput; + //doFinal + globalCipher.doFinal(null, (err, finalOutput) => { + if (error) { + console.error(`doFinal error, ${error.code}, ${error.message}`); + return; + } + if (finalOutput != null) { + globalCipherText = Array.from(globalCipherText.data); + finalOutput = Array.from(finalOutput.data); + globalCipherText = globalCipherText.concat(finalOutput); + globalCipherText = new Uint8Array(globalCipherText); + globalCipherText = {data : globalCipherText}; + } + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + // init + globalCipher.init(mode, globalKey, null, (err, ) => { + // update + globalCipher.update(globalCipherText, (err, updateOutput) => { + console.info('decrypt plainText: ' + uint8ArrayToString(updateOutput.data)); + // doFinal + globalCipher.doFinal(null, (error, finalOutput) => { + if (finalOutput != null) { // 使用finalOutput.data前，先判断结果是否为null + console.info("decrypt plainText:" + uint8ArrayToString(finalOutput.data)); + } + }) + }) + }) + }) + }) + }) + }) + } catch (error) { + console.error(`convertKey failed, ${error.code}, ${error.message}`); + return; + } +} +``` +以AES GCM以promise方式，分段update()实现加解密为例： + +```javascript +import cryptoFramework from '@ohos.security.cryptoFramework'; + +var globalCipher; +var globalGcmParams; +var globalKey; +var globalCipherText; +var globalPlainText; + +function genGcmParamsSpec() { + let arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0 , 0, 0]; // 12 bytes + let dataIv = new Uint8Array(arr); + let ivBlob = {data : dataIv}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0]; // 8 bytes + let dataAad = new Uint8Array(arr); + let aadBlob = {data : dataAad}; + + arr = [0, 0, 0, 0 , 0, 0, 0, 0, 0, 0, 0, 0 , 0, 0, 0, 0]; // 16 bytes + let dataTag = new Uint8Array(arr); + let tagBlob = {data : dataTag}; + let gcmParamsSpec = {iv : ivBlob, aad : aadBlob, authTag : tagBlob, algName : "GcmParamsSpec"}; + return gcmParamsSpec; +} + +// 字节流以16进制输出 +function uint8ArrayToShowStr(uint8Array) { + return Array.prototype.map + .call(uint8Array, (x) => ('00' + x.toString(16)).slice(-2)) + .join(''); +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +// 算法库不限定update的次数和每次加解密的数据量，业务可根据自身内存情况对明文/密文进行多次分段。 +function testAesMultiUpdate() { + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve('testAesMultiUpdate'); + }, 10) + }).then(() => { + // 生成对称密钥生成器 + let symAlgName = 'AES128'; + let symKeyGenerator = cryptoFramework.createSymKeyGenerator(symAlgName); + if (symKeyGenerator == null) { + console.error('createSymKeyGenerator failed'); + return; + } + console.info(`symKeyGenerator algName: ${symKeyGenerator.algName}`); + // 通过密钥生成器随机生成128位长度的对称密钥 + let promiseSymKey = symKeyGenerator.generateSymKey(); + // 构造参数 + globalGcmParams = genGcmParamsSpec(); + + // 生成加解密生成器 + let cipherAlgName = 'AES128|GCM|PKCS7'; + try { + globalCipher = cryptoFramework.createCipher(cipherAlgName); + console.info(`cipher algName: ${globalCipher.algName}`); + } catch (error) { + console.error(`createCipher failed, ${error.code}, ${error.message}`); + return; + } + return promiseSymKey; + }).then(key => { + let encodedKey = key.getEncoded(); + console.info('key hex:' + uint8ArrayToShowStr(encodedKey.data)); + globalKey = key; + return key; + }).then(key => { + // 初始化加解密操作环境:开始加密 + let mode = cryptoFramework.CryptoMode.ENCRYPT_MODE; + let promiseInit = globalCipher.init(mode, key, globalGcmParams); // init + return promiseInit; + }).then(async () => { + let plainText = "aaaaa.....bbbbb.....ccccc.....ddddd.....eee"; // 假设明文总共43字节 + let messageArr = []; + let updateLength = 20; // 假设每20字节分段update一次 + globalCipherText = []; + + for (let i = 0; i <= plainText.length; i++) { + if ((i % updateLength == 0 || i == plainText.length) && messageArr.length != 0) { + let message = new Uint8Array(messageArr); + let messageBlob = { data : message }; + let updateOutput = await globalCipher.update(messageBlob); // 分段update + // 把update的结果拼接起来，得到密文（有些情况下还需拼接doFinal的结果，这取决于分组模式 + // 和填充模式，本例中GCM模式的doFinal结果只包含authTag而不含密文，所以不需要拼接） + globalCipherText = globalCipherText.concat(Array.from(updateOutput.data)); + messageArr = []; + } + if (i < plainText.length) { + messageArr.push(plainText.charCodeAt(i)); + } + } + return; + }).then(() => { + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(authTag => { + // 获取加密后的认证信息 + globalGcmParams.authTag = authTag; + return; + }).then(() => { + // 初始化加解密操作环境:开始解密 + let mode = cryptoFramework.CryptoMode.DECRYPT_MODE; + let promiseInit = globalCipher.init(mode, globalKey, globalGcmParams); // init + return promiseInit; + }).then(async () => { + let updateLength = 20; + let updateTimes = Math.ceil(globalCipherText.length / updateLength); // 上取整 + globalPlainText = ""; + for (let i = 0; i < updateTimes; i++) { + let messageArr = globalCipherText.slice(i * updateLength, (i + 1) * updateLength); + let message = new Uint8Array(messageArr); + let messageBlob = { data : message }; + let updateOutput = await globalCipher.update(messageBlob); // 分段update + globalPlainText += uint8ArrayToString(updateOutput.data); // 恢复出原始明文 + } + return; + }).then(() => { + let promiseFinal = globalCipher.doFinal(null); // doFinal + return promiseFinal; + }).then(finalOutput => { + if (finalOutput == null) { + console.info('GCM finalOutput is null'); + } + console.info(`decrypt output: ${globalPlainText}`); + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +示例2：使用非对称密钥的加解密操作 + +1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 +2. 生成Cipher对象。通过createCipher接口创建Cipher对象，执行初始化操作，设置密钥及加解密模式。 +3. 执行加解密操作。通过调用Cipher对象提供的doFinal接口，执行加密操作生成密文或执行解密操作生成明文。 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let plan = "This is cipher test."; + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +function encryptMessageProMise() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + let keyGenPromise = rsaGenerator.generateKeyPair(); + keyGenPromise.then(rsaKeyPair => { + let pubKey = rsaKeyPair.pubKey; + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null); + }).then(() => { + let input = { data : stringToUint8Array(plan) }; + return cipher.doFinal(input); + }).then(dataBlob => { + console.info("EncryptOutPut is " + dataBlob.data); + }); +} + +function encryptMessageCallback() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + rsaGenerator.generateKeyPair(function (err, keyPair) { + let pubKey = keyPair.pubKey; + cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, pubKey, null, function (err, data) { + let input = {data : stringToUint8Array(plan) }; + cipher.doFinal(input, function (err, data) { + console.info("EncryptOutPut is " + data.data); + }) + }) + }) +} + +function decryptMessageProMise() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + let decoder = cryptoFramework.createCipher("RSA1024|PKCS1"); + let keyGenPromise = rsaGenerator.generateKeyPair(); + let keyPair; + let cipherDataBlob; + let input = { data : stringToUint8Array(plan) }; + keyGenPromise.then(rsaKeyPair => { + keyPair = rsaKeyPair; + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, keyPair.pubKey, null); + }).then(() => { + return cipher.doFinal(input); + }).then(dataBlob => { + console.info("EncryptOutPut is " + dataBlob.data); + AlertDialog.show({message : "output" + dataBlob.data}); + cipherDataBlob = dataBlob; + return decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, keyPair.priKey, null); + }).then(() => { + return decoder.doFinal(cipherDataBlob); + }).then(decodeData => { + if (decodeData.data.toString() === input.data.toString()) { + AlertDialog.show({message : "decrypt success"}); + return; + } + AlertDialog.show({message : "decrypt fail"}); + }); +} + +function decryptMessageCallback() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let cipher = cryptoFramework.createCipher("RSA1024|PKCS1"); + let decoder = cryptoFramework.createCipher("RSA1024|PKCS1"); + let plainText = "this is cipher text"; + let input = {data : stringToUint8Array(plainText) }; + let cipherData; + let keyPair; + rsaGenerator.generateKeyPair(function (err, newKeyPair) { + keyPair = newKeyPair; + cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, keyPair.pubKey, null, function (err, data) { + cipher.doFinal(input, function (err, data) { + AlertDialog.show({ message : "EncryptOutPut is " + data.data} ); + cipherData = data; + decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, keyPair.priKey, null, function (err, data) { + decoder.doFinal(cipherData, function (err, data) { + if (input.data.toString() === data.data.toString()) { + AlertDialog.show({ message : "decrype success"} ); + return; + } + AlertDialog.show({ message : "decrype fail"} ); + }); + }); + }); + }); + }); +} +``` +以RSA非对称加解密（多次调用doFinal实现分段）为例： +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +// 字节流转成可理解的字符串 +function uint8ArrayToString(array) { + let arrayString = ''; + for (let i = 0; i < array.length; i++) { + arrayString += String.fromCharCode(array[i]); + } + return arrayString; +} + +function encryptLongMessagePromise() { + let globalPlainText = "This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!"; + let globalCipherOutput; + let globalDecodeOutput; + var globalKeyPair; + let plainTextSplitLen = 64; // RSA每次加解密允许的原文长度大小与密钥位数和填充模式等有关，详细规格内容见overview文档 + let cipherTextSplitLen = 128; // RSA密钥每次加密生成的密文数据长度计算方式：密钥位数/8 + let keyGenName = "RSA1024"; + let cipherAlgName = "RSA1024|PKCS1"; + let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator(keyGenName); // 创建非对称密钥生成器对象 + let cipher = cryptoFramework.createCipher(cipherAlgName); // 创建加密Cipher对象 + let decoder = cryptoFramework.createCipher(cipherAlgName); // 创建解密Decoder对象 + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve("testRsaMultiDoFinal"); + }, 10); + }).then(() => { + return asyKeyGenerator.generateKeyPair(); // 生成rsa密钥 + }).then(keyPair => { + globalKeyPair = keyPair; // 保存到密钥对全局变量 + return cipher.init(cryptoFramework.CryptoMode.ENCRYPT_MODE, globalKeyPair.pubKey, null); + }).then(async () => { + globalCipherOutput = []; + // 将原文按64字符进行拆分，循环调用doFinal进行加密，使用1024bit密钥时，每次加密生成128B长度的密文 + for (let i = 0; i < (globalPlainText.length / plainTextSplitLen); i++) { + let tempStr = globalPlainText.substr(i * plainTextSplitLen, plainTextSplitLen); + let tempBlob = { data : stringToUint8Array(tempStr) }; + let tempCipherOutput = await cipher.doFinal(tempBlob); + globalCipherOutput = globalCipherOutput.concat(Array.from(tempCipherOutput.data)); + } + console.info(`globalCipherOutput len is ${globalCipherOutput.length}, data is: ${globalCipherOutput.toString()}`); + return; + }).then(() =>{ + return decoder.init(cryptoFramework.CryptoMode.DECRYPT_MODE, globalKeyPair.priKey, null); + }).then(async() => { + globalDecodeOutput = []; + // 将密文按128B进行拆分解密，得到原文后进行拼接 + for (let i = 0; i < (globalCipherOutput.length / cipherTextSplitLen); i++) { + let tempBlobData = globalCipherOutput.slice(i * cipherTextSplitLen, (i + 1) * cipherTextSplitLen); + let message = new Uint8Array(tempBlobData); + let tempBlob = { data : message }; + let tempDecodeOutput = await decoder.doFinal(tempBlob); + globalDecodeOutput += uint8ArrayToString(tempDecodeOutput.data); + } + if (globalDecodeOutput === globalPlainText) { + console.info(`encode and decode success`); + } else { + console.info(`encode and decode error`); + } + return; + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +**说明** + +1. 使用RSA加解密时，Cipher对象不可重复调用init方法初始化，在创建了一个加密Cipher对象后，如果要进行解密，则需要重新创建另一个Cipher对象执行解密操作。 +2. RSA加密有长度限制，允许加密明文的最大长度见[加解密算法库框架概述](cryptoFramework-overview.md)中的基本概念章节。 +3. RSA解密每次允许解密的密文长度为，RSA密钥的位数/8。 + +## 使用签名验签操作 + +**场景说明** + +当需要判断接收的数据是否被篡改且是否为指定对象发送的数据时，可以使用签名验签操作。使用签名验签操作中，典型的场景有： +1. 使用RSA签名验签操作 +2. 使用ECC签名验签操作 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。
由于密码算法的复杂性，在选取不同规格和参数时，开发差异较大，无法通过代码示例一一列举，请仔细阅读API参考资料中的相关接口，确保使用正确。 + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createSign(algName : string) : Sign|根据String设置的参数创建Sign对象| +|Sign|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Sign对象| +|Sign|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Sign对象| +|Sign|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加签名数据| +|Sign|update(data : DataBlob) : Promise\|用Promise方式添加签名数据| +|Sign|sign(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式签名所有数据| +|Sign|sign(data : DataBlob) : Promise\|使用Promise方式签名所有数据| +|cryptoFramework|function createVerify(algName : string) : Verify|根据String设置的参数创建Verify对象| +|Verify|init(priKey : PriKey, callback : AsyncCallback\) : void|使用callback方式设置密钥并初始化Verify对象| +|Verify|init(priKey : PriKey) : Promise\|使用Promise方式设置密钥并初始化Verify对象| +|Verify|update(data : DataBlob, callback : AsyncCallback\) : void|使用callback方式添加验签数据| +|Verify|update(data : DataBlob) : Promise\|用Promise方式添加验签数据| +|Verify|verify(data : DataBlob, signatureData : DataBlob, callback : AsyncCallback\) : void|使用callback方式验签所有数据| +|Verify|verify(data : DataBlob, signatureData : DataBlob) : Promise\|使用Promise方式验签所有数据| + +**开发步骤** + +示例1：使用RSA签名验签操作 +1. 生成RSA密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成RSA非对称密钥。 +2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 +3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用sign接口生成数据的签名。 +4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 +5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用verify接口传入签名进行验签。 +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +let globalKeyPair; +let SignMessageBlob; +let plan1 = "This is Sign test plan1"; +let plan2 = "This is Sign test plan1"; +let input1 = { data : stringToUint8Array(plan1) }; +let input2 = { data : stringToUint8Array(plan2) }; + +function signMessagePromise() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); + let keyGenPromise = rsaGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + return signer.init(priKey); + }).then(() => { + return signer.update(input1); + }).then(() => { + return signer.sign(input2); + }).then(dataBlob => { + SignMessageBlob = dataBlob; + console.info("sign output is " + SignMessageBlob.data); + }); +} + +function verifyMessagePromise() { + let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); + let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); + verifyInitPromise.then(() => { + return verifyer.update(input1); + }).then(() => { + return verifyer.verify(input2, SignMessageBlob); + }).then(res => { + console.log("Verify result is " + res); + }); +} + +function signMessageCallback() { + let rsaGenerator = cryptoFramework.createAsyKeyGenerator("RSA1024|PRIMES_2"); + let signer = cryptoFramework.createSign("RSA1024|PKCS1|SHA256"); + rsaGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + signer.init(priKey, function (err, data) { + signer.update(input1, function (err, data) { + signer.sign(input2, function (err, data) { + SignMessageBlob = data; + console.info("sign output is " + SignMessageBlob.data); + }); + }); + }); + }); +} + +function verifyMessageCallback() { + let verifyer = cryptoFramework.createVerify("RSA1024|PKCS1|SHA256"); + verifyer.init(globalKeyPair.pubKey, function (err, data) { + verifyer.update(input1, function(err, data) { + verifyer.verify(input2, SignMessageBlob, function(err, data) { + console.info("verify result is " + data); + }); + }); + }) +} +``` + +示例2：使用ECDSA操作 +1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 +2. 生成Sign对象。通过createSign接口创建Sign对象，执行初始化操作并设置签名私钥。 +3. 执行签名操作。通过Sign类提供的update接口，添加签名数据，并调用doFinal接口生成数据的签名。 +4. 生成Verify对象。通过createVerify接口创建Verify对象，执行初始化操作并设置验签公钥。 +5. 执行验签操作。通过Verify类提供的update接口，添加签名数据，并调用doFinal接口传入签名进行验签。 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +let globalKeyPair; +let SignMessageBlob; +let plan1 = "This is Sign test plan1"; +let plan2 = "This is Sign test plan1"; +let input1 = { data : stringToUint8Array(plan1) }; +let input2 = { data : stringToUint8Array(plan2) }; + +function signMessagePromise() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let signer = cryptoFramework.createSign("ECC256|SHA256"); + let keyGenPromise = eccGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + return signer.init(priKey); + }).then(() => { + return signer.update(input1); + }).then(() => { + return signer.sign(input2); + }).then(dataBlob => { + SignMessageBlob = dataBlob; + console.info("sign output is " + SignMessageBlob.data); + }); +} + +function verifyMessagePromise() { + let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); + let verifyInitPromise = verifyer.init(globalKeyPair.pubKey); + verifyInitPromise.then(() => { + return verifyer.update(input1); + }).then(() => { + return verifyer.verify(input2, SignMessageBlob); + }).then(res => { + console.log("Verify result is " + res); + }); +} + +function signMessageCallback() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let signer = cryptoFramework.createSign("ECC256|SHA256"); + eccGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + let priKey = globalKeyPair.priKey; + signer.init(priKey, function (err, data) { + signer.update(input1, function (err, data) { + signer.sign(input2, function (err, data) { + SignMessageBlob = data; + console.info("sign output is " + SignMessageBlob.data); + }); + }); + }); + }); +} + +function verifyMessageCallback() { + let verifyer = cryptoFramework.createVerify("ECC256|SHA256"); + verifyer.init(globalKeyPair.pubKey, function (err, data) { + verifyer.update(input1, function(err, data) { + verifyer.verify(input2, SignMessageBlob, function(err, data) { + console.info("verify result is " + data); + }); + }); + }) +} +``` +以执行签名、验签操作时多次调用update实现分段为例： + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpArray = new Uint8Array(arr); + return tmpArray; +} + +function signLongMessagePromise() { + let globalPlainText = "This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!" + + "This is a long plainTest! This is a long plainTest! This is a long plainTest! This is a long plainTest!"; + let globalSignData; + let textSplitLen = 64; // 自定义的数据拆分长度 + let keyGenName = "RSA1024"; + let cipherAlgName = "RSA1024|PKCS1|SHA256"; + let globalKeyPair; + let asyKeyGenerator = cryptoFramework.createAsyKeyGenerator(keyGenName); // 创建非对称密钥生成器对象 + let signer = cryptoFramework.createSign(cipherAlgName); // 创建加密Cipher对象 + let verifier = cryptoFramework.createVerify(cipherAlgName); // 创建解密Decoder对象 + return new Promise((resolve, reject) => { + setTimeout(() => { + resolve("testRsaMultiUpdate"); + }, 10); + }).then(() => { + return asyKeyGenerator.generateKeyPair(); // 生成rsa密钥 + }).then(keyPair => { + globalKeyPair = keyPair; // 保存到密钥对全局变量 + return signer.init(globalKeyPair.priKey); + }).then(async () => { + // 当原文过大时，可将原文按理想长度进行拆分，循环调用update添加原文 + for (let i = 0; i < (globalPlainText.length / textSplitLen); i++) { + let tempStr = globalPlainText.substr(i * textSplitLen, textSplitLen); + let tempBlob = { data : stringToUint8Array(tempStr) }; + await signer.update(tempBlob); + } + return signer.sign(null); + }).then(data =>{ + globalSignData = data.data; + console.info(`globalSignOutput len is ${globalSignData.length}, data is: ${globalSignData.toString()}`); + return verifier.init(globalKeyPair.pubKey); + }).then(async() => { + // 将密文按128B进行拆分解密，得到原文后进行拼接 + for (let i = 0; i < (globalPlainText.length / textSplitLen); i++) { + let tempData = globalPlainText.slice(i * textSplitLen, (i + 1) * textSplitLen); + let tempBlob = { data : stringToUint8Array(tempData) }; + await verifier.update(tempBlob); + } + return verifier.verify(null, { data : globalSignData}); + }).then(res => { + console.info(`verify res is ${res}`); + }).catch(error => { + console.error(`catch error, ${error.code}, ${error.message}`); + }) +} +``` + +## 使用摘要操作 + +**场景说明** + +用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） + +使用摘要操作的主要场景为： + +用户指定摘要算法（如SHA256）生成Md实例，并输入单段或多段需要摘要的信息，进行摘要计算更新，并返回消息摘要计算结果，在指定算法后可获取当前算法名与摘要计算长度（字节） + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | -------------------------------------------------- | +| cryptoFramework | function createMd(algName : string) : Md; | 指定摘要算法，生成摘要操作实例Md | +| Md | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受用户输入数据，通过Callback的方式，异步更新摘要 | +| Md | update(input : DataBlob) : Promise\; | 接受用户输入数据，通过Promise的方式，异步更新摘要 | +| Md | digest(callback : AsyncCallback\) : void; | 通过Callback的方式，返回结果 | +| Md | digest() : Promise\; | 通过Promise的方式，返回结果 | +| Md | getMdLength() : number; | 获取摘要的长度（由指定的摘要算法决定） | +| Md | readonly algName : string; | 获取当前设置的摘要算法名 | + +**开发步骤** + +1. 设置算法，通过接口`createMd`生成摘要操作实例 +2. 接受用户数据，通过接口`update`，更新摘要，此步骤可重复 +3. 通过接口`digest`，返回摘要计算结果 +4. 获取当前摘要算法名与摘要计算长度 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// turn string into uint8Arr +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +// generate dataBlob with given length +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +// md with promise async +function doMdByPromise(algName) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Promise]: Md algName is: " + md.algName); + // 初次update + var promiseMdUpdate = md.update(GenDataBlob(12)); + promiseMdUpdate.then(() => { + // 可根据情况进行多次update + promiseMdUpdate = md.update(GenDataBlob(12)); + return promiseMdUpdate; + }).then(mdOutput => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Promise]: MD len: " + mdLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// md with callback async +function doMdByCallback(algName) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Callback]: Md algName is: " + md.algName); + // 初次update + md.update(GenDataBlob(12), (err,) => { + if (err) { + console.error("[Callback]: err: " + err.code); + } + // 可根据情况进行多次update + md.update(GenDataBlob(12), (err1,) => { + if (err1) { + console.error("[Callback]: err: " + err1.code); + } + md.digest((err2, mdOutput) => { + if (err2) { + console.error("[Callback]: err: " + err2.code); + } else { + console.error("[Callback]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Callback]: MD len: " + mdLen); + } + }); + }); + }); +} +``` +以MD更新时多次调用update实现分段为例： +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +async function updateData(index, obj, data) { + console.error("update " + (index + 1) + " MB data..."); + return obj.update(data); +} + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function LoopMdPromise(algName, loopSize) { + var md; + try { + md = cryptoFramework.createMd(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + return; + } + console.error("[Promise]: Md algName is: " + md.algName); + var promiseMdUpdate = md.update(GenDataBlob(12)); + promiseMdUpdate.then(() => { + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(async () => { + for (var i = 0; i < loopSize; i++) { + await updateData(i, md, GenDataBlob(12)); + } + var PromiseMdDigest = md.digest(); + return PromiseMdDigest; + }).then(mdOutput => { + console.error("[Promise]: MD result: " + mdOutput.data); + var mdLen = md.getMdLength(); + console.error("[Promise]: MD len: " + mdLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} +``` + +## 使用密钥协商操作 + +**场景说明** + +使用密钥协商操作中，典型的场景有： + +通信双方可以在一个公开的信道上通过相互传送一些消息，共同建立一个安全的共享秘密密钥。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +|实例名|接口名|描述| +|---|---|---| +|cryptoFramework|createKeyAgreement(algName : string) : KeyAgreement|根据String设置的参数创建KeyAgreement对象| +|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey, callback : AsyncCallback\) : void|使用callback方式进行密钥协商| +|KeyAgreement|generateSecret(priKey : PriKey, pubKey : PubKey) : Promise\|使用Promise方式进行密钥协商| + +**开发步骤** + +1. 生成ECC密钥。通过createAsyKeyGenerator接口创建AsyKeyGenerator对象，并生成ECC非对称密钥。 +2. 基于ECC密钥的私钥及公钥执行ECDH操作。 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +let globalKeyPair; + +function ecdhPromise() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); + let keyGenPromise = eccGenerator.generateKeyPair(); + keyGenPromise.then( keyPair => { + globalKeyPair = keyPair; + return eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey); + }).then((secret) => { + console.info("ecdh output is " + secret.data); + }).catch((error) => { + console.error("ecdh error."); + }); +} + +function ecdhCallback() { + let eccGenerator = cryptoFramework.createAsyKeyGenerator("ECC256"); + let eccKeyAgreement = cryptoFramework.createKeyAgreement("ECC256"); + eccGenerator.generateKeyPair(function (err, keyPair) { + globalKeyPair = keyPair; + eccKeyAgreement.generateSecret(keyPair.priKey, keyPair.pubKey, function (err, secret) { + if (err) { + console.error("ecdh error."); + return; + } + console.info("ecdh output is " + secret.data); + }); + }); +} +``` + +## 使用消息认证码操作 + +**场景说明** + +消息认证码操作主要应用于身份认证的场景： + +Mac(message authentication code)可以对消息进行完整性校验，通过使用双方共享的密钥，识别出信息伪装篡改等行为 + +用户指定摘要算法（如SHA256）生成消息认证码Mac实例，输入对称密钥初始化Mac，并传入单段或多段需要摘要的信息，进行消息认证码计算，并获取消息认证码计算结果，在指定算法后可获取当前算法名与消息认证码计算长度（字节）。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | --------------------------------------------------- | +| cryptoFramework | function createMac(algName : string) : Mac; | 指定摘要算法，生成消息认证码实例Mac | +| Mac | init(key : SymKey, callback : AsyncCallback\) : void; | 接收输入对称密钥，通过Callback的方式，异步初始化MAC | +| Mac | init(key : SymKey) : Promise\; | 接收输入对称密钥，通过Promise的方式，异步初始化MAC | +| Mac | update(input : DataBlob, callback : AsyncCallback\) : void; | 接受输入数据，通过Callback的方式，异步更新MAC | +| Mac | update(input : DataBlob) : Promise\; | 接受输入数据，通过Promise的方式，异步更新MAC | +| Mac | doFinal(callback : AsyncCallback\) : void; | 通过Callback的方式，返回MAC计算结果 | +| Mac | doFinal() : Promise\; | 通过Promise的方式，返回MAC计算结果 | +| Mac | getMacLength() : number; | 获取MAC的长度（由指定的摘要算法决定） | +| Mac | readonly algName : string; | 获取当前设置的摘要算法名 | + +**开发步骤** + +1. 设置算法，通过接口`createMac`生成消息认证码操作实例 +2. 接受输入对称密钥，通过接口`init`，初始化Mac +3. 接受数据，通过接口`update`，更新Mac，此步骤可重复 +4. 通过接口`doFinal`，返回Mac计算结果 +5. 获取当前摘要算法名与Mac计算长度 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// turn string into uint8Arr +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +// generate blob with this func +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function doHmacByPromise(algName) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + console.error("[Promise]: Mac algName is: " + mac.algName); + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); + var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); + promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; + }).then(() => { + // 初次update + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + // 可根据情况进行多次update + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; + }).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Promise]: MAC len: " + macLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// process by callback +function doHmacByCallback(algName) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + AlertDialog.show({message: "[Callback]: error code: " + error.code + ", message is: " + error.message}); + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); + symKeyGenerator.convertKey(KeyBlob, (err, symKey) => { + if (err) { + console.error("[Callback]: err: " + err.code); + } + mac.init(symKey, (err1, ) => { + if (err1) { + console.error("[Callback]: err: " + err1.code); + } + // 初次update + mac.update(GenDataBlob(12), (err2, ) => { + if (err2) { + console.error("[Callback]: err: " + err2.code); + } + // 可根据情况进行多次update + mac.update(GenDataBlob(12), (err3, ) => { + if (err3) { + console.error("[Callback]: err: " + err3.code); + } + mac.doFinal((err4, macOutput) => { + if (err4) { + console.error("[Callback]: err: " + err4.code); + } else { + console.error("[Callback]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Callback]: MAC len: " + macLen); + } + }); + }); + }); + }); + }); +} +``` +以HMAC更新MAC时多次调用update实现分段为例： +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +async function updateData(index, obj, data) { + console.error("update " + (index + 1) + " MB data..."); + return obj.update(data); +} + +function stringToUint8Array(str) { + var arr = []; + for (var i = 0, j = str.length; i < j; ++i) { + arr.push(str.charCodeAt(i)); + } + var tmpUint8Array = new Uint8Array(arr); + return tmpUint8Array; +} + +function GenDataBlob(dataBlobLen) { + var dataBlob; + if (dataBlobLen == 12) { + dataBlob = {data: stringToUint8Array("my test data")}; + } else { + console.error("GenDataBlob: dataBlobLen is invalid"); + dataBlob = {data: stringToUint8Array("my test data")}; + } + return dataBlob; +} + +function LoopHmacPromise(algName, loopSize) { + var mac; + try { + mac = cryptoFramework.createMac(algName); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + return; + } + console.error("[Promise]: Mac algName is: " + mac.algName); + var KeyBlob = { + data : stringToUint8Array("12345678abcdefgh") + } + var symKeyGenerator = cryptoFramework.createSymKeyGenerator("AES128"); + var promiseConvertKey = symKeyGenerator.convertKey(KeyBlob); + promiseConvertKey.then(symKey => { + var promiseMacInit = mac.init(symKey); + return promiseMacInit; + }).then(async () => { + for (var i = 0; i < loopSize; i++) { + await updateData(i, mac, GenDataBlob(12)); + } + var promiseMacUpdate = mac.update(GenDataBlob(12)); + return promiseMacUpdate; + }).then(() => { + var PromiseMacDoFinal = mac.doFinal(); + return PromiseMacDoFinal; + }).then(macOutput => { + console.error("[Promise]: HMAC result: " + macOutput.data); + var macLen = mac.getMacLength(); + console.error("[Promise]: MAC len: " + macLen); + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} +``` + + +## 使用随机数操作 + +**场景说明** + +使用随机数操作的主要场景为： + +- 用户生成随机数Random实例，输入随机数生成的长度（字节），生成指定长度的随机数。 +- 用户使用生成的随机数作为参数，进行种子设置。 + +**接口及参数说明** + +详细接口说明可参考[API参考](../reference/apis/js-apis-cryptoFramework.md)。 + +| 实例名 | 接口名 | 描述 | +| --------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| cryptoFramework | function createRandom() : Random; | 生成随机数Random实例 | +| Random | generateRandom(len : number, callback: AsyncCallback\) : void; | 接受输入长度，通过Callback，异步生成随机数 | +| Random | generateRandom(len : number) : Promise\; | 接受输入长度，通过Promise，异步生成随机数 | +| Random | setSeed(seed : DataBlob) : void; | 接受输入Blob，设置种子 | + +**开发步骤** + +1. 通过接口`createRandom`生成随机数操作实例 +2. 接受输入长度，通过接口`generateRandom`，生成指定长度的随机数 +3. 接受DataBlob数据，通过接口`setSeed`，为随机数生成池设置种子 + +```javascript +import cryptoFramework from "@ohos.security.cryptoFramework" + +// process by promise +function doRandByPromise(len) { + var rand; + try { + rand = cryptoFramework.createRandom(); + } catch (error) { + console.error("[Promise]: error code: " + error.code + ", message is: " + error.message); + } + var promiseGenerateRand = rand.generateRandom(len); + promiseGenerateRand.then(randData => { + console.error("[Promise]: rand result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + }).catch(error => { + console.error("[Promise]: error: " + error.message); + }); +} + +// process by callback +function doRandByCallback(len) { + var rand; + try { + rand = cryptoFramework.createRandom(); + } catch (error) { + console.error("[Callback]: error code: " + error.code + ", message is: " + error.message); + } + rand.generateRandom(len, (err, randData) => { + if (err) { + console.error("[Callback]: err: " + err.code); + } else { + console.error("[Callback]: generate random result: " + randData.data); + try { + rand.setSeed(randData); + } catch (error) { + console.log("setSeed failed, errCode: " + error.code + ", errMsg: " + error.message); + } + } + }); +} +``` diff --git a/zh-cn/application-dev/security/cryptoFramework-overview.md b/zh-cn/application-dev/security/cryptoFramework-overview.md index 0678a4d0f6cda6e596880e21af4a2da982f0ff62..65c6ef5d43d7773be21c1f73cf17c0a46200b8c9 100644 --- a/zh-cn/application-dev/security/cryptoFramework-overview.md +++ b/zh-cn/application-dev/security/cryptoFramework-overview.md @@ -1,235 +1,385 @@ -# 加解密算法库框架概述 -加解密算法库框架是一个屏蔽了第三方密码学算法库实现差异的算法框架，提供加解密、签名验签、消息验证码、哈希、安全随机数等相关功能。开发者可以通过调用加解密算法库框架，忽略底层不同三方算法库的差异，实现迅捷开发。 -## 框架实现原理 -加解密算法库框架提供的组件分为三层：接口层，Framework层和插件层。接口层负责对外提供统一的JS接口，插件层实现针对具体三方算法库的功能，Framework层通过灵活加载插件层的插件适配并屏蔽三方算法库差异。 -## 基本概念 -**对称密钥** - -对称密钥使用同一个密钥对数据进行加密解密操作。即对称加密算法中，数据发送方使用加密密钥对明文进行特殊加密算法处理后，使其变成复杂的加密密文发送出去。接收方收到密文后，若想解读原文，则需要使用同一个加密密钥以及相同算法的逆算法对密文进行解密，才能使其恢复成可读明文。 - -- **AES加密** - - AES的全称是Advanced Encryption Standard，是最常见的对称加密。AES为分组密码，分组密码也就是把明文分成一组一组的，每组长度相等，每次加密一组数据，直到加密完整个明文。在AES标准规范中，分组长度只能是128位，也就是说，每个分组为16个字节（每个字节8位）。密钥的长度可以使用128位、192位或256位。 -- **3DES加密** - - 3DES，也称为 3DESede 或 TripleDES，是三重数据加密算法，相当于是对每个数据块应用三次DES的对称加密算法，它使用3个64位的密钥对数据块进行三次加密。相比DES，3DES因密钥长度变长，安全性有所提高，但其处理速度不高。因此又出现了AES加密算法，AES较于3DES速度更快、安全性更高。 - -**非对称密钥** - -非对称密钥使用公钥和私钥两个密钥来进行算法操作，公钥对外公开，私钥对外保密。对于加解密操作，一般使用公钥对明文进行加密形成密文，持有私钥的人即可对密文解密形成明文。对于签名验签操作，使用私钥对明文进行签名，公钥持有者可以通过公钥对签名数据做验签，验证数据是否被篡改。 - -- **RSA密钥** - - RSA密钥以极大整数做因数分解的数学难题作为密钥安全性的基石。生成密钥时，首先需要随机出两个大素数p和q，计算n = p * q并将n做为模，再选择一个大于1且小于(p - 1) * (q - 1)的整数e，确保e与(p - 1)*(q - 1)互素，最后计算d，使得e * d - 1为(p - 1)和(q - 1)的倍数，则可得到公钥(n, e)和私钥(n, d)。 - - 算法库框架除提供了默认的双素数RSA密钥生成外，还提供了多素数密钥生成方式，可以在密钥生成时通过指定primes参数（PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5）指定素数个数。多素数密钥的优点是可以减少解密、签名的计算量（中国剩余定理），但相对的劣势是密钥强度会越低，算法库依据OpenSSL的素数使用规则制定了相应规格，具体将在**约束与限制**章节中说明。 -- **ECC密钥** - - ECC是一种基于椭圆曲线数学的公开密钥加密算法，其数学基础是利用椭圆曲线上的有理点构成Abel加法群上椭圆离散对数的计算困难性，算法库框架提供了多种椭圆曲线的ECC密钥生成能力。 - -**加解密** - -- **对称AES加解密** - - 算法库目前提供了AES加解密常用的7种加密模式：ECB、CBC、OFB、CFB、CTR、GCM和CCM。AES为分组加密算法，分组长度大小为128位。实际应用中明文最后一组可能不足128位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充； - - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； - - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； - - > **说明：** ECB、CBC加密模式，明文长度不是128位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即AES加密填充至16字节。 -- **对称3DES加解密** - - 该算法的加解密过程分别是对明文/密文数据进行三次DES加密或解密，得到相应的密文或明文。 - - 算法库目前提供了3DES加解密常用的4种加密模式：ECB、CBC、OFB和CFB。DES为分组加密算法，分组长度大小为64位。实际应用中明文最后一组可能不足64位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充； - - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； - - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； - - > **说明：** ECB、CBC加密模式，明文长度不是64位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即3DES加密填充至8字节。 - -- **非对称RSA加解密** - - 当持有RSA公钥(n, e)和私钥(n, d)后，RSA加密过程为：密文 = 明文 ^ e mod n, 解密过程为：明文 = 密文 ^ d mod n。算法库目前提供了RSA加解密常用的三种模式：PKCS1、PKCS1_OAEP和NoPadding。RSA为块加密算法，加密长度需要在固定长度进行，实际应用中会使用各种padding模式做数据填充。下文中描述了各个padding的区别： - - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长； - - PKCS1：pkcs1padding V1.5是RSA加解密默认的填充方式，输入的数据必须<=RSA钥模-11，输出数据长度与RSA钥模一样长； - - PKCS1_OAEP：RSA_PKCS1_OAEP_PADDING填充模式是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2，输出数据长度与RSA钥模一样长；
- - **补充说明：** RSA钥模 = (RSA的bits + 7) / 8 - -**签名验签** - -- **RSA签名验签** - - 当持有RSA公钥(n, e)和私钥(n, d)后，RSA签名生成过程为：签名 = 消息 ^ d mod n, 验签过程为：消息 = 签名 ^ d mod n。消息发送方发送数据时，同时发送消息和私钥签名后的签名信息，消息接收方接受到数据后，将签名信息用公钥解密并验证消息是否一致。因发送的消息长度大多大于RSA钥模，因此算法库框架提供了两种padding模式，通过摘要提取消息的散列值再做签名。算法库框架中提供了签名验签相关的两种模式：PKCS1和PSS。下问对两种模式做详细描述： - - PKCS1: pkcs1padding V1.5是RSA加解密默认的填充方式，使用该模式时需要设置摘要（md）； - - PSS: PSS模式是RSA 算法的基础上叠加上一种填充算法，使用该签名算法时需要使用摘要(md)和掩码函数（mgf1_md）; -- **ECDSA** - - 椭圆曲线数字签名算法（ECDSA）是基于椭圆曲线密码（ECC）模拟数字签名算法（DSA）。相比普通的离散对数问题（DLP）和大数分解问题（IFP），椭圆曲线密码的单位比特强度要高于其他公钥体制。算法库框架提供了多种椭圆曲线及摘要算法组合的椭圆曲线数字签名算法（ECDSA）能力。 - -**密钥协商** - -- **ECDH** - - ECDH的全称是椭圆曲线迪菲-赫尔曼秘钥交换，是用来在一个非安全通道中建立起安全的共有加密资料，交换双方可以在不共享任何秘密的情况下协商出一个密钥。算法库框架基于开源算法库提供了多种椭圆曲线的ECDH能力。 - -**摘要** - -消息摘要MD算法是一种能将任意长度的输入消息，通过哈希算法生成长度固定的摘要的算法。消息摘要算法通过其不可逆的特性能被用于敏感信息的加密。消息摘要算法也被称为哈希算法或单向散列算法。 -在摘要算法相同时，生成的摘要值主要有下列特点： - -- 当输入消息相同时，生成摘要序列相同； -- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）； -- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）； - -消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节） -MD算法包括MD2，MD4和MD5。 -SHA算法主要包括SHA1，SHA224，SHA256，SHA384，SHA512。 - -**消息验证码** - -HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息认证码算法。HMAC通过指定摘要算法，以通信双方共享密钥与消息作为输入，生成消息认证码用于检验传递报文的完整性，HMAC生成的消息认证码为固定长度。HMAC在消息摘要算法的基础上增加了密钥的输入，确保了信息的正确性。 - -**随机数** - -随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性 - -- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列 -- **种子**（seed）是一个用来对伪随机数的内部状态进行初始化的数据，随机数生成器通过种子来生成一系列的随机序列。 - - -## 约束与限制 - -- 算法库框架不支持多线程并发操作。 - -### 密钥生成规格 - -**对称密钥生成规格** - -支持的对称密钥生成参数： - -|对称密钥算法|密钥长度（bit）|字符串参数| -|---|---|---| -|3DES|192|3DES192| -|AES|128|AES128| -|AES|192|AES192| -|AES|256|AES256| - - > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 - -**非对称密钥生成规格** -- **RSA密钥生成** - - 支持的非对称密钥生成参数： - - |非对称密钥算法|密钥长度（bit）|素数个数|字符串参数| - |---|---|---|---| - |RSA|512|2|RSA512\|PRIMES_2| - |RSA|768|2|RSA768\|PRIMES_2| - |RSA|1024|2|RSA1024\|PRIMES_2| - |RSA|1024|3|RSA1024\|PRIMES_3| - |RSA|2048|2|RSA2048\|PRIMES_2| - |RSA|2048|3|RSA2048\|PRIMES_3| - |RSA|3072|2|RSA3072\|PRIMES_2| - |RSA|3072|3|RSA3072\|PRIMES_3| - |RSA|4096|2|RSA4096\|PRIMES_2| - |RSA|4096|3|RSA4096\|PRIMES_3| - |RSA|4096|4|RSA4096\|PRIMES_4| - |RSA|8192|2|RSA8192\|PRIMES_2| - |RSA|8192|3|RSA8192\|PRIMES_3| - |RSA|8192|4|RSA8192\|PRIMES_4| - |RSA|8192|5|RSA8192\|PRIMES_5| - - > **说明**：生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 - -- **ECC密钥生成** - - 支持的非对称密钥生成参数： - - |非对称密钥算法|密钥长度| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - -### 加解密规格 - -**对称加解密** - -支持的对称加密算法： - -|对称加解密算法|分组模式| 字符串参数 | -|---|---|---| -|3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]| -|3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]| -|AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]| -|AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]| -|AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]| - -> **说明：** -> 1. []中只能任选一项。 -> 2. “字符串参数”是“对称加解密算法（含密钥长度）”、“分组模式”、“填充模式”拼接而成，用于在创建对称加解密实例时，指定对称加解密算法规格。 - -**非对称RSA加解密** - -RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 -- 使用NoPadding模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|NoPadding -- 使用PKCS1模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1 -- 使用PKCS1_OAEP模式时可以指定的参数：[RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1_OAEP|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512]|[MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] - -> **说明：** []内的参数只能任选一项，非[]内的为固定值 - -### 签名验签规格 - -**RSA签名验签** - -RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 -- 使用PKCS1模式时可以指定的参数: [RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PKCS1|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512] -- 使用PSS模式时可以指定的参数：[RSA512|RSA768|RSA1024|RSA2048|RSA3072|RSA4096|RSA8192]|PSS|[MD5|SHA1|SHA224|SHA256|SHA384|SHA512]|[MGF1_MD5|MGF1_SHA1|MGF1_SHA224|MGF1_SHA256|MGF1_SHA384|MGF1_SHA512] -> **说明：** []内的参数只能任选一项，非[]内的为固定值 - -**ECDSA签名验签** - -支持的ECDSA参数： - - |非对称密钥算法|支持种类| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - - |摘要算法|支持种类| - |---|---| - |HASH|SHA1| - |HASH|SHA224| - |HASH|SHA256| - |HASH|SHA384| - |HASH|SHA512| - -### 密钥协商规格 - -**ECDH** - - 支持的ECDH参数： - - |非对称密钥算法|支持种类| - |---|---| - |ECC|ECC224| - |ECC|ECC256| - |ECC|ECC384| - |ECC|ECC521| - -### MD算法规格 -加解密算法库框架当前支持MD5算法 - -### SHA算法规格 -加解密算法库框架当前支持：SHA1，SHA224，SHA256，SHA384，SHA512 +# 加解密算法库框架概述 +加解密算法库框架是一个屏蔽了第三方密码学算法库实现差异的算法框架，提供加解密、签名验签、消息验证码、哈希、安全随机数等相关功能。开发者可以通过调用加解密算法库框架，忽略底层不同三方算法库的差异，实现迅捷开发。 + +> **说明：** 加解密算法库框架仅提供密钥的密码学操作，而不提供密钥管理功能。因此，使用算法库时，需要应用自己来保管密钥（适用于临时会话密钥等仅在内存中使用的场景，或者应用自己实现密钥安全存储的场景）。如果业务需要由系统提供密钥管理功能（密钥存储等），请使用[HUKS部件](huks-overview.md)。 + +## 框架实现原理 +加解密算法库框架提供的组件分为三层：接口层，Framework层和插件层。接口层负责对外提供统一的JS接口，插件层实现针对具体三方算法库的功能，Framework层通过灵活加载插件层的插件适配并屏蔽三方算法库差异。 + +## 基本概念 +**对称密钥** + +对称密钥使用同一个密钥对数据进行加密解密操作。即对称加密算法中，数据发送方使用加密密钥对明文进行特殊加密算法处理后，使其变成复杂的加密密文发送出去。接收方收到密文后，若想解读原文，则需要使用同一个加密密钥以及相同算法的逆算法对密文进行解密，才能使其恢复成可读明文。 + +- **AES加密** + + AES的全称是Advanced Encryption Standard，是最常见的对称加密。AES为分组密码，分组密码也就是把明文分成一组一组的，每组长度相等，每次加密一组数据，直到加密完整个明文。在AES标准规范中，分组长度只能是128位，也就是说，每个分组为16个字节（每个字节8位）。密钥的长度可以使用128位、192位或256位。 +- **3DES加密** + + 3DES，也称为 3DESede 或 TripleDES，是三重数据加密算法，相当于是对每个数据块应用三次DES的对称加密算法，它使用3个64位的密钥对数据块进行三次加密。相比DES，3DES因密钥长度变长，安全性有所提高，但其处理速度不高。因此又出现了AES加密算法，AES较于3DES速度更快、安全性更高。 + +**非对称密钥** + +非对称密钥使用公钥和私钥两个密钥来进行算法操作，公钥对外公开，私钥对外保密。对于加解密操作，一般使用公钥对明文进行加密形成密文，持有私钥的人即可对密文解密形成明文。对于签名验签操作，使用私钥对明文进行签名，公钥持有者可以通过公钥对签名数据做验签，验证数据是否被篡改。 + +- **RSA密钥** + + RSA密钥以极大整数做因数分解的数学难题作为密钥安全性的基石。生成密钥时，首先需要随机出两个大素数p和q，计算n = p * q并将n做为模，再选择一个大于1且小于(p - 1) * (q - 1)的整数e，确保e与(p - 1)*(q - 1)互素，最后计算d，使得e * d - 1为(p - 1)和(q - 1)的倍数，则可得到公钥(n, e)和私钥(n, d)。 + + 算法库框架除提供了默认的双素数RSA密钥生成外，还提供了多素数密钥生成方式，可以在密钥生成时通过指定primes参数（PRIMES_2, PRIMES_3, PRIMES_4, PRIMES_5）指定素数个数。多素数密钥的优点是可以减少解密、签名的计算量（中国剩余定理），但相对的劣势是密钥强度会越低，算法库依据OpenSSL的素数使用规则制定了相应规格，具体将在**约束与限制**章节中说明。 +- **ECC密钥** + + ECC是一种基于椭圆曲线数学的公开密钥加密算法，其数学基础是利用椭圆曲线上的有理点构成Abel加法群上椭圆离散对数的计算困难性，算法库框架提供了多种椭圆曲线的ECC密钥生成能力。 + +**加解密** + +- **对称AES加解密** + + 算法库目前提供了AES加解密常用的7种加密模式：ECB、CBC、OFB、CFB、CTR、GCM和CCM。AES为分组加密算法，分组长度大小为128位。实际应用中明文最后一组可能不足128位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充； + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； + + > **说明：** ECB、CBC加密模式，明文长度不是128位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即AES加密填充至16字节。 +- **对称3DES加解密** + + 该算法的加解密过程分别是对明文/密文数据进行三次DES加密或解密，得到相应的密文或明文。 + + 算法库目前提供了3DES加解密常用的4种加密模式：ECB、CBC、OFB和CFB。DES为分组加密算法，分组长度大小为64位。实际应用中明文最后一组可能不足64位，不足数据可以使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充； + - PKCS5：填充字符由一个字节序列组成，每个字节填充该填充字节序列的长度，规定是8字节填充； + - PKCS7：填充字符和PKCS5填充方法一致，但是可以在1-255字节之间任意填充； + + > **说明：** ECB、CBC加密模式，明文长度不是64位整数倍，必须使用填充方法补足。
由于需要填充至分组大小，所以实际算法库中的PKCS5和PKCS7都是以分组大小作为填充长度的，即3DES加密填充至8字节。 + +- **非对称RSA加解密** + + 当持有RSA公钥(n, e)和私钥(n, d)后，RSA加密过程为：密文 = 明文 ^ e mod n, 解密过程为：明文 = 密文 ^ d mod n。算法库目前提供了RSA加解密常用的三种模式：PKCS1、PKCS1_OAEP和NoPadding。RSA为块加密算法，加密长度需要在固定长度进行，实际应用中会使用各种padding模式做数据填充。下文中描述了各个padding的区别： + - NoPadding：不带填充，输入的数据必须与RSA钥模一样长，输出数据长度与RSA钥模一样长； + - PKCS1：pkcs1padding V1.5是RSA加解密默认的填充方式，输入的数据必须<=RSA钥模-11，输出数据长度与RSA钥模一样长； + - PKCS1_OAEP：RSA_PKCS1_OAEP_PADDING填充模式是PKCS#1推出的新填充方式，此模式需要设置两个摘要（md和mgf1_md），输入的数据必须小于RSA钥模 - md摘要长度 - mgf1_md摘要长度 - 2，输出数据长度与RSA钥模一样长；
+ + **补充说明：** RSA钥模 = (RSA的bits + 7) / 8 + +**签名验签** + +- **RSA签名验签** + + 当持有RSA公钥(n, e)和私钥(n, d)后，RSA签名生成过程为：签名 = 消息 ^ d mod n, 验签过程为：消息 = 签名 ^ d mod n。消息发送方发送数据时，同时发送消息和私钥签名后的签名信息，消息接收方接受到数据后，将签名信息用公钥解密并验证消息是否一致。因发送的消息长度大多大于RSA钥模，因此算法库框架提供了两种padding模式，通过摘要提取消息的散列值再做签名。算法库框架中提供了签名验签相关的两种模式：PKCS1和PSS。下问对两种模式做详细描述： + - PKCS1: pkcs1padding V1.5是RSA加解密默认的填充方式，使用该模式时需要设置摘要（md）； + - PSS: PSS模式是RSA 算法的基础上叠加上一种填充算法，使用该签名算法时需要使用摘要(md)和掩码函数（mgf1_md）; +- **ECDSA** + + 椭圆曲线数字签名算法（ECDSA）是基于椭圆曲线密码（ECC）模拟数字签名算法（DSA）。相比普通的离散对数问题（DLP）和大数分解问题（IFP），椭圆曲线密码的单位比特强度要高于其他公钥体制。算法库框架提供了多种椭圆曲线及摘要算法组合的椭圆曲线数字签名算法（ECDSA）能力。 + +**密钥协商** + +- **ECDH** + + ECDH的全称是椭圆曲线迪菲-赫尔曼秘钥交换，是用来在一个非安全通道中建立起安全的共有加密资料，交换双方可以在不共享任何秘密的情况下协商出一个密钥。算法库框架基于开源算法库提供了多种椭圆曲线的ECDH能力。 + +**摘要** + +消息摘要MD算法是一种能将任意长度的输入消息，通过哈希算法生成长度固定的摘要的算法。消息摘要算法通过其不可逆的特性能被用于敏感信息的加密。消息摘要算法也被称为哈希算法或单向散列算法。 +在摘要算法相同时，生成的摘要值主要有下列特点： + +- 当输入消息相同时，生成摘要序列相同； +- 当输入消息的长度不一致时，生成摘要序列长度固定（摘要长度由算法决定）； +- 当输入消息不一致时，生成摘要序列几乎不会相同（依然存在相同概率，由摘要长度决定相同概率）； + +消息摘要算法主要分为三类：MD，SHA与MAC（详见HMAC章节） +MD算法包括MD2，MD4和MD5。 +SHA算法主要包括SHA1，SHA224，SHA256，SHA384，SHA512。 + +**消息验证码** + +HMAC（Hash-based Message Authentication Code）是一种基于密钥的消息认证码算法。HMAC通过指定摘要算法，以通信双方共享密钥与消息作为输入，生成消息认证码用于检验传递报文的完整性，HMAC生成的消息认证码为固定长度。HMAC在消息摘要算法的基础上增加了密钥的输入，确保了信息的正确性。 + +**随机数** + +随机数在加解密过程中主要用于临时会话密钥的生成与非对称加密算法中密钥的生成。随机数由硬件生成的硬件随机数生成器或由软件生成的伪随机数生成器进行生成。在加解密的场景中，安全随机数生成器需要具备随机性，不可预测性，与不可重现性。密码学安全伪随机数生成器CSPRNG（Cryptography Secure Random Number Generators）生成的随机数满足密码学安全伪随机性 + +- **内部状态**代表随机数生成器内存中的数值，当内部状态相同时，随机数生成器会生成固定的随机数序列 +- **种子**（seed）是一个用来对伪随机数的内部状态进行初始化的数据，随机数生成器通过种子来生成一系列的随机序列。 + + +## 约束与限制 + +- 算法库框架不支持多线程并发操作。 +- 算法库当前只支持OpenSSL。 + +### 密钥生成规格 + +**对称密钥生成规格** + +- 支持的对称密钥生成参数： + + |对称密钥算法|密钥长度（bit）|字符串参数| + |---|---|---| + |3DES|192|3DES192| + |AES|128|AES128| + |AES|192|AES192| + |AES|256|AES256| + + > **说明**：“字符串参数”是“对称密钥算法”和“密钥长度”拼接而成，用于在创建对称密钥生成器时，指定密钥规格。 + +**非对称密钥生成规格** +- **RSA密钥生成** + + 支持的非对称密钥生成参数： + + |非对称密钥类型|素数个数|字符串参数| + |---|---|---| + |RSA512|2|RSA512\|PRIMES_2| + |RSA768|2|RSA768\|PRIMES_2| + |RSA1024|2|RSA1024\|PRIMES_2| + |RSA1024|3|RSA1024\|PRIMES_3| + |RSA2048|2|RSA2048\|PRIMES_2| + |RSA2048|3|RSA2048\|PRIMES_3| + |RSA3072|2|RSA3072\|PRIMES_2| + |RSA3072|3|RSA3072\|PRIMES_3| + |RSA4096|2|RSA4096\|PRIMES_2| + |RSA4096|3|RSA4096\|PRIMES_3| + |RSA4096|4|RSA4096\|PRIMES_4| + |RSA8192|2|RSA8192\|PRIMES_2| + |RSA8192|3|RSA8192\|PRIMES_3| + |RSA8192|4|RSA8192\|PRIMES_4| + |RSA8192|5|RSA8192\|PRIMES_5| + + > **说明**：生成RSA非对称密钥时，默认素数为2，PRIMES_2参数可省略。 + +- **ECC密钥生成** + + 支持的非对称密钥生成参数： + + |非对称密钥算法|密钥长度| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + +### 加解密规格 + +**对称加解密** + +- 支持的对称加密算法： + + |对称加解密算法|分组模式| 字符串参数 | + |---|---|---| + |3DES|ECB|3DES192\|ECB\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|CBC|3DES192\|CBC\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|OFB|3DES192\|OFB\|[NoPadding\|PKCS5\|PKCS7]| + |3DES|CFB|3DES192\|CFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|ECB|AES[128\|192\|256]\|ECB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CBC|AES[128\|192\|256]\|CBC\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CTR|AES[128\|192\|256]\|CTR\|[NoPadding\|PKCS5\|PKCS7]| + |AES|OFB|AES[128\|192\|256]\|OFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CFB|AES[128\|192\|256]\|CFB\|[NoPadding\|PKCS5\|PKCS7]| + |AES|GCM|AES[128\|192\|256]\|GCM\|[NoPadding\|PKCS5\|PKCS7]| + |AES|CCM|AES[128\|192\|256]\|CCM\|[NoPadding\|PKCS5\|PKCS7]| + +> **说明：** +> +> 1. []中只能任选一项。 +> 2. “字符串参数”是“对称加解密算法（含密钥长度）”、“分组模式”、“填充模式”拼接而成，用于在创建对称加解密实例时，指定对称加解密算法规格。 + +**非对称RSA加解密** + +RSA加解密时，涉及三种填充模式：NoPadding, PKCS1和PKCS1_OAEP。 +- 使用NoPadding模式时可以指定的参数: + + |非对称密钥类型| 填充模式 | 字符串参数 | + |---|---|---| + |RSA512|NoPadding|RSA512\|NoPadding| + |RSA768|NoPadding|RSA768\|NoPadding| + |RSA1024|NoPadding|RSA1024\|NoPadding| + |RSA2048|NoPadding|RSA2048\|NoPadding| + |RSA3072|NoPadding|RSA3072\|NoPadding| + |RSA4096|NoPadding|RSA4096\|NoPadding| + |RSA8192|NoPadding|RSA8192\|NoPadding| + +- 使用PKCS1模式时可以指定的参数: + + |非对称密钥类型| 填充模式 | 字符串参数 | + |---|---|---| + |RSA512|PKCS1|RSA512\|PKCS1| + |RSA768|PKCS1|RSA768\|PKCS1| + |RSA1024|PKCS1|RSA1024\|PKCS1| + |RSA2048|PKCS1|RSA2048\|PKCS1| + |RSA3072|PKCS1|RSA3072\|PKCS1| + |RSA4096|PKCS1|RSA4096\|PKCS1| + |RSA8192|PKCS1|RSA8192\|PKCS1| + +- 使用PKCS1_OAEP模式时可以指定的参数： + > **说明：** + > + > 1.[]内的参数只能任选一项，非[]内的为固定值； + > 2.使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成字符串。 + > 例如："RSA2048|PKCS1_OAEP|SHA256|MGF1_SHA256" + + | 非对称密钥类型 | 填充模式 | 摘要 | 掩码摘要 | + |---|---|---|---| + |RSA512|PKCS1_OAEP|MD5| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224] + |RSA768|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA768|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA768|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA1024|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA2048|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512 ]| + |RSA8192|PKCS1_OAEP|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PKCS1_OAEP|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + + +### 签名验签规格 + +**RSA签名验签** + +RSA签名验签时，涉及两种填充模式：PKCS1和PSS。 +- 使用PKCS1模式时可以指定的参数: + + | 非对称密钥类型 | 填充模式 | 摘要 | 字符串参数 | + |---|---|---|---| + |RSA512|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384]|RSA512\|PKCS1\| [MD5\|SHA1\|SHA224\|SHA256\|SHA384]| + |RSA768|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA768\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA1024|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA1024\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA2048|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA2048\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA3072|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA3072\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA4096|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA4096\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + |RSA8192|PKCS1|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]|RSA8192\|PKCS1\|[MD5\|SHA1\|SHA224\|SHA256\|SHA384\|SHA512]| + +- 使用PSS模式时可以指定的参数： + > **说明：** + > + > 1.[]内的参数只能任选一项，非[]内的为固定值； + > 2.使用时请从表格中选择非对称密钥类型、填充模式、摘要、掩码摘要四个数据，用|拼接成字符串。 + > 例如："RSA2048|PSS|SHA256|MGF1_SHA256" + + | 非对称密钥类型 | 填充模式 | 摘要 | 掩码摘要 | + |---|---|---|---| + |RSA512|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA512|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]|RSA512\|PSS\|SHA256\|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA768|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA768|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA768|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256]| + |RSA768|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224]| + |RSA1024|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA1024|PSS|SHA512| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384]| + |RSA2048|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA2048|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA3072|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA4096|PSS|SHA512|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|MD5|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA1|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA224|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA256|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA384|[MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + |RSA8192|PSS|SHA512| [MGF1_MD5\|MGF1_SHA1\|MGF1_SHA224\|MGF1_SHA256\|MGF1_SHA384\|MGF1_SHA512]| + +**ECDSA签名验签** + +- 支持的ECDSA参数： + + |非对称密钥算法|支持种类| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| + +### 密钥协商规格 + +**ECDH** + +- 支持的ECDH参数： + + |非对称密钥算法|支持种类| + |---|---| + |ECC|ECC224| + |ECC|ECC256| + |ECC|ECC384| + |ECC|ECC521| + +### MD消息摘要算法规格 +- 加解密算法库框架当前支持的MD算法参数： + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| + |HASH|MD5| + +### HMAC消息认证码算法规格 +- 加解密算法库框架当前支持的HMAC算法参数： + + |摘要算法|支持种类| + |---|---| + |HASH|SHA1| + |HASH|SHA224| + |HASH|SHA256| + |HASH|SHA384| + |HASH|SHA512| diff --git a/zh-cn/application-dev/security/permission-verify-guidelines.md b/zh-cn/application-dev/security/permission-verify-guidelines.md index f36c97d7b88ad29230df4cd600d802e22b96c50a..0d514041edd27762f4fb5ced86121089bb1b3ddf 100644 --- a/zh-cn/application-dev/security/permission-verify-guidelines.md +++ b/zh-cn/application-dev/security/permission-verify-guidelines.md @@ -6,11 +6,14 @@ ## 接口说明 -以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-ability-context.md)。 +以下仅列举本指导使用的接口，更多说明可以查阅[API参考](../reference/apis/js-apis-abilityAccessCtrl)。 -| 接口名 | 描述 | -| ------------------------------------------------------------ | --------------------------------------------------- | -| verifyAccessToken(tokenID: number, permissionName: string): Promise<GrantStatus> | 校验指定的应用进程是否已被授权指定的权限。 | +checkAccessToken(tokenID: number, permissionName: Permissions): Promise<GrantStatus> + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | ------------------------------------------ | +| tokenID | number | 是 | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](../reference/apis/js-apis-bundleManager-applicationInfo.md)获得。 | +| permissionName | Permissions | 是 | 需要校验的权限名称，合法的权限名取值可在[系统权限定义列表](permission-list.md)中查询。 | ## 完整示例 @@ -20,8 +23,8 @@ 1. 获取调用者的身份标识：tokenId。 > **说明：**
> 获取访问者身份标识tokenId的方法 getCallingTokenId 可参考[API参考](../reference/apis/js-apis-rpc.md)。 -2. 待校验的权限名：ohos.permission.PERMISSION。 -3. 使用verifyAccessToken接口对当前调用者进行权限校验。 +2. 待校验的权限名：ohos.permission.ACCELEROMETER。 +3. 使用checkAccessToken接口对当前调用者进行权限校验。 4. 根据权限校验结果采取对应的措施。 ```js @@ -33,11 +36,14 @@ let callerTokenId = rpc.IPCSkeleton.getCallingTokenId(); console.log("RpcServer: getCallingTokenId result: " + callerTokenId); var atManager = abilityAccessCtrl.createAtManager(); - var result = await atManager.verifyAccessToken(tokenID, "ohos.permission.PERMISSION"); - if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { - // 允许访问者调用当前应用提供的接口 - } else { - // 不允许访问者调用当前应用提供的接口 + try { + atManager.checkAccessToken(callerTokenId, "ohos.permission.ACCELEROMETER").then((data) => { + console.log(`checkAccessToken success, data->${JSON.stringify(data)}`); + }).catch((err) => { + console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`); + }); + } catch(err) { + console.log(`catch err->${JSON.stringify(err)}`); } return true; } diff --git a/zh-cn/application-dev/windowmanager/application-window-fa.md b/zh-cn/application-dev/windowmanager/application-window-fa.md index f3eb1da1e329aa6f4a2df28236dc44fe8f2c56be..09c29be1c50dc55ec80c6a87c8f93a99e89c43e7 100644 --- a/zh-cn/application-dev/windowmanager/application-window-fa.md +++ b/zh-cn/application-dev/windowmanager/application-window-fa.md @@ -23,7 +23,7 @@ | 实例名 | 接口名 | 描述 | | -------- | -------- | -------- | | window静态方法 | createWindow(config: Configuration, callback: AsyncCallback\): void | 创建子窗口。
-`config`：创建窗口时的参数。 | -| window静态方法 | findWindow(id: string, callback: AsyncCallback<Window>): void | 查找`id`所对应的窗口。 | +| window静态方法 | findWindow(name: string): Window | 查找`name`所对应的窗口。 | | Window | SetUIContent(path: string, callback: AsyncCallback<void>): void | 为当前窗口加载具体页面内容。 | | Window | moveWindowTo(x: number, y: number, callback: AsyncCallback<void>): void | 移动当前窗口。 | | Window | setWindowBackgroundColor(color: string, callback: AsyncCallback<void>): void | 设置窗口的背景色。 | @@ -64,14 +64,11 @@ windowClass = data; }); // 方式二：查找得到子窗口。 - window.findWindow("subWindow", (err, data) => { - if (err.code) { - console.error('Failed to find the subWindow. Cause: ' + JSON.stringify(err)); - return; - } - console.info('Succeeded in finding subWindow. Data: ' + JSON.stringify(data)); - windowClass = data; - }); + try { + windowClass = window.findWindow('subWindow'); + } catch (exception) { + console.error('Failed to find the Window. Cause: ' + JSON.stringify(exception)); + } ``` 2. 设置子窗口属性。 @@ -156,7 +153,7 @@ let mainWindowClass = null; // 获取主窗口。 - window.getLastWindow((err, data) => { + window.getLastWindow(this.context,(err, data) => { if (err.code) { console.error('Failed to get the subWindow. Cause: ' + JSON.stringify(err)); return; diff --git a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md index 767d07500b7bf43df2acc1d5a86a2ad6c83ee1ee..285a917f36d6e4491b333cb619c81e572acb3497 100644 --- a/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md +++ b/zh-cn/device-dev/subsystems/subsys-dfx-hisysevent-logging-config.md @@ -31,20 +31,20 @@ - 每个事件名称可定义多个参数，同一个事件名称内部的参数不能重名，每个事件名称有且只有一个名称为__BASE的参数，此参数字段组成如表1，其它自定义参数，具体字段组成如表2。 **表1** __BASE参数字段说明 - | 字段名称 | 描述 | + | 字段名称 | 描述 | | -------- | -------- | - | type | 字段说明：必选字段，用来标识该事件名称的类型。
取值范围：
- FAULT：错误类型。
- STATISTIC：统计类型。
- SECURITY：安全性。
- BEHAVIOR：用户行为。 | - | level | 字段说明：必选字段，用来标识该事件名称的级别。
取值范围：
- CRITICAL：严重。
- MINOR：一般。 | - | tag | 字段说明：可选字段，用来标识该事件名称的标签。
定义规则：
- 最多可同时定义5个标签，标签之间使用空格来分隔。
- 单个标签最多包含16个字符，字符范围[a-zA-Z0-9] | - | desc | 字段说明：必选字段，用来对该事件名称进行描述。
定义规则：
- 至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _] | + | type | 字段说明：必选字段，用来标识该事件名称的类型。
取值范围：
- FAULT：错误类型。
- STATISTIC：统计类型。
- SECURITY：安全性。
- BEHAVIOR：用户行为。 | + | level | 字段说明：必选字段，用来标识该事件名称的级别。
取值范围：
- CRITICAL：严重。
- MINOR：一般。 | + | tag | 字段说明：可选字段，用来标识该事件名称的标签。
定义规则：
- 最多可同时定义5个标签，标签之间使用空格来分隔。
- 单个标签最多包含16个字符，字符范围[a-zA-Z0-9] | + | desc | 字段说明：必选字段，用来对该事件名称进行描述。
定义规则：
- 至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _] | **表2** 自定义参数字段说明 - | 字段名称 | 描述 | + | 字段名称 | 描述 | | -------- | -------- | - | type | 字段说明：必选字段，用来标识该参数的类型。
取值范围：
- BOOL
- UINT8
- UINT16
- INT32
- UINT32
- UINT64
- FLOAT
- DOUBLE
- STRING | - | arrsize | 字段作用：可选字段，用来标识数组类型参数的长度。
取值范围：
- 1~100 | - | desc | 字段作用：必选字段，用来对该参数进行描述。
定义规则：
- 至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _] | + | type | 字段说明：必选字段，用来标识该参数的类型。
取值范围：
- BOOL
- INT8
- UINT8
- INT16
- UINT16
- INT32
- UINT32
- INT64
- UINT64
- FLOAT
- DOUBLE
- STRING | + | arrsize | 字段作用：可选字段，用来标识数组类型参数的长度。
取值范围：
- 1~100 | + | desc | 字段作用：必选字段，用来对该参数进行描述。
定义规则：
- 至少包含3个字符，最多包含128个字符，字符范围[a-zA-Z0-9 _] | ## 编写yaml文件 @@ -74,7 +74,7 @@ - EVENT_NAMEA被定义成错误类型的严重事件，该事件包含类型为字符串类型的NAME1参数、字符串类型的NAME2参数及无符号短整型类型的NAME3参数，可以通过事件领域MODULEA和事件名称EVENT_NAMEA对其进行[实时订阅](../subsystems/subsys-dfx-hisysevent-listening.md)。 - EVENT_NAMEB被定义成统计类型的一般事件，EVENT_NAMEB包含类型为无符号短整型类型的NAME1参数及整型类型的NAME2参数。因为EVENT_NAMEB在__BASE参数中定义了名称为tag1和tag2的两个事件标签，所以不仅可以通过事件领域MODULEA和事件名称EVENT_NAMEB对其进行[实时订阅](../subsystems/subsys-dfx-hisysevent-listening.md)，所以还可以通过事件标签对该事件进行实时订阅。 - + ``` ########################################## # the hisysevent definition for module a # @@ -102,7 +102,7 @@ 在bundle.json文件中通过hisysevent_config属性完成yaml文件的路径指定： - + ``` { "name": "@ohos/moduel_a", @@ -153,14 +153,14 @@ - 全量编译： - 全量编译整个系统，会将所有组件配置的yaml文件中的配置进行汇总，正常完成系统编译后，指定目录下就会生成hisysevent.def文件。 - + ``` cd 工程根目录的绝对路径 ./build --product-name ``` - 全量编译生成的hisysevent.def文件可以通过以下命令获取： - + ``` cd 工程根目录的绝对路径 find out -name hisysevent.def -type f @@ -169,7 +169,7 @@ - 单文件编译： 也可以只编译单个组件的yaml文件，命令如下： - + ``` cd 工程根目录的绝对路径 ./build/ohos/hisysevent/gen_def_from_all_yaml.py --yaml-list --def-path @@ -177,10 +177,10 @@ **表3** 单文件编译参数说明 - | 选项名称 | 描述 | + | 选项名称 | 描述 | | -------- | -------- | - | --yaml-list | 指定需要编译的yaml文件路径列表，多个yaml文件路径之间用空格分隔。 | - | --def-path | 指定编译生成的hisysevent.def文件的生成路径。 | + | --yaml-list | 指定需要编译的yaml文件路径列表，多个yaml文件路径之间用空格分隔。 | + | --def-path | 指定编译生成的hisysevent.def文件的生成路径。 | ### 打点及查询定义的事件 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.7/changelogs-arkui.md b/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.7/changelogs-arkui.md new file mode 100644 index 0000000000000000000000000000000000000000..1dbe17d99b7290362d3982cc6834c753c9281e9a --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_3.2.10.7/changelogs-arkui.md @@ -0,0 +1,39 @@ +# arkui子系统ChangeLog + +## cl.arkui.1 getInspectorTree接口返回值从string修改为Object。 + +**变更影响** + +3.2.10.7之前使用getInspectorTree接口的代码需要适配 + +**关键的接口/组件变更** + +getInspectorTree接口返回值从string修改为Object + +**适配指导** + +将getInspectorTree返回值作为string使用的代码需要修改，比如以下示例代码： + +```typescript +console.info(getInspectorTree()) +``` + +需要修改成 + +```typescript +console.info(JSON.stringify(getInspectorTree())) +``` + +## cl.arkui.2 废弃GridItem的forceRebuild属性 + +**变更影响** + +无，该属性无作用 + +**关键的接口/组件变更** + +GridItem的forceRebuild属性废弃 + +**适配指导** + +如有使用可以直接删除，不影响GridItem功能 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-accesstoken.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-accesstoken.md new file mode 100644 index 0000000000000000000000000000000000000000..1a8369c1e143394448444df7a4f70b78322e1625 --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelog-accesstoken.md @@ -0,0 +1,33 @@ +# 程序访问控制子系统ChangeLog + +OpenHarmony 4.0.3.2 版本相较于OpenHarmony 之前的版本，程序访问控制子系统的API变更如下。 + +## cl.access_token.1 getPermissionUsedRecords命名变更 + +接口getPermissionUsedRecords由于命名规范问题，名称变更为getPermissionUsedRecord。 + +**变更影响** + +接口getPermissionUsedRecords，在4.0.3.3版本及后续版本中无法继续正常使用。 + +**关键的接口/组件变更** + +- 涉及接口 + + function getPermissionUsedRecords + +- 变更前： + + ```ts + function getPermissionUsedRecords + ``` + +- 变更后： + + ```ts + function getPermissionUsedRecord + ``` + +**适配指导** + +请使用getPermissionUsedRecord替换getPermissionUsedRecords \ No newline at end of file diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-arkui.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-arkui.md new file mode 100644 index 0000000000000000000000000000000000000000..216b033d74cf4c965009132e2b067f10c77ea22e --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-arkui.md @@ -0,0 +1,39 @@ +# arkui子系统ChangeLog + +## cl.arkui.1 getInspectorTree接口返回值从string修改为Object。 + +**变更影响** + +4.0.3.2之前使用getInspectorTree接口的代码需要适配 + +**关键的接口/组件变更** + +getInspectorTree接口返回值从string修改为Object + +**适配指导** + +将getInspectorTree返回值作为string使用的代码需要修改，比如以下示例代码： + +```typescript +console.info(getInspectorTree()) +``` + +需要修改成 + +```typescript +console.info(JSON.stringify(getInspectorTree())) +``` + +## cl.arkui.2 废弃GridItem的forceRebuild属性 + +**变更影响** + +无，该属性无作用 + +**关键的接口/组件变更** + +GridItem的forceRebuild属性废弃 + +**适配指导** + +如有使用可以直接删除，不影响GridItem功能 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-bundlemanager.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-bundlemanager.md new file mode 100644 index 0000000000000000000000000000000000000000..fce3cada2d5907f575c7b33f52c8a347d45647cb --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-bundlemanager.md @@ -0,0 +1,27 @@ +# 包管理子系统ChangeLog + +## cl.bundlemanager.1 包管理删除@ohos.bundle.bundleManager.d.ts中的getAbilityIcon接口，可以使用@ohos.resourceManager.d.ts中的getMediaContent替换。 + +包管理删除[@ohos.bundle.bundleManager.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.bundle.bundleManager.d.ts)中的getAbilityIcon接口，可以使用[@ohos.resourceManager.d.ts](https://gitee.com/openharmony/interface_sdk-js/blob/master/api/@ohos.resourceManager.d.ts)中的getMediaContent替换。 + +**变更影响**
+使用之前已发布的API 9各beta版本且使用到了getAbilityIcon接口的，需要改为使用getMediaContent接口。 + +**关键的接口/组件变更**
+删除@ohos.bundle.bundleManager.d.ts中的getAbilityIcon接口。 + +**适配指导**
+使用@ohos.bundle.bundleManager.d.ts下面的getAbilityIcon，需要修改为@ohos.resourceManager.d.ts中的getMediaContent。需要提前获取到图标的资源ID值，可参考该接口的[使用指导](../../../application-dev/reference/apis/js-apis-resource-manager.md#getmediacontent9)。 + +## cl.bundlemanager.2 包管理新增202错误码 + +包管理系统新增202错误码，非系统应用调用api9及之后包管理提供的系统api，将返回错误202。 + +**变更影响**
+非系统应用调用api9及之后包管理提供的系统api，将返回错误202。 + +**关键的接口/组件变更**
+所有包管理提供的api9及之后的系统api，非系统应用调用将返回错误202。 + +**适配指导**
+不影响已开发的程序，无需适配。 \ No newline at end of file diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-filemanagement.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-filemanagement.md new file mode 100644 index 0000000000000000000000000000000000000000..6aa36f7193fef03a5a022a0572963d7997cbb14a --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-filemanagement.md @@ -0,0 +1,23 @@ +# 文件管理子系统ChangeLog + +## cl.filemanagement.1 Filter类型模块变更 + +**变更影响** + +基于此前版本开发的应用，需注意d.ts位置的变更及import模块名的变更。现Filter类型变更至@ohos.file.fs模块下。Filter类型具体属性不变。 + +**关键接口/组件变更** + +原Filter类型在模块@ohos.fileio下，通过以下方式import: + +```js +import Filter from '@ohos.fileio'; +``` + +**适配指导** + +现Filter类型在模块@ohos.file.fs，通过以下方式import: + +```js +import Filter from '@ohos.file.fs'; +``` diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-sensor.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-sensor.md similarity index 96% rename from zh-cn/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-sensor.md rename to zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-sensor.md index bfec2426ed62dc23cd29c88d180f6e1960d7f73b..1b38e923b6c4aac5f7a560b1bcd86bd77e6dcb30 100644 --- a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.2.3/changelogs-sensor.md +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.3.2/changelogs-sensor.md @@ -1,49 +1,49 @@ -# 泛sensor子系统ChangeLog - -## cl.ability.1 Sensor接口中venderName属性名称变更，更改为vendorName。 - -venderName为错别字，更正为vendorName。 - -**变更影响** - -该venderName属性无法再使用，请使用新增属性vendorName替换。 - -**关键的接口/组件变更** - -- 变更前： - -```js - interface Sensor { - sensorName:string; /**< Sensor name */ - venderName:string; /**< Sensor vendor version */ - firmwareVersion:string; /**< Sensor firmware version */ - hardwareVersion:string; /**< Sensor hardware version */ - sensorId:number; /**< Sensor type ID, {@code SensorType} */ - maxRange:number; /**< Maximum measurement range of the sensor */ - minSamplePeriod:number; /**< Minimum sample period allowed, in ns */ - maxSamplePeriod:number; /**< maximum sample period allowed, in ns */ - precision:number; /**< Sensor accuracy */ - power:number; /**< Sensor power */ - } -``` - -- 变更后： - -```js - interface Sensor { - sensorName:string; /**< Sensor name */ - vendorName:string; /**< Sensor vendor version */ - firmwareVersion:string; /**< Sensor firmware version */ - hardwareVersion:string; /**< Sensor hardware version */ - sensorId:number; /**< Sensor type ID, {@code SensorType} */ - maxRange:number; /**< Maximum measurement range of the sensor */ - minSamplePeriod:number; /**< Minimum sample period allowed, in ns */ - maxSamplePeriod:number; /**< maximum sample period allowed, in ns */ - precision:number; /**< Sensor accuracy */ - power:number; /**< Sensor power */ - } -``` - -**适配指导** - -该venderName属性删除无法再使用，请使用新增属性vendorName替换。 +# 泛sensor子系统ChangeLog + +## cl.ability.1 Sensor接口中venderName属性名称变更，更改为vendorName。 + +venderName为错别字，更正为vendorName。 + +**变更影响** + +该venderName属性无法再使用，请使用新增属性vendorName替换。 + +**关键的接口/组件变更** + +- 变更前： + +```js + interface Sensor { + sensorName:string; /**< Sensor name */ + venderName:string; /**< Sensor vendor version */ + firmwareVersion:string; /**< Sensor firmware version */ + hardwareVersion:string; /**< Sensor hardware version */ + sensorId:number; /**< Sensor type ID, {@code SensorType} */ + maxRange:number; /**< Maximum measurement range of the sensor */ + minSamplePeriod:number; /**< Minimum sample period allowed, in ns */ + maxSamplePeriod:number; /**< maximum sample period allowed, in ns */ + precision:number; /**< Sensor accuracy */ + power:number; /**< Sensor power */ + } +``` + +- 变更后： + +```js + interface Sensor { + sensorName:string; /**< Sensor name */ + vendorName:string; /**< Sensor vendor version */ + firmwareVersion:string; /**< Sensor firmware version */ + hardwareVersion:string; /**< Sensor hardware version */ + sensorId:number; /**< Sensor type ID, {@code SensorType} */ + maxRange:number; /**< Maximum measurement range of the sensor */ + minSamplePeriod:number; /**< Minimum sample period allowed, in ns */ + maxSamplePeriod:number; /**< maximum sample period allowed, in ns */ + precision:number; /**< Sensor accuracy */ + power:number; /**< Sensor power */ + } +``` + +**适配指导** + +该venderName属性删除无法再使用，请使用新增属性vendorName替换。 \ No newline at end of file