# 本地截图上传 (/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## enableContentInspect [#enablecontentinspect]
启用或关闭本地截图上传功能。
```cpp
virtual int enableContentInspect(bool enabled, const media::ContentInspectConfig &config) = 0;
```
启用该功能后,SDK 会根据你在 [ContentInspectConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig) 中设置的模块类型和频率,对本地用户发送的视频进行截图并上传。截图和上传完成后,声网服务器会通过 HTTPS 请求将回调通知发送到你的应用服务器,并将所有截图上传至第三方云存储服务。
:::note
注:
- 在调用该方法前,请确保你已在声网控制台启用了本地截图上传功能。
- 当视频审核模块设置为使用声网自研扩展(`CONTENT_INSPECT_SUPERVISION`)进行视频审核时,需要使用本地截图上传动态库 libagora_content_inspect_extension.dll。删除该库将禁用截图上传功能。
:::
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数]
是否启用本地截图上传功能:
- true:启用本地截图上传功能。
- false:关闭本地截图上传功能。
截图上传配置,详见 [ContentInspectConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## enableContentInspectEx [#enablecontentinspectex]
启用或关闭本地截图上传功能。
```cpp
virtual int enableContentInspectEx(bool enabled, const media::ContentInspectConfig &config, const RtcConnection& connection) = 0;
```
该方法可对多个视频流进行截图并上传。启用该功能后,SDK 会根据你在 [ContentInspectConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig) 中设置的模块类型和频率,对本地用户发送的视频进行截图并上传。截图上传完成后,声网服务器会通过 HTTPS 请求将回调通知发送至你的应用服务器,并将所有截图上传至第三方云存储服务。
:::note
注: 调用该方法前,请确保你已在声网控制台启用了本地截图上传功能。
:::
### 适用场景 [#适用场景]
该方法适用于多频道场景。
### 调用时机 [#调用时机-1]
该方法可在加入频道前或加入频道后调用。
### 参数 [#参数-1]
是否启用本地截图上传功能:
- true:启用本地截图上传功能。
- false:关闭本地截图上传功能。
截图和上传的配置。详见 [ContentInspectConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-contentinspectconfig)。
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)
## takeSnapshot [1/2] [#takesnapshot-12]
截取视频流快照。
```cpp
virtual int takeSnapshot(uid_t uid, const char* filePath) = 0;
```
该方法用于从指定用户的视频流中截取一帧图像,生成 JPG 图片,并保存到指定路径。
:::note
注:
- 该方法为异步调用,调用返回时 SDK 尚未完成截图操作。
- 用于本地视频截图时,该方法会对 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中指定的视频流进行截图。如果用户的视频已进行预处理,例如添加水印或美颜,截图结果中会包含这些预处理效果。
:::
### 调用时机 [#调用时机-2]
请在加入频道后调用该方法。
### 相关回调 [#相关回调]
成功调用该方法后,SDK 会触发 [onSnapshotTaken](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 回调,报告截图是否成功以及截图的详细信息。
### 参数 [#参数-2]
用户 ID。若要截取本地用户的视频,请将 `uid` 设置为 0。
:::note
注: 请确保指定路径存在且可写。
:::
截图的本地路径(包含文件扩展名)。例如:
- Windows: C:\\Users\\<user_name>\\AppData\\Local\\Agora\\<process_name>\\example.jpg
- iOS: `/App Sandbox/Library/Caches/example.jpg`
- macOS: `~/Library/Logs/example.jpg`
- Android: `/storage/emulated/0/Android/data//files/example.jpg`
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## takeSnapshot [2/2] [#takesnapshot-22]
截取指定观察点的视频截图。
```cpp
virtual int takeSnapshot(uid_t uid, const media::SnapshotConfig& config) = 0;
```
:::note
注:
- 该方法为异步方法,调用返回时 SDK 尚未完成截图操作。
- 用于本地视频截图时,会对 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中指定的视频流进行截图。
:::
### 调用时机 [#调用时机-3]
在加入频道后调用该方法。
### 相关回调 [#相关回调-1]
成功调用该方法后,SDK 会触发 [onSnapshotTaken](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 回调,报告截图是否成功以及截图的详细信息。
### 参数 [#参数-3]
用户 ID。若要截取本地用户的视频,请将 `uid` 设置为 0。
截图配置,详见 [SnapshotConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-snapshotconfig)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## takeSnapshotEx [1/2] [#takesnapshotex-12]
使用连接 ID 对指定用户的视频流进行截图。
```cpp
virtual int takeSnapshotEx(const RtcConnection& connection, uid_t uid, const char* filePath) = 0;
```
该方法为异步调用,调用该方法时 SDK 尚未完成截图操作。用于本地视频截图时,会对 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中指定的视频流进行截图。如果用户的视频已被预处理(如添加水印或美颜),截图结果中会包含这些预处理效果。
### 适用场景 [#适用场景-1]
适用于多频道场景。
### 调用时机 [#调用时机-4]
请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 后调用该方法。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onSnapshotTaken](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 回调,报告截图是否成功以及截图的详细信息。
### 参数 [#参数-4]
连接信息,详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。
用户 ID。若要对本地用户的视频进行截图,请将 `uid` 设置为 0。
:::note
注: 请确保指定的路径存在且可写。
:::
截图的本地路径(包含文件扩展名)。例如:
- Windows: C:\\Users\\<user_name>\\AppData\\Local\\Agora\\<process_name>\\example.jpg
- iOS: `/App Sandbox/Library/Caches/example.jpg`
- macOS: `~/Library/Logs/example.jpg`
- Android: `/storage/emulated/0/Android/data//files/example.jpg`
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)
## takeSnapshotEx [2/2] [#takesnapshotex-22]
通过连接 ID 获取指定用户的视频截图。
```cpp
virtual int takeSnapshotEx(const RtcConnection& connection, uid_t uid, const media::SnapshotConfig& config) = 0;
```
该方法从指定用户的视频流中截取一帧图像,生成 JPG 图片,并保存到指定路径。截图结果中会包含视频预处理效果,例如水印或美颜。
:::note
注:
- 该方法为异步调用,调用返回时 SDK 尚未完成截图操作。
- 用于本地视频截图时,将对 [ChannelMediaOptions](/zh-CN/api-reference/rtc/cpp-all-platforms/class-channelmediaoptions) 中指定的视频流进行截图。
:::
### 适用场景 [#适用场景-2]
适用于多频道场景。
### 调用时机 [#调用时机-5]
请在调用 [joinChannelEx](/zh-CN/api-reference/rtc/cpp-all-platforms/channel#api_irtcengineex_joinchannelex) 后调用该方法。
### 相关回调 [#相关回调-3]
成功调用该方法后,SDK 会触发 [onSnapshotTaken](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-prenpro/snapshot#callback_irtcengineeventhandler_onsnapshottaken) 回调,报告截图是否成功以及截图的详细信息。
### 参数 [#参数-5]
连接信息。详见 [RtcConnection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-rtcconnection)。
用户 ID。
:::note
注: 若要截取本地用户的视频,请将 `uid` 设置为 0。
:::
截图配置。详见 [SnapshotConfig](/zh-CN/api-reference/rtc/cpp-all-platforms/class-snapshotconfig)。
### 返回值 [#返回值-5]
- 0:调用成功。
- < 0:调用失败。
### 所属接口类 [#所属接口类-5]
- [IRtcEngineEx](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineex)
## onSnapshotTaken [#onsnapshottaken]
截图结果回调。
```cpp
virtual void onSnapshotTaken(uid_t uid, const char* filePath, int width, int height, int errCode)
```
调用 `takeSnapshot` 方法成功后,SDK 会触发该回调,用于报告截图是否成功以及截图的详细信息。
### 触发时机 [#触发时机]
调用 `takeSnapshot` 方法成功后触发。
### 参数 [#参数-6]
用户 ID。`uid` 为 0 表示本地用户。
截图的本地路径。
截图的宽度(像素)。
截图的高度(像素)。
截图结果的错误码:
- 0:成功。
- < 0:失败:
- -1:SDK 写入文件或编码 JPEG 图像失败。
- -2:调用 `takeSnapshot` 方法成功后 1 秒内未找到指定用户的视频流。可能原因包括:本地采集停止、远端停止发布或视频数据处理阻塞。
- -3:调用 `takeSnapshot` 方法过于频繁。
### 所属接口类 [#所属接口类-6]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)