需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

Storage

  • C++

更新时间不可用

RTM 的 Storage 功能提供了一套动态数据库机制，可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据。

setChannelMetadata

接口描述

setChannelMetadata 方法可以为频道（Message Channel 或 Stream Channel）设置 Channel Metadata。一个频道只能有一组 Metadata，但每组 Metadata 可以有一个或多个 Metadata Item。如果多次调用该方法，SDK 会依次检索 Metadata Item 的 key 值，并按如下规则处理：

  • 如果设置的 Metadata Item key 值不同，则会根据调用顺序依次增加。
  • 如果设置的 Metadata Item key 值相同，则最后一次设置的 Metadata Item 的 value 会覆盖之前的值。

Channel Metadata 同时也引进了版本控制逻辑 CAS（Compare And Set），该方法提供两种独立的版本控制字段，你可以根据实际业务场景设置任意一种或多种：

  • 通过 Metadata 中的 majorRevision 属性开启整组 Channel Metadata 的版本号校验。
  • 通过 MetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置 Channel Metadata 或 Metadata Item 时，配合版本属性可以控制本次调用是否开启版本号校验，逻辑如下：

  • 版本属性默认为 -1 ，本次调用不开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在，则该值会被最新值覆盖；如果 Channel Metadata 或 Metadata Item 不存在，则 SDK 会创建该值。
  • 版本属性为正整数时，本次调用开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；否则 SDK 会返回错误码。

成功设置 Channel Metadata 后，订阅该频道且开启事件监听的用户会收到 RTM_STORAGE_TYPE_CHANNEL 类型的 onStorageEvent 事件通知。详见事件监听。

接口方法

你可以通过以下方式调用 setChannelMetadata 方法：

C++
virtual void setChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType,
    const Metadata& data, const MetadataOptions& options,
    const char* lockName, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
lockNameconst char*必填-Lock 名称。设置后，只有调用 acquireLock 方法获取该锁的用户才能执行操作。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onSetChannelMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

接口方法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<agora::rtm::MetadataItem> items;
items.emplace_back(MetadataItem("Apple", "100", 174298200));
items.emplace_back(MetadataItem("Banana", "200", 174298100));
metadata.items = items.data();
metadata.itemCount = items.size();

MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;

uint64_t requestId;
rtmClient->getStorage()->setChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, metadata, options, "lockName", requestId);

getChannelMetadata

接口描述

getChannelMetadata 方法可以获取指定频道的 Metadata。

接口方法

你可以通过以下方式调用 getChannelMetadata 方法：

C++
virtual void getChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onGetChannelMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
dataconst Metadata&Metadata Item。详见 Metadata。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

接口方法

C++
// 方法调用
uint64_t requestId;
rtmClient->getStorage()->getChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, requestId);

removeChannelMetadata

接口描述

removeChannelMetadata 方法可以删除 Channel Metadata 或 Channel Metadata Item 数组。

删除时，配合版本属性可以控制本次调用是否开启版本号校验，逻辑如下：

  • 版本属性默认为 -1 ，本次调用不开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在，则 SDK 会删除该值；如果 Channel Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。
  • 版本属性为正整数时，本次调用开启 CAS 验证。如果 Channel Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后删除对应值；否则 SDK 会返回错误码。

成功删除 Channel Metadata 或 Metadata Item 后，订阅该频道且开启事件监听的用户会收到 RTM_STORAGE_TYPE_CHANNEL 类型的 onStorageEvent 事件通知。详见事件监听。

接口方法

你可以通过以下方式调用 removeChannelMetadata 方法：

C++
virtual void removeChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType,
    const Metadata& data, const MetadataOptions& options,
    const char* lockName, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
lockNameconst char*必填-Lock 名称。设置后，只有调用 acquireLock 方法获取该锁的用户才能执行操作。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onRemoveChannelMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

接口方法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<agora::rtm::MetadataItem> items;
items.emplace_back(MetadataItem("Apple", "", 174298200));
metadata.items = items.data();
metadata.itemCount = items.size();

MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;

uint64_t requestId;
rtmClient->getStorage()->removeChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, metadata, options, "lockName", requestId);

updateChannelMetadata

接口描述

updateChannelMetadata 方法可以更新已有的 Channel Metadata。每次调用该方法，你可以更新一个 Channel Metadata，也可以更新一个或多个 Channel Metadata Item 数组。

成功更新后，订阅该频道且开启事件监听的用户会收到 RTM_STORAGE_TYPE_CHANNEL 类型的 onStorageEvent 事件通知。详见事件监听。

信息

该方法不能对不存在的 Metadata Item 进行操作。

接口方法

你可以通过以下方式调用 updateChannelMetadata 方法：

C++
virtual void updateChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType,
    const Metadata& data, const MetadataOptions& options,
    const char* lockName, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
channelNameconst char*必填-频道名称。
channelTypeRTM_CHANNEL_TYPE必填-频道类型。详见 RTM_CHANNEL_TYPE。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
lockNameconst char*必填-Lock 名称。设置后，只有调用 acquireLock 方法获取该锁的用户才能执行操作。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onUpdateChannelMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
channelNameconst char*频道名称。
channelTypeRTM_CHANNEL_TYPE频道类型，详见 RTM_CHANNEL_TYPE。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<agora::rtm::MetadataItem> items;
items.emplace_back(MetadataItem("Apple", "120", 174298200));
metadata.items = items.data();
metadata.itemCount = items.size();

MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;

uint64_t requestId;
rtmClient->getStorage()->updateChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, metadata, options, "lockName", requestId);

setUserMetadata

接口描述

setUserMetadata 方法可以设置 User Metadata。如果多次调用该方法时，SDK 会依次检索 User Metadata Item 的 key 值，并按如下规则处理：

  • 如果设置的 Metadata Item key 值不同，则会根据调用顺序依次增加。
  • 如果设置的 Metadata Item key 值相同，则最后一次设置的 Metadata 的 value 会覆盖之前的值。

成功设置 User Metadata 后，订阅该用户 Metadata 且开启事件监听的用户会收到 RTM_STORAGE_TYPE_USER 类型的 onStorageEvent 事件通知。详见事件监听。

User Metadata 同时也引进了版本控制逻辑 CAS，该方法提供两种独立的版本控制字段，你可以根据实际业务场景设置任意一种或多种：

  • 通过 Metadata 中的 majorRevision 属性开启整组 Channel Metadata 的版本号校验。
  • 通过 MetadataItem 中的 revision 属性开启某个 Metadata Item 的版本号校验。

设置 User Metadata 时，配合版本属性可以控制本次调用是否开启版本号校验，逻辑如下：

  • 版本属性为 -1 时，本次调用不开启 CAS 验证。如果 User Metadata 或 Metadata Item 已存在，则该值会被最新值覆盖；如果 User Metadata 或 Metadata Item 不存在，则会创建该值。
  • 版本属性为正整数时，本次调用开启 CAS 验证。如果 User Metadata 或 Metadata Item 已存在，则 SDK 会在版本号验证成功后更新对应的值；如果 User Metadata 或 Metadata Item 不存在，则 SDK 会返回错误码。

接口方法

你可以通过以下方式调用 setUserMetadata 方法：

C++
virtual void setUserMetadata(
    const char* userId, const Metadata& data,
    const MetadataOptions& options, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 ID。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onSetUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<agora::rtm::MetadataItem> items;
items.emplace_back(MetadataItem("Name", "Tony", 174298200));
items.emplace_back(MetadataItem("Mute", "true", 174298100));
metadata.items = items.data();
metadata.items = items.size();

MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;

uint64_t requestId;
rtmClient->getStorage()->setUserMetadata("Tony", metadata, options, requestId);

getUserMetadata

接口描述

getUserMetadata 方法可以获取指定用户的 Metadata 和 User Metadata Item。

接口方法

你可以通过以下方式调用 getUserMetadata 方法：

C++
virtual void getUserMetadata(const char* userId, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 userId。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onGetUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
dataconst Metadata&Metadata Item。详见 Metadata。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getStorage()->getUserMetadata("Tony", requestId);

removeUserMetadata

接口描述

removeUserMetadata 方法可以删除 User Metadata 或某几个 User Metadata Item。

成功删除后，订阅该用户 Metadata 且开启事件监听的用户会收到 RTM_STORAGE_TYPE_USER 类型的 onStorageEvent 事件通知。详见事件监听。

接口方法

你可以通过以下方式调用 removeUserMetadata 方法：

C++
virtual void removeUserMetadata(
    const char* userId, const Metadata& data,
    const MetadataOptions& options, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 ID。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onRemoveUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<MetadataItem> items;
MetadataItem item;
item.key = "Mute";
item.revision = 174298200;
items.emplace_back(item);
metadata.items = items.data();
metadata.itemCount = items.size();

uint64_t requestId;
rtmClient->getStorage()->removeUserMetadata("Tony", metadata, MetadataOptions(), requestId);

updateUserMetadata

接口描述

updateUserMetadata 方法可以更新已有的 User Metadata 或 Metadata Item。

成功更新后，订阅该 User Metadata 且开启事件监听的用户会收到 RTM_STORAGE_TYPE_USER 类型的 onStorageEvent 事件通知。详见事件监听。

信息

该方法不能对不存在的 Metadata Item 进行操作。

接口方法

你可以通过以下方式调用 updateUserMetadata 方法：

C++
virtual void updateUserMetadata(
    const char* userId, const Metadata& data,
    const MetadataOptions& options, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 ID。
dataconst Metadata&必填-Metadata Item。详见 Metadata。
optionsconst MetadataOptions&必填-Channel Metadata 配置选项。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataOptions 数据类型包含以下属性：

属性类型是否必填默认值描述
recordTsbool选填false是否记录编辑的时间戳。
recordUserIdbool选填false是否记录编辑者的用户 ID。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onUpdateUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<MetadataItem> items;
items.emplace_back(MetadataItem("Apple", "100", 174298200));
metadata.items = items.data();
metadata.itemCount = items.size();

MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;

uint64_t requestId;
rtmClient->getStorage()->updateUserMetadata("Tony", metadata, options, requestId);

subscribeUserMetadata

接口描述

subscribeUserMetadata 方法可以订阅指定用户的 Metadata。

成功订阅且开启事件监听后，当该用户的 Metadata 发生变更时会收到 RTM_STORAGE_TYPE_USER 类型的 onStorageEvent 事件通知。详见事件监听。

接口方法

你可以通过以下方式调用 subscribeUserMetadata 方法：

C++
virtual void subscribeUserMetadata(const char* userId, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 ID。
requestIduint64_t&必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onSubscribeUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
// 方法调用
uint64_t requestId;
rtmClient->getStorage()->subscribeUserMetadata("Tony", requestId);

unsubscribeUserMetadata

接口描述

如果你不需要接收某个用户 User Metadata 的变更通知，调用 unsubscribeUserMetadata 方法取消订阅。

接口方法

你可以通过以下方式调用 unsubscribeUserMetadata 方法：

C++
virtual void unsubscribeUserMetadata(const char* userId, uint64_t& requestId) = 0;
参数类型是否必填默认值描述
userIdconst char*必填-用户 ID。
requestIdconst uint64_t必填-（输出参数）请求标识符，后续用于识别和处理相应的请求。
表格内容超出当前宽度，可横向滚动查看更多列。

异步回调

调用该方法后，SDK 会触发 onUnsubscribeUserMetadataResult 回调并通过以下参数返回 API 调用结果：

参数类型描述
requestIdconst uint64_t请求标识符。
userIdconst char*用户 ID。
errorCodeRTM_ERROR_CODE错误码，详见错误排查。
表格内容超出当前宽度，可横向滚动查看更多列。

基本用法

C++
uint64_t requestId;
rtm_client->getStorage()->unsubscribeUserMetadata("Tony", requestId);
C++
// 异步回调
class RtmEventHandler : public IRtmEventHandler {
    void onUnsubscribeUserMetadataResult(const uint64_t requestId, const char* userId, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("UnsubscribeUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("UnsubscribeUserMetadata success\n");
        }
    }
};

Metadata

设置和管理 Metadata 的数据结构。包含以下属性：

属性类型是否必填默认值描述
majorRevisionint64_t选填-1

设置版本控制开关：

  • -1: 关闭版本校验。

  • 0: 开启版本校验，只有目标版本号与此值相符才能执行操作。

itemsMetadataItem*选填NULL设置 Metadata Item。
itemCountsize_t选填0Metadata Item 数组的长度。
表格内容超出当前宽度，可横向滚动查看更多列。

MetadataItem 数据类型包含以下属性：

属性类型是否必填默认值描述
keyconst char*选填-键。
valueconst char*选填-值。
authorUserIdconst char*选填-编辑者的用户 ID。该值为只读，不支持写入。
revisionint64_t选填-1
  • 在读取操作时作为真实版本号返回。
  • 在写入操作时作为版本控制开关：
    • -1: 关闭版本校验。

    • 0: 开启版本校验，只有目标版本号与此值相符才执行操作。

updateTsint64_t选填0更新时间戳。该值为只读，不支持写入。
表格内容超出当前宽度，可横向滚动查看更多列。

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利