# 插件 (/zh-CN/api-reference/rtc/cpp-all-platforms/extension)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## enableExtension [#enableextension]
启用或禁用插件。
```cpp
virtual int enableExtension(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, bool enable = true) = 0;
```
通过调用该方法,你可以在不更改处理流程的情况下动态启用或禁用插件。例如,启用或禁用 `Extension_A` 表示数据将被 `Extension_A` 处理或绕过。
:::note
注: 出于兼容性考虑,如果你尚未调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension),[enableExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_enableextension) 会自动注册指定的插件。建议你显式调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension)。
:::
### 参数 [#参数]
插件提供方的名称,例如 `agora.io`。
插件名称,例如 `agora.beauty`。
`ExtensionInfo` 对象,表示插件的信息。
是否启用插件:
- true:(默认)启用插件。
- false:禁用插件。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## getExtensionProperty [#getextensionproperty]
获取扩展属性。
```cpp
virtual int getExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, char* value, int buf_len) = 0;
```
### 参数 [#参数-1]
扩展提供方的名称,例如声网(agora.io)。
扩展的名称,例如 `agora.beauty`。
扩展信息。详见 `ExtensionInfo`。
扩展属性的键名。
输出参数,表示扩展属性键对应的值。
扩展属性值的最大长度(以 JSON 字符串形式表示)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## loadExtensionProvider [#loadextensionprovider]
加载扩展。
```cpp
virtual int loadExtensionProvider(const char* path, bool unload_after_use = false) = 0;
```
该方法用于将 SDK 外部的扩展(例如来自云市场或 SDK 扩展)加载到 SDK 中。
:::note
注: 如果你需要加载多个扩展,需要多次调用该方法。仅适用于 Windows 和 Android 平台。
:::
### 调用时机 [#调用时机]
请确保在调用该方法前已初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)。
### 参数 [#参数-2]
扩展库的路径和名称。例如:`/library/libagora_segmentation_extension.dll`。
是否在不再使用当前扩展时卸载该扩展:
- true:当 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 被销毁时卸载该扩展。
- false:(推荐)直到进程终止前都不卸载该扩展。
### 返回值 [#返回值-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)
## registerExtension [#registerextension]
注册一个扩展。
```cpp
virtual int registerExtension(const char* provider, const char* extension, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
```
对于 SDK 外部的扩展(例如来自云市场和 SDK 扩展),你需要在调用该方法前先加载它们。对于 SDK 内部的扩展(即包含在完整 SDK 包中的扩展),在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 后会自动加载并注册。
:::note
注:
- 如果你想注册多个扩展,需要多次调用此方法。
- SDK 中不同扩展的数据处理顺序由注册顺序决定,即先注册的扩展会优先处理数据。
:::
### 调用时机 [#调用时机-1]
声网建议你在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 后、加入频道前调用此方法。
- 对于视频扩展(如美颜特效扩展),你需要在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 或 [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo) 启用视频模块后再调用此方法。
- 在调用此方法前,你需要先调用 [loadExtensionProvider](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_loadextensionprovider) 加载扩展。
### 参数 [#参数-3]
扩展提供方的名称。
扩展的名称。
扩展的数据源类型,详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-mediasourcetype)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -3:扩展库未加载。声网建议你检查动态库的存储位置或名称。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## setExtensionProperty [#setextensionproperty]
设置插件的属性。
```cpp
virtual int setExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, const char* value) = 0;
```
### 参数 [#参数-4]
插件提供方的名称,例如 `agora.io`。
插件名称,例如 `agora.beauty`。
插件信息,详见 `ExtensionInfo`。
插件属性的键名。
插件属性键对应的值,采用 JSON 格式。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## setExtensionProviderProperty [#setextensionproviderproperty]
设置扩展提供方的属性。
```cpp
virtual int setExtensionProviderProperty(const char* provider, const char* key, const char* value) = 0;
```
调用该方法可设置扩展提供方的属性,并根据提供方的类型初始化相关参数。
:::note
注: 如果你想为多个扩展设置扩展提供方的属性,需要多次调用该方法。
:::
### 调用时机 [#调用时机-2]
在调用 [enableExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_enableextension) 之前,调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension) 之后。
### 参数 [#参数-5]
扩展提供方的名称。
扩展属性的键名。
扩展属性键对应的值。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)
## onExtensionErrorWithContext [#onextensionerrorwithcontext]
扩展运行异常时触发的回调。
```cpp
virtual void onExtensionErrorWithContext(const ExtensionContext &context, int error, const char* message)
```
当扩展启用失败或运行时发生错误时,会触发该回调,并返回错误码和错误原因。
### 参数 [#参数-6]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-extensioncontext)。
错误码。详见扩展提供方的扩展文档。
错误原因。详见扩展提供方的扩展文档。
### 所属接口类 [#所属接口类-6]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onExtensionEventWithContext [#onextensioneventwithcontext]
扩展事件回调。
```cpp
virtual void onExtensionEventWithContext(const ExtensionContext &context, const char* key, const char* value)
```
在扩展运行期间监听事件时,你需要注册该回调。
### 参数 [#参数-7]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-extensioncontext)。
扩展事件的键。
扩展事件键对应的值。
### 所属接口类 [#所属接口类-7]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onExtensionStartedWithContext [#onextensionstartedwithcontext]
[onExtensionStartedWithContext](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) 回调。当扩展启用成功时触发。
```cpp
virtual void onExtensionStartedWithContext(const ExtensionContext &context)
```
### 参数 [#参数-8]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-extensioncontext)。
### 所属接口类 [#所属接口类-8]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)
## onExtensionStoppedWithContext [#onextensionstoppedwithcontext]
[onExtensionStoppedWithContext](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) 回调:扩展被禁用时触发。
```cpp
virtual void onExtensionStoppedWithContext(const ExtensionContext &context)
```
### 触发时机 [#触发时机]
当扩展被成功禁用后触发该回调。
### 参数 [#参数-9]
扩展的上下文信息。详见 [ExtensionContext](/zh-CN/api-reference/rtc/cpp-all-platforms/class-extensioncontext)。
### 所属接口类 [#所属接口类-9]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)