startup_appspawn/docs/modules/module_client_api.md

Module: client_api

返回: 索引

Overview

client_api 模块提供 appspawn 的客户端 API，供 AMS（Ability Manager Service）等外部服务调用。客户端通过这些 API 构建孵化请求消息，经本地 socket 发送给 appspawn 服务端，并接收孵化结果。

客户端 API 采用句柄模型：AppSpawnClientHandle 代表客户端连接（线程安全），AppSpawnReqMsgHandle 代表单条请求消息（非线程安全）。

Source Location

• Directory: interfaces/innerkits/
• Files: client/appspawn_client.c, client/appspawn_msg.c, include/appspawn.h, client/appspawn_client.h
• Estimated LOC: ~1,803

Dependencies

• Depends on: 无（独立客户端库）
• Used by: AMS, 外部系统服务

---

KP-1: 客户端 SDK 架构

Priority: P0

Summary

公共 API 定义在 appspawn.h 中，使用不透明句柄（void * 类型）隐藏内部实现。核心设计是两个句柄：AppSpawnReqMsgHandle（消息构建）和 AppSpawnClientHandle（连接管理）。

Key Code

句柄类型定义

// interfaces/innerkits/include/appspawn.h:39
typedef void *AppSpawnReqMsgHandle;  // 请求消息句柄，不支持多线程
typedef void *AppSpawnClientHandle;  // 客户端句柄，支持多线程

#define INVALID_PERMISSION_INDEX (-1)
#define INVALID_REQ_HANDLE NULL
#define APPSPAWN_SERVER_NAME "appspawn"
#define NWEBSPAWN_SERVER_NAME "nwebspawn"
#define NATIVESPAWN_SERVER_NAME "nativespawn"

核心数据结构

// interfaces/innerkits/client/appspawn_client.h:84
typedef struct TagAppSpawnReqMsgNode {
    struct ListNode node;
    uint32_t reqId;
    uint32_t retryCount;
    int fdCount;
    int fds[APP_MAX_FD_COUNT];
    int isColdRun;
    AppSpawnMsgFlags *msgFlags;
    AppSpawnMsgFlags *permissionFlags;
    AppSpawnMsg *msg;
    struct ListNode msgBlocks;  // 保存实际的消息数据
} AppSpawnReqMsgNode;

// interfaces/innerkits/client/appspawn_client.h:74
typedef struct TagAppSpawnReqMsgMgr {
    AppSpawnClientType type;
    uint32_t maxRetryCount;
    uint32_t timeout;
    uint32_t msgNextId;
    int socketId;
    pthread_mutex_t mutex;       // 线程安全锁
    AppSpawnMsgBlock recvBlock;  // 消息接收缓存
} AppSpawnReqMsgMgr;

---

KP-2: 消息构造与发送

Priority: P0

Summary

消息构造通过 AppSpawnReqMsgCreate() 创建消息句柄，然后通过一系列 AppSpawnClientAdd* / AppSpawnClientSet* API 填充 TLV 字段。最后通过 AppSpawnClientSendMsg() 发送。

Key Code

DAC 信息结构体

// interfaces/innerkits/include/appspawn.h:64
typedef struct {
    uint32_t uid;       // 子进程 setuid() 后的 UID
    uint32_t gid;       // 子进程 setgid() 后的 GID
    uint32_t gidCount;  // gidTable 大小
    uint32_t gidTable[APP_MAX_GIDS];  // 64 个附加 GID
    char userName[APP_USER_NAME];
} AppDacInfo;

响应结构体

// interfaces/innerkits/include/appspawn.h:72
typedef struct {
    int result;
    pid_t pid;
    uint64_t checkPointId;  // checkpoint ID（镜像进程响应有效）
} AppSpawnResult;

消息块管理

// interfaces/innerkits/client/appspawn_client.h:67
typedef struct {
    struct ListNode node;
    uint32_t blockSize;     // block 大小
    uint32_t currentIndex;  // 当前填充位置
    uint8_t buffer[0];      // 柔性数组
} AppSpawnMsgBlock;

消息数据以 block 链表形式存储，支持动态扩展。

---

KP-3: DAC/权限信息设置 API

Priority: P0

Summary

API 层提供丰富的信息设置接口，覆盖孵化请求的所有字段。

主要 API

API	文件	用途
AppSpawnClientInit	appspawn.h	初始化客户端句柄
AppSpawnReqMsgCreate	appspawn.h	创建请求消息句柄
AppSpawnClientAddBundleInfo	appspawn.h	设置 bundle name 和 index
AppSpawnClientSetAppDacInfo	appspawn.h	设置 UID/GID/GID 表
AppSpawnClientSetAppDomainInfo	appspawn.h	设置 APL 和 hapFlags
AppSpawnClientSetAppAccessToken	appspawn.h	设置 AccessToken
AppSpawnClientAddPermission	appspawn.h	添加权限位
AppSpawnClientSetAppInternetPermission	appspawn.h	设置网络权限
AppSpawnClientSetAppOwnerId	appspawn.h	设置 OwnerId
AppSpawnClientSendMsg	appspawn.h	发送请求并等待结果

---

KP-4: 客户端连接管理

Priority: P1

Summary

客户端连接支持多线程安全，使用 pthread_mutex_t 保护。支持超时和重试机制。

Key Code

超时与重试

// interfaces/innerkits/client/appspawn_client.h:29
#define APPSPAWN_CLIENT_TIMEOUT_MIN 2       // 最小超时 2 秒
#define APPSPAWN_CLIENT_TIMEOUT_MAX 120     // 最大超时 120 秒
#define TIMEOUT_DEF 2                        // 默认超时
#define RETRY_TIME (200 * 1000)             // 重试间隔 200ms
#define MAX_RETRY_SEND_COUNT 2              // 最大重试次数

客户端类型

// interfaces/innerkits/client/appspawn_client.h:57
typedef enum {
    CLIENT_FOR_APPSPAWN,
    CLIENT_FOR_NWEBSPAWN,
    CLIENT_FOR_CJAPPSPAWN,
    CLIENT_FOR_NATIVESPAWN,
    CLIENT_FOR_HYBRIDSPAWN,
    CLIENT_FOR_APPSPAWNDF,
    CLIENT_MAX
} AppSpawnClientType;

---

Key Data Structures

Structure	File	Purpose
AppDacInfo	appspawn.h:64	DAC 信息（UID/GID/GID 表）
AppSpawnResult	appspawn.h:72	孵化响应
AppSpawnReqMsgMgr	appspawn_client.h:74	请求管理器（含互斥锁）
AppSpawnReqMsgNode	appspawn_client.h:84	单条请求消息
AppSpawnMsgBlock	appspawn_client.h:67	消息数据块
AppSpawnClientType	appspawn_client.h:57	客户端类型枚举

Cross-Module Interactions

Interaction	With Module	Mechanism	Direction
Socket 通信	standard	本地 socket	Outgoing
消息格式	modulemgr_engine	TLV 格式共享	Shared
错误码	util	APPSPAWN错误码	Shared

---

Related Modules

Module	Relationship	Link
standard	used_by	module_standard.md
modulemgr_engine	shares_with	module_modulemgr_engine.md
util	depends_on	module_util.md

另见: 本模块与上述模块存在依赖关系。具体交互细节请参考 系统架构 中的跨模块关系章节。