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设备，且单个进程只能启动一个Native子进程。 51 52## 类型定义说明 53### OH_Ability_OnNativeChildProcessStarted 54 55``` 56typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy) 57``` 58 59**描述** 60 61通知子进程启动结果的回调函数。 62 63**起始版本**：12 64 65**参数:** 66 67| 名称 | 描述 | 68| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 69| 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)定义。 | 70| remoteProxy | 子进程的IPC对象指针，出现异常时可能为nullptr； 使用完毕后需要调用[OH_IPCRemoteProxy_Destroy](../apis-ipc-kit/_o_h_i_p_c_remote_object.md#oh_ipcremoteproxy_destroy)方法释放。 | 71 72**参见：** 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**描述** 89 90子进程文件描述记录。 91 92**起始版本**：13 93 94**参数:** 95 96| 名称 | 描述 | 97| ----------- | ------------- | 98| fdName | 文件描述关键字。最大长度为20字符。 | 99| fd | 文件描述符句柄。| 100| next | 下一个文件描述记录指针。 | 101 102### NativeChildProcess_FdList 103 104``` 105typedef struct NativeChildProcess_FdList { 106 struct NativeChildProcess_Fd* head; 107} NativeChildProcess_FdList; 108``` 109 110**描述** 111 112子进程文件描述记录链表。文件描述符记录个数不能超过16个。 113 114**起始版本**：13 115 116**参数:** 117 118| 名称 | 描述 | 119| ----------- | ------------- | 120| head | 子进程文件描述记录链表中的第一个记录，详见[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**描述** 132 133启动子进程的入参。 134 135**起始版本**：13 136 137**参数:** 138 139| 名称 | 描述 | 140| ----------- | ------------- | 141| entryParams | 入口参数，大小不能超过150KB。 | 142| fdList | 子进程文件描述记录链表，详见[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**描述** 154 155启动子进程的配置选项。 156 157**起始版本**：13 158 159**参数:** 160 161| 名称 | 描述 | 162| ----------- | ------------- | 163| isolationMode | 进程独立模式，详见[NativeChildProcess_IsolationMode](#nativechildprocess_isolationmode)定义。 | 164| reserved | 保留字段。| 165 166## 枚举类型说明 167 168### Ability_NativeChildProcess_ErrCode 169 170``` 171enum Ability_NativeChildProcess_ErrCode 172``` 173 174**描述** 175 176定义Native子进程模块错误码。 177 178**起始版本**：12 179 180| 枚举值 | 描述 | 181| ----------------------------------- | ----------------------------------------------- | 182| NCP_NO_ERROR | 操作成功。 | 183| NCP_ERR_INVALID_PARAM | 无效参数。 | 184| NCP_ERR_NOT_SUPPORTED | 不支持创建Native子进程。 | 185| NCP_ERR_INTERNAL | 内部错误。 | 186| NCP_ERR_BUSY | 在Native子进程的启动过程中不能再次创建新的子进程，可以等待当前子进程启动完成后再次尝试。 | 187| NCP_ERR_TIMEOUT | 启动Native子进程超时。 | 188| NCP_ERR_SERVICE_ERROR | 服务端出错。 | 189| NCP_ERR_MULTI_PROCESS_DISABLED | 多进程模式已关闭，不允许启动子进程。 | 190| NCP_ERR_ALREADY_IN_CHILD | 不允许在子进程中再次创建进程。 | 191| NCP_ERR_MAX_CHILD_PROCESSES_REACHED | 到达最大Native子进程数量限制，不能再创建子进程。 | 192| NCP_ERR_LIB_LOADING_FAILED | 子进程加载动态库失败，文件不存在或者未实现对应的方法并导出。 | 193| NCP_ERR_CONNECTION_FAILED | 子进程调用动态库的OnConnect方法失败，可能返回了无效的IPC对象指针。 | 194 195### NativeChildProcess_IsolationMode 196 197``` 198enum NativeChildProcess_IsolationMode 199``` 200 201**描述** 202 203定义Native子进程独立模式。 204 205**起始版本**：13 206 207| 枚举值 | 描述 | 208| ----------------------------------- | ----------------------------------------------- | 209| NCP_ISOLATION_MODE_NORMAL | 普通进程独立模式，与主进程共享数据沙箱和网络环境。| 210| NCP_ISOLATION_MODE_ISOLATED | 独立沙箱进程模式，与主进程不共享数据沙箱和网络环境。 | 211 212## 函数说明 213 214### OH_Ability_CreateNativeChildProcess 215 216``` 217int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted ) 218``` 219 220**描述**： 221 222创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。 223 224参数所指定的动态库必须实现并导出下列函数： 225 226 1. OHIPCRemoteStub* NativeChildProcess_OnConnect() 227 2. void NativeChildProcess_MainProc() 228 229处理逻辑顺序如下列伪代码所示： 230 231 主进程： 232 1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback) 233 234 子进程 ： 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 主进程 ： 242 7. onProcessStartedCallback(ipcRemote, errCode) 243 244 子进程 ： 245 8. 在NativeChildProcess_MainProc()函数返回后子进程退出。 246 247> **说明：** 248> 249> 当前仅支持2in1设备，且单个进程只能启动一个Native子进程。 250 251**起始版本**：12 252 253**参数**： 254 255| 名称 | 描述 | 256| ------------------------ | --------------------------------------------------------------------------------------------------------------- | 257| libName | 子进程中加载的动态库文件名称，不能为nullptr。 | 258| onProcessStartedCallback | 通知子进程启动结果的回调函数指针，不能为nullptr，详见[OH_Ability_OnNativeChildProcessStarted](#oh_ability_onnativechildprocessstarted) | 259 260 261**返回**： 262 263执行成功返回NCP_NO_ERROR，失败返回错误码，详见[Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode)。 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**描述**： 274 275启动Native子进程，加载参数中指定的动态链接库文件并调用入口函数。支持传参到子进程。子进程中不支持创建ArkTS基础运行时环境。 276 277参数所指定的动态库必须实现参数为[NativeChildProcess_Args](#nativechildprocess_args)入口函数并导出。详见[Native子进程开发指导（C/C++）- 创建支持参数传递的子进程](../../application-models/capi_nativechildprocess_development_guideline.md#创建支持参数传递的子进程)。 278 279> **说明：** 280> 281> 当前仅支持2in1、tablet设备。 282 283**起始版本**：13 284 285**参数**： 286 287| 名称 | 描述 | 288| ---------------------- | ---------------- | 289| entry | 子进程中调用动态库的符号和入口函数，中间用“:”隔开（例如“libentry.so:Main”)。不能为nullptr。 | 290| args | 传给子进程的参数，详见[NativeChildProcess_Args](#nativechildprocess_args)定义。 | 291| options | 子进程的启动配置选项，详见[NativeChildProcess_Options](#nativechildprocess_options)定义。 | 292| pid | 启动子进程号。 | 293 294 295**返回**： 296 297执行成功返回NCP_NO_ERROR，失败返回错误码，详见[Ability_NativeChildProcess_ErrCode](#ability_nativechildprocess_errcode)。