From 9b818fbc5b0d8cbf7b042e00c4a4ae223867f778 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Tue, 22 Mar 2022 16:05:00 +0800 Subject: [PATCH] update docs Signed-off-by: shawn_he --- en/native_sdk/resmgr/raw_dir.h | 101 ++++++++++++++ en/native_sdk/resmgr/raw_file.h | 172 ++++++++++++++++++++++++ en/native_sdk/resmgr/raw_file_manager.h | 126 +++++++++++++++++ 3 files changed, 399 insertions(+) create mode 100644 en/native_sdk/resmgr/raw_dir.h create mode 100644 en/native_sdk/resmgr/raw_file.h create mode 100644 en/native_sdk/resmgr/raw_file_manager.h diff --git a/en/native_sdk/resmgr/raw_dir.h b/en/native_sdk/resmgr/raw_dir.h new file mode 100644 index 00000000..3b0ae1e9 --- /dev/null +++ b/en/native_sdk/resmgr/raw_dir.h @@ -0,0 +1,101 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup rawfile + * @{ + * + * @brief Provides the function of operating rawfile directories and rawfiles. + * + * These functions include traversing, opening, searching, reading, and closing rawfiles. + * + * @since 8 + * @version 1.0 + */ + +/** + * @file raw_dir.h + * + * @brief Provides functions for operating rawfile directories. + * + * These functions include traversing and closing rawfile directories. + * + * @since 8 + * @version 1.0 + */ +#ifndef GLOBAL_RAW_DIR_H +#define GLOBAL_RAW_DIR_H + +#ifdef __cplusplus +extern "C" { +#endif + +struct RawDir; + +/** + * @brief Provides the function of accessing rawfile directories. + * + * + * + * @since 8 + * @version 1.0 + */ +typedef struct RawDir RawDir; + +/** + * @brief Obtains the rawfile name via an index. + * + * You can use this function to traverse a rawfile directory. + * + * @param rawDir Indicates the pointer to {@link RawDir}. + * @param index Indicates the index of the file in {@link RawDir}. + * @return Returns the rawfile name via an index. The return value can be used as the input parameter of {@link OH_ResourceManager_OpenRawFile}. + * If no rawfile is found after all rawfiles are traversed, NULL will be returned. + * @see OH_ResourceManager_OpenRawFile + * @since 8 + * @version 1.0 + */ +const char *OH_ResourceManager_GetRawFileName(RawDir *rawDir, int index); + +/** + * @brief Obtains the number of rawfiles in {@link RawDir}. + * + * You can use this function to obtain available indexes in {@link OH_ResourceManager_GetRawFileName}. + * + * @param rawDir Indicates the pointer to {@link RawDir}. + * @see OH_ResourceManager_GetRawFileName + * @since 8 + * @version 1.0 + */ +int OH_ResourceManager_GetRawFileCount(RawDir *rawDir); + +/** + * @brief Closes an opened {@link RawDir} and releases all associated resources. + * + * + * + * @param rawDir Indicates the pointer to {@link RawDir}. + * @see OH_ResourceManager_OpenRawDir + * @since 8 + * @version 1.0 + */ +void OH_ResourceManager_CloseRawDir(RawDir *rawDir); + +#ifdef __cplusplus +}; +#endif + +/** @} */ +#endif // GLOBAL_RAW_DIR_H diff --git a/en/native_sdk/resmgr/raw_file.h b/en/native_sdk/resmgr/raw_file.h new file mode 100644 index 00000000..7b4de7a9 --- /dev/null +++ b/en/native_sdk/resmgr/raw_file.h @@ -0,0 +1,172 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup rawfile + * @{ + * + * @brief Provides the function of operating rawfile directories and rawfiles. + * + * These functions include traversing, opening, searching, reading, and closing rawfiles. + * + * @since 8 + * @version 1.0 + */ + +/** + * @file raw_file.h + * + * @brief Provides functions for operating rawfiles. + * + * These functions include searching, reading, and closing rawfiles. + * + * @since 8 + * @version 1.0 + */ +#ifndef GLOBAL_RAW_FILE_H +#define GLOBAL_RAW_FILE_H + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +struct RawFile; + +/** + * @brief Provides the function of accessing rawfiles. + * + * + * + * @since 8 + * @version 1.0 + */ +typedef struct RawFile RawFile; + +/** + * @brief Provides rawfile descriptor information. + * + * RawFileDescriptor is an output parameter of {@link OH_ResourceManager_GetRawFileDescriptor}. + * It provides information including the rawfile descriptor and the start position and length of the rawfile in the HAP package. + * + * @since 8 + * @version 1.0 + */ +typedef struct { + /** rawfile descriptor */ + int fd; + + /** Start position of rawfile in the HAP package */ + long start; + + /** Length of rawfile in the HAP package */ + long length; +} RawFileDescriptor; + +/** + * @brief Reads a rawfile. + * + * You can use this function to read data of the specified length from the current position. + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @param buf Indicates the pointer to the buffer for storing the read data. + * @param length Indicates the length of the read data, in bytes. + * @return Returns the length of the read data in bytes. If the length is beyond the end of the rawfile, 0 will be returned. + * @since 8 + * @version 1.0 + */ +int OH_ResourceManager_ReadRawFile(const RawFile *rawFile, void *buf, int length); + +/** + * @brief Seeks for the data read/write position in the rawfile based on the specified offset. + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @param offset Indicates the specified offset. + * @param whence Indicates the data read/write position. The options are as follows: \n + * 0: The read/write position is offset. \n + * 1: The read/write position is the current position plus offset. \n + * 2: The read/write position is the end of the file (EOF) plus offset. + * @return Returns the new data read/write position if the operation is successful; returns (long) -1 otherwise. + * @since 8 + * @version 1.0 + */ +int OH_ResourceManager_SeekRawFile(const RawFile *rawFile, long offset, int whence); + +/** + * @brief Obtains the length of a rawfile in int32_t. + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @return Returns the total length of the rawfile. + * @since 8 + * @version 1.0 + */ +long OH_ResourceManager_GetRawFileSize(RawFile *rawFile); + +/** + * @brief Closes an opened {@link RawFile} and releases all associated resources. + * + * + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @see OH_ResourceManager_OpenRawFile + * @since 8 + * @version 1.0 + */ +void OH_ResourceManager_CloseRawFile(RawFile *rawFile); + +/** + * @brief Obtains the current offset of the rawfile in int32_t. + * + * + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @return Returns the current offset of the rawfile. + * @since 8 + * @version 1.0 + */ +long OH_ResourceManager_GetRawFileOffset(const RawFile *rawFile); + +/** + * @brief 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. + * + * @param rawFile Indicates the pointer to {@link RawFile}. + * @param descriptor Indicates the rawfile descriptor, and the start position and length of the rawfile file in the HAP package. + * @return Returns true if the rawfile descriptor is opened successfully; returns false if the rawfile cannot be accessed. + * @since 8 + * @version 1.0 + */ +bool OH_ResourceManager_GetRawFileDescriptor(const RawFile *rawFile, RawFileDescriptor &descriptor); + +/** + * @brief Closes a rawfile descriptor. + * + * To prevent file descriptor leakage, you are advised to release a rawfile descriptor after use. + * + * @param descriptor Indicates the rawfile descriptor, and the start position and length of the rawfile file in the HAP package. + * @return Returns true if the rawfile descriptor is closed successfully; returns false otherwise. + * @since 8 + * @version 1.0 + */ +bool OH_ResourceManager_ReleaseRawFileDescriptor(const RawFileDescriptor &descriptor); + +#ifdef __cplusplus +}; +#endif + +/** @} */ +#endif // GLOBAL_RAW_FILE_H diff --git a/en/native_sdk/resmgr/raw_file_manager.h b/en/native_sdk/resmgr/raw_file_manager.h new file mode 100644 index 00000000..fecb0acb --- /dev/null +++ b/en/native_sdk/resmgr/raw_file_manager.h @@ -0,0 +1,126 @@ +/* + * Copyright (c) 2022 Huawei Device Co., Ltd. + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * @addtogroup rawfile + * @{ + * + * @brief Provides the function of operating rawfile directories and rawfiles. + * + * These functions include traversing, opening, searching, reading, and closing rawfiles. + * + * @since 8 + * @version 1.0 + */ + +/** + * @file resource_manager.h + * + * @brief Provides functions for managing rawfile resources. + * + * You can use the resource manager to open a rawfile and perform operations such as data search and reading. + * + * @since 8 + * @version 1.0 + */ +#ifndef GLOBAL_NATIVE_RESOURCE_MANAGER_H +#define GLOBAL_NATIVE_RESOURCE_MANAGER_H + +#include "napi/native_api.h" +#include "raw_dir.h" +#include "raw_file.h" + +#ifdef __cplusplus +extern "C" { +#endif + +struct NativeResourceManager; + +/** + * @brief Implements the resource manager. + * + * This class encapsulates the native implementation of the JavaScript resource manager. + * You can obtain the pointer to ResourceManager by calling {@link OH_ResourceManager_InitNativeResourceManager}. + * + * @since 8 + * @version 1.0 + */ +typedef struct NativeResourceManager NativeResourceManager; + +/** + * @brief Obtains the native resource manager based on JavaScipt resource manager. + * + * After obtaining a resource manager, you can use it complete various rawfile operations. + * + * @param env Indicates the pointer to the JavaScipt Native Interface (napi) environment. + * @param jsResMgr Indicates the JavaScipt resource manager. + * @return Returns the pointer to {@link NativeResourceManager}. + * @since 8 + * @version 1.0 + */ +NativeResourceManager *OH_ResourceManager_InitNativeResourceManager(napi_env env, napi_value jsResMgr); + +/** + * @brief Releases a native resource manager. + * + * + * + * @param resMgr Indicates the pointer to {@link NativeResourceManager}. + * @since 8 + * @version 1.0 + */ +void OH_ResourceManager_ReleaseNativeResourceManager(NativeResourceManager *resMgr); + +/** + * @brief Opens a rawfile directory. + * + * After opening a rawfile directory, you can traverse all the rawfile files in it. + * + * @param mgr Indicates the pointer to {@link NativeResourceManager}. You can obtain this pointer by + * calling {@link OH_ResourceManager_InitNativeResourceManager}. + * @param dirName Indicates the name of the rawfile directory to open. If this field is left empty, + * the root directory of rawfile will be opened. + * @return Returns the pointer to {@link RawDir}. If this pointer is no longer needed after use, + * call {@link OH_ResourceManager_CloseRawDir} to release it. + * @see OH_ResourceManager_InitNativeResourceManager + * @see OH_ResourceManager_CloseRawDir + * @since 8 + * @version 1.0 + */ +RawDir *OH_ResourceManager_OpenRawDir(const NativeResourceManager *mgr, const char *dirName); + +/** + * @brief Opens a rawfile. + * + * After a rawfile is opened, you can read the data in it. + * + * @param mgr Indicates the pointer to {@link NativeResourceManager}. You can obtain this pointer by + * calling {@link OH_ResourceManager_InitNativeResourceManager}. + * @param fileName Indicates the file name in the relative path of the rawfile root directory. + * @return Returns the pointer to {@link RawFile}. If this pointer is no longer needed after use, + * call {@link OH_ResourceManager_CloseRawFile} to release it. + * @see OH_ResourceManager_InitNativeResourceManager + * @see OH_ResourceManager_CloseRawFile + * @since 8 + * @version 1.0 + */ +RawFile *OH_ResourceManager_OpenRawFile(const NativeResourceManager *mgr, const char *fileName); + +#ifdef __cplusplus +}; +#endif + +/** @} */ +#endif // GLOBAL_NATIVE_RESOURCE_MANAGER_H -- Gitee