1# ChildProcess 2 3 4## Overview 5 6The 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_fd) | 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| typedef struct [NativeChildProcess_Options](#nativechildprocess_options) | Defines a struct for the child process options.| 34| typedef struct [Ability_ChildProcessConfigs](#ability_childprocessconfigs) | Defines the configuration for starting a child process.| 35| typedef void(\* [OH_Ability_OnNativeChildProcessExit](#oh_ability_onnativechildprocessexit)) (int32_t pid, int32_t signal) | Defines the callback function for detecting abnormal exit of a native child process.| 36 37### Enums 38 39| Name | Description | 40| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | 41| [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> NCP_ERR_CALLBACK_NOT_EXIST = 16010009<br>} | Enumerates the error codes used by the native child process module.| 42 43 44### Functions 45 46| Name | Description | 47| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | 48| 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 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.| 49| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_StartNativeChildProcess](#oh_ability_startnativechildprocess) (const char\* entry, [NativeChildProcess_Args](#nativechildprocess_args) args, [NativeChildProcess_Options](#nativechildprocess_options) options, int32_t *pid) | Starts a child process and loads the specified library file.| 50| [Ability_ChildProcessConfigs](#ability_childprocessconfigs)* [OH_Ability_CreateChildProcessConfigs](#oh_ability_createchildprocessconfigs) () | Creates a child process configuration object.| 51| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_DestroyChildProcessConfigs](#oh_ability_destroychildprocessconfigs) ([Ability_ChildProcessConfigs](#ability_childprocessconfigs)\* configs) | Destroys a child process configuration object and releases the memory.| 52| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_ChildProcessConfigs_SetIsolationMode](#oh_ability_childprocessconfigs_setisolationmode) ([Ability_ChildProcessConfigs](#ability_childprocessconfigs)\* configs, [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode) isolationMode) | Sets the sharing mode of the data sandbox and network environment for a child process configuration object. This setting takes effect only when [OH_Ability_StartNativeChildProcessWithConfigs](#oh_ability_startnativechildprocesswithconfigs) is called.| 53| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_ChildProcessConfigs_SetProcessName](#oh_ability_childprocessconfigs_setprocessname) ([Ability_ChildProcessConfigs](#ability_childprocessconfigs)\* configs, const char\* processName) | Sets the process name in a child process configuration object.| 54| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_CreateNativeChildProcessWithConfigs](#oh_ability_createnativechildprocesswithconfigs) (const char\* libName, [Ability_ChildProcessConfigs](#ability_childprocessconfigs)\* configs, [OH_Ability_OnNativeChildProcessStarted](#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.| 55| [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) [OH_Ability_StartNativeChildProcessWithConfigs](#oh_ability_startnativechildprocesswithconfigs) (const char\* entry, [NativeChildProcess_Args](#nativechildprocess_args) args, [Ability_ChildProcessConfigs](#ability_childprocessconfigs)\* configs, int32_t\* pid) | Starts a child process based on a child process configuration object and loads the specified library file.| 56 57> **NOTE** 58> 59> This function is valid only for 2-in-1 devices. 60> 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. 61 62## Type Description 63### OH_Ability_OnNativeChildProcessStarted 64 65``` 66typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) 67``` 68 69**Description** 70 71Defines a callback function for notifying the child process startup result. 72 73**Since**: 12 74 75**Parameters** 76 77| Name | Description | 78| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 79| errCode | NCP_NO_ERROR - The child process is created successfully.<br>NCP_ERR_LIB_LOADING_FAILED - Loading the DLL file fails or the necessary export function is not implemented in the DLL.<br>NCP_ERR_CONNECTION_FAILED - The OnConnect method implemented in the DLL does not return a valid IPC stub pointer.<br>For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode).| 80| 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. | 81 82**See** 83 84[OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess) 85 86[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) 87 88### OH_Ability_OnNativeChildProcessExit 89 90``` 91typedef void (*OH_Ability_OnNativeChildProcessExit)(int32_t pid, int32_t signal) 92``` 93 94**Description** 95 96Defines the callback function for detecting abnormal exit of a native child process. 97 98**Since**: 20 99 100**Parameters** 101 102| Name | Description | 103| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 104| pid | PID of the child process.| 105| signal | Signal for abnormal exit of the child process. | 106 107**See** 108 109[OH_Ability_RegisterNativeChildProcessExitCallback](#oh_ability_registernativechildprocessexitcallback) 110 111[OH_Ability_UnregisterNativeChildProcessExitCallback](#oh_ability_unregisternativechildprocessexitcallback) 112 113### NativeChildProcess_Fd 114 115``` 116typedef struct NativeChildProcess_Fd { 117 char* fdName; 118 int32_t fd; 119 struct NativeChildProcess_Fd* next; 120} NativeChildProcess_Fd; 121``` 122 123**Description** 124 125Defines a struct for the file descriptor of a child process. 126 127**Since**: 13 128 129**Parameters** 130 131| Name | Description| 132| ----------- | ------------- | 133| fdName | Pointer to the keyword of the file descriptor. A maximum of 20 characters are allowed.| 134| fd | File descriptor handle.| 135| next | Pointer to the next file descriptor.| 136 137### NativeChildProcess_FdList 138 139``` 140typedef struct NativeChildProcess_FdList { 141 struct NativeChildProcess_Fd* head; 142} NativeChildProcess_FdList; 143``` 144 145**Description** 146 147Defines a struct for the linked list of file descriptors of a child process. A maximum of 16 file descriptors are supported. 148 149**Since**: 13 150 151**Parameters** 152 153| Name | Description| 154| ----------- | ------------- | 155| head | First file descriptor record in the linked list. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).| 156 157### NativeChildProcess_Args 158 159``` 160typedef struct NativeChildProcess_Args { 161 char* entryParams; 162 struct NativeChildProcess_FdList fdList; 163} NativeChildProcess_Args; 164``` 165 166**Description** 167 168Defines a struct for the arguments used for starting a child process. 169 170**Since**: 13 171 172**Parameters** 173 174| Name | Description| 175| ----------- | ------------- | 176| entryParams | Pointer to the entry parameters. The size cannot exceed 150 KB.| 177| fdList | Linked list of File descriptors. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).| 178 179### NativeChildProcess_Options 180 181``` 182typedef struct NativeChildProcess_Options { 183 NativeChildProcess_IsolationMode isolationMode; 184 int64_t reserved; 185} NativeChildProcess_Options; 186``` 187 188**Description** 189 190Defines a struct for the child process options. 191 192**Since**: 13 193 194**Parameters** 195 196| Name | Description| 197| ----------- | ------------- | 198| isolationMode | Process isolation mode. For details, see [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode).| 199| reserved | Reserved field.| 200 201### Ability_ChildProcessConfigs 202 203**Description** 204 205Describes the configuration information about a child process, including the child process name and the sharing mode of the data sandbox and network environment. 206 207**Since**: 20 208 209## Enum Description 210 211### Ability_NativeChildProcess_ErrCode 212 213``` 214enum Ability_NativeChildProcess_ErrCode 215``` 216 217**Description** 218 219Enumerates the error codes used by the native child process module. 220 221**Since**: 12 222 223| Value | Description | 224| ----------------------------------- | ----------------------------------------------- | 225| NCP_NO_ERROR | Operation successful. | 226| NCP_ERR_INVALID_PARAM | Invalid parameter. | 227| NCP_ERR_NOT_SUPPORTED | Creating a native child process is not supported. | 228| NCP_ERR_INTERNAL | Internal error. | 229| 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.| 230| NCP_ERR_TIMEOUT | Starting the native child process times out. | 231| NCP_ERR_SERVICE_ERROR | Server error. | 232| NCP_ERR_MULTI_PROCESS_DISABLED | The multi-process mode is disabled. A child process cannot be started. | 233| NCP_ERR_ALREADY_IN_CHILD | A process cannot be created in a child process. | 234| NCP_ERR_MAX_CHILD_PROCESSES_REACHED | The number of native child processes reaches the maximum. | 235| NCP_ERR_LIB_LOADING_FAILED | The child process fails to load the DLL because the file does not exist or the corresponding method is not implemented or exported. | 236| NCP_ERR_CONNECTION_FAILED | The child process fails to call the OnConnect method of the DLL. An invalid IPC object pointer may be returned. | 237| NCP_ERR_CALLBACK_NOT_EXIST | The child process calls the **OH_Ability_UnregisterNativeChildProcessExitCallback** function to unregister a callback function, but the callback function is not found. | 238 239### NativeChildProcess_IsolationMode 240 241``` 242enum NativeChildProcess_IsolationMode 243``` 244 245**Description** 246 247Enumerates the sharing modes available for the data sandbox and network environment of a native child process. 248 249**Since**: 13 250 251| Value | Description | 252| ----------------------------------- | ----------------------------------------------- | 253| NCP_ISOLATION_MODE_NORMAL | The child process shares the same data sandbox and network environment as the main process.| 254| NCP_ISOLATION_MODE_ISOLATED | The child process has its own separate data sandbox and network environment, isolated from the main process.| 255 256## Function Description 257 258### OH_Ability_CreateNativeChildProcess 259 260``` 261int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted) 262``` 263 264**Description** 265 266Creates a child process, loads the specified 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. 267 268The DLL specified must implement and export the following functions: 269 270 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 271 2. void NativeChildProcess_MainProc() 272 273The processing logic sequence is shown in the following pseudocode: 274 275 Parent process: 276 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback) 277 278 Child process: 279 2. dlopen(libName) 280 3. dlsym("NativeChildProcess_OnConnect") 281 4. dlsym("NativeChildProcess_MainProc") 282 5. ipcRemote = NativeChildProcess_OnConnect() 283 6. NativeChildProcess_MainProc() 284 285 Parent process: 286 7. onProcessStartedCallback(ipcRemote, errCode) 287 288 Child process: 289 8. The child process exits after the NativeChildProcess_MainProc() function is returned. 290 291> **NOTE** 292> 293> This function is valid only for 2-in-1 devices. 294> 295> 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. 296 297**Since**: 12 298 299**Parameters** 300 301| Name | Description | 302| ------------------------ | --------------------------------------------------------------------------------------------------------------- | 303| libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr. | 304| onProcessStarted | 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).| 305 306 307**Returns** 308 309**NCP_NO_ERROR**. If the operation fails, an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) is returned. 310 311### OH_Ability_StartNativeChildProcess 312 313``` 314Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( 315 const char* entry, NativeChildProcess_Args args, 316 NativeChildProcess_Options options, int32_t *pid) 317``` 318 319**Description** 320 321Starts a native child process, loads the specified DLL 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. 322 323The specified DLL 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). 324 325> **NOTE** 326> 327> This function is valid only for 2-in-1 devices and tablets. 328 329**Since**: 13 330 331**Parameters** 332 333| Name | Description| 334| ---------------------- | ---------------- | 335| entry | The symbol and entry function of the DLL called in the child process are separated by a colon (:), for example, **libentry.so:Main**. The value cannot be nullptr.| 336| args | Arguments passed to the child process. For details, see [NativeChildProcess_Args](#nativechildprocess_args).| 337| options | Startup configuration options of the child process. For details, see [NativeChildProcess_Options](#nativechildprocess_options).| 338| pid | ID of the child process to start.| 339 340 341**Returns** 342 343**NCP_NO_ERROR**. If the operation fails, an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) is returned. 344 345### OH_Ability_GetCurrentChildProcessArgs 346 347``` 348NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs(); 349``` 350 351**Description** 352 353Used by a child process, after being started by calling [OH_Ability_StartNativeChildProcess](#oh_ability_startnativechildprocess), to obtain the startup parameter [NativeChildProcess_Args](#nativechildprocess_args) from any .so file or child thread. 354 355> **NOTE** 356> 357> This function is valid only for 2-in-1 devices and tablets. 358 359**Since**: 17 360 361**Returns** 362 363Pointer to a [NativeChildProcess_Args](#nativechildprocess_args) object. If the operation fails, nullptr is returned. 364 365### OH_Ability_RegisterNativeChildProcessExitCallback 366 367``` 368Ability_NativeChildProcess_ErrCode OH_Ability_RegisterNativeChildProcessExitCallback( 369 OH_Ability_OnNativeChildProcessExit onProcessExit) 370``` 371 372**Description** 373 374Registers a callback function for detecting abnormal exit of a native child process. 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. 375 376The 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). 377 378**Since**: 20 379 380**Parameters** 381 382| Name | Description| 383| ---------------------- | ---------------- | 384| onProcessExit | Address of the callback function to be called when the child process exits. The value cannot be nullptr.| 385 386**Returns** 387 388**NCP_NO_ERROR**. If the operation fails, an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) is returned. 389 390### OH_Ability_UnregisterNativeChildProcessExitCallback 391 392``` 393Ability_NativeChildProcess_ErrCode OH_Ability_UnregisterNativeChildProcessExitCallback( 394 OH_Ability_OnNativeChildProcessExit onProcessExit) 395``` 396 397**Description** 398 399Unregisters the callback function used for detecting abnormal exit of a native child process. 400 401The 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). 402 403**Since**: 20 404 405**Parameters** 406 407| Name | Description| 408| ---------------------- | ---------------- | 409| onProcessExit | Address of the callback function to be called when the child process exits. The value cannot be nullptr.| 410 411 412**Returns** 413 414**NCP_NO_ERROR**. If the operation fails, an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) is returned. 415 416### OH_Ability_CreateChildProcessConfigs 417 418``` 419Ability_ChildProcessConfigs* OH_Ability_CreateChildProcessConfigs(); 420``` 421 422**Description** 423 424Creates a child process configuration object. When this object is no longer needed, call [OH_Ability_DestroyChildProcessConfigs](#oh_ability_destroychildprocessconfigs) to destroy the object to prevent memory leakage. 425 426**Since**: 20 427 428**Returns** 429 430Pointer to the [Ability_ChildProcessConfigs](#ability_childprocessconfigs) object: The operation is successful. 431nullptr: An internal error occurs or memory allocation fails. 432 433### OH_Ability_DestroyChildProcessConfigs 434 435``` 436Ability_NativeChildProcess_ErrCode OH_Ability_DestroyChildProcessConfigs(Ability_ChildProcessConfigs* configs); 437``` 438 439**Description** 440 441Destroys a child process configuration object and releases its memory. After this function is called, do not use the destroyed object. 442 443**Since**: 20 444 445**Parameters** 446 447| Name | Description| 448| ---------------------- | ---------------- | 449| configs | Pointer to a child process configuration object. For details, see [Ability_ChildProcessConfigs](#ability_childprocessconfigs). After this function is called, the object pointer becomes invalid. Do not use the pointer. nullptr is allowed, which does not trigger any operation.| 450 451**Returns** 452 453**NCP_NO_ERROR**: The operation is successful. 454 455**NCP_ERR_INVALID_PARAM**: An input parameter is nullptr. 456 457For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode). 458 459 460### OH_Ability_ChildProcessConfigs_SetIsolationMode 461 462``` 463Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetIsolationMode( 464 Ability_ChildProcessConfigs* configs, NativeChildProcess_IsolationMode isolationMode); 465``` 466 467**Description** 468 469Sets the sharing mode of the data sandbox and network environment for a child process configuration object. This setting takes effect only when [OH_Ability_StartNativeChildProcessWithConfigs](#oh_ability_startnativechildprocesswithconfigs) is called. 470 471**Since**: 20 472 473**Parameters** 474 475| Name | Description| 476| ---------------------- | ---------------- | 477| configs | Pointer to a child process configuration object. For details, see [Ability_ChildProcessConfigs](#ability_childprocessconfigs).| 478| isolationMode | Sharing mode of the data sandbox and network environment. For details, see [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode).| 479 480**Returns** 481 482**NCP_NO_ERROR**: The operation is successful. 483 484**NCP_ERR_INVALID_PARAM**: The parameter **configs** is nullptr. 485 486For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode). 487 488### OH_Ability_ChildProcessConfigs_SetProcessName 489 490``` 491Ability_NativeChildProcess_ErrCode OH_Ability_ChildProcessConfigs_SetProcessName(Ability_ChildProcessConfigs* configs, const char* processName); 492``` 493 494**Description** 495 496Sets the process name in a child process configuration object. 497 498**Since**: 20 499 500**Parameters** 501 502| Name | Description| 503| ---------------------- | ---------------- | 504| configs | Pointer to a child process configuration object. For details, see [Ability_ChildProcessConfigs](#ability_childprocessconfigs). The pointer cannot be null.| 505| processName | Pointer to the process name, which must be a non-empty string containing a maximum of 64 characters. The string can contain only letters, digits, and underscores (_). The final process name is in the format of {bundleName}:{processName}.| 506 507**Returns** 508 509**NCP_NO_ERROR**: The operation is successful. 510 511**NCP_ERR_INVALID_PARAM**: The input parameter **configs** is nullptr, or **processName** contains characters other than letters, digits, and underscores (_). 512 513For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode). 514 515 516### OH_Ability_CreateNativeChildProcessWithConfigs 517 518``` 519 Ability_NativeChildProcess_ErrCode OH_Ability_CreateNativeChildProcessWithConfigs(const char* libName, 520 Ability_ChildProcessConfigs* configs, OH_Ability_OnNativeChildProcessStarted onProcessStarted); 521``` 522 523**Description** 524 525Creates 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. 526 527The DLL specified must implement and export the following functions: 528 529 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 530 2. void NativeChildProcess_MainProc() 531 532The processing logic sequence is shown in the following pseudocode: 533 534 Parent process: 535 1. OH_Ability_CreateNativeChildProcessWithConfigs(libName, configs, onProcessStartedCallback) 536 537 Child process: 538 2. dlopen(libName) 539 3. dlsym("NativeChildProcess_OnConnect") 540 4. dlsym("NativeChildProcess_MainProc") 541 5. ipcRemote = NativeChildProcess_OnConnect() 542 6. NativeChildProcess_MainProc() 543 544 Parent process: 545 7. onProcessStartedCallback(ipcRemote, errCode) 546 547 Child process: 548 8. The child process exits after the NativeChildProcess_MainProc() function is returned. 549 550> **NOTE** 551> 552> This function is valid only for 2-in-1 devices and tablets. 553 554**Since**: 20 555 556**Parameters** 557 558| Name | Description| 559| ---------------------- | ---------------- | 560| libName | Pointer to the name of the DLL file loaded in the child process. The value cannot be nullptr.| 561| configs | Pointer to the child process configuration object. The value cannot be nullptr. For details, see [Ability_ChildProcessConfigs](#ability_childprocessconfigs).| 562| onProcessStarted | 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).| 563 564**Returns** 565 566**NCP_NO_ERROR**: The operation is successful. 567 568**NCP_ERR_INVALID_PARAM**: An input parameter is invalid. 569 570**NCP_ERR_NOT_SUPPORTED**: The device does not support the creation of native child processes. 571 572**NCP_ERR_MULTI_PROCESS_DISABLED**: Multi-process mode is disabled on the device, and the child process cannot be started. 573 574**NCP_ERR_ALREADY_IN_CHILD**: A process cannot be created in a child process. 575 576**NCP_ERR_MAX_CHILD_PROCESSES_REACHED**: The maximum number of native child processes has been reached. 577 578For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode). 579 580### OH_Ability_StartNativeChildProcessWithConfigs 581 582``` 583 Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcessWithConfigs( 584 const char* entry, NativeChildProcess_Args args, Ability_ChildProcessConfigs* configs, int32_t *pid); 585``` 586 587**Description** 588 589Starts 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. 590 591The specified DLL file must implement the entry function with the parameter [NativeChildProcess_Args](#nativechildprocess_args) and export the entry function. For details, see [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). The following is an example: 592 593 1. void Main(NativeChildProcess_Args args); 594 595The processing logic sequence is shown in the following pseudocode: 596 597 Parent process: 598 1. OH_Ability_StartNativeChildProcessWithConfigs(entryPoint, args, configs, &pid) 599 600 Child process: 601 2. dlopen(libName) 602 3. dlsym("Main") 603 4. Main(args) 604 5. The child process exits after the Main(args) function returns. 605 606> **NOTE** 607> 608> This function is valid only for 2-in-1 devices and tablets. 609 610**Since**: 20 611 612**Parameters** 613 614| Name | Description| 615| ---------------------- | ---------------- | 616| 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.| 617| args | Arguments passed to the child process. For details, see [NativeChildProcess_Args](#nativechildprocess_args).| 618| configs | Pointer to a child process configuration object. For details, see [Ability_ChildProcessConfigs](#ability_childprocessconfigs).| 619| pid | Pointer to the ID of the child process to start.| 620 621**Returns** 622 623**NCP_NO_ERROR**: The operation is successful. 624 625**NCP_ERR_INVALID_PARAM**: An input parameter is invalid. 626 627**NCP_ERR_NOT_SUPPORTED**: The device does not support the creation of native child processes. 628 629**NCP_ERR_ALREADY_IN_CHILD**: A process cannot be created in a child process. 630 631**NCP_ERR_MAX_CHILD_PROCESSES_REACHED**: The maximum number of native child processes has been reached. 632 633For details about the error codes, see [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode). 634