1# ChildProcess 2 3 4## 概述 5 6提供子进程的管理能力，支持创建Native子进程并在父子进程间建立IPC通道，用于实现多进程应用开发。 7 8创建的子进程不支持UI界面，也不支持Context相关的接口调用。通过此模块和[childProcessManager](js-apis-app-ability-childProcessManager.md)（非SELF_FORK模式）启动的子进程总数最大为512个。 9 10**系统能力**：SystemCapability.Ability.AbilityRuntime.Core 11 12**起始版本**：12 13 14 15## 汇总 16 17 18### 文件 19 20| 名称 | 描述 | 21| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | 22| [native_child_process.h](native__child__process_8h.md) | 支持创建Native子进程，并在父子进程间建立IPC通道。<br>引用文件：<AbilityKit/native_child_process.h><br>库：libchild_process.so<br> | 23 24### 类型定义 25 26| 名称 | 描述 | 27| ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | 28| typedef enum Ability_NativeChildProcess_ErrCode [Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode) | 定义Native子进程模块错误码。 | 29| typedef void(\* [OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted)) (int errCode, OHIPCRemoteProxy \*remoteProxy) | 定义通知子进程启动结果的回调函数。 | 30| typedef struct [NativeChildProcess_Fd](#nativechildprocess_fdlist) | 定义子进程文件描述符记录。 | 31| typedef struct [NativeChildProcess_FdList](#nativechildprocess_fdlist) | 定义子进程文件描述符记录链表。 | 32| typedef struct [NativeChildProcess_Args](#nativechildprocess_args) | 定义启动子进程入参。 | 33 34 35### 枚举 36 37| 名称 | 描述 | 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>} | 定义Native子进程模块错误码。 | 40 41 42### 函数 43 44| 名称 | 描述 | 45| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | 46| int [OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess) (const char \*libName, [OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted) onProcessStarted) | 创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。 | 47 48> **说明：** 49> 50> 当前仅支持2in1设备。 51> 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。 52 53## 类型定义说明 54### OH_Ability_OnNativeChildProcessStarted 55 56``` 57typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) 58``` 59 60**描述** 61 62通知子进程启动结果的回调函数。 63 64**起始版本**：12 65 66**参数:** 67 68| 名称 | 描述 | 69| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 70| errCode | NCP_NO_ERROR - 创建子进程成功<br>NCP_ERR_LIB_LOADING_FAILED - 加载动态库文件失败或动态库中未实现必要的导出函数<br>NCP_ERR_CONNECTION_FAILED - 动态库中实现的OnConnect方法未返回有效的IPC Stub指针<br>详见[Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode)定义。 | 71| remoteProxy | 子进程的IPC对象指针，出现异常时可能为nullptr； 使用完毕后需要调用[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy)方法释放。 | 72 73**参见：** 74 75[OH_Ability_CreateNativeChildProcess](#oh_ability_createnativechildprocess) 76 77[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy) 78 79### NativeChildProcess_Fd 80 81``` 82typedef struct NativeChildProcess_Fd { 83 char* fdName; 84 int32_t fd; 85 struct NativeChildProcess_Fd* next; 86} NativeChildProcess_Fd; 87``` 88 89**描述** 90 91子进程文件描述记录。 92 93**起始版本**：13 94 95**参数:** 96 97| 名称 | 描述 | 98| ----------- | ------------- | 99| fdName | 文件描述关键字。最大长度为20字符。 | 100| fd | 文件描述符句柄。| 101| next | 下一个文件描述记录指针。 | 102 103### NativeChildProcess_FdList 104 105``` 106typedef struct NativeChildProcess_FdList { 107 struct NativeChildProcess_Fd* head; 108} NativeChildProcess_FdList; 109``` 110 111**描述** 112 113子进程文件描述记录链表。文件描述符记录个数不能超过16个。 114 115**起始版本**：13 116 117**参数:** 118 119| 名称 | 描述 | 120| ----------- | ------------- | 121| head | 子进程文件描述记录链表中的第一个记录，详见[NativeChildProcess_FdList](#nativechildprocess_fdlist)定义。 | 122 123### NativeChildProcess_Args 124 125``` 126typedef struct NativeChildProcess_Args { 127 char* entryParams; 128 struct NativeChildProcess_FdList fdList; 129} NativeChildProcess_Args; 130``` 131 132**描述** 133 134启动子进程的入参。 135 136**起始版本**：13 137 138**参数:** 139 140| 名称 | 描述 | 141| ----------- | ------------- | 142| entryParams | 入口参数，大小不能超过150KB。 | 143| fdList | 子进程文件描述记录链表，详见[NativeChildProcess_FdList](#nativechildprocess_fdlist)定义。 | 144 145### NativeChildProcess_Options 146 147``` 148typedef struct NativeChildProcess_Options { 149 NativeChildProcess_IsolationMode isolationMode; 150 int64_t reserved; 151} NativeChildProcess_Options; 152``` 153 154**描述** 155 156启动子进程的配置选项。 157 158**起始版本**：13 159 160**参数:** 161 162| 名称 | 描述 | 163| ----------- | ------------- | 164| isolationMode | 进程独立模式，详见[NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode)定义。 | 165| reserved | 保留字段。| 166 167## 枚举类型说明 168 169### Ability_NativeChildProcess_ErrCode 170 171``` 172enum Ability_NativeChildProcess_ErrCode 173``` 174 175**描述** 176 177定义Native子进程模块错误码。 178 179**起始版本**：12 180 181| 枚举值 | 描述 | 182| ----------------------------------- | ----------------------------------------------- | 183| NCP_NO_ERROR | 操作成功。 | 184| NCP_ERR_INVALID_PARAM | 无效参数。 | 185| NCP_ERR_NOT_SUPPORTED | 不支持创建Native子进程。 | 186| NCP_ERR_INTERNAL | 内部错误。 | 187| NCP_ERR_BUSY | 在Native子进程的启动过程中不能再次创建新的子进程，可以等待当前子进程启动完成后再次尝试。从API version 15开始被废弃。 | 188| NCP_ERR_TIMEOUT | 启动Native子进程超时。 | 189| NCP_ERR_SERVICE_ERROR | 服务端出错。 | 190| NCP_ERR_MULTI_PROCESS_DISABLED | 多进程模式已关闭，不允许启动子进程。 | 191| NCP_ERR_ALREADY_IN_CHILD | 不允许在子进程中再次创建进程。 | 192| NCP_ERR_MAX_CHILD_PROCESSES_REACHED | 到达最大Native子进程数量限制，不能再创建子进程。 | 193| NCP_ERR_LIB_LOADING_FAILED | 子进程加载动态库失败，文件不存在或者未实现对应的方法并导出。 | 194| NCP_ERR_CONNECTION_FAILED | 子进程调用动态库的OnConnect方法失败，可能返回了无效的IPC对象指针。 | 195 196### NativeChildProcess_IsolationMode 197 198``` 199enum NativeChildProcess_IsolationMode 200``` 201 202**描述** 203 204定义Native子进程独立模式。 205 206**起始版本**：13 207 208| 枚举值 | 描述 | 209| ----------------------------------- | ----------------------------------------------- | 210| NCP_ISOLATION_MODE_NORMAL | 普通进程独立模式，与主进程共享数据沙箱和网络环境。| 211| NCP_ISOLATION_MODE_ISOLATED | 独立沙箱进程模式，与主进程不共享数据沙箱和网络环境。 | 212 213## 函数说明 214 215### OH_Ability_CreateNativeChildProcess 216 217``` 218int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted) 219``` 220 221**描述**： 222 223创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。 224 225参数所指定的动态库必须实现并导出下列函数： 226 227 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 228 2. void NativeChildProcess_MainProc() 229 230处理逻辑顺序如下列伪代码所示： 231 232 主进程： 233 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback) 234 235 子进程 ： 236 2. dlopen(libName) 237 3. dlsym("NativeChildProcess_OnConnect") 238 4. dlsym("NativeChildProcess_MainProc") 239 5. ipcRemote = NativeChildProcess_OnConnect() 240 6. NativeChildProcess_MainProc() 241 242 主进程 ： 243 7. onProcessStartedCallback(ipcRemote, errCode) 244 245 子进程 ： 246 8. 在NativeChildProcess_MainProc()函数返回后子进程退出。 247 248> **说明：** 249> 250> 当前仅支持2in1设备。 251> 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。 252 253**起始版本**：12 254 255**参数**： 256 257| 名称 | 描述 | 258| ------------------------ | --------------------------------------------------------------------------------------------------------------- | 259| libName | 子进程中加载的动态库文件名称，不能为nullptr。 | 260| onProcessStartedCallback | 通知子进程启动结果的回调函数指针，不能为nullptr，详见[OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted) | 261 262 263**返回**： 264 265执行成功返回NCP_NO_ERROR，失败返回错误码，详见[Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode)。 266 267### OH_Ability_StartNativeChildProcess 268 269``` 270Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess( 271 const char* entry, NativeChildProcess_Args args, 272 NativeChildProcess_Options options, int32_t *pid) 273``` 274 275**描述**： 276 277启动Native子进程，加载参数中指定的动态链接库文件并调用入口函数。支持传参到子进程。子进程中不支持创建ArkTS基础运行时环境。 278 279参数所指定的动态库必须实现参数为[NativeChildProcess_Args](#nativechildprocess_args)入口函数并导出。详见[Native子进程开发指导（C/C++）- 创建支持参数传递的子进程](../../application-models/capi_nativechildprocess_development_guideline.md#创建支持参数传递的子进程)。 280 281> **说明：** 282> 283> 当前仅支持2in1、tablet设备。 284 285**起始版本**：13 286 287**参数**： 288 289| 名称 | 描述 | 290| ---------------------- | ---------------- | 291| entry | 子进程中调用动态库的符号和入口函数，中间用“:”隔开（例如“libentry.so:Main”)。不能为nullptr。 | 292| args | 传给子进程的参数，详见[NativeChildProcess_Args](#nativechildprocess_args)定义。 | 293| options | 子进程的启动配置选项，详见[NativeChildProcess_Options](#nativechildprocess_options)定义。 | 294| pid | 启动子进程号。 | 295 296 297**返回**： 298 299执行成功返回NCP_NO_ERROR，失败返回错误码，详见[Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode)。 300 301### OH_Ability_GetCurrentChildProcessArgs 302 303``` 304NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs(); 305``` 306 307**描述**： 308 309通过[OH_Ability_StartNativeChildProcess](#oh_ability_startnativechildprocess)启动子进程后，子进程能够在任意so和任意子线程中获取启动参数[NativeChildProcess_Args](#nativechildprocess_args)。 310 311> **说明：** 312> 313> 当前仅支持2in1、tablet设备。 314 315**起始版本**：17 316 317**返回**： 318 319执行成功返回指向[NativeChildProcess_Args](#nativechildprocess_args)对象的指针，失败返回nullptr。