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> Currently, only 2-in-1 devices are supported, and only one native child process can be started for a process.
51
52## Type Description
53### OH_Ability_OnNativeChildProcessStarted
54
55```
56typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy)
57```
58
59**Description**
60
61Defines a callback function for notifying the child process startup result.
62
63**Since**: 12
64
65**Parameters**
66
67| Name         | Description                                                                                                                                                                                                                                 |
68| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69| 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).|
70| 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.                                                                                      |
71
72**See**
73
74[OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess)
75
76[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy)
77
78### NativeChildProcess_Fd
79
80```
81typedef struct NativeChildProcess_Fd {
82    char* fdName;
83    int32_t fd;
84    struct NativeChildProcess_Fd* next;
85} NativeChildProcess_Fd;
86```
87
88**Description**
89
90Defines a struct for the file descriptor of a child process.
91
92**Since**: 13
93
94**Parameters**
95
96| Name         | Description|
97| ----------- | ------------- |
98| fdName     | Pointer to the keyword of the file descriptor. A maximum of 20 characters are allowed.|
99| fd | File descriptor handle.|
100| next | Pointer to the next file descriptor.|
101
102### NativeChildProcess_FdList
103
104```
105typedef struct NativeChildProcess_FdList {
106    struct NativeChildProcess_Fd* head;
107} NativeChildProcess_FdList;
108```
109
110**Description**
111
112Defines a struct for the linked list of file descriptors of a child process. A maximum of 16 file descriptors are supported.
113
114**Since**: 13
115
116**Parameters**
117
118| Name         | Description|
119| ----------- | ------------- |
120| head     | First file descriptor record in the linked list. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).|
121
122### NativeChildProcess_Args
123
124```
125typedef struct NativeChildProcess_Args {
126    char* entryParams;
127    struct NativeChildProcess_FdList fdList;
128} NativeChildProcess_Args;
129```
130
131**Description**
132
133Defines a struct for the arguments used for starting a child process.
134
135**Since**: 13
136
137**Parameters**
138
139| Name         | Description|
140| ----------- | ------------- |
141| entryParams     | Pointer to the entry parameters. The size cannot exceed 150 KB.|
142| fdList | Linked list of File descriptors. For details, see [NativeChildProcess_FdList](#nativechildprocess_fdlist).|
143
144### NativeChildProcess_Options
145
146```
147typedef struct NativeChildProcess_Options {
148    NativeChildProcess_IsolationMode isolationMode;
149    int64_t reserved;
150} NativeChildProcess_Options;
151```
152
153**Description**
154
155Defines a struct for the child process options.
156
157**Since**: 13
158
159**Parameters**
160
161| Name         | Description|
162| ----------- | ------------- |
163| isolationMode     | Process isolation mode. For details, see [NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode).|
164| reserved | Reserved field.|
165
166## Enum Description
167
168### Ability_NativeChildProcess_ErrCode
169
170```
171enum Ability_NativeChildProcess_ErrCode
172```
173
174**Description**
175
176Enumerates the error codes used by the native child process module.
177
178**Since**: 12
179
180| Value                                | Description                                             |
181| ----------------------------------- | ----------------------------------------------- |
182| NCP_NO_ERROR                        | Operation successful.                                          |
183| NCP_ERR_INVALID_PARAM               | Invalid parameter.                                          |
184| NCP_ERR_NOT_SUPPORTED               | Creating a native child process is not supported.                                |
185| NCP_ERR_INTERNAL                    | Internal error.                                          |
186| 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.|
187| NCP_ERR_TIMEOUT                     | Starting the native child process times out.                                 |
188| NCP_ERR_SERVICE_ERROR               | Server error.                                         |
189| NCP_ERR_MULTI_PROCESS_DISABLED      | The multi-process mode is disabled. A child process cannot be started.                             |
190| NCP_ERR_ALREADY_IN_CHILD            | A process cannot be created in a child process.                                |
191| NCP_ERR_MAX_CHILD_PROCESSES_REACHED | The number of native child processes reaches the maximum.                    |
192| 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.                 |
193| 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.        |
194
195### NativeChildProcess_IsolationMode
196
197```
198enum NativeChildProcess_IsolationMode
199```
200
201**Description**
202
203Enumerates the isolation modes of a child process.
204
205**Since**: 13
206
207| Value                                | Description                                             |
208| ----------------------------------- | ----------------------------------------------- |
209| NCP_ISOLATION_MODE_NORMAL | Normal mode. The child process shares the data sandbox and network environment with the main process.|
210| NCP_ISOLATION_MODE_ISOLATED | Isolated mode. The child process does not share the data sandbox and network environment with the main process.|
211
212## Function Description
213
214### OH_Ability_CreateNativeChildProcess
215
216```
217int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted )
218```
219
220**Description**
221
222Creates 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.
223
224The dynamic library specified must implement and export the following functions:
225
226	1. OHIPCRemoteStub* NativeChildProcess_OnConnect()
227	2. void NativeChildProcess_MainProc()
228
229The processing logic sequence is shown in the following pseudocode:
230
231	Parent process:
232	1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)
233
234	Child process:
235	2. dlopen(libName)
236	3. dlsym("NativeChildProcess_OnConnect")
237	4. dlsym("NativeChildProcess_MainProc")
238	5. ipcRemote = NativeChildProcess_OnConnect()
239	6. NativeChildProcess_MainProc()
240
241	Parent process:
242	7. onProcessStartedCallback(ipcRemote, errCode)
243
244	Child process:
245	8. The child process exits after the NativeChildProcess_MainProc() function is returned.
246
247> **NOTE**
248>
249> Currently, only 2-in-1 devices are supported, and only one native child process can be started for a process.
250
251**Since**: 12
252
253**Parameters**
254
255| Name                      | Description                                                                                                             |
256| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
257| libName                  | Pointer to the name of the dynamic library file loaded in the child process. The value cannot be nullptr.                                                                                     |
258| 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).|
259
260
261**Returns**
262
263Returns **NCP_NO_ERROR** if the operation is successful; returns an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) otherwise.
264
265### OH_Ability_StartNativeChildProcess
266
267```
268Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(
269    const char* entry, NativeChildProcess_Args args,
270    NativeChildProcess_Options options, int32_t *pid)
271```
272
273**Description**
274
275Starts 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.
276
277The 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).
278
279> **NOTE**
280>
281> This function is valid only for 2-in-1 devices and tablets.
282
283**Since**: 13
284
285**Parameters**
286
287| Name                      | Description|
288| ---------------------- | ---------------- |
289| 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.|
290| args | Arguments passed to the child process. For details, see [NativeChildProcess_Args](#nativechildprocess_args).|
291| options |  Startup configuration options of the child process. For details, see [NativeChildProcess_Options](#nativechildprocess_options).|
292| pid | ID of the child process to start.|
293
294
295**Returns**
296
297Returns **NCP_NO_ERROR** if the operation is successful; returns an error code defined in [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) otherwise.
298