diff --git a/en/application-dev/file-management/app-file-upload-download.md b/en/application-dev/file-management/app-file-upload-download.md index e95ba1dc8794404b4b79162356434017b57d08e4..a73fc9568cc03e791074866c20dc963b028cdb55 100644 --- a/en/application-dev/file-management/app-file-upload-download.md +++ b/en/application-dev/file-management/app-file-upload-download.md @@ -48,7 +48,7 @@ try { .then((uploadTask) => { uploadTask.on('complete', (taskStates) => { for (let i = 0; i < taskStates.length; i++) { - console.info(`upload complete taskState: ${JSON.stringify(taskStates[i])}'); + console.info(`upload complete taskState: ${JSON.stringify(taskStates[i])}`); } }); }) diff --git a/en/application-dev/file-management/figures/application-file-directory-structure.png b/en/application-dev/file-management/figures/application-file-directory-structure.png index 2ccc93278cb82842e21730194772a530324dcba7..6dd9d88ba37bd2a74a9d8a03fe8d61a378ce768e 100644 Binary files a/en/application-dev/file-management/figures/application-file-directory-structure.png and b/en/application-dev/file-management/figures/application-file-directory-structure.png differ diff --git a/en/application-dev/napi/figures/rawfile1.png b/en/application-dev/napi/figures/rawfile1.png index 9f29f7875cd983f967b7a3b27b5898bfce76c9f3..8e3ea5f2844a8124dee1bd3132b1cc86c70b8f64 100644 Binary files a/en/application-dev/napi/figures/rawfile1.png and b/en/application-dev/napi/figures/rawfile1.png differ diff --git a/en/application-dev/napi/rawfile-guidelines.md b/en/application-dev/napi/rawfile-guidelines.md index ccd517b40d77362b94b76001cf921f134a0cf237..555ef7fafdb5bf830d1f17ed7f73f50424c2edf4 100644 --- a/en/application-dev/napi/rawfile-guidelines.md +++ b/en/application-dev/napi/rawfile-guidelines.md @@ -1,313 +1,43 @@ -# Raw File Development +# RawFile Development ## When to Use -This document describes how to use the native Rawfile APIs to manage raw file directories and files in OpenHarmony. You can use Rawfile APIs to perform operations such as traversing the file list, opening, searching for, reading, and closing raw files. +This document describes how to use Native Rawfile APIs to manage the directories and files in the **rawfile** directory in OpenHarmony. You can use the APIs to perform operations, such as traversing a directory and opening, searching for, reading, and closing a file in the the **rawfile** directory. ## Available APIs -| Name | Description | -| :----------------------------------------------------------- | :--------------------------------------- | -| NativeResourceManager *OH_ResourceManager_InitNativeResourceManager(napi_env env, napi_value jsResMgr) | Initializes the native resource manager. | -| RawDir *OH_ResourceManager_OpenRawDir(const NativeResourceManager *mgr, const char *dirName) | Opens a raw file directory. | -| int OH_ResourceManager_GetRawFileCount(RawDir *rawDir) | Obtains the number of raw files in the specified directory.| -| const char *OH_ResourceManager_GetRawFileName(RawDir *rawDir, int index) | Obtains the name of a raw file. | -| RawFile *OH_ResourceManager_OpenRawFile(const NativeResourceManager *mgr, const char *fileName) | Opens a raw file. | -| long OH_ResourceManager_GetRawFileSize(RawFile *rawFile) | Obtains the size of a raw file. | -| int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence) | Seeks a read/write position in a raw file based on the specified offset. | -| long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile) | Obtains the offset. | -| int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length) | Reads a raw file. | -| void OH_ResourceManager_CloseRawFile(RawFile *rawFile) | Closes a raw file to release resources. | -| void OH_ResourceManager_CloseRawDir(RawDir *rawDir) | Closes a raw file directory to release resources. | -| bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor) | Obtains the file descriptor (FD) of a raw file. | -| bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor) | Releases the FD of a raw file. | -| void OH_ResourceManager_ReleaseNativeResourceManager(NativeResourceManager *resMgr) | Releases the native resource manager. | - -## How to Develop - - The following describes how to obtain the raw file list, raw file content, and raw file descriptor on the JavaScript side as an example. - -1. Create a project. - -![Creating a C++ application](figures/rawfile1.png) - -2. Add dependencies. - -After a project is created, the **cpp** directory is created under the project. The directory contains files such as **libentry/index.d.ts**, **hello.cpp**, and **CMakeLists.txt**. - -1. Open the **src/main/cpp/CMakeLists.txt** file, and add **librawfile.z.so** and **libhilog_ndk.z.so** to **target_link_libraries**. - - ```c++ - target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so librawfile.z.so) - ``` - -2. Open the **src/main/cpp/types/libentry/index.d.ts** file, and declare the application functions **getFileList**, **getRawFileContent**, and **getRawFileDescriptor**. - - ```c++ - import resourceManager from '@ohos.resourceManager'; - export const getFileList: (resmgr: resourceManager.ResourceManager, path: string) => Array; - export const getRawFileContent: (resmgr: resourceManager.ResourceManager, path: string) => Uint8Array; - export const getRawFileDescriptor: (resmgr: resourceManager.ResourceManager, path: string) => resourceManager.RawFileDescriptor; - ``` - -3. Modify the source file. - -1. Open the **src/main/cpp/hello.cpp** file. During initialization, the file maps the external JavaScript APIs **getFileList**, **getRawFileContent**, and **getRawFileDescriptor** to C++ native APIs **GetFileList**, **GetRawFileContent**, and **GetRawFileDescriptor**. - - ```c++ - EXTERN_C_START - static napi_value Init(napi_env env, napi_value exports) - { - napi_property_descriptor desc[] = { - { "getFileList", nullptr, GetFileList, nullptr, nullptr, nullptr, napi_default, nullptr }, - { "getRawFileContent", nullptr, GetRawFileContent, nullptr, nullptr, nullptr, napi_default, nullptr }, - { "getRawFileDescriptor", nullptr, GetRawFileDescriptor, nullptr, nullptr, nullptr, napi_default, nullptr } - }; - - napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); - return exports; - } - EXTERN_C_END - ``` - -2. Add the three functions to the **src/main/cpp/hello.cpp** file. - - ```c++ - static napi_value GetFileList(napi_env env, napi_callback_info info) - static napi_value GetRawFileContent(napi_env env, napi_callback_info info) - static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) - ``` - -3. Obtain JavaScript resource objects from the **hello.cpp** file, and convert them to native resource objects. Then, call the native APIs to obtain the raw file list, raw file content, and raw file descriptor {fd, offset, length}. The sample code is as follows: - - ```c++ - // Example 1: Use GetFileList to obtain the raw file list. - static napi_value GetFileList(napi_env env, napi_callback_info info) - { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest Begin"); - size_t requireArgc = 3; - size_t argc = 2; - napi_value argv[2] = { nullptr }; - // Obtain arguments of the native API. - napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); - - // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. - NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); - - // Obtain argv[1], which specifies the relative path of the raw file. - size_t strSize; - char strBuf[256]; - napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); - std::string dirName(strBuf, strSize); - - // Obtain the corresponding rawDir pointer object. - RawDir* rawDir = OH_ResourceManager_OpenRawDir(mNativeResMgr, dirName.c_str()); - - // Obtain the number of files and folders in rawDir. - int count = OH_ResourceManager_GetRawFileCount(rawDir); - - // Traverse rawDir to obtain the list of file names and save it. - std::vector tempArray; - for(int i = 0; i < count; i++) { - std::string filename = OH_ResourceManager_GetRawFileName(rawDir, i); - tempArray.emplace_back(filename); - } - - napi_value fileList; - napi_create_array(env, &fileList); - for (size_t i = 0; i < tempArray.size(); i++) { - napi_value jsString; - napi_create_string_utf8(env, tempArray[i].c_str(), NAPI_AUTO_LENGTH, &jsString); - napi_set_element(env, fileList, i, jsString); - } - - // Close the rawDir pointer object. - OH_ResourceManager_CloseRawDir(rawDir); - OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); - return fileList; - } - - // Example 2: Use rawDir pointer object to obtain the content of the raw file. - napi_value CreateJsArrayValue(napi_env env, std::unique_ptr &data, long length) - { - napi_value buffer; - napi_status status = napi_create_external_arraybuffer(env, data.get(), length, - [](napi_env env, void *data, void *hint) { - delete[] static_cast(data); - }, nullptr, &buffer); - if (status != napi_ok) { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create external array buffer"); - return nullptr; - } - napi_value result = nullptr; - status = napi_create_typedarray(env, napi_uint8_array, length, buffer, 0, &result); - if (status != napi_ok) { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create media typed array"); - return nullptr; - } - data.release(); - return result; - } - static napi_value GetRawFileContent(napi_env env, napi_callback_info info) - { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "GetFileContent Begin"); - size_t requireArgc = 3; - size_t argc = 2; - napi_value argv[2] = { nullptr }; - // Obtain arguments of the native API. - napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); - - // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. - NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); - size_t strSize; - char strBuf[256]; - napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); - std::string filename(strBuf, strSize); - - // Obtain the raw file pointer object. - RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); - if (rawFile != nullptr) { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); - } - // Obtain the size of the raw file and apply for memory. - long len = OH_ResourceManager_GetRawFileSize(rawFile); - std::unique_ptr data= std::make_unique(len); - // Read the raw file. - int res = OH_ResourceManager_ReadRawFile(rawFile, data.get(), len); - // Close the raw file pointer object. - OH_ResourceManager_CloseRawFile(rawFile); - OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); - // Convert the native object to a JavaScript object. - return CreateJsArrayValue(env, data, len); - } - - // Example 3: Use GetRawFileDescriptor to obtain the FD of the raw file. - napi_value createJsFileDescriptor(napi_env env, RawFileDescriptor &descriptor) - { - napi_value result; - napi_status status = napi_create_object(env, &result); - if (status != napi_ok) { - return result; - } - - napi_value fd; - status = napi_create_int32(env, descriptor.fd, &fd); - if (status != napi_ok) { - return result; - } - status = napi_set_named_property(env, result, "fd", fd); - if (status != napi_ok) { - return result; - } - - napi_value offset; - status = napi_create_int64(env, descriptor.start, &offset); - if (status != napi_ok) { - return result; - } - status = napi_set_named_property(env, result, "offset", offset); - if (status != napi_ok) { - return result; - } - - napi_value length; - status = napi_create_int64(env, descriptor.length, &length); - if (status != napi_ok) { - return result; - } - status = napi_set_named_property(env, result, "length", length); - if (status != napi_ok) { - return result; - } - return result; - } - static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) - { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest GetRawFileDescriptor Begin"); - size_t requireArgc = 3; - size_t argc = 2; - napi_value argv[2] = { nullptr }; - // Obtain arguments of the native API. - napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); - - napi_valuetype valueType; - napi_typeof(env, argv[0], &valueType); - // Obtain the native resourceManager object. - NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); - size_t strSize; - char strBuf[256]; - napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); - std::string filename(strBuf, strSize); - // Obtain the raw file pointer object. - RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); - if (rawFile != nullptr) { - OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); - } - // Obtain the FD of the raw file, that is, RawFileDescriptor {fd, offset, length}. - RawFileDescriptor descriptor; - OH_ResourceManager_GetRawFileDescriptor(rawFile, descriptor); - // Close the raw file pointer object. - OH_ResourceManager_CloseRawFile(rawFile); - OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); - // Convert the native object to a JavaScript object. - return createJsFileDescriptor(env,descriptor); - } - ``` - -4. Call APIs on the JavaScript side. - -1. Open **src\main\ets\pages\index.ets**, and import **libentry.so**. - -2. Obtain the JavaScript resource object, that is, **resourceManager**. - -3. Call **getFileList**, that is, the native API declared in **src/main/cpp/types/libentry/index.d.ts**. When calling the API, pass the JavaScript resource object and the relative path of the raw file. The sample code is as follows: - - ```js - import hilog from '@ohos.hilog'; - import testNapi from 'libentry.so' // Import the libentry.so file. - @Entry - @Component - struct Index { - @State message: string = 'Hello World' - private resmgr = getContext().resourceManager; // Obtain the JavaScript resource object. - build() { - Row() { - Column() { - Text(this.message) - .fontSize(50) - .fontWeight(FontWeight.Bold) - .onClick(() => { - hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO); - let rawfilelist = testNapi.getFileList(this.resmgr, ""); // Pass the JavaScript resource object and the relative path of the raw file. - console.log("rawfilelist" + rawfilelist); - let rawfileContet = testNapi.getRawFileContent(this.resmgr, "rawfile1.txt"); - console.log("rawfileContet" + rawfileContet); - let rawfileDescriptor = testNapi.getRawFileDescriptor(this.resmgr, "rawfile1.txt"); - console.log("getRawFileDescriptor" + rawfileDescriptor.fd, rawfileDescriptor.offset, rawfileDescriptor.length); - }) - } - .width('100%') - } - .height('100%') - } - } - ``` - -## Using C++ Functions +| API | Description | +| :----------------------------------------------------------- | :----------------------------------------------------------- | +| NativeResourceManager *OH_ResourceManager_InitNativeResourceManager(napi_env env, napi_value jsResMgr) | Initializes a Native resource manager instance. | +| RawDir *OH_ResourceManager_OpenRawDir(const NativeResourceManager *mgr, const char *dirName) | Opens a directory in the **rawfile** directory. | +| int OH_ResourceManager_GetRawFileCount(RawDir *rawDir) | Obtains the number of files in the specified directory. | +| const char *OH_ResourceManager_GetRawFileName(RawDir *rawDir, int index) | Obtains the name of a file in the **rawfile** directory. | +| RawFile *OH_ResourceManager_OpenRawFile(const NativeResourceManager *mgr, const char *fileName) | Opens a file in the **rawfile** directory. | +| long OH_ResourceManager_GetRawFileSize(RawFile *rawFile) | Obtains the size of a file in the **rawfile** directory. | +| int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence) | Seeks for the read/write position in a file in the **rawfile** directory based on the specified offset. | +| long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile) | Obtains the offset of a file. | +| int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, size_t length) | Reads data from a file in the **rawfile** directory. | +| void OH_ResourceManager_CloseRawFile(RawFile *rawFile) | Closes a file in the **rawfile** directory to release resources. | +| void OH_ResourceManager_CloseRawDir(RawDir *rawDir) | Closes a directory in the **rawfile** directory to release resources. | +| bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor) | Obtains the file descriptor (FD) of a file in the **rawfile** directory. | +| bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor) | Releases the FD of a file in the **rawfile** directory. | +| void OH_ResourceManager_ReleaseNativeResourceManager(NativeResourceManager *resMgr) | Releases a Native resource manager instance. | + +## Functions 1. Call **OH_ResourceManager_OpenRawDir** to obtain a **RawDir** instance based on the **NativeResourceManager** instance. ```c++ RawDir* rawDir = OH_ResourceManager_OpenRawDir(nativeResourceManager, path.c_str()); ``` - -2. Call **OH_ResourceManager_GetRawFileCount** to obtain the total number of raw files in the directory based on the **RawDir** instance. + +2. Call **OH_ResourceManager_GetRawFileCount** to obtain the total number of files in the directory based on the **RawDir** instance. ```c++ int count = OH_ResourceManager_GetRawFileCount(rawDir); ``` - -3. Call **OH_ResourceManager_GetRawFileName** to obtain the name of the raw file with the specified index. + +3. Call **OH_ResourceManager_GetRawFileName** to obtain the name of a file based on the specified index. ```c++ for (int index = 0; index < count; index++) { @@ -315,19 +45,19 @@ After a project is created, the **cpp** directory is created under the project. } ``` -4. Call **OH_ResourceManager_OpenRawFile** to obtain a **RawFile** instance with the specified file name. +4. Call **OH_ResourceManager_OpenRawFile** to open a **RawFile** instance with the specified file name. ```c++ RawFile* rawFile = OH_ResourceManager_OpenRawFile(nativeResourceManager, fileName.c_str()); ``` - -5. Call **OH_ResourceManager_GetRawFileSize** to obtain the size of the raw file. + +5. Call **OH_ResourceManager_GetRawFileSize** to obtain the size of the file. ```c++ long rawFileSize = OH_ResourceManager_GetRawFileSize(rawFile); ``` -6. Call **OH_ResourceManager_SeekRawFile** to seek a read/write position in the raw file based on the specified offset. +6. Call **OH_ResourceManager_SeekRawFile** to seek for the read/write position in the file based on the specified offset. ```c++ int position = OH_ResourceManager_SeekRawFile(rawFile, 10, 0); @@ -335,13 +65,13 @@ After a project is created, the **cpp** directory is created under the project. int position = OH_ResourceManager_SeekRawFile(rawFile, -10, 2); ``` -7. Call **OH_ResourceManager_GetRawFileOffset** to obtain the raw file offset. +7. Call **OH_ResourceManager_GetRawFileOffset** to obtain the file offset. ```c++ long rawFileOffset = OH_ResourceManager_GetRawFileOffset(rawFile) ``` -8. Call **OH_ResourceManager_ReadRawFile** to read the raw file. +8. Call **OH_ResourceManager_ReadRawFile** to read a file. ```c++ std::unique_ptr mediaData = std::make_unique(rawFileSize); @@ -354,27 +84,314 @@ After a project is created, the **cpp** directory is created under the project. OH_ResourceManager_CloseRawFile(rawFile); ``` -10. Call **OH_ResourceManager_CloseRawDir** to close the raw file directory. +10. Call **OH_ResourceManager_CloseRawDir** to close the file directory. ```c++ OH_ResourceManager_CloseRawDir(rawDir); ``` -11. Call **OH_ResourceManager_GetRawFileDescriptor** to obtain the FD of the raw file. +11. Call **OH_ResourceManager_GetRawFileDescriptor** to obtain the FD of the file. ```c++ RawFileDescriptor descriptor; bool result = OH_ResourceManager_GetRawFileDescriptor(rawFile, descriptor); ``` -12. Call **OH_ResourceManager_ReleaseRawFileDescriptor** to release the FD of the raw file. +12. Call **OH_ResourceManager_ReleaseRawFileDescriptor** to release the FD of the file. ```c++ OH_ResourceManager_ReleaseRawFileDescriptor(descriptor); ``` -13. Call **OH_ResourceManager_ReleaseNativeResourceManager** to release the native resource manager. +13. Call **OH_ResourceManager_ReleaseNativeResourceManager** to release the Native resource manager. ```c++ OH_ResourceManager_ReleaseNativeResourceManager(nativeResourceManager); ``` + +## How to Develop + +The following describes how to obtain the file list in the **rawfile** directory, file content, and FD {fd, offset, length} on the JavaScript side as an example. + +1. Create a project. + + ![Creating a C++ application](figures/rawfile1.png) + +2. Add dependencies. + + After the project is created, the **cpp** directory is created under the project. The directory contains files such as **libentry/index.d.ts**, **hello.cpp**, and **CMakeLists.txt**. + + 1. Open the **src/main/cpp/CMakeLists.txt** file, and add **librawfile.z.so** and **libhilog_ndk.z.so** to **target_link_libraries**. + + ``` + target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so librawfile.z.so) + ``` + + + + 2. Open the **src/main/cpp/types/libentry/index.d.ts** file, and declare the application functions **getFileList**, **getRawFileContent**, and **getRawFileDescriptor**. + + ```c++ + import resourceManager from '@ohos.resourceManager'; + export const getFileList: (resmgr: resourceManager.ResourceManager, path: string) => Array; + export const getRawFileContent: (resmgr: resourceManager.ResourceManager, path: string) => Uint8Array; + export const getRawFileDescriptor: (resmgr: resourceManager.ResourceManager, path: string) => resourceManager.RawFileDescriptor; + ``` + + + +3. Modify the source file. + + 1. Open the **src/main/cpp/hello.cpp** file. During initialization, the file maps the external JavaScript APIs **getFileList**, **getRawFileContent**, and **getRawFileDescriptor** to C++ native APIs **GetFileList**, **GetRawFileContent**, and **GetRawFileDescriptor**. + + ```c++ + EXTERN_C_START + static napi_value Init(napi_env env, napi_value exports) + { + napi_property_descriptor desc[] = { + { "getFileList", nullptr, GetFileList, nullptr, nullptr, nullptr, napi_default, nullptr }, + { "getRawFileContent", nullptr, GetRawFileContent, nullptr, nullptr, nullptr, napi_default, nullptr }, + { "getRawFileDescriptor", nullptr, GetRawFileDescriptor, nullptr, nullptr, nullptr, napi_default, nullptr } + }; + + napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); + return exports; + } + EXTERN_C_END + ``` + + + + 2. Add the three functions to the **src/main/cpp/hello.cpp** file. + + ```c++ + static napi_value GetFileList(napi_env env, napi_callback_info info) + static napi_value GetRawFileContent(napi_env env, napi_callback_info info) + static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) + ``` + + + + 3. Obtain JavaScript resource objects from the **hello.cpp** file, and convert them to Native resource objects. Then, call the Native APIs to obtain the file list, file content, and FD {fd, offset, length}. + + The sample code is as follows: + + ```c++ + // Example 1: Use GetFileList to obtain the raw file list. + static napi_value GetFileList(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + + // Obtain argv[1], which specifies the relative path of the raw file. + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string dirName(strBuf, strSize); + + // Obtain the corresponding rawDir pointer object. + RawDir* rawDir = OH_ResourceManager_OpenRawDir(mNativeResMgr, dirName.c_str()); + + // Obtain the number of files and folders in rawDir. + int count = OH_ResourceManager_GetRawFileCount(rawDir); + + // Traverse rawDir to obtain the list of file names and save it. + std::vector tempArray; + for(int i = 0; i < count; i++) { + std::string filename = OH_ResourceManager_GetRawFileName(rawDir, i); + tempArray.emplace_back(filename); + } + + napi_value fileList; + napi_create_array(env, &fileList); + for (size_t i = 0; i < tempArray.size(); i++) { + napi_value jsString; + napi_create_string_utf8(env, tempArray[i].c_str(), NAPI_AUTO_LENGTH, &jsString); + napi_set_element(env, fileList, i, jsString); + } + + // Close the rawDir pointer object. + OH_ResourceManager_CloseRawDir(rawDir); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + return fileList; + } + + // Example 2: Use rawDir pointer object to obtain the content of the raw file. + napi_value CreateJsArrayValue(napi_env env, std::unique_ptr &data, long length) + { + napi_value buffer; + napi_status status = napi_create_external_arraybuffer(env, data.get(), length, + [](napi_env env, void *data, void *hint) { + delete[] static_cast(data); + }, nullptr, &buffer); + if (status != napi_ok) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create external array buffer"); + return nullptr; + } + napi_value result = nullptr; + status = napi_create_typedarray(env, napi_uint8_array, length, buffer, 0, &result); + if (status != napi_ok) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "Failed to create media typed array"); + return nullptr; + } + data.release(); + return result; + } + static napi_value GetRawFileContent(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "GetFileContent Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + // Obtain argv[0], which specifies conversion of the JavaScript resource object (that is, OH_ResourceManager_InitNativeResourceManager) to a native object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string filename(strBuf, strSize); + + // Obtain the raw file pointer object. + RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); + if (rawFile != nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); + } + // Obtain the size of the raw file and apply for memory. + long len = OH_ResourceManager_GetRawFileSize(rawFile); + std::unique_ptr data= std::make_unique(len); + // Read the raw file. + int res = OH_ResourceManager_ReadRawFile(rawFile, data.get(), len); + // Close the rawDir pointer object. + OH_ResourceManager_CloseRawFile(rawFile); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + // Convert the native object to a JavaScript object. + return CreateJsArrayValue(env, data, len); + } + + // Example 3: Use GetRawFileDescriptor to obtain the FD of the raw file. + napi_value createJsFileDescriptor(napi_env env, RawFileDescriptor &descriptor) + { + napi_value result; + napi_status status = napi_create_object(env, &result); + if (status != napi_ok) { + return result; + } + + napi_value fd; + status = napi_create_int32(env, descriptor.fd, &fd); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "fd", fd); + if (status != napi_ok) { + return result; + } + + napi_value offset; + status = napi_create_int64(env, descriptor.start, &offset); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "offset", offset); + if (status != napi_ok) { + return result; + } + + napi_value length; + status = napi_create_int64(env, descriptor.length, &length); + if (status != napi_ok) { + return result; + } + status = napi_set_named_property(env, result, "length", length); + if (status != napi_ok) { + return result; + } + return result; + } + static napi_value GetRawFileDescriptor(napi_env env, napi_callback_info info) + { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "NDKTest GetRawFileDescriptor Begin"); + size_t requireArgc = 3; + size_t argc = 2; + napi_value argv[2] = { nullptr }; + // Obtain arguments of the native API. + napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); + + napi_valuetype valueType; + napi_typeof(env, argv[0], &valueType); + // Obtain the native resourceManager object. + NativeResourceManager *mNativeResMgr = OH_ResourceManager_InitNativeResourceManager(env, argv[0]); + size_t strSize; + char strBuf[256]; + napi_get_value_string_utf8(env, argv[1], strBuf, sizeof(strBuf), &strSize); + std::string filename(strBuf, strSize); + // Obtain the raw file pointer object. + RawFile *rawFile = OH_ResourceManager_OpenRawFile(mNativeResMgr, filename.c_str()); + if (rawFile != nullptr) { + OH_LOG_Print(LOG_APP, LOG_ERROR, GLOBAL_RESMGR, tag, "OH_ResourceManager_OpenRawFile success"); + } + // Obtain the FD of the raw file, that is, RawFileDescriptor {fd, offset, length}. + RawFileDescriptor descriptor; + OH_ResourceManager_GetRawFileDescriptor(rawFile, descriptor); + // Close the rawDir pointer object. + OH_ResourceManager_CloseRawFile(rawFile); + OH_ResourceManager_ReleaseNativeResourceManager(mNativeResMgr); + // Convert the native object to a JavaScript object. + return createJsFileDescriptor(env,descriptor); + } + ``` + + + +4. Call JavaScript APIs. + + 1. Open **src\main\ets\pages\index.ets**, and import **libentry.so**. + + 2. Obtain the JavaScript resource object, that is, **resourceManager**. + + 3. Call **getFileList**, that is, the Native API declared in **src/main/cpp/types/libentry/index.d.ts**. When calling the API, pass in the JavaScript resource object and the relative path of the file. + + The sample code is as follows: + + ```js + import hilog from '@ohos.hilog'; + import testNapi from 'libentry.so' // Import the libentry.so file. + @Entry + @Component + struct Index { + @State message: string = 'Hello World' + private resmgr = getContext().resourceManager; // Obtain the JavaScript resource object. + build() { + Row() { + Column() { + Text(this.message) + .fontSize(50) + .fontWeight(FontWeight.Bold) + .onClick(() => { + hilog.isLoggable(0x0000, 'testTag', hilog.LogLevel.INFO); + let rawfilelist = testNapi.getFileList(this.resmgr, ""); // Pass the JavaScript resource object and the relative path of the raw file. + console.log("rawfilelist" + rawfilelist); + let rawfileContet = testNapi.getRawFileContent(this.resmgr, "rawfile1.txt"); + console.log("rawfileContet" + rawfileContet); + let rawfileDescriptor = testNapi.getRawFileDescriptor(this.resmgr, "rawfile1.txt"); + console.log("getRawFileDescriptor" + rawfileDescriptor.fd, rawfileDescriptor.offset, rawfileDescriptor.length); + }) + } + .width('100%') + } + .height('100%') + } + } + ``` + + + diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index 6bb9b3075d7fd7787a943e44fea8a1968e413551..5d3b4b8ea4893b3784b0589e63ff12f808fc82ff 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -301,6 +301,7 @@ - [@ohos.nfc.controller (Standard NFC)](js-apis-nfcController.md) - [@ohos.nfc.tag (Standard NFC Tags)](js-apis-nfcTag.md) - [@ohos.rpc (RPC)](js-apis-rpc.md) + - [@ohos.secureElement (SE Channel Management)](js-apis-secureElement.md) - [@ohos.wifiManager (WLAN) (Recommended)](js-apis-wifiManager.md) - [@ohos.wifiManagerExt (WLAN Extension) (Recommended)](js-apis-wifiManagerExt.md) - [@ohos.wifi (WLAN) (To Be Deprecated Soon)](js-apis-wifi.md) diff --git a/en/application-dev/reference/apis/js-apis-huks.md b/en/application-dev/reference/apis/js-apis-huks.md index 11c2f8d4ea97dbc0149b68b6eea7b873ba8eeefb..911af6e5872df7747d837dd656ae63a259a991ad 100644 --- a/en/application-dev/reference/apis/js-apis-huks.md +++ b/en/application-dev/reference/apis/js-apis-huks.md @@ -17,7 +17,7 @@ import huks from '@ohos.security.huks' Defines the **param** in the **properties** array of **options** used in the APIs. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name| Type | Mandatory| Description | | ------ | ----------------------------------- | ---- | ------------ | @@ -28,7 +28,7 @@ Defines the **param** in the **properties** array of **options** used in the API Defines the **options** used in the APIs. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Type | Mandatory| Description | | ---------- | ----------------- | ---- | ------------------------ | @@ -39,7 +39,7 @@ Defines the **options** used in the APIs. Defines the HUKS handle structure. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Type | Mandatory| Description | | --------- | ---------- | ---- | ---------------------------------------------------- | @@ -48,9 +48,9 @@ Defines the HUKS handle structure. ## HuksReturnResult9+ -Defines the **HuksResult** structure. +Defines the **HuksResult** struct. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core @@ -67,7 +67,7 @@ generateKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ Generates a key. This API uses an asynchronous callback to return the result. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core **Parameters** @@ -142,7 +142,7 @@ generateKeyItem(keyAlias: string, options: HuksOptions) : Promise\ Generates a key. This API uses a promise to return the result. Because the key is always protected in an trusted environment (such as a TEE), the promise does not return the key content. It returns only the information indicating whether the API is successfully called. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -216,7 +216,7 @@ deleteKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ Deletes a key. This API uses a promise to return the result. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -317,7 +317,7 @@ getSdkVersion(options: HuksOptions) : string Obtains the SDK version of the current system. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -347,7 +347,7 @@ importKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ Imports a key in plaintext. This API uses a promise to return the result. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -524,7 +524,7 @@ attestKeyItem(keyAlias: string, options: HuksOptions, callback: AsyncCallback\ Checks whether a key exists. This API uses a promise to return the result. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -1432,7 +1432,7 @@ let keyAlias = 'keyAlias'; let emptyOptions = { properties: [] }; -await huks.isKeyItemExist(keyAlias, emptyOptions).then((data) => { +huks.isKeyItemExist(keyAlias, emptyOptions).then((data) => { promptAction.showToast({ message: "keyAlias: " + keyAlias +"is existed! ", duration: 500, @@ -1451,7 +1451,7 @@ initSession(keyAlias: string, options: HuksOptions, callback: AsyncCallback\; Aborts a key operation. This API uses a promise to return the result. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2087,7 +2087,7 @@ Enumerates the error codes. For details about the error codes, see [KUKS Error Codes](../errorcodes/errorcode-huks.md). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value| Description | | ---------------------------------------------- | -------- |--------------------------- | @@ -2114,25 +2114,25 @@ For details about the error codes, see [KUKS Error Codes](../errorcodes/errorcod Enumerates the key purposes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | ------------------------ | ---- | -------------------------------- | -| HUKS_KEY_PURPOSE_ENCRYPT | 1 | Used to encrypt the plaintext.| -| HUKS_KEY_PURPOSE_DECRYPT | 2 | Used to decrypt the cipher text.| -| HUKS_KEY_PURPOSE_SIGN | 4 | Used for signing. | -| HUKS_KEY_PURPOSE_VERIFY | 8 | Used to verify the signature. | -| HUKS_KEY_PURPOSE_DERIVE | 16 | Used to derive a key. | -| HUKS_KEY_PURPOSE_WRAP | 32 | Used for an encrypted export. | -| HUKS_KEY_PURPOSE_UNWRAP | 64 | Used for an encrypted import. | -| HUKS_KEY_PURPOSE_MAC | 128 | Used to generate a message authentication code (MAC). | -| HUKS_KEY_PURPOSE_AGREE | 256 | Used for key agreement. | +| HUKS_KEY_PURPOSE_ENCRYPT | 1 | Used to encrypt the plaintext.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_KEY_PURPOSE_DECRYPT | 2 | Used to decrypt the cipher text.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_KEY_PURPOSE_SIGN | 4 | Used for signing.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_VERIFY | 8 | Used to verify the signature.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_DERIVE | 16 | Used to derive a key.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_WRAP | 32 | Used for an encrypted export.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_UNWRAP | 64 | Used for an encrypted import.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_MAC | 128 | Used to generate a message authentication code (MAC).
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_KEY_PURPOSE_AGREE | 256 | Used for key agreement.
**System capability**: SystemCapability.Security.Huks.Extension| ## HuksKeyDigest Enumerates the digest algorithms. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ---------------------- | ---- | ---------------------------------------- | @@ -2149,89 +2149,89 @@ Enumerates the digest algorithms. Enumerates the padding algorithms. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | ---------------------- | ---- | ---------------------------------------- | -| HUKS_PADDING_NONE | 0 | No padding algorithm| -| HUKS_PADDING_OAEP | 1 | Optimal Asymmetric Encryption Padding (OAEP)| -| HUKS_PADDING_PSS | 2 | Probabilistic Signature Scheme (PSS)| -| HUKS_PADDING_PKCS1_V1_5 | 3 | Public Key Cryptography Standards (PKCS) #1 v1.5| -| HUKS_PADDING_PKCS5 | 4 | PKCS #5| -| HUKS_PADDING_PKCS7 | 5 | PKCS #7| +| HUKS_PADDING_NONE | 0 | No padding algorithm
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_PADDING_OAEP | 1 | Optimal Asymmetric Encryption Padding (OAEP)
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_PADDING_PSS | 2 | Probabilistic Signature Scheme (PSS)
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_PADDING_PKCS1_V1_5 | 3 | Public Key Cryptography Standards (PKCS) #1 v1.5
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_PADDING_PKCS5 | 4 | PKCS #5
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_PADDING_PKCS7 | 5 | PKCS #7
**System capability**: SystemCapability.Security.Huks.Core| ## HuksCipherMode Enumerates the cipher modes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | ------------- | ---- | --------------------- | -| HUKS_MODE_ECB | 1 | Electronic Code Block (ECB) mode| -| HUKS_MODE_CBC | 2 | Cipher Block Chaining (CBC) mode| -| HUKS_MODE_CTR | 3 | Counter (CTR) mode| -| HUKS_MODE_OFB | 4 | Output Feedback (OFB) mode| -| HUKS_MODE_CCM | 31 | Counter with CBC-MAC (CCM) mode| -| HUKS_MODE_GCM | 32 | Galois/Counter (GCM) mode| +| HUKS_MODE_ECB | 1 | Electronic Code Block (ECB) mode
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_MODE_CBC | 2 | Cipher Block Chaining (CBC) mode
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_MODE_CTR | 3 | Counter (CTR) mode
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_MODE_OFB | 4 | Output Feedback (OFB) mode
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_MODE_CCM | 31 | Counter with CBC-MAC (CCM) mode
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_MODE_GCM | 32 | Galois/Counter (GCM) mode
**System capability**: SystemCapability.Security.Huks.Core| ## HuksKeySize Enumerates the key sizes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | ---------------------------------- | ---- | ------------------------------------------ | -| HUKS_RSA_KEY_SIZE_512 | 512 | Rivest-Shamir-Adleman (RSA) key of 512 bits | -| HUKS_RSA_KEY_SIZE_768 | 768 | RSA key of 768 bits | -| HUKS_RSA_KEY_SIZE_1024 | 1024 | RSA key of 1024 bits | -| HUKS_RSA_KEY_SIZE_2048 | 2048 | RSA key of 2048 bits | -| HUKS_RSA_KEY_SIZE_3072 | 3072 | RSA key of 3072 bits | -| HUKS_RSA_KEY_SIZE_4096 | 4096 | RSA key of 4096 bits | -| HUKS_ECC_KEY_SIZE_224 | 224 | Elliptic Curve Cryptography (ECC) key of 224 bits | -| HUKS_ECC_KEY_SIZE_256 | 256 | ECC key of 256 bits | -| HUKS_ECC_KEY_SIZE_384 | 384 | ECC key of 384 bits | -| HUKS_ECC_KEY_SIZE_521 | 521 | ECC key of 521 bits | -| HUKS_AES_KEY_SIZE_128 | 128 | Advanced Encryption Standard (AES) key of 128 bits | -| HUKS_AES_KEY_SIZE_192 | 192 | AES key of 192 bits | -| HUKS_AES_KEY_SIZE_256 | 256 | AES key of 256 bits | -| HUKS_AES_KEY_SIZE_512 | 512 | AES key of 512 bits | -| HUKS_CURVE25519_KEY_SIZE_256 | 256 | Curve25519 key of 256 bits| -| HUKS_DH_KEY_SIZE_2048 | 2048 | Diffie-Hellman (DH) key of 2048 bits | -| HUKS_DH_KEY_SIZE_3072 | 3072 | DH key of 3072 bits | -| HUKS_DH_KEY_SIZE_4096 | 4096 | DH key of 4096 bits | -| HUKS_SM2_KEY_SIZE_2569+ | 256 | ShangMi2 (SM2) key of 256 bits | -| HUKS_SM4_KEY_SIZE_1289+ | 128 | ShangMi4 (SM4) key of 128 bits | +| HUKS_RSA_KEY_SIZE_512 | 512 | Rivest-Shamir-Adleman (RSA) key of 512 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_RSA_KEY_SIZE_768 | 768 | RSA key of 768 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_RSA_KEY_SIZE_1024 | 1024 | RSA key of 1024 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_RSA_KEY_SIZE_2048 | 2048 | RSA key of 2048 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_RSA_KEY_SIZE_3072 | 3072 | RSA key of 3072 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_RSA_KEY_SIZE_4096 | 4096 | RSA key of 4096 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ECC_KEY_SIZE_224 | 224 | Elliptic Curve Cryptography (ECC) key of 224 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ECC_KEY_SIZE_256 | 256 | ECC key of 256 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ECC_KEY_SIZE_384 | 384 | ECC key of 384 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ECC_KEY_SIZE_521 | 521 | ECC key of 521 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_AES_KEY_SIZE_128 | 128 | Advanced Encryption Standard (AES) key of 128 bits
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_AES_KEY_SIZE_192 | 192 | AES key of 192 bits
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_AES_KEY_SIZE_256 | 256 | AES key of 256 bits
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_AES_KEY_SIZE_512 | 512 | AES key of 512 bits
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_CURVE25519_KEY_SIZE_256 | 256 | Curve25519 key of 256 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_DH_KEY_SIZE_2048 | 2048 | Diffie-Hellman (DH) key of 2048 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_DH_KEY_SIZE_3072 | 3072 | DH key of 3072 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_DH_KEY_SIZE_4096 | 4096 | DH key of 4096 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_SM2_KEY_SIZE_2569+ | 256 | ShangMi2 (SM2) key of 256 bits
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_SM4_KEY_SIZE_1289+ | 128 | ShangMi4 (SM4) key of 128 bits
**System capability**: SystemCapability.Security.Huks.Extension| ## HuksKeyAlg Enumerates the key algorithms. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | ------------------------- | ---- | --------------------- | -| HUKS_ALG_RSA | 1 | RSA | -| HUKS_ALG_ECC | 2 | ECC | -| HUKS_ALG_DSA | 3 | DSA | -| HUKS_ALG_AES | 20 | AES | -| HUKS_ALG_HMAC | 50 | HMAC | -| HUKS_ALG_HKDF | 51 | HKDF | -| HUKS_ALG_PBKDF2 | 52 | PBKDF2 | -| HUKS_ALG_ECDH | 100 | ECDH | -| HUKS_ALG_X25519 | 101 | X25519 | -| HUKS_ALG_ED25519 | 102 | ED25519| -| HUKS_ALG_DH | 103 | DH | -| HUKS_ALG_SM29+ | 150 | SM2 | -| HUKS_ALG_SM39+ | 151 | SM3 | -| HUKS_ALG_SM49+ | 152 | SM4 | +| HUKS_ALG_RSA | 1 | RSA
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_ECC | 2 | ECC
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_DSA | 3 | DSA
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_AES | 20 | AES
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_ALG_HMAC | 50 | HMAC
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_HKDF | 51 | HKDF
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_PBKDF2 | 52 | PBKDF2
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_ECDH | 100 | ECDH
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_X25519 | 101 | X25519
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_ED25519 | 102 | ED25519
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_DH | 103 | DH
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_SM29+ | 150 | SM2
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_SM39+ | 151 | SM3
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_ALG_SM49+ | 152 | SM4
**System capability**: SystemCapability.Security.Huks.Extension| ## HuksKeyGenerateType Enumerates the key generation types. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------ | ---- | ---------------- | @@ -2243,7 +2243,7 @@ Enumerates the key generation types. Enumerates the key generation modes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | -------------------------- | ---- | ------------------------------------ | @@ -2256,20 +2256,20 @@ Enumerates the key generation modes. Enumerates the key storage modes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | -------------------------------------------- | ---- | ------------------------------ | -| HUKS_STORAGE_TEMP | 0 | The key is managed locally. | -| HUKS_STORAGE_PERSISTENT | 1 | The key is managed by the HUKS service.| -| HUKS_STORAGE_ONLY_USED_IN_HUKS10+ | 2 | The key is stored only in the HUKS. | -| HUKS_STORAGE_KEY_EXPORT_ALLOWED10+ | 3 | The key is exported from the HUKS and is not stored.| +| HUKS_STORAGE_TEMP(deprecated) | 0 | The key is managed locally.
**NOTE**: This tag is discarded since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_STORAGE_PERSISTENT(deprecated) | 1 | The key is managed by the HUKS service.
**NOTE**: This tag is discarded since API version 10. No substitute is provided because this tag is not used in key management. In key derivation scenarios, use **HUKS_STORAGE_ONLY_USED_IN_HUKS** or **HUKS_STORAGE_KEY_EXPORT_ALLOWED**.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_STORAGE_ONLY_USED_IN_HUKS10+ | 2 | The key derived from the master key is stored in the HUKS and managed by the HUKS.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_STORAGE_KEY_EXPORT_ALLOWED10+ | 3 | The key derived from the master key is exported to the service, and not managed by the HUKS.
**System capability**: SystemCapability.Security.Huks.Extension| ## HuksSendType Enumerates the tag transfer modes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | -------------------- | ---- | ----------------- | @@ -2280,7 +2280,7 @@ Enumerates the tag transfer modes. Enumerates the algorithm suites used for importing an encrypted key. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ---------------------------------------------- | ---- | ----------------------------------------------------- | @@ -2291,7 +2291,7 @@ Enumerates the algorithm suites used for importing an encrypted key. Enumerates the types of keys to import. By default, a public key is imported. This field is not required when a symmetric key is imported. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------- | ---- | ------------------------------ | @@ -2303,7 +2303,7 @@ Enumerates the types of keys to import. By default, a public key is imported. Th Enumerates the **salt_len** types to set when PSS padding is used in RSA signing or signature verification. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------------------ | ---- | ---------------------------- | @@ -2314,7 +2314,7 @@ Enumerates the **salt_len** types to set when PSS padding is used in RSA signing Enumerates the user authentication types. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------- | ---- | ------------------------- | @@ -2326,7 +2326,7 @@ Enumerates the user authentication types. Enumerates the access control types. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | --------------------------------------- | ---- | ------------------------------------------------ | @@ -2337,7 +2337,7 @@ Enumerates the access control types. Enumerates the types of the challenges generated when a key is used. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------- | ---- | ------------------------------ | @@ -2349,7 +2349,7 @@ Enumerates the types of the challenges generated when a key is used. Enumerates the positions of the 8-byte valid value in a custom challenge generated. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------- | ---- | ------------------------------ | @@ -2362,7 +2362,7 @@ Enumerates the positions of the 8-byte valid value in a custom challenge generat Defines the signature type of the key generated or imported. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension | Name | Value | Description | | ------------------------------ | ---- | ------------------------------------------------------------ | @@ -2372,7 +2372,7 @@ Defines the signature type of the key generated or imported. Enumerates the tag data types. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | --------------------- | ------- | --------------------------------------- | @@ -2387,95 +2387,95 @@ Enumerates the tag data types. Enumerates the tags used to invoke parameters. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Core | Name | Value | Description | | -------------------------------------------- | ---------------------------------------- | -------------------------------------- | -| HUKS_TAG_INVALID | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0 | Invalid tag. | -| HUKS_TAG_ALGORITHM | HuksTagType.HUKS_TAG_TYPE_UINT \| 1 | Algorithm. | -| HUKS_TAG_PURPOSE | HuksTagType.HUKS_TAG_TYPE_UINT \| 2 | Purpose of the key. | -| HUKS_TAG_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 3 | Key size. | -| HUKS_TAG_DIGEST | HuksTagType.HUKS_TAG_TYPE_UINT \| 4 | Digest algorithm. | -| HUKS_TAG_PADDING | HuksTagType.HUKS_TAG_TYPE_UINT \| 5 | Padding algorithm. | -| HUKS_TAG_BLOCK_MODE | HuksTagType.HUKS_TAG_TYPE_UINT \| 6 | Cipher mode. | -| HUKS_TAG_KEY_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 7 | Key type. | -| HUKS_TAG_ASSOCIATED_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 8 | Associated authentication data. | -| HUKS_TAG_NONCE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 9 | Field for key encryption and decryption. | -| HUKS_TAG_IV | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10 | IV. | -| HUKS_TAG_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 11 | Information generated during key derivation. | -| HUKS_TAG_SALT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 12 | Salt value used for key derivation. | -| HUKS_TAG_PWD | HuksTagType.HUKS_TAG_TYPE_BYTES \| 13 | Password used for key derivation. | -| HUKS_TAG_ITERATION | HuksTagType.HUKS_TAG_TYPE_UINT \| 14 | Number of iterations for key derivation. | -| HUKS_TAG_KEY_GENERATE_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 15 | Key generation type. | -| HUKS_TAG_DERIVE_MAIN_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 16 | Main key for key derivation. | -| HUKS_TAG_DERIVE_FACTOR | HuksTagType.HUKS_TAG_TYPE_BYTES \| 17 | Factor for key derivation. | -| HUKS_TAG_DERIVE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 18 | Type of the algorithm used for key derivation. | -| HUKS_TAG_AGREE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 19 | Type of the algorithm used for key agreement. | -| HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 20 | Public key alias used in key agreement. | -| HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 21 | Private key alias used in key agreement. | -| HUKS_TAG_AGREE_PUBLIC_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22 | Public key used in key agreement. | -| HUKS_TAG_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23 | Key alias. | -| HUKS_TAG_DERIVE_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 24 | Size of the derived key. | -| HUKS_TAG_IMPORT_KEY_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 25 | Type of the imported key. | -| HUKS_TAG_UNWRAP_ALGORITHM_SUITE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 26 | Algorithm suite required for encrypted imports. | -| HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|29 | Storage type of the derived key or agreed key.| -| HUKS_TAG_RSA_PSS_SALT_LEN_TYPE10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|30 | Type of the **rsa_pss_salt_length**.| -| HUKS_TAG_ACTIVE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module. | -| HUKS_TAG_ORIGINATION_EXPIRE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module. | -| HUKS_TAG_USAGE_EXPIRE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module. | -| HUKS_TAG_CREATION_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 204 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module. | -| HUKS_TAG_ALL_USERS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 301 | Reserved. | -| HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | ID of the user to which the key belongs. | -| HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | Reserved. | -| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | User authentication type. For details, see [HuksUserAuthType](#huksuserauthtype9). This parameter must be set together with [HuksAuthAccessType](#huksauthaccesstype9). You can set a maximum of two user authentication types at a time. For example, if **HuksAuthAccessType** is **HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL**, you can set two of **HKS_USER_AUTH_TYPE_FACE**, **HKS_USER_AUTH_TYPE_FINGERPRINT**, and **HKS_USER_AUTH_TYPE_FACE\**.| HKS_USER_AUTH_TYPE_FINGERPRINT | -| HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | Timeout period of an authentication token. | -| HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | Used to pass in the authentication token. | -| HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | Access control type. For details, see [HuksAuthAccessType](#huksauthaccesstype9). This parameter must be set together with [HuksUserAuthType](#huksuserauthtype9).| -| HUKS_TAG_KEY_SECURE_SIGN_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 308 | Signature type of the key generated or imported.| -| HUKS_TAG_CHALLENGE_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 309 | Type of the challenge generated for a key. For details, see [HuksChallengeType](#hukschallengetype9).| -| HUKS_TAG_CHALLENGE_POS9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 310 | Position of the 8-byte valid value in a custom challenge. For details, see [HuksChallengePosition](#hukschallengeposition9).| -| HUKS_TAG_KEY_AUTH_PURPOSE10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|311 | Key authentication purpose.| -| HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | Challenge value used in the attestation. | -| HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | Application ID used in the attestation. | -| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | Brand of the device. | -| HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | ID of the device. | -| HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | Product name of the device. | -| HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | SN of the device. | -| HUKS_TAG_ATTESTATION_ID_IMEI | HuksTagType.HUKS_TAG_TYPE_BYTES \| 507 | International mobile equipment identity (IMEI) of the device. | -| HUKS_TAG_ATTESTATION_ID_MEID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 508 | Mobile equipment identity (MEID) of the device. | -| HUKS_TAG_ATTESTATION_ID_MANUFACTURER | HuksTagType.HUKS_TAG_TYPE_BYTES \| 509 | Manufacturer of the device. | -| HUKS_TAG_ATTESTATION_ID_MODEL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 510 | Device model. | -| HUKS_TAG_ATTESTATION_ID_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 511 | Key alias used in the attestation. | -| HUKS_TAG_ATTESTATION_ID_SOCID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 512 | System-on-a-chip (SoCID) of the device. | -| HUKS_TAG_ATTESTATION_ID_UDID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 513 | Unique device identifier (UDID) of the device. | -| HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 514 | Security level used in the attestation. | -| HUKS_TAG_ATTESTATION_ID_VERSION_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 515 | Version information used in the attestation. | -| HUKS_TAG_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1001 | Whether to use the alias passed in during key generation.| -| HUKS_TAG_KEY_STORAGE_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1002 | Key storage mode. | -| HUKS_TAG_IS_ALLOWED_WRAP | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1003 | Reserved. | -| HUKS_TAG_KEY_WRAP_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1004 | Reserved. | -| HUKS_TAG_KEY_AUTH_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1005 | Reserved. | -| HUKS_TAG_KEY_ROLE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1006 | Reserved. | -| HUKS_TAG_KEY_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1007 | Flag of the key. | -| HUKS_TAG_IS_ASYNCHRONIZED | HuksTagType.HUKS_TAG_TYPE_UINT \| 1008 | Reserved. | -| HUKS_TAG_SECURE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1009 | Reserved. | -| HUKS_TAG_SECURE_KEY_UUID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1010 | Reserved. | -| HUKS_TAG_KEY_DOMAIN | HuksTagType.HUKS_TAG_TYPE_UINT \| 1011 | Reserved. | -| HUKS_TAG_PROCESS_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10001 | Process name. | -| HUKS_TAG_PACKAGE_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10002 | Reserved. | -| HUKS_TAG_ACCESS_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10003 | Reserved. | -| HUKS_TAG_USES_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10004 | Reserved. | -| HUKS_TAG_CRYPTO_CTX | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10005 | Reserved. | -| HUKS_TAG_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10006 | Reserved. | -| HUKS_TAG_KEY_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10007 | Key version. | -| HUKS_TAG_PAYLOAD_LEN | HuksTagType.HUKS_TAG_TYPE_UINT \| 10008 | Reserved. | -| HUKS_TAG_AE_TAG | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10009 | Used to pass in the AEAD in GCM mode. | -| HUKS_TAG_IS_KEY_HANDLE | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10010 | Reserved. | -| HUKS_TAG_OS_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10101 | OS version. | -| HUKS_TAG_OS_PATCHLEVEL | HuksTagType.HUKS_TAG_TYPE_UINT \| 10102 | OS patch level. | -| HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | Reserved. | -| HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | Reserved. | -| HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | Reserved. | +| HUKS_TAG_INVALID | HuksTagType.HUKS_TAG_TYPE_INVALID \| 0 | Invalid tag.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_ALGORITHM | HuksTagType.HUKS_TAG_TYPE_UINT \| 1 | Algorithm.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_PURPOSE | HuksTagType.HUKS_TAG_TYPE_UINT \| 2 | Purpose of the key.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 3 | Key size.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_DIGEST | HuksTagType.HUKS_TAG_TYPE_UINT \| 4 | Digest algorithm.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_PADDING | HuksTagType.HUKS_TAG_TYPE_UINT \| 5 | Padding algorithm.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_BLOCK_MODE | HuksTagType.HUKS_TAG_TYPE_UINT \| 6 | Cipher mode.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_KEY_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 7 | Key type.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_ASSOCIATED_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 8 | Associated authentication data.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_NONCE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 9 | Field for key encryption and decryption.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_IV | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10 | IV.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 11 | Information generated during key derivation.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_SALT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 12 | Salt value used for key derivation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_PWD | HuksTagType.HUKS_TAG_TYPE_BYTES \| 13 | Password used for key derivation.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_ITERATION | HuksTagType.HUKS_TAG_TYPE_UINT \| 14 | Number of iterations for key derivation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_GENERATE_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 15 | Key generation type.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_DERIVE_MAIN_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 16 | Main key for key derivation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_DERIVE_FACTOR | HuksTagType.HUKS_TAG_TYPE_BYTES \| 17 | Factor for key derivation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_DERIVE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 18 | Type of the algorithm used for key derivation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AGREE_ALG | HuksTagType.HUKS_TAG_TYPE_UINT \| 19 | Type of the algorithm used for key agreement.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 20 | Public key alias used in key agreement.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 21 | Private key alias used in key agreement.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AGREE_PUBLIC_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 22 | Public key used in key agreement.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 23 | Key alias.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_DERIVE_KEY_SIZE | HuksTagType.HUKS_TAG_TYPE_UINT \| 24 | Size of the derived key.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_IMPORT_KEY_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 25 | Type of the imported key.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_UNWRAP_ALGORITHM_SUITE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 26 | Algorithm suite required for encrypted imports.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|29 | Storage type of the derived key or agreed key.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_RSA_PSS_SALT_LEN_TYPE10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|30 | Type of the **rsa_pss_salt_length**.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ACTIVE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 201 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ORIGINATION_EXPIRE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 202 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_USAGE_EXPIRE_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 203 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_CREATION_DATETIME(deprecated) | HuksTagType.HUKS_TAG_TYPE_ULONG \| 204 | Parameter originally reserved for certificate management. It is deprecated because certificate management is no longer implemented in this module.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_ALL_USERS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 301 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_USER_ID | HuksTagType.HUKS_TAG_TYPE_UINT \| 302 | ID of the user to which the key belongs.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_NO_AUTH_REQUIRED | HuksTagType.HUKS_TAG_TYPE_BOOL \| 303 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_USER_AUTH_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 304 | User authentication type. For details, see [HuksUserAuthType](#huksuserauthtype9). This parameter must be set together with [HuksAuthAccessType](#huksauthaccesstype9). You can set a maximum of two user authentication types at a time. For example, if **HuksAuthAccessType** is **HKS_SECURE_ACCESS_INVALID_NEW_BIO_ENROLL**, you can set two of **HKS_USER_AUTH_TYPE_FACE**, **HKS_USER_AUTH_TYPE_FINGERPRINT**, and **HKS_USER_AUTH_TYPE_FACE\**.| HKS_USER_AUTH_TYPE_FINGERPRINT
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AUTH_TIMEOUT | HuksTagType.HUKS_TAG_TYPE_UINT \| 305 | Timeout period of an authentication token.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AUTH_TOKEN | HuksTagType.HUKS_TAG_TYPE_BYTES \| 306 | Used to pass in the authentication token.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_AUTH_ACCESS_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 307 | Access control type. For details, see [HuksAuthAccessType](#huksauthaccesstype9). This parameter must be set together with [HuksUserAuthType](#huksuserauthtype9).
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_SECURE_SIGN_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 308 | Signature type of the key generated or imported.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_CHALLENGE_TYPE9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 309 | Type of the challenge generated for a key. For details, see [HuksChallengeType](#hukschallengetype9).
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_CHALLENGE_POS9+ | HuksTagType.HUKS_TAG_TYPE_UINT \| 310 | Position of the 8-byte valid value in a custom challenge. For details, see [HuksChallengePosition](#hukschallengeposition9).
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_AUTH_PURPOSE10+ | HuksTagType.HUKS_TAG_TYPE_UINT \|311 | Key authentication purpose.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_CHALLENGE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 501 | Challenge value used in the attestation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_APPLICATION_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 502 | Application ID used in the attestation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_BRAND | HuksTagType.HUKS_TAG_TYPE_BYTES \| 503 | Brand of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_DEVICE | HuksTagType.HUKS_TAG_TYPE_BYTES \| 504 | ID of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_PRODUCT | HuksTagType.HUKS_TAG_TYPE_BYTES \| 505 | Product name of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_SERIAL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 506 | SN of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_IMEI | HuksTagType.HUKS_TAG_TYPE_BYTES \| 507 | International mobile equipment identity (IMEI) of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_MEID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 508 | Mobile equipment identity (MEID) of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_MANUFACTURER | HuksTagType.HUKS_TAG_TYPE_BYTES \| 509 | Manufacturer of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_MODEL | HuksTagType.HUKS_TAG_TYPE_BYTES \| 510 | Device model.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_ALIAS | HuksTagType.HUKS_TAG_TYPE_BYTES \| 511 | Key alias used in the attestation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_SOCID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 512 | System-on-a-chip (SoCID) of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_UDID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 513 | Unique device identifier (UDID) of the device.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 514 | Security level used in the attestation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ATTESTATION_ID_VERSION_INFO | HuksTagType.HUKS_TAG_TYPE_BYTES \| 515 | Version information used in the attestation.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_IS_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1001 | Whether to use the alias passed in during key generation.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_KEY_STORAGE_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1002 | Key storage mode.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_IS_ALLOWED_WRAP | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1003 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_WRAP_TYPE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1004 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_AUTH_ID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1005 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_ROLE | HuksTagType.HUKS_TAG_TYPE_UINT \| 1006 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_FLAG | HuksTagType.HUKS_TAG_TYPE_UINT \| 1007 | Flag of the key.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_IS_ASYNCHRONIZED | HuksTagType.HUKS_TAG_TYPE_UINT \| 1008 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_SECURE_KEY_ALIAS | HuksTagType.HUKS_TAG_TYPE_BOOL \| 1009 | Reserved.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_SECURE_KEY_UUID | HuksTagType.HUKS_TAG_TYPE_BYTES \| 1010 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY_DOMAIN | HuksTagType.HUKS_TAG_TYPE_UINT \| 1011 | Reserved.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_PROCESS_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10001 | Process name.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_PACKAGE_NAME | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10002 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ACCESS_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10003 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_USES_TIME | HuksTagType.HUKS_TAG_TYPE_UINT \| 10004 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_CRYPTO_CTX | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10005 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_KEY | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10006 | Reserved.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_KEY_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10007 | Key version.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_PAYLOAD_LEN | HuksTagType.HUKS_TAG_TYPE_UINT \| 10008 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_AE_TAG | HuksTagType.HUKS_TAG_TYPE_BYTES \| 10009 | Used to pass in the AEAD in GCM mode.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_IS_KEY_HANDLE | HuksTagType.HUKS_TAG_TYPE_ULONG \| 10010 | Reserved.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_OS_VERSION | HuksTagType.HUKS_TAG_TYPE_UINT \| 10101 | OS version.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_OS_PATCHLEVEL | HuksTagType.HUKS_TAG_TYPE_UINT \| 10102 | OS patch level.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_SYMMETRIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20001 | Reserved.
**System capability**: SystemCapability.Security.Huks.Core| +| HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20002 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| +| HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | HuksTagType.HUKS_TAG_TYPE_BYTES \| 20003 | Reserved.
**System capability**: SystemCapability.Security.Huks.Extension| ## huks.generateKey(deprecated) @@ -2485,7 +2485,7 @@ Generates a key. This API uses an asynchronous callback to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2537,7 +2537,7 @@ Generates a key. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.generateKeyItem9+](#huksgeneratekeyitem9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2590,7 +2590,7 @@ Deletes a key. This API uses an asynchronous callback to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2619,7 +2619,7 @@ Deletes a key. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.deleteKeyItem9+](#huksdeletekeyitem9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2653,7 +2653,7 @@ Imports a key in plaintext. This API uses an asynchronous callback to return the > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2713,7 +2713,7 @@ Imports a key in plaintext. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.importKeyItem9+](#huksimportkeyitem9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2780,7 +2780,7 @@ Exports a key. This API uses an asynchronous callback to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2809,7 +2809,7 @@ Exports a key. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.exportKeyItem9+](#huksexportkeyitem9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2843,7 +2843,7 @@ Obtains key properties. This API uses an asynchronous callback to return the res > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2872,7 +2872,7 @@ Obtains key properties. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.getKeyItemProperties9+](#huksgetkeyitemproperties9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2906,7 +2906,7 @@ Checks whether a key exists. This API uses an asynchronous callback to return th > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2935,7 +2935,7 @@ Checks whether a key exists. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.isKeyItemExist9+](#huksiskeyitemexist9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2969,7 +2969,7 @@ Initializes the data for a key operation. This API uses an asynchronous callback > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -2987,7 +2987,7 @@ Initializes the data for a key operation. This API uses a promise to return the > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.initSession9+](#huksinitsession9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3010,7 +3010,7 @@ Updates the key operation by segment. This API uses an asynchronous callback to > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3029,7 +3029,7 @@ Updates the key operation by segment. This API uses a promise to return the resu > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.updateSession9+](#huksupdatesession9-2). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3053,7 +3053,7 @@ Completes the key operation and releases resources. This API uses an asynchronou > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3071,7 +3071,7 @@ Completes the key operation and releases resources. This API uses a promise to r > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.finishSession9+](#huksfinishsession9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3094,7 +3094,7 @@ Aborts the use of the key. This API uses an asynchronous callback to return the > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3205,7 +3205,7 @@ Aborts the use of the key. This API uses a promise to return the result. > **NOTE**
This API is deprecated since API version 9. You are advised to use [huks.abortSession9+](#huksabortsession9-1). -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension **Parameters** @@ -3323,7 +3323,7 @@ function huksAbort() { Defines the HUKS handle structure. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension > **NOTE**
This API is deprecated since API version 9. You are advised to use [HuksSessionHandle9+](#hukssessionhandle9). | Name | Type | Mandatory| Description | @@ -3336,7 +3336,7 @@ Defines the HUKS handle structure. Defines the **HuksResult** structure. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension > **NOTE**
This API is deprecated since API version 9. You are advised to use [HuksReturnResult9+](#huksreturnresult9). @@ -3352,7 +3352,7 @@ Defines the **HuksResult** structure. Enumerates the error codes. -**System capability**: SystemCapability.Security.Huks +**System capability**: SystemCapability.Security.Huks.Extension > **NOTE**
This API is deprecated since API version 9. You are advised to use HuksExceptionErrCode9+](#huksexceptionerrcode9). | Name | Value | Description| diff --git a/en/application-dev/reference/apis/js-apis-secureElement.md b/en/application-dev/reference/apis/js-apis-secureElement.md new file mode 100644 index 0000000000000000000000000000000000000000..429058cec789dcb61dcec498183c4ec92161c9be --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-secureElement.md @@ -0,0 +1,1283 @@ +# @ohos.secureElement (SE Management) + +The **secureElement** module provides APIs for operating and managing the SecureElement (SE). The SE service mentioned in this document is an **SEService** instance. For details, see [newSEService](#secureelementnewseservice). + +The instances of the following classes are involved in this document. + +| Class | Description | +| ------- | ---------------------------------------------- | +| Session | A **Session** instance represents a session for connecting to an available SE on the device.| +| Reader | A **Reader** instance represents an SE reader supported by the device. | +| Channel | A **Channel** instance represents an ISO/IEC 7816-4 channel opened to the SE. | + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## **Modules to Import** + +```js +import secureElement from '@ohos.secureElement'; +``` + +## secureElement.ServiceState + +Defines the SE service status values. + +**System capability**: SystemCapability.Communication.SecureElement + +| Name | Value | Description | +| ------------ | ---- | ------------------ | +| DISCONNECTED | 0 | The SE service is disconnected.| +| CONNECTED | 1 | The SE service is connected.| + +## secureElement.newSEService + +newSEService(type: 'serviceState', callback: Callback<[ServiceState](#secureelementservicestate)>): SEService + +Creates an **SEService** instance for connecting to all available SEs in the system. The connection is time-consuming. Therefore, this API supports only the asynchronous mode. + +The returned **SEService** object is available only when **true** is returned by the specified callback or [isConnected](#seserviceisconnected). + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ---------------------------------------------------- | -------------------- | +| type | string | 'serviceState' | +| callback | Callback<[ServiceState](#secureelementservicestate)> | Callback invoked to return the SE service status.| + +**Return value** + +| **Type** | **Description** | +| :-------- | :--------- | +| SEService | Returns the **SEService** instance created.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcSEService: secureElement.SEService = null; + +this.result = "Service state is Unkown"; +try { + this.nfcSEService = secureElement.newSEService("serviceState", (state) => { + if (state == secureElement.ServiceState.DISCONNECTED) { + this.result = "Service state is Disconnected"; + } else { + this.result = "Service state is Connected"; + } + }); +} catch (e) { + this.result = "newSEService occurs exception:" + e.message; +} +``` + +## SEService.getReaders + +getReaders(): Reader[] + +Obtains the available SE readers. The returned array cannot contain duplicate objects. Even if no card is inserted, all available readers should be listed. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| :------- | :--------------------- | +| Reader[] | Returns an array of available **Reader** objects.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcSEService: secureElement.SEService = null; +@State nfcServiceState: secureElement.ServiceState = null; +@State nfcOmaReader: secureElement.Reader = null; +@State nfcOmaReaderList: secureElement.Reader[] = null; + +// get SEService +try { + this.nfcSEService = secureElement.newSEService("serviceState", (state) => { + if (state == secureElement.ServiceState.DISCONNECTED) { + this.result = "Service state is Disconnected"; + } else { + this.result = "Service state is Connected"; + } + }); +} catch (e) { + this.result = "newSEService excpetion:" + e.message; +} + +try { + this.nfcOmaReaderList = this.nfcSEService.getReaders(); + if (this.nfcOmaReaderList != null && this.nfcOmaReaderList.length > 0) { + this.nfcOmaReader = this.nfcOmaReaderList[0]; + this.result = "get reader successfully"; + } else { + this.result = "get reader failed"; + } +} catch (e) { + this.result = "getReaders exception:" + e.message; +} +``` + +## SEService.isConnected + +isConnected(): boolean + +Checks whether this SE service is connected. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| :------- | :--------------------------------------------- | +| boolean | Returns **true** if the SE service is connected; returns **false** otherwise.| + +**Example** + +```JS +import secureElement from '@ohos.secureElement'; + +@State result: string = '' +@State nfcSEService: secureElement.SEService = null; + +try { + let ret: boolean; + // refer to newSEService for this.nfcSEService + ret = this.nfcSEService.isConnected(); + if (ret) { + this.result = 'get state: connected'; + } else { + this.result = 'get state: not connected'; + } +} catch (e) { + this.result = "isConnected exception: " + e.message; +} +``` + +## SEService.shutdown + +shutdown(): void + +Releases all SE resources allocated to this service. After that, [isConnected](#seserviceisconnected) returns **false**. + +**System capability**: SystemCapability.Communication.SecureElement + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcSEService: secureElement.SEService = null; + +try { + // refer to newSEService for this.nfcSEService + this.nfcSEService.shutdown(); + this.result = "shutdown successfully"; +} catch (e) { + this.result = "shutdown exception:" + e.message; +} +``` + +## SEService.getVersion + +getVersion(): string + +Obtains the version of the Open Mobile API Specification used for the implementation. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | -------------------------------------------------- | +| string | Returns the OMA version. For example, **3.3** indicates Open Mobile API Specification v3.3.| + +**Example** + +```JS +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcSEService: secureElement.SEService = null; + +this.result = "version: " +try { + // refer to newSEService for this.nfcSEService + this.result += this.nfcSEService.getVersion(); +} catch (e) { + this.result = "getVersion exception:" + e.message; +} +``` + +## Reader.getName + +getName(): string + +Obtains the reader name. If the card reader is a SIM reader, its name must be in **SIM[Slot]** format. If the card reader is an embedded SE reader, its name must be in **eSE[slot]** format. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ---------- | +| string | Returns the reader name obtained.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaReader: secureElement.Reader = null; + +try { + // refer to SEService.getReaders for this.nfcOmaReader + this.result = this.nfcOmaReader.getName(); +} catch (e) { + this.result = "getName exception:" + e.message; +} +``` + +## Reader.isSecureElementPresent + +isSecureElementPresent(): boolean + +Checks whether the SE corresponding to this reader is available. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | -------------------------------------------- | +| boolean | Returns **true** if the SE is available; returns **false** otherwise.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaReader: secureElement.Reader = null; + +try { + // refer to SEService.getReaders for this.nfcOmaReader + if (this.nfcOmaReader.isSecureElementPresent()) { + this.result = "isSecureElementPresent TRUE"; + } else { + this.result = "isSecureElementPresent FALSE"; + } +} catch (e) { + this.result = "isSecureElementPresent exception:" + e.message; +} +``` + +## Reader.openSession + + openSession(): Session + +Connects to the SE of this reader. This API initializes the SE for communication before returning the session object. Multiple sessions may be opened on a reader at the same time. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------ | +| Session | Returns the **Session** object used to create a channel.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaReader: secureElement.Reader = null; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to SEService.getReaders for this.nfcOmaReader + this.nfcOmaSession = this.nfcOmaReader.openSession(); + if (this.nfcOmaSession) { + this.result = "get session successfully"; + } else { + this.result = "get session failed"; + } +} catch (e) { + this.result = "OpenSession exception: " + e.message; +} +``` + +## Reader.closeSessions + + closeSessions(): void + +Closes all sessions opened on this reader. This API closes all channels opened by these sessions. + +**System capability**: SystemCapability.Communication.SecureElement + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaReader: secureElement.Reader = null; + +try { + // refer to SEService.getReaders for this.nfcOmaReader + this.nfcOmaReader.closeSessions(); + this.result = "close Sessions successfully"; +} catch (e) { + this.result = "closeSessions exception:" + e.message; +} +``` + +## Session.getReader + +getReader(): Reader + +Obtains the reader that provides this session. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | --------------------------- | +| Reader | Returns the **Reader** object obtained.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaReader: secureElement.Reader = null; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to Reader.openSession for this.nfcOmaSession + this.nfcOmaReader = this.nfcOmaSession.getReader(); + if (this.nfcOmaReader) { + this.result = "get reader successfully"; + } else { + this.result = "get reader failed"; + } +} catch (e) { + this.result = "getReader exception:" + e.message; +} +``` + +## Session.getATR + +getATR(): number[] + +Obtains the ATR of this SE. If the ATR of this SE is not available, an empty array will be returned. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | -------------------------------------------- | +| number[] | Returns the ATR obtained if the SE has an available ATR; returns an empty array otherwise.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to Reader.openSession for this.nfcOmaSession + let ret = this.nfcOmaSession.getATR(); + if (ret) { + this.result = "getATR result:["; + for (let i = 0; i < ret.length; ++i) { + this.result += ret[i]; + this.result += ' '; + } + this.result += ']'; + } else { + this.result = "getATR result is null"; + } +} catch (e) { + this.result = "getATR exception:" + e.message; +} +``` + +## Session.close + +close(): void + +Closes the connection with this SE. This API closes all channels opened between this application and the SE. + +**System capability**: SystemCapability.Communication.SecureElement + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to Reader.openSession for this.nfcOmaSession + this.nfcOmaSession.close(); + this.result = "session close successfully"; +} catch (e) { + this.result = "session close exception:" + e.message; +} +``` + +## Session. isClosed + +isClosed(): boolean + +Checks whether the session is closed. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------------ | +| boolean | Returns **true** if the session is closed; returns **false** otherwise.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +**Example** + +```Js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to Reader.openSession for this.nfcOmaSession + let ret = this.nfcOmaSession.isClosed(); + if (ret) { + this.result = "session state is closed"; + } else { + this.result = "session state is not closed"; + } +} catch (e) { + this.result = "isClosed exception:" + e.message; +} +``` + +## Session.closeChannels + +closeChannels(): void + +Closes all channels opened in this session. + +**System capability**: SystemCapability.Communication.SecureElement + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; + +try { + // refer to Reader.openSession for this.nfcOmaSession + this.nfcOmaSession.closeChannels(); + this.result = "close Channels successfully"; +} catch (e) { + this.result = "closeChannels exception:" + e.message; +} +``` + +## Session.openBasicChannel + +openBasicChannel(aid: number[]): Promise + +Opens a basic channel. This API uses a promise to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type**| **Description** | +| ---------- | -------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on this channel or null if no applet is selected. | + +**Return value** + +| **Type**| **Description** | +| -------- | --------------------- | +| Channel | Returns the **Channel** instance opened. If the SE cannot provide a new basic channel or cannot obtain the access control rule due to lack of available basic channels, null will be returned. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Reader.openSession for this.nfcOmaSession. + let getPromise = this.nfcOmaSession.openBasicChannel(this.aidArray); + getPromise.then((channel) => { + this.nfcOmaChannel = channel; + this.result = "openBasicChannel1 get channel successfully"; + }).catch ((err) => { + this.result = "openBasicChannel1 exception:" + err.message; + }); +} catch (e) { + this.result = "OpenBasicChannel1 exception:" + e.message; +} +``` + +## Session.openBasicChannel + + openBasicChannel(aid: number[], callback: AsyncCallback): void + +Opens a basic channel. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ---------------------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on this channel or null if no applet is selected. | +| callback | AsyncCallback | Callback invoked to return the **Channel** instance opened. If the SE cannot provide a new basic channel or cannot obtain the access control rule due to lack of available basic channels, null will be returned. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; + +try { + // See Reader.openSession for this.nfcOmaSession. + this.nfcOmaSession.openBasicChannel(this.aidArray, (error, data) => { + if (error) { + this.result = "openBasicChannel2 failed:" + JSON.stringify(error); + return; + } + this.nfcOmaChannel = data; + this.result = "openBasicChannel2 get channel successfully"; + }); +} catch (e) { + this.result = "openBasicChannel2 exception:" + e.message; +} +``` + +## Session.openBasicChannel + +openBasicChannel(aid: number[], p2: number): Promise + +Opens a basic channel. This API uses a promise to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type**| **Description** | +| ---------- | -------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on this channel or null if no applet is selected. | +| p2 | number | P2 parameter of the **SELECT APDU** command executed on the channel. | + +**Return value** + +| **Type**| **Description** | +| -------- | --------------------- | +| Channel | Returns the **Channel** instance opened. If the SE cannot provide a new basic channel or cannot obtain the access control rule due to lack of available basic channels, null will be returned. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; +p2: number = 0x00; + +try { + // See Reader.openSession for this.nfcOmaSession. + let getPromise = this.nfcOmaSession.openBasicChannel(this.aidArray, this.p2); + getPromise.then((channel) => { + this.nfcOmaChannel = channel; + this.result = "openBasicChannel3 get channel successfully"; + }).catch ((err) => { + this.result = "openBasicChannel3 exception"; + }); +} catch (e) { + this.result = "openBasicChannel3 exception:" + e.message; +} +``` + +## Session.openBasicChannel + +openBasicChannel(aid: number[], p2:number, callback: AsyncCallback): void + +Opens a basic channel. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ---------------------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on this channel or null if no applet is selected. | +| p2 | number | P2 parameter of the **SELECT APDU** command executed on the channel. | +| callback | AsyncCallback | Callback invoked to return the **Channel** instance opened. If the SE cannot provide a new basic channel or cannot obtain the access control rule due to lack of available basic channels, null will be returned. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; +p2: number = 0x00; + +try { + // See Reader.openSession for this.nfcOmaSession. + this.nfcOmaSession.openBasicChannel(this.aidArray, this.p2, (error, data) => { + if (error) { + this.result = "openBasicChannel4 failed:" + JSON.stringify(error); + return; + } + this.nfcOmaChannel = data; + this.result = "openBasicChannel4 get channel successfully"; + }); +} catch (e) { + this.result = "openBasicChannel4 exception:" + e.message; +} +``` + +## Session.openLogicalChannel + +openLogicalChannel(aid: number[]): Promise + +Opens a logical channel. This API uses a promise to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type**| **Description** | +| ---------- | -------- | --------------------------------------- | +| aid | number[] | AIDs of the applets selected on the **Channel** instance. | + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------------------------------------ | +| Channel | Returns the **Channel** instance opened. If the SE cannot provide a new **Channel** instance or cannot obtain access control rules due to lack of available logical **Channel** instances, null will be returned.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; + +try { + // See Reader.openSession for this.nfcOmaSession. + let getPromise = this.nfcOmaSession.openLogicalChannel(this.aidArray) + getPromise.then((channel) => { + this.nfcOmaChannel = channel; + this.result = "openLogicChannel1 get channel successfully"; + }).catch ((err) => { + this.result = "openLogicChannel1 exception:" + err.message; + }); +} catch (e) { + this.result = "openLogicChannel1 exception:" + e.message; +} +``` + +## Session.openLogicalChannel + + openLogicalChannel(aid:number[], callback: AsyncCallback): void + +Opens a logical channel. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ---------------------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on the **Channel** instance. | +| callback | AsyncCallback | Callback invoked to return the **Channel** instance opened. If the SE cannot provide a new **Channel** instance or cannot obtain access control rules due to lack of available logical **Channel** instances, null will be returned.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; + +try { + // See Reader.openSession for this.nfcOmaSession. + this.nfcOmaSession.openLogicalChannel(this.aidArray, (error, data) => { + if (error) { + this.result = "openLogicChannel2 failed:" + JSON.stringify(error); + return; + } + this.nfcOmaChannel = data; + this.result = "openLogicChannel2 get channel successfully"; + }); +} catch (e) { + this.result = "openLogicChannel2 exception:" + e.message; +} +``` + +## Session.openLogicalChannel + +openLogicalChannel(aid: number[], p2: number): Promise + +Opens a logical channel with the applet represented by the given AID (the AID is not null and the length is not 0). + +If the AID length is 0, this API sends a **select** command with the AID length of 0 (as per [GPCS]) to select the Issuer Security Domain of the SE. + +If the AID is null, this API sends the **MANAGE CHANNEL Open** only. In this case, the default applet associated with the logical channel is selected. + +**P2** is usually **0x00**. The device shall allow any value of **P2** and the following values: **0x00**, **0x04**, **0x08**, **0x0C** as defined in [ISO 7816-4](https://www.iso.org/standard/77180.html). + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type**| **Description** | +| ---------- | -------- | ----------------------------------------- | +| aid | number[] | AIDs of the applets selected on the **Channel** instance. | +| p2 | number | P2 parameter of the **SELECT APDU** command executed on the channel. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; +p2: number = 0x00; + +if (this.nfcOmaSession) { + try { + // See Reader.openSession for this.nfcOmaSession. + let getPromise = this.nfcOmaSession.openLogicalChannel(this.aidArray, this.p2); + getPromise.then((channel) => { + this.nfcOmaChannel = channel; + this.result = "openLogicChannel3 get channel successfully"; + }).catch ((err) => { + this.result = "openLogicChannel3 exception"; + }) +} catch (e) { + this.result = "openLogicChannel3 exception:" + e.message; +} +``` + +## Session.openLogicalChannel + +openLogicalChannel(aid: number[], p2: number, callback: AsyncCallback):void + +Opens a logical channel with the applet represented by the given AID (the AID is not null and the length is not 0). + +If the AID length is 0, this API sends a **select** command with the AID length of 0 (as per [GPCS]) to select the Issuer Security Domain of the SE. + +If the AID is null, this API sends the **MANAGE CHANNEL Open** only. In this case, the default applet associated with the logical channel is selected. + +**P2** is usually **0x00**. The device shall allow any value of **P2** and the following values: **0x00**, **0x04**, **0x08**, **0x0C** as defined in [ISO 7816-4](https://www.iso.org/standard/77180.html). + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ---------------------- | ------------------------------------------------------------ | +| aid | number[] | AIDs of the applets selected on the **Channel** instance. | +| p2 | number | P2 parameter of the **SELECT APDU** command executed on the channel. | +| callback | AsyncCallback | Callback invoked to return the **Channel** instance opened. If the SE cannot provide a new **Channel** instance or cannot obtain access control rules due to lack of available logical **Channel** instances, null will be returned.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300102 | No such element exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; +aidArray: number[] = [720, 1080]; +p2: number = 0x00; + +try { + // See Reader.openSession for this.nfcOmaSession. + this.nfcOmaSession.openLogicalChannel(this.aidArray, this.p2, (error, data) => { + if (error) { + this.result = "openLogicChannel4 failed:" + JSON.stringify(error); + return; + } + this.nfcOmaChannel = data; + this.result = "openLogicChannel4 get channel successfully"; + }) +} catch (e) { + this.result = "openLogicChannel4 exception:" + e.message; +} +``` + +## Channel. getSession + + getSession(): Session + +Obtains the session that opens this channel. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ----------------------------- | +| Session | Returns the session obtained.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Session.openBasicChannel for this.nfcOmaChannel. + let ret = this.nfcOmaChannel.getSession(); + if (ret) { + this.result = "get session successfully"; + } else { + this.result = "get session failed"; + } +} catch (e) { + this.result = "getSession exception:" + e.message; +} +``` + +## Channel. close + +close(): void + +Closes the channel of the SE. + +**System capability**: SystemCapability.Communication.SecureElement + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaSession: secureElement.Session = null; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Session.openBasicChannel for this.nfcOmaChannel. + this.nfcOmaChannel.close(); + this.result = "channel close successfully"; +} catch (e) { + this.result = "channel close exception:" + e.message; +} +``` + +## Channel. isBasicChannel + +isBasicChannel(): boolean + +Checks whether this channel is a basic channel. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------------------------------------ | +| boolean | Returns **true** if the channel is a basic channel; returns **false** otherwise.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Session.openBasicChannel for this.nfcOmaChannel. + let ret = this.nfcOmaChannel.isBasicChannel(); + if (ret) { + this.result = "isBasicChannel TRUE"; + } else { + this.result = "isBasicChannel FALSE"; + } +} catch (e) { + this.result = "isBasicChannel Exception: "+ e.message; +} +``` + +## Channel. isClosed + +isClosed(): boolean + +Checks whether this channel is closed. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | --------------------------------------------- | +| boolean | Returns **true** if this channel is closed; returns **false** otherwise.| + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Session.openBasicChannel for this.nfcOmaChannel. + let ret = this.nfcOmaChannel.isClosed(); + if (ret) { + this.result = "channel isClosed TRUE"; + } else { + this.result = "channel isClosed False"; + } +} catch (e) { + this.result = "Channel isClosed exception:" + e.message; +} +``` + +## Channel. getSelectResponse + +getSelectResponse():number[] + +Obtains the data as received from the application **select** command, including the status word received when the applet is selected. + +**System capability**: SystemCapability.Communication.SecureElement + +**Return value** + +| **Type**| **Description** | +| -------- | ------------------------------------------------------------ | +| number[] | Returns the data obtained.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + // See Session.openBasicChannel for this.nfcOmaChannel. + let ret = this.nfcOmaChannel.getSelectResponse(); + if (ret) { + this.result = "getSelectResponse result:["; + for (let i = 0; i < ret.length; ++i) { + this.result += ret[i]; + this.result += ' '; + } + this.result += ']'; + } else { + this.result = "getSelectResponse result is null"; + } +} catch (e) { + this.result = "getSelectResponse exception:" + e.message; +} +``` + +## Channel. transmit + +transmit(command: number[]): Promise + +Transmits the **APDU** command to the SE (according to ISO/IEC 7816). This API uses a promise to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type**| **Description** | +| ---------- | -------- | ------------------------------------- | +| command | number[] | AIDs of the applets selected on the channel. | + +**Return value** + +| **Type**| **Description** | +| -------- | -------------- | +| number[] | Returns the response obtained.| + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + let command: number[] = [100, 200]; + // See Session.openBasicChannel for this.nfcOmaChannel. + let getPromise = this.nfcOmaChannel.transmit(command); + getPromise.then((data) => { + this.result = "transmit1 result:["; + for (let i = 0; i < data.length; ++i) { + this.result += data[i]; + this.result += " "; + } + this.result += "]"; + }).catch ((err) => { + this.result = "transmit1 exception:" + err.code; + }) +} catch (e) { + this.result = "transit1 exception:" + e.message; +} +``` + +## Channel. transmit + +transmit(command: number[], callback: AsyncCallback): void + +Transmits the **APDU** command to the SE (according to ISO/IEC 7816). This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Communication.SecureElement + +**Parameters** + +| **Name**| **Type** | **Description** | +| ---------- | ----------------------- | ------------------------------------- | +| command | number[] | AIDs of the applets selected on the channel. | +| callback | AsyncCallback | Callback invoked to return the result. | + +**Error codes** + +For details about error codes, see [SE Error Codes](../errorcodes/errorcode-se.md). + +| ID| Error Message | +| -------- | -------------------------------- | +| 3300101 | Illegal service state exception. | +| 3300103 | Illegal access rule exception. | +| 3300104 | Secure element IO exception. | + +**Example** + +```js +import secureElement from '@ohos.secureElement'; + +@State result: string = ''; +@State nfcOmaChannel: secureElement.Channel = null; + +try { + let command: number[] = [100, 200]; + // See Session.openBasicChannel for this.nfcOmaChannel. + this.nfcOmaChannel.transmit(command, (error, data) => { + if (error) { + this.result = "transmit2 exception:" + JSON.stringify(error); + return; + } + this.result = "transmit2 result:["; + for (let i = 0; i < data.length; ++i) { + this.result += data[i]; + this.result += " "; + } + this.result += "]"; + }); +} catch (e) { + this.result = "transit2 exception:" + e.message; +} +``` diff --git a/en/application-dev/reference/errorcodes/Readme-EN.md b/en/application-dev/reference/errorcodes/Readme-EN.md index baffeb2d779edbb96e55d77add3164bbbd2be604..8c91c3d1205b3bd853b05dfa015a3f4e06a3290f 100644 --- a/en/application-dev/reference/errorcodes/Readme-EN.md +++ b/en/application-dev/reference/errorcodes/Readme-EN.md @@ -60,6 +60,7 @@ - [Bluetooth Error Codes](errorcode-bluetoothManager.md) - [Wi-Fi Error Codes](errorcode-wifi.md) - [NFC Error Codes](errorcode-nfc.md) + - [SE Error Codes](errorcode-se.md) - [RPC Error Codes](errorcode-rpc.md) - Basic Features - [Accessibility Error Codes](errorcode-accessibility.md) diff --git a/en/application-dev/reference/errorcodes/errorcode-se.md b/en/application-dev/reference/errorcodes/errorcode-se.md new file mode 100644 index 0000000000000000000000000000000000000000..adafce2852253a434ef9f1d40ef860cea9a43832 --- /dev/null +++ b/en/application-dev/reference/errorcodes/errorcode-se.md @@ -0,0 +1,85 @@ +# SE Error Codes + +> **NOTE** +> +> This topic describes only module-specific error codes. For details about universal error codes, see [Universal Error Codes](errorcode-universal.md). + +## 3300101 Abnormal SE Service Status + +**Error Message** + +Illegal service state exception. + +**Description** + +The SecureElement (SE) service is abnormal. + +**Possible Causes** + +1. The SE service is disconnected. + +**Solution** + +1. Close the SE service. + +2. Set up a connection with the SE service again. + +## 3300102 No Such SE + +**Error Message** + +No such element exception. + +**Description** + +The SE is unavailable. + +**Possible Causes** + +1. Communication with the SE service is abnormal. +2. Communication of the SE chip is abnormal. + +**Solution** + +1. Close the SE service and set up a connection with the SE service again. +2. Restart the device. + +## 3300103 Failed to Obtain the Access Rule + +**Error Message** + +Illegal access rule exception. + +**Description** + +The access rule cannot be obtained. + +**Possible Causes** + +1. There is no access rule for the application on the SE. + +**Solution** + +1. Write correct access rules to the SE. +2. Close the SE service and set up a connection with the SE service again. + +## 3300104 SE Chip I/O Exception + +**Error Message** + +Secure element IO exception. + +**Description** + +The I/O of the SE chip is abnormal. + +**Possible Causes** + +1. The communication with the SE chip is abnormal. +2. The SE chip is abnormal. + +**Solution** + +1. Close the SE service and set up a connection with the SE service again. + +2. Restart the device. diff --git a/en/application-dev/reference/native-api-intro.md b/en/application-dev/reference/native-api-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..75e18a70d7ca16751be7c6ed7979401919303d4a --- /dev/null +++ b/en/application-dev/reference/native-api-intro.md @@ -0,0 +1,77 @@ +# Native API Introduction + +Native APIs, also called Native Develop Kit (NDK), are a set of native interfaces and tools provided by the OpenHarmony SDK for implementing key application features by using C or C++. Different from JS APIs, the Native APIs provide only part of underlying capabilities of OpenHarmony, such as the libc, graphics library, window system, multimedia, and compression library. The Native APIs will be build as a dynamic library before being packaged into an application. + +## Concepts + +|Term|Description| +|--|--| +|Native API|Native interfaces, build scripts, and compiler toolchains provided by the **native** package in the OpenHarmony SDK for third-party application development. Native APIs include the C runtime libc, 3D graphics library **OpenGL**, and Node-APIs for cross-language programming between JS and C.| +|NDK|Native Develop Kit (NDK) that provides the Native APIs in OpenHarmony. NDK is the equivalent of Native API. Native API is the official name.| +|SDK CAPI|C interfaces and toolchains in OpenHarmony Native APIs.
Currently, OpenHarmony Native APIs contain only C interfaces. Therefore, Native API is CAPI. However, you are advised to use CAPI.| +|Node-API|Native interfaces that implement cross-language invocation between C and JS. Node-API is formerly called napi. Although OpenHarmony Node-APIs are extension of the Node-APIs provided by **Node.js**, they are not fully compatible with the Node-APIs in **Node.js**.| +|napi|Former name of Node-API. It is not used because it may be interpreted as Native API or Node-API by mistake. Currently, the interfaces in the Node-API header files still start with **napi_**.| + +## Native API Composition + +### Native API Directory Structure + +Native APIs are stored in the **$(SDK_ROOT)/native** directory of the SDK. + +|Directory|Description| +|--|--| +|build|Provides the toolchain cmake script used to build the dynamic library of an application. The **ohos.toolchain.cmake** file in this directory defines OpenHarmony cross-compilation options.| +|build-tools|Provides build tools, such as CMake.| +|docs|Provides Native API reference documents, which are extracted from the header files using Doxgen.| +|llvm|Provides the LLVM, a cross compiler that supports the OpenHarmony Application Binary Interface (ABI).| +|sysroot|Provides dependencies of links, including header files and dynamic libraries.| + +### Native APIs + +|Category|Description|Introduced Since Version| +|--|--|--| +|[C standard library](native-lib/third_party_libc/musl.md)|Provides more than 1500 libc interfaces based on musl.|8| +|[C++ standard library](native-lib/third_party_libc/cpp.md)|Provides the libc++_shared library for C++ runtime. This library must be packed or statically linked to the application during packing.|8| +|Log|Provides HiLog interfaces for printing logs to the system.|8| +|Node-API|Provides APIs like Node-APIs (also called napis) for accessing the JS application environment. Node-APIs are provided by ArkUI and are part of Native APIs.|8| +|XComponent|Provides Surface and touchscreen event interfaces for developing high-performance graphics applications on ArkUI.|8| +|libuv|Provides a third-party asynchronous I/O library integrated by ArkUI.|8| +|libz|Provides basic compression and decompression interfaces.|8| +|Drawing|Provides a 2D graphics library for drawing on Surface.|8| +|OpenGL|Provides OpenGL 3.0 interfaces.|8| +|Rawfile|Provides application resource access interfaces for reading various resources packed in applications.|8| +|OpenSLES|Provides interfaces for 2D and 3D audio acceleration.|8| +|Mindspore|Provides AI model interfaces.|9| +|Bundle management|Provides bundle service interfaces for querying bundle information of applications.|8| + +### Native API Documents + +* [Native API Reference](native-apis/_o_h___native_x_component.md): provides reference for Native APIs. +* [Standard Libraries Supported by Native APIs](../reference/native-lib/third_party_libc/musl.md): describes the open-source standard libraries supported by Native APIs. +* [Native API Development](../napi/napi-guidelines.md): describes how to use Native APIs. +* [Using NDK to Build a CMake C/C++ Project](../faqs/how-to-migrate-cmake-with-ohosndk.md): describes how to use Native APIs to develop a CMake project. +* [Using Node-APIs in Application Projects](../napi/napi-guidelines.md): describes how to use Node-APIs. + +## How to Use + +### Recommended Use of Native APIs + +Use Native APIs when you want to: + +1. Develop performance-sensitive code in computing-intensive scenarios, such as gaming and physical simulation. +2. Reuse the existing C or C++ library. +3. Customize libraries related to CPU features, such as neon acceleration. + +### Use of Native APIs Not Recommended + +Do not use Native APIs when you want to: + +1. Develop a pure OpenHarmony application. +2. Develop an application that is compatible on as many OpenHarmony devices as possible. + +## Debugging Capabilities + +1. OpenHarmony provides remote code debugging by using the low-level Debugger (LLDB). For details, see [LLDB](https://gitee.com/openharmony/third_party_llvm-project/blob/master/lldb/README_en.md). +2. OpenHarmony provides the log debugging for the musl library. For details, see "Debugging Capabilities" in [libc](./native-lib/third_party_libc/musl.md). + + \ No newline at end of file diff --git a/en/application-dev/reference/native-apis/_huks_type_api.md b/en/application-dev/reference/native-apis/_huks_type_api.md index 398b5df7b89d78913171fe0aa5d06a41e5ed81e2..fd8b7e2ee7038277dd517a32cf9ebe40298b9430 100644 --- a/en/application-dev/reference/native-apis/_huks_type_api.md +++ b/en/application-dev/reference/native-apis/_huks_type_api.md @@ -3,11 +3,11 @@ ## Overview -Defines the macros, enumerated values, data structures, and error codes used by OpenHarmony Universal KeyStore (HUKS) APIs. +Defines the macros, enums, structs, and error codes used by OpenHarmony Universal KeyStore (HUKS) APIs. \@syscap SystemCapability.Security.Huks -**Since:** +**Since**: 9 @@ -16,74 +16,75 @@ Defines the macros, enumerated values, data structures, and error codes used by ### Files -| Name | Description | +| Name| Description| | -------- | -------- | -| [native_huks_type.h](native__huks__type_8h.md) | Defines the enumerated variables, structures, and macros used in the HUKS APIs.
File to Include: | +| [native_huks_type.h](native__huks__type_8h.md) | Defines the enumerated variables, structs, and macros used in the HUKS APIs.
**File to include**:
**Library**: libhuks_ndk.z.so| ### Structs -| Name | Description | +| Name| Description| | -------- | -------- | -| [OH_Huks_Result](_o_h___huks___result.md) | Defines the return data, including the result code and message. | -| [OH_Huks_Blob](_o_h___huks___blob.md) | Defines the structure for storing data. | -| [OH_Huks_Param](_o_h___huks___param.md) | Defines the parameter structure in a parameter set. | -| [OH_Huks_ParamSet](_o_h___huks___param_set.md) | Defines the structure of the parameter set. | -| [OH_Huks_CertChain](_o_h___huks___cert_chain.md) | Defines the structure of the certificate chain. | -| [OH_Huks_KeyInfo](_o_h___huks___key_info.md) | Defines the key information structure. | -| [OH_Huks_PubKeyInfo](_o_h___huks___pub_key_info.md) | Defines the structure of a public key. | -| [OH_Huks_KeyMaterialRsa](_o_h___huks___key_material_rsa.md) | Defines the structure of an RSA key. | -| [OH_Huks_KeyMaterialEcc](_o_h___huks___key_material_ecc.md) | Defines the structure of an ECC key. | -| [OH_Huks_KeyMaterialDsa](_o_h___huks___key_material_dsa.md) | Defines the structure of a DSA key. | -| [OH_Huks_KeyMaterialDh](_o_h___huks___key_material_dh.md) | Defines the structure of a DH key. | -| [OH_Huks_KeyMaterial25519](_o_h___huks___key_material25519.md) | Defines the structure of a 25519 key. | +| [OH_Huks_Result](_o_h___huks___result.md) | Defines the returned status data, including the return code and message. | +| [OH_Huks_Blob](_o_h___huks___blob.md) | Defines the structure of the binary large object (BLOB) that stores data. | +| [OH_Huks_Param](_o_h___huks___param.md) | Defines the structure of the parameters in a parameter set. | +| [OH_Huks_ParamSet](_o_h___huks___param_set.md) | Defines the parameter set structure. | +| [OH_Huks_CertChain](_o_h___huks___cert_chain.md) | Defines the certificate chain structure. | +| [OH_Huks_KeyInfo](_o_h___huks___key_info.md) | Defines the key information structure. | +| [OH_Huks_PubKeyInfo](_o_h___huks___pub_key_info.md) | Defines the structure of a public key. | +| [OH_Huks_KeyMaterialRsa](_o_h___huks___key_material_rsa.md) | Defines the structure of an RSA key. | +| [OH_Huks_KeyMaterialEcc](_o_h___huks___key_material_ecc.md) | Defines the structure of an Elliptic Curve Cryptography (ECC) key. | +| [OH_Huks_KeyMaterialDsa](_o_h___huks___key_material_dsa.md) | Defines the structure of a DSA key. | +| [OH_Huks_KeyMaterialDh](_o_h___huks___key_material_dh.md) | Defines the structure of a Diffie-Hellman (DH) key. | +| [OH_Huks_KeyMaterial25519](_o_h___huks___key_material25519.md) | Defines the structure of a 25519 key. | ### Macros -| Name | Value | +| Name| Value| | -------- | -------- | -| **OH_HUKS_AE_TAG_LEN** | 16 | -| **OH_HUKS_BITS_PER_BYTE** | 8 | -| **OH_HUKS_MAX_KEY_SIZE** | 2048 | -| **OH_HUKS_AE_NONCE_LEN** | 12| -| **OH_HUKS_MAX_KEY_ALIAS_LEN** | 64 | -| **OH_HUKS_MAX_PROCESS_NAME_LEN** | 50 | -| **OH_HUKS_MAX_RANDOM_LEN** | 1024 | -| **OH_HUKS_SIGNATURE_MIN_SIZE** | 64 | -| **OH_HUKS_MAX_OUT_BLOB_SIZE** | (5 \* 1024 \* 1024) | -| **OH_HUKS_WRAPPED_FORMAT_MAX_SIZE** | (1024 \* 1024) | -| **OH_HUKS_IMPORT_WRAPPED_KEY_TOTAL_BLOBS** | 10 | -| **TOKEN_CHALLENGE_LEN** | 32 | -| **SHA256_SIGN_LEN** | 32 | -| **TOKEN_SIZE** | 32| -| **MAX_AUTH_TIMEOUT_SECOND** | 60 | -| **SECURE_SIGN_VERSION** | 0x01000001 | +| **OH_HUKS_AE_TAG_LEN** | 16 | +| **OH_HUKS_BITS_PER_BYTE** | 8| +| **OH_HUKS_MAX_KEY_SIZE** | 2048 | +| **OH_HUKS_AE_NONCE_LEN** | 12 | +| **OH_HUKS_MAX_KEY_ALIAS_LEN** | 64 | +| **OH_HUKS_MAX_PROCESS_NAME_LEN** | 50 | +| **OH_HUKS_MAX_RANDOM_LEN** | 1024 | +| **OH_HUKS_SIGNATURE_MIN_SIZE** | 64 | +| **OH_HUKS_MAX_OUT_BLOB_SIZE** | (5 \* 1024 \* 1024) | +| **OH_HUKS_WRAPPED_FORMAT_MAX_SIZE** | (1024 \* 1024) | +| **OH_HUKS_IMPORT_WRAPPED_KEY_TOTAL_BLOBS** | 10 | +| **TOKEN_CHALLENGE_LEN** |32 | +| **SHA256_SIGN_LEN** | 32 | +| **TOKEN_SIZE** |32 | +| **MAX_AUTH_TIMEOUT_SECOND** | 60 | +| **SECURE_SIGN_VERSION** | 0x01000001 | ### Enums -| Name | Description | +| Name| Description| | -------- | -------- | -| [OH_Huks_KeyPurpose](#oh_huks_keypurpose) {
OH_HUKS_KEY_PURPOSE_ENCRYPT = 1, OH_HUKS_KEY_PURPOSE_DECRYPT = 2, OH_HUKS_KEY_PURPOSE_SIGN = 4, OH_HUKS_KEY_PURPOSE_VERIFY = 8,
OH_HUKS_KEY_PURPOSE_DERIVE = 16, OH_HUKS_KEY_PURPOSE_WRAP = 32, OH_HUKS_KEY_PURPOSE_UNWRAP = 64, OH_HUKS_KEY_PURPOSE_MAC = 128,
OH_HUKS_KEY_PURPOSE_AGREE = 256
} | Enumerates the key purposes. | -| [OH_Huks_KeyDigest](#oh_huks_keydigest) {
OH_HUKS_DIGEST_NONE = 0, OH_HUKS_DIGEST_MD5 = 1, OH_HUKS_DIGEST_SM3 = 2, OH_HUKS_DIGEST_SHA1 = 10,
OH_HUKS_DIGEST_SHA224 = 11, OH_HUKS_DIGEST_SHA256 = 12, OH_HUKS_DIGEST_SHA384 = 13, OH_HUKS_DIGEST_SHA512 = 14
} | Enumerates the digest algorithms. | -| [OH_Huks_KeyPadding](#oh_huks_keypadding) {
OH_HUKS_PADDING_NONE = 0, OH_HUKS_PADDING_OAEP = 1, OH_HUKS_PADDING_PSS = 2, OH_HUKS_PADDING_PKCS1_V1_5 = 3,
OH_HUKS_PADDING_PKCS5 = 4, OH_HUKS_PADDING_PKCS7 = 5
} | Enumerates the padding algorithms. | -| [OH_Huks_CipherMode](#oh_huks_ciphermode) {
OH_HUKS_MODE_ECB = 1, OH_HUKS_MODE_CBC = 2, OH_HUKS_MODE_CTR = 3, OH_HUKS_MODE_OFB = 4,
OH_HUKS_MODE_CCM = 31, OH_HUKS_MODE_GCM = 32
} | Enumerates the cipher modes. | -| [OH_Huks_KeySize](#oh_huks_keysize) {
OH_HUKS_RSA_KEY_SIZE_512 = 512, OH_HUKS_RSA_KEY_SIZE_768 = 768, OH_HUKS_RSA_KEY_SIZE_1024 = 1024, OH_HUKS_RSA_KEY_SIZE_2048 = 2048,
OH_HUKS_RSA_KEY_SIZE_3072 = 3072, OH_HUKS_RSA_KEY_SIZE_4096 = 4096, OH_HUKS_ECC_KEY_SIZE_224 = 224, OH_HUKS_ECC_KEY_SIZE_256 = 256,
OH_HUKS_ECC_KEY_SIZE_384 = 384, OH_HUKS_ECC_KEY_SIZE_521 = 521, OH_HUKS_AES_KEY_SIZE_128 = 128, OH_HUKS_AES_KEY_SIZE_192 = 192,
OH_HUKS_AES_KEY_SIZE_256 = 256, OH_HUKS_AES_KEY_SIZE_512 = 512, OH_HUKS_CURVE25519_KEY_SIZE_256 = 256, OH_HUKS_DH_KEY_SIZE_2048 = 2048,
OH_HUKS_DH_KEY_SIZE_3072 = 3072, OH_HUKS_DH_KEY_SIZE_4096 = 4096, OH_HUKS_SM2_KEY_SIZE_256 = 256, OH_HUKS_SM4_KEY_SIZE_128 = 128
} | Enumerates the key sizes. | -| [OH_Huks_KeyAlg](#oh_huks_keyalg) {
OH_HUKS_ALG_RSA = 1, OH_HUKS_ALG_ECC = 2, OH_HUKS_ALG_DSA = 3, OH_HUKS_ALG_AES = 20,
OH_HUKS_ALG_HMAC = 50, OH_HUKS_ALG_HKDF = 51, OH_HUKS_ALG_PBKDF2 = 52, OH_HUKS_ALG_ECDH = 100,
OH_HUKS_ALG_X25519 = 101, OH_HUKS_ALG_ED25519 = 102, OH_HUKS_ALG_DH = 103, OH_HUKS_ALG_SM2 = 150,
OH_HUKS_ALG_SM3 = 151, OH_HUKS_ALG_SM4 = 152
} | Enumerates the key algorithms. | -| [OH_Huks_AlgSuite](#oh_huks_algsuite) { OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING = 1, OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING = 2 } | Enumerates the algorithm suites required for ciphertext imports. | -| [OH_Huks_KeyGenerateType](#oh_huks_keygeneratetype) { OH_HUKS_KEY_GENERATE_TYPE_DEFAULT = 0, OH_HUKS_KEY_GENERATE_TYPE_DERIVE = 1, OH_HUKS_KEY_GENERATE_TYPE_AGREE = 2 } | Enumerates the key generation types. | -| [OH_Huks_KeyFlag](#oh_huks_keyflag) { OH_HUKS_KEY_FLAG_IMPORT_KEY = 1, OH_HUKS_KEY_FLAG_GENERATE_KEY = 2, OH_HUKS_KEY_FLAG_AGREE_KEY = 3, OH_HUKS_KEY_FLAG_DERIVE_KEY = 4 } | Enumerates the key generation modes. | -| [OH_Huks_KeyStorageType](#oh_huks_keystoragetype) { OH_HUKS_STORAGE_TEMP = 0, OH_HUKS_STORAGE_PERSISTENT = 1 } | Enumerates the key storage modes. | -| [OH_Huks_ImportKeyType](#oh_huks_importkeytype) { OH_HUKS_KEY_TYPE_PUBLIC_KEY = 0, OH_HUKS_KEY_TYPE_PRIVATE_KEY = 1, OH_HUKS_KEY_TYPE_KEY_PAIR = 2 } | Enumerates the types of keys to import. By default, a public key is imported. This field is not required when a symmetric key is imported. | -| [OH_Huks_ErrCode](#oh_huks_errcode) {
OH_HUKS_SUCCESS = 0, OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201, OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401, OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801,
OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001, OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002, OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003, OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004,
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005, OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006, OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007, OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008,
OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009, OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010, OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011, OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012,
OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013
} | Enumerates the error codes. | -| [OH_Huks_TagType](#oh_huks_tagtype) {
OH_HUKS_TAG_TYPE_INVALID = 0 << 28, OH_HUKS_TAG_TYPE_INT = 1 << 28, OH_HUKS_TAG_TYPE_UINT = 2 << 28, OH_HUKS_TAG_TYPE_ULONG = 3 << 28,
OH_HUKS_TAG_TYPE_BOOL = 4 << 28, OH_HUKS_TAG_TYPE_BYTES = 5 << 28
} | Enumerates the tag types. | -| [OH_Huks_UserAuthType](#oh_huks_userauthtype) { OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0, OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1, OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2 } | Enumerates the user authentication types. | -| [OH_Huks_AuthAccessType](#oh_huks_authaccesstype) { OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0, OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1 } | Enumerates the access control types. | -| [OH_Huks_ChallengeType](#oh_huks_challengetype) { OH_HUKS_CHALLENGE_TYPE_NORMAL = 0, OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1, OH_HUKS_CHALLENGE_TYPE_NONE = 2 } | Enumerates the types of the challenges generated when a key is used. | -| [OH_Huks_ChallengePosition](#oh_huks_challengeposition) { OH_HUKS_CHALLENGE_POS_0 = 0, OH_HUKS_CHALLENGE_POS_1, OH_HUKS_CHALLENGE_POS_2, OH_HUKS_CHALLENGE_POS_3 } | Enumerates the positions of the 8-byte valid value in a custom challenge generated. | -| [OH_Huks_SecureSignType](#oh_huks_securesigntype) { OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1 } | Enumerates the signature types of the keys generated or imported. | -| [OH_Huks_Tag](#oh_huks_tag) {
OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT \| 1, OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 2, OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 3,
OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT \| 4, OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT \| 5, OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT \| 6, OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 7,
OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES \| 8, OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES \| 9, OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES \| 10, OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES \| 11,
OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES \| 12, OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT \| 14, OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 15,
OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT \| 19,
OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 20, OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 21, OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES \| 22, OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 23,
OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 24, OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 25, OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT \| 26, OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL \| 301,
OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT \| 302, OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL \| 303, OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT \| 304, OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT \| 305,
OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES \| 306, OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT \| 307, OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 308, OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 309,
OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT \| 310, OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES \| 501, OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES \| 502,
OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 511,
OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES \| 514, OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES \| 515,
OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 1001, OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1002, OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL \| 1003, OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT \| 1004,
OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES \| 1005, OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT \| 1006, OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1007, OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT \| 1008,
OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT \| 1011, OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20001,
OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20002, OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20003
} | Enumerates the tag values used in parameter sets. | +| [OH_Huks_KeyPurpose](#oh_huks_keypurpose) {
OH_HUKS_KEY_PURPOSE_ENCRYPT = 1,
OH_HUKS_KEY_PURPOSE_DECRYPT = 2,
OH_HUKS_KEY_PURPOSE_SIGN = 4,
OH_HUKS_KEY_PURPOSE_VERIFY = 8,
OH_HUKS_KEY_PURPOSE_DERIVE = 16,
OH_HUKS_KEY_PURPOSE_WRAP = 32,
OH_HUKS_KEY_PURPOSE_UNWRAP = 64,
OH_HUKS_KEY_PURPOSE_MAC = 128,
OH_HUKS_KEY_PURPOSE_AGREE = 256
} | Enumerates the key purposes. | +| [OH_Huks_KeyDigest](#oh_huks_keydigest) {
OH_HUKS_DIGEST_NONE = 0,
OH_HUKS_DIGEST_MD5 = 1,
OH_HUKS_DIGEST_SM3 = 2,
OH_HUKS_DIGEST_SHA1 = 10,
OH_HUKS_DIGEST_SHA224 = 11,
OH_HUKS_DIGEST_SHA256 = 12,
OH_HUKS_DIGEST_SHA384 = 13,
OH_HUKS_DIGEST_SHA512 = 14
} | Enumerates the digest algorithms. | +| [OH_Huks_KeyPadding](#oh_huks_keypadding) {
OH_HUKS_PADDING_NONE = 0,
OH_HUKS_PADDING_OAEP = 1,
OH_HUKS_PADDING_PSS = 2,
OH_HUKS_PADDING_PKCS1_V1_5 = 3,
OH_HUKS_PADDING_PKCS5 = 4,
OH_HUKS_PADDING_PKCS7 = 5
} | Enumerates the padding algorithms. | +| [OH_Huks_CipherMode](#oh_huks_ciphermode) {
OH_HUKS_MODE_ECB = 1,
OH_HUKS_MODE_CBC = 2,
OH_HUKS_MODE_CTR = 3,
OH_HUKS_MODE_OFB = 4,
OH_HUKS_MODE_CCM = 31,
OH_HUKS_MODE_GCM = 32
} | Enumerates the cipher modes. | +| [OH_Huks_KeySize](#oh_huks_keysize) {
OH_HUKS_RSA_KEY_SIZE_512 = 512,
OH_HUKS_RSA_KEY_SIZE_768 = 768,
OH_HUKS_RSA_KEY_SIZE_1024 = 1024,
OH_HUKS_RSA_KEY_SIZE_2048 = 2048,
OH_HUKS_RSA_KEY_SIZE_3072 = 3072,
OH_HUKS_RSA_KEY_SIZE_4096 = 4096,
OH_HUKS_ECC_KEY_SIZE_224 = 224,
OH_HUKS_ECC_KEY_SIZE_256 = 256,
OH_HUKS_ECC_KEY_SIZE_384 = 384,
OH_HUKS_ECC_KEY_SIZE_521 = 521,
OH_HUKS_AES_KEY_SIZE_128 = 128,
OH_HUKS_AES_KEY_SIZE_192 = 192,
OH_HUKS_AES_KEY_SIZE_256 = 256,
OH_HUKS_AES_KEY_SIZE_512 = 512,
OH_HUKS_CURVE25519_KEY_SIZE_256 = 256,
OH_HUKS_DH_KEY_SIZE_2048 = 2048,
OH_HUKS_DH_KEY_SIZE_3072 = 3072,
OH_HUKS_DH_KEY_SIZE_4096 = 4096,
OH_HUKS_SM2_KEY_SIZE_256 = 256,
OH_HUKS_SM4_KEY_SIZE_128 = 128
} | Enumerates key sizes of different algorithms. | +| [OH_Huks_KeyAlg](#oh_huks_keyalg) {
OH_HUKS_ALG_RSA = 1,
OH_HUKS_ALG_ECC = 2,
OH_HUKS_ALG_DSA = 3,
OH_HUKS_ALG_AES = 20,
OH_HUKS_ALG_HMAC = 50,
OH_HUKS_ALG_HKDF = 51,
OH_HUKS_ALG_PBKDF2 = 52,
OH_HUKS_ALG_ECDH = 100,
OH_HUKS_ALG_X25519 = 101,
OH_HUKS_ALG_ED25519 = 102,
OH_HUKS_ALG_DH = 103,
OH_HUKS_ALG_SM2 = 150,
OH_HUKS_ALG_SM3 = 151,
OH_HUKS_ALG_SM4 = 152
} | Enumerates the algorithms for keys. | +| [OH_Huks_AlgSuite](#oh_huks_algsuite) {
OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING = 1,
OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING = 2
} | Enumerates the algorithm suites for the import of a wrapped key. | +| [OH_Huks_KeyGenerateType](#oh_huks_keygeneratetype) {
OH_HUKS_KEY_GENERATE_TYPE_DEFAULT = 0,
OH_HUKS_KEY_GENERATE_TYPE_DERIVE = 1,
OH_HUKS_KEY_GENERATE_TYPE_AGREE = 2
} | Enumerates the types of the key generated. | +| [OH_Huks_KeyFlag](#oh_huks_keyflag) {
OH_HUKS_KEY_FLAG_IMPORT_KEY = 1,
OH_HUKS_KEY_FLAG_GENERATE_KEY = 2,
OH_HUKS_KEY_FLAG_AGREE_KEY = 3,
OH_HUKS_KEY_FLAG_DERIVE_KEY = 4
} | Enumerates the key generation types. | +| [OH_Huks_KeyStorageType](#oh_huks_keystoragetype) {
OH_HUKS_STORAGE_TEMP = 0,
OH_HUKS_STORAGE_PERSISTENT = 1,
OH_HUKS_STORAGE_ONLY_USED_IN_HUKS = 2,
OH_HUKS_STORAGE_KEY_EXPORT_ALLOWED = 3
} | Enumerates the key storage types. | +| [OH_Huks_ImportKeyType](#oh_huks_importkeytype) {
OH_HUKS_KEY_TYPE_PUBLIC_KEY = 0,
OH_HUKS_KEY_TYPE_PRIVATE_KEY = 1,
OH_HUKS_KEY_TYPE_KEY_PAIR = 2
} | Enumerates the types of the key to import. By default, a public key is imported. This field is not required when a symmetric key is imported. | +| [OH_Huks_RsaPssSaltLenType](#oh_huks_rsapsssaltlentype) {
OH_HUKS_RSA_PSS_SALT_LEN_DIGEST = 0, OH_HUKS_RSA_PSS_SALT_LEN_MAX = 1
} | Enumerates the salt length types when the PSS padding mode is used in RSA signing or signature verification.| +| [OH_Huks_ErrCode](#oh_huks_errcode) {
OH_HUKS_SUCCESS = 0,
OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201,
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401,
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801,
OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001,
OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002,
OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003,
OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004,
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005,
OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006,
OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007,
OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008,
OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009,
OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010,
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011,
OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012,
OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013
} | Enumerates the error codes. | +| [OH_Huks_TagType](#oh_huks_tagtype) {
OH_HUKS_TAG_TYPE_INVALID = 0 << 28,
OH_HUKS_TAG_TYPE_INT = 1 << 28,
OH_HUKS_TAG_TYPE_UINT = 2 << 28,
OH_HUKS_TAG_TYPE_ULONG = 3 << 28,
OH_HUKS_TAG_TYPE_BOOL = 4 << 28,
OH_HUKS_TAG_TYPE_BYTES = 5 << 28
} | Enumerates the mask values of the parameter type in the parameter set. | +| [OH_Huks_UserAuthType](#oh_huks_userauthtype) {
OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0,
OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1,
OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2
} | Enumerates the user authentication types in key access control. | +| [OH_Huks_AuthAccessType](#oh_huks_authaccesstype) {
OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0,
OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1
} | Enumerates the rules for invalidating a key. | +| [OH_Huks_ChallengeType](#oh_huks_challengetype) {
OH_HUKS_CHALLENGE_TYPE_NORMAL = 0,
OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1,
OH_HUKS_CHALLENGE_TYPE_NONE = 2
} | Enumerates the types of the challenge generated when a key is used. | +| [OH_Huks_ChallengePosition](#oh_huks_challengeposition) {
OH_HUKS_CHALLENGE_POS_0 = 0,
OH_HUKS_CHALLENGE_POS_1,
OH_HUKS_CHALLENGE_POS_2,
OH_HUKS_CHALLENGE_POS_3
} | Enumerates the positions of the 8-byte valid value in a custom challenge generated. | +| [OH_Huks_SecureSignType](#oh_huks_securesigntype) { OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1 } | Enumerates the signature types of the key generated or imported. | +| [OH_Huks_Tag](#oh_huks_tag) {
OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT \| 1, OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 2, OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 3,
OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT \| 4, OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT \| 5, OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT \| 6, OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 7,
OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES \| 8, OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES \| 9, OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES \| 10, OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES \| 11,
OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES \| 12, OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT \| 14, OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 15, OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT \| 19,
OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 20, OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 21, OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES \| 22, OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 23,
OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 24, OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 25, OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT \| 26, OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 29, OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 30, OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL \| 301,
OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT \| 302, OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL \| 303, OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT \| 304, OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT \| 305,
OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES \| 306, OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT \| 307, OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 308, OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 309,
OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT \| 310, OH_HUKS_TAG_KEY_AUTH_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 311, OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES \| 501, OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES \| 502, OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 511,
OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES \| 514, OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES \| 515,
OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 1001, OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1002, OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL \| 1003, OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT \| 1004,
OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES \| 1005, OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT \| 1006, OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1007, OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT \| 1008,
OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT \| 1011, OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20001,
OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20002, OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20003
} | Enumerates the tag values used in the parameter set. | ## Enum Description @@ -91,416 +92,463 @@ Defines the macros, enumerated values, data structures, and error codes used by ### OH_Huks_AlgSuite - + ``` enum OH_Huks_AlgSuite ``` -**Description**
-Enumerates the algorithm suites required for ciphertext imports. +**Description** + +Enumerates the algorithm suites for the import of a wrapped key. -| Name | Description | +| Value| Description| | -------- | -------- | -| OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING | Key material format (Length-Value format), X25519 key agreement, and AES-256-GCM encryption and decryption. \| x25519_plain_pubkey_length (4 Byte) \| x25519_plain_pubkey \| agreekey_aad_length (4 Byte) \| agreekey_aad \| agreekey_nonce_length (4 Byte) \| agreekey_nonce \| agreekey_aead_tag_len(4 Byte) \| agreekey_aead_tag \| kek_enc_data_length (4 Byte) \| kek_enc_data \| kek_aad_length (4 Byte) \| kek_aad \| kek_nonce_length (4 Byte) \| kek_nonce \| kek_aead_tag_len (4 Byte) \| kek_aead_tag \| key_material_size_len (4 Byte) \| key_material_size \| key_mat_enc_length (4 Byte) \| key_mat_enc_data | -| OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING | Key material format (Length-Value format), ECDH-p256 key agreement, and AES-256-GCM encryption and decryption. \| ECC_plain_pubkey_length (4 Byte) \| ECC_plain_pubkey \| agreekey_aad_length (4 Byte) \| agreekey_aad \| agreekey_nonce_length (4 Byte) \| agreekey_nonce \| agreekey_aead_tag_len(4 Byte) \| agreekey_aead_tag \| kek_enc_data_length (4 Byte) \| kek_enc_data \| kek_aad_length (4 Byte) \| kek_aad \| kek_nonce_length (4 Byte) \| kek_nonce \| kek_aead_tag_len (4 Byte) \| kek_aead_tag \| key_material_size_len (4 Byte) \| key_material_size \| key_mat_enc_length (4 Byte) \| key_mat_enc_data | +| OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING | Key material format (Length-Value format), use X25519 for key agreement, and use AES-256-GCM for encryption and decryption: \| x25519_plain_pubkey_length (4 Byte) \| x25519_plain_pubkey \| agreekey_aad_length (4 Byte) \| agreekey_aad \| agreekey_nonce_length (4 Byte) \| agreekey_nonce \| agreekey_aead_tag_len(4 Byte) \| agreekey_aead_tag \| kek_enc_data_length (4 Byte) \| kek_enc_data \| kek_aad_length (4 Byte) \| kek_aad \| kek_nonce_length (4 Byte) \| kek_nonce \| kek_aead_tag_len (4 Byte) \| kek_aead_tag \| key_material_size_len (4 Byte) \| key_material_size \| key_mat_enc_length (4 Byte) \| key_mat_enc_data | +| OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING | Key material format (Length-Value format), use ECDH-p256 for key agreement, and use AES-256-GCM for encryption and decryption: \| ECC_plain_pubkey_length (4 Byte) \| ECC_plain_pubkey \| agreekey_aad_length (4 Byte) \| agreekey_aad \| agreekey_nonce_length (4 Byte) \| agreekey_nonce \| agreekey_aead_tag_len(4 Byte) \| agreekey_aead_tag \| kek_enc_data_length (4 Byte) \| kek_enc_data \| kek_aad_length (4 Byte) \| kek_aad \| kek_nonce_length (4 Byte) \| kek_nonce \| kek_aead_tag_len (4 Byte) \| kek_aead_tag \| key_material_size_len (4 Byte) \| key_material_size \| key_mat_enc_length (4 Byte) \| key_mat_enc_data | ### OH_Huks_AuthAccessType - + ``` enum OH_Huks_AuthAccessType ``` -**Description**
-Enumerates the access control types. +**Description** + +Enumerates the rules for invalidating a key. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | The key is invalid after the password is cleared. | -| OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | The key is invalid after a new biometric feature is enrolled. | +| OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD | The key becomes invalid after the password is cleared.| +| OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL | The key becomes invalid after a new biometric feature is enrolled.| ### OH_Huks_ChallengePosition - + ``` enum OH_Huks_ChallengePosition ``` -**Description**
+**Description** + Enumerates the positions of the 8-byte valid value in a custom challenge generated. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_CHALLENGE_POS_0 | Bytes 0 to 7. | -| OH_HUKS_CHALLENGE_POS_1 | Bytes 8 to 15. | -| OH_HUKS_CHALLENGE_POS_2 | Bytes 16 to 23. | -| OH_HUKS_CHALLENGE_POS_3 | Bytes 24 to 31. | +| OH_HUKS_CHALLENGE_POS_0 | Bytes 0 to 7.| +| OH_HUKS_CHALLENGE_POS_1 | Bytes 8 to 15.| +| OH_HUKS_CHALLENGE_POS_2 | Bytes 16 to 23.| +| OH_HUKS_CHALLENGE_POS_3 | Bytes 24 to 31.| ### OH_Huks_ChallengeType - + ``` enum OH_Huks_ChallengeType ``` -**Description**
-Enumerates the types of the challenges generated when a key is used. +**Description** - **See** +Enumerates the types of the challenge generated when a key is used. + +**See** [OH_Huks_ChallengePosition](#oh_huks_challengeposition) -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_CHALLENGE_TYPE_NORMAL | Normal challenge, which is of 32 bytes by default. | -| OH_HUKS_CHALLENGE_TYPE_CUSTOM | Custom challenge, which supports only one authentication for multiple keys. The valid value of a custom challenge is of 8 bytes. | -| OH_HUKS_CHALLENGE_TYPE_NONE | Challenge is not required. | +| OH_HUKS_CHALLENGE_TYPE_NORMAL | Normal challenge, which is of 32 bytes by default.| +| OH_HUKS_CHALLENGE_TYPE_CUSTOM | Custom challenge, which supports only one authentication for multiple keys. The valid value of a custom challenge is of 8 bytes.| +| OH_HUKS_CHALLENGE_TYPE_NONE | Challenge is not required.| ### OH_Huks_CipherMode - + ``` enum OH_Huks_CipherMode ``` -**Description**
+**Description** + Enumerates the cipher modes. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_MODE_ECB | Electronic Code Block (ECB) mode. | -| OH_HUKS_MODE_CBC | Cipher Block Chaining (CBC) mode. | -| OH_HUKS_MODE_CTR | Counter (CTR) mode. | -| OH_HUKS_MODE_OFB | Output Feedback (OFB) mode. | -| OH_HUKS_MODE_CCM | Counter with CBC-MAC (CCM) mode. | -| OH_HUKS_MODE_GCM | Galois/Counter (GCM) mode. | +| OH_HUKS_MODE_ECB | Electronic Code Block (ECB) mode.| +| OH_HUKS_MODE_CBC | Cipher Block Chaining (CBC) mode.| +| OH_HUKS_MODE_CTR | Counter (CTR) mode.| +| OH_HUKS_MODE_OFB | Output Feedback (OFB) mode.| +| OH_HUKS_MODE_CCM | Counter with CBC-MAC (CCM) mode.| +| OH_HUKS_MODE_GCM | Galois/Counter (GCM) mode.| + + +### OH_Huks_RsaPssSaltLenType + +``` +enum OH_Huks_RsaPssSaltLenType +``` +**Description** + +Enumerates the types of the salt length when the PSS padding mode is used in RSA signing or signature verification. + +**Since**: +10 + +| Name | Description| +| -------- | -------- | +| OH_HUKS_RSA_PSS_SALT_LEN_DIGEST | The salt length is set to the digest length.| +| OH_HUKS_RSA_PSS_SALT_LEN_MAX | The salt length is set to the maximum length.| ### OH_Huks_ErrCode - + ``` enum OH_Huks_ErrCode ``` -**Description**
+**Description** + Enumerates the error codes. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_SUCCESS | The operation is successful. | -| OH_HUKS_ERR_CODE_PERMISSION_FAIL | Permission verification failed. | -| OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT | Invalid parameters are detected. | -| OH_HUKS_ERR_CODE_NOT_SUPPORTED_API | The API is not supported. | -| OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED | The feature is not supported. | -| OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT | Key algorithm parameters are missing. | -| OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT | Invalid key algorithm parameters are detected. | -| OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL | Failed to operate the file. | -| OH_HUKS_ERR_CODE_COMMUNICATION_FAIL | The process communication failed. | -| OH_HUKS_ERR_CODE_CRYPTO_FAIL | Failed to operate the algorithm library. | -| OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED | Failed to access the key because the key has expired. | -| OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED | Failed to access the key because the authentication has failed. | -| OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT | Key access timed out. | -| OH_HUKS_ERR_CODE_SESSION_LIMIT | The number of key operation sessions has reached the limit. | -| OH_HUKS_ERR_CODE_ITEM_NOT_EXIST | The entity does not exist. | -| OH_HUKS_ERR_CODE_INTERNAL_ERROR | Internal error. | -| OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST | The authentication credential does not exist. | +| OH_HUKS_SUCCESS | Success.| +| OH_HUKS_ERR_CODE_PERMISSION_FAIL | Permission verification failed.| +| OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT | Invalid parameter (universal).| +| OH_HUKS_ERR_CODE_NOT_SUPPORTED_API | The API is not supported.| +| OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED | The feature is not supported.| +| OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT | Key algorithm parameters are missing.| +| OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT | Invalid key algorithm parameter.| +| OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL | File operation failed.| +| OH_HUKS_ERR_CODE_COMMUNICATION_FAIL | The process communication failed.| +| OH_HUKS_ERR_CODE_CRYPTO_FAIL | Failed to operate the crypto algorithm library.| +| OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED | Failed to access the key because the key has expired.| +| OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED | Failed to access the key because the authentication has failed.| +| OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT | Key access timed out.| +| OH_HUKS_ERR_CODE_SESSION_LIMIT | The number of key operation sessions has reached the limit.| +| OH_HUKS_ERR_CODE_ITEM_NOT_EXIST | The entity does not exist.| +| OH_HUKS_ERR_CODE_INTERNAL_ERROR | Internal error.| +| OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST | The authentication credential does not exist.| ### OH_Huks_ImportKeyType - + ``` enum OH_Huks_ImportKeyType ``` -**Description**
-Enumerates the types of keys to import. By default, a public key is imported. This field is not required when a symmetric key is imported. +**Description** -| Name | Description | +Enumerates the types of the key to import. By default, a public key is imported. This field is not required when a symmetric key is imported. + +| Name | Description| | -------- | -------- | -| OH_HUKS_KEY_TYPE_PUBLIC_KEY | Public key. | -| OH_HUKS_KEY_TYPE_PRIVATE_KEY | Private key. | -| OH_HUKS_KEY_TYPE_KEY_PAIR | Public and private key pair. | +| OH_HUKS_KEY_TYPE_PUBLIC_KEY | Public key.| +| OH_HUKS_KEY_TYPE_PRIVATE_KEY | Private key.| +| OH_HUKS_KEY_TYPE_KEY_PAIR | Public and private key pair.| ### OH_Huks_KeyAlg - + ``` enum OH_Huks_KeyAlg ``` -**Description**
-Enumerates the key algorithms. +**Description** + +Enumerates the algorithms for keys. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_ALG_RSA | RSA. | -| OH_HUKS_ALG_ECC | ECC. | -| OH_HUKS_ALG_DSA | DSA. | -| OH_HUKS_ALG_AES | AES. | -| OH_HUKS_ALG_HMAC | HMAC. | -| OH_HUKS_ALG_HKDF | HKDF. | -| OH_HUKS_ALG_PBKDF2 | PBKDF2. | -| OH_HUKS_ALG_ECDH | ECDH. | -| OH_HUKS_ALG_X25519 | X25519. | -| OH_HUKS_ALG_ED25519 | Ed25519. | -| OH_HUKS_ALG_DH | DH. | -| OH_HUKS_ALG_SM2 | SM2. | -| OH_HUKS_ALG_SM3 | SM3. | -| OH_HUKS_ALG_SM4 | SM4. | +| OH_HUKS_ALG_RSA | RSA.| +| OH_HUKS_ALG_ECC | ECC.| +| OH_HUKS_ALG_DSA | DSA.| +| OH_HUKS_ALG_AES | Advanced Encryption Standard (AES).| +| OH_HUKS_ALG_HMAC | HMAC algorithm.| +| OH_HUKS_ALG_HKDF | HKDF.| +| OH_HUKS_ALG_PBKDF2 | PBKDF2.| +| OH_HUKS_ALG_ECDH | ECDH.| +| OH_HUKS_ALG_X25519 | X25519.| +| OH_HUKS_ALG_ED25519 | Ed25519.| +| OH_HUKS_ALG_DH | DH.| +| OH_HUKS_ALG_SM2 | ShangMi2 (SM2).| +| OH_HUKS_ALG_SM3 | SM3.| +| OH_HUKS_ALG_SM4 | ShangMi4 (SM4).| ### OH_Huks_KeyDigest - + ``` enum OH_Huks_KeyDigest ``` -**Description**
+**Description** + Enumerates the digest algorithms. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_DIGEST_NONE | No digest algorithm. | -| OH_HUKS_DIGEST_MD5 | MD5. | -| OH_HUKS_DIGEST_SM3 | SM3. | -| OH_HUKS_DIGEST_SHA1 | SHA-1. | -| OH_HUKS_DIGEST_SHA224 | SHA-224. | -| OH_HUKS_DIGEST_SHA256 | SHA-256. | -| OH_HUKS_DIGEST_SHA384 | SHA-384. | -| OH_HUKS_DIGEST_SHA512 | SHA-512. | +| OH_HUKS_DIGEST_NONE | No digest algorithm.| +| OH_HUKS_DIGEST_MD5 | MD5.| +| OH_HUKS_DIGEST_SM3 | SM3.| +| OH_HUKS_DIGEST_SHA1 | SHA-1.| +| OH_HUKS_DIGEST_SHA224 | SHA-224.| +| OH_HUKS_DIGEST_SHA256 | SHA-256.| +| OH_HUKS_DIGEST_SHA384 | SHA-384.| +| OH_HUKS_DIGEST_SHA512 | SHA-512.| ### OH_Huks_KeyFlag - + ``` enum OH_Huks_KeyFlag ``` -**Description**
-Enumerates the key generation modes. +**Description** -| Name | Description | +Enumerates the key generation types. + +| Name | Description| | -------- | -------- | -| OH_HUKS_KEY_FLAG_IMPORT_KEY | Import a public key using an API. | -| OH_HUKS_KEY_FLAG_GENERATE_KEY | Generate a key by using an API. | -| OH_HUKS_KEY_FLAG_AGREE_KEY | Generate a key by using a key agreement API. | -| OH_HUKS_KEY_FLAG_DERIVE_KEY | Derive a key by using an API. | +| OH_HUKS_KEY_FLAG_IMPORT_KEY | Import a public key using an API.| +| OH_HUKS_KEY_FLAG_GENERATE_KEY | Generate a key by using an API.| +| OH_HUKS_KEY_FLAG_AGREE_KEY | Generate a key by using a key agreement API.| +| OH_HUKS_KEY_FLAG_DERIVE_KEY | Derive a key by using an API.| ### OH_Huks_KeyGenerateType - + ``` enum OH_Huks_KeyGenerateType ``` -**Description**
-Enumerates the key generation types. +**Description** -| Name | Description | +Enumerates the types of the key generated. + +| Name | Description| | -------- | -------- | -| OH_HUKS_KEY_GENERATE_TYPE_DEFAULT | Key generated by default. | -| OH_HUKS_KEY_GENERATE_TYPE_DERIVE | Derived key. | -| OH_HUKS_KEY_GENERATE_TYPE_AGREE | Key obtained by key agreement. | +| OH_HUKS_KEY_GENERATE_TYPE_DEFAULT | Key generated by default.| +| OH_HUKS_KEY_GENERATE_TYPE_DERIVE | Derived key.| +| OH_HUKS_KEY_GENERATE_TYPE_AGREE | Key generated by key agreement.| ### OH_Huks_KeyPadding - + ``` enum OH_Huks_KeyPadding ``` -**Description**
+**Description** + Enumerates the padding algorithms. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_PADDING_NONE | No padding algorithm. | -| OH_HUKS_PADDING_OAEP | Optimal Asymmetric Encryption Padding (OAEP). | -| OH_HUKS_PADDING_PSS | Probabilistic Signature Scheme (PSS). | -| OH_HUKS_PADDING_PKCS1_V1_5 | Public Key Cryptography Standards (PKCS) \#1 v1.5. | -| OH_HUKS_PADDING_PKCS5 | PKCS \#5. | -| OH_HUKS_PADDING_PKCS7 | PKCS \#7. | +| OH_HUKS_PADDING_NONE | No padding algorithm.| +| OH_HUKS_PADDING_OAEP | Optimal Asymmetric Encryption Padding (OAEP).| +| OH_HUKS_PADDING_PSS | Probabilistic Signature Scheme (PSS).| +| OH_HUKS_PADDING_PKCS1_V1_5 | Public Key Cryptography Standards (PKCS) #1 v1.5.| +| OH_HUKS_PADDING_PKCS5 | PKCS #5.| +| OH_HUKS_PADDING_PKCS7 | PKCS #7.| ### OH_Huks_KeyPurpose - + ``` enum OH_Huks_KeyPurpose ``` -**Description**
+**Description** + Enumerates the key purposes. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_KEY_PURPOSE_ENCRYPT | Used to encrypt the plaintext. | -| OH_HUKS_KEY_PURPOSE_DECRYPT | Used to decrypt the cipher text. | -| OH_HUKS_KEY_PURPOSE_SIGN | Used to sign data. | -| OH_HUKS_KEY_PURPOSE_VERIFY | Used to verify the signature. | -| OH_HUKS_KEY_PURPOSE_DERIVE | Used to derive a key. | -| OH_HUKS_KEY_PURPOSE_WRAP | Used for an encrypted export. | -| OH_HUKS_KEY_PURPOSE_UNWRAP | Used for an encrypted import. | -| OH_HUKS_KEY_PURPOSE_MAC | Used to generate a message authentication code (MAC). | -| OH_HUKS_KEY_PURPOSE_AGREE | Used for key agreement. | +| OH_HUKS_KEY_PURPOSE_ENCRYPT | Used to encrypt the plaintext.| +| OH_HUKS_KEY_PURPOSE_DECRYPT | Used to decrypt the cipher text.| +| OH_HUKS_KEY_PURPOSE_SIGN | Used for signing.| +| OH_HUKS_KEY_PURPOSE_VERIFY | Used to verify the signature.| +| OH_HUKS_KEY_PURPOSE_DERIVE | Used to derive a key.| +| OH_HUKS_KEY_PURPOSE_WRAP | Used for an encrypted export.| +| OH_HUKS_KEY_PURPOSE_UNWRAP | Used for an encrypted import.| +| OH_HUKS_KEY_PURPOSE_MAC | Used to generate a message authentication code (MAC).| +| OH_HUKS_KEY_PURPOSE_AGREE | Used for key agreement.| ### OH_Huks_KeySize - + ``` enum OH_Huks_KeySize ``` -**Description**
-Enumerates the key sizes. +**Description** -| Name | Description | +Enumerates key sizes of different algorithms. + +| Name | Description| | -------- | -------- | -| OH_HUKS_RSA_KEY_SIZE_512 | Rivest-Shamir-Adleman (RSA) key of 512 bits. | -| OH_HUKS_RSA_KEY_SIZE_768 | RSA key of 768 bits. | -| OH_HUKS_RSA_KEY_SIZE_1024 | RSA key of 1024 bits. | -| OH_HUKS_RSA_KEY_SIZE_2048 | RSA key of 2048 bits. | -| OH_HUKS_RSA_KEY_SIZE_3072 | RSA key of 3072 bits. | -| OH_HUKS_RSA_KEY_SIZE_4096 | RSA key of 4096 bits. | -| OH_HUKS_ECC_KEY_SIZE_224 | Elliptic Curve Cryptography (ECC) key of 224 bits. | -| OH_HUKS_ECC_KEY_SIZE_256 | ECC key of 256 bits. | -| OH_HUKS_ECC_KEY_SIZE_384 | ECC key of 384 bits. | -| OH_HUKS_ECC_KEY_SIZE_521 | ECC key of 521 bits. | -| OH_HUKS_AES_KEY_SIZE_128 | Advanced Encryption Standard (AES) key of 128 bits. | -| OH_HUKS_AES_KEY_SIZE_192 | AES key of 192 bits. | -| OH_HUKS_AES_KEY_SIZE_256 | AES key of 256 bits. | -| OH_HUKS_AES_KEY_SIZE_512 | AES key of 512 bits. | -| OH_HUKS_CURVE25519_KEY_SIZE_256 | Curve25519 key of 256 bits. | -| OH_HUKS_DH_KEY_SIZE_2048 | Diffie-Hellman (DH) key of 2048 bits. | -| OH_HUKS_DH_KEY_SIZE_3072 | DH key of 3072 bits. | -| OH_HUKS_DH_KEY_SIZE_4096 | DH key of 4096 bits. | -| OH_HUKS_SM2_KEY_SIZE_256 | ShangMi2 (SM2) key of 256 bits. | -| OH_HUKS_SM4_KEY_SIZE_128 | ShangMi4 (SM4) key of 128 bits. | +| OH_HUKS_RSA_KEY_SIZE_512 | Rivest-Shamir-Adleman (RSA) key of 512 bits.| +| OH_HUKS_RSA_KEY_SIZE_768 | RSA key of 768 bits.| +| OH_HUKS_RSA_KEY_SIZE_1024 | RSA key of 1024 bits.| +| OH_HUKS_RSA_KEY_SIZE_2048 | RSA key of 2048 bits.| +| OH_HUKS_RSA_KEY_SIZE_3072 | RSA key of 3072 bits.| +| OH_HUKS_RSA_KEY_SIZE_4096 | RSA key of 4096 bits.| +| OH_HUKS_ECC_KEY_SIZE_224 | ECC key of 224 bits.| +| OH_HUKS_ECC_KEY_SIZE_256 | ECC key of 256 bits.| +| OH_HUKS_ECC_KEY_SIZE_384 | ECC key of 384 bits.| +| OH_HUKS_ECC_KEY_SIZE_521 | ECC key of 521 bits.| +| OH_HUKS_AES_KEY_SIZE_128 | AES key of 128 bits.| +| OH_HUKS_AES_KEY_SIZE_192 | AES key of 192 bits.| +| OH_HUKS_AES_KEY_SIZE_256 | AES key of 256 bits.| +| OH_HUKS_AES_KEY_SIZE_512 | AES key of 512 bits.| +| OH_HUKS_CURVE25519_KEY_SIZE_256 | Curve25519 key of 256 bits.| +| OH_HUKS_DH_KEY_SIZE_2048 | DH key of 2048 bits.| +| OH_HUKS_DH_KEY_SIZE_3072 | DH key of 3072 bits.| +| OH_HUKS_DH_KEY_SIZE_4096 | DH key of 4096 bits.| +| OH_HUKS_SM2_KEY_SIZE_256 | SM2 key of 256 bits.| +| OH_HUKS_SM4_KEY_SIZE_128 | SM4 key of 128 bits.| ### OH_Huks_KeyStorageType - + ``` enum OH_Huks_KeyStorageType ``` -**Description**
-Enumerates the key storage modes. +**Description** + +Enumerates the key storage types. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_STORAGE_TEMP | The key is managed locally. | -| OH_HUKS_STORAGE_PERSISTENT | The key is managed by the HUKS service. | +| OH_HUKS_STORAGE_TEMP | The key is managed locally.| +| OH_HUKS_STORAGE_PERSISTENT | The key is managed by the HUKS service.| +| OH_HUKS_STORAGE_ONLY_USED_IN_HUKS | The key is stored only in the HUKS.| +| OH_HUKS_STORAGE_KEY_EXPORT_ALLOWED | The key is exported from the HUKS and is not stored.| ### OH_Huks_SecureSignType - + ``` enum OH_Huks_SecureSignType ``` -**Description**
-Enumerates the signature types of the keys generated or imported. +**Description** + +Enumerates the signature types of the key generated or imported. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_SECURE_SIGN_WITH_AUTHINFO | The signature carries authentication information. This field is specified when a key is generated or imported. When the key is used to sign data, the data will be added with the authentication information and then be signed. | +| OH_HUKS_SECURE_SIGN_WITH_AUTHINFO | The signature carries authentication information. This field is specified when a key is generated or imported. When the key is used for signing, the data will be added with the authentication information and then be signed.| ### OH_Huks_Tag - + ``` enum OH_Huks_Tag ``` -**Description**
-Enumerates the tag values used in parameter sets. - -| Name | Description | -| -------- | -------- | -| OH_HUKS_TAG_ALGORITHM | Tags for key parameters. The value range is 1 to 200. Algorithm. | -| OH_HUKS_TAG_PURPOSE | Key purpose. | -| OH_HUKS_TAG_KEY_SIZE | Key size. | -| OH_HUKS_TAG_DIGEST | Digest algorithm. | -| OH_HUKS_TAG_PADDING | Padding algorithm. | -| OH_HUKS_TAG_BLOCK_MODE | Cipher mode. | -| OH_HUKS_TAG_KEY_TYPE | Key type. | -| OH_HUKS_TAG_ASSOCIATED_DATA | Associated authentication data. | -| OH_HUKS_TAG_NONCE | Field for key encryption and decryption. | -| OH_HUKS_TAG_IV | Initialized vector (IV). | -| OH_HUKS_TAG_INFO | Information generated during key derivation. | -| OH_HUKS_TAG_SALT | Salt value used for key derivation. | -| OH_HUKS_TAG_ITERATION | Number of iterations for key derivation. | -| OH_HUKS_TAG_KEY_GENERATE_TYPE | Type of the generated key. For details, see [OH_Huks_KeyGenerateType](#oh_huks_keygeneratetype). | -| OH_HUKS_TAG_AGREE_ALG | Algorithm used in key agreement. | -| OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | Alias of the public key used for key agreement. | -| OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | Alias of the private key used for key agreement. | -| OH_HUKS_TAG_AGREE_PUBLIC_KEY | Public key used for key agreement. | -| OH_HUKS_TAG_KEY_ALIAS | Alias of the key. | -| OH_HUKS_TAG_DERIVE_KEY_SIZE | Size of the derived key. | -| OH_HUKS_TAG_IMPORT_KEY_TYPE | Type of the key to import. For details, see [OH_Huks_ImportKeyType](#oh_huks_importkeytype). | -| OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE | Algorithm suite required for encrypted imports. | -| OH_HUKS_TAG_ALL_USERS | Tags for access control and user authentication. The value range is 301 to 500. All users in the multi-user scenario. | -| OH_HUKS_TAG_USER_ID | Multi-user ID. | -| OH_HUKS_TAG_NO_AUTH_REQUIRED | Specifies whether key access control is required. | -| OH_HUKS_TAG_USER_AUTH_TYPE | User authentication type in key access control. | -| OH_HUKS_TAG_AUTH_TIMEOUT | Timeout duration for key access. | -| OH_HUKS_TAG_AUTH_TOKEN | Authentication token for the key. | -| OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE | Access control type. For details, see [OH_Huks_AuthAccessType](#oh_huks_authaccesstype). This parameter must be set together with the user authentication type. | -| OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE | Signature type for the key to be generated or imported. | -| OH_HUKS_TAG_CHALLENGE_TYPE | Challenge type. For details, see [OH_Huks_ChallengeType](#oh_huks_challengetype). | -| OH_HUKS_TAG_CHALLENGE_POS | Position of the 8-byte valid value in a custom challenge. For details, see [OH_Huks_ChallengePosition](#oh_huks_challengeposition). | -| OH_HUKS_TAG_ATTESTATION_CHALLENGE | Tags for key attestation. The value range is 501 to 600. Challenge value used in the attestation. | -| OH_HUKS_TAG_ATTESTATION_APPLICATION_ID | Application ID used in the attestation. | -| OH_HUKS_TAG_ATTESTATION_ID_ALIAS | Alias of the key. | -| OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | Security level used in the attestation. | -| OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO | Version information used in the attestation. | -| OH_HUKS_TAG_IS_KEY_ALIAS | 601 to 1000 are reserved for other tags.
Extended tags. The value range is 1001 to 9999. Specifies whether it is a key alias. | -| OH_HUKS_TAG_KEY_STORAGE_FLAG | Key storage mode. For details, see [OH_Huks_KeyStorageType](#oh_huks_keystoragetype). | -| OH_HUKS_TAG_IS_ALLOWED_WRAP | Specifies whether to allow the key to be wrapped. | -| OH_HUKS_TAG_KEY_WRAP_TYPE | Key wrap type. | -| OH_HUKS_TAG_KEY_AUTH_ID | Authentication ID. | -| OH_HUKS_TAG_KEY_ROLE | Role of the key. | -| OH_HUKS_TAG_KEY_FLAG | Key flag. For details, see [OH_Huks_KeyFlag](#oh_huks_keyflag). | -| OH_HUKS_TAG_IS_ASYNCHRONIZED | Specifies whether this API is asynchronous. | -| OH_HUKS_TAG_KEY_DOMAIN | Key domain. | -| OH_HUKS_TAG_SYMMETRIC_KEY_DATA | 11000 to 12000 are reserved.
20001 to N are reserved for other tags. Symmetric key data. | -| OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | Public key data of the asymmetric key pair. | -| OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | Private key data of the asymmetric key pair. | +**Description** + +Enumerates the tag values used in the parameter set. + +| Name | Description| +| :------- | -------- | +| Tags for key parameters: 1 to 200 | | +| OH_HUKS_TAG_ALGORITHM | Algorithm type. | +| OH_HUKS_TAG_PURPOSE | Key purpose.| +| OH_HUKS_TAG_KEY_SIZE | Key length.| +| OH_HUKS_TAG_DIGEST | Digest algorithm.| +| OH_HUKS_TAG_PADDING | Padding algorithm.| +| OH_HUKS_TAG_BLOCK_MODE | Cipher mode.| +| OH_HUKS_TAG_KEY_TYPE | Key type.| +| OH_HUKS_TAG_ASSOCIATED_DATA | Associated authentication data.| +| OH_HUKS_TAG_NONCE | Field for key encryption and decryption.| +| OH_HUKS_TAG_IV | Initialized vector (IV).| +| OH_HUKS_TAG_INFO | Information generated during key derivation.| +| OH_HUKS_TAG_SALT | Salt value used for key derivation.| +| OH_HUKS_TAG_ITERATION | Number of iterations for key derivation.| +| OH_HUKS_TAG_KEY_GENERATE_TYPE | Type of the generated key. For details, see [OH_Huks_KeyGenerateType](#oh_huks_keygeneratetype).| +| OH_HUKS_TAG_AGREE_ALG | Algorithm used in key agreement.| +| OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS | Alias of the public key used for key agreement.| +| OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS | Alias of the private key used for key agreement.| +| OH_HUKS_TAG_AGREE_PUBLIC_KEY | Public key used for key agreement.| +| OH_HUKS_TAG_KEY_ALIAS | Key alias.| +| OH_HUKS_TAG_DERIVE_KEY_SIZE | Size of the derived key.| +| OH_HUKS_TAG_IMPORT_KEY_TYPE | Type of the key to import. For details, see {@link OH_Huks_ImportKeyType}.| +| OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE | Algorithm suite required for encrypted imports.| +| OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG | Storage type of the derived/agreed key.| +| OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE | Salt length type when the PSS padding mode is used for the RSA algorithm.| +| Tags for key access control and authentication: 300 to 500 | | +| OH_HUKS_TAG_ALL_USERS | All users in multi-user scenarios. | +| OH_HUKS_TAG_USER_ID | Multi-user ID.| +| OH_HUKS_TAG_NO_AUTH_REQUIRED | Whether key access control is required.| +| OH_HUKS_TAG_USER_AUTH_TYPE | User authentication type in key access control.| +| OH_HUKS_TAG_AUTH_TIMEOUT | Timeout duration for key access.| +| OH_HUKS_TAG_AUTH_TOKEN | Authentication token for the key.| +| OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE | Access control type. For details, see {@link OH_Huks_AuthAccessType}. This parameter must be set together with the user authentication type.| +| OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE | Signature type of the key generated or imported.| +| OH_HUKS_TAG_CHALLENGE_TYPE | Type of the challenge generated for a key. For details, see {@link OH_Huks_ChallengeType}.| +| OH_HUKS_TAG_CHALLENGE_POS | Position of the 8-byte valid value in a custom challenge. For details, see {@link OH_Huks_ChallengePosition}.| +| H_HUKS_TAG_KEY_AUTH_PURPOSE | Type of the key authentication purpose.| +| Tags for key attestation: 501 to 600 | | +| OH_HUKS_TAG_ATTESTATION_CHALLENGE | Challenge value used for key attestation. | +| OH_HUKS_TAG_ATTESTATION_APPLICATION_ID | ID of the application, to which the key belongs, in key attestation.| +| OH_HUKS_TAG_ATTESTATION_ID_ALIAS | Key alias.| +| OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO | Security level used in key attestation.| +| OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO | Version information used in key attestation.| +| 601 to 1000 are reserved. Extended tags: 1001 to 9999 | | +| OH_HUKS_TAG_IS_KEY_ALIAS | Whether the key alias is used. | +| OH_HUKS_TAG_KEY_STORAGE_FLAG | Key storage mode. For details, see [OH_Huks_KeyStorageType](#oh_huks_keystoragetype).| +| OH_HUKS_TAG_IS_ALLOWED_WRAP | Whether to allow the key to be wrapped.| +| OH_HUKS_TAG_KEY_WRAP_TYPE | Key wrap type.| +| OH_HUKS_TAG_KEY_AUTH_ID | Authentication ID.| +| OH_HUKS_TAG_KEY_ROLE | Role of the key.| +| OH_HUKS_TAG_KEY_FLAG | Key flag. For details, see [OH_Huks_KeyFlag](#oh_huks_keyflag).| +| OH_HUKS_TAG_IS_ASYNCHRONIZED | Whether the invocation is asynchronous.| +| OH_HUKS_TAG_KEY_DOMAIN | Key domain.| +| 11000 to 12000 are reserved. Reserved values for other tags: 20001 - N | | +| OH_HUKS_TAG_SYMMETRIC_KEY_DATA | Symmetric key data. | +| OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA | Public key data of the asymmetric key pair.| +| OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA | Private key data of the asymmetric key pair.| ### OH_Huks_TagType - + ``` enum OH_Huks_TagType ``` -**Description**
-Enumerates the tag types. +**Description** - **See** +Enumerates the mask values of the parameter type in the parameter set. + +**See** [OH_Huks_Param](_o_h___huks___param.md) -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_TAG_TYPE_INVALID | Invalid tag type. | -| OH_HUKS_TAG_TYPE_INT | int32_t. | -| OH_HUKS_TAG_TYPE_UINT | uin32_t. | -| OH_HUKS_TAG_TYPE_ULONG | uin64_t. | -| OH_HUKS_TAG_TYPE_BOOL | Boolean. | -| OH_HUKS_TAG_TYPE_BYTES | [OH_Huks_Blob](_o_h___huks___blob.md). | +| OH_HUKS_TAG_TYPE_INVALID | Invalid tag type.| +| OH_HUKS_TAG_TYPE_INT | int32_t.| +| OH_HUKS_TAG_TYPE_UINT | uin32_t.| +| OH_HUKS_TAG_TYPE_ULONG | uin64_t.| +| OH_HUKS_TAG_TYPE_BOOL | Boolean.| +| OH_HUKS_TAG_TYPE_BYTES | OH_Huks_Blob.| ### OH_Huks_UserAuthType - + ``` enum OH_Huks_UserAuthType ``` -**Description**
-Enumerates the user authentication types. +**Description** + +Enumerates the user authentication types in key access control. -| Name | Description | +| Name | Description| | -------- | -------- | -| OH_HUKS_USER_AUTH_TYPE_FINGERPRINT | Fingerprint authentication. | -| OH_HUKS_USER_AUTH_TYPE_FACE | Facial authentication. | -| OH_HUKS_USER_AUTH_TYPE_PIN | PIN authentication. | +| OH_HUKS_USER_AUTH_TYPE_FINGERPRINT | Fingerprint authentication.| +| OH_HUKS_USER_AUTH_TYPE_FACE | Facial authentication.| +| OH_HUKS_USER_AUTH_TYPE_PIN | PIN authentication.| diff --git a/en/application-dev/reference/native-apis/native__huks__type_8h.md b/en/application-dev/reference/native-apis/native__huks__type_8h.md index caa129bf8f4d97fdf18e2e333998e536b84bbbba..6b5368fefeb2f9647ca419446891d0f7d8adbc95 100644 --- a/en/application-dev/reference/native-apis/native__huks__type_8h.md +++ b/en/application-dev/reference/native-apis/native__huks__type_8h.md @@ -3,12 +3,12 @@ ## Overview -Defines the enumerated variables, structures, and macros used in the HUKS APIs. +Defines the enumerated variables, structs, and macros used in the HUKS APIs. -**Since:** + **Since** 9 -**Related Modules:** +**Related Modules** [HuksTypeApi](_huks_type_api.md) @@ -18,64 +18,65 @@ Defines the enumerated variables, structures, and macros used in the HUKS APIs. ### Structs -| Name | Description | +| Name| Description| | -------- | -------- | -| [OH_Huks_Result](_o_h___huks___result.md) | Defines the return data, including the result code and message. | -| [OH_Huks_Blob](_o_h___huks___blob.md) | Defines the structure for storing data. | -| [OH_Huks_Param](_o_h___huks___param.md) | Defines the parameter structure in a parameter set. | -| [OH_Huks_ParamSet](_o_h___huks___param_set.md) | Defines the structure of the parameter set. | -| [OH_Huks_CertChain](_o_h___huks___cert_chain.md) | Defines the structure of the certificate chain. | -| [OH_Huks_KeyInfo](_o_h___huks___key_info.md) | Defines the key information structure. | -| [OH_Huks_PubKeyInfo](_o_h___huks___pub_key_info.md) | Defines the structure of a public key. | -| [OH_Huks_KeyMaterialRsa](_o_h___huks___key_material_rsa.md) | Defines the structure of an RSA key. | -| [OH_Huks_KeyMaterialEcc](_o_h___huks___key_material_ecc.md) | Defines the structure of an ECC key. | -| [OH_Huks_KeyMaterialDsa](_o_h___huks___key_material_dsa.md) | Defines the structure of a DSA key. | -| [OH_Huks_KeyMaterialDh](_o_h___huks___key_material_dh.md) | Defines the structure of a DH key. | -| [OH_Huks_KeyMaterial25519](_o_h___huks___key_material25519.md) | Defines the structure of a 25519 key. | +| [OH_Huks_Result](_o_h___huks___result.md) | Defines the returned status data, including the return code and message. | +| [OH_Huks_Blob](_o_h___huks___blob.md) | Defines the binary large object (BLOB) that stores data. | +| [OH_Huks_Param](_o_h___huks___param.md) | Defines the structure of the parameters in a parameter set. | +| [OH_Huks_ParamSet](_o_h___huks___param_set.md) | Defines the parameter set information. | +| [OH_Huks_CertChain](_o_h___huks___cert_chain.md) | Defines the certificate chain information. | +| [OH_Huks_KeyInfo](_o_h___huks___key_info.md) | Defines the key information. | +| [OH_Huks_PubKeyInfo](_o_h___huks___pub_key_info.md) | Defines the information of a public key. | +| [OH_Huks_KeyMaterialRsa](_o_h___huks___key_material_rsa.md) | Defines the information of an RSA key. | +| [OH_Huks_KeyMaterialEcc](_o_h___huks___key_material_ecc.md) | Defines the information of an ECC key. | +| [OH_Huks_KeyMaterialDsa](_o_h___huks___key_material_dsa.md) | Defines the information of a DSA key. | +| [OH_Huks_KeyMaterialDh](_o_h___huks___key_material_dh.md) | Defines the information of a DH key. | +| [OH_Huks_KeyMaterial25519](_o_h___huks___key_material25519.md) | Defines the information of a 25519 key. | ### Macros -| Name | Value | +| Name| Value| | -------- | -------- | -| **OH_HUKS_AE_TAG_LEN** | 16 | -| **OH_HUKS_BITS_PER_BYTE** | 8| +| **OH_HUKS_AE_TAG_LEN** | 16| +| **OH_HUKS_BITS_PER_BYTE** |8 | | **OH_HUKS_MAX_KEY_SIZE** | 2048 | | **OH_HUKS_AE_NONCE_LEN** | 12 | | **OH_HUKS_MAX_KEY_ALIAS_LEN** | 64 | -| **OH_HUKS_MAX_PROCESS_NAME_LEN** | 50| -| **OH_HUKS_MAX_RANDOM_LEN** | 1024 | +| **OH_HUKS_MAX_PROCESS_NAME_LEN** | 50 | +| **OH_HUKS_MAX_RANDOM_LEN** | 1024 | | **OH_HUKS_SIGNATURE_MIN_SIZE** | 64 | -| **OH_HUKS_MAX_OUT_BLOB_SIZE** | (5 \* 1024 \* 1024) | +| **OH_HUKS_MAX_OUT_BLOB_SIZE** | (5 \* 1024 \* 1024) | | **OH_HUKS_WRAPPED_FORMAT_MAX_SIZE** | (1024 \* 1024) | | **OH_HUKS_IMPORT_WRAPPED_KEY_TOTAL_BLOBS** | 10 | | **TOKEN_CHALLENGE_LEN** | 32 | | **SHA256_SIGN_LEN** | 32 | -| **TOKEN_SIZE** | 32 | -| **MAX_AUTH_TIMEOUT_SECOND** | 60 | -| **SECURE_SIGN_VERSION** | 0x01000001 | +| **TOKEN_SIZE** | 32 | +| **MAX_AUTH_TIMEOUT_SECOND** | 60 | +| **SECURE_SIGN_VERSION** | 0x01000001| ### Enums -| Name | Description | +| Name| Description| | -------- | -------- | -| [OH_Huks_KeyPurpose](_huks_type_api.md#oh_huks_keypurpose) {
OH_HUKS_KEY_PURPOSE_ENCRYPT = 1, OH_HUKS_KEY_PURPOSE_DECRYPT = 2, OH_HUKS_KEY_PURPOSE_SIGN = 4, OH_HUKS_KEY_PURPOSE_VERIFY = 8,
OH_HUKS_KEY_PURPOSE_DERIVE = 16, OH_HUKS_KEY_PURPOSE_WRAP = 32, OH_HUKS_KEY_PURPOSE_UNWRAP = 64, OH_HUKS_KEY_PURPOSE_MAC = 128,
OH_HUKS_KEY_PURPOSE_AGREE = 256
} | Enumerates the key purposes. | -| [OH_Huks_KeyDigest](_huks_type_api.md#oh_huks_keydigest) {
OH_HUKS_DIGEST_NONE = 0, OH_HUKS_DIGEST_MD5 = 1, OH_HUKS_DIGEST_SM3 = 2, OH_HUKS_DIGEST_SHA1 = 10,
OH_HUKS_DIGEST_SHA224 = 11, OH_HUKS_DIGEST_SHA256 = 12, OH_HUKS_DIGEST_SHA384 = 13, OH_HUKS_DIGEST_SHA512 = 14
} | Enumerates the digest algorithms. | -| [OH_Huks_KeyPadding](_huks_type_api.md#oh_huks_keypadding) {
OH_HUKS_PADDING_NONE = 0, OH_HUKS_PADDING_OAEP = 1, OH_HUKS_PADDING_PSS = 2, OH_HUKS_PADDING_PKCS1_V1_5 = 3,
OH_HUKS_PADDING_PKCS5 = 4, OH_HUKS_PADDING_PKCS7 = 5
} | Enumerates the padding algorithms. | -| [OH_Huks_CipherMode](_huks_type_api.md#oh_huks_ciphermode) {
OH_HUKS_MODE_ECB = 1, OH_HUKS_MODE_CBC = 2, OH_HUKS_MODE_CTR = 3, OH_HUKS_MODE_OFB = 4,
OH_HUKS_MODE_CCM = 31, OH_HUKS_MODE_GCM = 32
} | Enumerates the cipher modes. | -| [OH_Huks_KeySize](_huks_type_api.md#oh_huks_keysize) {
OH_HUKS_RSA_KEY_SIZE_512 = 512, OH_HUKS_RSA_KEY_SIZE_768 = 768, OH_HUKS_RSA_KEY_SIZE_1024 = 1024, OH_HUKS_RSA_KEY_SIZE_2048 = 2048,
OH_HUKS_RSA_KEY_SIZE_3072 = 3072, OH_HUKS_RSA_KEY_SIZE_4096 = 4096, OH_HUKS_ECC_KEY_SIZE_224 = 224, OH_HUKS_ECC_KEY_SIZE_256 = 256,
OH_HUKS_ECC_KEY_SIZE_384 = 384, OH_HUKS_ECC_KEY_SIZE_521 = 521, OH_HUKS_AES_KEY_SIZE_128 = 128, OH_HUKS_AES_KEY_SIZE_192 = 192,
OH_HUKS_AES_KEY_SIZE_256 = 256, OH_HUKS_AES_KEY_SIZE_512 = 512, OH_HUKS_CURVE25519_KEY_SIZE_256 = 256, OH_HUKS_DH_KEY_SIZE_2048 = 2048,
OH_HUKS_DH_KEY_SIZE_3072 = 3072, OH_HUKS_DH_KEY_SIZE_4096 = 4096, OH_HUKS_SM2_KEY_SIZE_256 = 256, OH_HUKS_SM4_KEY_SIZE_128 = 128
} | Enumerates the key sizes. | -| [OH_Huks_KeyAlg](_huks_type_api.md#oh_huks_keyalg) {
OH_HUKS_ALG_RSA = 1, OH_HUKS_ALG_ECC = 2, OH_HUKS_ALG_DSA = 3, OH_HUKS_ALG_AES = 20,
OH_HUKS_ALG_HMAC = 50, OH_HUKS_ALG_HKDF = 51, OH_HUKS_ALG_PBKDF2 = 52, OH_HUKS_ALG_ECDH = 100,
OH_HUKS_ALG_X25519 = 101, OH_HUKS_ALG_ED25519 = 102, OH_HUKS_ALG_DH = 103, OH_HUKS_ALG_SM2 = 150,
OH_HUKS_ALG_SM3 = 151, OH_HUKS_ALG_SM4 = 152
} | Enumerates the key algorithms. | -| [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite) { OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING = 1, OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING = 2 } | Enumerates the algorithm suites required for ciphertext imports. | -| [OH_Huks_KeyGenerateType](_huks_type_api.md#oh_huks_keygeneratetype) { OH_HUKS_KEY_GENERATE_TYPE_DEFAULT = 0, OH_HUKS_KEY_GENERATE_TYPE_DERIVE = 1, OH_HUKS_KEY_GENERATE_TYPE_AGREE = 2 } | Enumerates the key generation types. | -| [OH_Huks_KeyFlag](_huks_type_api.md#oh_huks_keyflag) { OH_HUKS_KEY_FLAG_IMPORT_KEY = 1, OH_HUKS_KEY_FLAG_GENERATE_KEY = 2, OH_HUKS_KEY_FLAG_AGREE_KEY = 3, OH_HUKS_KEY_FLAG_DERIVE_KEY = 4 } | Enumerates the key generation modes. | -| [OH_Huks_KeyStorageType](_huks_type_api.md#oh_huks_keystoragetype) { OH_HUKS_STORAGE_TEMP = 0, OH_HUKS_STORAGE_PERSISTENT = 1 } | Enumerates the key storage modes. | -| [OH_Huks_ImportKeyType](_huks_type_api.md#oh_huks_importkeytype) { OH_HUKS_KEY_TYPE_PUBLIC_KEY = 0, OH_HUKS_KEY_TYPE_PRIVATE_KEY = 1, OH_HUKS_KEY_TYPE_KEY_PAIR = 2 } | Enumerates the types of keys to import. By default, a public key is imported. This field is not required when a symmetric key is imported. | -| [OH_Huks_ErrCode](_huks_type_api.md#oh_huks_errcode) {
OH_HUKS_SUCCESS = 0, OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201, OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401, OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801,
OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001, OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002, OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003, OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004,
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005, OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006, OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007, OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008,
OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009, OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010, OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011, OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012,
OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013
} | Enumerates the error codes. | -| [OH_Huks_TagType](_huks_type_api.md#oh_huks_tagtype) {
OH_HUKS_TAG_TYPE_INVALID = 0 << 28, OH_HUKS_TAG_TYPE_INT = 1 << 28, OH_HUKS_TAG_TYPE_UINT = 2 << 28, OH_HUKS_TAG_TYPE_ULONG = 3 << 28,
OH_HUKS_TAG_TYPE_BOOL = 4 << 28, OH_HUKS_TAG_TYPE_BYTES = 5 << 28
} | Enumerates the tag types. | -| [OH_Huks_UserAuthType](_huks_type_api.md#oh_huks_userauthtype) { OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0, OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1, OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2 } | Enumerates the user authentication types. | -| [OH_Huks_AuthAccessType](_huks_type_api.md#oh_huks_authaccesstype) { OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0, OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1 } | Enumerates the access control types. | -| [OH_Huks_ChallengeType](_huks_type_api.md#oh_huks_challengetype) { OH_HUKS_CHALLENGE_TYPE_NORMAL = 0, OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1, OH_HUKS_CHALLENGE_TYPE_NONE = 2 } | Enumerates the types of the challenges generated when a key is used. | -| [OH_Huks_ChallengePosition](_huks_type_api.md#oh_huks_challengeposition) { OH_HUKS_CHALLENGE_POS_0 = 0, OH_HUKS_CHALLENGE_POS_1, OH_HUKS_CHALLENGE_POS_2, OH_HUKS_CHALLENGE_POS_3 } | Enumerates the positions of the 8-byte valid value in a custom challenge generated. | -| [OH_Huks_SecureSignType](_huks_type_api.md#oh_huks_securesigntype) { OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1 } | Enumerates the signature types of the keys generated or imported. | -| [OH_Huks_Tag](_huks_type_api.md#oh_huks_tag) {
OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT \| 1, OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 2, OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 3,
OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT \| 4, OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT \| 5, OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT \| 6, OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 7,
OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES \| 8, OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES \| 9, OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES \| 10, OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES \| 11,
OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES \| 12, OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT \| 14, OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 15,
OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT \| 19,
OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 20, OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 21, OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES \| 22, OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 23,
OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 24, OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 25, OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT \| 26, OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL \| 301,
OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT \| 302, OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL \| 303, OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT \| 304, OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT \| 305,
OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES \| 306, OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT \| 307, OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 308, OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 309,
OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT \| 310, OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES \| 501, OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES \| 502,
OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 511,
OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES \| 514, OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES \| 515,
OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 1001, OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1002, OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL \| 1003, OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT \| 1004,
OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES \| 1005, OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT \| 1006, OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1007, OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT \| 1008,
OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT \| 1011, OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20001,
OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20002, OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20003
} | Enumerates the tag values used in parameter sets. | +| [OH_Huks_KeyPurpose](_huks_type_api.md#oh_huks_keypurpose) {
OH_HUKS_KEY_PURPOSE_ENCRYPT = 1,
OH_HUKS_KEY_PURPOSE_DECRYPT = 2,
OH_HUKS_KEY_PURPOSE_SIGN = 4,
OH_HUKS_KEY_PURPOSE_VERIFY = 8,
OH_HUKS_KEY_PURPOSE_DERIVE = 16,
OH_HUKS_KEY_PURPOSE_WRAP = 32,
OH_HUKS_KEY_PURPOSE_UNWRAP = 64,
OH_HUKS_KEY_PURPOSE_MAC = 128,
OH_HUKS_KEY_PURPOSE_AGREE = 256
} | Enumerates the key purposes. | +| [OH_Huks_KeyDigest](_huks_type_api.md#oh_huks_keydigest) {
OH_HUKS_DIGEST_NONE = 0,
OH_HUKS_DIGEST_MD5 = 1,
OH_HUKS_DIGEST_SM3 = 2,
OH_HUKS_DIGEST_SHA1 = 10,
OH_HUKS_DIGEST_SHA224 = 11,
OH_HUKS_DIGEST_SHA256 = 12,
OH_HUKS_DIGEST_SHA384 = 13,
OH_HUKS_DIGEST_SHA512 = 14
} | Enumerates the digest algorithms. | +| [OH_Huks_KeyPadding](_huks_type_api.md#oh_huks_keypadding) {
OH_HUKS_PADDING_NONE = 0,
OH_HUKS_PADDING_OAEP = 1,
OH_HUKS_PADDING_PSS = 2,
OH_HUKS_PADDING_PKCS1_V1_5 = 3,
OH_HUKS_PADDING_PKCS5 = 4,
OH_HUKS_PADDING_PKCS7 = 5
} | Enumerates the padding algorithms. | +| [OH_Huks_CipherMode](_huks_type_api.md#oh_huks_ciphermode) {
OH_HUKS_MODE_ECB = 1,
OH_HUKS_MODE_CBC = 2,
OH_HUKS_MODE_CTR = 3,
OH_HUKS_MODE_OFB = 4,
OH_HUKS_MODE_CCM = 31,
OH_HUKS_MODE_GCM = 32
} | Enumerates the cipher modes. | +| [OH_Huks_KeySize](_huks_type_api.md#oh_huks_keysize) {
OH_HUKS_RSA_KEY_SIZE_512 = 512,
OH_HUKS_RSA_KEY_SIZE_768 = 768,
OH_HUKS_RSA_KEY_SIZE_1024 = 1024,
OH_HUKS_RSA_KEY_SIZE_2048 = 2048,
OH_HUKS_RSA_KEY_SIZE_3072 = 3072,
OH_HUKS_RSA_KEY_SIZE_4096 = 4096,
OH_HUKS_ECC_KEY_SIZE_224 = 224,
OH_HUKS_ECC_KEY_SIZE_256 = 256,
OH_HUKS_ECC_KEY_SIZE_384 = 384,
OH_HUKS_ECC_KEY_SIZE_521 = 521,
OH_HUKS_AES_KEY_SIZE_128 = 128,
OH_HUKS_AES_KEY_SIZE_192 = 192,
OH_HUKS_AES_KEY_SIZE_256 = 256,
OH_HUKS_AES_KEY_SIZE_512 = 512,
OH_HUKS_CURVE25519_KEY_SIZE_256 = 256,
OH_HUKS_DH_KEY_SIZE_2048 = 2048,
OH_HUKS_DH_KEY_SIZE_3072 = 3072,
OH_HUKS_DH_KEY_SIZE_4096 = 4096,
OH_HUKS_SM2_KEY_SIZE_256 = 256,
OH_HUKS_SM4_KEY_SIZE_128 = 128
} | Enumerates key sizes of different algorithms. | +| [OH_Huks_KeyAlg](_huks_type_api.md#oh_huks_keyalg) {
OH_HUKS_ALG_RSA = 1,
OH_HUKS_ALG_ECC = 2,
OH_HUKS_ALG_DSA = 3,
OH_HUKS_ALG_AES = 20,
OH_HUKS_ALG_HMAC = 50,
OH_HUKS_ALG_HKDF = 51,
OH_HUKS_ALG_PBKDF2 = 52,
OH_HUKS_ALG_ECDH = 100,
OH_HUKS_ALG_X25519 = 101,
OH_HUKS_ALG_ED25519 = 102,
OH_HUKS_ALG_DH = 103,
OH_HUKS_ALG_SM2 = 150,
OH_HUKS_ALG_SM3 = 151,
OH_HUKS_ALG_SM4 = 152
} | Enumerates the algorithms for keys. | +| [OH_Huks_AlgSuite](_huks_type_api.md#oh_huks_algsuite) {
OH_HUKS_UNWRAP_SUITE_X25519_AES_256_GCM_NOPADDING = 1,
OH_HUKS_UNWRAP_SUITE_ECDH_AES_256_GCM_NOPADDING = 2
} | Enumerates the algorithm suites for the import of a wrapped key. | +| [OH_Huks_KeyGenerateType](_huks_type_api.md#oh_huks_keygeneratetype) {
OH_HUKS_KEY_GENERATE_TYPE_DEFAULT = 0,
OH_HUKS_KEY_GENERATE_TYPE_DERIVE = 1,
OH_HUKS_KEY_GENERATE_TYPE_AGREE = 2
} | Enumerates the types of the key generated. | +| [OH_Huks_KeyFlag](_huks_type_api.md#oh_huks_keyflag) {
OH_HUKS_KEY_FLAG_IMPORT_KEY = 1,
OH_HUKS_KEY_FLAG_GENERATE_KEY = 2,
OH_HUKS_KEY_FLAG_AGREE_KEY = 3,
OH_HUKS_KEY_FLAG_DERIVE_KEY = 4
} | Enumerates the key generation types. | +| [OH_Huks_KeyStorageType](_huks_type_api.md#oh_huks_keystoragetype) {
OH_HUKS_STORAGE_TEMP = 0,
OH_HUKS_STORAGE_PERSISTENT = 1,
OH_HUKS_STORAGE_ONLY_USED_IN_HUKS = 2,
OH_HUKS_STORAGE_KEY_EXPORT_ALLOWED = 3
} | Enumerates the key storage types. | +| [OH_Huks_ImportKeyType](_huks_type_api.md#oh_huks_importkeytype) {
OH_HUKS_KEY_TYPE_PUBLIC_KEY = 0,
OH_HUKS_KEY_TYPE_PRIVATE_KEY = 1,
OH_HUKS_KEY_TYPE_KEY_PAIR = 2
}| Enumerates the types of the key to import. By default, a public key is imported. This field is not required when a symmetric key is imported. | +| [OH_Huks_RsaPssSaltLenType](_huks_type_api.md#oh_huks_rsapsssaltlentype) {
OH_HUKS_RSA_PSS_SALT_LEN_DIGEST = 0, OH_HUKS_RSA_PSS_SALT_LEN_MAX = 1
} | Enumerates the salt length types when the PSS padding mode is used in RSA signing or signature verification.| +| [OH_Huks_ErrCode](_huks_type_api.md#oh_huks_errcode) {
OH_HUKS_SUCCESS = 0,
OH_HUKS_ERR_CODE_PERMISSION_FAIL = 201,
OH_HUKS_ERR_CODE_ILLEGAL_ARGUMENT = 401,
OH_HUKS_ERR_CODE_NOT_SUPPORTED_API = 801,
OH_HUKS_ERR_CODE_FEATURE_NOT_SUPPORTED = 12000001,
OH_HUKS_ERR_CODE_MISSING_CRYPTO_ALG_ARGUMENT = 12000002,
OH_HUKS_ERR_CODE_INVALID_CRYPTO_ALG_ARGUMENT = 12000003,
OH_HUKS_ERR_CODE_FILE_OPERATION_FAIL = 12000004,
OH_HUKS_ERR_CODE_COMMUNICATION_FAIL = 12000005,
OH_HUKS_ERR_CODE_CRYPTO_FAIL = 12000006,
OH_HUKS_ERR_CODE_KEY_AUTH_PERMANENTLY_INVALIDATED = 12000007,
OH_HUKS_ERR_CODE_KEY_AUTH_VERIFY_FAILED = 12000008,
OH_HUKS_ERR_CODE_KEY_AUTH_TIME_OUT = 12000009,
OH_HUKS_ERR_CODE_SESSION_LIMIT = 12000010,
OH_HUKS_ERR_CODE_ITEM_NOT_EXIST = 12000011,
OH_HUKS_ERR_CODE_INTERNAL_ERROR = 12000012,
OH_HUKS_ERR_CODE_CREDENTIAL_NOT_EXIST = 12000013
} | Enumerates the error codes. | +| [OH_Huks_TagType](_huks_type_api.md#oh_huks_tagtype) {
OH_HUKS_TAG_TYPE_INVALID = 0 << 28,
OH_HUKS_TAG_TYPE_INT = 1 << 28,
OH_HUKS_TAG_TYPE_UINT = 2 << 28,
OH_HUKS_TAG_TYPE_ULONG = 3 << 28,
OH_HUKS_TAG_TYPE_BOOL = 4 << 28,
OH_HUKS_TAG_TYPE_BYTES = 5 << 28
} | Enumerates the mask values of the parameter type in the parameter set. | +| [OH_Huks_UserAuthType](_huks_type_api.md#oh_huks_userauthtype) {
OH_HUKS_USER_AUTH_TYPE_FINGERPRINT = 1 << 0,
OH_HUKS_USER_AUTH_TYPE_FACE = 1 << 1,
OH_HUKS_USER_AUTH_TYPE_PIN = 1 << 2
} | Enumerates the user authentication types in key access control. | +| [OH_Huks_AuthAccessType](_huks_type_api.md#oh_huks_authaccesstype) {
OH_HUKS_AUTH_ACCESS_INVALID_CLEAR_PASSWORD = 1 << 0,
OH_HUKS_AUTH_ACCESS_INVALID_NEW_BIO_ENROLL = 1 << 1
} | Enumerates the rules for invalidating a key. | +| [OH_Huks_ChallengeType](_huks_type_api.md#oh_huks_challengetype) {
OH_HUKS_CHALLENGE_TYPE_NORMAL = 0,
OH_HUKS_CHALLENGE_TYPE_CUSTOM = 1,
OH_HUKS_CHALLENGE_TYPE_NONE = 2
} | Enumerates the types of the challenge generated when a key is used. | +| [OH_Huks_ChallengePosition](_huks_type_api.md#oh_huks_challengeposition) {
OH_HUKS_CHALLENGE_POS_0 = 0,
OH_HUKS_CHALLENGE_POS_1,
OH_HUKS_CHALLENGE_POS_2,
OH_HUKS_CHALLENGE_POS_3
} | Enumerates the positions of the 8-byte valid value in a custom challenge generated. | +| [OH_Huks_SecureSignType](_huks_type_api.md#oh_huks_securesigntype) { OH_HUKS_SECURE_SIGN_WITH_AUTHINFO = 1 } | Enumerates the signature types of the key generated or imported. | +| [OH_Huks_Tag](_huks_type_api.md#oh_huks_tag) {
OH_HUKS_TAG_ALGORITHM = OH_HUKS_TAG_TYPE_UINT \| 1, OH_HUKS_TAG_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 2, OH_HUKS_TAG_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 3,
OH_HUKS_TAG_DIGEST = OH_HUKS_TAG_TYPE_UINT \| 4, OH_HUKS_TAG_PADDING = OH_HUKS_TAG_TYPE_UINT \| 5, OH_HUKS_TAG_BLOCK_MODE = OH_HUKS_TAG_TYPE_UINT \| 6, OH_HUKS_TAG_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 7,
OH_HUKS_TAG_ASSOCIATED_DATA = OH_HUKS_TAG_TYPE_BYTES \| 8, OH_HUKS_TAG_NONCE = OH_HUKS_TAG_TYPE_BYTES \| 9, OH_HUKS_TAG_IV = OH_HUKS_TAG_TYPE_BYTES \| 10, OH_HUKS_TAG_INFO = OH_HUKS_TAG_TYPE_BYTES \| 11,
OH_HUKS_TAG_SALT = OH_HUKS_TAG_TYPE_BYTES \| 12, OH_HUKS_TAG_ITERATION = OH_HUKS_TAG_TYPE_UINT \| 14, OH_HUKS_TAG_KEY_GENERATE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 15, OH_HUKS_TAG_AGREE_ALG = OH_HUKS_TAG_TYPE_UINT \| 19,
OH_HUKS_TAG_AGREE_PUBLIC_KEY_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 20, OH_HUKS_TAG_AGREE_PRIVATE_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 21, OH_HUKS_TAG_AGREE_PUBLIC_KEY = OH_HUKS_TAG_TYPE_BYTES \| 22, OH_HUKS_TAG_KEY_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 23,
OH_HUKS_TAG_DERIVE_KEY_SIZE = OH_HUKS_TAG_TYPE_UINT \| 24, OH_HUKS_TAG_IMPORT_KEY_TYPE = OH_HUKS_TAG_TYPE_UINT \| 25, OH_HUKS_TAG_UNWRAP_ALGORITHM_SUITE = OH_HUKS_TAG_TYPE_UINT \| 26,
OH_HUKS_TAG_DERIVED_AGREED_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 29,
OH_HUKS_TAG_RSA_PSS_SALT_LEN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 30, OH_HUKS_TAG_ALL_USERS = OH_HUKS_TAG_TYPE_BOOL \| 301,
OH_HUKS_TAG_USER_ID = OH_HUKS_TAG_TYPE_UINT \| 302, OH_HUKS_TAG_NO_AUTH_REQUIRED = OH_HUKS_TAG_TYPE_BOOL \| 303, OH_HUKS_TAG_USER_AUTH_TYPE = OH_HUKS_TAG_TYPE_UINT \| 304, OH_HUKS_TAG_AUTH_TIMEOUT = OH_HUKS_TAG_TYPE_UINT \| 305,
OH_HUKS_TAG_AUTH_TOKEN = OH_HUKS_TAG_TYPE_BYTES \| 306, OH_HUKS_TAG_KEY_AUTH_ACCESS_TYPE = OH_HUKS_TAG_TYPE_UINT \| 307, OH_HUKS_TAG_KEY_SECURE_SIGN_TYPE = OH_HUKS_TAG_TYPE_UINT \| 308, OH_HUKS_TAG_CHALLENGE_TYPE = OH_HUKS_TAG_TYPE_UINT \| 309,
OH_HUKS_TAG_CHALLENGE_POS = OH_HUKS_TAG_TYPE_UINT \| 310, OH_HUKS_TAG_KEY_AUTH_PURPOSE = OH_HUKS_TAG_TYPE_UINT \| 311, OH_HUKS_TAG_ATTESTATION_CHALLENGE = OH_HUKS_TAG_TYPE_BYTES \| 501, OH_HUKS_TAG_ATTESTATION_APPLICATION_ID = OH_HUKS_TAG_TYPE_BYTES \| 502, OH_HUKS_TAG_ATTESTATION_ID_ALIAS = OH_HUKS_TAG_TYPE_BYTES \| 511,
OH_HUKS_TAG_ATTESTATION_ID_SEC_LEVEL_INFO = OH_HUKS_TAG_TYPE_BYTES \| 514, OH_HUKS_TAG_ATTESTATION_ID_VERSION_INFO = OH_HUKS_TAG_TYPE_BYTES \| 515,
OH_HUKS_TAG_IS_KEY_ALIAS = OH_HUKS_TAG_TYPE_BOOL \| 1001, OH_HUKS_TAG_KEY_STORAGE_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1002, OH_HUKS_TAG_IS_ALLOWED_WRAP = OH_HUKS_TAG_TYPE_BOOL \| 1003, OH_HUKS_TAG_KEY_WRAP_TYPE = OH_HUKS_TAG_TYPE_UINT \| 1004,
OH_HUKS_TAG_KEY_AUTH_ID = OH_HUKS_TAG_TYPE_BYTES \| 1005, OH_HUKS_TAG_KEY_ROLE = OH_HUKS_TAG_TYPE_UINT \| 1006, OH_HUKS_TAG_KEY_FLAG = OH_HUKS_TAG_TYPE_UINT \| 1007, OH_HUKS_TAG_IS_ASYNCHRONIZED = OH_HUKS_TAG_TYPE_UINT \| 1008,
OH_HUKS_TAG_KEY_DOMAIN = OH_HUKS_TAG_TYPE_UINT \| 1011, OH_HUKS_TAG_SYMMETRIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20001,
OH_HUKS_TAG_ASYMMETRIC_PUBLIC_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20002, OH_HUKS_TAG_ASYMMETRIC_PRIVATE_KEY_DATA = OH_HUKS_TAG_TYPE_BYTES \| 20003
} | Enumerates the tag values used in the parameter set. | diff --git a/en/application-dev/reference/native-apis/rawfile.md b/en/application-dev/reference/native-apis/rawfile.md index 7314b4b36ea9eac50bf23972ef35833f5a828537..d77f9e4fb1c94336eed7aee74e8d21f7ee5c62f1 100644 --- a/en/application-dev/reference/native-apis/rawfile.md +++ b/en/application-dev/reference/native-apis/rawfile.md @@ -1,13 +1,11 @@ # Rawfile -## Overview +Provides APIs for operating the **rawfile** directory and its files, including traversing the **rawfile** directory and opening, searching for, reading, and closing a file in it. -Provides the function of operating rawfile directories and rawfiles. +**Since** -These functions include traversing, opening, searching, reading, and closing rawfiles. -**Since:** 8 @@ -16,399 +14,506 @@ These functions include traversing, opening, searching, reading, and closing raw ### Files -| Name | Description | -| -------- | -------- | -| [raw_dir.h](raw__dir_8h.md) | Provides functions for operating rawfile directories.
File to Include: | -| [raw_file.h](raw__file_8h.md) | Provides functions for operating rawfiles.
File to Include: | -| [raw_file_manager.h](raw__file__manager_8h.md) | Provides functions for managing rawfile resources.
File to Include: | +| Name | Description | +| ---------------------------------------- | ------------------ | +| [raw_dir.h](raw__dir_8h.md) | Provides functions related to the **rawfile** directory.
File to include: \ | +| [raw_file.h](raw__file_8h.md) | Provides functions related to the files in the **rawfile** directory.
File to include: \ | +| [raw_file_manager.h](raw__file__manager_8h.md) | Provides file management functions for the **rawfile** directory.
File to import: \| ### Structs -| Name | Description | -| -------- | -------- | -| [RawFileDescriptor](_raw_file_descriptor.md) | Provides rawfile descriptor information. | +| Name | Description | +| ---------------------------------------- | ----------------- | +| [RawFileDescriptor](_raw_file_descriptor.md) | Defines the file descriptor (FD) information of a file in the **rawfile** directory. | ### Types -| Name | Description | -| -------- | -------- | -| [RawDir](#rawdir) | Provides the function of accessing rawfile directories. | -| [RawFile](#rawfile) | Provides the function of accessing rawfiles. | -| [NativeResourceManager](#nativeresourcemanager) | Implements the resource manager. | +| Name | Description | +| ---------------------------------------- | ------------------- | +| [RawDir](#rawdir) | Provides access to the **rawfile** directory. | +| [RawFile](#rawfile) | Provides access to the files in **rawfile**. | +| [NativeResourceManager](#nativeresourcemanager) | Represents the resource manager.| ### Functions -| Name | Description | -| -------- | -------- | -| [OH_ResourceManager_GetRawFileName](#oh_resourcemanager_getrawfilename) ([RawDir](#rawdir) \*rawDir, int index) | Obtains the rawfile name via an index. | -| [OH_ResourceManager_GetRawFileCount](#oh_resourcemanager_getrawfilecount) ([RawDir](#rawdir) \*rawDir) |Obtains the number of rawfiles in [RawDir](#rawdir). | -| [OH_ResourceManager_CloseRawDir](#oh_resourcemanager_closerawdir) ([RawDir](#rawdir) \*rawDir) | Closes an opened [RawDir](#rawdir) and releases all associated resources. | -| [OH_ResourceManager_ReadRawFile](#oh_resourcemanager_readrawfile) (const [RawFile](#rawfile) \*rawFile, void \*buf, size_t length) |Reads a rawfile. | -| [OH_ResourceManager_SeekRawFile](#oh_resourcemanager_seekrawfile) (const [RawFile](#rawfile) \*rawFile, long offset, int whence) |Seeks for the data read/write position in the rawfile based on the specified offset. | -| [OH_ResourceManager_GetRawFileSize](#oh_resourcemanager_getrawfilesize) ([RawFile](#rawfile) \*rawFile) | Obtains the length of a rawfile in int32_t. | -| [OH_ResourceManager_CloseRawFile](#oh_resourcemanager_closerawfile) ([RawFile](#rawfile) \*rawFile) | Closes an opened [RawFile](#rawfile) and releases all associated resources. | -| [OH_ResourceManager_GetRawFileOffset](#oh_resourcemanager_getrawfileoffset) (const [RawFile](#rawfile) \*rawFile) | Obtains the current offset of the rawfile in int32_t. | -| [OH_ResourceManager_GetRawFileDescriptor](#oh_resourcemanager_getrawfiledescriptor) (const [RawFile](#rawfile) \*rawFile, [RawFileDescriptor](_raw_file_descriptor.md) &descriptor) | Opens a rawfile descriptor. | -| [OH_ResourceManager_ReleaseRawFileDescriptor](#oh_resourcemanager_releaserawfiledescriptor) (const [RawFileDescriptor](_raw_file_descriptor.md) &descriptor) | Closes a rawfile descriptor. | -| [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager) (napi_env env, napi_value jsResMgr) | Obtains the native resource manager based on JavaScipt resource manager. | -| [OH_ResourceManager_ReleaseNativeResourceManager](#oh_resourcemanager_releasenativeresourcemanager) ([NativeResourceManager](#nativeresourcemanager) \*resMgr) | Releases a native resource manager. | -| [OH_ResourceManager_OpenRawDir](#oh_resourcemanager_openrawdir) (const [NativeResourceManager](#nativeresourcemanager) \*mgr, const char \*dirName) | Opens a rawfile directory. | -| [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile) (const [NativeResourceManager](#nativeresourcemanager) \*mgr, const char \*fileName) | Opens a rawfile. | +| Name | Description | +| ------------------------------------------------------------ | ------------------------------------------------------------ | +| [OH_ResourceManager_GetRawFileName](#oh_resourcemanager_getrawfilename) ([RawDir](#rawdir) \*rawDir, int index) | Obtains the name of a file in **rawfile** based on the index. | +| [OH_ResourceManager_GetRawFileCount](#oh_resourcemanager_getrawfilecount) ([RawDir](#rawdir) \*rawDir) | Obtains the number of files in a [RawDir](#rawdir). | +| [OH_ResourceManager_CloseRawDir](#oh_resourcemanager_closerawdir) ([RawDir](#rawdir) \*rawDir) | Closes a [RawDir](#rawdir) and releases all associated resources. | +| [OH_ResourceManager_ReadRawFile](#oh_resourcemanager_readrawfile) (const [RawFile](#rawfile) \*rawFile, void \*buf, size_t length) | Reads data from a file in **rawfile**. | +| [OH_ResourceManager_SeekRawFile](#oh_resourcemanager_seekrawfile) (const [RawFile](#rawfile) \*rawFile, long offset, int whence) | Seeks for the data read/write position in a file in **rawfile** based on the specified offset. | +| [OH_ResourceManager_GetRawFileSize](#oh_resourcemanager_getrawfilesize) ([RawFile](#rawfile) \*rawFile) | Obtains the size of a file in **rawfile**. | +| [OH_ResourceManager_CloseRawFile](#oh_resourcemanager_closerawfile) ([RawFile](#rawfile) \*rawFile) | Closes a [RawFile](#rawfile) and releases all associated resources. | +| [OH_ResourceManager_GetRawFileOffset](#oh_resourcemanager_getrawfileoffset) (const [RawFile](#rawfile) \*rawFile) | Obtains the current offset of a file in **rawfile**. | +| [OH_ResourceManager_GetRawFileDescriptor](#oh_resourcemanager_getrawfiledescriptor) (const [RawFile](#rawfile) \*rawFile, [RawFileDescriptor](_raw_file_descriptor.md) &descriptor) | Opens a file in **rawfile** based on the offset and file length and obtains the FD. | +| [OH_ResourceManager_ReleaseRawFileDescriptor](#oh_resourcemanager_releaserawfiledescriptor) (const [RawFileDescriptor](_raw_file_descriptor.md) &descriptor) | Releases an FD. | +| [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager) (napi_env env, napi_value jsResMgr) | Initializes a Native resource manager using the JavaScript resource manager. You can use the Native resource manager obtained to implement operations related to **rawfile**. | +| [OH_ResourceManager_ReleaseNativeResourceManager](#oh_resourcemanager_releasenativeresourcemanager) ([NativeResourceManager](#nativeresourcemanager) \*resMgr) | Releases a Native resource manager instance. | +| [OH_ResourceManager_OpenRawDir](#oh_resourcemanager_openrawdir) (const [NativeResourceManager](#nativeresourcemanager) \*mgr, const char \*dirName) | Opens a directory in the **rawfile** directory. | +| [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile) (const [NativeResourceManager](#nativeresourcemanager) \*mgr, const char \*fileName) | Opens a file in the **rawfile** directory. | -## Type Description +## Description -### NativeResourceManager +### Type Description + + +#### NativeResourceManager + - ``` -typedef struct NativeResourceManagerNativeResourceManager +typedef struct NativeResourceManager NativeResourceManager ``` -**Description**
-Implements the resource manager. -This class encapsulates the native implementation of the JavaScript resource manager. You can obtain the pointer to **ResourceManager** by calling [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager). +**Description** + +Represents the resource manager. + +This class encapsulates the native implementation of the JavaScript resource manager. The **ResourceManager** pointer can be obtained by using [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager). + +**Since** + +8 + +#### RawDir -### RawDir - ``` -typedef struct RawDirRawDir +typedef struct RawDir RawDir ``` -**Description**
-Provides the function of accessing rawfile directories. + +**Description** + +Provides access to the **rawfile** directory. + +**Since** + +8 -### RawFile +#### RawFile + - ``` -typedef struct RawFileRawFile +typedef struct RawFile RawFile ``` -**Description**
-Provides the function of accessing rawfiles. +**Description** + +Provides access to the files in **rawfile**. + +**Since** + +8 + + +### Function Description -## Function Description +#### OH_ResourceManager_CloseRawDir() -### OH_ResourceManager_CloseRawDir() - ``` void OH_ResourceManager_CloseRawDir (RawDir * rawDir) ``` -**Description**
-Closes an opened [RawDir](#rawdir) and releases all associated resources. - **Parameters** +**Description** -| Name | Description | -| -------- | -------- | -| rawDir | Indicates the pointer to [RawDir](#rawdir). | +Closes a [RawDir](#rawdir) opened and releases all associated resources. - **See** +**Parameters** + +| Name | Description | +| ------ | ------------------------- | +| rawDir | Pointer to the [RawDir](#rawdir) to close.| + +**See** [OH_ResourceManager_OpenRawDir](#oh_resourcemanager_openrawdir) +**Since** + +8 + + +#### OH_ResourceManager_CloseRawFile() -### OH_ResourceManager_CloseRawFile() - ``` void OH_ResourceManager_CloseRawFile (RawFile * rawFile) ``` -**Description**
-Closes an opened [RawFile](#rawfile) and releases all associated resources. - **Parameters** +**Description** -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | +Closes a [RawFile](#rawfile) and releases all associated resources. - **See** +**Parameters** + +| Name | Description | +| ------- | --------------------------- | +| rawFile | Pointer to the [RawFile](#rawfile) to close.| + +**See** [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile) +**Since** + +8 + + +#### OH_ResourceManager_GetRawFileCount() -### OH_ResourceManager_GetRawFileCount() - ``` int OH_ResourceManager_GetRawFileCount (RawDir * rawDir) ``` -**Description**
-Obtains the number of rawfiles in [RawDir](#rawdir). + +**Description** + +Obtains the number of files in a [RawDir](#rawdir). You can use this function to obtain available indexes in [OH_ResourceManager_GetRawFileName](#oh_resourcemanager_getrawfilename). - **Parameters** +**Parameters** -| Name | Description | -| -------- | -------- | -| rawDir | Indicates the pointer to [RawDir](#rawdir). | +| Name | Description | +| ------ | ------------------------- | +| rawDir | Pointer to the target [RawDir](#rawdir).| - **See** +**See** [OH_ResourceManager_GetRawFileName](#oh_resourcemanager_getrawfilename) +**Since** + +8 + + +#### OH_ResourceManager_GetRawFileDescriptor() -### OH_ResourceManager_GetRawFileDescriptor() - ``` bool OH_ResourceManager_GetRawFileDescriptor (const RawFile * rawFile, RawFileDescriptor & descriptor ) ``` -**Description**
-Opens a rawfile descriptor. -After the descriptor is opened, you can use it to read the rawfile based on the offset (in int32_t) and file length. +**Description** + +Opens a file in the **rawfile** directory based on the offset and file length and obtains the FD. - **Parameters** +The FD obtained can be used to read the file. -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | -| descriptor | Indicates the rawfile descriptor, and the start position and length of the rawfile file in the HAP package. | +**Parameters** + +| Name | Description | +| ---------- | ---------------------------------------------------- | +| rawFile | Pointer to the [RawFile](#rawfile). | +| descriptor | File descriptor of the file, start position of the file in the hAP, and length of the file.| **Returns** -Returns **true** if the rawfile descriptor is opened successfully; returns **false** if the rawfile cannot be accessed. +Returns true if the file is opened; returns false if the access to the file is rejected. + +**Since** + +8 -### OH_ResourceManager_GetRawFileName() +#### OH_ResourceManager_GetRawFileName() + - ``` const char* OH_ResourceManager_GetRawFileName (RawDir * rawDir, int index ) ``` -**Description**
-Obtains the rawfile name via an index. -You can use this function to traverse a rawfile directory. +**Description** + +Obtains the name of a file in **rawfile** based on the index. + +You can use this function to traverse the **rawfile** directory. - **Parameters** +**Parameters** -| Name | Description | -| -------- | -------- | -| rawDir | Indicates the pointer to [RawDir](#rawdir). | -| index | Indicates the index of the file in [RawDir](#rawdir). | +| Name | Description | +| ------ | ----------------------------- | +| rawDir | Pointer to the [RawDir](#rawdir). | +| index | Index of the file in the [RawDir](#rawdir).| **Returns** -Returns the rawfile name via an index. The return value can be used as the input parameter of [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile). If no rawfile is found after all rawfiles are traversed, **NULL** will be returned. +Returns the file name obtained if the file exists in the directory; returns **null** otherwise. The file name returned can be used as the input parameter of [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile). - **See** +**See** [OH_ResourceManager_OpenRawFile](#oh_resourcemanager_openrawfile) +**Since** + +8 + + +#### OH_ResourceManager_GetRawFileOffset() -### OH_ResourceManager_GetRawFileOffset() - ``` long OH_ResourceManager_GetRawFileOffset (const RawFile * rawFile) ``` -**Description**
-Obtains the current offset of the rawfile in int32_t. - **Parameters** +**Description** + +Obtains the current offset of a file in **rawfile**. + +The offset indicates the position of the file in the HAP. -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | +**Parameters** + +| Name | Description | +| ------- | --------------------------- | +| rawFile | Pointer to the target [RawFile](#rawfile).| **Returns** -Returns the current offset of the rawfile. +Returns the file offset obtained. + +**Since** + +8 -### OH_ResourceManager_GetRawFileSize() +#### OH_ResourceManager_GetRawFileSize() + - ``` long OH_ResourceManager_GetRawFileSize (RawFile * rawFile) ``` -**Description**
-Obtains the length of a rawfile in int32_t. - **Parameters** +**Description** + +Obtains the size of a file in **rawfile**. + +**Parameters** -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | +| Name | Description | +| ------- | --------------------------- | +| rawFile | Pointer to the target [RawFile](#rawfile).| **Returns** -Returns the total length of the rawfile. +Returns the file size obtained. +**Since** + +8 + + +#### OH_ResourceManager_InitNativeResourceManager() -### OH_ResourceManager_InitNativeResourceManager() - ``` NativeResourceManager* OH_ResourceManager_InitNativeResourceManager (napi_env env, napi_value jsResMgr ) ``` -**Description**
-Obtains the native resource manager based on JavaScipt resource manager. -After obtaining a resource manager, you can use it complete various rawfile operations. +**Description** + +Initializes a Native resource manager using the JavaScript resource manager. + +You can use the resource manager obtained to implement **rawfile** operations. - **Parameters** +**Parameters** -| Name | Description | -| -------- | -------- | -| env | Indicates the pointer to the JavaScipt Native Interface (napi) environment. | -| jsResMgr | Indicates the JavaScipt resource manager. | +| Name | Description | +| -------- | ---------------------------------------- | +| env | Pointer to the JavaScript Native API (napi) environment.| +| jsResMgr | JavaScript resource manager. | **Returns** -Returns the pointer to [NativeResourceManager](#nativeresourcemanager). +Returns the pointer to the [NativeResourceManager](#nativeresourcemanager) obtained. +**Since** + +8 + + +#### OH_ResourceManager_OpenRawDir() -### OH_ResourceManager_OpenRawDir() - ``` RawDir* OH_ResourceManager_OpenRawDir (const NativeResourceManager * mgr, const char * dirName ) ``` -**Description**
-Opens a rawfile directory. -After opening a rawfile directory, you can traverse all the rawfile files in it. +**Description** - **Parameters** +Opens a directory in **rawfile**. -| Name | Description | -| -------- | -------- | -| mgr | Indicates the pointer to [NativeResourceManager](#nativeresourcemanager). You can obtain this pointer by calling [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager). | -| dirName | Indicates the name of the rawfile directory to open. If this field is left empty, the root directory of rawfile will be opened. | +After opening the directory, you can traverse all files in it. + +**Parameters** + +| Name | Description | +| ------- | ---------------------------------------- | +| mgr | Pointer to the [NativeResourceManager](#nativeresourcemanager), which is obtained by using [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager).| +| dirName | Pointer to the name of the directory to open. If this field is left empty, the root directory will be opened.| **Returns** -Returns the pointer to [RawDir](#rawdir). If this pointer is no longer needed after use, call [OH_ResourceManager_CloseRawDir](#oh_resourcemanager_closerawdir) to release it. +Returns the pointer to the [RawDir](#rawdir) opened. You can use [OH_ResourceManager_CloseRawDir](#oh_resourcemanager_closerawdir) to close the directory and release resources. - **See** +**See** [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager) [OH_ResourceManager_CloseRawDir](#oh_resourcemanager_closerawdir) +**Since** + +8 + + +#### OH_ResourceManager_OpenRawFile() -### OH_ResourceManager_OpenRawFile() - ``` RawFile* OH_ResourceManager_OpenRawFile (const NativeResourceManager * mgr, const char * fileName ) ``` -**Description**
-Opens a rawfile. -After a rawfile is opened, you can read the data in it. +**Description** - **Parameters** +Opens a file in **rawfile**. -| Name | Description | -| -------- | -------- | -| mgr | Indicates the pointer to [NativeResourceManager](#nativeresourcemanager). You can obtain this pointer by calling [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager). | -| fileName | Indicates the file name in the relative path of the rawfile root directory. | +After the file is opened, you can read data in it. + +**Parameters** + +| Name | Description | +| -------- | ---------------------------------------- | +| mgr | Pointer to the [NativeResourceManager](#nativeresourcemanager), which is obtained by using [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager).| +| fileName | Pointer to the name of the file in the relative path of the **rawfile** root directory. | **Returns** -Returns the pointer to [RawFile](#rawfile). If this pointer is no longer needed after use, call [OH_ResourceManager_CloseRawFile](#oh_resourcemanager_closerawfile) to release it. +Returns the pointer to the [RawFile](#rawfile) opened. You can use [OH_ResourceManager_CloseRawFile](#oh_resourcemanager_closerawfile) to close the file and release resources. - **See** +**See** [OH_ResourceManager_InitNativeResourceManager](#oh_resourcemanager_initnativeresourcemanager) [OH_ResourceManager_CloseRawFile](#oh_resourcemanager_closerawfile) +**Since** + +8 + + +#### OH_ResourceManager_ReadRawFile() -### OH_ResourceManager_ReadRawFile() - ``` int OH_ResourceManager_ReadRawFile (const RawFile * rawFile, void * buf, size_t length ) ``` -**Description**
-Reads a rawfile. + +**Description** + +Reads a file in **rawfile**. You can use this function to read data of the specified length from the current position. - **Parameters** +**Parameters** -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | -| buf | Indicates the pointer to the buffer for storing the read data. | -| length | Indicates the length of the read data, in bytes. | +| Name | Description | +| ------- | --------------------------- | +| rawFile | Pointer to the [RawFile](#rawfile) to read.| +| buf | Pointer to the buffer for receiving the read data. | +| length | Length of the data to read. | **Returns** -Returns the length of the read data in bytes. If the length is beyond the end of the rawfile, **0** will be returned. +Returns the number of bytes read. If the read length exceeds the length of the file end, **0** will be returned. + +**Since** +8 + + +#### OH_ResourceManager_ReleaseNativeResourceManager() -### OH_ResourceManager_ReleaseNativeResourceManager() - ``` void OH_ResourceManager_ReleaseNativeResourceManager (NativeResourceManager * resMgr) ``` -**Description**
-Releases a native resource manager. - **Parameters** +**Description** + +Releases a Native resource manager instance. + +**Parameters** + +| Name | Description | +| ------ | ---------------------------------------- | +| resMgr | Pointer to the [NativeResourceManager](#nativeresourcemanager) instance to release.| + +**Since** + +8 -| Name | Description | -| -------- | -------- | -| resMgr | Indicates the pointer to [NativeResourceManager](#nativeresourcemanager). | +#### OH_ResourceManager_ReleaseRawFileDescriptor() -### OH_ResourceManager_ReleaseRawFileDescriptor() - ``` bool OH_ResourceManager_ReleaseRawFileDescriptor (const RawFileDescriptor & descriptor) ``` -**Description**
-Closes a rawfile descriptor. -To prevent file descriptor leakage, you are advised to release a rawfile descriptor after use. +**Description** + +Releases the FD of a file in **rawfile**. + +To prevent FD leakage, you are advised to release an FD immediately after use. - **Parameters** +**Parameters** -| Name | Description | -| -------- | -------- | -| descriptor | Indicates the rawfile descriptor, and the start position and length of the rawfile file in the HAP package. | +| Name | Description | +| ---------- | ------------------------------------------------------------ | +| descriptor | File descriptor to close. It contains the FD, start position in the HAP, and file length. | **Returns** -Returns **true** if the rawfile descriptor is closed successfully; returns **false** otherwise. +Returns true if the FD is released; returns false otherwise. + +**Since** + +8 -### OH_ResourceManager_SeekRawFile() +#### OH_ResourceManager_SeekRawFile() + - ``` int OH_ResourceManager_SeekRawFile (const RawFile * rawFile, long offset, int whence ) ``` -**Description**
-Seeks for the data read/write position in the rawfile based on the specified offset. - **Parameters** +**Description** + +Seeks for the data read/write position in a file in **rawfile** based on the specified offset. + +**Parameters** -| Name | Description | -| -------- | -------- | -| rawFile | Indicates the pointer to [RawFile](#rawfile). | -| offset | Indicates the specified offset. | -| whence | Indicates the data read/write position. The options are as follows:
**0**: The read/write position is **offset**.
**1**: The read/write position is the current position plus **offset**.
**2**: The read/write position is the end of the file (EOF) plus **offset**. | +| Name | Description | +| ------- | ---------------------------------------- | +| rawFile | Pointer to the target [RawFile](#rawfile). | +| offset | Offset. | +| whence | Read/Write position. The options are as follows:
**0**: The read/write position is the offset.
**1**: The read/write position is the current position plus the offset.
**2**: The read/write position is the end of the file (EOF) plus the offset.| **Returns** -Returns the new data read/write position if the operation is successful; returns **(long) -1** otherwise. +Returns the read/write position if the operation is successful; returns **(long) -1** otherwise. + +**Since** + +8 diff --git a/en/application-dev/reference/native-lib/Readme-EN.md b/en/application-dev/reference/native-lib/Readme-EN.md index 9b0fbca08e15c7b7e0e5e500d3532019bb56eb87..35aae001da731ad020290e3f35ee0f3693221018 100644 --- a/en/application-dev/reference/native-lib/Readme-EN.md +++ b/en/application-dev/reference/native-lib/Readme-EN.md @@ -1,8 +1,12 @@ -# Standard Libraries Supported by Native APIs +# Native API Standard Libraries - [libc](third_party_libc/musl.md) +- [libc++](third_party_libc/cpp.md) - [Node-API](third_party_napi/napi.md) - [libuv](third_party_libuv/libuv.md) - [OpenSL ES](third_party_opensles/opensles.md) +- [OpenGL ES](third_party_opengl/opengles.md) +- [EGL](third_party_opengl/egl.md) +- [zlib](third_party_zlib/zlib.md) - Appendix - [Native API Symbols Not Exported](third_party_libc/musl-peculiar-symbol.md) - [Native API Symbols That May Fail to Be Invoked Due to Permission Control](third_party_libc/musl-permission-control-symbol.md) diff --git a/en/application-dev/reference/native-lib/third_party_libc/cpp.md b/en/application-dev/reference/native-lib/third_party_libc/cpp.md new file mode 100644 index 0000000000000000000000000000000000000000..ab373884f2a7f50f451e2f6aaa2682b9020bc745 --- /dev/null +++ b/en/application-dev/reference/native-lib/third_party_libc/cpp.md @@ -0,0 +1,29 @@ + +# libc++ + +Currently, OpenHarmony uses the C++ standard library [(libc++)](https://libcxx.llvm.org/) of the LLVM project. + +## Version + +From OpenHarmony 3.0, libc++ uses Clang/LLVM 10.0.1. + +From OpenHarmony 3.2, libc++ is upgraded to Clang/LLVM 12.0.1. + +From OpenHarmony 4.0, libc++ is upgraded to Clang/LLVM 15.0.4. + +## Supported Capabilities + +The C++11 and C++14 standards are supported, and the C++17 and C++20 standards are on the way. For details about the standards supported by language features, see the corresponding Release Notes at [https://libcxx.llvm.org/](https://libcxx.llvm.org/). + +## ABI Compatibility +In OpenHarmony, both the system library and application native library use the libc++. However, the two libc++ are different. The libc++ of the system library is updated with the image version, while the libc++ of the application native library is updated with the SDK version used for compilation. Both the libc++ libraries cross multiple major versions, which may cause Application Binary Interface (ABI) compatibility issues. To solve this problem, OpenHarmony differentiates the libc++ libraries as follows: + * System library: uses **libc++.so**, which is released with the system image. + * Application native library: uses **libc++_shared.so**, which is released with the application. + +The two libc++ libraries use different namespaces. **libc++_shared.so** uses **__n1** as the namespace for C++ symbols, and **libc++.so** uses **__h** as the namespace for C++ symbols. + +> **CAUTION** +> +> Currently, the Native API supports C only. The system library can use any programming language. + + \ No newline at end of file diff --git a/en/application-dev/reference/native-lib/third_party_libc/musl-permission-control-symbol.md b/en/application-dev/reference/native-lib/third_party_libc/musl-permission-control-symbol.md index ee2eb1bf6c1ab5473369e86287298349c54098eb..da2a9a0bef4cbd2a4122ddeae93eb0405cbab91d 100644 --- a/en/application-dev/reference/native-lib/third_party_libc/musl-permission-control-symbol.md +++ b/en/application-dev/reference/native-lib/third_party_libc/musl-permission-control-symbol.md @@ -1,12 +1,14 @@ # Native API Symbols That May Fail to Be Invoked Due to Permission Control +Before using the following interfaces, ensure that the application entity has the corresponding permission. + | Symbol| Possible Cause| | --- | --- | -| mlockall | User namespace isolation or lack of the CAP_IPC_LOCK privilege.| -| swapon | User namespace isolation. | -| swapoff | User namespace isolation. | -| stime | User namespace isolation or lack of the CAP_SYS_TIME privilege.| -| settimeofday | User namespace isolation or lack of the CAP_SYS_TIME privilege.| -| adjtime | User namespace isolation or lack of the CAP_SYS_TIME privilege.| -| clock_settime | User namespace isolation or lack of the CAP_SYS_TIME privilege.| -| klogctl | User namespace isolation or lack of the CAP_SYS_ADMIN/CAP_SYSLOG privilege.| +| mlockall | usr namespace isolation or lack of CAP_IPC_LOCK privilege | +| swapon | usr namespace isolation | +| swapoff | usr namespace isolation | +| stime | usr namespace isolation or lack of CAP_SYS_TIME privilege | +| settimeofday | usr namespace isolation or lack of CAP_SYS_TIME privilege | +| adjtime | usr namespace isolation or lack of CAP_SYS_TIME privilege | +| clock_settime | usr namespace isolation or lack of CAP_SYS_TIME privilege | +| klogctl | usr namespace isolation or lack of CAP_SYS_ADMIN/CAP_SYSLOG privilege | diff --git a/en/application-dev/reference/native-lib/third_party_libc/musl.md b/en/application-dev/reference/native-lib/third_party_libc/musl.md index cf74c7efdf1a796acd0de7f27883cec9a7cbb85f..460040d4f205ddc055f321eb3af30bde7e183271 100644 --- a/en/application-dev/reference/native-lib/third_party_libc/musl.md +++ b/en/application-dev/reference/native-lib/third_party_libc/musl.md @@ -1,85 +1,66 @@ -# Native Standard Libraries Supported by OpenHarmony +# libc ## Overview +The C standard library (libc) provides standard header files and common library implementations (such as input/output processing and string handling) in C language programming. -**Table 1** Standard libraries supported by OpenHarmony +OpenHarmony uses musl as the libc. musl is a lightweight, fast, simple, and free open-source libc. For details, see [musl libc Reference Manual](http://musl.libc.org/manual.html). -| Library | Description | -| :-------- | :----------------------------------------------------------- | -| C standard library | C11 standard library implemented by [libc, libm, and libdl](https://en.cppreference.com/w/c/header). | -| C++ standard library ([libc++](https://libcxx.llvm.org/))| An implementation of the C++ standard library. | -| Open Sound Library for Embedded Systems ([OpenSL ES](https://www.khronos.org/registry/OpenSL-ES/))| An embedded, cross-platform audio processing library.| -| [zlib](https://zlib.net/) | A general data compression library implemented in C/C++.| -| [EGL](https://www.khronos.org/egl/) | A standard software interface between rendering APIs and the underlying native window system.| -| Open Graphics Library for Embedded Systems ([OpenGL ES](https://www.khronos.org/opengles/))| A cross-platform software interface for rendering 3D graphics on embedded and mobile systems.| +For details about the differences between musl and glibc, see [Functional differences from glibc](https://wiki.musl-libc.org/functional-differences-from-glibc.html). -## C Standard Library +## libc Components -The C standard library is a C11 standard library implemented by: +C11 is implemented by [libc, libm, and libdl](https://en.cppreference.com/w/c/header). -- libc: provides thread-related functions and a majority of standard functions. +libc: provides thread-related interfaces and a majority of standard interfaces. +libm: provides mathematical library interfaces. Currently, OpenHarmony provides a link to libm, and the interfaces are defined in libc. -- libm: provides basic mathematical functions. +libdl: provides dynamic linker interfaces such as dlopen. Currently, OpenHarmony provides a link to libdl, and the interfaces are defined in libc. - -- libdl: provides functions related to dynamic linking, such as **dlopen**. - - -**Version** +## musl Version 1.2.0 -**Capabilities** - -C standard library includes a set of header files in accordance with standard C and provides common functions, such as the functions related to input/output (I/O) and string control. - -**musl** - +From OpenHarmony 4.0, musl 1.2.3 is supported. + +## Supported Capabilities +OpenHarmony provides header files and library interfaces that are compatible (not fully compatible) with C99, C11, and POSIX, and supports Armv7-A, Arm64, and x86_64 architectures. + +To better adapt to the basic features of OpenHarmony devices, such as high performance, low memory, high security, lightweight, and multi-form support, OpenHarmony has optimized the musl library and removed the interfaces that are not applicable to embedded devices. + +### New Capabilities +1. The dynamic loader supports isolation by namespace. The dynamic libraries that can be loaded by **dlopen()** are restricted by the system namespace. For example, the system dynamic libraries cannot be opened. +2. **dlclose()** can be used to unload a dynamic library. This capability is not supported by musl. +3. The symbol-versioning is supported. +4. **dlopen()** can directly load uncompressed files in a .zip package. + +### Debugging Capabilities +The libc provides dynamic settings of the basic log functions (disabled by default) for developers to view internal exceptions of the libc. You can set the **param** to enable or disable the log functions, without recompiling the libc. However, you are advised not to use the log functions in official release versions because they affect the running performance. + +#### 1. musl.log +Set **musl.log.enable** to **true** to enable the **musl.log** function. To print other logs, you need to enable this function first. +``` +setparam musl.log.enable true +``` + +#### 2. Loader log function +The loader starts applications and invokes dlopen() and dlclose() in libc. To view exceptions in the dynamic loading process, enable the loader log function. +* Enable the loader log of all applications (exercise caution when using this function). +``` +param set musl.log.ld.app true +``` +* Enable the loader log of the specified application. {app_name} specifies the target application. +``` +param set musl.log.ld.all false +param set musl.log.ld.app.{app_name} true +``` +* Enable the loader log of all applications except the specified application. +``` +param set musl.log.ld.all true +param set musl.log.ld.app.{app_name} false +``` + +## Interfaces Not Supported by musl [Native API Symbols Not Exported](musl-peculiar-symbol.md) - [Native API Symbols That May Fail to Be Invoked Due to Permission Control](musl-permission-control-symbol.md) -## libc++ - -[libc++](https://libcxx.llvm.org/) is an implementation of the C++ standard library. - -**Version** - -10.0.1 - -**Capabilities** - -The C++11 and C++14 standards are supported, and the C++17 and C++20 standards are on the way. - -## OpenSL ES - -[OpenGL ES](https://www.khronos.org/opengles/) is an embedded, cross-platform audio processing library. - -**Capabilities** - -[OpenSL ES Interfaces Supported by Native APIs](../third_party_opensles/opensles.md) - -## zlib - -[zlib](https://zlib.net/) is a general data compression library implemented in C/C++. - -## EGL - -EGL is an interface between Khronos rendering APIs (such as OpenGL ES and OpenVG) and the underlying native window system. OpenHarmony supports EGL. - -**Symbols Exported from the Standard Library** - -[EGL Symbols Exported from Native APIs](../third_party_opengl/egl-symbol.md) - -## OpenGL ES - -OpenGL is a cross-platform software interface for 3D graphics processing. [OpenGL ES](https://www.khronos.org/opengles/) is a OpenGL specification for embedded devices. OpenHarmony supports OpenGL ES 3.0. - -**Capabilities** - -OpenGL ES 3.0 - -**Symbols Exported from the Standard Library** - -[OpenGL ES 3.0 Symbols Exported from Native APIs](../third_party_opengl/openglesv3-symbol.md) diff --git a/en/application-dev/reference/native-lib/third_party_opengl/egl.md b/en/application-dev/reference/native-lib/third_party_opengl/egl.md new file mode 100644 index 0000000000000000000000000000000000000000..a74e6ef1c85df1a3df081fbcc010b3bae4379ec5 --- /dev/null +++ b/en/application-dev/reference/native-lib/third_party_opengl/egl.md @@ -0,0 +1,9 @@ + +# EGL + +EGL is an interface between Khronos rendering APIs (such as OpenGL ES and OpenVG) and the underlying native window system. OpenHarmony supports EGL. + +## **Symbols Exported from the NAPI Library** + +[EGL Symbols Exported fom Native APIs](egl-symbol.md) + diff --git a/en/application-dev/reference/native-lib/third_party_opengl/opengles.md b/en/application-dev/reference/native-lib/third_party_opengl/opengles.md new file mode 100644 index 0000000000000000000000000000000000000000..b73c456300b7b9abe4dff24fa6933a311fb950a3 --- /dev/null +++ b/en/application-dev/reference/native-lib/third_party_opengl/opengles.md @@ -0,0 +1,12 @@ +# OpenGL ES + +OpenGL is a cross-platform software interface for 3D graphics processing. [OpenGL ES](https://www.khronos.org/opengles/) is a OpenGL specification for embedded devices. OpenHarmony supports OpenGL ES 3.0. + +## Supported Capabilities + +OpenGL ES 3.0 + +## **Symbols Exported from the NAPI Library** + +[OpenGL ES 3.0 Symbols Exported from Native APIs](openglesv3-symbol.md) + diff --git a/en/application-dev/reference/native-lib/third_party_zlib/zlib.md b/en/application-dev/reference/native-lib/third_party_zlib/zlib.md new file mode 100644 index 0000000000000000000000000000000000000000..a1a3600569bb1de9ba360269bfeaf067aba4ad3a --- /dev/null +++ b/en/application-dev/reference/native-lib/third_party_zlib/zlib.md @@ -0,0 +1,3 @@ +# zlib + +[zlib](https://zlib.net/) is a general data compression library implemented in C/C++. \ No newline at end of file diff --git a/en/device-dev/driver/driver-peripherals-codec-des.md b/en/device-dev/driver/driver-peripherals-codec-des.md index 735c38fa84ae0ae500b7fac604398cc3562b14eb..bb0c7f8cabb0b242703a8d0604761fc69eeed189 100644 --- a/en/device-dev/driver/driver-peripherals-codec-des.md +++ b/en/device-dev/driver/driver-peripherals-codec-des.md @@ -39,7 +39,7 @@ Before you get started, understand the following concepts: - Component - An OpenMAX IL component, which is an abstraction of modules in video streams. The components in this document refer to codec components for video encoding and decoding. + An OpenMAX IL component, which is an abstraction of modules in video streams. The components in this document refer to codec components used for video encoding and decoding. ### Constraints @@ -54,33 +54,33 @@ The codec module implements hardware encoding and decoding of video data. It con ### Available APIs -- codec_component_manager.h +- icodec_component_manager.h | API | Description | | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------| - | int32_t (*CreateComponent)(struct CodecComponentType **component, uint32_t *componentId, char *compName, int64_t appData, struct CodecCallbackType *callbacks) | Creates a codec component instance. | - | int32_t (*DestroyComponent)(uint32_t componentId) | Destroys a component instance. | - -- codec_component _if.h - - | API | Description | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | - | int32_t (*SendCommand)(struct CodecComponentType *self, enum OMX_COMMANDTYPE cmd, uint32_t param, int8_t *cmdData, uint32_t cmdDataLen) | Sends commands to a component. | - | int32_t (*GetParameter)(struct CodecComponentType *self, uint32_t paramIndex, int8_t *paramStruct, uint32_t paramStructLen) | Obtains component parameter settings. | - | int32_t (*SetParameter)(struct CodecComponentType *self, uint32_t index, int8_t *paramStruct, uint32_t paramStructLen) | Sets component parameters. | - | int32_t (*GetState)(struct CodecComponentType *self, enum OMX_STATETYPE *state) | Obtains the component status. | - | int32_t (*UseBuffer)(struct CodecComponentType *self, uint32_t portIndex, struct OmxCodecBuffer *buffer) | Specifies the buffer of a component port. | - | int32_t (*FreeBuffer)(struct CodecComponentType *self, uint32_t portIndex, const struct OmxCodecBuffer *buffer) | Releases the buffer. | - | int32_t (*EmptyThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer) | Empties this buffer. | - | int32_t (*FillThisBuffer)(struct CodecComponentType *self, const struct OmxCodecBuffer *buffer) | Fills this buffer. | - -- codec_callback_if.h - - | API | Description | - | ---------------------------------------------------------------------------------------------------------------- |----------------------------------- | - | int32_t (*EventHandler)(struct CodecCallbackType *self, enum OMX_EVENTTYPE event, struct EventInfo *info) | Reports an event. | - | int32_t (*EmptyBufferDone)(struct CodecCallbackType *self, int64_t appData, const struct OmxCodecBuffer *buffer) | Reports an event indicating that the encoding or decoding in the input buffer is complete.| - | int32_t (*FillBufferDone)(struct CodecCallbackType *self, int64_t appData, const struct OmxCodecBuffer *buffer) | Reports an event indicating that the output buffer is filled. | + | int32_t CreateComponent(sptr& component, uint32_t& componentId,
const std::string& compName, int64_t appData, const sptr& callbacks) | Creates a codec component instance. | + | int32_t DestoryComponent(uint32_t componentId) | Destroys a codec component instance. | + +- icodec_component.h + + | API | Description | + | ------------------------------------------------------------ | ---------------------- | + | int32_t SendCommand(CodecCommandType cmd, uint32_t param, const std::vector& cmdData) | Sends commands to a component. | + | int32_t GetParameter(uint32_t index, const std::vector& inParamStruct, std::vector& outParamStruct) | Obtains component parameter settings. | + | int32_t SetParameter(uint32_t index, const std::vector& paramStruct) | Sets component parameters. | + | int32_t GetState(CodecStateType& state) | Obtains the component status. | + | int32_t UseBuffer(uint32_t portIndex, const OmxCodecBuffer& inBuffer, OmxCodecBuffer& outBuffer) | Requests a port buffer for the component. | + | int32_t FreeBuffer(uint32_t portIndex, const OmxCodecBuffer& buffer) | Releases the buffer. | + | int32_t EmptyThisBuffer(const OmxCodecBuffer& buffer) | Empties this buffer.| + | int32_t FillThisBuffer(const OmxCodecBuffer& buffer) | Fills this buffer. | + +- icodec_callback.h + + | API | Description | + | ------------------------------------------------------------ | ---------------------------------- | + | int32_t EventHandler(CodecEventType event, const EventInfo& info) | Called to report an event. | + | int32_t EmptyBufferDone(int64_t appData, const OmxCodecBuffer& buffer) | Called to report an event indicating that the encoding or decoding in the input buffer is complete.| + | int32_t FillBufferDone(int64_t appData, const OmxCodecBuffer& buffer) | Called to report an event indicating that the output buffer is filled. | For more information, see [codec](https://gitee.com/openharmony/drivers_peripheral/tree/master/codec). @@ -88,83 +88,86 @@ For more information, see [codec](https://gitee.com/openharmony/drivers_peripher The codec HDI driver development procedure is as follows: #### Registering and Initializing the Driver -Define the **HdfDriverEntry** structure (which defines the driver initialization method) and fill in the **g_codecComponentDriverEntry** structure to implement the **Bind()**, **Init()**, and **Release()** pointers. +Define the **HdfDriverEntry** struct (which defines the driver initialization method) and fill in the **g_codeccomponentmanagerDriverEntry** struct to implement the **Bind()**, **Init()**, and **Release()** pointers. ```c -struct HdfDriverEntry g_codecComponentDriverEntry = { +static struct HdfDriverEntry g_codeccomponentmanagerDriverEntry = { .moduleVersion = 1, - .moduleName = "codec_hdi_omx_server", - .Bind = HdfCodecComponentTypeDriverBind, - .Init = HdfCodecComponentTypeDriverInit, - .Release = HdfCodecComponentTypeDriverRelease, -}; -HDF_INIT(g_codecComponentDriverEntry); // Register HdfDriverEntry of the codec HDI with the HDF. + .moduleName = "codec_component_manager_service", + .Bind = HdfCodecComponentManagerDriverBind, + .Init = HdfCodecComponentManagerDriverInit, + .Release = HdfCodecComponentManagerDriverRelease, +}; // Register the HdfDriverEntry struct of the codec HDI with the HDF. ``` -- **HdfCodecComponentTypeDriverBind**: binds the device in the HDF to **CodecComponentTypeHost** and registers the codec service with the HDF. +- **HdfCodecComponentManagerDriverBind**: binds the device in the HDF to the **HdfCodecComponentManagerHost** and registers the codec service with the HDF. ```c - int32_t HdfCodecComponentTypeDriverBind(struct HdfDeviceObject *deviceObject) + static int HdfCodecComponentManagerDriverBind(struct HdfDeviceObject *deviceObject) { - HDF_LOGI("HdfCodecComponentTypeDriverBind enter."); - struct HdfCodecComponentTypeHost *omxcomponenttypeHost = - (struct HdfCodecComponentTypeHost *)OsalMemAlloc(sizeof(struct HdfCodecComponentTypeHost)); - if (omxcomponenttypeHost == NULL) { - HDF_LOGE("HdfCodecComponentTypeDriverBind OsalMemAlloc HdfCodecComponentTypeHost failed!"); + CODEC_LOGI("HdfCodecComponentManagerDriverBind enter"); + + auto *hdfCodecComponentManagerHost = new (std::nothrow) HdfCodecComponentManagerHost; + if (hdfCodecComponentManagerHost == nullptr) { + CODEC_LOGE("failed to create create HdfCodecComponentManagerHost object"); return HDF_FAILURE; } - int ret = HdfDeviceObjectSetInterfaceDesc(deviceObject, COMPONENT_MANAGER_SERVICE_DESC); - if (ret != HDF_SUCCESS) { - HDF_LOGE("Failed to set interface desc"); - return ret; + + hdfCodecComponentManagerHost->ioService.Dispatch = CodecComponentManagerDriverDispatch; + hdfCodecComponentManagerHost->ioService.Open = NULL; + hdfCodecComponentManagerHost->ioService.Release = NULL; + + auto serviceImpl = ICodecComponentManager::Get(true); + if (serviceImpl == nullptr) { + CODEC_LOGE("failed to get of implement service"); + delete hdfCodecComponentManagerHost; + return HDF_FAILURE; } - - omxcomponenttypeHost->ioservice.Dispatch = CodecComponentTypeDriverDispatch; - omxcomponenttypeHost->ioservice.Open = NULL; - omxcomponenttypeHost->ioservice.Release = NULL; - omxcomponenttypeHost->service = CodecComponentManagerSerivceGet(); - if (omxcomponenttypeHost->service == NULL) { - OsalMemFree(omxcomponenttypeHost); + + hdfCodecComponentManagerHost->stub = + OHOS::HDI::ObjectCollector::GetInstance().GetOrNewObject(serviceImpl, ICodecComponentManager::GetDescriptor()); + if (hdfCodecComponentManagerHost->stub == nullptr) { + CODEC_LOGE("failed to get stub object"); + delete hdfCodecComponentManagerHost; return HDF_FAILURE; } - - deviceObject->service = &omxcomponenttypeHost->ioservice; + + deviceObject->service = &hdfCodecComponentManagerHost->ioService; return HDF_SUCCESS; } ``` -- **HdfCodecComponentTypeDriverInit**: loads the attribute configuration from the HDF configuration source (HCS). +- **HdfCodecComponentManagerDriverInit**: loads the attribute configuration from the HDF Configuration Source (HCS). ```c - int32_t HdfCodecComponentTypeDriverInit(struct HdfDeviceObject *deviceObject) + static int HdfCodecComponentManagerDriverInit(struct HdfDeviceObject *deviceObject) { - HDF_LOGI("HdfCodecComponentTypeDriverInit enter."); - if (deviceObject == NULL) { - return HDF_FAILURE; - } - InitDataNode(deviceObject->property); - if (LoadCapabilityData() != HDF_SUCCESS) { - ClearCapabilityData(); + CODEC_LOGI("HdfCodecComponentManagerDriverInit enter"); + if (DevHostRegisterDumpHost(CodecDfxService::DevCodecHostDump) != HDF_SUCCESS) { + CODEC_LOGE("DevHostRegisterDumpHost error!"); } return HDF_SUCCESS; } ``` - + - **HdfCodecComponentTypeDriverRelease**: releases the driver instance. ```c - void HdfCodecComponentTypeDriverRelease(struct HdfDeviceObject *deviceObject) + static void HdfCodecComponentManagerDriverRelease(struct HdfDeviceObject *deviceObject) { - HDF_LOGI("HdfCodecComponentTypeDriverRelease enter."); - struct HdfCodecComponentTypeHost *omxcomponenttypeHost = - CONTAINER_OF(deviceObject->service, struct HdfCodecComponentTypeHost, ioservice); - OmxComponentManagerSeriveRelease(omxcomponenttypeHost->service); - OsalMemFree(omxcomponenttypeHost); - ClearCapabilityData(); + CODEC_LOGI("HdfCodecComponentManagerDriverRelease enter"); + if (deviceObject->service == nullptr) { + CODEC_LOGE("HdfCodecComponentManagerDriverRelease not initted"); + return; + } + + auto *hdfCodecComponentManagerHost = + CONTAINER_OF(deviceObject->service, struct HdfCodecComponentManagerHost, ioService); + delete hdfCodecComponentManagerHost; } ``` -#### Driver HCS +#### Configuring the Driver HCS The HCS consists of the following: - Device configuration @@ -172,48 +175,53 @@ The HCS consists of the following: The HCS includes the driver node, loading sequence, and service name. For details about the HCS syntax, see [Configuration Management](driver-hdf-manage.md). -Configuration file Path of the standard system: -vendor/hihope/rk3568/hdf_config/uhdf/ +The following uses the RK3568 development board as an example. The configuration files of the standard system are in the **vendor/hihope/rk3568/hdf_config/uhdf/** directory. + +1. Configure the device. + + Add the **codec_component_manager_service** configuration to **codec_host** in **device_info.hcs**. -1. Device configuration + Example: - Add the **codec_omx_service** configuration to **codec_host** in **device_info.hcs**. The following is an example: ```c codec :: host { hostName = "codec_host"; priority = 50; gid = ["codec_host", "uhdf_driver", "vendor_mpp_driver"]; - codec_omx_device :: device { + codec_omx_idl_device :: device { device0 :: deviceNode { policy = 2; // Automatic loading, not lazy loading. priority = 100; // Priority. - moduleName = "libcodec_hdi_omx_server.z.so"; // Dynamic library of the driver. - serviceName = "codec_hdi_omx_service"; // Service name of the driver. - deviceMatchAttr = "codec_component_capabilities"; //Attribute configuration. + moduleName = "libcodec_driver.z.so"; // Dynamic library of the driver. + serviceName = "codec_component_manager_service"; // Service name of the driver. + deviceMatchAttr = "media_codec_capabilities"; // Attribute configuration. } } } ``` -2. Configuration of supported components +2. Configure supported components. - Add the component configuration to the **media_codec\codec_component_capabilities.hcs file**. The following is an example: + Add the component configuration to the **media_codec\media_codec_capabilities.hcs** file. + + Example: + ```c /* node name explanation -- HDF_video_hw_enc_avc_rk: ** ** HDF____________video__________________hw____________________enc____________avc_______rk ** | | | | | | - ** HDF or OMX video or audio hardware or software encoder or decoder mime vendor + ** HDF or OMX video or audio hardware or software encoder or decoder MIME vendor */ HDF_video_hw_enc_avc_rk { - role = 1; // Role of the AvCodec. + role = 1; // Role of the audio and video codec. type = 1; // Codec type. name = "OMX.rk.video_encoder.avc"; // Component name. supportProfiles = [1, 32768, 2, 32768, 8, 32768]; // Supported profiles. maxInst = 4; // Maximum number of instances. isSoftwareCodec = false; // Whether it is software codec. processModeMask = []; // Codec processing mode. - capsMask = [0x01]; // Codec playback capabilities. + capsMask = [0x01]; // CodecCapsMask configuration. minBitRate = 1; // Minimum bit rate. maxBitRate = 40000000; // Maximum bit rate. minWidth = 176; // Minimum video width. @@ -228,10 +236,10 @@ vendor/hihope/rk3568/hdf_config/uhdf/ maxBlocksPerSecond = 0xFFFFFFFF; blockSizeWidth = 0xFFFFFFFF; blockSizeHeight = 0xFFFFFFFF; - supportPixelFmts = [28, 24, 30, 22, 7, 3, 14, 13, 20, 26, 27, 12]; // List of supported colors. + supportPixelFmts = [28, 24, 20, 12]; // List of colors supported by the display. measuredFrameRate = [320, 240, 165, 165, 720, 480, 149, 149, 1280, 720, 73, 73, 1920, 1080, 18, 18]; - bitRateMode = [1, 2]; // Bit rate mode. - minFrameRate = 0; // Frame rate. + bitRateMode = [1, 2]; // Bit rate mode. + minFrameRate = 0; // Frame rate. maxFrameRate = 0; } ``` @@ -239,42 +247,37 @@ vendor/hihope/rk3568/hdf_config/uhdf/ ### Development Example After completing codec module driver adaptation, use the HDI APIs provided by the codec module for further development. The codec HDI provides the following features: -1. Provides codec HDI APIs for video services to implement encoding and decoding of video services. -2. Provides standard interfaces for device developers to ensure that the OEM vendors comply with the HDI adapter standard. This promises a healthy evolution of the ecosystem. +- Provides codec HDI APIs for video services to implement encoding and decoding for video services. +- Provides standard interfaces for device developers to ensure that the OEM vendors comply with the HDI adapter standard. This promises a healthy evolution of the ecosystem. The development procedure is as follows: 1. Initialize the driver, including initializing the instances, callbacks, and component. 2. Set codec parameters and information such as the video width, height, and bit rate. 3. Apply for input and output buffers. -4. Flip codec buffers, enable the component to enter the **OMX_Executing** state, and process the callbacks. -5. Deinitialize the interface instance, destroy the buffers, close the component, and releases all interface objects. +4. Flip codec buffers, enable the component to enter the **CODEC_STATE_EXECUTING** state, and process the callbacks. +5. Deinitialize the interface instance, destroy the buffers, close the component, and releases all interface instances. #### Initializing the Driver Initialize the interface instance and callbacks, and create a component. ```cpp // Initialize the codec HDI ComponentManager instance. -omxMgr_ = GetCodecComponentManager(); - +omxMgr_ = ICodecComponentManager::Get(false); +if ((omxMgr_ == nullptr)) { + HDF_LOGE("%{public}s omxMgr_ is null", __func__); + return false; +} // Initialize the callback. -callback_ = CodecCallbackTypeStubGetInstance(); -if (!omxMgr_ || !callback_) { - FUNC_EXIT_ERR(); +callback_ = new CodecHdiCallback(shared_from_this()); +if ((callback_ == nullptr)) { + HDF_LOGE("%{public}s callback_ is null", __func__); return false; } -// Set the callback pointers. -callback_->EventHandler = &OMXCore::OnEvent; -callback_->EmptyBufferDone = &OMXCore::OnEmptyBufferDone; -callback_->FillBufferDone = &OMXCore::OnFillBufferDone; - // Create a component instance. -uint32_t err = HDF_SUCCESS; -if (codec == codecMime::AVC) { - err = omxMgr_->CreateComponent(&client_, &componentId_, const_cast(DECODER_AVC), (int64_t)this, - callback_); -} else { - err = omxMgr_->CreateComponent(&client_, &componentId_, const_cast(DECODER_HEVC), (int64_t)this, - callback_); +err = omxMgr_->CreateComponent(client_, componentId_, compName, reinterpret_cast(this), callback_); +if (err != HDF_SUCCESS) { + HDF_LOGE("%{public}s failed to CreateComponent", __func__); + return false; } ``` @@ -283,64 +286,79 @@ Set the width and height of the input and output data, input data format, and ou ```cpp // Set the width and height of the input image. OMX_PARAM_PORTDEFINITIONTYPE param; -InitParam(param); -param.nPortIndex = (uint32_t)PortIndex::PORT_INDEX_INPUT; -auto err = client_->GetParameter(client_, OMX_IndexParamPortDefinition, (int8_t *)¶m, sizeof(param)); +if (util_->InitParam(param) != HDF_SUCCESS) { + return HDF_FAILURE; +} +param.nPortIndex = static_cast(PortIndex::PORT_INDEX_INPUT); + +std::vector inVec, outVec; +util_->ObjectToVector(param, inVec); +auto err = client_->GetParameter(OMX_IndexParamPortDefinition, inVec, outVec); if (err != HDF_SUCCESS) { - HDF_LOGE("%{public}s failed PortIndex::PORT_INDEX_INPUT, index is OMX_IndexParamPortDefinition", __func__); - return false; + HDF_LOGE("%{public}s failed PortIndex::PORT_INDEX_INPUT, index is OMX_IndexParamPortDefinition", __func__); + return err; } +util_->VectorToObject(outVec, param); + HDF_LOGI("PortIndex::PORT_INDEX_INPUT: eCompressionFormat = %{public}d, eColorFormat = %{public}d ", param.format.video.eCompressionFormat, param.format.video.eColorFormat); -param.format.video.nFrameWidth = width_; -param.format.video.nFrameHeight = height_; -param.format.video.nStride = width_; -param.format.video.nSliceHeight = height_; -err = client_->SetParameter(client_, OMX_IndexParamPortDefinition, (int8_t *)¶m, sizeof(param)); +util_->setParmValue(param, width_, height_, stride_); +util_->ObjectToVector(param, inVec); +err = client_->SetParameter(OMX_IndexParamPortDefinition, inVec); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_INPUT, index is OMX_IndexParamPortDefinition", __func__); - return false; + return err; } // Set the output width, height, and format. -InitParam(param); -param.nPortIndex = (uint32_t)PortIndex::PORT_INDEX_OUTPUT; -err = client_->GetParameter(client_, OMX_IndexParamPortDefinition, (int8_t *)¶m, sizeof(param)); +if (util_->InitParam(param) != HDF_SUCCESS) { + return HDF_FAILURE; +} +param.nPortIndex = static_cast(PortIndex::PORT_INDEX_OUTPUT); +util_->ObjectToVector(param, inVec); +err = client_->GetParameter(OMX_IndexParamPortDefinition, inVec, outVec); if (err != HDF_SUCCESS) { - HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_OUTPUT, index is OMX_IndexParamPortDefinition", __func__); - return false; + HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_OUTPUT, index is OMX_IndexParamPortDefinition", + __func__); + return err; } +util_->VectorToObject(outVec, param); + HDF_LOGI("PortIndex::PORT_INDEX_OUTPUT eCompressionFormat = %{public}d, eColorFormat=%{public}d", param.format.video.eCompressionFormat, param.format.video.eColorFormat); -param.format.video.nFrameWidth = width_; -param.format.video.nFrameHeight = height_; -param.format.video.nStride = width_; -param.format.video.nSliceHeight = height_; +util_->setParmValue(param, width_, height_, stride_); param.format.video.eColorFormat = AV_COLOR_FORMAT; // Set the output data format to YUV420SP. -err = client_->SetParameter(client_, OMX_IndexParamPortDefinition, (int8_t *)¶m, sizeof(param)); +err = client_->SetParameter(OMX_IndexParamPortDefinition, inVec); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_OUTPUT, index is OMX_IndexParamPortDefinition", __func__); - return false; + return err; } // Set the input data format to H.264/H.265. OMX_VIDEO_PARAM_PORTFORMATTYPE param; -InitParam(param); +if (util_->InitParam(param) != HDF_SUCCESS) { + return false; +} param.nPortIndex = (uint32_t)PortIndex::PORT_INDEX_INPUT; -auto err = client_->GetParameter(client_, OMX_IndexParamVideoPortFormat, (int8_t *)¶m, sizeof(param)); +std::vector inVec, outVec; +util_->ObjectToVector(param, inVec); +auto err = client_->GetParameter(OMX_IndexParamVideoPortFormat, inVec, outVec); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_INPUT", __func__); return false; } +util_->VectorToObject(outVec, param); + HDF_LOGI("set Format PortIndex::PORT_INDEX_INPUT eCompressionFormat = %{public}d, eColorFormat=%{public}d", param.eCompressionFormat, param.eColorFormat); -param.xFramerate = FRAME; // Set the frame rate to 30. +param.xFramerate = FRAME // Set the frame rate to 30. if (codecMime_ == codecMime::AVC) { param.eCompressionFormat = OMX_VIDEO_CodingAVC; // H264 } else { param.eCompressionFormat = (OMX_VIDEO_CODINGTYPE)CODEC_OMX_VIDEO_CodingHEVC; // H265 } -err = client_->SetParameter(client_, OMX_IndexParamVideoPortFormat, (int8_t *)¶m, sizeof(param)); +util_->ObjectToVector(param, inVec); +err = client_->SetParameter(OMX_IndexParamVideoPortFormat, inVec); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed with PortIndex::PORT_INDEX_INPUT", __func__); return false; @@ -352,90 +370,97 @@ Perform the following steps: 1. Use **UseBuffer()** to apply for input and output buffers and save the buffer IDs. The buffer IDs can be used for subsequent buffer flipping. 2. Check whether the corresponding port is enabled. If not, enable the port first. -3. Use **SendCommand()** to change the component status to OMX_StateIdle, and wait until the operation result is obtained. +3. Use **SendCommand()** to change the component status to **CODEC_STATE_IDLE**, and wait until the operation result is obtained. ```cpp // Apply for the input buffer. -auto ret = UseBufferOnPort(PortIndex::PORT_INDEX_INPUT); -if (!ret) { +auto err = UseBufferOnPort(PortIndex::PORT_INDEX_INPUT); +if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s UseBufferOnPort PortIndex::PORT_INDEX_INPUT error", __func__); return false; } // Apply for the output buffer. -ret = UseBufferOnPort(PortIndex::PORT_INDEX_OUTPUT); -if (!ret) { +err = UseBufferOnPort(PortIndex::PORT_INDEX_OUTPUT); +if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s UseBufferOnPort PortIndex::PORT_INDEX_OUTPUT error", __func__); return false; } // Enable the component to enter the OMX_StateIdle state. -auto err = client_->SendCommand(client_, OMX_CommandStateSet, OMX_StateIdle, NULL, 0); +std::vector cmdData; +auto err = client_->SendCommand(CODEC_COMMAND_STATE_SET, CODEC_STATE_IDLE, cmdData); if (err != HDF_SUCCESS) { - HDF_LOGE("%{public}s failed to SendCommand with OMX_CommandStateSet:OMX_StateIdle", __func__); + HDF_LOGE("%{public}s failed to SendCommand with CODEC_COMMAND_STATE_SET:CODEC_STATE_IDLE", __func__); return false; } -HDF_LOGI("Wait for OMX_StateIdle status"); -this->WaitForStatusChanged(); ``` -Implement **UseBufferOnPort** as follows: +Implement **UseBufferOnPort()** as follows: ```cpp -bool CodecHdiDecode::UseBufferOnPort(enum PortIndex portIndex) +int32_t CodecHdiDecode::UseBufferOnPort(PortIndex portIndex) { HDF_LOGI("%{public}s enter, portIndex = %{public}d", __func__, portIndex); int bufferSize = 0; int bufferCount = 0; - bool bPortEnable = false; + bool PortEnable = false; // Obtain parameters of the port buffer. OMX_PARAM_PORTDEFINITIONTYPE param; - InitParam(param); - param.nPortIndex = (OMX_U32)portIndex; - auto err = client_->GetParameter(client_, OMX_IndexParamPortDefinition, (int8_t *)¶m, sizeof(param)); + if (util_->InitParam(param) != HDF_SUCCESS) { + return HDF_FAILURE; + } + param.nPortIndex = static_cast(portIndex); + + std::vector inVec, outVec; + util_->ObjectToVector(param, inVec); + auto err = client_->GetParameter(OMX_IndexParamPortDefinition, inVec, outVec); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed to GetParameter with OMX_IndexParamPortDefinition : portIndex[%{public}d]", - __func__, portIndex); - return false; + __func__, portIndex); + return err; } + util_->VectorToObject(outVec, param); + bufferSize = param.nBufferSize; bufferCount = param.nBufferCountActual; - bPortEnable = param.bEnabled; + portEnable = param.bEnabled; HDF_LOGI("buffer index [%{public}d], buffer size [%{public}d], " - "buffer count [%{public}d], portEnable[%{public}d], err [%{public}d]", - portIndex, bufferSize, bufferCount, bPortEnable, err); - { - OMX_PARAM_BUFFERSUPPLIERTYPE param; - InitParam(param); - param.nPortIndex = (uint32_t)portIndex; - auto err = client_->GetParameter(client_, OMX_IndexParamCompBufferSupplier, (int8_t *)¶m, sizeof(param)); - HDF_LOGI("param.eBufferSupplier[%{public}d] isSupply [%{public}d], err [%{public}d]", param.eBufferSupplier, - this->isSupply_, err); - } + "buffer count [%{public}d], portEnable[%{public}d], ret [%{public}d]", + portIndex, bufferSize, bufferCount, portEnable, err); // Set the port buffer. - UseBufferOnPort(portIndex, bufferCount, bufferSize); + if (useBufferHandle_ && portIndex == PortIndex::PORT_INDEX_OUTPUT) { + err = UseBufferHandle(bufferCount, bufferSize); + } else { + err = UseBufferOnPort(portIndex, bufferCount, bufferSize); + } // Check whether the port is available. - if (!bPortEnable) { - auto err = client_->SendCommand(client_, OMX_CommandPortEnable, (uint32_t)portIndex, NULL, 0); + if (!portEnable) { + err = client_->SendCommand(CODEC_COMMAND_PORT_ENABLE, static_cast(portIndex), {}); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s SendCommand OMX_CommandPortEnable::PortIndex::PORT_INDEX_INPUT error", __func__); - return false; + return err; } } - return true; + return HDF_SUCCESS; } -bool CodecHdiDecode::UseBufferOnPort(enum PortIndex portIndex, int bufferCount, int bufferSize) +int32_t CodecHdiDecode::UseBufferOnPort(PortIndex portIndex, int bufferCount, int bufferSize) { + if (bufferCount <= 0 || bufferSize <= 0) { + HDF_LOGE("UseBufferOnPort bufferCount <= 0 or bufferSize <= 0"); + return HDF_ERR_INVALID_PARAM; + } for (int i = 0; i < bufferCount; i++) { - OmxCodecBuffer *omxBuffer = new OmxCodecBuffer(); - memset_s(omxBuffer, sizeof(OmxCodecBuffer), 0, sizeof(OmxCodecBuffer)); + std::shared_ptr omxBuffer = std::make_shared(); omxBuffer->size = sizeof(OmxCodecBuffer); omxBuffer->version.s.nVersionMajor = 1; - omxBuffer->bufferType = BUFFER_TYPE_AVSHARE_MEM_FD; + omxBuffer->bufferType = CODEC_BUFFER_TYPE_AVSHARE_MEM_FD; int fd = AshmemCreate(0, bufferSize); shared_ptr sharedMem = make_shared(fd, bufferSize); - omxBuffer->bufferLen = FD_SIZE; - omxBuffer->buffer = (uint8_t *)(unsigned long)fd; + omxBuffer->fd = fd; + omxBuffer->bufferhandle = nullptr; omxBuffer->allocLen = bufferSize; omxBuffer->fenceFd = -1; + omxBuffer->pts = 0; + omxBuffer->flag = 0; if (portIndex == PortIndex::PORT_INDEX_INPUT) { omxBuffer->type = READ_ONLY_TYPE; // ReadOnly @@ -444,84 +469,75 @@ bool CodecHdiDecode::UseBufferOnPort(enum PortIndex portIndex, int bufferCount, omxBuffer->type = READ_WRITE_TYPE; sharedMem->MapReadOnlyAshmem(); } - auto err = client_->UseBuffer(client_, (uint32_t)portIndex, omxBuffer); + OmxCodecBuffer outBuffer; + auto err = client_->UseBuffer((uint32_t)portIndex, *omxBuffer.get(), outBuffer); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s failed to UseBuffer with portIndex[%{public}d]", __func__, portIndex); sharedMem->UnmapAshmem(); sharedMem->CloseAshmem(); sharedMem = nullptr; - return false; + return err; } - omxBuffer->bufferLen = 0; + omxBuffer->bufferId = outBuffer.bufferId; + omxBuffer->fd = -1; HDF_LOGI("UseBuffer returned bufferID [%{public}d]", omxBuffer->bufferId); - BufferInfo *bufferInfo = new BufferInfo; + std::shared_ptr bufferInfo = std::make_shared(); bufferInfo->omxBuffer = omxBuffer; bufferInfo->avSharedPtr = sharedMem; bufferInfo->portIndex = portIndex; - omxBuffers_.insert(std::make_pair(omxBuffer->bufferId, std::move(bufferInfo))); + omxBuffers_.emplace(std::make_pair(omxBuffer->bufferId, bufferInfo)); if (portIndex == PortIndex::PORT_INDEX_INPUT) { unUsedInBuffers_.push_back(omxBuffer->bufferId); } else { unUsedOutBuffers_.push_back(omxBuffer->bufferId); } - int fdret = (int)omxBuffer->buffer; - HDF_LOGI("{bufferID = %{public}d, srcfd = %{public}d, retfd = %{public}d}", omxBuffer->bufferId, fd, fdret); } - return true; + + return HDF_SUCCESS; } ``` -#### Codec Buffer Flipping -Set the component to the **OMX_StateExecuting** state, fill the input buffer, read data from the output buffer, and flip the buffers. +#### Flipping Codec Buffers +Set the component to the **CODEC_STATE_EXECUTING** state, fill the input buffer, read data from the output buffer, and flip the buffers. ```cpp // Set the component to the OMX_StateExecuting state and start buffer flipping. -HDF_LOGI("...command to OMX_StateExecuting...."); -auto err = client_->SendCommand(client_, OMX_CommandStateSet, OMX_StateExecuting, NULL, 0); +HDF_LOGI("...command to CODEC_STATE_EXECUTING...."); +auto err = client_->SendCommand(CODEC_COMMAND_STATE_SET, CODEC_STATE_EXECUTING, {}); if (err != HDF_SUCCESS) { - HDF_LOGE("%{public}s failed to SendCommand with OMX_CommandStateSet:OMX_StateIdle", __func__); + HDF_LOGE("%{public}s failed to SendCommand with CODEC_COMMAND_STATE_SET:CODEC_STATE_IDLE", __func__); return; } -// Set the output buffer. -for (auto bufferId : unUsedOutBuffers_) { - HDF_LOGI("fill bufferid [%{public}d]", bufferId); - auto iter = omxBuffers_.find(bufferId); - if (iter != omxBuffers_.end()) { - BufferInfo *bufferInfo = iter->second; - auto err = client_->FillThisBuffer(client_, bufferInfo->pOmxBuffer); - if (err != HDF_SUCCESS) { - HDF_LOGE("FillThisBuffer error"); - FUNC_EXIT_ERR(); - return; - } - } +// Set the output buffer to fill. +if (!FillAllTheBuffer()) { + HDF_LOGE("%{public}s FillAllTheBuffer error", __func__); + return; } // Fill the input buffer. -bool bEndOfFile = false; -while (!bEndOfFile) { - int bufferID = GetFreeBufferId(); +auto t1 = std::chrono::system_clock::now(); +bool eosFlag = false; +while (!eosFlag) { if (this->exit_) { break; } + int bufferID = GetFreeBufferId(); if (bufferID < 0) { - usleep(10000); + usleep(10000); // 10000 for wait 10ms continue; } auto iter = omxBuffers_.find(bufferID); if (iter == omxBuffers_.end()) { continue; } - BufferInfo *bufferInfo = iter->second; - void *sharedAddr = (void *)bufferInfo->avSharedPtr->ReadFromAshmem(0, 0); - bool bEOS = (size_t)this->ReadOnePacket(fpIn_, (char *)sharedAddr, bufferInfo->omxBuffer->filledLen); - HDF_LOGI("read data size is %{public}d", bufferInfo->omxBuffer->filledLen); + auto bufferInfo = iter->second; + void *sharedAddr = const_cast(bufferInfo->avSharedPtr->ReadFromAshmem(0, 0)); + eosFlag = this->ReadOnePacket(fpIn_, static_cast(sharedAddr), bufferInfo->omxBuffer->filledLen); bufferInfo->omxBuffer->offset = 0; - if (bEOS) { + if (eosFlag) { bufferInfo->omxBuffer->flag = OMX_BUFFERFLAG_EOS; - bEndOfFile = true; } - auto err = client_->EmptyThisBuffer(client_, bufferInfo->omxBuffer); + err = client_->EmptyThisBuffer(*bufferInfo->omxBuffer.get()); if (err != HDF_SUCCESS) { HDF_LOGE("%{public}s EmptyThisBuffer error", __func__); return; @@ -529,181 +545,186 @@ while (!bEndOfFile) { } // Wait. while (!this->exit_) { - usleep(10000); - continue; + usleep(10000); // 10000 for wait 10ms } // Enable the component to enter the OMX_StateIdle state after decoding. -client_->SendCommand(client_, OMX_CommandStateSet, OMX_StateIdle, NULL, 0); +auto t2 = std::chrono::system_clock::now(); +std::chrono::duration diff = t2 - t1; +HDF_LOGI("cost %{public}f, count=%{public}d", diff.count(), count_); +(void)client_->SendCommand(CODEC_COMMAND_STATE_SET, CODEC_STATE_IDLE, {}); +return; +} ``` Automatic framing is not supported in rk OMX decoding. Therefore, you need to manually divide data into frames. Currently, data is divided into frames from code 0x000001 or 0x00000001 and sent to the server for processing. The sample code is as follows: ```cpp // Read a file by frame. -bool OMXCore::ReadOnePacket(FILE* fp, char* buf, uint32_t& nFilled) +bool CodecHdiDecode::ReadOnePacket(FILE *fp, char *buf, uint32_t &filledCount) { - // Read four bytes first. - size_t t = fread(buf, 1, 4, fp); - if (t < 4) { - // The file reading ends. + // Read the start code. + size_t t = fread(buf, 1, START_CODE_SIZE_FRAME, fp); + if (t < START_CODE_SIZE_FRAME) { return true; } - size_t filled = 0; - filled = 4; - - bool bRet = true; + char *temp = buf; + temp += START_CODE_SIZE_FRAME; + bool ret = true; while (!feof(fp)) { - fread(buf + filled, 1, 1, fp); - if (buf[filled] == 1) { - // Check the start code. - if ((buf[filled - 1] == 0) && - (buf[filled - 2] == 0) && - (buf[filled - 3] == 0)) { - fseek(fp, -4, SEEK_CUR); - filled -= 3; - bRet = false; - break; - } else if ((buf[filled - 1] == 0) && - (buf[filled - 2] == 0)) { - fseek(fp, -3, SEEK_CUR); - filled -= 2; - bRet = false; - break; + (void)fread(temp, 1, 1, fp); + if (*temp != START_CODE) { + temp++; + continue; + } + // Check the start code. + if ((temp[START_CODE_OFFSET_ONE] == 0) && (temp[START_CODE_OFFSET_SEC] == 0) && + (temp[START_CODE_OFFSET_THIRD] == 0)) { + fseek(fp, -START_CODE_SIZE_FRAME, SEEK_CUR); + temp -= (START_CODE_SIZE_FRAME - 1); + ret = false; + break; } + if ((temp[START_CODE_OFFSET_ONE] == 0) && (temp[START_CODE_OFFSET_SEC] == 0)) { + fseek(fp, -START_CODE_SIZE_SLICE, SEEK_CUR); + temp -= (START_CODE_SIZE_SLICE - 1); + ret = false; + break; } - filled++; + temp++; } - nFilled = filled; - return bRet; + filledCount = (temp - buf); + return ret; } ``` The codec HDI provides the following callbacks: -- **EventHandler**: Called when a command is executed. For example, when the command for changing the component state from **OMX_StateIdle** to **OMX_StateExecuting** is executed, this callback is invoked to return the result. -- **EmptyBufferDone**: Called when the input data is consumed. If the client needs to fill in data to encode or decode, call **EmptyThisBuffer()**. -- **FillBufferDone**: Called when the output data is filled. If the client needs to read the encoded or decoded data, call **FillThisBuffer()**. +- **EventHandler**: Called when a command is executed. For example, when the command for changing the component state from **CODEC_STATE_IDLE** to **CODEC_STATE_EXECUTING** is executed, this callback is invoked to return the result. +- **EmptyBufferDone**: Called when the input data is consumed. If the client needs to fill data to encode or decode, it must call **EmptyThisBuffer()** again. +- **FillBufferDone**: Called when the output data is filled. If the client needs to read the encoded or decoded data, it must call **FillThisBuffer()** again. ```cpp // EmptyBufferDone example -int32_t OMXCore::OnEmptyBufferDone(struct CodecCallbackType *self, int8_t *pAppData, uint32_t pAppDataLen, - const struct OmxCodecBuffer *pBuffer) -{ - HDF_LOGI("onEmptyBufferDone: pBuffer.bufferID [%{public}d]", pBuffer->bufferId); - g_core->OnEmptyBufferDone(pBuffer); - return HDF_SUCCESS; -} -int32_t OMXCore::OnEmptyBufferDone(const struct OmxCodecBuffer *pBuffer) +int32_t CodecHdiDecode::OnEmptyBufferDone(const struct OmxCodecBuffer &buffer) { - unique_lock ulk(mLockInputBuffers_); - unUsedInBuffers_.push_back(pBuffer->bufferId); + HDF_LOGI("OnEmptyBufferDone, bufferId [%{public}d]", buffer.bufferId); + unique_lock ulk(lockInputBuffers_); + unUsedInBuffers_.push_back(buffer.bufferId); return HDF_SUCCESS; } // FillBufferDone example -int32_t OMXCore::OnFillBufferDone(struct CodecCallbackType *self, int8_t *pAppData, uint32_t pAppDataLen, - struct OmxCodecBuffer *pBuffer) +int32_t CodecHdiDecode::OnFillBufferDone(const struct OmxCodecBuffer &buffer) { - HDF_LOGI("onFillBufferDone: pBuffer.bufferID [%{public}d]", pBuffer->bufferId); - g_core->OnFillBufferDone(pBuffer); - return HDF_SUCCESS; -} -int32_t OMXCore::onFillBufferDone(struct OmxCodecBuffer* pBuffer) -{ - // Locate the buffer based on the buffer ID. - if (bExit_) { + HDF_LOGI("OnFillBufferDone, bufferId [%{public}d]", buffer.bufferId); + if (exit_) { return HDF_SUCCESS; } - auto iter = omxBuffers_.find(pBuffer->bufferId); - if (iter == omxBuffers_.end() || !iter->second) { + auto iter = omxBuffers_.find(buffer.bufferId); + if ((iter == omxBuffers_.end()) || (iter->second == nullptr)) { return HDF_SUCCESS; } - // Obtain the output data. - BufferInfo *pBufferInfo = iter->second; - const void *addr = pBufferInfo->avSharedPtr->ReadFromAshmem(pBuffer->filledLen, pBuffer->offset); - // Decode the data and save it to a file. - fwrite(addr, 1, pBuffer->filledLen, fpOut_.get()); - fflush(fpOut_.get()); - // Reset the buffer data. - pBuffer->offset = 0; - pBuffer->filledLen = 0; - if (pBuffer->flag == OMX_BUFFERFLAG_EOS) { - // End - bExit_ = true; + count_++; + // read buffer + auto bufferInfo = iter->second; + if (bufferInfo->avSharedPtr != nullptr) { + const void *addr = bufferInfo->avSharedPtr->ReadFromAshmem(buffer.filledLen, buffer.offset); + (void)fwrite(addr, 1, buffer.filledLen, fpOut_); + } else if (bufferInfo->bufferHandle != nullptr && gralloc_ != nullptr) { + gralloc_->Mmap(*bufferInfo->bufferHandle); + (void)fwrite(bufferInfo->bufferHandle->virAddr, 1, buffer.filledLen, fpOut_); + gralloc_->Unmap(*bufferInfo->bufferHandle); + } + + (void)fflush(fpOut_); + if (buffer.flag == OMX_BUFFERFLAG_EOS) { + // end + exit_ = true; HDF_LOGI("OnFillBufferDone the END coming"); return HDF_SUCCESS; } - // Call FillThisBuffer() again. - auto err = client_->FillThisBuffer(client_, pBufferInfo->pOmxBuffer); + // call fillthisbuffer again + auto err = client_->FillThisBuffer(*bufferInfo->omxBuffer.get()); if (err != HDF_SUCCESS) { - HDF_LOGE("FillThisBuffer error"); + HDF_LOGE("%{public}s FillThisBuffer error", __func__); return HDF_SUCCESS; } return HDF_SUCCESS; } - // EventHandler example -int32_t CodecHdiDecode::OnEvent(struct CodecCallbackType *self, enum OMX_EVENTTYPE event, struct EventInfo *info) +int32_t CodecHdiDecode::EventHandler(CodecEventType event, const EventInfo &info) { - HDF_LOGI("onEvent: appData[0x%{public}p], eEvent [%{public}d], " - "nData1[%{public}d]", - info->appData, event, info->data1); switch (event) { - case OMX_EventCmdComplete: { - OMX_COMMANDTYPE cmd = (OMX_COMMANDTYPE)info->data1; - if (OMX_CommandStateSet == cmd) { - HDF_LOGI("OMX_CommandStateSet reached, status is %{public}d", info->data2); - g_core->onStatusChanged(); + case CODEC_EVENT_CMD_COMPLETE: { + CodecCommandType cmd = (CodecCommandType)info.data1; + if (CODEC_COMMAND_STATE_SET == cmd) { + HDF_LOGI("CODEC_COMMAND_STATE_SET reached, status is %{public}d", info.data2); + this->OnStatusChanged(); } break; } + case OMX_EventPortSettingsChanged: { + HDF_LOGI("OMX_EventPortSeetingsChanged reached"); + this->HandleEventPortSettingsChanged(info.data1, info.data2); + } + default: break; } + return HDF_SUCCESS; } ``` #### Destroying a Component -Change the component state to IDLE, release the input and output buffers, change the component state to **OMX_StateLoaded**, and call **DestoryComponent** to destroy the component. +Change the component state to **CODEC_STATE_IDLE**, release the input and output buffers, change the component state to **CODEC_STATE_LOADED**, and call **DestoryComponent** to destroy the component. -##### Example of Releasing Buffers +##### Releasing Buffers ```cpp // Change the component state to OMX_StateLoaded. -client_->SendCommand(client_, OMX_CommandStateSet, OMX_StateLoaded, nullptr, 0); +client_->SendCommand(CODEC_COMMAND_STATE_SET, CODEC_STATE_LOADED, {}); // Release all buffers in use. auto iter = omxBuffers_.begin(); while (iter != omxBuffers_.end()) { - BufferInfo *bufferInfo = iter->second; - client_->FreeBuffer(client_, (uint32_t)bufferInfo->portIndex, bufferInfo->omxBuffer); - delete bufferInfo; - iter++; + auto bufferInfo = iter->second; + iter = omxBuffers_.erase(iter); + (void)client_->FreeBuffer((uint32_t)bufferInfo->portIndex, *bufferInfo->omxBuffer.get()); + bufferInfo = nullptr; } -omxBuffers_.clear(); + unUsedInBuffers_.clear(); unUsedOutBuffers_.clear(); -enum OMX_STATETYPE status; -client_->GetState(client_, &status); // After the buffers are released, the component enters the OMX_StateLoaded state. -if (status != OMX_StateLoaded) { - HDF_LOGI("Wait for OMX_StateLoaded status"); - this->WaitForStatusChanged(); -} else { - HDF_LOGI(" status is %{public}d", status); -} +CodecStateType status = CODEC_STATE_INVALID; +int32_t err = HDF_SUCCESS; +int32_t tryCount = 3; +do { + err = client_->GetState(status); + if (err != HDF_SUCCESS) { + HDF_LOGE("%s GetState error [%{public}x]", __func__, err); + break; + } + if (status != CODEC_STATE_LOADED) { + HDF_LOGI("Wait for OMX_StateLoaded status"); + this->WaitForStatusChanged(); + } + tryCount--; +} while ((status != CODEC_STATE_LOADED) && (tryCount > 0)); ``` -##### Example of Destroying a Component Instance +##### Destroying a Component Instance ```cpp // Destroy a component instance. -void OMXCore::Release() { - omxMgr_->DestoryComponent(client_); +void CodecHdiDecode::Release() +{ + omxMgr_->DestoryComponent(componentId_); client_ = nullptr; - CodecComponentManagerRelease(); + callback_ = nullptr; + omxMgr_ = nullptr; } ``` @@ -721,7 +742,7 @@ OpenMAX does not support framing. **Solution** -Transfer data frame by frame when **EmptyThisBuffer** is called. +When **EmptyThisBuffer** is call, only one frame can be passed in at a time. ## Only Green Screen Displayed During the Decoding Process @@ -745,15 +766,12 @@ After the generated video stream (H.264 stream) is written to a file, the video **Possible Causes** -- The **xFramerate** parameter of the output port is incorrectly set. -- The **OMX_VIDEO_PARAM_AVCTYPE** parameter is correctly set. - +1. The **xFramerate** parameter of the output port is incorrectly set. +2. The **OMX_VIDEO_PARAM_AVCTYPE** parameter is correctly set. **Solution** -View the **codec_host** log generated during encoding, search for "encode params init settings", and check for incorrect parameters. If **framerate** is **0**, **xFramerate** is incorrectly set. In this case, move the framerate leftwards by 16 bits. - -Check the value of **OMX_VIDEO_PARAM_AVCTYPE**, and set it correctly. +View the **codec_host** log generated during encoding, search for "encode params init settings", and check for incorrect parameters. If **framerate** is **0**, **xFramerate** is incorrectly set. In this case, move the frame rate leftwards by 16 bits.
In other cases, correct the setting of **OMX_VIDEO_PARAM_AVCTYPE**. # Reference diff --git a/en/device-dev/driver/driver-peripherals-external-des.md b/en/device-dev/driver/driver-peripherals-external-des.md index d2b681dcad9172b622cb261d81c9efdf3a0b86cc..04f0d7631555e55f7481da003d214a1715f5533d 100644 --- a/en/device-dev/driver/driver-peripherals-external-des.md +++ b/en/device-dev/driver/driver-peripherals-external-des.md @@ -3,164 +3,152 @@ ## Overview -### WLAN +### Function -The Wireless Local Area Network (WLAN) driver module is developed based on OpenHarmony Hardware Driver Foundation (HDF). It supports modular assembly and building, automatic adaptation to device differences, and cross-OS porting. +A wireless LAN (WLAN) allows users to easily connect to a wireless network to transmit and share data and move around within the area and remain connected to the network. The WLAN driver developed based on the Hardware Driver Foundation (HDF) shields hardware component differences and provides stable basic capability interfaces for upper-layer WLAN services, including starting a scan, associating with or disassociating from a hotspot, obtaining or setting MAC addresses, and obtaining link information. -### Working Principles - -You can modify your driver code based on the unified APIs provided by the WLAN module. The WLAN module provides: - -- APIs for the underlying layer to implement capabilities, such as opening or closing a WLAN hotspot, scanning hotspots, and connecting to or disconnecting from a hotspot. -- APIs for the Hardware Device Interface (HDI) layer to implement capabilities, such as setting or obtaining the device Media Access Control (MAC) address and setting the transmit power. - -The following figure shows the WLAN architecture. The WLAN driver module implements startup loading, parses configuration files, and provides bus abstraction APIs. The WLAN chip driver module provides the MAC Sublayer Management Entity (MLME). - - **Figure 1** WLAN architecture - - ![image](figures/WLAN_architecture.png "WLAN architecture") +### Basic Concepts - The following figure shows the WLAN driver architecture. +Before development, you need to understand the following basic concepts related to WLAN: - **Figure 2** WLAN driver architecture +- AP + + A wireless access point (AP) is a central node of a network that provides the wireless access service. Once connecting to the wireless network, the device can access data. - ![image](figures/WLAN_driver_architecture.png "WLAN driver architecture") +- STA + + A station (STA) is a basic component of a WLAN. Each terminal connected to a WLAN, such as a notebook and a personal digital assistant (PDA), is an STA. -The WLAN driver consists of the following modules: +- SSID + + A service set identifier (SSID) identifies a wireless network. Each WLAN has its SSID. -1. WLAN Message: provides an independent interface for each service or a composite service interface for multiple dependent services. It can run in the user mode, kernel mode, and MCU to implement complete decoupling between components. +- bssid + + A basic service set identifier (BSSID) is a 48-bit MAC address that uniquely identifies a basic service set on a WLAN. + +- Scan -2. WLAN Configuration Core: parses WLAN configuration files. + A terminal device scans the wireless network to obtain visible wireless network information, including the hotspot SSID, operating frequency band, and signal strength. -3. Access point (AP): allows devices to connect to the WLAN. +- Associate -4. Station (STA): a device that has access to the WLAN system and allows transmission and reception of data. + When a terminal device is associated with a valid hotspot, it can communicate with the AP. A device (STA) can set up a connection with only one AP at a time. -5. mac80211: defines MAC-layer APIs for underlying drivers. - -6. Bus: provides a unified bus abstract interface for the upper layer. It shields the differences between different kernels by calling the Secure Digital Input Output (SDIO) interfaces provided by the platform layer and encapsulating the adapted USB and PCIe interfaces. It also encapsulates different types of bus operations in a unified manner to shield differences between different chipsets. The complete bus driving capabilities provided by the bus module help simplify and streamline the development of different chip vendors. - -7. NetDevice: creates dedicated network devices to shield differences between OSs, provides unified interfaces for Wi-Fi drivers, unified HDF NetDevice data structure, and unified management, registration, and deregistration capabilities, and connects to the Linux network device layer on mini-, small-, standard, and large-system devices. - -8. NetBuf: encapsulates the unified data structure of the Linux or LiteOS native network data buffer and the operation interfaces for network data. +### Working Principles -9. FlowCtl: processes data based on the priority when the data volume is too large. +This document describes how to develop WLAN functions based on the HDF. The following figure shows the WLAN framework. -10. HCC-CFG: configures WLAN parameters, including the board configuration, driver configuration, and module configuration. +![image](figures/WLAN-driver-framework.png "WLAN Framework") -The relationships between the main modules are as follows: +1. The upper-layer service calls a hardware device interface (HDI) based on service requirements to deliver user-mode messages to the client through the Wi-Fi Protected Access (WPA) layer or hardware abstraction layer (HAL). The WPA layer provides interfaces for setting the encryption mode, associating with a hotspot, setting a channel, and hiding the hotspot. As a supplement to the WPA layer, the HAL provides APIs for setting the country code or MAC address and obtaining channel information. + +2. The Message module distributes user-mode messages to modules, such as the AP and STA, by component. + +3. Hdf_Mac80211 defines MAC-layer interfaces for underlying drivers. The command field is delivered to Hdf_Mac80211 and then sent to the WLAN chip firmware through the Bus module. + +4. The Bus module provides unified bus abstraction interfaces for the upper layer. It shields the differences between kernels by calling the Secure Digital Input Output (SDIO) interfaces provided by the platform layer and encapsulating the USB and PCIe interfaces. The Bus module also encapsulates different types of bus operations in a unified manner to shield differences between chipsets. The interfaces provided by the Bus module simplify and streamline the development of different chip vendors. + +5. Extensible Authentication Protocol (EAP) over LAN (EAPOL) is a LAN-based extended authentication protocol. It is used to transmit EAP packets between a client and a device (access device or server) so that EAP packets can be transmitted on a LAN to complete the authentication process and enable the device to go online. + +6. NetDevice creates dedicated network devices to shield differences between OSs. It provides unified interfaces for Wi-Fi drivers, unified HDF NetDevice data structs, and unified management, registration, and deregistration capabilities, and connects to the Linux network device layer on OpenHarmony devices. + +7. NetBuf encapsulates the unified data structure of the Linux or LiteOS native network data buffer and the operation interfaces for network data. + +8. The protocol stack works with the NetDevice and NetBuf modules to exchange data flows. -1. The WLAN driver works with HCC-CFG and WLAN Configuration Core to parse and load configuration files. +### Constraints -2. The WLAN Message module distributes user-mode messages to the AP and STA by component. +The WLAN driver provides basic capability interfaces for upper-layer WLAN services. The HDI interfaces apply to the standard system, and the HAL interfaces apply to mini and small systems. -3. Commands are delivered to mac80211, and then forwarded by the Bus module to the WLAN chip firmware. +## Development Guidelines -4. The protocol stack works with the NetDevice, NetBuf, and FlowCtl modules to exchange data flows. +### When to Use -## How to Develop +The WLAN driver provides basic capability interfaces for upper-layer WLAN services to ensure that users can easily access the wireless network and transmit and share data. Refer to the following when you adapt your WLAN module to OpenHarmony. ### Available APIs -The WLAN module provides the following types of APIs: +The WLAN module provides the following APIs: -1. HDI and Hardware Abstraction Layer (HAL) APIs for upper-layer services +1. HDI and HAL APIs for upper-layer services 2. APIs for vendors 3. WLAN APIs directly called by drivers - **Figure 3** WLAN driver APIs - - ![image](figures/WLAN_driver_APIs.png "WLAN Driver APIs") - - -- The WLAN module provides HAL APIs for upper-layer services (applicable to small and mini systems). **Table 1** and **Table 2** describe some APIs. +- This interfaces provided by the WLAN Driver module for upper-layer services can be used to create or destroy an IWiFi object, and set MAC addresses or transmit power. Table 1 and Table 2 list the C function interfaces generated based on the IDL interface description. For details about the interface declaration, see the IDL files (**/drivers/interface/wlan/v1_1/**). **Table 1** wifi_hal.h | API| Description| | -------- | -------- | - | int32_t WifiConstruct(struct IWiFi \*\*wifiInstance)| Creates an **IWiFi** instance with basic capabilities.| - | int32_t WifiDestruct(struct IWiFi \*\*wifiInstance)| Destroys an **IWiFi** instance.| - | int32_t (\*start)(struct IWiFi \*)| Creates a channel between the HAL and the driver and obtains the NICs supported by the driver.| - | int32_t (\*stop)(struct IWiFi \*)| Stops the channel between the HAL and the driver.| + | int32_t WifiConstruct(struct IWiFi \*\*wifiInstance) | Creates an **IWiFi** instance with basic capabilities.| + | int32_t WifiDestruct(struct IWiFi \*\*wifiInstance) | Destroys an **IWiFi** instance.| + | int32_t (\*start)(struct IWiFi \*) | Creates a channel between the HAL and the driver and obtains the NICs supported by the driver.| + | int32_t (\*stop)(struct IWiFi \*) | Stops the channel between the HAL and the driver.| **Table 2** wifi_hal_base_feature.h | API| Description| | -------- | -------- | - | int32_t (\*getFeatureType)(const struct IWiFiBaseFeature \*)| Obtains the feature type.| - | int32_t (\*setMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t)| Sets the MAC address.| - | int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t)| Obtains the device MAC address.| - | int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t)| Sets the transmit power.| + | int32_t (\*getFeatureType)(const struct IWiFiBaseFeature \*) | Obtains the feature type.| + | int32_t (\*setMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | Sets the MAC address.| + | int32_t (\*getDeviceMacAddress)(const struct IWiFiBaseFeature \*, unsigned char \*, uint8_t) | Obtains the device MAC address.| + | int32_t (\*setTxPower)(const struct IWiFiBaseFeature \*, int32_t) | Sets the transmit power.| -- The WLAN Driver module also provides APIs that you need to fill in the implementation. **Table 3** describes some APIs. +- The WLAN Driver module also provides APIs that you need to fill in the implementation. These APIs can be used to initialize or deregister a network device, open or stop a network device, and obtain network device status. Table 3 describes some APIs. **Table 3** net_device.h | API| Description| | -------- | -------- | - | int32_t (\*init)(struct NetDevice \*netDev)| Initializes a network device.| - | struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev)| Obtains the state of a network device.| - | int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr)| Sets the MAC address.| - | void (\*deInit)(struct NetDevice \*netDev)| Deinitializes a network device.| - | int32_t (\*open)(struct NetDevice \*netDev)| Opens a network device.| - | int32_t (\*stop)(struct NetDevice \*netDev)| Stops a network device.| + | int32_t (\*init)(struct NetDevice \*netDev) | Initializes a network device.| + | struct NetDevStats \*(\*getStats)(struct NetDevice \*netDev) | Obtains the state of a network device.| + | int32_t (\*setMacAddr)(struct NetDevice \*netDev, void \*addr) | Sets the MAC address.| + | void (\*deInit)(struct NetDevice \*netDev) | Deinitializes a network device.| + | int32_t (\*open)(struct NetDevice \*netDev) | Opens a network device.| + | int32_t (\*stop)(struct NetDevice \*netDev) | Stops a network device.| -- The WLAN Driver module provides APIs that you can directly use to create or release a **WifiModule**, connect to or disconnect from a WLAN hotspot, request or release a **NetBuf**, and convert between the **pbuf** structure of Lightweight IP (lwIP) and a **NetBuf**. +- The WLAN Driver module provides APIs that you can directly use to create or release a **WifiModule**, connect to or disconnect from a WLAN hotspot, request or release a **NetBuf**, and convert between the **pbuf** struct of Lightweight IP (lwIP) and a **NetBuf**. - The following tables describe the APIs. + Tables 4 to 6 list the APIs that can be directly called. - **Table 4** wifi_module.h + **Table 4** wifi_module.h | API| Description| | -------- | -------- | - | struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config)| Creates a **WifiModule**.| - | void WifiModuleDelete(struct WifiModule \*module)| Deletes a **WifiModule** and releases its data.| - | int32_t DelFeature(struct WifiModule \*module, uint16_t featureType)| Deletes a feature from a **WifiModule**.| - | int32_t AddFeature(struct WifiModule \*module, uint16_t featureType,
struct WifiFeature \*featureData)| Adds a feature to a **WifiModule**.| + | struct WifiModule \*WifiModuleCreate(const struct HdfConfigWifiModuleConfig \*config) | Creates a **WifiModule**.| + | void WifiModuleDelete(struct WifiModule \*module) | Deletes a **WifiModule** and releases its data.| + | int32_t DelFeature(struct WifiModule \*module, uint16_t featureType) | Deletes a feature from a **WifiModule**.| + | int32_t AddFeature(struct WifiModule \*module, uint16_t featureType,
 struct WifiFeature \*featureData) | Adds a feature to a **WifiModule**.| - **Table 5** wifi_mac80211_ops.h + **Table 5** wifi_mac80211_ops.h | API| Description| | -------- | -------- | - | int32_t (\*startAp)(NetDevice \*netDev)| Starts an AP.| - | int32_t (\*stopAp)(NetDevice \*netDev)| Stops an AP.| - | int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param)| Connects to a hotspot.| - | int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode)| Disconnects from a hotspot.| + | int32_t (\*startAp)(NetDevice \*netDev) | Starts an AP.| + | int32_t (\*stopAp)(NetDevice \*netDev) | Stops an AP.| + | int32_t (\*connect)(NetDevice \*netDev, WifiConnectParams \*param) | Connects to a hotspot.| + | int32_t (\*disconnect)(NetDevice \*netDev, uint16_t reasonCode) | Disconnects from a hotspot.| - **Table 6** hdf_netbuf.h + **Table 6** hdf_netbuf.h | API| Description| | -------- | -------- | - | static inline void NetBufQueueInit(struct NetBufQueue \*q)| Initializes a **NetBuf** queue.| - | struct NetBuf \*NetBufAlloc(uint32_t size)| Allocates a **NetBuf**.| - | void NetBufFree(struct NetBuf \*nb)| Releases a **NetBuf**.| - | struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf)| Converts the **pbuf** structure of lwIP to a **NetBuf**.| - | struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb)| Converts a **NetBuf** to the **pbuf** structure of lwIP.| - -### Development Procedure -#### WLAN Framework Adaptation - -The WLAN driver framework developed based on the HDF and Platform framework provides a unified driver model regardless of the OS and system on a chip (SoC). When developing your WLAN driver, you need to configure data based on the WLAN driver framework. -**Development Procedure** - -1. Configure hardware (such as modules and chips) parameters in the **wlan_platform.hcs** file. The HDF parses the file to generate structure objects with full configuration. - -2. Implement initialization and deinitialization of the WLAN module (such as initialize and deinitialize the WLAN chip and WLAN chip driver). + | static inline void NetBufQueueInit(struct NetBufQueue \*q) | Initializes a **NetBuf** queue.| + | struct NetBuf \*NetBufAlloc(uint32_t size) | Allocates a **NetBuf**.| + | void NetBufFree(struct NetBuf \*nb) | Releases a **NetBuf**.| + | struct NetBuf \*Pbuf2NetBuf(const struct NetDevice \*netdev, struct pbuf \*lwipBuf) | Converts the **pbuf** structure of lwIP to a **NetBuf**.| + | struct pbuf \*NetBuf2Pbuf(const struct NetBuf \*nb) | Converts a **NetBuf** to the **pbuf** structure of lwIP.| -3. Implement the delivery of control flow commands. +### How to Develop -4. Implement event reporting. +The WLAN driver framework developed based on the HDF and Platform framework provides a unified driver model for vendors regardless of the OS and system on a chip (SoC). When developing your WLAN driver based on the WLAN driver framework, you need to make adaptation. The following uses the Hi3881 WLAN chip as an example. -**Development Example** +#### Configuring the HCS for the Driver -The following uses the Hi3881 WLAN chip as an example to describe how to initialize a WLAN module. - -1. Configure the HDF configuration source (HCS) for the driver. - - The HCS includes device configuration and component configuration. + The HDF configuration source (HCS) includes device configuration and component configuration. - Device configuration @@ -223,8 +211,9 @@ The following uses the Hi3881 WLAN chip as an example to describe how to initial } ``` -2. Hook the **init** and **deinit** functions of the WLAN chip and WLAN chip driver. - - Implementing the driver adaptation entry function +#### Initializing and deinitializing the WLAN Chip and WLAN Chip Driver + + - Implement the driver adaptation entry function Define a variable of the HdfDriverEntry type based on the chip to hook functions of **Bind()**, **Init()**, and **Release()**. Call **HDF_INIT** to register the driver entry with the HDF. During driver loading, the HDF calls the **Bind** function and then the **Init** function to load the driver. If **Init()** fails to be called, the HDF calls **Release()** to release driver resources. ```c @@ -239,7 +228,7 @@ The following uses the Hi3881 WLAN chip as an example to describe how to initial HDF_INIT(g_hdfHisiChipEntry); ``` - - Registering the functions for initializing the chip and chip driver + - Register the functions for initializing the chip and chip driver Hook the chip initialization function to **InitChip()** and the chip deinitialization function to **DeinitChip()**. @@ -278,296 +267,308 @@ The following uses the Hi3881 WLAN chip as an example to describe how to initial } ``` - - Initializing and deinitializing the chip - ```c - /* Function for initializing the WLAN chip. */ - int32_t InitHi3881Chip(struct HdfWlanDevice *device) - { - uint8_t maxPortCount = 3; - int32_t ret = HI_SUCCESS; - uint8_t maxRetryCount = 3; - if (device == NULL || device->bus == NULL) { - HDF_LOGE("%s:NULL ptr!", __func__); - return HI_FAIL; - } - - do { - if (ret != HI_SUCCESS) { - if (device->reset != NULL && device->reset->Reset != NULL) { - device->reset->Reset(device->reset); - } - HDF_LOGE("%s:Retry init hi3881!last ret=%d", __func__, ret); - } - ret = hi_wifi_init(maxPortCount, device->bus); - } while (ret != 0 && --maxRetryCount > 0); - - if (ret != 0) { - HDF_LOGE("%s:Init hi3881 driver failed!", __func__); - return ret; - } - return HI_SUCCESS; - } - - /* Function for deinitializing the WLAN chip. */ - int32_t DeinitHi3881Chip(struct HdfWlanDevice *device) - { - (void)device; - int32_t ret = hi_wifi_deinit(); - if (ret != 0) { - HDF_LOGE("%s:Deinit failed!ret=%d", __func__, ret); - } - return ret; - } - ``` - - Initializing and deinitializing the chip driver - ```c - /* Hook the functions of the WLAN chip driver, mac80211, and chip. */ - static struct HdfChipDriver *BuildHi3881Driver(struct HdfWlanDevice *device, uint8_t ifIndex) - { - struct HdfChipDriver *specificDriver = NULL; - if (device == NULL) { - HDF_LOGE("%s fail: channel is NULL!", __func__); - return NULL; - } - (void)ifIndex; - specificDriver = (struct HdfChipDriver *)OsalMemCalloc(sizeof(struct HdfChipDriver)); - if (specificDriver == NULL) { - HDF_LOGE("%s fail: OsalMemCalloc fail!", __func__); - return NULL; - } - if (memset_s(specificDriver, sizeof(struct HdfChipDriver), 0, sizeof(struct HdfChipDriver)) != EOK) { - HDF_LOGE("%s fail: memset_s fail!", __func__); - OsalMemFree(specificDriver); - return NULL; - } - - if (strcpy_s(specificDriver->name, MAX_WIFI_COMPONENT_NAME_LEN, HI3881_DRIVER_NAME) != EOK) { - HDF_LOGE("%s fail: strcpy_s fail!", __func__); - OsalMemFree(specificDriver); - return NULL; - } - specificDriver->init = Hi3881Init; - specificDriver->deinit = Hi3881Deinit; - - HiMac80211Init(specificDriver); - - return specificDriver; - } - - /* Release the WLAN chip driver. */ - static void ReleaseHi3881Driver(struct HdfChipDriver *chipDriver) - { - if (chipDriver == NULL) { - return; - } - if (strcmp(chipDriver->name, HI3881_DRIVER_NAME) != 0) { - HDF_LOGE("%s:Not my driver!", __func__); - return; - } - OsalMemFree(chipDriver); - } - - /* Function for initializing the WLAN chip driver. */ - int32_t Hi3881Init(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) - { - hi_u16 mode; - int32_t ret; - nl80211_iftype_uint8 type; - (void)chipDriver; - HDF_LOGI("%s: start...", __func__); - mode = wal_get_vap_mode(); - if (mode >= WAL_WIFI_MODE_BUTT) { - oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); - return HI_FAIL; - } - if (mode == WAL_WIFI_MODE_STA) { - type = NL80211_IFTYPE_STATION; - #ifdef _PRE_WLAN_FEATURE_P2P - if (InitNetdev(netDevice, NL80211_IFTYPE_P2P_DEVICE) != HI_SUCCESS) { - return HI_FAIL; - } - #endif - } else if (mode == WAL_WIFI_MODE_AP) { - type = NL80211_IFTYPE_AP; - } else { - oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); - return HI_FAIL; - } - ret = wal_init_drv_wlan_netdev(type, WAL_PHY_MODE_11N, netDevice); - if (ret != HI_SUCCESS) { - oam_error_log2(0, OAM_SF_ANY, "wal_init_drv_netdev %s failed.l_return:%d\n", netDevice->name, ret); - } - return ret; - } - - /* Function for deinitializing the WLAN chip driver. */ - int32_t Hi3881Deinit(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) - { - int32_t ret; - (void)chipDriver; - ret = DeinitNetdev(NL80211_IFTYPE_P2P_DEVICE); - if (ret != HI_SUCCESS) { - oam_error_log1(0, OAM_SF_ANY, "Hi3881Deinit: DeinitNetdev p2p device fail, ret = %d\n", ret); - return ret; - } - return wal_deinit_drv_wlan_netdev(netDevice); - } - - ``` + 1. Initialize and deinitialize the chip. + + ```c + /* Function for initializing the WLAN chip. */ + int32_t InitHi3881Chip(struct HdfWlanDevice *device) + { + uint8_t maxPortCount = 3; + int32_t ret = HI_SUCCESS; + uint8_t maxRetryCount = 3; + if (device == NULL || device->bus == NULL) { + HDF_LOGE("%s:NULL ptr!", __func__); + return HI_FAIL; + } + + do { + if (ret != HI_SUCCESS) { + if (device->reset != NULL && device->reset->Reset != NULL) { + device->reset->Reset(device->reset); + } + HDF_LOGE("%s:Retry init hi3881!last ret=%d", __func__, ret); + } + ret = hi_wifi_init(maxPortCount, device->bus); + } while (ret != 0 && --maxRetryCount > 0); + + if (ret != 0) { + HDF_LOGE("%s:Init hi3881 driver failed!", __func__); + return ret; + } + return HI_SUCCESS; + } + + /* Function for deinitializing the WLAN chip. */ + int32_t DeinitHi3881Chip(struct HdfWlanDevice *device) + { + (void)device; + int32_t ret = hi_wifi_deinit(); + if (ret != 0) { + HDF_LOGE("%s:Deinit failed!ret=%d", __func__, ret); + } + return ret; + } + ``` - During the chip initialization process, call **NetDeviceInit()** to initialize a network device, call **NetDeviceAdd()** to add the network device to a protocol stack, and hook function pointers of **netdev**. + 2. Initialize and deinitialize the chip driver. + + ```c + /* Hook the functions of the WLAN chip driver, mac80211, and chip. */ + static struct HdfChipDriver *BuildHi3881Driver(struct HdfWlanDevice *device, uint8_t ifIndex) + { + struct HdfChipDriver *specificDriver = NULL; + if (device == NULL) { + HDF_LOGE("%s fail: channel is NULL!", __func__); + return NULL; + } + (void)ifIndex; + specificDriver = (struct HdfChipDriver *)OsalMemCalloc(sizeof(struct HdfChipDriver)); + if (specificDriver == NULL) { + HDF_LOGE("%s fail: OsalMemCalloc fail!", __func__); + return NULL; + } + if (memset_s(specificDriver, sizeof(struct HdfChipDriver), 0, sizeof(struct HdfChipDriver)) != EOK) { + HDF_LOGE("%s fail: memset_s fail!", __func__); + OsalMemFree(specificDriver); + return NULL; + } + + if (strcpy_s(specificDriver->name, MAX_WIFI_COMPONENT_NAME_LEN, HI3881_DRIVER_NAME) != EOK) { + HDF_LOGE("%s fail: strcpy_s fail!", __func__); + OsalMemFree(specificDriver); + return NULL; + } + specificDriver->init = Hi3881Init; + specificDriver->deinit = Hi3881Deinit; + + HiMac80211Init(specificDriver); + + return specificDriver; + } + + /* Release the WLAN chip driver. */ + static void ReleaseHi3881Driver(struct HdfChipDriver *chipDriver) + { + if (chipDriver == NULL) { + return; + } + if (strcmp(chipDriver->name, HI3881_DRIVER_NAME) != 0) { + HDF_LOGE("%s:Not my driver!", __func__); + return; + } + OsalMemFree(chipDriver); + } + + /* Function for initializing the WLAN chip driver. */ + int32_t Hi3881Init(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) + { + hi_u16 mode; + int32_t ret; + nl80211_iftype_uint8 type; + (void)chipDriver; + HDF_LOGI("%s: start...", __func__); + mode = wal_get_vap_mode(); + if (mode >= WAL_WIFI_MODE_BUTT) { + oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); + return HI_FAIL; + } + if (mode == WAL_WIFI_MODE_STA) { + type = NL80211_IFTYPE_STATION; + #ifdef _PRE_WLAN_FEATURE_P2P + if (InitNetdev(netDevice, NL80211_IFTYPE_P2P_DEVICE) != HI_SUCCESS) { + return HI_FAIL; + } + #endif + } else if (mode == WAL_WIFI_MODE_AP) { + type = NL80211_IFTYPE_AP; + } else { + oam_error_log1(0, 0, "wal_init_drv_netdev:: invalid mode[%d]", mode); + return HI_FAIL; + } + ret = wal_init_drv_wlan_netdev(type, WAL_PHY_MODE_11N, netDevice); + if (ret != HI_SUCCESS) { + oam_error_log2(0, OAM_SF_ANY, "wal_init_drv_netdev %s failed.l_return:%d\n", netDevice->name, ret); + } + return ret; + } + + /* Function for deinitializing the WLAN chip driver. */ + int32_t Hi3881Deinit(struct HdfChipDriver *chipDriver, struct NetDevice *netDevice) + { + int32_t ret; + (void)chipDriver; + ret = DeinitNetdev(NL80211_IFTYPE_P2P_DEVICE); + if (ret != HI_SUCCESS) { + oam_error_log1(0, OAM_SF_ANY, "Hi3881Deinit: DeinitNetdev p2p device fail, ret = %d\n", ret); + return ret; + } + return wal_deinit_drv_wlan_netdev(netDevice); + } - ```c - hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, oal_net_device_stru *netdev) - { - hi_char *ac_mode_str = NULL; - hi_s32 ret; - if (oal_unlikely(netdev == HI_NULL)) { - oam_error_log0(0, OAM_SF_ANY, "{netdev is null!}"); - return HI_ERR_CODE_PTR_NULL; - } + ``` - do { - /* Initialize the network device. */ - ret = wal_init_netdev(type, netdev); - if (ret != HI_SUCCESS) { - break; - } - - ret = wal_init_netif(type, netdev); - if (ret != HI_SUCCESS) { - break; - } - ac_mode_str = "11bgn"; - if (mode == WAL_PHY_MODE_11G) { - ac_mode_str = "11bg"; - } else if (mode == WAL_PHY_MODE_11B) { - ac_mode_str = "11b"; - } - - ret = wal_ioctl_set_mode(netdev, ac_mode_str); - } while (false); - - if (ret != HI_SUCCESS) { - wal_deinit_wlan_vap(netdev); - oal_net_unregister_netdev(netdev); - oal_net_clear_netdev(netdev); - return HI_FAIL; - } + During the chip initialization process, call **NetDeviceInit()** to initialize a network device, call **NetDeviceAdd()** to add the network device to a protocol stack, and hook function pointers of **netdev**. + + ```c + hi_s32 wal_init_drv_wlan_netdev(nl80211_iftype_uint8 type, wal_phy_mode mode, oal_net_device_stru *netdev) + { + hi_char *ac_mode_str = NULL; + hi_s32 ret; + if (oal_unlikely(netdev == HI_NULL)) { + oam_error_log0(0, OAM_SF_ANY, "{netdev is null!}"); + return HI_ERR_CODE_PTR_NULL; + } + + do { + /* Initialize the network device. */ + ret = wal_init_netdev(type, netdev); + if (ret != HI_SUCCESS) { + break; + } + + ret = wal_init_netif(type, netdev); + if (ret != HI_SUCCESS) { + break; + } + ac_mode_str = "11bgn"; + if (mode == WAL_PHY_MODE_11G) { + ac_mode_str = "11bg"; + } else if (mode == WAL_PHY_MODE_11B) { + ac_mode_str = "11b"; + } + + ret = wal_ioctl_set_mode(netdev, ac_mode_str); + } while (false); + + if (ret != HI_SUCCESS) { + wal_deinit_wlan_vap(netdev); + oal_net_unregister_netdev(netdev); + oal_net_clear_netdev(netdev); + return HI_FAIL; + } + + return HI_SUCCESS; + } + + /* Hook function pointers of netdev. For details, see NetDeviceInterFace. */ + oal_net_device_ops_stru g_wal_net_dev_ops = + { + .getStats = wal_netdev_get_stats, + .open = wal_netdev_open, + .stop = wal_netdev_stop, + .xmit = hmac_bridge_vap_xmit, + .ioctl = wal_net_device_ioctl, + .changeMtu = oal_net_device_change_mtu, + .init = oal_net_device_init, + .deInit = oal_net_free_netdev, + + ...... + + }; + + hi_s32 wal_init_netif(nl80211_iftype_uint8 type, oal_net_device_stru *netdev, const oal_wireless_dev *wdev) + { + /* Add the network device to the protocol stack. */ + hi_u32 ret = NetDeviceAdd(netdev, (Protocol80211IfType)type); + + ... + + return HI_SUCCESS; + } + ``` - return HI_SUCCESS; - } +#### Modifying the MAC Layer Interfaces - /* Hook function pointers of netdev. For details, see NetDeviceInterFace. */ - oal_net_device_ops_stru g_wal_net_dev_ops = - { - .getStats = wal_netdev_get_stats, - .open = wal_netdev_open, - .stop = wal_netdev_stop, - .xmit = hmac_bridge_vap_xmit, - .ioctl = wal_net_device_ioctl, - .changeMtu = oal_net_device_change_mtu, - .init = oal_net_device_init, - .deInit = oal_net_free_netdev, - - ... +After the user-mode message is delivered to the driver, the driver calls the corresponding MAC-layer capability interfaces. - }; + ```c + /* Define the functions for implementing the basic capabilities in the MAC layer for the driver. */ + static struct HdfMac80211BaseOps g_baseOps = { + .SetMode = WalSetMode, + .AddKey = WalAddKey, + .DelKey = WalDelKey, + .SetDefaultKey = WalSetDefaultKey, + .GetDeviceMacAddr = WalGetDeviceMacAddr, + .SetMacAddr = WalSetMacAddr, + .SetTxPower = WalSetTxPower, + .GetValidFreqsWithBand = WalGetValidFreqsWithBand, + .GetHwCapability = WalGetHwCapability + }; + + /* Define the functions for implementing the STA capabilities in the MAC layer for the driver. */ + static struct HdfMac80211STAOps g_staOps = { + .Connect = WalConnect, + .Disconnect = WalDisconnect, + .StartScan = WalStartScan, + .AbortScan = WalAbortScan, + .SetScanningMacAddress = WalSetScanningMacAddress, + }; + + /* Define the functions for implementing the AP capabilities in the MAC layer for the driver. */ + static struct HdfMac80211APOps g_apOps = { + .ConfigAp = WalConfigAp, + .StartAp = WalStartAp, + .StopAp = WalStopAp, + .ConfigBeacon = WalChangeBeacon, + .DelStation = WalDelStation, + .SetCountryCode = WalSetCountryCode, + .GetAssociatedStasCount = WalGetAssociatedStasCount, + .GetAssociatedStasInfo = WalGetAssociatedStasInfo + }; + + static struct HdfMac80211P2POps g_p2pOps = { + .RemainOnChannel = WalRemainOnChannel, + .CancelRemainOnChannel = WalCancelRemainOnChannel, + .ProbeReqReport = WalProbeReqReport, + .AddIf = WalAddIf, + .RemoveIf = WalRemoveIf, + .SetApWpsP2pIe = WalSetApWpsP2pIe, + .GetDriverFlag = WalGetDriverFlag + }; + + /* Initialize mac80211 and hook functions of the chip. */ + void HiMac80211Init(struct HdfChipDriver *chipDriver) + { + if (chipDriver == NULL) { + HDF_LOGE("%s:input is NULL!", __func__); + return; + } + chipDriver->ops = &g_baseOps; + chipDriver->staOps = &g_staOps; + chipDriver->apOps = &g_apOps; + chipDriver->p2pOps = &g_p2pOps; + } + ``` - hi_s32 wal_init_netif(nl80211_iftype_uint8 type, oal_net_device_stru *netdev, const oal_wireless_dev *wdev) - { - /* Add the network device to the protocol stack. */ - hi_u32 ret = NetDeviceAdd(netdev, (Protocol80211IfType)type); +#### Configuring Event Reporting - ... +The WLAN framework provides interfaces for event reporting. For details, see **hdf_wifi_event.c**. - return HI_SUCCESS; - } - ``` +The following presents how to use **HdfWiFiEventNewSta()** to report information about a newly associated STA. -3. Bind the commands to be delivered, including setting the MAC address and transmit power, implement STA connection and scan, start APs, and setting the country code. - - ```c - /* Implement the basic capabilities of the MAC layer. */ - static struct HdfMac80211BaseOps g_baseOps = { - .SetMode = WalSetMode, - .AddKey = WalAddKey, - .DelKey = WalDelKey, - .SetDefaultKey = WalSetDefaultKey, - .GetDeviceMacAddr = WalGetDeviceMacAddr, - .SetMacAddr = WalSetMacAddr, - .SetTxPower = WalSetTxPower, - .GetValidFreqsWithBand = WalGetValidFreqsWithBand, - .GetHwCapability = WalGetHwCapability - }; - - /* Implement the STA capabilities of the MAC layer. */ - static struct HdfMac80211STAOps g_staOps = { - .Connect = WalConnect, - .Disconnect = WalDisconnect, - .StartScan = WalStartScan, - .AbortScan = WalAbortScan, - .SetScanningMacAddress = WalSetScanningMacAddress, - }; - - /* Implement the AP capabilities of the MAC layer. */ - static struct HdfMac80211APOps g_apOps = { - .ConfigAp = WalConfigAp, - .StartAp = WalStartAp, - .StopAp = WalStopAp, - .ConfigBeacon = WalChangeBeacon, - .DelStation = WalDelStation, - .SetCountryCode = WalSetCountryCode, - .GetAssociatedStasCount = WalGetAssociatedStasCount, - .GetAssociatedStasInfo = WalGetAssociatedStasInfo - }; - - static struct HdfMac80211P2POps g_p2pOps = { - .RemainOnChannel = WalRemainOnChannel, - .CancelRemainOnChannel = WalCancelRemainOnChannel, - .ProbeReqReport = WalProbeReqReport, - .AddIf = WalAddIf, - .RemoveIf = WalRemoveIf, - .SetApWpsP2pIe = WalSetApWpsP2pIe, - .GetDriverFlag = WalGetDriverFlag - }; - - /* Initialize mac80211 and hook functions of the chip. */ - void HiMac80211Init(struct HdfChipDriver *chipDriver) - { - if (chipDriver == NULL) { - HDF_LOGE("%s:input is NULL!", __func__); - return; - } - chipDriver->ops = &g_baseOps; - chipDriver->staOps = &g_staOps; - chipDriver->apOps = &g_apOps; - chipDriver->p2pOps = &g_p2pOps; - } - ``` + ```c + hi_u32 oal_cfg80211_new_sta(oal_net_device_stru *net_device, const hi_u8 *mac_addr, hi_u8 addr_len, + oal_station_info_stru *station_info, oal_gfp_enum_uint8 en_gfp) + { + #if (_PRE_OS_VERSION_LINUX == _PRE_OS_VERSION) && !defined(_PRE_HDF_LINUX) + cfg80211_new_sta(net_device, mac_addr, station_info, en_gfp); + hi_unref_param(addr_len); + #elif (_PRE_OS_VERSION_LITEOS == _PRE_OS_VERSION) || defined(_PRE_HDF_LINUX) + struct StationInfo info = { 0 }; + info.assocReqIes = station_info->assoc_req_ies; + info.assocReqIesLen = station_info->assoc_req_ies_len; + HdfWifiEventNewSta(net_device, mac_addr, WLAN_MAC_ADDR_LEN, &info); + hi_unref_param(en_gfp); + hi_unref_param(addr_len); + #endif + + return HI_SUCCESS; + } + ``` -4. Invoke the event reporting APIs.
The WLAN framework provides the event reporting APIs. For details, see hdf_wifi_event.c.
For example, call **HdfWiFiEventNewSta AP** to report information about the newly associated STA. +### Debugging and Verification - ```c - hi_u32 oal_cfg80211_new_sta(oal_net_device_stru *net_device, const hi_u8 *mac_addr, hi_u8 addr_len, - oal_station_info_stru *station_info, oal_gfp_enum_uint8 en_gfp) - { - #if (_PRE_OS_VERSION_LINUX == _PRE_OS_VERSION) && !defined(_PRE_HDF_LINUX) - cfg80211_new_sta(net_device, mac_addr, station_info, en_gfp); - hi_unref_param(addr_len); - #elif (_PRE_OS_VERSION_LITEOS == _PRE_OS_VERSION) || defined(_PRE_HDF_LINUX) - struct StationInfo info = { 0 }; - info.assocReqIes = station_info->assoc_req_ies; - info.assocReqIesLen = station_info->assoc_req_ies_len; - HdfWifiEventNewSta(net_device, mac_addr, WLAN_MAC_ADDR_LEN, &info); - hi_unref_param(en_gfp); - hi_unref_param(addr_len); - #endif - - return HI_SUCCESS; - } - ``` -**Verification** +#### Driver Adaptation Verification Develop test cases in the WLAN module unit test to verify the basic features of the WLAN module. The following uses Hi3516D V300 standard system as an example. @@ -644,7 +645,9 @@ Develop test cases in the WLAN module unit test to verify the basic features of exit 0 ``` - - Create a **udhcpd.conf** file (used to start the **udhcpd**) and copy the following content to the file.
In the following, **opt dns** *x.x.x.x* *x.x.x.x* indicates two DNS servers configured. You can configure DNS servers as required. + - Create the **udhcpd.conf** file and copy the following content to the file. + + In the following example, "opt dns x.x.x.x x.x.x.x" indicates two DNS servers configured. You can configure DNS servers as required. ```text start 192.168.12.2 @@ -698,7 +701,7 @@ Develop test cases in the WLAN module unit test to verify the basic features of busybox udhcpd /vendor/etc/udhcpd.conf ``` - 4. On the mobile phone, select the network named **test** in the available Wi-Fi list and enter the password.
The network name and password are configured in the **hostapd.conf** file. You can see that network name in the connected Wi-Fi list if the connection is successful. + 4. On the mobile phone, select the network named **test** in the available Wi-Fi list and enter the password. (The network name and password are configured in the **hostapd.conf** file.) You can see that network name in the connected Wi-Fi list if the connection is successful. 5. Ping the test terminal from the development board. @@ -706,11 +709,11 @@ Develop test cases in the WLAN module unit test to verify the basic features of busybox ping xxx.xxx.xxx.xxx ``` - In the command, *xxx.xxx.xxx.xxx* indicates the IP address of the test terminal. If the test terminal can be pinged, the WLAN driver provides basic features normally. + In the command, xxx.xxx.xxx.xxx indicates the IP address of the test terminal. If the test terminal can be pinged, the WLAN driver provides basic features normally. - - Verify basic STA features. + - Verify basic STA functions - 1. Start the STA on the development board, and enable the hotspot on the test terminal.
The hotspot name and password are configured in the **hostapd.conf** file. The hotspot name is **test**, and the password is **12345678**. + 1. Start the STA on the development board, and enable the hotspot on the test terminal. (The hotspot name and password are configured in the **hostapd.conf** file. The hotspot name is **test**, and the password is **12345678**.) 2. Run the following command in the **cmd** window: @@ -737,8 +740,9 @@ Develop test cases in the WLAN module unit test to verify the basic features of In the command, xxx.xxx.xxx.xxx indicates the IP address of the test terminal. If the test terminal can be pinged, the WLAN driver provides basic features normally. -#### **API Invocation** -The WLAN driver module provides two types of capability interfaces for the upper layer: HDI interface and HAL interface. +#### API Usage Example + +The WLAN Driver module provides two types of capability interfaces for the upper layer: HDI APIs and HAL APIs. - HDI API invocation The following uses **GetSupportFeature** as an example to describe the development procedure: @@ -753,7 +757,7 @@ The WLAN driver module provides two types of capability interfaces for the upper 5. Call **WlanInterfaceRelease()** to destroy the WLAN service instance. - The sample code is as follows: + Example: ```c #include "v1_0/iwlan_interface.h" #include "wlan_callback_impl.h" @@ -848,7 +852,7 @@ The WLAN driver module provides two types of capability interfaces for the upper 7. Call **WifiDestruct()** to destroy the **IWiFi** instance. - The sample code is as follows: + Example: ```c #include "wifi_hal.h" @@ -947,17 +951,16 @@ The WLAN driver module provides two types of capability interfaces for the upper - Code paths: - Adaptation of WLAN FlowCtl component on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network/wifi** - - Adaptation of HDF network model on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network** + - Adaptation of WLAN FlowCtl component on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network/wifi** - Adaptation of WLAN FlowCtl component on Linux, build of the HDF WLAN model, and build of the vendor's WLAN driver: **//drivers/hdf_core/adapter/khdf/linux/model/network/wifi** + - Adaptation of HDF network model on LiteOS: **//drivers/hdf_core/adapter/khdf/liteos/model/network** - Core code for implementing the WLAN module: **//drivers/hdf_core/framework/model/network/wifi** + - Adaptation of WLAN FlowCtl component on Linux, build of the HDF WLAN model, and build of the vendor's WLAN driver: **//drivers/hdf_core/adapter/khdf/linux/model/network/wifi** - External APIs of the WLAN module: **//drivers/hdf_core/framework/include/wifi** + - Core code for implementing the WLAN module: **//drivers/hdf_core/framework/model/network/wifi** - HDF network model APIs: **//drivers/hdf_core/framework/include/net** + - External APIs of the WLAN module: **//drivers/hdf_core/framework/include/wifi** - WLAN HDI server implementation: **//drivers/peripheral/wlan** + - HDF network model APIs: **//drivers/hdf_core/framework/include/net** + - WLAN HDI server implementation: **//drivers/peripheral/wlan** diff --git a/en/device-dev/driver/figures/WLAN-driver-framework.png b/en/device-dev/driver/figures/WLAN-driver-framework.png new file mode 100644 index 0000000000000000000000000000000000000000..4dbbe0b49a4e5a61993152d266fa21dad18014c7 Binary files /dev/null and b/en/device-dev/driver/figures/WLAN-driver-framework.png differ diff --git a/en/device-dev/driver/figures/WLAN_architecture.png b/en/device-dev/driver/figures/WLAN_architecture.png deleted file mode 100644 index 2479e5101bf555d57c0ed700d82e7671b868bc3a..0000000000000000000000000000000000000000 Binary files a/en/device-dev/driver/figures/WLAN_architecture.png and /dev/null differ diff --git a/en/device-dev/driver/figures/WLAN_driver_APIs.png b/en/device-dev/driver/figures/WLAN_driver_APIs.png deleted file mode 100644 index 19cee91371e94ae6c375c4011174f65b2e0f5664..0000000000000000000000000000000000000000 Binary files a/en/device-dev/driver/figures/WLAN_driver_APIs.png and /dev/null differ diff --git a/en/device-dev/driver/figures/WLAN_driver_architecture.png b/en/device-dev/driver/figures/WLAN_driver_architecture.png deleted file mode 100644 index a902741d5f92c6a3b80ad5e51cb2f9343ed91787..0000000000000000000000000000000000000000 Binary files a/en/device-dev/driver/figures/WLAN_driver_architecture.png and /dev/null differ diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md index 6f995e544e3c27be0aac36f334b485c7e69baa22..109dad778e2361330dc7343cf0b51168c0f03640 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-proxy.md @@ -28,7 +28,7 @@ 1. 数据提供方以`key + subscriberId`作为数据的标识,将数据存储到数据库。 2. 数据管理服务感知到数据库变化,将新的数据发布给当前注册的所有订阅实例。 3. 卡片管理服务从订阅实例中解析出数据,发送给卡片渲染服务。 -4. 卡片渲染服务运行卡片页面代码widgets.abc,widgets.abc按新数据进行渲染,并将渲染后的数据发送至卡片使用方对应的[卡片组件](https://gitee.com/openharmony/docs/blob/fd489446c497c09d86ffa3beafd73dad90f1adb6/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md)。 +4. 卡片渲染服务运行卡片页面代码widgets.abc,widgets.abc按新数据进行渲染,并将渲染后的数据发送至卡片使用方对应的[卡片组件](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md)。 数据提供方提供的共享数据有两种类型: @@ -177,7 +177,7 @@ } ``` -- 在卡片页面代码widgets.abc中,通过LocalStorage变量获取订阅到的数据,LocalStorage绑定了一个字符串,以key:value的键值对格式来刷新卡片订阅数据,其中key必须与卡片提供方订阅的key保持一致。示例中,通过'list'获取订阅的数据,并把第一个元素的值显示在Text组件上。 +- 在卡片页面代码文件(一般为工程中卡片目录下pages目录中的.ets文件)中,通过LocalStorage变量获取订阅到的数据,LocalStorage绑定了一个字符串,以key:value的键值对格式来刷新卡片订阅数据,其中key必须与卡片提供方订阅的key保持一致。示例中,通过'list'获取订阅的数据,并把第一个元素的值显示在Text组件上。 ```ts let storage = new LocalStorage(); @Entry(storage) diff --git a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md index 50e72306f7ab210debc55ee69f04d084b641ab29..c987a54bf9f52e28025d4df47cc61a80e2bcf24d 100644 --- a/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md +++ b/zh-cn/application-dev/application-models/arkts-ui-widget-update-by-status.md @@ -20,7 +20,8 @@ }, "colorMode": "auto", "isDefault": true, - "updateEnabled": true,"scheduledUpdateTime": "07:00", + "updateEnabled": true, + "scheduledUpdateTime": "07:00", "updateDuration": 0, "defaultDimension": "2*2", "supportDimensions": ["2*2"] @@ -102,10 +103,15 @@ let isTempCard: boolean = want.parameters[formInfo.FormParam.TEMPORARY_KEY]; if (isTempCard === false) { // 如果为常态卡片,直接进行信息持久化 console.info('Not temp card, init db for:' + formId); - let storeDB = dataPreferences.getPreferences(this.context, 'mystore') - storeDB.put('A' + formId, 'false'); - storeDB.put('B' + formId, 'false'); - storeDB.flush(); + let promise = dataPreferences.getPreferences(this.context, 'myStore'); + promise.then((storeDB) => { + console.info("Succeeded to get preferences."); + storeDB.putSync('A' + formId, 'false'); + storeDB.putSync('B' + formId, 'false'); + storeDB.flush(); + }).catch((err) => { + console.info(`Failed to get preferences. ${JSON.stringify(err)}`); + }) } let formData = {}; return formBindingData.createFormBindingData(formData); @@ -113,54 +119,71 @@ onRemoveForm(formId) { console.info('onRemoveForm, formId:' + formId); - let storeDB = dataPreferences.getPreferences(this.context, 'mystore') - storeDB.delete('A' + formId); - storeDB.delete('B' + formId); + let promise = dataPreferences.getPreferences(this.context, 'myStore'); + promise.then((storeDB) => { + console.info("Succeeded to get preferences."); + storeDB.deleteSync('A' + formId); + storeDB.deleteSync('B' + formId); + }).catch((err) => { + console.info(`Failed to get preferences. ${JSON.stringify(err)}`); + }) } // 如果在添加时为临时卡片,则建议转为常态卡片时进行信息持久化 onCastToNormalForm(formId) { console.info('onCastToNormalForm, formId:' + formId); - let storeDB = dataPreferences.getPreferences(this.context, 'myStore') - storeDB.put('A' + formId, 'false'); - storeDB.put('B' + formId, 'false'); - storeDB.flush(); + let promise = dataPreferences.getPreferences(this.context, 'myStore'); + promise.then((storeDB) => { + console.info("Succeeded to get preferences."); + storeDB.putSync('A' + formId, 'false'); + storeDB.putSync('B' + formId, 'false'); + storeDB.flush(); + }).catch((err) => { + console.info(`Failed to get preferences. ${JSON.stringify(err)}`); + }) } onUpdateForm(formId) { - let storeDB = dataPreferences.getPreferences(this.context, 'myStore') - let stateA = storeDB.get('A' + formId, 'false').toString() - let stateB = storeDB.get('B' + formId, 'false').toString() - // A状态选中则更新textA - if (stateA === 'true') { - let formInfo = formBindingData.createFormBindingData({ - 'textA': 'AAA' - }) - formProvider.updateForm(formId, formInfo) - } - // B状态选中则更新textB - if (stateB === 'true') { - let formInfo = formBindingData.createFormBindingData({ - 'textB': 'BBB' - }) - formProvider.updateForm(formId, formInfo) - } + let promise = dataPreferences.getPreferences(this.context, 'myStore'); + promise.then((storeDB) => { + console.info("Succeeded to get preferences."); + let stateA = storeDB.getSync('A' + formId, 'false').toString(); + let stateB = storeDB.getSync('B' + formId, 'false').toString(); + // A状态选中则更新textA + if (stateA === 'true') { + let formInfo = formBindingData.createFormBindingData({'textA': 'AAA'}); + formProvider.updateForm(formId, formInfo); + } + // B状态选中则更新textB + if (stateB === 'true') { + let formInfo = formBindingData.createFormBindingData({'textB': 'BBB'}); + formProvider.updateForm(formId, formInfo); + } + console.info(`Update form success stateA:${stateA} stateB:${stateB}.`); + }).catch((err) => { + console.info(`Failed to get preferences. ${JSON.stringify(err)}`); + }) } onFormEvent(formId, message) { // 存放卡片状态 console.info('onFormEvent formId:' + formId + 'msg:' + message); - let storeDB = dataPreferences.getPreferences(this.context, 'myStore') - let msg = JSON.parse(message) - if (msg.selectA != undefined) { - console.info('onFormEvent selectA info:' + msg.selectA); - storeDB.put('A' + formId, msg.selectA); - } - if (msg.selectB != undefined) { - console.info('onFormEvent selectB info:' + msg.selectB); - storeDB.put('B' + formId, msg.selectB); - } - storeDB.flush(); + let promise = dataPreferences.getPreferences(this.context, 'myStore'); + promise.then((storeDB) => { + console.info("Succeeded to get preferences."); + let msg = JSON.parse(message); + if (msg.selectA != undefined) { + console.info('onFormEvent selectA info:' + msg.selectA); + storeDB.putSync('A' + formId, msg.selectA); + } + if (msg.selectB != undefined) { + console.info('onFormEvent selectB info:' + msg.selectB); + storeDB.putSync('B' + formId, msg.selectB); + } + storeDB.flush(); + }).catch((err) => { + console.info(`Failed to get preferences. ${JSON.stringify(err)}`); + }) } }; ``` diff --git a/zh-cn/application-dev/database/share-data-by-silent-access.md b/zh-cn/application-dev/database/share-data-by-silent-access.md index eb531ac0880f9a0783c6ada9d333d644253b620f..60d13a072f7da5fe9420509790833ed40e541363 100644 --- a/zh-cn/application-dev/database/share-data-by-silent-access.md +++ b/zh-cn/application-dev/database/share-data-by-silent-access.md @@ -96,8 +96,8 @@ | 属性名称 | 备注说明 | 必填 | | ----------------------- | ---------------------------------------- | ---- | | uri | 数据使用的URI,是跨应用数据访问的唯一标识。 | 是 | - | requiredReadPermission | 访问数据时需要的权限,不配置默认不允许其他APP访问数据。 | 否 | - | requiredWritePermission | 修改数据时需要的权限,不配置默认不允许其他APP修改数据。 | 否 | + | requiredReadPermission | 标识从该数据代理读取数据时所需要的权限,不配置默认不允许其他APP访问数据。支持权限可参考[权限列表](../security/permission-list.md)。 | 否 | + | requiredWritePermission | 标识从该数据代理修改数据时所需要的权限,不配置默认不允许其他APP修改数据。支持权限可参考[权限列表](../security/permission-list.md)。 | 否 | | metadata | 数据源的信息,包含name和resource字段。
name类型固定为"dataProperties",是配置的唯一标识。
resource类型固定为"$profile:{fileName}",表示配置文件的名称为{fileName}.json。 | 是 | **module.json5配置样例:** @@ -107,7 +107,7 @@ { "uri": "datashareproxy://com.acts.ohos.data.datasharetest/test", "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO", - "requiredWritePermission": "ohos.permission.GET_BUNDLE_INFO", + "requiredWritePermission": "ohos.permission.KEEP_BACKGROUND_RUNNING", "metadata": { "name": "dataProperties", "resource": "$profile:my_config" @@ -244,8 +244,8 @@ | 属性名称 | 备注说明 | 必填 | | ----------------------- | ----------------------------- | ---- | | uri | 数据使用的URI,是跨应用数据访问的唯一标识。 | 是 | -| requiredReadPermission | 访问数据时需要的权限,不配置默认不允许其他APP访问数据。 | 否 | -| requiredWritePermission | 修改数据时需要的权限,不配置默认不允许其他APP修改数据。 | 否 | +| requiredReadPermission | 标识从该数据代理读取数据时所需要的权限,不配置默认不允许其他APP访问数据。支持权限可参考[权限列表](../security/permission-list.md)。 | 否 | +| requiredWritePermission | 标识从该数据代理修改数据时所需要的权限,不配置默认不允许其他APP访问数据。支持权限可参考[权限列表](../security/permission-list.md)。 | 否 | **module.json5配置样例:** @@ -254,7 +254,7 @@ { "uri": "datashareproxy://com.acts.ohos.data.datasharetest/weather", "requiredReadPermission": "ohos.permission.GET_BUNDLE_INFO", - "requiredWritePermission": "ohos.permission.GET_BUNDLE_INFO" + "requiredWritePermission": "ohos.permission.KEEP_BACKGROUND_RUNNING" } ] ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-common.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-common.md index 101320203d58556a56d6d5d742dd87d573148a05..b9fa6aa45bdda2596691cc3fd04785c3b5a7ad72 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-common.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-common.md @@ -12,6 +12,7 @@ Common模块将二级模块API组织在一起方便开发者进行导出。 ```ts import common from '@ohos.app.ability.common'; ``` +## 属性 **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-configuration.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-configuration.md index 1dedb6e904e4e37555c7c69199bc7e72751108d9..67ff713322188b7817a183df43a4e2c4446e6b29 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-configuration.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-configuration.md @@ -12,6 +12,8 @@ import Configuration from '@ohos.app.ability.Configuration'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md index 720a5a6b78bef9c78c93594f32d59781816299cc..dd967e7981f4e2b3aee42a2d67a63440c89b0149 100755 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md @@ -1098,3 +1098,315 @@ try { console.error('moveMissionToFront failed. Cause: ${error.message}'); } ``` + +## missionManager.moveMissionsToForeground10+ + +moveMissionsToForeground(missionIds: Array<number>, callback: AsyncCallback<void>): void; + +将指定任务批量切到前台,以回调函数的方式返回。 + +**需要权限**:ohos.permission.MANAGE_MISSIONS + +**系统能力**:SystemCapability.Ability.AbilityRuntime.Mission + +**系统接口**: 此接口为系统接口。 + +**参数:** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | missionIds | Array<number> | 是 | 任务ID数组。 | + | callback | AsyncCallback<void> | 是 | 执行结果回调函数。 | + +**错误码**: + +以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +**示例:** + +```ts +import abilityManager from '@ohos.app.ability.abilityManager'; +import missionManager from '@ohos.app.ability.missionManager'; + +try { + missionManager.getMissionInfos("", 10, (error, missionInfos) => { + if (error.code) { + console.log("getMissionInfos failed, error.code:" + JSON.stringify(error.code)); + return; + } + if (missionInfos.length < 1) { + return; + } + + let toShows = new Array(); + for (let missionInfo of missionInfos) { + if (missionInfo.abilityState == abilityManager.AbilityState.BACKGROUND) { + toShows.push(missionInfo.missionId); + } + } + missionManager.moveMissionsToForeground(toShows, (err, data) => { + if (err) { + console.error('moveMissionsToForeground failed: ${err.message}'); + } else { + console.info('moveMissionsToForeground successfully: ${JSON.stringify(data)}'); + } + }); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} + +``` + +## missionManager.moveMissionsToForeground10+ + +moveMissionsToForeground(missionIds: Array<number>, topMission: number, callback: AsyncCallback<void>): void; + +将指定任务批量切换到前台,并将任务ID等于topMission的任务移动到最顶层,以回调函数的方式返回。 + +**需要权限**:ohos.permission.MANAGE_MISSIONS + +**系统能力**:SystemCapability.Ability.AbilityRuntime.Mission + +**系统接口**: 此接口为系统接口。 + +**参数:** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | missionIds | Array<number> | 是 | 任务ID数组。 | + | topMission | number | 是 | 待移动到最顶层的任务ID | + | callback | AsyncCallback<void> | 是 | 执行结果回调函数。 | + +**错误码**: + +以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +**示例:** + +```ts +import abilityManager from '@ohos.app.ability.abilityManager'; +import missionManager from '@ohos.app.ability.missionManager'; + +try { + missionManager.getMissionInfos("", 10, (error, missionInfos) => { + if (error.code) { + console.log("getMissionInfos failed, error.code:" + JSON.stringify(error.code)); + return; + } + if (missionInfos.length < 1) { + return; + } + + let toShows = new Array(); + for (let missionInfo of missionInfos) { + if (missionInfo.abilityState == abilityManager.AbilityState.BACKGROUND) { + toShows.push(missionInfo.missionId); + } + } + missionManager.moveMissionsToForeground(toShows, toShows[0], (err, data) => { + if (err) { + console.error('moveMissionsToForeground failed: ${err.message}'); + } else { + console.info('moveMissionsToForeground successfully: ${JSON.stringify(data)}'); + } + }); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} + +``` + +## missionManager.moveMissionsToForeground10+ + +moveMissionsToForeground(missionIds: Array<number>, topMission?: number): Promise<void>; + +将指定任务批量切到前台,并将任务ID等于topMission的任务移动到最顶层,以promise的方式返回。 + +**需要权限**:ohos.permission.MANAGE_MISSIONS + +**系统能力**:SystemCapability.Ability.AbilityRuntime.Mission + +**系统接口**: 此接口为系统接口。 + +**参数:** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | missionIds | Array<number> | 是 | 任务ID数组。 | + | topMission | number | 否 | 待移动到最顶层的任务ID | + +**返回值:** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<void> | promise方式返回执行结果。 | + +**错误码**: + +以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +**示例:** + +```ts +import abilityManager from '@ohos.app.ability.abilityManager'; +import missionManager from '@ohos.app.ability.missionManager'; + +try { + missionManager.getMissionInfos("", 10, (error, missionInfos) => { + if (error.code) { + console.log("getMissionInfos failed, error.code:" + JSON.stringify(error.code)); + return; + } + if (missionInfos.length < 1) { + return; + } + + let toShows = new Array(); + for (let missionInfo of missionInfos) { + if (missionInfo.abilityState == abilityManager.AbilityState.BACKGROUND) { + toShows.push(missionInfo.missionId); + } + } + missionManager.moveMissionsToForeground(toShows, toShows[0]).then(() => { + console.log("moveMissionsToForeground is called" ); + }); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} + +``` + +## missionManager.moveMissionsToBackground10+ + +moveMissionsToBackground(missionIds: Array<number>, callback: AsyncCallback<Array<number>>): void; + +将指定任务批量切到后台,以回调函数的方式返回, 返回的结果任务ID按被隐藏时的任务层级排序。 + +**需要权限**:ohos.permission.MANAGE_MISSIONS + +**系统能力**:SystemCapability.Ability.AbilityRuntime.Mission + +**系统接口**: 此接口为系统接口。 + +**参数:** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | missionIds | Array<number> | 是 | 任务ID数组。 | + | callback | AsyncCallback<Array<number>> | 是 | 执行结果回调函数。 | + +**错误码**: + +以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +**示例:** + +```ts +import abilityManager from '@ohos.app.ability.abilityManager'; +import missionManager from '@ohos.app.ability.missionManager'; + +try { + missionManager.getMissionInfos("", 10, (error, missionInfos) => { + if (error.code) { + console.log("getMissionInfos failed, error.code:" + JSON.stringify(error.code)); + return; + } + + let toHides = new Array(); + for (let missionInfo of missionInfos) { + if (missionInfo.abilityState == abilityManager.AbilityState.FOREGROUND) { + toHides.push(missionInfo.missionId); + } + } + missionManager.moveMissionsToBackground(toHides, (err, data) => { + if (err) { + console.error('moveMissionsToBackground failed: ${err.message}'); + } else { + console.info('moveMissionsToBackground successfully: ${JSON.stringify(data)}'); + } + }); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} +``` + +## missionManager.moveMissionsToBackground10+ + +moveMissionsToBackground(missionIds : Array<number>): Promise<Array<number>>; + +将指定任务批量切到后台,以promise的方式返回, 返回的结果按被隐藏时的任务层级排序。 + +**需要权限**:ohos.permission.MANAGE_MISSIONS + +**系统能力**:SystemCapability.Ability.AbilityRuntime.Mission + +**系统接口**: 此接口为系统接口。 + +**参数:** + + | 参数名 | 类型 | 必填 | 说明 | + | -------- | -------- | -------- | -------- | + | missionIds | Array<number> | 是 | 任务ID数组。 | + +**返回值:** + + | 类型 | 说明 | + | -------- | -------- | + | Promise<Array<number>> | promise方式返回执行结果。 | + +**错误码**: + +以下错误码的详细介绍请参见[errcode-ability](../errorcodes/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| ------- | -------- | +| 16000050 | Internal error. | + +**示例:** + +```ts +import abilityManager from '@ohos.app.ability.abilityManager'; +import missionManager from '@ohos.app.ability.missionManager'; + +try { + missionManager.getMissionInfos("", 10, (error, missionInfos) => { + if (error.code) { + console.log("getMissionInfos failed, error.code:" + JSON.stringify(error.code)); + return; + } + + let toHides = new Array(); + for (let missionInfo of missionInfos) { + if (missionInfo.abilityState == abilityManager.AbilityState.FOREGROUND) { + toHides.push(missionInfo.missionId); + } + } + missionManager.moveMissionsToBackground(toHides).then((hideRes) => { + console.log("moveMissionsToBackground is called, res: "+ JSON.stringify(hideRes)); + }); + }); +} catch (paramError) { + console.log("error: " + paramError.code + ", " + paramError.message); +} + +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-data-dataShare.md b/zh-cn/application-dev/reference/apis/js-apis-data-dataShare.md index 8eac658728dd5ebf6261a9ed8526762d3db71cba..9108469149f87ad75973ac02caab20f5ce975cee 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-data-dataShare.md +++ b/zh-cn/application-dev/reference/apis/js-apis-data-dataShare.md @@ -199,7 +199,7 @@ try { | 名称 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | key | string | 是 | 指定发布数据的键。 | -| data | string \| [Ashmem](js-apis-rpc.md#ashmem8) | 是 | 指定发布的数据。如果数据很大,请使用Ashmem。 | +| data | string \| ArrayBuffer | 是 | 指定发布的数据。如果发布数据大小超过20KB,建议使用ArrayBuffer。 | | subscriberId | string | 是 | 指定订阅者id。 | ## RdbDataChangeNode10+ @@ -478,18 +478,15 @@ on(type: 'publishedDataChange', uris: Array<string>, subscriberId: string, **示例:** ```ts -import rpc from '@ohos.rpc'; - function onPublishCallback(err, node:dataShare.PublishedDataChangeNode) { console.info("onPublishCallback node bundleName " + JSON.stringify(node.bundleName)); console.info("onPublishCallback node data size" + node.data.length); for (let i = 0; i < node.data.length; i++) { console.info("onPublishCallback node " + typeof node.data[i].data); if (typeof node.data[i].data != 'string') { - let ash:rpc.Ashmem = node.data[i].data; - ash.mapReadonlyAshmem(); - console.info("onPublishCallback " + JSON.stringify(ash.readAshmem(ash.getAshmemSize()/4, 0))); - ash.closeAshmem(); + let array:ArrayBuffer = node.data[i].data; + let data:Uint8Array = new Uint8Array(array); + console.info("onPublishCallback " + i + " " + JSON.stringify(data)); } console.info("onPublishCallback data " + i + " " + JSON.stringify(node.data[i])); } @@ -561,29 +558,13 @@ publish(data: Array<PublishedItem>, bundleName: string, version: number, c **示例:** ```ts -import rpc from '@ohos.rpc'; - -let ashmem = null; -let subscriberId = '11'; +let arrayBuffer = new ArrayBuffer(1); let version = 1; -let data : Array = [ - {key:"city", subscriberId:"11", data:"xian"}, - {key:"datashareproxy://com.acts.ohos.data.datasharetest/appInfo", subscriberId:"11", data:"appinfo is just a test app"}, - {key:"empty", subscriberId:"11", data:"nobody sub"}]; -let nums:number[] = [1,2,3]; +let data : Array = [{key:"key2", subscriberId:"11", data:arrayBuffer}]; function publishCallback(err, result: Array) { console.info("publishCallback " + JSON.stringify(result)); - ashmem.closeAshmem(); } try { - ashmem = rpc.Ashmem.create("ashmem", (nums.length) * 4); - ashmem.mapReadWriteAshmem(); - ashmem.writeAshmem(nums, nums.length, 0); - data.push({ - "key" : "key2", - "data" : ashmem, - "subscriberId" : "11", - }); console.info("data length is:", data.length); dataShareHelper.publish(data, "com.acts.ohos.data.datasharetest", version, publishCallback); } catch (e) { diff --git a/zh-cn/application-dev/reference/apis/js-apis-enterprise-adminManager.md b/zh-cn/application-dev/reference/apis/js-apis-enterprise-adminManager.md index 8a40383016240006d26233edf8b4ca95f485d221..bf67f0143711ccafe447658bf38d737c612a0147 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-enterprise-adminManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-enterprise-adminManager.md @@ -949,10 +949,10 @@ adminManager.unsubscribeManagedEvent(wantTemp, events).then(() => { **系统API**: 此接口为系统接口。 -| 名称 | 类型 | 可读 | 可写 | 说明 | -| ----------- | --------| ---- | ----- | ------------------------------- | -| name | string | 是 | 否 | 表示设备管理员应用所属企业的名称。 | -| description | string | 是 | 否 | 表示设备管理员应用所属企业的描述。 | +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------| ---- | ------------------------------- | +| name | string | 是 | 表示设备管理员应用所属企业的名称。 | +| description | string | 是 | 表示设备管理员应用所属企业的描述。 | ## AdminType diff --git a/zh-cn/application-dev/reference/apis/js-apis-enterprise-networkManager.md b/zh-cn/application-dev/reference/apis/js-apis-enterprise-networkManager.md index d78499bf78eb2bf3e493f8ebf65f8052a8cbda54..58aa91556894286b9ab1cf42b14779af7473c10e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-enterprise-networkManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-enterprise-networkManager.md @@ -487,4 +487,425 @@ networkManager.setNetworkInterfaceDisabled(wantTemp, 'eth0', true).then(() => { }).catch((err) => { console.error(`Failed to set network interface disabled. Code: ${err.code}, message: ${err.message}`); }); -``` \ No newline at end of file +``` + +## networkManager.addIptablesFilterRule + +addIptablesFilterRule(admin: Want, filterRule: AddFilterRule, callback: AsyncCallback\): void + +指定设备管理员应用添加网络包过滤规则,使用callback形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | +| filterRule | [AddFilterRule](#addfilterrule) | 是 | 添加网络包过滤规则。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当接口调用成功,err为null,否则err为错误对象。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let filterRule = { + "ruleNo": 1, + "srcAddr": "192.168.1.1-192.188.22.66", + "destAddr": "10.1.1.1", + "srcPort": "8080", + "destPort": "8080", + "uid": "9696", + "method": networkManager.AddMethod.APPEND, + "direction": networkManager.Direction.OUTPUT, + "action": networkManager.Action.DENY, + "protocol": networkManager.Protocol.UDP, +} + +networkManager.addIptablesFilterRule(wantTemp, filterRule, (err) => { + if (err) { + console.error(`Failed to set iptables filter rule. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in setting iptables filter rule`); +}); +``` + +## networkManager.addIptablesFilterRule + +addIptablesFilterRule(admin: Want, filterRule: AddFilterRule): Promise\ + +指定设备管理员应用添加网络包过滤规则,使用Promise形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | +| filterRule | [AddFilterRule](#addfilterrule) | 是 | 添加网络包过滤规则。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。当添加网络包过滤规则失败时抛出错误对象。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let filterRule = { + "ruleNo": 1, + "srcAddr": "192.168.1.1-192.188.22.66", + "destAddr": "10.1.1.1", + "srcPort": "8080", + "destPort": "8080", + "uid": "9696", + "method": networkManager.AddMethod.APPEND, + "direction": networkManager.Direction.OUTPUT, + "action": networkManager.Action.DENY, + "protocol": networkManager.Protocol.UDP, +} + +networkManager.addIptablesFilterRule(wantTemp, filterRule).then(() => { + console.info(`Succeeded in setting iptables filter rule`); +}).catch((err) => { + console.error(`Failed to set iptables filter rule. Code: ${err.code}, message: ${err.message}`); +}); +``` + +## networkManager.removeIptablesFilterRule + +removeIptablesFilterRule(admin: Want, filterRule: RemoveFilterRule, callback: AsyncCallback\): void + +指定设备管理员应用移除网络包过滤规则,使用callback形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | +| filterRule | [RemoveFilterRule](#removefilterrule) | 是 | 移除网络包过滤规则。 | +| callback | AsyncCallback<void> | 是 | 回调函数。当接口调用成功,err为null,否则err为错误对象。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let filterRule = { + "srcAddr": "192.168.1.1-192.188.22.66", + "destAddr": "10.1.1.1", + "srcPort": "8080", + "destPort": "8080", + "uid": "9696", + "direction": networkManager.Direction.OUTPUT, + "action": networkManager.Action.DENY, + "protocol": networkManager.Protocol.UDP, +} + +networkManager.removeIptablesFilterRule(wantTemp, filterRule, (err) => { + if (err) { + console.error(`Failed to remove iptables filter rule. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in removing iptables filter rule`); +}); +``` + +## networkManager.removeIptablesFilterRule + +removeIptablesFilterRule(admin: Want, filterRule: RemoveFilterRule): Promise\ + +指定设备管理员应用移除网络包过滤规则,使用Promise形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | +| filterRule | [RemoveFilterRule](#removefilterrule) | 是 | 移除网络包过滤规则。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------- | ------------------------- | +| Promise<void> | 无返回结果的Promise对象。当移除网络包过滤规则失败时抛出错误对象。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; +let filterRule = { + "srcAddr": "192.168.1.1-192.188.22.66", + "destAddr": "10.1.1.1", + "srcPort": "8080", + "destPort": "8080", + "uid": "9696", + "direction": networkManager.Direction.OUTPUT, + "action": networkManager.Action.DENY, + "protocol": networkManager.Protocol.UDP, +} + +networkManager.removeIptablesFilterRule(wantTemp, filterRule).then(() => { + console.info(`Succeeded in removing iptables filter rule`); +}).catch((err) => { + console.error(`Failed to remove iptables filter rule. Code: ${err.code}, message: ${err.message}`); +}); +``` + +## networkManager.listIptablesFilterRules + +listIptablesFilterRules(admin: Want, callback: AsyncCallback\): void + +指定设备管理员应用获取网络包过滤规则,使用callback形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | +| callback | AsyncCallback<string> | 是 | 回调函数。当接口调用成功,err为null,否则err为错误对象。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; + +networkManager.listIptablesFilterRules(wantTemp, (err, result) => { + if (err) { + console.error(`Failed to get iptables filter rule. Code: ${err.code}, message: ${err.message}`); + return; + } + console.info(`Succeeded in getting iptables filter rule, result : ${result}`); +}); +``` + +## networkManager.listIptablesFilterRules + +listIptablesFilterRules(admin: Want): Promise\ + +指定设备管理员应用获取网络包过滤规则,使用Promise形式返回。 + +**需要权限:** ohos.permission.ENTERPRISE_MANAGE_NETWORK + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| ----- | ----------------------------------- | ---- | ------- | +| admin | [Want](js-apis-app-ability-want.md) | 是 | 设备管理员应用。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------- | ------------------------- | +| Promise<string> | Promise对象,返回网络包过滤规则。 | + +**错误码**: + +以下的错误码的详细介绍请参见[企业设备管理错误码](../errorcodes/errorcode-enterpriseDeviceManager.md) + +| 错误码ID | 错误信息 | +| ------- | ---------------------------------------------------------------------------- | +| 9200001 | the application is not an administrator of the device. | +| 9200002 | the administrator application does not have permission to manage the device. | + +**示例:** + +```js +let wantTemp = { + bundleName: 'com.example.myapplication', + abilityName: 'EntryAbility', +}; + +networkManager.listIptablesFilterRules(wantTemp).then((result) => { + console.info(`Succeeded in getting iptables filter rule, result: ${result}`); +}).catch((err) => { + console.error(`Failed to remove iptables filter rule. Code: ${err.code}, message: ${err.message}`); +}); +``` + +## AddFilterRule + +添加网络包过滤规则 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------| ---- | ------------------------------- | +| ruleNo | number | 否 | 规则序号。 | +| srcAddr | string | 否 | ip源地址。 | +| destAddr | string | 否 | ip目标地址。 | +| srcPort | string | 否 | ip源端口。 | +| destPort | string | 否 | ip目标端口。 | +| uid | string | 否 | 应用uid。 | +| method | [AddMethod](#addmethod) | 是 | 添加策略。 | +| direction | [Direction](#direction) | 是 | 规则链。 | +| action | [Action](#action) | 是 | 接收或者丢弃数据包。 | +| protocol | [Protocol](#protocol) | 否 | 网络协议。 | + +## RemoveFilterRule + +移除网络包过滤规则 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 类型 | 必填 | 说明 | +| ----------- | --------| ---- | ------------------------------- | +| srcAddr | string | 否 | ip源地址。 | +| destAddr | string | 否 | ip目标地址。 | +| srcPort | string | 否 | ip源端口。 | +| destPort | string | 否 | ip目标端口。 | +| uid | string | 否 | 应用uid。 | +| direction | [Direction](#direction) | 是 | 规则链。 | +| action | [Action](#action) | 否 | 接收或者丢弃数据包。 | +| protocol | [Protocol](#protocol) | 否 | 网络协议。 | + +## AddMethod + +添加网络包方法。 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| APPEND | 0 | 追加。 | +| INSERT | 1 | 插入。 | + +## Direction + +规则链。 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| INPUT | 0 | 输入链。 | +| OUTPUT | 1 | 输出链。 | + +## Action + +数据包的行为。 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| ALLOW | 0 | 接收数据包。 | +| DENY | 1 | 丢弃数据包。 | + +## Protocol + +网络协议。 + +**系统能力:** SystemCapability.Customization.EnterpriseDeviceManager + +**系统API**: 此接口为系统接口。 + +| 名称 | 值 | 说明 | +| -------- | -------- | -------- | +| ALL | 0 | 全部网络协议。 | +| TCP | 1 | 网络协议TCP。 | +| UDP | 2 | 网络协议UDP。 | +| ICMP | 3 | 网络协议ICMP。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-font.md b/zh-cn/application-dev/reference/apis/js-apis-font.md index 13e2c49b00169f956699b2e153c128391ebc5619..0cd35ce7ca5352a1eb4affb0a5d9a58c33406976 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-font.md +++ b/zh-cn/application-dev/reference/apis/js-apis-font.md @@ -36,8 +36,8 @@ registerFont(options: FontOptions): void | 名称 | 类型 | 必填 | 说明 | | ---------- | ------ | ---- | ------------ | -| familyName | string | 是 | 设置注册的字体名称。 | -| familySrc | string | 是 | 设置注册字体文件的路径。 | +| familyName | string\| [Resource](../arkui-ts/ts-types.md#resource)10+ | 是 | 设置注册的字体名称。 | +| familySrc | string\| [Resource](../arkui-ts/ts-types.md#resource)10+ | 是 | 设置注册字体文件的路径。 | **示例:** @@ -51,10 +51,23 @@ struct FontExample { @State message: string = '你好,世界' aboutToAppear() { + // familyName和familySrc都支持string font.registerFont({ familyName: 'medium', familySrc: '/font/medium.ttf' }) + + // familyName和familySrc都支持系统Resource + font.registerFont({ + familyName: $r('app.string.mediumFamilyName'), + familySrc: $r('app.string.mediumFamilySrc') + }) + + // familySrc支持RawFile + font.registerFont({ + familyName: 'mediumRawFile', + familySrc: $rawfile('font/medium.ttf') + }) } build() { @@ -62,7 +75,7 @@ struct FontExample { Text(this.message) .align(Alignment.Center) .fontSize(20) - .fontFamily('medium') // medium:注册自定义字体的名字 + .fontFamily('medium') // medium:注册自定义字体的名字($r('app.string.mediumFamilyName')、'mediumRawFile'等已注册字体也能正常使用) .height('100%') }.width('100%') } diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md index d5d3792be77922e70a687ea91091423ec7b74e92..5708145672bc59d6d1a93c5c79de61b71e0d136b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-abilityResult.md @@ -12,6 +12,8 @@ import ability from '@ohos.ability.ability'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase | 名称 | 可读 | 可写 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md index 890bcd1d48ad6e678f47c601b6b268c688f5c092..81499edbf280f22ad979f9355317559bb5394867 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-connectOptions.md @@ -12,6 +12,8 @@ import common from '@ohos.app.ability.common'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 参数名 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md index 542a1a2f1bdeb58d17ab63e2f5a09bf2bdad341f..051953a537866d72ba86715e182b4be864e30d13 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityOperation.md @@ -13,6 +13,8 @@ import ability from '@ohos.ability.ability'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel | 名称 | 类型 | 必填| 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md index 943a8bd636ce9a1bc71707a261163e56b8faed6d..a4f9f141f628816aa45dac99f0c0ed7b951a43ef 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-dataAbilityResult.md @@ -13,6 +13,8 @@ import ability from '@ohos.ability.ability'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md index a119fe766061daf40bdf0f9e1daed2c8f67ad42d..3dcf2ddfbd08a06bfa89590c2ba6bf8f0774eab8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-startAbilityParameter.md @@ -13,6 +13,8 @@ import ability from '@ohos.ability.ability'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-want.md b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-want.md index 97f8b12c1060d0a2ac1983c43e562666d2866fc2..5fc5be2faf9a75b3e4f5773982fd7c67d09f5900 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-ability-want.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-ability-want.md @@ -12,6 +12,8 @@ Want是对象间信息传递的载体, 可以用于应用组件间的信息传 import Want from '@ohos.app.ability.Want'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md index d08a4d237ec97b5a76bc22a1fa11a206720871ad..2a8e062143317e3ebb9a77f4bf2b248417151d8c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-app-appVersionInfo.md @@ -12,6 +12,8 @@ import featureAbility from '@ohos.ability.featureAbility'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-app-processInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-app-processInfo.md index bf576fce0b4b592a0a3b4c847e00310c625deecb..187f7206ad8ec7afe5c3c7f5cc89c132e1e86d58 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-app-processInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-app-processInfo.md @@ -12,6 +12,8 @@ import featureAbility from '@ohos.ability.featureAbility'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md index 6f05c3a6175193585f19e1a10c039bd0ccac38e8..960feb5beac10ddfd2f5161b666ad47750881282 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityDelegator.md @@ -14,7 +14,7 @@ import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry ## 使用说明 -通过AbilityDelegatorRegistry中[getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator)方法获取。 +通过AbilityDelegatorRegistry中[getAbilityDelegator](js-apis-app-ability-abilityDelegatorRegistry.md#abilitydelegatorregistrygetabilitydelegator)方法获取。此接口只能在测试环境下使用。 ```ts import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md index a6008172ee8b41cba3539db17fec35f043fc3f5b..4ba721cc2e27ccb0bc6acd6392e16fc7eadd819b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStageMonitor.md @@ -6,6 +6,8 @@ > > 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md index 0b5a78558c235ed70e7055da1afe081f96f8bae1..99e7167bf66f965b2f852a16bdc4e054ca151e20 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-abilityStateData.md @@ -12,6 +12,8 @@ import appManager from '@ohos.application.appManager'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-baseContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-baseContext.md index b0873a6584d298daf7a18c429d2e2fadb8e10466..00819c66f1af6650a0cc3546d7209017c17d5e81 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-baseContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-baseContext.md @@ -12,6 +12,8 @@ BaseContext抽象类用于表示继承的子类Context是Stage模型还是FA模 import common from '@ohos.app.ability.common'; ``` +## 属性 + **系统能力**:SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-continuableInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-continuableInfo.md index 0e87d5c15627938449252f67e1a7e10617ca57dc..9ac8782c1d4bdf62bd834a5f9ebfb348accb556e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-continuableInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-continuableInfo.md @@ -13,6 +13,8 @@ import distributedMissionManager from '@ohos.distributedMissionManager'; ``` +## 属性 + **系统能力**:SystemCapability.Ability.AbilityRuntime.Mission | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md index 7caece5795a344dbd331aee89aeef64dd6040ec3..3be9c897b9a8656b3896c8ab1fadf56a106b6883 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-continueDeviceInfo.md @@ -6,6 +6,8 @@ > > 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +## 属性 + **系统能力**:SystemCapability.Ability.AbilityRuntime.Mission | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionInfo.md index 62b3c93e69f80cd84f5a40061049320682c05e71..862f497eae6e40ea6b10259252304c00cba00c81 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionInfo.md @@ -12,6 +12,8 @@ import missionManager from '@ohos.app.ability.missionManager'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Mission **系统API**: 此接口为系统接口,三方应用不支持调用。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionListener.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionListener.md index a8bef951f6836f13cec6bb8013469f4ffe0a3913..757c6029a084b70efd438f7cd921aab0864b6a9c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionListener.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionListener.md @@ -12,6 +12,8 @@ import missionManager from '@ohos.app.ability.missionManager'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Mission | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md index e4260dce7eadc7cfcaaf9a0d358e0fbca256bd2b..39523a3d373ad9adfa860cf4f5e4fdc37c6e5454 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-missionSnapshot.md @@ -13,6 +13,8 @@ import missionManager from '@ohos.app.ability.missionManager'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Mission | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-processData.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-processData.md index bfc8f25f899b234f767e25f2481689741294633c..2c8b741d66009227d6bb08bbcd5193386ef61ca3 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-processData.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-processData.md @@ -12,6 +12,8 @@ import appManager from '@ohos.application.appManager'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core **系统API**:该接口为系统接口,三方应用不支持调用。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md index e94eaf768ac911fe9f507f1a789ec27287a2b261..8d5da70ca93589878900fc34080b521ed21f1bf4 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-shellCmdResult.md @@ -12,6 +12,8 @@ import AbilityDelegatorRegistry from '@ohos.app.ability.abilityDelegatorRegistry'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 可读 | 可写 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md index 070f9c77989c361aa72cccf780dab30c21da06f3..0c83afc034eb50662d56bf798a680c1e0d4d5480 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-triggerInfo.md @@ -12,6 +12,8 @@ import wantAgent from '@ohos.app.ability.wantAgent'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md b/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md index 84bc35b73d4f87def3c8e005a1fd7794ccc2a605..caed7c6e296e3d5b06c16c76e15837604255809a 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-wantAgent-wantAgentInfo.md @@ -12,6 +12,8 @@ import wantAgent from '@ohos.app.ability.wantAgent'; ``` +## 属性 + **系统能力**:以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 类型 | 必填 | 说明 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-installer.md b/zh-cn/application-dev/reference/apis/js-apis-installer.md index 195ee7dcdeaa8588ff65bbb7b6f44075e6a5ccba..9d87e39f6edf9365a3e63258f4e8b5d81ca51efa 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-installer.md +++ b/zh-cn/application-dev/reference/apis/js-apis-installer.md @@ -789,7 +789,7 @@ try { | 名称 | 类型 | 必填 | 说明 | | ------------------------------ | ------------------------------ | ------------------ | ------------------ | | userId | number | 否 | 指示用户id,默认值:调用方所在用户,取值范围:大于等于0,可使用[queryOsAccountLocalIdFromProcess](js-apis-osAccount.md#getOsAccountLocalId)获取当前进程所在用户。 | -| installFlag | number | 否 | 指示安装标志,枚举值:0:应用初次安装,1:应用覆盖安装,默认值为应用初次安装 | +| installFlag | number | 否 | 指示安装标志,枚举值:0x00:应用初次安装,0x01:应用覆盖安装,0x10:应用免安装,默认值为应用初次安装。 | | isKeepData | boolean | 否 | 卸载时是否保留数据目录,默认值为false。 | | hashParams | Array<[HashParam](#hashparam)> | 否 | 哈希值参数,默认值为空。 | | crowdtestDeadline| number | 否 | 众测活动的截止日期,默认值为-1,表示无截止日期约束。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md b/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md index 8a018b9032da3414e2a2c9c614def2b31c34def9..6c181358df81b5d44dc7b123c9bea33d62f3865c 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md +++ b/zh-cn/application-dev/reference/apis/js-apis-medialibrary.md @@ -82,6 +82,9 @@ getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileRe 获取文件资源,使用callback方式返回异步结果。 +> **说明:** +> 在API version 10上,摒弃了物理目录作为相册的设计,采用了逻辑相册的设计,一个相册中可以添加多个文件,一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容,无法作为MediaFetchOptions的参数在getFileAssets接口中使用。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -150,6 +153,9 @@ getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> 获取文件资源,使用Promise方式返回结果。 +> **说明:** +> 在API version 10上,摒弃了物理目录作为相册的设计,采用了逻辑相册的设计,一个相册中可以添加多个文件,一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容,无法作为MediaFetchOptions的参数在getFileAssets接口中使用。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -265,6 +271,9 @@ createAsset(mediaType: MediaType, displayName: string, relativePath: string, cal 创建媒体资源,使用callback方式返回结果。 +> **说明:** +> 由于API version 10的SDK上relativePath和相册没有关联关系,文件创建成功后,relativePath的最后一级目录不会作为相册呈现。变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -302,6 +311,9 @@ createAsset(mediaType: MediaType, displayName: string, relativePath: string): Pr 创建媒体资源,使用Promise方式返回结果。 +> **说明:** +> 由于API version 10的SDK上relativePath和相册没有关联关系,文件创建成功后,relativePath的最后一级目录不会作为相册呈现。变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -502,6 +514,9 @@ getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album& 获取相册列表,使用callback 方式返回结果。 +> **说明:** +> 由于API version 10的SDK上relativePath和相册没有关联关系,在使用getAlbums时不支持relativePath作为查询条件,当前仅支持“Camera”和“ScreenShots”两类相册,变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -517,10 +532,9 @@ getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album& ```js async function example() { - // 获取相册需要先预置相册和资源,示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', - selectionArgs: ['新建相册1'], + selectionArgs: ['Camera'], }; media.getAlbums(AlbumNoArgsfetchOp, (error, albumList) => { if (albumList != undefined) { @@ -538,6 +552,9 @@ getAlbums(options: MediaFetchOptions): Promise<Array<Album>> 获取相册列表,使用 promise 方式返回结果。 +> **说明:** +> 由于API version 10的SDK上relativePath和相册没有关联关系,在使用getAlbums时不支持relativePath作为查询条件.当前仅支持“Camera”和“ScreenShots”两类相册,变更详情请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -558,10 +575,9 @@ getAlbums(options: MediaFetchOptions): Promise<Array<Album>> ```js async function example() { - // 获取相册需要先预置相册和资源,示例代码为预置的新建相册1。 let AlbumNoArgsfetchOp = { selections: mediaLibrary.FileKey.ALBUM_NAME + '= ?', - selectionArgs: ['新建相册1'], + selectionArgs: ['Camera'], }; media.getAlbums(AlbumNoArgsfetchOp).then((albumList) => { console.info('getAlbums successfully: ' + JSON.stringify(albumList)); @@ -1047,7 +1063,7 @@ async function example() { | displayName | string | 是 | 是 | 显示文件名,包含后缀名。 | | title | string | 是 | 是 | 文件标题。 | | relativePath8+ | string | 是 | 是 | 相对公共目录路径。 | -| parent8+ | number | 是 | 否 | 父目录id。 | +| parent8+ | number | 是 | 否 | 父目录id。由于API version 10的SDK上Asset可以存在多个相册,该属性不兼容。获取值始终为0。 | | size | number | 是 | 否 | 文件大小(单位:字节)。 | | dateAdded | number | 是 | 否 | 添加日期(添加文件时间到1970年1月1日的秒数值)。 | | dateModified | number | 是 | 否 | 修改日期(修改文件时间到1970年1月1日的秒数值,修改文件名不会改变此值,当文件内容发生修改时才会更新)。| @@ -1058,9 +1074,9 @@ async function example() { | height | number | 是 | 否 | 图片高度(单位:像素)。 | | orientation | number | 是 | 是 | 图片显示方向(顺时针旋转角度,如0,90,180 单位:度)。 | | duration8+ | number | 是 | 否 | 持续时间(单位:毫秒)。 | -| albumId | number | 是 | 否 | 文件所归属的相册编号。 | -| albumUri8+ | string | 是 | 否 | 文件所归属相册uri。 | -| albumName | string | 是 | 否 | 文件所归属相册名称。 | +| albumId | number | 是 | 否 | 文件所归属的相册编号。由于API version 10的SDK上Asset可以存在多个相册,该属性不兼容。获取值始终为0。 | +| albumUri8+ | string | 是 | 否 | 文件所归属相册uri。由于API version 10的SDK上Asset可以存在多个相册,该属性不兼容。获取值始终为空字符串。 | +| albumName | string | 是 | 否 | 文件所归属相册名称。由于API version 10的SDK上Asset可以存在多个相册,该属性不兼容。获取值始终为空字符串。 | ### isDirectory8+ @@ -1146,6 +1162,9 @@ commitModify(callback: AsyncCallback<void>): void 修改文件的元数据,使用callback方式返回异步结果。 +> **说明:** +> 由于API version 10的SDK上audio没有orientation属性,在使用commitModify接口时将无法对audio资源的orientation属性进行修改。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core @@ -1183,6 +1202,9 @@ commitModify(): Promise<void> 修改文件的元数据,使用promise方式返回异步结果。 +> **说明:** +> 由于API version 10的SDK上audio没有orientation属性,在使用commitModify接口时将无法对audio资源的orientation属性进行修改。请参考[changelogs-mediaLibrary.md](../../../release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md)。 + **需要权限**:ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA **系统能力**:SystemCapability.Multimedia.MediaLibrary.Core diff --git a/zh-cn/application-dev/reference/apis/js-apis-treemap.md b/zh-cn/application-dev/reference/apis/js-apis-treemap.md index b30d57cf7c47c0377aa5c7f8dfcedd89acd05bb4..439e6c1d006929a558b1becb2ff8591cf2161282 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-treemap.md +++ b/zh-cn/application-dev/reference/apis/js-apis-treemap.md @@ -4,7 +4,7 @@ TreeMap可用于存储具有关联关系的key-value键值对集合,存储元 TreeMap底层使用红黑树实现,可以利用二叉树特性快速查找键值对。key值有序存储,可以实现快速的插入和删除。 -TreeMap和[HashMap](js-apis-treemap.md)相比,HashMap依据键的hashCode存取数据,访问速度较快。而TreeMap是有序存取,效率较低。 +TreeMap和[HashMap](js-apis-hashmap.md)相比,HashMap依据键的hashCode存取数据,访问速度较快。而TreeMap是有序存取,效率较低。 **推荐使用场景:** 一般需要存储有序键值对的场景,可以使用TreeMap。 diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-drag-drop.md b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-drag-drop.md index 733e49cde195026da3d3ffb7c677c22dfac61704..2dfb94304f064bc0ea63f40063eed74dc2c2d9e2 100644 --- a/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-drag-drop.md +++ b/zh-cn/application-dev/reference/arkui-ts/ts-universal-events-drag-drop.md @@ -81,6 +81,8 @@ ### 示例1 ```ts +import UDMF from '@ohos.data.UDMF'; + @Observed class ClassA { public name: string @@ -105,11 +107,27 @@ class ClassA { struct DragExample { @State arr: ClassA[] = [new ClassA('A', true), new ClassA('B', true), new ClassA('C', true)] @State dragIndex: number = 0 + @State mTextNew: string = '' + @State mBool: boolean = false changeIndex(index1: number, index2: number) { // 交换数组位置 [this.arr[index1], this.arr[index2]] = [this.arr[index2], this.arr[index1]]; } + public getDataFromUDMFWithRetry(event: DragEvent) { + let records = event.getData().getRecords(); + if (records) { + let plainText = (records[0]) + this.mTextNew = plainText.textContent + this.mBool = false + return; + } + // 获取失败延时 1.5s 再次获取 + setTimeout(() => { + this.getDataFromUDMFWithRetry(event) + }, 1500) + } + build() { Column() { Row({ space: 15 }) { @@ -130,8 +148,7 @@ struct DragExample { } .listDirection(Axis.Horizontal) .onDrop((event: DragEvent, extraParams: string) => { // 绑定此事件的组件可作为拖拽释放目标,当在本组件范围内停止拖拽行为时,触发回调。 - let jsonString = JSON.parse(extraParams); - this.changeIndex(this.dragIndex, jsonString.insertIndex) + this.getDataFromUDMFWithRetry(event); }) }.padding({ top: 10, bottom: 10 }).margin(10) @@ -187,6 +204,8 @@ struct Child { ```ts // xxx.ets +import UDMF from '@ohos.data.UDMF'; + @Extend(Text) function textStyle () { .width('25%') .height(35) @@ -201,6 +220,8 @@ struct DragExample { @State numbers: string[] = ['one', 'two', 'three', 'four', 'five', 'six'] @State text: string = '' @State bool: boolean = true + @State mBool: boolean = false + @State mTextNew: string = '' @State eventType: string = '' @State appleVisible: Visibility = Visibility.Visible @State orangeVisible: Visibility = Visibility.Visible @@ -222,6 +243,20 @@ struct DragExample { } } + public getDataFromUDMFWithRetry(event: DragEvent) { + let records = event.getData().getRecords() + if (records) { + let plainText = (records[0]) + this.mTextNew = plainText.textContent + this.mBool = false + return; + } + // 获取失败延时 1.5s 再次获取 + setTimeout(() => { + this.getDataFromUDMFWithRetry(event) + }, 1500) + } + build() { Column() { Text('There are three Text elements here') @@ -298,6 +333,7 @@ struct DragExample { this.bool = false } this.fruitVisible[this.idx] = Visibility.None + this.getDataFromUDMFWithRetry(event); }) }.width('100%').height('100%').padding({ top: 20 }).margin({ top: 20 }) } diff --git a/zh-cn/application-dev/reference/native-apis/_video_encoder.md b/zh-cn/application-dev/reference/native-apis/_video_encoder.md index 8d64bccf8dd94328800a4dcc968cb46828ba43ca..afa80160619f0fdfb1803378c529953044ef8c01 100644 --- a/zh-cn/application-dev/reference/native-apis/_video_encoder.md +++ b/zh-cn/application-dev/reference/native-apis/_video_encoder.md @@ -33,7 +33,7 @@ VideoEncoder模块提供用于视频编码功能的函数。 | 名称 | 描述 | | -------- | -------- | -| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) { **CBR** = 0, **VBR** = 1, **CQ** = 2 } | 视频编码器的比特率模式。 | +| [OH_VideoEncodeBitrateMode](#oh_videoencodebitratemode) {
    **CBR** = 0,
    **VBR** = 1,
    **CQ** = 2
} | 视频编码器的比特率模式。 | ### 函数 diff --git a/zh-cn/application-dev/security/permission-list.md b/zh-cn/application-dev/security/permission-list.md index 4feece1f00c36b79e525bb4f61b4e36f11b57ae5..73f0d0b914f7e0ac1f66bbb6a7edc2ad4d0dcdd0 100644 --- a/zh-cn/application-dev/security/permission-list.md +++ b/zh-cn/application-dev/security/permission-list.md @@ -2158,6 +2158,16 @@ **ACL使能**:TRUE +## ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO + +允许应用采集语音下行音频。 + +**权限级别**:system_basic + +**授权方式**:system_grant + +**ACL使能**:TRUE + ## ohos.permission.MANAGE_INTELLIGENT_VOICE 允许应用访问智能语音服务接口。 diff --git a/zh-cn/device-dev/device-test/smartperf-host.md b/zh-cn/device-dev/device-test/smartperf-host.md index 0c02f2bb41a6ce9b96f77c79a6584ec669a813ee..847db0436f4ee0e8057f6dee216acdc6dba6fcfe 100644 --- a/zh-cn/device-dev/device-test/smartperf-host.md +++ b/zh-cn/device-dev/device-test/smartperf-host.md @@ -3,6 +3,7 @@ Smartperf-Host是一款深入挖掘数据、细粒度地展示数据的性能功耗调优工具,旨在为开发者提供一套性能调优平台,支持对CPU调度、频点、进程线程时间片、堆内存、帧率等数据进行采集和展示,展示方式为泳道图,支持GUI(图形用户界面)操作进行详细数据分析。 ## 架构图 ![系统架构图](figures/smartperf_frame.png) + 该组件整体分为设备端和PC端两部分,设备端和PC端基于gRPC(Remote Procedure Call)通信框架进行数据交互。 设备端内部分为应用程序内嵌组件、命令行工具、性能调优服务、性能调优插件集合、部分系统工具及部分系统内核等模块。设备端提供了插件扩展能力,对外提供了插件接口,基于该扩展能力可以按需定义自己的能力,并集成到框架中来,目前基于插件能力已经完成了native内存插件、trace插件等,详细介绍见[性能调优组件](https://gitee.com/openharmony/developtools_profiler)。 diff --git a/zh-cn/device-dev/device-test/xdevice.md b/zh-cn/device-dev/device-test/xdevice.md index 8f08fccebc1cef832feff16c0838992a91ef3791..9bdd6ffb7b123c4064103eddf7120ef21343d25b 100644 --- a/zh-cn/device-dev/device-test/xdevice.md +++ b/zh-cn/device-dev/device-test/xdevice.md @@ -46,7 +46,7 @@ environment环境相关配置,详解介绍如下。 - + @@ -63,7 +63,7 @@ environment环境相关配置,详解介绍如下。 - + @@ -75,7 +75,7 @@ environment环境相关配置,详解介绍如下。 - + @@ -383,7 +383,7 @@ run指令基本使用方法如下。 若AT命令串口和日志输出串口共用,可以配置为相同,即user_config中的type为cmd的com口与type为deploy的com口可配置为一样的端口,如COM18。 - ![L0-1](figures/L0-1.PNG) + ![轻量系统设备-1](figures/L0-1.PNG) user_config.xml的修改示例如下。 @@ -476,7 +476,7 @@ run指令基本使用方法如下。 type为cmd的com口对应板子上的AT命令串口,用于对设备发送指令,示例中配置为ChA(COM20)串口号。 - ![L0-1](figures/L0-1.PNG) + ![小型系统设备-1](figures/L0-1.PNG) ipcamera设备有两种连接方式,一种是本地串口连接,一种是通过局域网ip连接。 diff --git a/zh-cn/device-dev/driver/driver-peripherals-light-des.md b/zh-cn/device-dev/driver/driver-peripherals-light-des.md index 6b36351d818e284a5117c92f8d083cd4add44cc6..4e95c7157d8ca181a09b3e1bf8268431129d5286 100644 --- a/zh-cn/device-dev/driver/driver-peripherals-light-des.md +++ b/zh-cn/device-dev/driver/driver-peripherals-light-des.md @@ -32,7 +32,7 @@ Light驱动模型为上层Light硬件服务层提供稳定的灯控制能力接 ### 场景介绍 -灯设备的控制,在实际生活中比比皆是,例如短信通知时闪灯、手机电量不足时预警、充电时根据充电进度变换灯的颜色等等。这些动作的实现,都需要使用Light驱动模型提供的接口,动态配置点灯模式、配置灯闪烁效果、点灯、熄灯等。 +灯设备的控制,在实际生活中比比皆是,例如短信通知时闪灯、终端电量不足时预警、充电时根据充电进度变换灯的颜色等等。这些动作的实现,都需要使用Light驱动模型提供的接口,动态配置点灯模式、配置灯闪烁效果、点灯、熄灯等。 ### 接口说明 diff --git a/zh-cn/device-dev/guide/device-camera-visual-prepare.md b/zh-cn/device-dev/guide/device-camera-visual-prepare.md index d9dce9afe76703bc0554c5f75ae705f26e35e943..898fad0b389c6dbf28d04bda7c876d2b72b9ac3e 100644 --- a/zh-cn/device-dev/guide/device-camera-visual-prepare.md +++ b/zh-cn/device-dev/guide/device-camera-visual-prepare.md @@ -10,18 +10,15 @@ ## 创建项目 1. 通过如下两种方式,打开工程创建向导界面。 - - 如果当前未打开任何工程,可以在DevEco Studio的欢迎页,选择**Create HarmonyOS Project**开始创建一个新工程。 - - 如果已经打开了工程,可以在菜单栏选择**File \> New \> New Project**来创建一个新工程。 + - 如果当前未打开任何工程,可以在DevEco Studio的欢迎页,选择**Create Project**开始创建一个新工程。 + - 如果已经打开了工程,可以在菜单栏选择**File \> New \> Create Project**来创建一个新工程。 -2. 选择“Smart Vision”下的“Empty Feature Ability”模板。 +2. 选择“Application”下的“Empty Ability”模板,点击**Next**。 ![](figures/empty-feature-ability.png) -3. 点击**Next**,进入到工程配置阶段,需要根据向导配置工程的基本信息。 - - **Project Name**:工程的名称,可以自定义。 - - **Package Name**:软件包名称,默认情况下,应用ID也会使用该名称,应用发布时,应用ID需要唯一。 - - **Save Location**:工程文件本地存储路径,存储路径中不能包含中文字符和空格。 - - **Compatible API Version**:兼容的SDK版本。 - -4. 点击**Finish**,工具会自动生成示例代码和相关资源,等待工程创建完成。 - +3. 填写工程相关信息,保持默认值即可,单击**Finish**。 + + 关于各个参数的详细介绍,请参考[《DevEco Studio使用指南》](https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/create_new_project-0000001053342414-V3)。 + + 工程创建完成后,DevEco Studio会自动进行工程的同步。 diff --git a/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md b/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md index df848c5943caffd43d9e490dcbd5857383d2c2e2..ec89ec6b80c47e44ce527d4e76d47296214b53e8 100644 --- a/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md +++ b/zh-cn/device-dev/kernel/kernel-mini-memory-exception.md @@ -23,13 +23,14 @@ OpenHarmony LiteOS-M提供异常接管调测手段,帮助开发者定位分析 ## 接口说明 -OpenHarmony LiteOS-M内核的回溯栈模块提供下面几种功能,接口详细信息可以查看API参考。 +OpenHarmony LiteOS-M内核的回溯栈模块提供以下接口,接口详细信息可以查看API参考。 **表1** 回溯栈模块接口 -| 功能分类 | 接口名 | +| 接口名 | 功能 | | -------- | -------- | -| 回溯栈接口 | LOS_BackTrace:打印调用处的函数调用栈关系。
LOS_RecordLR:在无法打印的场景,用该接口获取调用处的函数调用栈关系。 | +| LOS_BackTrace | 打印调用处的函数调用栈关系。| +| LOS_RecordLR | 在无法打印的场景,用该接口获取调用处的函数调用栈关系。| ## 使用指导 @@ -40,16 +41,19 @@ OpenHarmony LiteOS-M内核的回溯栈模块提供下面几种功能,接口详 开启异常调测的典型流程如下: 1. 配置异常接管相关宏。 - 需要在target_config.h头文件中修改配置: - | 配置项 | 含义 | 设置值 | + + 需要在target_config.h头文件中修改配置: + + | 配置项 | 含义 | 设置值 | | -------- | -------- | -------- | | LOSCFG_BACKTRACE_DEPTH | 函数调用栈深度,默认15层 | 15 | | LOSCFG_BACKTRACE_TYPE | 回溯栈类型:
0:表示关闭该功能;
1:表示支持Cortex-m系列硬件的函数调用栈解析;
2:表示用于Risc-v系列硬件的函数调用栈解析; | 根据工具链类型设置1或2 | -1. 使用示例中有问题的代码,编译、运行工程,在串口终端中查看异常信息输出。示例代码模拟异常代码,实际产品开发时使用异常调测机制定位异常问题。 - 本示例演示异常输出,包含1个任务,该任务入口函数模拟若干函数调用,最终调用一个模拟异常的函数。代码实现如下: +2. 使用示例中有问题的代码,编译、运行工程,在串口终端中查看异常信息输出。示例代码模拟异常代码,实际产品开发时使用异常调测机制定位异常问题。 + + 本示例演示异常输出,包含1个任务,该任务入口函数模拟若干函数调用,最终调用一个模拟异常的函数。代码实现如下: - 本演示代码在 ./kernel/liteos_m/testsuites/src/osTest.c 中编译验证,在TestTaskEntry中调用验证入口函数ExampleExcEntry。 + 本演示代码在`./kernel/liteos_m/testsuites/src/osTest.c`中编译验证,在TestTaskEntry中调用验证入口函数ExampleExcEntry。 ``` #include @@ -210,17 +214,17 @@ OpenHarmony LiteOS-M内核的回溯栈模块提供下面几种功能,接口详 异常接管一般的定位步骤如下: -0. 确认编译时关掉优化选项,否则下述的描述内容可能被优化掉。 +1. 确认编译时关掉优化选项,否则下述的描述内容可能被优化掉。 -1. 打开编译后生成的镜像反汇编(asm)文件。如果默认没有生成,可以使用objdump工具生成,命令为: +2. 打开编译后生成的镜像反汇编(asm)文件。如果默认没有生成,可以使用objdump工具生成,命令为: ``` - arm-none-eabi-objdump -S -l XXX.elf + arm-none-eabi-objdump -S -l XXX.elf ``` -1. 搜索PC指针(指向当前正在执行的指令)在asm中的位置,找到发生异常的函数。 - PC地址指向发生异常时程序正在执行的指令。在当前执行的二进制文件对应的asm文件中,查找PC值0x2101c61a,找到当前CPU正在执行的指令行,反汇编如下所示: +3. 搜索PC指针(指向当前正在执行的指令)在asm中的位置,找到发生异常的函数。 + PC地址指向发生异常时程序正在执行的指令。在当前执行的二进制文件对应的asm文件中,查找PC值0x2101c61a,找到当前CPU正在执行的指令行,反汇编如下所示: ``` 2101c60c : @@ -243,14 +247,14 @@ OpenHarmony LiteOS-M内核的回溯栈模块提供下面几种功能,接口详 2101c630: 21025f90 .word 0x21025f90 ``` -1. 可以看到: - 1. 异常时CPU正在执行的指令是ldr r3, [r3, #0],其中r3取值为0xffffffff,导致发生非法地址异常。 +4. 可以看到: + 1. 异常时CPU正在执行的指令是ldr r3, [r3, #0],其中r3取值为0xffffffff,导致发生非法地址异常。 2. 异常发生在函数GetResultException0中。 -2. 根据LR值查找异常函数的父函数。 +5. 根据LR值查找异常函数的父函数。 + 包含LR值0x2101c64d的反汇编如下所示: - ``` 2101c634 : 2101c634: b580 push {r7, lr} @@ -272,6 +276,6 @@ OpenHarmony LiteOS-M内核的回溯栈模块提供下面几种功能,接口详 2101c658: 21025fb0 .word 0x21025fb0 ``` -1. LR值2101c648上一行是bl 2101c60c ,此处调用了异常函数,调用异常函数的父函数为GetResultException1。 -2. 重复步骤3,解析异常信息中backtrace start至backtrace end之间的LR值,得到调用产生异常的函数调用栈关系,找到异常原因。 +7. 重复步骤3,解析异常信息中backtrace start至backtrace end之间的LR值,得到调用产生异常的函数调用栈关系,找到异常原因。 diff --git a/zh-cn/device-dev/kernel/kernel-overview.md b/zh-cn/device-dev/kernel/kernel-overview.md index 66b00c70b82c0d51e39776e120889629f0d3cadd..d2aad66886961b8ea2d268da4a9a0af270656fa5 100644 --- a/zh-cn/device-dev/kernel/kernel-overview.md +++ b/zh-cn/device-dev/kernel/kernel-overview.md @@ -27,7 +27,7 @@ - 负责本机操作系统和另外一个设备上操作系统通信的“网络”。 -OpenHarmony采用了多内核结构,支持Linux和LiteOS,开发者可按不同产品规格进行选择使用。linux和LiteOS均具备上述组成单元,只是实现方式有所不同。多个内核通过KAL(Kernel Abstraction Layer)模块,向上提供统一的标准接口。 +OpenHarmony采用了多内核结构,支持Linux和LiteOS,开发者可按不同产品规格进行选择使用。Linux和LiteOS均具备上述组成单元,只是实现方式有所不同。多个内核通过KAL(Kernel Abstraction Layer)模块,向上提供统一的标准接口。 内核子系统位于OpenHarmony下层。需要特别注意的是,由于OpenHarmony面向多种设备类型,这些设备有着不同的CPU能力,存储大小等。为了更好的适配这些不同的设备类型,内核子系统支持针对不同资源等级的设备选用适合的OS内核,内核抽象层(KAL,Kernel Abstract Layer)通过屏蔽内核间差异,对上层提供基础的内核能力。 diff --git a/zh-cn/device-dev/porting/porting-asr582x-combo-demo.md b/zh-cn/device-dev/porting/porting-asr582x-combo-demo.md index 94d215fb8b801cb89a358cede38fd47b101a9924..fcd91fc40a544a3d085c1df669a171bf9e22f3a4 100755 --- a/zh-cn/device-dev/porting/porting-asr582x-combo-demo.md +++ b/zh-cn/device-dev/porting/porting-asr582x-combo-demo.md @@ -693,9 +693,13 @@ dsoftbus组件的运行需至少预留80KB RAM。如资源不够,可对其它 在communication_dsoftbus仓中,加入了-fPIC编译选项,这样会让编译器产生与位置无关代码,并使用相对地址,但是在LiteOS-M核中使用的是静态库,不推荐使用。 建议开发者手动注释-fPIC编译选项,后续会推进OpenHarmony统一规划此编译选项的开关。修改方法是在如下的四个文件中,找到"-fPIC"选项,并全部注释: + `//foundation/communication/dsoftbus/core/common/BUILD.gn` + `//foundation/communication/dsoftbus/core/frame/BUILD.gn` + `//foundation/communication/dsoftbus/sdk/BUILD.gn` + `//foundation/communication/dsoftbus/components/nstackx_mini/nstackx_ctrl/BUILD.gn` 软总线的组网需要通过设备认证,在研发阶段,可以把认证跳过,先行调试组网以及传输能力,需将文件`//foundation/communication/dsoftbus/core/authentication/src/auth_manager.c`中的HandleReceiveDeviceId函数替换为如下实现: diff --git a/zh-cn/device-dev/porting/porting-smallchip-driver-plat.md b/zh-cn/device-dev/porting/porting-smallchip-driver-plat.md index 5ba5c7ed9d3ccf8b8482cee0319a6037546cfa25..a002077a26205777f0f8dd6702a0ae158b74b82f 100644 --- a/zh-cn/device-dev/porting/porting-smallchip-driver-plat.md +++ b/zh-cn/device-dev/porting/porting-smallchip-driver-plat.md @@ -1,13 +1,11 @@ # 平台驱动移植 -在这一步,我们会在源码目录//device/vendor_name/soc_name/drivers 目录下创建平台驱动,如果你要移植的SOC的厂商还没有创建仓库的话,请联系[sig_devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard_cn.md)创建。 +在这一步,我们会在源码目录`//device/vendor_name/soc_name/drivers`目录下创建平台驱动,如果你要移植的SOC的厂商还没有创建仓库的话,请联系[sig_devboard](https://gitee.com/openharmony/community/blob/master/sig/sig_devboard/sig_devboard_cn.md)创建。 建议的目录结构: - - ``` device ├── vendor_name @@ -33,17 +31,15 @@ device │ ├── board_name ``` - - -HDF为所有的平台驱动都创建了驱动模型,移植平台驱动的主要工作是向模型注入实例。 这些模型你可以在源码目录//drivers/framework/support/platform/include中找到定义。 +HDF为所有的平台驱动都创建了驱动模型,移植平台驱动的主要工作是向模型注入实例。 这些模型你可以在源码目录`//drivers/hdf_core/framework/support/platform/include`中找到定义。 本节我们会以GPIO为例,讲解如何移植平台驱动,移植过程包含以下步骤: 1. 创建GPIO驱动 - 在源码目录//device/vendor_name/soc_name/drivers/gpio中创建文件soc_name_gpio.c 内容模板如下: + 在源码目录`//device/vendor_name/soc_name/drivers/gpio`中创建文件`soc_name_gpio.c`。内容模板如下: ``` #include "gpio_core.h" @@ -92,7 +88,8 @@ HDF为所有的平台驱动都创建了驱动模型,移植平台驱动的主 ``` 2. 创建厂商驱动构建入口 - 如前所述device/vendor_name/drivers/lite.mk是厂商驱动的构建的入口。我们需要从这个入口开始,进行构建 + + 如前所述`device/vendor_name/drivers/lite.mk`是厂商驱动的构建的入口。我们需要从这个入口开始,进行构建。 ``` @@ -147,7 +144,8 @@ HDF为所有的平台驱动都创建了驱动模型,移植平台驱动的主 ``` 5. 配置产品加载驱动 - 产品的所有设备信息被定义在源码文件//vendor/vendor_name/product_name/config/device_info/device_info.hcs中。 + + 产品的所有设备信息被定义在源码文件`//vendor/vendor_name/product_name/config/device_info/device_info.hcs`中。 平台驱动请添加到platform的host中。 diff --git a/zh-cn/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md b/zh-cn/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md index 0f12d0219895c462dfabf80211a3d80d0f19e575..3738ab388e81d4ba8129afa5dee32522326ea865 100644 --- a/zh-cn/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md +++ b/zh-cn/device-dev/porting/porting-stm32mp15xx-on-smallsystem.md @@ -547,13 +547,13 @@ vendor `graphic`配置文件见 `//vendor/bearpi/bearpi_hm_micro/graphic_config/product_graphic_lite_config.h`。 -#### ACE开发框架子系统适配 +#### ArkUI开发框架子系统适配 -进行`ACE`开发框架子系统适配需要添加`ace_engine_lite`部件,直接在`config.json`配置即可。 +进行ArkUI开发框架子系统适配需要添加`ace_engine_lite`部件,直接在`config.json`配置即可。 ``` { - "subsystem": "ace", + "subsystem": "arkui", "components": [ { "component": "ace_engine_lite", diff --git a/zh-cn/device-dev/quick-start/quickstart-pkg-3516-burn.md b/zh-cn/device-dev/quick-start/quickstart-pkg-3516-burn.md index 130f18d0703c39bdd6e1bffbc26161d2f9c0faef..2d0b1f2620af9be878813bda7ce10d5b30a4d7d5 100644 --- a/zh-cn/device-dev/quick-start/quickstart-pkg-3516-burn.md +++ b/zh-cn/device-dev/quick-start/quickstart-pkg-3516-burn.md @@ -22,9 +22,7 @@ 1. 准备烧录相关文件。 1. 在客户端新建用于保存烧录文件的文件夹,例如“D:\liteos”或“D:\linux”。 2. 将烧录所需烧写配置文件和启动引导文件保存到新建的文件夹中。 - - 其L1_LiteOS烧写配置文件为L1_3516_liteos.xml,其启动引导文件为“[u-boot-hi3516dv300.bin](https://gitee.com/openharmony/device_board_hisilicon/tree/master/hispark_taurus/uboot/out/boot)”。 - 其中L1_3516_liteos.xml文件需要开发者自行准备,模板如下: - + - Hi3516DV300对应的LiteOS内核小型系统的启动引导文件为“[u-boot-hi3516dv300.bin](https://gitee.com/openharmony/device_board_hisilicon/tree/master/hispark_taurus/uboot/out/boot)”,烧写配置文件需要开发者自行准备(可自行命名,例如LS_3516_liteos.xml),模板如下: ``` @@ -35,9 +33,7 @@ ``` - - 其L1_Linux烧写配置文件为L1_3516_linux.xml,其启动引导文件为“[u-boot-hi3516dv300.bin](https://gitee.com/openharmony/device_board_hisilicon/tree/master/hispark_taurus/uboot/out/boot)”。 - 其中L1_3516_linux.xml文件需要开发者自行准备,模板如下: - + - Hi3516DV300对应的Linux内核小型系统的启动引导文件为“[u-boot-hi3516dv300.bin](https://gitee.com/openharmony/device_board_hisilicon/tree/master/hispark_taurus/uboot/out/boot)”,烧写配置文件需要开发者自行准备(可自行命名,例如LS_3516_linux.xml),模板如下 ``` @@ -51,17 +47,17 @@ ``` 3. 将编译完成的源码包下载至客户端并解压,将烧录相关文件拷贝至步骤1中新建的文件夹。 - 针对Hi3516开发板(轻量级系统使用LiteOS内核或Linux内核根据业务实际需要选择): + 针对Hi3516DV300开发板(系统使用LiteOS内核或Linux内核根据业务实际需要选择): - - 其L1_LiteOS烧写所需文件为:OHOS_Image.bin、rootfs_vfat.img、userfs_vfat.img - - 其L1_Linux烧写所需文件为:uImage_hi3516dv300_smp、rootfs_ext4.img、userfs_ext4.img、userdata_ext4.img + - LiteOS内核小型系统对应的烧写所需文件为:OHOS_Image.bin、rootfs_vfat.img、userfs_vfat.img + - Linux内核小型系统对应的烧写所需文件为:uImage_hi3516dv300_smp、rootfs_ext4.img、userfs_ext4.img、userdata_ext4.img 2. 使用HiTool烧录。 1. 打开HiTool。 2. 设置HiTool参数。 传输方式选择USB口,烧写方式选择烧写eMMC(单板的存储介质为eMMC)。 - 3. 单击浏览在步骤1创建的文件夹中选择烧写配置文件(例如L1_3516_linux.xml)。 + 3. 单击浏览在步骤1创建的文件夹中选择烧写配置文件(例如LS_3516_linux.xml)。 ![zh-cn_image_0000001249937195](figures/zh-cn_image_0000001249937195.png) 4. 单击烧写后,按住开发板上串口旁的按钮(Update键),并拔插USB线(上下电)。 @@ -77,7 +73,7 @@ 终端界面中出现“hisilicon \#”表示已连接开发板串口。 3. 在串口终端拷贝如下启动参数后,按回车完成配置。 - - 其L1_LiteOS对应的启动参数为: + - LiteOS内核小型系统对应的启动参数为: ``` setenv bootcmd "mmc read 0x0 0x80000000 0x800 0x4800;go 0x80000000"; @@ -85,7 +81,7 @@ saveenv sa;reset ``` - - 其L1_Linux对应的启动参数为: + - Linux内核小型系统对应的启动参数为: ``` setenv bootargs "mem=128M console=ttyAMA0,115200 root=/dev/mmcblk0p3 rw rootfstype=ext4 rootwait blkdevparts=mmcblk0:1M(boot),9M(kernel),50M(rootfs),50M(userfs),1024M(userdata)" diff --git a/zh-cn/device-dev/subsystems/subsys-application-framework-guide.md b/zh-cn/device-dev/subsystems/subsys-application-framework-guide.md index 94a70866aa4a6b1d91fe20925a3abc1e6101afbe..528f5558c1553e68f333161f7d65521dc8f46d7d 100644 --- a/zh-cn/device-dev/subsystems/subsys-application-framework-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-application-framework-guide.md @@ -111,11 +111,14 @@ } ``` -3. 实现Service相关的生命周期方法。Service也是一种Ability,Ability为服务提供了以下生命周期方法,用户可以重写这些方法来添加自己的处理。用户在重写的方法里,需要调用父类对应的方法。 - - OnStart() - 该方法在创建Service的时候调用,用于做一些Service初始化且耗时较短的工作,在Service的整个生命周期只会调用一次。 +3. 实现Service相关的生命周期方法。 - + Service也是一种Ability,Ability为服务提供了以下生命周期方法,用户可以重写这些方法来添加自己的处理。用户在重写的方法里,需要调用父类对应的方法。 + + - OnStart() + + 该方法在创建Service的时候调用,用于做一些Service初始化且耗时较短的工作,在Service的整个生命周期只会调用一次。 + ``` void MyServiceAbility::OnStart(const Want& want) { @@ -124,8 +127,8 @@ } ``` - OnConnect​() - 在组件和服务连接时调用,该方法返回SvcIdentity,组件可以通过它与服务交互。 - + + 在组件和服务连接时调用,该方法返回SvcIdentity,组件可以通过它与服务交互。 ``` const SvcIdentity *MyServiceAbility::OnConnect(const Want &want) @@ -135,14 +138,17 @@ } ``` - OnDisconnect​() - 在组件与绑定的Service断开连接时调用。 + + 在组件与绑定的Service断开连接时调用。 + - OnStop() - 在Service销毁时调用。Service应通过实现此方法来清理任何资源,如关闭线程、注册的侦听器等。 + + 在Service销毁时调用。Service应通过实现此方法来清理任何资源,如关闭线程、注册的侦听器等。 4. 重写消息处理方法。 - MsgHandle是Service用来处理客户端消息的方法。其中funcId是客户端传过来的消息类型,request是客户端传过来的序列化请求参数。如果用户在处理完成之后想要把结果传回去,需要把结果序列化后写入reply中。 - + MsgHandle是Service用来处理客户端消息的方法。其中funcId是客户端传过来的消息类型,request是客户端传过来的序列化请求参数。如果用户在处理完成之后想要把结果传回去,需要把结果序列化后写入reply中。 + ``` void ServiceAbility::MsgHandle(uint32_t funcId, IpcIo *request, IpcIo *reply) { @@ -157,6 +163,7 @@ ``` 5. 注册Service。 + Service也需要在应用清单文件config.json中进行注册,注册类型type需要设置为service。 @@ -173,8 +180,10 @@ ``` 6. 启动Service。 + - Ability为用户提供了StartAbility()方法来启动另外一个Ability,因为Service也是Ability的一种,开发者同样可以通过将Want传递给该方法来启动Service。 - 开发者可以通过Want的SetWantElement ()来设置目标服务信息。ElementName结构体的两个主要参数:第一个参数为包名称;第二个参数为目标Ability。 + + 开发者可以通过Want的SetWantElement ()来设置目标服务信息。ElementName结构体的两个主要参数:第一个参数为包名称;第二个参数为目标Ability。 ``` { @@ -191,10 +200,14 @@ StartAbility() 方法会立即执行,如果Service尚未运行,则系统首先会调用OnStart()。 - 停止Service。 - Service一旦创建就会一直保持在后台运行,开发者可以通过调用StopAbility()来停止Service。 + + Service一旦创建就会一直保持在后台运行,开发者可以通过调用StopAbility()来停止Service。 7. 连接Service。 - - 如果Service需要与Page Ability或其他应用组件中的Service进行交互,则应创建用于连接的Service。Service支持其他Ability通过ConnectAbility()与其进行连接,ConnectAbility()需要传入目标Service的Want,以及IAbilityConnection的实例来处理回调。IAbilityConnection提供了两个方法供用户实现,OnAbilityConnectDone()用来处理连接的回调,OnAbilityDisconnectDone()用来处理断开连接的回调。 + + - 如果Service需要与Page Ability或其他应用组件中的Service进行交互,则应创建用于连接的Service。 + + Service支持其他Ability通过ConnectAbility()与其进行连接,ConnectAbility()需要传入目标Service的Want,以及IAbilityConnection的实例来处理回调。IAbilityConnection提供了两个方法供用户实现,OnAbilityConnectDone()用来处理连接的回调,OnAbilityDisconnectDone()用来处理断开连接的回调。 ``` { @@ -264,12 +277,18 @@ 安装接口只能给内置的系统应用使用。根据应用的安装路径,可以在安装应用时进行选择: + - 将应用安装到系统默认的文件目录/storage/app/。 - 将应用安装到系统外挂的存储介质中,例如micro sdcard。 -这两种选择可以在创建InstallParam实例的时候指定,当InstallParam的成员变量installLocation为 INSTALL_LOCATION_INTERNAL_ONLY时,意味着应用将会被安装到/storage/app/目录下;当InstallParam的成员变量installLocation为INSTALL_LOCATION_PREFER_EXTERNAL时,意味着应用将被安装到存储介质,其安装目录是/sdcard/app/。由于安装应用的过程是异步的,所以需要使用类似信号量的机制来确保安装的回调可以被执行。 +这两种选择可以在创建InstallParam实例的时候指定, + +- 当InstallParam的成员变量installLocation为 INSTALL_LOCATION_INTERNAL_ONLY时,意味着应用将会被安装到/storage/app/目录下。 +- 当InstallParam的成员变量installLocation为INSTALL_LOCATION_PREFER_EXTERNAL时,意味着应用将被安装到存储介质,其安装目录是/sdcard/app/。 + +由于安装应用的过程是异步的,所以需要使用类似信号量的机制来确保安装的回调可以被执行。 安装应用的步骤如下(示例代码以安装到系统目录为例): @@ -384,8 +403,10 @@ 打包工具一般集成到开发工具或者IDE中,开发者一般不涉及直接使用该工具,下面的介绍开发者可以作为了解。打包工具的jar包在开源代码中的位置:developtools/packing_tool/jar。 + - 打包命令行参数 - **表2** 打包所需要的资源文件描述 + + **表2** 打包所需要的资源文件描述 | 命令参数 | 对应的资源文件 | 说明 | 是否可缺省 | | -------- | -------- | -------- | -------- | diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-deviceInfo.md b/zh-cn/device-dev/subsystems/subsys-boot-init-deviceInfo.md index 8fbaac350ee73750bc2dba8ed5f85336354f3166..5c57a90b23c64d46ec5cecd8565c0dc89efa15d0 100644 --- a/zh-cn/device-dev/subsystems/subsys-boot-init-deviceInfo.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-deviceInfo.md @@ -35,7 +35,7 @@ - 适配说明: - OHOS 固定值参数由OHOS系统填充,厂商不能也不需适配,目前这部分参数主要定义在/base/startup/init/services/etc/param/ohos_const/ohos.para文件中。 + OHOS 固定值参数由OHOS系统填充,厂商不能也不需适配,目前这部分参数主要定义在`/base/startup/init/services/etc/param/ohos_const/ohos.para`文件中。 ### 厂商固定值参数的适配: @@ -63,18 +63,18 @@ 由各产品根据自身情况在vendor目录下适配。 - (1)L2以RK3568为例,在/vendor/hihope/rk3568/etc/para/hardware_rk3568.para中适配,并安装到指定目录。 + - 标准系统以RK3568为例,在`/vendor/hihope/rk3568/etc/para/hardware_rk3568.para`中适配,并安装到指定目录。 - ``` - ohos_prebuilt_etc("para_for_chip_prod") { - source = "./para/hardware_rk3568.para" - install_images = [ chip_prod_base_dir ] - relative_install_dir = "para" - part_name = "product_rk3568" - } - ``` + ``` + ohos_prebuilt_etc("para_for_chip_prod") { + source = "./para/hardware_rk3568.para" + install_images = [ chip_prod_base_dir ] + relative_install_dir = "para" + part_name = "product_rk3568" + } + ``` - (2)L0与L1 在产品对应的 hals/utils/sys_param/vendor.para文件中配置。例如: + - 轻量系统与小型系统在产品对应的`hals/utils/sys_param/vendor.para`文件中配置。例如: ``` const.product.manufacturer=Talkweb @@ -97,62 +97,63 @@ ### 厂商动态参数的适配 -- 厂商动态值参数,目前有三种获取形式:cmdline 读取,编译宏定义,在BUILD.gn中定义。 - - 1、cmdline 中读取的值有:ohos.boot.hardware, ohos.boot.bootslots, ohos.boot.sn等,其中ohos.boot.sn的获取略有不同,具体如下: - - (1)L2 Serial从参数ohos.boot.sn读取,ohos.boot.sn 参数值的获取方式:首先从cmdline (由uboot生成)获取,如果获取到的是sn值则直接读取,若获取的是文件路径,则从文件中读取;当获取不到时从默认的Sn文件读取,默认文件为:/sys/block/mmcblk0/device/cid;/proc/bootdevice/cid。 - - (2)L0 和 L1的 Serial各产品在实现过程中可能有自己特殊的算法,因此我们支持在hals/utils/sys_param目录下hal_sys_param.c文件中通过HalGetSerial()接口自定算法来获取Serial。 - - 2、编译宏定义的形式获取参数,目前主要在L0 和 L1中用到,例如: - - ``` - defines = [ - "INCREMENTAL_VERSION=\"${ohos_version}\"", - "BUILD_TYPE=\"${ohos_build_type}\"", - "BUILD_USER=\"${ohos_build_user}\"", - "BUILD_TIME=\"${ohos_build_time}\"", - "BUILD_HOST=\"${ohos_build_host}\"", - "BUILD_ROOTHASH=\"${ohos_build_roothash}\"", - ] - ``` - - 3、在BUILD.gn中定义,可参考文件/base/startup/init/services/etc/BUILD.gn,例如: - - ``` - if (target_cpu == "arm64") { - extra_paras += [ "const.product.cpu.abilist=arm64-v8a" ] - } - if (build_variant == "user") { - extra_paras += [ - "const.secure=1", - "const.debuggable=0", - ] - } else if (build_variant == "root") { - extra_paras += [ - "const.secure=0", - "const.debuggable=1", - ] - } - if (device_type != "default") { - extra_paras += [ - "const.product.devicetype=${device_type}", - "const.build.characteristics=${device_type}", - ] - } - module_install_dir = "etc/param" - } - ``` +厂商动态值参数,目前有三种获取形式:cmdline读取,编译宏定义,在BUILD.gn中定义。 + +1. cmdline中读取的值有:ohos.boot.hardware、ohos.boot.bootslots、ohos.boot.sn等,其中ohos.boot.sn的获取略有不同,具体如下: + + - 标准系统的Serial从参数ohos.boot.sn读取。 + + ohos.boot.sn参数值的获取方式:首先从cmdline(由uboot生成)获取,如果获取到的是sn值则直接读取,若获取的是文件路径,则从文件中读取;当获取不到时从默认的Sn文件读取,默认文件为:`/sys/block/mmcblk0/device/cid;/proc/bootdevice/cid`。 + + - 轻量系统与小型系统的Serial各产品在实现过程中可能有自己特殊的算法,因此OpenHarmony支持在`hals/utils/sys_param`目录下hal_sys_param.c文件中通过HalGetSerial()接口自定算法来获取Serial。 + +2. 编译宏定义的形式获取参数,目前主要在轻量系统与小型系统中用到,例如: + + ``` + defines = [ + "INCREMENTAL_VERSION=\"${ohos_version}\"", + "BUILD_TYPE=\"${ohos_build_type}\"", + "BUILD_USER=\"${ohos_build_user}\"", + "BUILD_TIME=\"${ohos_build_time}\"", + "BUILD_HOST=\"${ohos_build_host}\"", + "BUILD_ROOTHASH=\"${ohos_build_roothash}\"", + ] + ``` +3. 在BUILD.gn中定义,可参考文件`/base/startup/init/services/etc/BUILD.gn`,例如: + + ``` + if (target_cpu == "arm64") { + extra_paras += [ "const.product.cpu.abilist=arm64-v8a" ] + } + if (build_variant == "user") { + extra_paras += [ + "const.secure=1", + "const.debuggable=0", + ] + } else if (build_variant == "root") { + extra_paras += [ + "const.secure=0", + "const.debuggable=1", + ] + } + if (device_type != "default") { + extra_paras += [ + "const.product.devicetype=${device_type}", + "const.build.characteristics=${device_type}", + ] + } + module_install_dir = "etc/param" + + ``` #### 特别说明: - (1) L1的产品需要在hals/utils/sys_param/BUILD.gn中添加vendor.para的编译,具体如下: +1. 小型系统的产品需要在`hals/utils/sys_param/BUILD.gn`中添加vendor.para的编译,具体如下: - ``` - copy("vendor.para") { - sources = [ "./vendor.para" ] - outputs = [ "$root_out_dir/vendor/etc/param/vendor.para" ] - } - ``` + ``` + copy("vendor.para") { + sources = [ "./vendor.para" ] + outputs = [ "$root_out_dir/vendor/etc/param/vendor.para" ] + } + ``` - (2) L0的由于没有文件系统,在编译时会把hal_sys_param.c和vendor.para文件转化为头文件,编译时直接编译到系统中。 \ No newline at end of file +2. 轻量系统的产品由于没有文件系统,在编译时会把hal_sys_param.c和vendor.para文件转化为头文件,编译时直接编译到系统中。 \ No newline at end of file diff --git a/zh-cn/device-dev/subsystems/subsys-boot-init-log.md b/zh-cn/device-dev/subsystems/subsys-boot-init-log.md index f7e67b7d31bee1e67f7957ca9182d6748528e7dc..91d8ef25150e0e98d6be31fe48723418aa72634f 100644 --- a/zh-cn/device-dev/subsystems/subsys-boot-init-log.md +++ b/zh-cn/device-dev/subsystems/subsys-boot-init-log.md @@ -5,15 +5,14 @@ - 基于日志可以定位故障问题,可以查看各子系统启动时长,命令执行时长等。 - 可以查看不同模块的日志tag,如param、uevent、module等。 - 输出关键阶段日志,如第一阶段启动日志、required partition设备节点、uevent创建日志、服务启动日志等。 -- 日志等级可控,根据需要输出不同级别日志,目前日志级别分为INIT_DEBUG, -INIT_INFO,INIT_WARN,INIT_ERROR,INIT_FATAL。 +- 日志等级可控,根据需要输出不同级别日志,目前日志级别分为INIT_DEBUG、INIT_INFO、INIT_WARN、INIT_ERROR、INIT_FATAL。 ### 基本概念 init日志根据OpenHarmony版本不同实现方式不同。 -- 对于OpenHarmony标准版本,init日志采用内核的dmesg log实现。 -- 对于OpenHarmony liteos L1版本init日志采用hilog接口实现。 -- 对于OpenHarmony liteos L0版本init日志采用printf接口实现。 +- 对于OpenHarmony标准系统版本,init日志采用内核的dmesg log实现。 +- 对于OpenHarmony LiteOS小型系统版本init日志采用hilog接口实现。 +- 对于OpenHarmony LiteOS轻量系统版本init日志采用printf接口实现。 ### 约束与限制 无 diff --git a/zh-cn/device-dev/subsystems/subsys-build-gn-hap-compilation-guide.md b/zh-cn/device-dev/subsystems/subsys-build-gn-hap-compilation-guide.md index 045a09c28d618d7b84963820dfdd08db709dd182..4308d54284d488b2d06ed6962a4cd33eebb70df4 100644 --- a/zh-cn/device-dev/subsystems/subsys-build-gn-hap-compilation-guide.md +++ b/zh-cn/device-dev/subsystems/subsys-build-gn-hap-compilation-guide.md @@ -27,8 +27,8 @@ | hap_profile | HAP的config.json,Stage模型对应module.json。 | | raw_assets | 原始assets,这些assets会直接拷贝到HAP的assets目录下。 | | resources | 资源文件,编译后放置在assets/entry/resources目录下 | -| js_assets | js资源,ace编译后放置在assets/js/default目录下。| -| ets_assets | ets资源,ace编译后放置在assets/js/default目录下 | +| js_assets | js资源,编译后放置在assets/js/default目录下。| +| ets_assets | ets资源,编译后放置在assets/js/default目录下 | | deps | 当前目标的依赖 | | shared_libraries | 当前目标依赖的native库 | | hap_name | HAP的名字,可选,默认为目标名 | @@ -55,7 +55,7 @@ | sources | HAP的AppScope中的资源resources,只在Stage模型下使用。| #### ohos_js_assets -js或ets代码,ace编译后放置在assets/js/default目录下,stage模型根据代码分别放置到js或ets目录。 +js或ets代码,编译后放置在assets/js/default目录下,stage模型根据代码分别放置到js或ets目录。 | 支持的变量 | 说明 | | --------- | ---- | diff --git a/zh-cn/device-dev/subsystems/subsys-remote-start.md b/zh-cn/device-dev/subsystems/subsys-remote-start.md index 0cf26f8b0538e29872aa139f5a22e63220384376..26ba7d6eafbab2a50d19c830f3282937d1b44fd3 100755 --- a/zh-cn/device-dev/subsystems/subsys-remote-start.md +++ b/zh-cn/device-dev/subsystems/subsys-remote-start.md @@ -76,7 +76,7 @@ // 启动远程设备FA Want want = new Want(); // 封装启动远端FA的Want // 使用步骤2中获取的设备ID,并指定FA信息 - ElementName name = new ElementName(remote_device_id, "com.huawei.remote_package_name", "remote_class_name"); + ElementName name = new ElementName(remote_device_id, "com.example.remote_package_name", "remote_class_name"); want.setElement(name); // 将待启动的FA信息添加到Want中 want.setFlags(Want.FLAG_ABILITYSLICE_MULTI_DEVICE); // 设置分布式标记,若不设置将无法使用分布式能力 startAbility(want); // 按照Want启动指定FA,Want参数命名以实际开发平台API为准 diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-datashare.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-datashare.md new file mode 100644 index 0000000000000000000000000000000000000000..64a399d30f428d342fadf30bedf3955282c42466 --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-datashare.md @@ -0,0 +1,39 @@ +# 分布式数据管理子系统ChangeLog + +## cl.datashare.1 js-apis-data-dataShare API version 10开始托管数据PublishedItem中data的数据类型从Ashmem变更为ArrayBuffer + +**变更影响** + +PublishedItem中data的数据类型从Ashmem变更为ArrayBuffer + +## PublishedItem10+ + +指定发布的数据类型。 + +**系统能力:** SystemCapability.DistributedDataManager.DataShare.Consumer + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | -------- | -------- | +| key | string | 是 | 指定发布数据的键。 | +| data | string \| ArrayBuffer | 是 | 指定发布的数据。如果数据很大,请使用ArrayBuffer。 | +| subscriberId | string | 是 | 指定订阅者id。 | + +**适配指导** +示例代码如下: + +**示例:** + +```ts +let arrayBuffer = new ArrayBuffer(1); +let version = 1; +let data : Array = [{key:"key2", subscriberId:"11", data:arrayBuffer}]; +function publishCallback(err, result: Array) { + console.info("publishCallback " + JSON.stringify(result)); +} +try { + console.info("data length is:", data.length); + dataShareHelper.publish(data, "com.acts.ohos.data.datasharetest", version, publishCallback); +} catch (e) { + console.error("publish error " + JSON.stringify(e)); +} +``` \ No newline at end of file diff --git a/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md new file mode 100644 index 0000000000000000000000000000000000000000..468d7c3461f1920d9dcf6f6f23805ac694b9214a --- /dev/null +++ b/zh-cn/release-notes/changelogs/OpenHarmony_4.0.8.2/changelogs-mediaLibrary.md @@ -0,0 +1,145 @@ +# 文件子系统ChangeLog + +## cl.file.1 mediaLibrary相关接口兼容性变更 + +mediaLibrary部分接口兼容性变更。 + +**变更影响** + +[mediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md)部分接口兼容性变更。 +基于此前版本开发的应用,需注意接口的迭代更新。 + +**关键接口/组件变更** + +| 模块名 | 方法/属性/枚举/常量 | 变更类型 | +| ------------------------- | ------------------------------------------------------------ | -------- | +| medialibrary | **function** getFileAssets(options: MediaFetchOptions, callback: AsyncCallback<FetchFileResult>): void | 接口兼容性变更 | +| medialibrary | **function** getFileAssets(options: MediaFetchOptions): Promise<FetchFileResult> | 接口兼容性变更 | +| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string, callback: AsyncCallback<FileAsset>): void| 接口兼容性变更 | +| medialibrary | **function** createAsset(mediaType: MediaType, displayName: string, relativePath: string): Promise<FileAsset>| 接口兼容性变更 | +| medialibrary | **function** getAlbums(options: MediaFetchOptions, callback: AsyncCallback<Array<Album>>): void | 接口兼容性变更 | +| medialibrary | **function** getAlbums(options: MediaFetchOptions): Promise<Array<Album>> | 接口兼容性变更 | +| medialibrary | **function** FileAsset.commitModify(callback: AsyncCallback<void>): void | 接口兼容性变更 | +| medialibrary | **function** FileAsset.commitModify(): Promise<void> | 接口兼容性变更 | + +**适配指导** + +**getFileAssets接口获取文件资源兼容性影响:** + +在API version 10上,摒弃了物理目录作为相册的设计,采用了逻辑相册的设计,一个相册中可以添加多个文件,一个文件也可以在多个相册中呈现。新的设计将带来parent、albumId、albumUri和albumName属性使用上的不兼容,无法作为MediaFetchOptions的参数在getFileAssets接口中使用。下面示例代码为错误示例: + +1. 使用[getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary)接口获取媒体库实例。 +2. 创建检索条件[MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7)。 +3. 调用[getFileAssets](../../../application-dev/reference/apis/js-apis-medialibrary.md#getfileassets7)接口获取文件资源。 + +**错误示例:** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let albumId = 1; + let getImageOp = { + selections: fileKeyObj.ALBUM_ID + '= ?', // 使用parent、albumId、albumUri和albumName属性查询均无法获取文件资源。 + selectionArgs: [albumId.toString()], + }; + const fetchFileResult = await media.getFileAssets(getImageOp); // 查询失败,获取的fetchFileResult为空。 + const fileAsset = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +推荐使用以下方式调用getFileAssets接口获取文件资源: + +**正确示例:** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let fileKeyObj = mediaLibrary.FileKey; + let imageType = mediaLibrary.MediaType.IMAGE; + let getImageOp = { + selections: fileKeyObj.MEDIA_TYPE + '= ?', + selectionArgs: [imageType.toString()], // 查询所有图片类型的文件。 + }; + const fetchFileResult = await media.getFileAssets(getImageOp); + const fileAsset = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary fileAsset displayName: ' + fileAsset.displayName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**createAsset接口创建相册兼容性影响:** + +由于API version 10的SDK上relativePath和相册没有关联关系,文件创建成功后,relativePath的最后一级目录不会作为相册呈现。 + +**getAlbums接口获取相册兼容性影响:** + +由于API version 10的SDK上relativePath和相册没有关联关系,在使用getAlbums时不支持relativePath作为查询条件,并且ALBUM_NAME参数只能使用"Camera"和"Screenshots"。下面示例代码为错误示例: + +1. 使用[getMediaLibrary](../../../application-dev/reference/apis/js-apis-medialibrary.md#medialibrarygetmedialibrary)接口获取媒体库实例。 +2. 创建相册检索条件[MediaFetchOptions](../../../application-dev/reference/apis/js-apis-medialibrary.md#mediafetchoptions7)。 +3. 调用[getAlbums](../../../application-dev/reference/apis/js-apis-medialibrary.md#getalbums7)接口获取相册。 + +**错误示例:** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let AlbumNoArgsfetchOp = { + selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ?', + selectionArgs: ['新建相册1'], // 获取albumName为新建相册1的相册。 + }; + const fetchFileResult = await media.getAlbums(AlbumNoArgsfetchOp); // 查询失败,获取的fetchFileResult为空。 + const album = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary album albumName: ' + album.albumName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +使用如下示例代码可以获取Camera和Screenshots相册。 + +**正确示例:** + +```js +import mediaLibrary from '@ohos.multimedia.mediaLibrary'; + +async function example() { + try { + let context = getContext(this); + let media = mediaLibrary.getmediaLibrary(context); + let AlbumNoArgsfetchOp = { + selections: mediaLibrary.FileKey.ALBUM_NAME + ' = ? OR ' + mediaLibrary.FileKey.ALBUM_NAME + ' = ?', + selectionArgs: ['Camera', 'Screenshots'], // 获取相机相册和截屏录屏相册。 + }; + const fetchFileResult = await media.getAlbums(AlbumNoArgsfetchOp); + const album = await fetchFileResult.getFirstObject(); + console.info('mediaLibrary album albumName: ' + album.albumName); + } catch (err) { + console.error('mediaLibrary fail, err: ' + err); + } +} +``` + +**FileAsset.commitModify接口获取相册兼容性影响:** + +在API version 10的SDK上去掉了针对audio无意义的orientation属性,在使用commitModify接口时将无法对audio资源的orientation属性进行修改。