1# native_child_process.h 2 3<!--Kit: Ability Kit--> 4<!--Subsystem: Ability--> 5<!--Owner: @SKY2001--> 6<!--Designer: @jsjzju--> 7<!--Tester: @lixueqing513--> 8<!--Adviser: @huipeizi--> 9 10## Overview 11 12Declares the APIs used to create a native child process and establish an IPC channel between the parent and child processes. 13 14A maximum of 512 child processes can be started through this module and [childProcessManager](js-apis-app-ability-childProcessManager.md) (non-SELF_FORK mode). 15 16**File to include**: <AbilityKit/native_child_process.h> 17 18**Library**: libchild_process.so 19 20**System capability**: SystemCapability.Ability.AbilityRuntime.Core 21 22**Since**: 12 23 24**Related module**: [ChildProcess](capi-childprocess.md) 25 26## Summary 27 28### Structs 29 30| Name| typedef Keyword| Description| 31| -- | -- | -- | 32| [NativeChildProcess_Fd](capi-nativechildprocess-fd.md) | NativeChildProcess_Fd | Describes the information about the file descriptor passed to the child process.| 33| [NativeChildProcess_FdList](capi-nativechildprocess-fdlist.md) | NativeChildProcess_FdList | Describes the list of file descriptors passed to the child process. A maximum of 16 file descriptors are supported.| 34| [NativeChildProcess_Options](capi-nativechildprocess-options.md) | NativeChildProcess_Options | Describes the options used by the child process.| 35| [NativeChildProcess_Args](capi-nativechildprocess-args.md) | NativeChildProcess_Args | Describes the parameters passed to the child process.| 36| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md) | 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.| 37 38### Enums 39 40| Name| typedef Keyword| Description| 41| -- | -- | -- | 42| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) | Ability_NativeChildProcess_ErrCode | Defines an enum for the error codes used by the native child process module.| 43| [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode) | NativeChildProcess_IsolationMode | Enumerates the sharing modes available for the data sandbox and network environment of a native child process.| 44 45### Functions 46 47| Name| typedef Keyword| Description| 48| -- | -- | -- | 49| [Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs()](#oh_ability_createchildprocessconfigs) | - | Creates a child process configuration object. When this object is no longer needed, call [OH_Ability_DestroyChildProcessConfigs](capi-native-child-process-h.md#oh_ability_destroychildprocessconfigs) to destroy the object to prevent memory leakage.| 50| [Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs)](#oh_ability_destroychildprocessconfigs) | - | Destroys a child process configuration object and releases its memory. After this function is called, do not use the destroyed object.| 51| [Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode(Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode)](#oh_ability_childprocessconfigs_setisolationmode) | - | Sets the sharing mode of the data sandbox and network environment for a child process configuration object. For details, see [NativeChildProcess_IsolationMode](capi-native-child-process-h.md#nativechildprocess_isolationmode). This setting takes effect only when [OH_Ability_StartNativeChildProcessWithConfigs](capi-native-child-process-h.md#oh_ability_startnativechildprocesswithconfigs) is called.| 52| [Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs,const char* processName)](#oh_ability_childprocessconfigs_setprocessname) | - | Sets the process name in a child process configuration object.| 53| [typedef void (\*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy)](#oh_ability_onnativechildprocessstarted) | 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.| 54| [int OH_Ability_CreateNativeChildProcess(const char* libName,OH_Ability_OnNativeChildProcessStarted onProcessStarted)](#oh_ability_createnativechildprocess) | - | 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:<br>1. OHIPCRemoteStub* NativeChildProcess_OnConnect()<br>2. void NativeChildProcess_MainProc()<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("NativeChildProcess_OnConnect")<br>4. dlsym("NativeChildProcess_MainProc")<br>5. ipcRemote = NativeChildProcess_OnConnect()<br>6. NativeChildProcess_MainProc()<br>Parent process:<br>7. onProcessStartedCallback(ipcRemote, errCode)<br>Child process:<br>8. The child process exits after the NativeChildProcess_MainProc() function is returned.<br>Note: Starting from API version 14, 2-in-1 devices and tablets are supported. In API version 13 and earlier versions, only 2-in-1 devices are supported. Starting from API version 15, a single process supports a maximum of 50 native child processes. In API version 14 and earlier versions, a single process supports only one native child process.| 55| [Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName,Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted)](#oh_ability_createnativechildprocesswithconfigs) | - | 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:<br>1. OHIPCRemoteStub* NativeChildProcess_OnConnect()<br>2. void NativeChildProcess_MainProc()<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("NativeChildProcess_OnConnect")<br>4. dlsym("NativeChildProcess_MainProc")<br>5. ipcRemote = NativeChildProcess_OnConnect()<br>6. NativeChildProcess_MainProc()<br>Parent process:<br>7. onProcessStartedCallback(ipcRemote, errCode)<br>Child process:<br>8. <br>The child process exits after the NativeChildProcess_MainProc() function is returned. <br>Note: Currently, only 2-in-1 devices and tablets are supported.| 56| [Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(const char* entry, NativeChildProcess_Args args,NativeChildProcess_Options options, int32_t *pid)](#oh_ability_startnativechildprocess) | - | 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:<br>1. void Main(NativeChildProcess_Args args);<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_StartNativeChildProcess(entryPoint, args, options)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("Main")<br>4. Main(args)<br>5. The child process exits after the Main(args) function returns.<br>Note: Currently, only 2-in-1 devices and tablets are supported.| 57| [Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs(const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid)](#oh_ability_startnativechildprocesswithconfigs) | - | 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:<br>1. void Main(NativeChildProcess_Args args);<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("Main")<br>4. Main(args)<br>5. The child process exits after the Main(args) function returns.<br>Note: Currently, only 2-in-1 devices and tablets are supported.| 58| [NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs()](#oh_ability_getcurrentchildprocessargs) | - | Obtains the startup parameters of the child process.<br>Note: Currently, only 2-in-1 devices and tablets are supported.| 59| [typedef void (\*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal)](#oh_ability_onnativechildprocessexit) | OH_Ability_OnNativeChildProcessExit | Obtains the exit information of the child process.| 60| [Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit)](#oh_ability_registernativechildprocessexitcallback) | - | Registers a callback to listen for child process exit. If the same callback function is registered repeatedly, only one of them is kept.| 61| [Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit)](#oh_ability_unregisternativechildprocessexitcallback) | - | Unregisters the callback used to listen for child process exit.| 62 63## Enum Description 64 65### Ability_NativeChildProcess_ErrCode 66 67``` 68enum Ability_NativeChildProcess_ErrCode 69``` 70 71**Description** 72 73Defines an enum for the error codes used by the native child process module. 74 75**Since**: 12 76 77| Value| Description| 78| -- | -- | 79| NCP_NO_ERROR = 0 | Operation successful.| 80| NCP_ERR_INVALID_PARAM = 401 | Invalid parameter.| 81| NCP_ERR_NOT_SUPPORTED = 801 | Creating a native child process is not supported.| 82| NCP_ERR_INTERNAL = 16000050 | Internal error.| 83| 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.| 84| NCP_ERR_TIMEOUT = 16010002 | Starting the native child process times out.| 85| NCP_ERR_SERVICE_ERROR = 16010003 | Server error.| 86| NCP_ERR_MULTI_PROCESS_DISABLED = 16010004 | The multi-process mode is disabled. A child process cannot be started.| 87| NCP_ERR_ALREADY_IN_CHILD = 16010005 | A process cannot be created in a child process.| 88| NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006 | The number of native child processes reaches the maximum.| 89| 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.| 90| 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.| 91| 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.| 92 93### NativeChildProcess_IsolationMode 94 95``` 96enum NativeChildProcess_IsolationMode 97``` 98 99**Description** 100 101Enumerates the sharing modes available for the data sandbox and network environment of a native child process. 102 103**Since**: 13 104 105| Value| Description| 106| -- | -- | 107| NCP_ISOLATION_MODE_NORMAL = 0 | In normal mode, the parent and child processes share the same sandbox or network environment.| 108| NCP_ISOLATION_MODE_ISOLATED = 1 | In isolated mode, the parent and child processes each have their own separate sandbox and network environment.| 109 110 111## Function Description 112 113### OH_Ability_CreateChildProcessConfigs() 114 115``` 116Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs() 117``` 118 119**Description** 120 121Creates a child process configuration object. When this object is no longer needed, call [OH_Ability_DestroyChildProcessConfigs](capi-native-child-process-h.md#oh_ability_destroychildprocessconfigs) to destroy the object to prevent memory leakage. 122 123**Since**: 20 124 125**Returns** 126 127| Type | Description| 128|----------------------------------| -- | 129| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* | Pointer to the [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md) object: The call is successful.<br> nullptr: An internal error occurs or memory allocation fails.| 130 131### OH_Ability_DestroyChildProcessConfigs() 132 133``` 134Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs) 135``` 136 137**Description** 138 139Destroys a child process configuration object and releases its memory. After this function is called, do not use the destroyed object. 140 141**Since**: 20 142 143 144**Parameters** 145 146| Name| Description| 147| -- | -- | 148| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* 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.| 149 150**Returns** 151 152| Type| Description| 153| -- | -- | 154| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_NO_ERR_INVALID_PARAM**: An input parameter is nullptr.| 155 156### OH_Ability_ChildProcessConfigs_SetIsolationMode() 157 158``` 159Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode(Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode) 160``` 161 162**Description** 163 164Sets the sharing mode of the data sandbox and network environment for a child process configuration object. For details, see [NativeChildProcess_IsolationMode](capi-native-child-process-h.md#nativechildprocess_isolationmode). This setting takes effect only when [OH_Ability_StartNativeChildProcessWithConfigs](capi-native-child-process-h.md#oh_ability_startnativechildprocesswithconfigs) is called. 165 166**Since**: 20 167 168 169**Parameters** 170 171| Name| Description| 172| -- | -- | 173| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* configs | Pointer to a child process configuration object. The value cannot be nullptr.| 174| [NativeChildProcess_IsolationMode](capi-native-child-process-h.md#nativechildprocess_isolationmode) isolationMode | Sharing mode of the data sandbox and network environment. For details, see **NativeChildProcess_IsolationMode**.| 175 176**Returns** 177 178| Type| Description| 179| -- | -- | 180| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_NO_ERR_INVALID_PARAM**: The input parameter **configs** is nullptr.| 181 182### OH_Ability_ChildProcessConfigs_SetProcessName() 183 184``` 185Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs,const char* processName) 186``` 187 188**Description** 189 190Sets the process name in a child process configuration object. 191 192**Since**: 20 193 194 195**Parameters** 196 197| Name| Description| 198| -- | -- | 199| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* configs | Pointer to a child process configuration object. The pointer cannot be null.| 200| 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}.| 201 202**Returns** 203 204| Type| Description| 205| -- | -- | 206| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_NO_ERR_INVALID_PARAM**: The input parameter **configs** is nullptr, or **processName** contains characters other than letters, digits, and underscores (_).| 207 208### OH_Ability_OnNativeChildProcessStarted() 209 210``` 211typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) 212``` 213 214**Description** 215 216Defines a callback function for notifying the child process startup result. 217 218**Since**: 12 219 220**Parameters** 221 222| Name| Description| 223| -- | -- | 224| int errCode | Error code returned by the callback function.<br>[NCP_NO_ERROR](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The child process is created successfully.<br>[NCP_ERR_LIB_LOADING_FAILED](capi-native-child-process-h.md#ability_nativechildprocess_errcode): Loading the DLL file fails or the necessary export function is not implemented in the DLL.<br>[NCP_ERR_CONNECTION_FAILED](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The **OnConnect** method implemented in the DLL does not return a valid IPC stub pointer.<br>For details, see [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode).| 225| [OHIPCRemoteProxy *remoteProxy](../apis-ipc-kit/capi-ohipcparcel-ohipcremoteproxy.md) | 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_Destory](../apis-ipc-kit/capi-ipc-cremote-object-h.md#oh_ipcremoteproxy_destroy) when it is no longer needed.| 226 227**Reference** 228 229[OH_IPCRemoteProxy_Destory](../apis-ipc-kit/capi-ipc-cremote-object-h.md#oh_ipcremoteproxy_destroy) 230 231### OH_Ability_CreateNativeChildProcess() 232 233``` 234int OH_Ability_CreateNativeChildProcess(const char* libName,OH_Ability_OnNativeChildProcessStarted onProcessStarted) 235``` 236 237**Description** 238 239Creates 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. 240 241The DLL specified must implement and export the following functions:<br>1. OHIPCRemoteStub* NativeChildProcess_OnConnect()<br>2. void NativeChildProcess_MainProc()<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("NativeChildProcess_OnConnect")<br>4. dlsym("NativeChildProcess_MainProc")<br>5. ipcRemote = NativeChildProcess_OnConnect()<br>6. NativeChildProcess_MainProc()<br>Parent process:<br>7. onProcessStartedCallback(ipcRemote, errCode)<br>Child process:<br>8. The child process exits after the NativeChildProcess_MainProc() function is returned. 242 243> **NOTE** 244> 245> Starting from API version 14, 2-in-1 devices and tablets are supported. In API version 13 and earlier versions, only 2-in-1 devices are supported. 246> 247> Starting from API version 15, a single process supports a maximum of 50 native child processes. In API version 14 and earlier versions, a single process supports only one native child process. 248 249**Since**: 12 250 251**Parameters** 252 253| Name| Description| 254| -- | -- | 255| const char* libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr.| 256| [OH_Ability_OnNativeChildProcessStarted](capi-native-child-process-h.md#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](capi-native-child-process-h.md#oh_ability_onnativechildprocessstarted).| 257 258**Returns** 259 260| Type| Description| 261| -- | -- | 262| int | [NCP_NO_ERROR](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The call is successful, but the actual startup result is notified by the callback function.<br>[NCP_ERR_INVALID_PARAM](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The dynamic library name or callback function pointer is invalid.<br>[NCP_ERR_NOT_SUPPORTED](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The device does not support the creation of native child processes.<br>[NCP_ERR_MULTI_PROCESS_DISABLED](capi-native-child-process-h.md#ability_nativechildprocess_errcode): Multi-process mode is disabled on the device.<br>[NCP_ERR_ALREADY_IN_CHILD](capi-native-child-process-h.md#ability_nativechildprocess_errcode): A process cannot be created in a child process.<br>[NCP_ERR_MAX_CHILD_PROCESSES_REACHED](capi-native-child-process-h.md#ability_nativechildprocess_errcode): The number of native child processes reaches the maximum.<br>For details, see [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode).| 263 264**Reference** 265 266[OH_Ability_OnNativeChildProcessStarted](capi-native-child-process-h.md#oh_ability_onnativechildprocessstarted) 267 268### OH_Ability_CreateNativeChildProcessWithConfigs() 269 270``` 271Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName,Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted) 272``` 273 274**Description** 275 276Creates 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. 277 278The DLL specified must implement and export the following functions:<br>1. OHIPCRemoteStub* NativeChildProcess_OnConnect()<br>2. void NativeChildProcess_MainProc()<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("NativeChildProcess_OnConnect")<br>4. dlsym("NativeChildProcess_MainProc")<br>5. ipcRemote = NativeChildProcess_OnConnect()<br>6. NativeChildProcess_MainProc()<br>Parent process:<br>7. onProcessStartedCallback(ipcRemote, errCode)<br>Child process:<br>8. The child process exits after the NativeChildProcess_MainProc() function is returned. 279 280> **NOTE** 281> 282> Currently, only 2-in-1 devices and tablets are supported. 283 284**Since**: 20 285 286**Parameters** 287 288| Name| Description| 289| -- | -- | 290| const char* libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr.| 291| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* configs | Pointer to a child process configuration object. The value cannot be nullptr.| 292| [OH_Ability_OnNativeChildProcessStarted](capi-native-child-process-h.md#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**.| 293 294**Returns** 295 296| Type| Description| 297| -- | -- | 298| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_ERR_INVALID_PARAM**: An input parameter is invalid.<br>**NCP_ERR_NOT_SUPPORTED**: The device does not support the creation of native child processes.<br>**NCP_ERR_MULTI_PROCESS_DISABLED**: Multi-process mode is disabled on the device, and the child process cannot be started.<br>**NCP_ERR_ALREADY_IN_CHILD**: A process cannot be created in a child process.<br>**NCP_ERR_MAX_CHILD_PROCESSES_REACHED**: The maximum number of native child processes has been reached.<br>For details about the error codes, see **Ability_NativeChildProcess_ErrCode**.| 299 300**Reference** 301 302[OH_Ability_OnNativeChildProcessStarted](capi-native-child-process-h.md#oh_ability_onnativechildprocessstarted) 303 304### OH_Ability_StartNativeChildProcess() 305 306``` 307Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(const char* entry, NativeChildProcess_Args args,NativeChildProcess_Options options, int32_t *pid) 308``` 309 310**Description** 311 312Starts 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](capi-nativechildprocess-args.md) 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. 313 314The following is an example:<br>void Main(NativeChildProcess_Args args);<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_StartNativeChildProcess(entryPoint, args, options)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("Main")<br>4. Main(args)<br>5. The child process exits after the Main(args) function returns. 315 316> **NOTE** 317> 318> Starting from API version 14, 2-in-1 devices and tablets are supported. In API version 13 and earlier versions, only 2-in-1 devices are supported. 319 320**Since**: 13 321 322**Parameters** 323 324| Name| Description| 325| -- | -- | 326| 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.| 327| [NativeChildProcess_Args](capi-nativechildprocess-args.md) args | Parameters passed to the child process.| 328| [NativeChildProcess_Options](capi-nativechildprocess-options.md) options | Child process options.| 329| int32_t *pid | Pointer to the ID of the child process.| 330 331**Returns** 332 333| Type| Description| 334| -- | -- | 335| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_ERR_INVALID_PARAM**: The dynamic library name or callback function pointer is invalid.<br>**NCP_ERR_NOT_SUPPORTED**: The device does not support the creation of native child processes.<br> **NCP_ERR_ALREADY_IN_CHILD**: Multi-process mode is disabled on the device.<br>**NCP_ERR_MAX_CHILD_PROCESSES_REACHED**: The maximum number of native child processes has been reached.<br>For details about the error codes, see **Ability_NativeChildProcess_ErrCode**.| 336 337**Reference** 338 339[OH_Ability_OnNativeChildProcessStarted](capi-native-child-process-h.md#oh_ability_onnativechildprocessstarted) 340 341### OH_Ability_StartNativeChildProcessWithConfigs() 342 343``` 344Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs(const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid) 345``` 346 347**Description** 348 349Starts 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](capi-nativechildprocess-args.md) as its parameter (you can customize the function name). 350 351The following is an example:<br>void Main(NativeChildProcess_Args args);<br>The processing logic sequence is shown in the following pseudocode:<br>Parent process:<br>1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid)<br>Child process:<br>2. dlopen(libName)<br>3. dlsym("Main")<br>4. Main(args)<br>5. The child process exits after the Main(args) function returns. 352 353> **NOTE** 354> 355> Currently, only 2-in-1 devices and tablets are supported. 356 357**Since**: 20 358 359**Parameters** 360 361| Name| Description| 362| -- | -- | 363| 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.| 364| [NativeChildProcess_Args](capi-nativechildprocess-args.md) args | Parameters passed to the child process.| 365| [Ability_ChildProcessConfigs](capi-ability-childprocessconfigs.md)* configs | Pointer to a child process configuration object.| 366| int32_t *pid | Pointer to the ID of the child process.| 367 368**Returns** 369 370| Type| Description| 371| -- | -- | 372| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_ERR_INVALID_PARAM**: An input parameter is invalid.<br>**NCP_ERR_NOT_SUPPORTED**: The device does not support the creation of native child processes.<br>**NCP_ERR_ALREADY_IN_CHILD**: A process cannot be created in a child process.<br>**NCP_ERR_MAX_CHILD_PROCESSES_REACHED**: The maximum number of native child processes has been reached.<br>For details about the error codes, see **Ability_NativeChildProcess_ErrCode**.| 373 374### OH_Ability_GetCurrentChildProcessArgs() 375 376``` 377NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs() 378``` 379 380**Description** 381 382Used by a child process, after being started by calling [OH_Ability_StartNativeChildProcess](#oh_ability_startnativechildprocess), to obtain the startup parameter [NativeChildProcess_Args](capi-nativechildprocess-args.md) from any .so file or child thread. 383 384> **NOTE** 385> 386> Currently, only 2-in-1 devices and tablets are supported. 387 388**Since**: 17 389 390**Returns** 391 392| Type | Description| 393|------------------------------| -- | 394| [NativeChildProcess_Args](capi-nativechildprocess-args.md)* | Pointer to the startup parameters of the child process.| 395 396### OH_Ability_OnNativeChildProcessExit() 397 398``` 399typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal) 400``` 401 402**Description** 403 404Defines a callback to listen for child process exit. 405 406**Since**: 20 407 408**Parameters** 409 410| Name| Description| 411| -- | -- | 412| int32_t pid | Pointer to the ID of the child process.| 413| int32_t signal | Signal for child process exit.| 414 415**See** 416 417[OH_Ability_RegisterNativeChildProcessExitCallback](#oh_ability_registernativechildprocessexitcallback) 418 419[OH_Ability_UnregisterNativeChildProcessExitCallback](#oh_ability_unregisternativechildprocessexitcallback) 420 421### OH_Ability_RegisterNativeChildProcessExitCallback() 422 423``` 424Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit) 425``` 426 427**Description** 428 429Registers a callback to listen for child process exit. When a child process started by calling [OH_Ability_StartNativeChildProcess](#oh_ability_startnativechildprocess) or [startNativeChildProcess in @ohos.app.ability.childProcessManager](js-apis-app-ability-childProcessManager.md#childprocessmanagerstartnativechildprocess13) 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. 430 431The parameter must implement the entry function [OH_Ability_OnNativeChildProcessExit](#oh_ability_onnativechildprocessexit). For details, see [Registering the Native Child Process Exit Callback Function](../../application-models/capi-nativechildprocess-exit-info.md). 432 433**Since**: 20 434 435**Parameters** 436 437| Name| Description| 438| -- | -- | 439| [OH_Ability_OnNativeChildProcessExit](capi-native-child-process-h.md#oh_ability_onnativechildprocessexit) onProcessExit | Entry point of the callback function to be called when the child process exits. The value cannot be nullptr.| 440 441**Returns** 442 443| Type| Description| 444| -- | -- | 445| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_ERR_INVALID_PARAM**: An input parameter is invalid.<br>**NCP_ERR_INTERNAL**: An internal error occurs.<br>For details, see **Ability_NativeChildProcess_ErrCode**.| 446 447### OH_Ability_UnregisterNativeChildProcessExitCallback() 448 449``` 450Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback(OH_Ability_OnNativeChildProcessExit onProcessExit) 451``` 452 453**Description** 454 455Unregisters the callback used to listen for child process exit. 456 457The parameter must implement the entry function [OH_Ability_OnNativeChildProcessExit](#oh_ability_onnativechildprocessexit). For details, see [Registering the Native Child Process Exit Callback Function](../../application-models/capi-nativechildprocess-exit-info.md). 458 459**Since**: 20 460 461 462**Parameters** 463 464| Name| Description| 465| -- | -- | 466| [OH_Ability_OnNativeChildProcessExit](capi-native-child-process-h.md#oh_ability_onnativechildprocessexit) onProcessExit | Entry point of the callback function to be called when the child process exits. The value cannot be nullptr.| 467 468**Returns** 469 470| Type| Description| 471| -- | -- | 472| [Ability_NativeChildProcess_ErrCode](capi-native-child-process-h.md#ability_nativechildprocess_errcode) | **NCP_NO_ERROR**: The call is successful.<br>**NCP_ERR_INVALID_PARAM**: An input parameter is invalid.<br>**NCP_ERR_INTERNAL**: An internal error occurs.<br>**NCP_ERR_CALLBACK_NOT_EXIST**: The callback function is not found.<br>For details, see **Ability_NativeChildProcess_ErrCode**.| 473