超节点

版本：24.03 LTS SP4
文档中心
超节点
接口说明

API 参考 ​

介绍 ​

本文介绍 UBS MemStore 对外提供的 C API。接口定义以 src/include/mms_c.h 为准。

UBS MemStore 主体使用 C/C++ 开发，对外提供 C 语言接口。调用方应先调用 MmsInitialize 初始化服务，再调用读写、查询、通知注册等接口，退出时调用 MmsExit。

基本约定 ​

  • 批量接口中，每个 item 都有独立的 result 字段，用于返回单条 key 的执行结果。
  • 批量接口整体返回值规则：全部成功返回 RET_MMS_OK；任意 item 失败时返回最后一个失败 item 的错误码。
  • key 统一使用 const char *key + uint16_t keyLen 表示，keyLen 不包含字符串结束符 '\0'。
  • key 最大有效长度为 31 字节，超过该长度的请求会返回入参错误。
  • PutItems::isNotify 和 DeleteItems::isNotify 用于控制单条 key 是否触发数据变更通知。全局通知开关关闭或 isNotify 为 0 时，不触发通知。

错误码 ​

错误码取值说明
RET_MMS_OK0成功。
RET_MMS_PROTECTED1写保护。
RET_MMS_ERROR2未知错误。
RET_MMS_EPERM3入参错误。
RET_MMS_BUSY4服务忙，需要外部重试。
RET_MMS_NEED_RETRY5需要重试。
RET_MMS_NOT_READY6服务未就绪。
RET_MMS_NOT_FOUND7key 不存在。
RET_MMS_CONFLICT8key 冲突。
RET_MMS_MISS9缓存未命中。
RET_MMS_NO_SPACE10容量不足。
RET_MMS_UNAVAILABLE11服务不可用。
RET_MMS_EXCEED_QUOTA12超过配额限制。
RET_MMS_PT_FAULT13分区故障。
RET_MMS_READ_EXCEED14读取范围超过限制。
RET_MMS_EXISTS15资源已存在。

公共类型 ​

MmsOptions ​

MMS 初始化配置。

c
typedef struct {
    uint16_t netConnectCnt;
    uint16_t netGroupNum;
    uint8_t netIsBusyPolling;
    uint8_t tlsEnable;
    char certificationPath[PATH_MAX];
    char caCerPath[PATH_MAX];
    char caCrlPath[PATH_MAX];
    char privateKeyPath[PATH_MAX];
    char privateKeyPasswordPath[PATH_MAX];
    char decrypterLibPath[PATH_MAX];
    char opensslLibDir[PATH_MAX];
} MmsOptions;
字段说明
netConnectCnt每个 channel 的网络连接数。
netGroupNumIPC worker group 数量，需要与mms.conf中mms.net.ipc.worker.groups配置的组数一致。
netIsBusyPolling网络 polling 模式。0 表示 event polling；非 0 表示 busy polling。
tlsEnableTLS 开关。0 表示关闭；非 0 表示开启。
certificationPath证书路径。
caCerPathCA 证书路径。
caCrlPathCA CRL 文件路径。
privateKeyPath私钥路径。
privateKeyPasswordPath私钥口令密文文件路径。
decrypterLibPath证书解密函数动态库路径。
opensslLibDirOpenSSL 动态库目录。

PutItems ​

写入 item 描述。

c
typedef struct {
    const char *key;
    const char *value;
    uint32_t valueLen;
    uint16_t keyLen;
    uint16_t isNotify;
    char **valueAddr;
    int32_t *result;
} PutItems;
字段方向说明
key输入key 首地址。
value输入value 首地址。
valueLen输入value 长度。
keyLen输入key 长度，不包含 '\0'。
isNotify输入是否触发数据变更通知。0 表示不通知；非 0 表示通知。
valueAddr输出写入成功后返回底层存储数据的内存首地址。
result输出单条 item 的执行结果。

GetItems ​

读取 item 描述。

c
typedef struct {
    const char *key;
    uint16_t keyLen;
    uint32_t offset;
    uint32_t length;
    char **value;
    uint32_t *realLength;
    int32_t *result;
} GetItems;
字段方向说明
key输入key 首地址。
keyLen输入key 长度，不包含 '\0'。
offset输入读取起始偏移。
length输入期望读取长度。
value输入/输出若 *value == NULL，返回底层存储数据的内存首地址；否则将数据拷贝到 *value 指向的内存。
realLength输出实际返回的数据长度。
result输出单条 item 的执行结果。

UpdateItems / ReplaceItems ​

更新和替换 item 描述。ReplaceItems 与 UpdateItems 使用相同结构。

c
typedef struct {
    const char *key;
    const char *value;
    uint16_t keyLen;
    uint32_t valueLen;
    uint32_t offset;
    int32_t *result;
} UpdateItems, ReplaceItems;
字段方向说明
key输入key 首地址。
value输入待写入的数据首地址。
keyLen输入key 长度，不包含 '\0'。
valueLen输入待写入的数据长度。
offset输入写入起始偏移。
result输出单条 item 的执行结果。

DeleteItems ​

删除 item 描述。

c
typedef struct {
    const char *key;
    uint16_t keyLen;
    uint16_t isNotify;
    int32_t *result;
} DeleteItems;
字段方向说明
key输入key 首地址。
keyLen输入key 长度，不包含 '\0'。
isNotify输入是否触发数据变更通知。0 表示不通知；非 0 表示通知。
result输出单条 item 的执行结果。

数据变更通知类型 ​

c
typedef enum {
    OP_PUT = 0,
    OP_DELETE = 1,
    OP_BUTT
} OperateType;

typedef void (*NotifyCallback)(const char *key, uint32_t keyLen, OperateType opType, void *lpUserData);

当前通知类型包括：

类型说明
OP_PUT写入通知。
OP_DELETE删除通知。

服务状态回调 ​

c
typedef void (*ServiceCallback)(uint8_t serviceable);

serviceable 为 0 表示不可服务，非 0 表示可服务。

MmsInitialize ​

功能 ​

初始化 MMS 服务。

函数原型 ​

c
CResult MmsInitialize(const MmsOptions *options, ServiceCallback service);

参数 ​

参数方向说明
options输入初始化配置。
service输入服务状态回调函数。

返回值 ​

返回值说明
RET_MMS_OK初始化成功。
其它初始化失败。

MmsRegisterNotifyCallback ​

功能 ​

注册数据变更通知回调函数。

函数原型 ​

c
CResult MmsRegisterNotifyCallback(NotifyCallback callback, void *lpUserData);

参数 ​

参数方向说明
callback输入数据变更通知回调函数。
lpUserData输入用户上下文指针，触发通知时通过回调函数原样返回。

返回值 ​

返回值说明
RET_MMS_OK注册成功。
其它注册失败。

MmsExit ​

功能 ​

退出 MMS 服务。

函数原型 ​

c
void MmsExit(void);

参数 ​

无。

返回值 ​

无。

MmsPut ​

功能 ​

批量写入 key/value。

函数原型 ​

c
CResult MmsPut(PutItems *itemList, uint32_t itemNum);

参数 ​

参数方向说明
itemList输入/输出写入 item 数组。
itemNum输入item 数量。

返回值 ​

返回值说明
RET_MMS_OK全部 item 写入成功。
其它至少一个 item 写入失败，返回最后一个失败 item 的错误码。

注意事项 ​

  • 每个 item 的 result 返回该 key 的执行结果。
  • 每个 item 的 valueAddr 返回实际写入后的内存地址。
  • isNotify 仅表示该 item 是否请求通知；最终是否通知还受全局通知开关控制。

MmsGet ​

功能 ​

批量读取 key/value。

函数原型 ​

c
CResult MmsGet(GetItems *itemList, uint32_t itemNum);

参数 ​

参数方向说明
itemList输入/输出读取 item 数组。
itemNum输入item 数量。

返回值 ​

返回值说明
RET_MMS_OK全部 item 读取成功。
其它至少一个 item 读取失败，返回最后一个失败 item 的错误码。

注意事项 ​

  • 若 GetItems::value 指向的指针为 NULL，接口返回底层存储数据的内存首地址，不执行 value 拷贝。
  • 若 GetItems::value 指向的指针非 NULL，接口将读取到的数据拷贝到调用方提供的内存中。
  • 免拷贝返回的内存由 MMS 管理，调用方不得释放。

MmsUpdate ​

功能 ​

批量更新已存在 key 的部分 value。

函数原型 ​

c
CResult MmsUpdate(UpdateItems *itemList, uint32_t itemNum);

参数 ​

参数方向说明
itemList输入/输出更新 item 数组。
itemNum输入item 数量。

返回值 ​

返回值说明
RET_MMS_OK全部 item 更新成功。
其它至少一个 item 更新失败，返回最后一个失败 item 的错误码。

MmsDelete ​

功能 ​

批量删除 key。

函数原型 ​

c
CResult MmsDelete(DeleteItems *itemList, uint32_t itemNum);

参数 ​

参数方向说明
itemList输入/输出删除 item 数组。
itemNum输入item 数量。

返回值 ​

返回值说明
RET_MMS_OK全部 item 删除成功。
其它至少一个 item 删除失败，返回最后一个失败 item 的错误码。

注意事项 ​

isNotify 仅表示该 item 是否请求通知；最终是否通知还受全局通知开关控制。

MmsReplace ​

功能 ​

批量替换 key/value。key 已存在时更新，key 不存在时写入。

函数原型 ​

c
CResult MmsReplace(ReplaceItems *itemList, uint32_t itemNum);

参数 ​

参数方向说明
itemList输入/输出替换 item 数组。
itemNum输入item 数量。

返回值 ​

返回值说明
RET_MMS_OK全部 item 替换成功。
其它至少一个 item 替换失败，返回最后一个失败 item 的错误码。

MmsStartCatchUpTask ​

功能 ​

启动恢复追平任务。

函数原型 ​

c
CResult MmsStartCatchUpTask(void);

参数 ​

无。

返回值 ​

返回值说明
RET_MMS_OK启动成功。
其它启动失败。

遵循 木兰宽松许可证第2版（MulanPSL2）

版权所有 © 2026 openEuler 保留一切权利京ICP备2020036654号-1京公网安备 11030102011597 号
品牌隐私声明法律声明关于cookies
品牌隐私声明法律声明关于cookies
遵循木兰宽松许可证第2版（MulanPSL2）
版权所有 © 2026 openEuler 保留一切权利
京ICP备2020036654号-1京公网安备 11030102011597 号