diff --git a/ability/ability_runtime/child_process/libchild_process.ndk.json b/ability/ability_runtime/child_process/libchild_process.ndk.json index 6f6bdcebf52d519ab862738a444bbdc8ae0a2a04..4da099fecf077e9dc58e43479da54d32e0dbfbf6 100644 --- a/ability/ability_runtime/child_process/libchild_process.ndk.json +++ b/ability/ability_runtime/child_process/libchild_process.ndk.json @@ -10,5 +10,29 @@ { "first_introduced": "17", "name": "OH_Ability_GetCurrentChildProcessArgs" + }, + { + "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" } ] \ No newline at end of file diff --git a/ability/ability_runtime/child_process/native_child_process.h b/ability/ability_runtime/child_process/native_child_process.h index ca195fdefad29793d3711a5fc3b03084cf25f7d1..d7d253040ad23524fabaf9bc5c140b8656546a0b 100644 --- a/ability/ability_runtime/child_process/native_child_process.h +++ b/ability/ability_runtime/child_process/native_child_process.h @@ -113,6 +113,61 @@ typedef enum Ability_NativeChildProcess_ErrCode { NCP_ERR_CONNECTION_FAILED = 16010008, } Ability_NativeChildProcess_ErrCode; +/** + * @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 resources. + * + * @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_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 successfully. + * Returns {@link NCP_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 successfully. + * Returns {@link NCP_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. @@ -173,6 +228,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:\n + * 1. OHIPCRemoteStub* NativeChildProcess_OnConnect()\n + * 2. void NativeChildProcess_MainProc()\n + * + * The processing logic sequence is shown in the following pseudocode: \n + * Main process: \n + * 1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback)\n + * Child process: \n + * 2. dlopen(libName)\n + * 3. dlsym("NativeChildProcess_OnConnect")\n + * 4. dlsym("NativeChildProcess_MainProc")\n + * 5. ipcRemote = NativeChildProcess_OnConnect()\n + * 6. NativeChildProcess_MainProc()\n + * Main process: \n + * 7. onProcessStartedCallback(ipcRemote, errCode)\n + * Child process: \n + * 8. The child process exits after the NativeChildProcess_MainProc() function is returned. \n + * + * @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.\n + * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n + * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n + * Returns {@link NCP_ERR_MULTI_PROCESS_DISABLED} if the multi-process mode is disabled on the device.\n + * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n + * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n + * 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 @@ -279,6 +376,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:\n + * 1. void Main(NativeChildProcess_Args args); + * + * The processing logic sequence is shown in the following pseudocode: \n + * Main process: \n + * 1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid)\n + * Child process: \n + * 2. dlopen(libName)\n + * 3. dlsym("Main")\n + * 4. Main(args)\n + * 5. The child process exits after the Main(args) function is returned \n + * + * @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.\n + * Returns {@link NCP_ERR_INVALID_PARAM} if the dynamic library name or callback function pointer is invalid.\n + * Returns {@link NCP_ERR_NOT_SUPPORTED} if the device does not support the creation of native child processes.\n + * Returns {@link NCP_ERR_ALREADY_IN_CHILD} if it is not allowed to create another child process in the child process.\n + * Returns {@link NCP_ERR_MAX_CHILD_PROCESSES_REACHED} if the maximum number of native child processes is reached.\n + * 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. *