ChildProcess

概述

提供子进程的管理能力，支持创建Native子进程并在父子进程间建立IPC通道，用于实现多进程应用开发。

创建的子进程不支持UI界面，也不支持Context相关的接口调用。通过此模块和childProcessManager（非SELF_FORK模式）启动的子进程总数最大为512个。

系统能力：SystemCapability.Ability.AbilityRuntime.Core

起始版本：12

汇总

文件

名称	描述
native_child_process.h	支持创建Native子进程，并在父子进程间建立IPC通道。 引用文件：<AbilityKit/native_child_process.h> 库：libchild_process.so

类型定义

名称	描述
typedef enum Ability_NativeChildProcess_ErrCode Ability_NativeChildProcess_ErrCode	定义Native子进程模块错误码。
typedef void(* OH_Ability_OnNativeChildProcessStarted) (int errCode, OHIPCRemoteProxy *remoteProxy)	定义通知子进程启动结果的回调函数。
typedef struct NativeChildProcess_Fd	定义子进程文件描述符记录。
typedef struct NativeChildProcess_FdList	定义子进程文件描述符记录链表。
typedef struct NativeChildProcess_Args	定义启动子进程入参。

枚举

名称

描述

Ability_NativeChildProcess_ErrCode { NCP_NO_ERROR = 0, NCP_ERR_INVALID_PARAM = 401, NCP_ERR_NOT_SUPPORTED = 801, NCP_ERR_INTERNAL = 16000050, NCP_ERR_BUSY = 16010001, NCP_ERR_TIMEOUT = 16010002, NCP_ERR_SERVICE_ERROR = 16010003, NCP_ERR_MULTI_PROCESS_DISABLED = 16010004, NCP_ERR_ALREADY_IN_CHILD = 16010005, NCP_ERR_MAX_CHILD_PROCESSES_REACHED = 16010006, NCP_ERR_LIB_LOADING_FAILED = 16010007, NCP_ERR_CONNECTION_FAILED = 16010008 }

定义Native子进程模块错误码。

函数

名称	描述
int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted)	创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。

说明：

当前仅支持2in1设备。 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。

类型定义说明

OH_Ability_OnNativeChildProcessStarted

typedef void (*OH_Ability_OnNativeChildProcessStarted)(int errCode, OHIPCRemoteProxy *remoteProxy)

描述

通知子进程启动结果的回调函数。

起始版本：12

参数:

名称	描述
errCode	NCP_NO_ERROR - 创建子进程成功 NCP_ERR_LIB_LOADING_FAILED - 加载动态库文件失败或动态库中未实现必要的导出函数 NCP_ERR_CONNECTION_FAILED - 动态库中实现的OnConnect方法未返回有效的IPC Stub指针 详见Ability_NativeChildProcess_ErrCode定义。
remoteProxy	子进程的IPC对象指针，出现异常时可能为nullptr； 使用完毕后需要调用OH_IPCRemoteProxy_Destroy方法释放。

参见：

OH_Ability_CreateNativeChildProcess

OH_IPCRemoteProxy_Destroy

NativeChildProcess_Fd

typedef struct NativeChildProcess_Fd {
    char* fdName;
    int32_t fd;
    struct NativeChildProcess_Fd* next;
} NativeChildProcess_Fd;

描述

子进程文件描述记录。

起始版本：13

参数:

名称	描述
fdName	文件描述关键字。最大长度为20字符。
fd	文件描述符句柄。
next	下一个文件描述记录指针。

NativeChildProcess_FdList

typedef struct NativeChildProcess_FdList {
    struct NativeChildProcess_Fd* head;
} NativeChildProcess_FdList;

描述

子进程文件描述记录链表。文件描述符记录个数不能超过16个。

起始版本：13

参数:

名称	描述
head	子进程文件描述记录链表中的第一个记录，详见NativeChildProcess_FdList定义。

NativeChildProcess_Args

typedef struct NativeChildProcess_Args {
    char* entryParams;
    struct NativeChildProcess_FdList fdList;
} NativeChildProcess_Args;

描述

启动子进程的入参。

起始版本：13

参数:

名称	描述
entryParams	入口参数，大小不能超过150KB。
fdList	子进程文件描述记录链表，详见NativeChildProcess_FdList定义。

NativeChildProcess_Options

typedef struct NativeChildProcess_Options {
    NativeChildProcess_IsolationMode isolationMode;
    int64_t reserved;
} NativeChildProcess_Options;

描述

启动子进程的配置选项。

起始版本：13

参数:

名称	描述
isolationMode	进程独立模式，详见NativeChildProcess_IsolationMode定义。
reserved	保留字段。

枚举类型说明

Ability_NativeChildProcess_ErrCode

enum Ability_NativeChildProcess_ErrCode

描述

定义Native子进程模块错误码。

起始版本：12

枚举值	描述
NCP_NO_ERROR	操作成功。
NCP_ERR_INVALID_PARAM	无效参数。
NCP_ERR_NOT_SUPPORTED	不支持创建Native子进程。
NCP_ERR_INTERNAL	内部错误。
NCP_ERR_BUSY	在Native子进程的启动过程中不能再次创建新的子进程，可以等待当前子进程启动完成后再次尝试。从API version 15开始被废弃。
NCP_ERR_TIMEOUT	启动Native子进程超时。
NCP_ERR_SERVICE_ERROR	服务端出错。
NCP_ERR_MULTI_PROCESS_DISABLED	多进程模式已关闭，不允许启动子进程。
NCP_ERR_ALREADY_IN_CHILD	不允许在子进程中再次创建进程。
NCP_ERR_MAX_CHILD_PROCESSES_REACHED	到达最大Native子进程数量限制，不能再创建子进程。
NCP_ERR_LIB_LOADING_FAILED	子进程加载动态库失败，文件不存在或者未实现对应的方法并导出。
NCP_ERR_CONNECTION_FAILED	子进程调用动态库的OnConnect方法失败，可能返回了无效的IPC对象指针。

NativeChildProcess_IsolationMode

enum NativeChildProcess_IsolationMode

描述

定义Native子进程独立模式。

起始版本：13

枚举值	描述
NCP_ISOLATION_MODE_NORMAL	普通进程独立模式，与主进程共享数据沙箱和网络环境。
NCP_ISOLATION_MODE_ISOLATED	独立沙箱进程模式，与主进程不共享数据沙箱和网络环境。

函数说明

OH_Ability_CreateNativeChildProcess

int OH_Ability_CreateNativeChildProcess (const char *libName, OH_Ability_OnNativeChildProcessStarted onProcessStarted)

描述：

创建子进程并加载参数中指定的动态链接库文件，进程启动结果通过回调参数异步通知，需注意回调通知为独立线程，回调函数实现需要注意线程同步，且不能执行高耗时操作避免长时间阻塞。

参数所指定的动态库必须实现并导出下列函数：

1. OHIPCRemoteStub* NativeChildProcess_OnConnect()
2. void NativeChildProcess_MainProc()

处理逻辑顺序如下列伪代码所示：

主进程：
1. OH_Ability_CreateNativeChildProcess(libName, onProcessStartedCallback)

子进程 ：
2. dlopen(libName)
3. dlsym("NativeChildProcess_OnConnect")
4. dlsym("NativeChildProcess_MainProc")
5. ipcRemote = NativeChildProcess_OnConnect()
6. NativeChildProcess_MainProc()

主进程 ：
7. onProcessStartedCallback(ipcRemote, errCode)

子进程 ：
8. 在NativeChildProcess_MainProc()函数返回后子进程退出。

说明：

当前仅支持2in1设备。 从API version 15开始，单个进程最多支持启动50个Native子进程。API version 14及之前版本，单个进程只能启动1个Native子进程。

起始版本：12

参数：

名称	描述
libName	子进程中加载的动态库文件名称，不能为nullptr。
onProcessStartedCallback	通知子进程启动结果的回调函数指针，不能为nullptr，详见OH_Ability_OnNativeChildProcessStarted

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_StartNativeChildProcess

Ability_NativeChildProcess_ErrCode OH_Ability_StartNativeChildProcess(
    const char* entry, NativeChildProcess_Args args,
    NativeChildProcess_Options options, int32_t *pid)

描述：

启动Native子进程，加载参数中指定的动态链接库文件并调用入口函数。支持传参到子进程。子进程中不支持创建ArkTS基础运行时环境。

参数所指定的动态库必须实现参数为NativeChildProcess_Args入口函数并导出。详见Native子进程开发指导（C/C++）- 创建支持参数传递的子进程。

说明：

当前仅支持2in1、tablet设备。

起始版本：13

参数：

名称	描述
entry	子进程中调用动态库的符号和入口函数，中间用“:”隔开（例如“libentry.so:Main”)。不能为nullptr。
args	传给子进程的参数，详见NativeChildProcess_Args定义。
options	子进程的启动配置选项，详见NativeChildProcess_Options定义。
pid	启动子进程号。

返回：

执行成功返回NCP_NO_ERROR，失败返回错误码，详见Ability_NativeChildProcess_ErrCode。

OH_Ability_GetCurrentChildProcessArgs

NativeChildProcess_Args* OH_Ability_GetCurrentChildProcessArgs();

描述：

通过OH_Ability_StartNativeChildProcess启动子进程后，子进程能够在任意so和任意子线程中获取启动参数NativeChildProcess_Args。

说明：

当前仅支持2in1、tablet设备。

起始版本：17

返回：

执行成功返回指向NativeChildProcess_Args对象的指针，失败返回nullptr。