# 插件 (/zh-CN/api-reference/rtc/unreal-blueprint/extension)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## EnableExtension [#enableextension]
启用/禁用插件。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int EnableExtension(const FString& provider, const FString& extension, bool enable = true, EMEDIA_SOURCE_TYPE type = EMEDIA_SOURCE_TYPE::UNKNOWN_MEDIA_SOURCE);
```
### 调用时机 [#调用时机]
建议你在加入频道后调用该方法。
### 调用限制 [#调用限制]
- 如果要开启多个插件,需要多次调用该方法。
- 该方法调用成功后,无法再加载其他插件。
### 相关回调 [#相关回调]
频道内调用该方法成功时会触发插件启用回调 [OnExtensionStartedWithContext](/zh-CN/api-reference/rtc/unreal-blueprint/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) 或插件禁用回调 [OnExtensionStoppedWithContext](/zh-CN/api-reference/rtc/unreal-blueprint/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext)。
### 参数 [#参数]
提供插件的服务商名称。
插件的名称。
是否启用插件:
- `true`: 启用插件。
- `false`: 禁用插件。
插件的媒体源类型。详见 [EUABT_MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-blueprint/enum-mediasourcetype)。
### 返回值 [#返回值]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置,或该动态库名是否正确。
### 所属接口类 [#所属接口类]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## GetExtensionProperty [#getextensionproperty]
获取插件的详细信息。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int GetExtensionProperty(const FString& provider, const FString& extension,const FExtensionInfo & ExtensionInfo, const FString& key, FString& value);
```
### 调用时机 [#调用时机-1]
加入频道前后均可调用。
### 调用限制 [#调用限制-1]
无。
### 参数 [#参数-1]
输出参数。提供插件的服务商名称。
输出参数。插件的名称。
输出参数。插件属性的 Key。
输出参数。插件属性 Key 对应的值。
插件的媒体源类型。详见 [EUABT_MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-blueprint/enum-mediasourcetype)。
插件属性 JSON 字符串的最大长度。最大值为 512 字节。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## LoadExtensionProvider [#loadextensionprovider]
加载插件。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int LoadExtensionProvider(const FString& path, bool unload_after_use);
```
该方法用于将 SDK 外部插件(例如云市场插件和 SDK 拓展插件)添加到 SDK 中。
### 调用时机 [#调用时机-2]
请在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine) 后立即调用该方法。
### 调用限制 [#调用限制-2]
如果要加载多个插件,需要多次调用该方法。
:::caution
注意: 该方法仅适用于 Windows 和 Android。
:::
### 参数 [#参数-2]
插件的动态库路径和名称。例如:`/library/libagora_segmentation_extension.dll`。
是否在插件使用完毕后自动卸载:
- `true`: 当 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine) 销毁时自动卸载插件。
- `false`: 不自动卸载插件,直到进程退出(推荐)。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## RegisterExtension [#registerextension]
注册插件。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int RegisterExtension(const FString& provider, const FString& extension, EMEDIA_SOURCE_TYPE type);
```
对于 SDK 外部的插件(例如云市场插件和 SDK 拓展插件),加载插件后,你需要调用该方法注册插件。SDK 内部插件(包含在 SDK 包中的插件)在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine) 后会自动加载并注册,无需调用该方法。
### 调用时机 [#调用时机-3]
- 建议你在初始化 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine) 后、加入频道前调用该方法。
- 对于视频相关插件(例如美颜插件),需要在启用视频模块([EnableVideo](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#api_irtcengine_enablevideo)/[EnableLocalVideo](/zh-CN/api-reference/rtc/unreal-blueprint/video/video-basic#api_irtcengine_enablelocalvideo))之前调用该方法。
- 调用该方法前,需要先调用 [LoadExtensionProvider](/zh-CN/api-reference/rtc/unreal-blueprint/extension#api_irtcengine_loadextensionprovider) 加载插件。
### 调用限制 [#调用限制-3]
- 如果要注册多个插件,需要多次调用该方法。
- 不同插件在 SDK 中处理数据的顺序由插件的注册顺序决定。即先注册的插件会先处理数据。
### 参数 [#参数-3]
提供插件的服务商名称。
插件的名称。
插件的媒体源类型。详见 [EUABT_MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-blueprint/enum-mediasourcetype)。
### 返回值 [#返回值-3]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置,或该动态库名是否正确。
### 所属接口类 [#所属接口类-3]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## SetExtensionProperty [#setextensionproperty]
设置插件的属性。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetExtensionProperty(const FString& provider, const FString& extension, const FString& key, const FString& value, EMEDIA_SOURCE_TYPE type = EMEDIA_SOURCE_TYPE::UNKNOWN_MEDIA_SOURCE);
```
开启插件后,你可以调用该方法设置插件的属性。
### 调用时机 [#调用时机-4]
请在调用 [EnableExtension](/zh-CN/api-reference/rtc/unreal-blueprint/extension#api_irtcengine_enableextension) 开启插件后调用该方法。
### 调用限制 [#调用限制-4]
如果要设置多个插件的属性,需要多次调用该方法。
### 相关回调 [#相关回调-1]
调用该方法后,可能会触发插件事件回调 [OnExtensionEventWithContext](/zh-CN/api-reference/rtc/unreal-blueprint/extension#callback_irtcengineeventhandler_onextensioneventwithcontext),具体触发逻辑与插件本身相关。
### 参数 [#参数-4]
提供插件的服务商名称。
插件的名称。
插件属性的 Key。
插件属性 Key 对应的值。
插件的媒体源类型。详见 [EUABT_MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/unreal-blueprint/enum-mediasourcetype)。
### 返回值 [#返回值-4]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## SetExtensionProviderProperty [#setextensionproviderproperty]
设置插件服务商的属性。
```cpp
UFUNCTION(BlueprintCallable, Category = "Agora|IRtcEngine")
int SetExtensionProviderProperty(const FString& provider, const FString& key, const FString& value);
```
你可以调用该方法设置插件服务商的属性,并根据服务商的类型初始化相关参数。
### 调用时机 [#调用时机-5]
请在调用 [RegisterExtension](/zh-CN/api-reference/rtc/unreal-blueprint/extension#api_irtcengine_registerextension) 之后、[EnableExtension](/zh-CN/api-reference/rtc/unreal-blueprint/extension#api_irtcengine_enableextension) 之前调用该方法。
### 调用限制 [#调用限制-5]
如果要设置多个插件服务商的属性,需要多次调用该方法。
### 参数 [#参数-5]
提供插件的服务商名称。
插件属性的 Key。
插件属性 Key 对应的值。
### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IRtcEngine](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengine)
## OnExtensionErrorWithContext [#onextensionerrorwithcontext]
插件出错回调。
```cpp
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnExtensionErrorWithContext(const FExtensionContext& context, int error, const FString& message);
```
### 详情 [#详情]
启用插件失败或者插件运行出错时,插件会触发该回调并报告错误码和错误原因。
### 参数 [#参数-6]
插件上下文信息,详见 [FExtensionContext](/zh-CN/api-reference/rtc/unreal-blueprint/class-extensioncontext)。
错误码。详见插件服务商提供的插件文档。
错误原因。详见插件服务商提供的插件文档。
### 所属接口类 [#所属接口类-6]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengineeventhandler)
## OnExtensionEventWithContext [#onextensioneventwithcontext]
插件事件回调。
```cpp
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnExtensionEventWithContext(const FExtensionContext& context, const FString& key, const FString& value);
```
### 详情 [#详情-1]
为监听插件事件,你需要注册该回调。
### 参数 [#参数-7]
插件上下文信息,详见 [FExtensionContext](/zh-CN/api-reference/rtc/unreal-blueprint/class-extensioncontext)。
插件属性的 Key。
插件属性 Key 对应的值。
### 所属接口类 [#所属接口类-7]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengineeventhandler)
## OnExtensionStartedWithContext [#onextensionstartedwithcontext]
插件已启用成功回调。
```cpp
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnExtensionStartedWithContext(const FExtensionContext& context);
```
### 详情 [#详情-2]
成功启用插件后会触发该回调。
### 参数 [#参数-8]
插件上下文信息,详见 [FExtensionContext](/zh-CN/api-reference/rtc/unreal-blueprint/class-extensioncontext)。
### 所属接口类 [#所属接口类-8]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengineeventhandler)
## OnExtensionStoppedWithContext [#onextensionstoppedwithcontext]
插件已禁用回调。
```cpp
UFUNCTION(BlueprintNativeEvent, Category = "Agora|Event")
void OnExtensionStoppedWithContext(const FExtensionContext& context);
```
### 详情 [#详情-3]
成功禁用插件后会触发该回调。
### 参数 [#参数-9]
插件上下文信息,详见 [FExtensionContext](/zh-CN/api-reference/rtc/unreal-blueprint/class-extensioncontext)。
### 所属接口类 [#所属接口类-9]
- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/unreal-blueprint/rtc-interface-class#class_irtcengineeventhandler)