native_child_process.h
Overview
Declares the APIs used to create a native child process and establish an IPC channel between the parent and child processes.
A maximum of 512 child processes can be started through this module and childProcessManager (non-SELF_FORK mode).
File to include: <AbilityKit/native_child_process.h>
Library: libchild_process.so
System capability: SystemCapability.Ability.AbilityRuntime.Core
Since: 12
Related module: ChildProcess
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| NativeChildProcess_Fd | NativeChildProcess_Fd | Describes the information about the file descriptor passed to the child process. |
| NativeChildProcess_FdList | NativeChildProcess_FdList | Describes the list of file descriptors passed to the child process. A maximum of 16 file descriptors are supported. |
| NativeChildProcess_Options | NativeChildProcess_Options | Describes the options used by the child process. |
| NativeChildProcess_Args | NativeChildProcess_Args | Describes the parameters passed to the child process. |
| Ability_ChildProcessConfigs | Ability_ChildProcessConfigs | Describes the configuration information about a child process, including the child process name and the sharing mode of the data sandbox and network environment. |
Enums
| Name | typedef Keyword | Description |
|---|---|---|
| Ability_NativeChildProcess_ErrCode | Ability_NativeChildProcess_ErrCode | Defines an enum for the error codes used by the native child process module. |
| NativeChildProcess_IsolationMode | NativeChildProcess_IsolationMode | Enumerates the sharing modes available for the data sandbox and network environment of a native child process. |
Functions
| Name | typedef Keyword | Description |
|---|---|---|
| Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs() | - | Creates a child process configuration object. When this object is no longer needed, call OH_Ability_DestroyChildProcessConfigs to destroy the object to prevent memory leakage. |
| Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs) | - | Destroys a child process configuration object and releases its memory. After this function is called, do not use the destroyed object. |
| Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode(Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode) | - | Sets the sharing mode of the data sandbox and network environment for a child process configuration object. For details, see NativeChildProcess_IsolationMode. This setting takes effect only when OH_Ability_StartNativeChildProcessWithConfigs or OH_Ability_CreateNativeChildProcessWithConfigs is called. |
| Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs,const char* processName) | - | Sets the process name in a child process configuration object. |
| typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) | OH_Ability_OnNativeChildProcessStarted | Creates a child process based on a child process configuration object and loads the specified DLL file. The startup result is asynchronously communicated to the caller via a callback. The callback runs in a separate thread. You must ensure thread synchronization and avoid time-consuming operations to prevent delays. |
| int OH_Ability_CreateNativeChildProcess(const char* libName,OH_Ability_OnNativeChildProcessStarted onProcessStarted) | - | Creates a child process, loads the specified Dynamic Link Library (DLL) 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 DLL 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: Parent process: 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback) Child process: 2. dlopen(libName) 3. dlsym("NativeChildProcess_OnConnect") 4. dlsym("NativeChildProcess_MainProc") 5. ipcRemote = NativeChildProcess_OnConnect() 6. NativeChildProcess_MainProc() Parent process: 7. onProcessStartedCallback(ipcRemote, errCode) Child process: 8. The child process exits after the NativeChildProcess_MainProc() function is returned. Device behavior differences: For API version 13 and earlier, this function can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. Starting from API version 14, this function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. Note: In API version 14 and earlier versions, a single process supports only one native child process. Starting from API version 15, a single process supports a maximum of 50 native child processes. |
| Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName,Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted) | - | Creates a child process based on a child process configuration object and loads the specified DLL file. The startup result is asynchronously communicated to the caller via a callback. The callback runs in a separate thread. You must ensure thread synchronization and avoid time-consuming operations to prevent delays. The DLL 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: Parent 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() Parent process: 7. onProcessStartedCallback(ipcRemote, errCode) Child process: 8. The child process exits after the NativeChildProcess_MainProc() function is returned. Device behavior differences: This function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. |
| Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(const char* entry, NativeChildProcess_Args args,NativeChildProcess_Options options, int32_t *pid) | - | Starts a child process and loads the specified Dynamic Link Library (DLL) file. The specified DLL must implement and export a function that accepts NativeChildProcess_Args as its parameter (you can customize the function name). The following is an example: 1. void Main(NativeChildProcess_Args args); The processing logic sequence is shown in the following pseudocode: Parent process: 1. OH_Ability_StartNativeChildProcess(entryPoint, args, options) Child process: 2. dlopen(libName) 3. dlsym("Main") 4. Main(args) 5. The child process exits after the Main(args) function returns. Device behavior differences: For API version 13 and earlier, this function can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. Starting from API version 14, this function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. |
| Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs(const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid) | - | Starts a native child process based on the child process configuration object, loads the specified DLL file, and calls the entry function. Arguments can be passed to the child process. The specified DLL must implement and export a function that accepts NativeChildProcess_Args as its parameter (you can customize the function name). The following is an example: 1. void Main(NativeChildProcess_Args args); The processing logic sequence is shown in the following pseudocode: Parent 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 returns. Device behavior differences: This function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. |
| NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs() | - | Obtains the startup parameters of the child process. |
| typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal) | OH_Ability_OnNativeChildProcessExit | Obtains the exit information of the child process. |
| Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit) | - | Registers a callback to listen for child process exit. If the same callback function is registered repeatedly, only one of them is kept. |
| Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit) | - | Unregisters the callback used to listen for child process exit. |
| Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationUid(Ability_ChildProcessConfigs* configs, bool enableIsolationUid) | - | Sets whether the child process uses an independent UID. This setting takes effect only when NativeChildProcess_IsolationMode is set to NCP_ISOLATION_MODE_ISOLATED. |
| Ability_NativeChildProcess_ErrCode OH_Ability_KillChildProcess(int32_t pid)) | - | Terminates a child process created by the current process. |
Enum Description
Ability_NativeChildProcess_ErrCode
enum Ability_NativeChildProcess_ErrCode
Description
Defines an enum for the error codes used by the native child process module.
Since: 12
| Value | Description |
|---|---|
| NCP_NO_ERROR = 0 | Operation successful. |
| NCP_ERR_INVALID_PARAM = 401 | Invalid parameter. |
| NCP_ERR_NOT_SUPPORTED = 801 | Creating a native child process is not supported. |
| NCP_ERR_INTERNAL = 16000050 | Internal error. |
| NCP_ERR_BUSY = 16010001 | A new child process cannot be created during the startup of another native child process. You can try again after the child process is started. This function is deprecated since API version 15. |
| NCP_ERR_TIMEOUT = 16010002 | Starting the native child process times out. |
| NCP_ERR_SERVICE_ERROR = 16010003 | Server error. |
| NCP_ERR_MULTI_PROCESS_DISABLED = 16010004 | The multi-process mode is disabled. A child process cannot be started. |
| NCP_ERR_ALREADY_IN_CHILD = 16010005 | A process cannot be created in a child process. |
| NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006 | The number of native child processes reaches the maximum. |
| NCP_ERR_LIB_LOADING_FAILED = 16010007 | The child process fails to load the DLL because the file does not exist or the corresponding method is not implemented or exported. |
| NCP_ERR_CONNECTION_FAILED = 16010008 | The child process fails to call the OnConnect method of the DLL. An invalid IPC object pointer may be returned. |
| NCP_ERR_CALLBACK_NOT_EXIST = 16010009 | The parent process calls the OH_Ability_UnregisterNativeChildProcessExitCallback function to unregister a callback function, but the callback function is not found. Since: 20 |
| NCP_ERR_INVALID_PID = 16010010 | The specified PID does not exist, does not belong to a child process of the current process, or belongs to a child process started in SELF_FORK mode by calling childProcessManager.startChildProcess. Since: 22 |
NativeChildProcess_IsolationMode
enum NativeChildProcess_IsolationMode
Description
Enumerates the sharing modes available for the data sandbox and network environment of a native child process.
Since: 13
| Value | Description |
|---|---|
| NCP_ISOLATION_MODE_NORMAL = 0 | In normal mode, the parent and child processes share the same sandbox or network environment. |
| NCP_ISOLATION_MODE_ISOLATED = 1 | In isolated mode, the parent and child processes each have their own separate sandbox and network environment. |
Function Description
OH_Ability_CreateChildProcessConfigs()
Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs()
Description
Creates a child process configuration object. When this object is no longer needed, call OH_Ability_DestroyChildProcessConfigs to destroy the object to prevent memory leakage.
Since: 20
Returns
| Type | Description |
|---|---|
| Ability_ChildProcessConfigs* | Pointer to the Ability_ChildProcessConfigs object: The call is successful. nullptr: An internal error occurs or memory allocation fails. |
OH_Ability_DestroyChildProcessConfigs()
Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs)
Description
Destroys a child process configuration object and releases its memory. After this function is called, do not use the destroyed object.
Since: 20
Parameters
| Name | Description |
|---|---|
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. After this function is called, the object pointer becomes invalid. Do not use the pointer. nullptr is allowed, which does not trigger any operation. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: An input parameter is nullptr. |
OH_Ability_ChildProcessConfigs_SetIsolationMode()
Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode(Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode)
Description
Sets the sharing mode of the data sandbox and network environment for a child process configuration object. For details, see NativeChildProcess_IsolationMode. This setting takes effect only when OH_Ability_StartNativeChildProcessWithConfigs or OH_Ability_CreateNativeChildProcessWithConfigs is called.
Since: 20
Parameters
| Name | Description |
|---|---|
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. The value cannot be nullptr. |
| NativeChildProcess_IsolationMode isolationMode | Sharing mode of the data sandbox and network environment. For details, see NativeChildProcess_IsolationMode. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: The parameter configs is nullptr. |
OH_Ability_ChildProcessConfigs_SetIsolationUid()
Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationUid(Ability_ChildProcessConfigs* configs, bool isolationUid)
Description
Sets whether the child process uses an independent UID. For example, in browser security hardening scenarios, you can isolate the UIDs of the main process and its child processes.
This setting takes effect only when NativeChildProcess_IsolationMode is set to NCP_ISOLATION_MODE_ISOLATED. If this function is not called to set isolationUid, the default value is false, meaning the child process will share the same UID as the main process.
Since: 21
Parameters
| Name | Description |
|---|---|
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. The value cannot be nullptr. |
| bool isolationUid | Whether the child process uses an independent UID. true if the child process uses an independent UID; false if the child process and the main process share the same UID. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: The parameter configs is nullptr. |
OH_Ability_ChildProcessConfigs_SetProcessName()
Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs,const char* processName)
Description
Sets the process name in a child process configuration object.
Since: 20
Parameters
| Name | Description |
|---|---|
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. The pointer cannot be null. |
| const char* processName | Pointer to the process name, which must be a non-empty string accepting only letters, digits, and underscores (_). The string contains a maximum of 64 characters. The final process name is in the format of {bundleName}:{processName}. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: The input parameter configs is nullptr, or processName contains characters other than letters, digits, and underscores (_). |
OH_Ability_OnNativeChildProcessStarted()
typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy)
Description
Defines a callback function for notifying the child process startup result.
Since: 12
Parameters
| Name | Description |
|---|---|
| int errCode | Error code returned by the callback function. NCP_NO_ERROR: The child process is created successfully. NCP_ERR_LIB_LOADING_FAILED: Loading the DLL file fails or the necessary export function is not implemented in the DLL. NCP_ERR_CONNECTION_FAILED: The OnConnect method implemented in the DLL does not return a valid IPC stub pointer. For details, see Ability_NativeChildProcess_ErrCode. |
| OHIPCRemoteProxy *remoteProxy | Pointer to the IPC object of the child process. If an exception occurs, the value may be nullptr. The pointer must be released by calling OH_IPCRemoteProxy_Destroy when it is no longer needed. |
Reference
OH_Ability_CreateNativeChildProcess()
int OH_Ability_CreateNativeChildProcess(const char* libName,OH_Ability_OnNativeChildProcessStarted onProcessStarted)
Description
Creates a child process, loads the specified Dynamic Link Library (DLL) 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 DLL 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:
Parent process:
1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)
Child process:
2. dlopen(libName)
3. dlsym("NativeChildProcess_OnConnect")
4. dlsym("NativeChildProcess_MainProc")
5. ipcRemote = NativeChildProcess_OnConnect()
6. NativeChildProcess_MainProc()
Parent process:
7. onProcessStartedCallback(ipcRemote, errCode)
Child process:
8. The child process exits after the NativeChildProcess_MainProc() function is returned.
Device behavior differences: For API version 13 and earlier, this function can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. Starting from API version 14, this function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned.
NOTE
In API version 14 and earlier versions, a single process supports only one native child process. Starting from API version 15, a single process supports a maximum of 50 native child processes.
Since: 12
Parameters
| Name | Description |
|---|---|
| const char* libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr. |
| OH_Ability_OnNativeChildProcessStarted onProcessStarted | Pointer to the callback function for notifying the child process startup result. The value cannot be nullptr. For details, see OH_Ability_OnNativeChildProcessStarted. |
Returns
| Type | Description |
|---|---|
| int | NCP_NO_ERROR: The call is successful, but the actual startup result is notified by the callback function. NCP_ERR_INVALID_PARAM: The dynamic library name or callback function pointer is invalid. NCP_ERR_NOT_SUPPORTED: The device does not support the creation of native child processes. NCP_ERR_MULTI_PROCESS_DISABLED: Multi-process mode is disabled on the device. NCP_ERR_ALREADY_IN_CHILD: A process cannot be created in a child process. NCP_ERR_MAX_CHILD_PROCESSES_REACHED: The number of native child processes reaches the maximum. For details, see Ability_NativeChildProcess_ErrCode. |
Reference
OH_Ability_OnNativeChildProcessStarted
OH_Ability_CreateNativeChildProcessWithConfigs()
Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName,Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted)
Description
Creates a child process based on a child process configuration object and loads the specified DLL file. The startup result is asynchronously communicated to the caller via a callback. The callback runs in a separate thread. You must ensure thread synchronization and avoid time-consuming operations to prevent delays.
The DLL 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:
Parent 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()
Parent process:
7. onProcessStartedCallback(ipcRemote, errCode)
Child process:
8. The child process exits after the NativeChildProcess_MainProc() function is returned.
Device behavior differences: This function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned.
Since: 20
Parameters
| Name | Description |
|---|---|
| const char* libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr. |
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. The value cannot be nullptr. |
| OH_Ability_OnNativeChildProcessStarted onProcessStarted | Pointer to the callback function for notifying the child process startup result. The value cannot be nullptr. For details, see OH_Ability_OnNativeChildProcessStarted. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: An input parameter is invalid. NCP_ERR_NOT_SUPPORTED: The device does not support the creation of native child processes. NCP_ERR_MULTI_PROCESS_DISABLED: Multi-process mode is disabled on the device, and the child process cannot be started. NCP_ERR_ALREADY_IN_CHILD: A process cannot be created in a child process. NCP_ERR_MAX_CHILD_PROCESSES_REACHED: The maximum number of native child processes has been reached. For details about the error codes, see Ability_NativeChildProcess_ErrCode. |
Reference
OH_Ability_OnNativeChildProcessStarted
OH_Ability_StartNativeChildProcess()
Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(const char* entry, NativeChildProcess_Args args,NativeChildProcess_Options options, int32_t *pid)
Description
Starts a native child process, loads the specified DLL file, and calls the entry function. The specified DLL must implement and export a function that accepts NativeChildProcess_Args as its parameter (you can customize the function name). Arguments can be passed to the child process. The ArkTS basic runtime environment cannot be created in the child process.
The following is an example:
void Main(NativeChildProcess_Args args);
The processing logic sequence is shown in the following pseudocode:
Parent process:
1. OH_Ability_StartNativeChildProcess(entryPoint, args, options)
Child process:
2. dlopen(libName)
3. dlsym("Main")
4. Main(args)
5. The child process exits after the Main(args) function returns.
Device behavior differences: For API version 13 and earlier, this function can be properly called on PCs/2-in-1 devices. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned. Starting from API version 14, this function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned.
Since: 13
Parameters
| Name | Description |
|---|---|
| const char* entry | Pointer to the DDL and entry function to be loaded by the child process, for example, libEntry.so:Main. The value cannot be nullptr. |
| NativeChildProcess_Args args | Parameters passed to the child process. |
| NativeChildProcess_Options options | Child process options. |
| int32_t *pid | Pointer to the ID of the child process. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: The dynamic library name or callback function pointer is invalid. NCP_ERR_NOT_SUPPORTED: The device does not support the creation of native child processes. NCP_ERR_ALREADY_IN_CHILD: Multi-process mode is disabled on the device. NCP_ERR_MAX_CHILD_PROCESSES_REACHED: The maximum number of native child processes has been reached. For details about the error codes, see Ability_NativeChildProcess_ErrCode. |
Reference
OH_Ability_OnNativeChildProcessStarted
OH_Ability_StartNativeChildProcessWithConfigs()
Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs(const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid)
Description
Starts a native child process based on the child process configuration object, loads the specified DLL file, and calls the entry function. Arguments can be passed to the child process. The specified DLL must implement and export a function that accepts NativeChildProcess_Args as its parameter (you can customize the function name).
The following is an example:
void Main(NativeChildProcess_Args args);
The processing logic sequence is shown in the following pseudocode:
Parent 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 returns.
Device behavior differences: This function can be properly called on PCs/2-in-1 devices and tablets. If it is called on other devices, error code NCP_ERR_NOT_SUPPORTED is returned.
Since: 20
Parameters
| Name | Description |
|---|---|
| const char* entry | Pointer to the symbol and entry function of the DDL called in the child process, separated by a colon (😃, for example, libentry.so:Main. The value cannot be nullptr. |
| NativeChildProcess_Args args | Parameters passed to the child process. |
| Ability_ChildProcessConfigs* configs | Pointer to a child process configuration object. |
| int32_t *pid | Pointer to the ID of the child process. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: An input parameter is invalid. NCP_ERR_NOT_SUPPORTED: The device does not support the creation of native child processes. NCP_ERR_ALREADY_IN_CHILD: A process cannot be created in a child process. NCP_ERR_MAX_CHILD_PROCESSES_REACHED: The maximum number of native child processes has been reached. For details about the error codes, see Ability_NativeChildProcess_ErrCode. |
OH_Ability_GetCurrentChildProcessArgs()
NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs()
Description
Used by a child process, after being started by calling OH_Ability_StartNativeChildProcess, to obtain the startup parameter NativeChildProcess_Args from any .so file or child thread.
Since: 17
Returns
| Type | Description |
|---|---|
| NativeChildProcess_Args* | Pointer to the startup parameters of the child process. |
OH_Ability_OnNativeChildProcessExit()
typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal)
Description
Defines a callback to listen for child process exit.
Since: 20
Parameters
| Name | Description |
|---|---|
| int32_t pid | Pointer to the ID of the child process. |
| int32_t signal | Signal for child process exit. |
See
OH_Ability_RegisterNativeChildProcessExitCallback
OH_Ability_UnregisterNativeChildProcessExitCallback
OH_Ability_RegisterNativeChildProcessExitCallback()
Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit)
Description
Registers a callback to listen for child process exit. When a child process started by calling OH_Ability_StartNativeChildProcess or startNativeChildProcess in @ohos.app.ability.childProcessManager exits abnormally, the callback function is invoked. If the same callback function is registered multiple times, the callback function is executed only once when the child process exits.
The parameter must implement the entry function OH_Ability_OnNativeChildProcessExit. For details, see Registering the Native Child Process Exit Callback Function.
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Ability_OnNativeChildProcessExit onProcessExit | Entry point of the callback function to be called when the child process exits. The value cannot be nullptr. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: An input parameter is invalid. NCP_ERR_INTERNAL: An internal error occurs. For details, see Ability_NativeChildProcess_ErrCode. |
OH_Ability_UnregisterNativeChildProcessExitCallback()
Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit)
Description
Unregisters the callback used to listen for child process exit.
The parameter must implement the entry function OH_Ability_OnNativeChildProcessExit. For details, see Registering the Native Child Process Exit Callback Function.
Since: 20
Parameters
| Name | Description |
|---|---|
| OH_Ability_OnNativeChildProcessExit onProcessExit | Entry point of the callback function to be called when the child process exits. The value cannot be nullptr. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_INVALID_PARAM: An input parameter is invalid. NCP_ERR_INTERNAL: An internal error occurs. NCP_ERR_CALLBACK_NOT_EXIST: The callback function is not found. For details, see Ability_NativeChildProcess_ErrCode. |
OH_Ability_KillChildProcess()
Ability_NativeChildProcess_ErrCode OH_Ability_KillChildProcess(int32_t pid)
Description
Terminates a child process created by the current process.
NOTE
This function cannot be used to terminate a child process started in SELF_FORK mode by calling childProcessManager.startChildProcess.
Since: 22
Parameters
| Name | Description |
|---|---|
| int32_t pid | PID of the child process to terminate. |
Returns
| Type | Description |
|---|---|
| Ability_NativeChildProcess_ErrCode | NCP_NO_ERROR: The call is successful. NCP_ERR_SERVICE_ERROR: Server error. NCP_ERR_INVALID_PID: The input PID is invalid. For details, see Ability_NativeChildProcess_ErrCode. |