1# ChildProcess 2 3 4## Overview 5 6The ChildProcess module provides APIs to manage child processes. You can call the APIs to create a native child process and establish an IPC channel between the parent and child processes to implement multi-process application development. 7 8The created child process does not support the UI or the calling of context-related APIs. A maximum of 512 child processes can be started through this module and [childProcessManager](js-apis-app-ability-childProcessManager.md) (non-SELF_FORK mode). 9 10**System capability**: SystemCapability.Ability.AbilityRuntime.Core 11 12**Since**: 12 13 14 15## Summary 16 17 18### Files 19 20| Name | Description | 21| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | 22| [native_child_process.h](native__child__process_8h.md) | Declares the APIs used to create a native child process and establish an IPC channel between the parent and child processes.<br>File to include: <AbilityKit/native_child_process.h><br>Library: libchild_process.so<br>| 23 24### Types 25 26| Name | Description | 27| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | 28| typedef enum Ability_NativeChildProcess_ErrCode [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) | Defines an enum for the error codes used by the native child process module.| 29| typedef void(\* [OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted)) (int errCode, OHIPCRemoteProxy \*remoteProxy) | Defines a callback function for notifying the child process startup result.| 30| typedef struct [NativeChildProcess_Fd](#nativechildprocess_fdlist) | Defines a struct for the file descriptor of a child process.| 31| typedef struct [NativeChildProcess_FdList](#nativechildprocess_fdlist) | Defines a struct for the linked list of file descriptors of a child process.| 32| typedef struct [NativeChildProcess_Args](#nativechildprocess_args) | Defines a struct for the arguments used for starting a child process.| 33 34 35### Enums 36 37| Name | Description | 38| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | 39| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) {<br> NCP_NO_ERROR = 0,<br> NCP_ERR_INVALID_PARAM = 401,<br> NCP_ERR_NOT_SUPPORTED = 801,<br> NCP_ERR_INTERNAL = 16000050,<br> NCP_ERR_BUSY = 16010001,<br> NCP_ERR_TIMEOUT = 16010002,<br> NCP_ERR_SERVICE_ERROR = 16010003,<br> NCP_ERR_MULTI_PROCESS_DISABLED = 16010004,<br> NCP_ERR_ALREADY_IN_CHILD = 16010005,<br> NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006,<br> NCP_ERR_LIB_LOADING_FAILED = 16010007,<br> NCP_ERR_CONNECTION_FAILED = 16010008<br>} | Enumerates the error codes used by the native child process module.| 40 41 42### Functions 43 44| Name | Description | 45| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | 46| int [OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess) (const char \*libName, [OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted) onProcessStarted) | 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.| 47 48> **NOTE** 49> 50> This function is valid only for 2-in-1 devices. 51> 52> Since 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. 53 54## Type Description 55### OH_Ability_OnNativeChildProcessStarted 56 57``` 58typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) 59``` 60 61**Description** 62 63Defines a callback function for notifying the child process startup result. 64 65**Since**: 12 66 67**Parameters** 68 69| Name | Description | 70| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 71| errCode | NCP_NO_ERROR - The child process is created successfully.<br>NCP_ERR_LIB_LOADING_FAILED - Loading the dynamic library file fails or the necessary export function is not implemented in the dynamic library.<br>NCP_ERR_CONNECTION_FAILED - The OnConnect method implemented in the dynamic library does not return a valid IPC stub pointer.<br>For details, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode).| 72| 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](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) when it is no longer needed. | 73 74**See** 75 76[OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess) 77 78[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) 79 80### NativeChildProcess_Fd 81 82``` 83typedef struct NativeChildProcess_Fd { 84 char* fdName; 85 int32_t fd; 86 struct NativeChildProcess_Fd* next; 87} NativeChildProcess_Fd; 88``` 89 90**Description** 91 92Defines a struct for the file descriptor of a child process. 93 94**Since**: 13 95 96**Parameters** 97 98| Name | Description| 99| ----------- | ------------- | 100| fdName | Pointer to the keyword of the file descriptor. A maximum of 20 characters are allowed.| 101| fd | File descriptor handle.| 102| next | Pointer to the next file descriptor.| 103 104### NativeChildProcess_FdList 105 106``` 107typedef struct NativeChildProcess_FdList { 108 struct NativeChildProcess_Fd* head; 109} NativeChildProcess_FdList; 110``` 111 112**Description** 113 114Defines a struct for the linked list of file descriptors of a child process. A maximum of 16 file descriptors are supported. 115 116**Since**: 13 117 118**Parameters** 119 120| Name | Description| 121| ----------- | ------------- | 122| head | First file descriptor record in the linked list. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).| 123 124### NativeChildProcess_Args 125 126``` 127typedef struct NativeChildProcess_Args { 128 char* entryParams; 129 struct NativeChildProcess_FdList fdList; 130} NativeChildProcess_Args; 131``` 132 133**Description** 134 135Defines a struct for the arguments used for starting a child process. 136 137**Since**: 13 138 139**Parameters** 140 141| Name | Description| 142| ----------- | ------------- | 143| entryParams | Pointer to the entry parameters. The size cannot exceed 150 KB.| 144| fdList | Linked list of File descriptors. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).| 145 146### NativeChildProcess_Options 147 148``` 149typedef struct NativeChildProcess_Options { 150 NativeChildProcess_IsolationMode isolationMode; 151 int64_t reserved; 152} NativeChildProcess_Options; 153``` 154 155**Description** 156 157Defines a struct for the child process options. 158 159**Since**: 13 160 161**Parameters** 162 163| Name | Description| 164| ----------- | ------------- | 165| isolationMode | Process isolation mode. For details, see [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode).| 166| reserved | Reserved field.| 167 168## Enum Description 169 170### Ability_NativeChildProcess_ErrCode 171 172``` 173enum Ability_NativeChildProcess_ErrCode 174``` 175 176**Description** 177 178Enumerates the error codes used by the native child process module. 179 180**Since**: 12 181 182| Value | Description | 183| ----------------------------------- | ----------------------------------------------- | 184| NCP_NO_ERROR | Operation successful. | 185| NCP_ERR_INVALID_PARAM | Invalid parameter. | 186| NCP_ERR_NOT_SUPPORTED | Creating a native child process is not supported. | 187| NCP_ERR_INTERNAL | Internal error. | 188| NCP_ERR_BUSY | 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.| 189| NCP_ERR_TIMEOUT | Starting the native child process times out. | 190| NCP_ERR_SERVICE_ERROR | Server error. | 191| NCP_ERR_MULTI_PROCESS_DISABLED | The multi-process mode is disabled. A child process cannot be started. | 192| NCP_ERR_ALREADY_IN_CHILD | A process cannot be created in a child process. | 193| NCP_ERR_MAX_CHILD_PROCESSES_REACHED | The number of native child processes reaches the maximum. | 194| NCP_ERR_LIB_LOADING_FAILED | The child process fails to load the dynamic library because the file does not exist or the corresponding method is not implemented or exported. | 195| NCP_ERR_CONNECTION_FAILED | The child process fails to call the OnConnect method of the dynamic library. An invalid IPC object pointer may be returned. | 196 197### NativeChildProcess_IsolationMode 198 199``` 200enum NativeChildProcess_IsolationMode 201``` 202 203**Description** 204 205Enumerates the isolation modes of a child process. 206 207**Since**: 13 208 209| Value | Description | 210| ----------------------------------- | ----------------------------------------------- | 211| NCP_ISOLATION_MODE_NORMAL | Normal mode. The child process shares the data sandbox and network environment with the main process.| 212| NCP_ISOLATION_MODE_ISOLATED | Isolated mode. The child process does not share the data sandbox and network environment with the main process.| 213 214## Function Description 215 216### OH_Ability_CreateNativeChildProcess 217 218``` 219int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted) 220``` 221 222**Description** 223 224Creates 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. 225 226The dynamic library specified must implement and export the following functions: 227 228 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 229 2. void NativeChildProcess_MainProc() 230 231The processing logic sequence is shown in the following pseudocode: 232 233 Parent process: 234 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback) 235 236 Child process: 237 2. dlopen(libName) 238 3. dlsym("NativeChildProcess_OnConnect") 239 4. dlsym("NativeChildProcess_MainProc") 240 5. ipcRemote = NativeChildProcess_OnConnect() 241 6. NativeChildProcess_MainProc() 242 243 Parent process: 244 7. onProcessStartedCallback(ipcRemote, errCode) 245 246 Child process: 247 8. The child process exits after the NativeChildProcess_MainProc() function is returned. 248 249> **NOTE** 250> 251> This function is valid only for 2-in-1 devices. 252> 253> Since 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. 254 255**Since**: 12 256 257**Parameters** 258 259| Name | Description | 260| ------------------------ | --------------------------------------------------------------------------------------------------------------- | 261| libName | Pointer to the name of the dynamic library file loaded in the child process. The value cannot be nullptr. | 262| onProcessStartedCallback | Pointer to the callback function for notifying the child process startup result. The value cannot be nullptr. For details, see [OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted).| 263 264 265**Returns** 266 267Returns **NCP_NO_ERROR** if the operation is successful; returns an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) otherwise. 268 269### OH_Ability_StartNativeChildProcess 270 271``` 272Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( 273 const char* entry, NativeChildProcess_Args args, 274 NativeChildProcess_Options options, int32_t *pid) 275``` 276 277**Description** 278 279Starts a native child process, loads the specified dynamic library file, and calls the entry function. Arguments can be passed to the child process. The ArkTS basic runtime environment cannot be created in the child process. 280 281The specified dynamic library must implement and export the entry parameters of [NativeChildProcess_Args](#nativechildprocess_args). For details, see [Native Child Process Development (C/C++) - Creating a Child Process That Supports Pass-by-Parameter](../../application-models/capi_nativechildprocess_development_guideline.md#creating-a-child-process-that-supports-pass-by-parameter). 282 283> **NOTE** 284> 285> This function is valid only for 2-in-1 devices and tablets. 286 287**Since**: 13 288 289**Parameters** 290 291| Name | Description| 292| ---------------------- | ---------------- | 293| entry | The symbol and entry function of the dynamic library called in the child process are separated by a colon (:), for example, **libentry.so:Main**. The value cannot be a null pointer.| 294| args | Arguments passed to the child process. For details, see [NativeChildProcess_Args](#nativechildprocess_args).| 295| options | Startup configuration options of the child process. For details, see [NativeChildProcess_Options](#nativechildprocess_options).| 296| pid | ID of the child process to start.| 297 298 299**Returns** 300 301Returns **NCP_NO_ERROR** if the operation is successful; returns an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) otherwise. 302