From 7c3c55d16327307f32532e75abcc9b1bf1c63cbe Mon Sep 17 00:00:00 2001 From: xlw Date: Thu, 22 May 2025 10:35:52 +0800 Subject: [PATCH] =?UTF-8?q?childprocess=E5=A2=9E=E5=8A=A0ndk=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: xlw Change-Id: I818ff71ecaa04bf86b4caa9cac6d1dc7bc106d05 --- .../child_process/libchild_process.ndk.json | 24 +++ .../child_process/native_child_process.h | 163 ++++++++++++++++-- 2 files changed, 171 insertions(+), 16 deletions(-) diff --git a/ability/ability_runtime/child_process/libchild_process.ndk.json b/ability/ability_runtime/child_process/libchild_process.ndk.json index 7dcaf85d2..60cf2b93d 100644 --- a/ability/ability_runtime/child_process/libchild_process.ndk.json +++ b/ability/ability_runtime/child_process/libchild_process.ndk.json @@ -18,5 +18,29 @@ { "first_introduced": "20", "name": "OH_Ability_UnregisterNativeChildProcessExitCallback" + }, + { + "first_introduced": "20", + "name": "OH_Ability_CreateChildProcessConfigs" + }, + { + "first_introduced": "20", + "name": "OH_Ability_DestroyChildProcessConfigs" + }, + { + "first_introduced": "20", + "name": "OH_Ability_ChildProcessConfigs_SetIsolationMode" + }, + { + "first_introduced": "20", + "name": "OH_Ability_ChildProcessConfigs_SetProcessName" + }, + { + "first_introduced": "20", + "name": "OH_Ability_CreateNativeChildProcessWithConfigs" + }, + { + "first_introduced": "20", + "name": "OH_Ability_StartNativeChildProcessWithConfigs" } ] diff --git a/ability/ability_runtime/child_process/native_child_process.h b/ability/ability_runtime/child_process/native_child_process.h index 69a72e273..ce59adf74 100644 --- a/ability/ability_runtime/child_process/native_child_process.h +++ b/ability/ability_runtime/child_process/native_child_process.h @@ -119,6 +119,77 @@ typedef enum Ability_NativeChildProcess_ErrCode { NCP_ERR_CALLBACK_NOT_EXIST = 16010009, } Ability_NativeChildProcess_ErrCode; +/** + * @brief Enumerates the isolation modes used by the native child process module. + * @since 13 + */ +typedef enum NativeChildProcess_IsolationMode { + /** + * Normal isolation mode, parent process shares the same sandbox or internet with the child process. + */ + NCP_ISOLATION_MODE_NORMAL = 0, + + /** + * Isolated mode, parent process does not share the same sandbox or internet with the child process. + */ + NCP_ISOLATION_MODE_ISOLATED = 1, +} NativeChildProcess_IsolationMode; + +/** + * @brief Defines a struct for the child process configs. + * @since 20 + */ +typedef struct Ability_ChildProcessConfigs Ability_ChildProcessConfigs; + +/** + * @brief Creates a new child process configs object. + * The caller is responsible for destroying the returned object by calling + * {@link OH_Ability_DestroyChildProcessConfigs} to avoid memory leaks. + * @return Returns a pointer to the newly created {@link Ability_ChildProcessConfigs} object if successful. + * Returns nullptr if an internal error occurs or memory allocation fails. + * @since 20 + */ +Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs(); + +/** + * @brief Destroys a child process configs object and releases associated rescources. + * + * @param configs Pointer to the child process configs object to be destroyed. + * After this call, the pointer becomes invalid and must not be used. + * Passing nullptr is allowed and will be ignored. + * @return Returns {@link NCP_NO_ERROR} if the operation is successful or if the input is nullptr. + * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. + * @since 20 + */ +Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs); + +/** + * @brief Sets the isolation mode for the specified child process configs. + * The isolationMode only takes effect in {@link OH_Ability_StartNativeChildProcessWithConfigs}. + * + * @param configs Pointer to the child process configs object. Must not be nullptr. + * @param isolationMode The isolation mode to set. See {@link NativeChildProcess_IsolationMode} for details. + * @return Returns {@link NCP_NO_ERROR} if the isolation mode is set successful. + * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. + * @since 20 + */ +Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode( + Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode); + +/** + * @brief Sets the process name for the specified child process configs. + * + * @param configs Pointer to the child process configs object. Must not be nullptr. + * @param processName The process name to set. + * Must be a non-empty string containing only letters, digits, or underscores. + * Maximum length is 64 characters. + * The name ultimately assigned to the process is {bundleName}:{processName}. + * @return Returns {@link NCP_NO_ERROR} if the process name is set successful. + * Returns {@link NCP_NO_ERR_INVALID_PARAM} if the input parameters are invalid. + * @since 20 + */ +Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs, + const char* processName); /** * @brief Defines a callback function for notifying the child process startup result. @@ -179,6 +250,48 @@ typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteP int OH_Ability_CreateNativeChildProcess(const char* libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted); +/** + * @brief Creates a child process, loads the specified dynamic library file, and returns the startup result + * asynchronously through a callback parameter. + * The callback notification is an independent thread. When implementing the callback function, + * pay attention to thread synchronization and do not perform time-consuming operations to avoid long-time blocking. + * + * The dynamic library specified must implement and export the following functions: + * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() + * 2. void NativeChildProcess_MainProc() + * + * The processing logic sequence is shown in the following pseudocode: + * Main process: + * 1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback) + * Child process: + * 2. dlopen(libName) + * 3. dlsym("NativeChildProcess_OnConnect") + * 4. dlsym("NativeChildProcess_MainProc") + * 5. ipcRemote = NativeChildProcess_OnConnect() + * 6. NativeChildProcess_MainProc() + * Main process: + * 7. onProcessStartedCallback(ipcRemote, errCode) + * Child process: + * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. + * + * @param libName Name of the dynamic library file loaded in the child process. The value cannot be nullptr. + * @param configs Pointer to the child process configs object. The value cannot be nullptr. + * @param onProcessStarted Pointer to the callback function for notifying the child process startup result. + * The value cannot be nullptr. For details, see {@link OH_Ability_OnNativeChildProcessStarted}. + * @return Returns {@link NCP_NO_ERROR} if the call is successful, but the actual startup result is notified by the + * callback function. + * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. + * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. + * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device. + * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. + * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. + * For details, see {@link Ability_NativeChildProcess_ErrCode}. + * @see OH_Ability_OnNativeChildProcessStarted + * @since 20 + */ +Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName, + Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted); + /** * @brief The info of the file descriptors passed to child process. * @since 13 @@ -205,22 +318,6 @@ typedef struct NativeChildProcess_FdList { struct NativeChildProcess_Fd* head; } NativeChildProcess_FdList; -/** - * @brief Enumerates the isolation modes used by the native child process module. - * @since 13 - */ -typedef enum NativeChildProcess_IsolationMode { - /** - * Normal isolation mode, parent process shares the same sandbox or internet with the child process. - */ - NCP_ISOLATION_MODE_NORMAL = 0, - - /** - * Isolated mode, parent process does not share the same sandbox or internet with the child process. - */ - NCP_ISOLATION_MODE_ISOLATED = 1, -} NativeChildProcess_IsolationMode; - /** * @brief The options used by the child process. * @since 13 @@ -285,6 +382,40 @@ Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( const char* entry, NativeChildProcess_Args args, NativeChildProcess_Options options, int32_t *pid); +/** + * @brief Starts a child process, loads the specified dynamic library file. + * + * The dynamic library specified must implement a function with NativeChildProcess_Args as a + * pamameter(function name can be customized), and export the function, such as: + * 1. void Main(NativeChildProcess_Args args); + * + * The processing logic sequence is shown in the following pseudocode: + * Main process: + * 1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid) + * Child process: + * 2. dlopen(libName) + * 3. dlsym("Main") + * 4. Main(args) + * 5. The child process exits after the Main(args) function is returned + * + * @param entry Dynamic library and entry function loaded in child process, such as "libEntry.so:Main". + * The value cannot be nullptr. + * @param args The arguments passed to the child process. + * For details, see {@link NativeChildProcess_Args}. + * @param configs Pointer to the child process configs object. The value cannot be null. + * For details, see {@link Ability_ChildProcessConfigs}. + * @param pid The started child process id. + * @return Returns {@link NCP_NO_ERROR} if the call is successful. + * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid. + * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes. + * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process. + * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached. + * For details, see {@link Ability_NativeChildProcess_ErrCode}. + * @since 20 + */ +Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs( + const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid); + /** * @brief Child process get self NativeChildProcess_Args. * -- Gitee