# Storage (/zh-CN/api-reference/rtm/cpp/storage) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). RTM 的 Storage 功能提供了一套动态数据库机制,可以让开发者动态设置、存储、更新、删除 Channel Metadata 和 User Metadata 等数据。 ## setChannelMetadata [#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` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 ### 接口方法 [#接口方法] 你可以通过以下方式调用 `setChannelMetadata` 方法: ```cpp virtual void setChannelMetadata( const char* channelName, RTM_CHANNEL_TYPE channelType, const Metadata& data, const MetadataOptions& options, const char* lockName, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | const char* | 必填 | - | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 必填 | - | 频道类型。详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `lockName` | const char* | 必填 | - | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ----------- | ---- | ----- | ---- | ----------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调] 调用该方法后,SDK 会触发 `onSetChannelMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `channelName` | const char* | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 频道类型,详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 接口方法 [#接口方法-1] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onSetChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("SetChannelMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("SetChannelMetadata success\n"); } } }; ``` ## getChannelMetadata [#getchannelmetadata] ### 接口描述 [#接口描述-1] `getChannelMetadata` 方法可以获取指定频道的 Metadata。 ### 接口方法 [#接口方法-2] 你可以通过以下方式调用 `getChannelMetadata` 方法: ```cpp virtual void getChannelMetadata( const char* channelName, RTM_CHANNEL_TYPE channelType, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | const char* | 必填 | - | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 必填 | - | 频道类型。详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | ### 异步回调 [#异步回调-1] 调用该方法后,SDK 会触发 `onGetChannelMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `channelName` | const char* | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 频道类型,详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `data` | `const Metadata&` | Metadata Item。详见 [`Metadata`](#metadata)。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 接口方法 [#接口方法-3] ```cpp tab="方法调用" // 方法调用 uint64_t requestId; rtmClient->getStorage()->getChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, requestId); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onGetChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, const Metadata& data, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("GetChannelMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("GetChannelMetadata success %d channel: %s, channel type: %d\n"); for (int i = 0 ; i < data.itemCount; i++) { printf("key: %s value: %s revision: %lld\n", data.items[i].key, data.items[i].value, data.items[i].revision); } } } }; ``` ## removeChannelMetadata [#removechannelmetadata] ### 接口描述 [#接口描述-2] `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` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 ### 接口方法 [#接口方法-4] 你可以通过以下方式调用 `removeChannelMetadata` 方法: ```cpp virtual void removeChannelMetadata( const char* channelName, RTM_CHANNEL_TYPE channelType, const Metadata& data, const MetadataOptions& options, const char* lockName, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | const char* | 必填 | - | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 必填 | - | 频道类型。详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `lockName` | const char* | 必填 | - | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ----------- | ---- | ----- | ---- | ----------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调-2] 调用该方法后,SDK 会触发 `onRemoveChannelMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `channelName` | const char* | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 频道类型,详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 接口方法 [#接口方法-5] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onRemoveChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("RemoveChannelMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("RemoveChannelMetadata success\n"); } } }; ``` ## updateChannelMetadata [#updatechannelmetadata] ### 接口描述 [#接口描述-3] `updateChannelMetadata` 方法可以更新已有的 Channel Metadata。每次调用该方法,你可以更新一个 Channel Metadata,也可以更新一个或多个 Channel Metadata Item 数组。 成功更新后,订阅该频道且开启事件监听的用户会收到 `RTM_STORAGE_TYPE_CHANNEL` 类型的 `onStorageEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 :::info[信息] 该方法不能对不存在的 Metadata Item 进行操作。 ::: ### 接口方法 [#接口方法-6] 你可以通过以下方式调用 `updateChannelMetadata` 方法: ```cpp virtual void updateChannelMetadata( const char* channelName, RTM_CHANNEL_TYPE channelType, const Metadata& data, const MetadataOptions& options, const char* lockName, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `channelName` | const char* | 必填 | - | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 必填 | - | 频道类型。详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `lockName` | const char* | 必填 | - | Lock 名称。设置后,只有调用 `acquireLock` 方法获取该锁的用户才能执行操作。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ----------- | ---- | ----- | ---- | ----------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调-3] 调用该方法后,SDK 会触发 `onUpdateChannelMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `channelName` | const char* | 频道名称。 | | `channelType` | `RTM_CHANNEL_TYPE` | 频道类型,详见 [`RTM_CHANNEL_TYPE`](/zh-CN/api-reference/rtm/cpp/enumv#channeltype)。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onUpdateChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("UpdateChannelMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("UpdateChannelMetadata success\n"); } } }; ``` ## setUserMetadata [#setusermetadata] ### 接口描述 [#接口描述-4] `setUserMetadata` 方法可以设置 User Metadata。如果多次调用该方法时,SDK 会依次检索 User Metadata Item 的 `key` 值,并按如下规则处理: - 如果设置的 Metadata Item key 值不同,则会根据调用顺序依次增加。 - 如果设置的 Metadata Item key 值相同,则最后一次设置的 Metadata 的 value 会覆盖之前的值。 成功设置 User Metadata 后,订阅该用户 Metadata 且开启事件监听的用户会收到 `RTM_STORAGE_TYPE_USER` 类型的 `onStorageEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 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 会返回错误码。 ### 接口方法 [#接口方法-7] 你可以通过以下方式调用 `setUserMetadata` 方法: ```cpp virtual void setUserMetadata( const char* userId, const Metadata& data, const MetadataOptions& options, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 ID。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ----------- | ---- | ----- | ---- | ----------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调-4] 调用该方法后,SDK 会触发 `onSetUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-1] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onSetUserMetadataResult(const uint64_t requestId, const char *userId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("SetUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("SetUserMetadata success\n"); } } }; ``` ## getUserMetadata [#getusermetadata] ### 接口描述 [#接口描述-5] `getUserMetadata` 方法可以获取指定用户的 Metadata 和 User Metadata Item。 ### 接口方法 [#接口方法-8] 你可以通过以下方式调用 `getUserMetadata` 方法: ```cpp virtual void getUserMetadata(const char* userId, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 `userId`。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | ### 异步回调 [#异步回调-5] 调用该方法后,SDK 会触发 `onGetUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `data` | `const Metadata&` | Metadata Item。详见 [`Metadata`](#metadata)。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-2] ```cpp tab="方法调用" // 方法调用 uint64_t requestId; rtmClient->getStorage()->getUserMetadata("Tony", requestId); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onGetUserMetadataResult(const uint64_t requestId, const char *userId, const Metadata& data, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("GetUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("GetUserMetadata success user id: %s\n", userId); for (int i = 0 ; i < data.itemCount; i++) { printf("key: %s value: %s revision: %lld\n", data.items[i].key, data.items[i].value, data.items[i].revision); } } } }; ``` ## removeUserMetadata [#removeusermetadata] ### 接口描述 [#接口描述-6] `removeUserMetadata` 方法可以删除 User Metadata 或某几个 User Metadata Item。 成功删除后,订阅该用户 Metadata 且开启事件监听的用户会收到 `RTM_STORAGE_TYPE_USER` 类型的 `onStorageEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 ### 接口方法 [#接口方法-9] 你可以通过以下方式调用 `removeUserMetadata` 方法: ```cpp virtual void removeUserMetadata( const char* userId, const Metadata& data, const MetadataOptions& options, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 ID。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ----------- | ---- | ----- | ---- | ----------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调-6] 调用该方法后,SDK 会触发 `onRemoveUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-3] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onRemoveUserMetadataResult(const uint64_t requestId, const char *userId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("RemoveUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("RemoveUserMetadata success\n"); } } }; ``` ## updateUserMetadata [#updateusermetadata] ### 接口描述 [#接口描述-7] `updateUserMetadata` 方法可以更新已有的 User Metadata 或 Metadata Item。 成功更新后,订阅该 User Metadata 且开启事件监听的用户会收到 `RTM_STORAGE_TYPE_USER` 类型的 `onStorageEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 :::info[信息] 该方法不能对不存在的 Metadata Item 进行操作。 ::: ### 接口方法 [#接口方法-10] 你可以通过以下方式调用 `updateUserMetadata` 方法: ```cpp virtual void updateUserMetadata( const char* userId, const Metadata& data, const MetadataOptions& options, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 ID。 | | `data` | `const Metadata&` | 必填 | - | Metadata Item。详见 [`Metadata`](#metadata)。 | | `options` | `const MetadataOptions&` | 必填 | - | Channel Metadata 配置选项。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | `MetadataOptions` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | ------------ | ---- | ----- | ---- | ------------- | | `recordTs` | bool | 选填 | `false` | 是否记录编辑的时间戳。 | | `recordUserId` | bool | 选填 | `false` | 是否记录编辑者的用户 ID。 | ### 异步回调 [#异步回调-7] 调用该方法后,SDK 会触发 `onUpdateUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-4] ```cpp tab="方法调用" // 方法调用 Metadata metadata; metadata.majorRevision = 174298270; std::vector 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); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onUpdateUserMetadataResult(const uint64_t requestId, const char *userId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("UpdateUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("UpdateUserMetadata success\n"); } } }; ``` ## subscribeUserMetadata [#subscribeusermetadata] ### 接口描述 [#接口描述-8] `subscribeUserMetadata` 方法可以订阅指定用户的 Metadata。 成功订阅且开启事件监听后,当该用户的 Metadata 发生变更时会收到 `RTM_STORAGE_TYPE_USER` 类型的 `onStorageEvent` 事件通知。详见[事件监听](/zh-CN/api-reference/rtm/cpp/configuration#事件监听)。 ### 接口方法 [#接口方法-11] 你可以通过以下方式调用 `subscribeUserMetadata` 方法: ```cpp virtual void subscribeUserMetadata(const char* userId, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 ID。 | | `requestId` | uint64_t& | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | 异步回调 调用该方法后,SDK 会触发 `onSubscribeUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-5] ```cpp tab="方法调用" // 方法调用 uint64_t requestId; rtmClient->getStorage()->subscribeUserMetadata("Tony", requestId); ``` ```cpp tab="异步回调" // 异步回调 class RtmEventHandler : public IRtmEventHandler { void onSubscribeUserMetadataResult(const uint64_t requestId, const char *userId, RTM_ERROR_CODE errorCode) override { if (errorCode != RTM_ERROR_OK) { printf("SubscribeUserMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode)); } else { printf("SubscribeUserMetadata success\n"); } } }; ``` ## unsubscribeUserMetadata [#unsubscribeusermetadata] ### 接口描述 [#接口描述-9] 如果你不需要接收某个用户 User Metadata 的变更通知,调用 `unsubscribeUserMetadata` 方法取消订阅。 ### 接口方法 [#接口方法-12] 你可以通过以下方式调用 `unsubscribeUserMetadata` 方法: ```cpp virtual void unsubscribeUserMetadata(const char* userId, uint64_t& requestId) = 0; ``` | 参数 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `userId` | const char* | 必填 | - | 用户 ID。 | | `requestId` | const uint64_t | 必填 | - | (输出参数)请求标识符,后续用于识别和处理相应的请求。 | ### 异步回调 [#异步回调-8] 调用该方法后,SDK 会触发 `onUnsubscribeUserMetadataResult` 回调并通过以下参数返回 API 调用结果: | 参数 | 类型 | 描述 | | --- | --- | --- | | `requestId` | const uint64_t | 请求标识符。 | | `userId` | const char* | 用户 ID。 | | `errorCode` | `RTM_ERROR_CODE` | 错误码,详见[错误排查](/zh-CN/realtime-media/rtm/build/troubleshooting)。 | ### 基本用法 [#基本用法-6] ```cpp uint64_t requestId; rtm_client->getStorage()->unsubscribeUserMetadata("Tony", requestId); ``` ```cpp // 异步回调 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] 设置和管理 Metadata 的数据结构。包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `majorRevision` | int64_t | 选填 | `-1` | [storage-cpp-html-20-1-4 details](#table-slot-storage-cpp-html-20-1-4) | | `items` | `MetadataItem*` | 选填 | `NULL` | 设置 Metadata Item。 | | `itemCount` | size_t | 选填 | `0` | Metadata Item 数组的长度。 | **storage-cpp-html-20-1-4 details** 设置版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才能执行操作。 `MetadataItem` 数据类型包含以下属性: | 属性 | 类型 | 是否必填 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | `key` | const char* | 选填 | - | 键。 | | `value` | const char* | 选填 | - | 值。 | | `authorUserId` | const char* | 选填 | - | 编辑者的用户 ID。该值为只读,不支持写入。 | | `revision` | int64_t | 选填 | `-1` | [storage-cpp-html-21-4-4 details](#table-slot-storage-cpp-html-21-4-4) | | `updateTs` | int64_t | 选填 | `0` | 更新时间戳。该值为只读,不支持写入。 | **storage-cpp-html-21-4-4 details** - 在读取操作时作为真实版本号返回。 - 在写入操作时作为版本控制开关: - `-1`: 关闭版本校验。 - > `0`: 开启版本校验,只有目标版本号与此值相符才执行操作。