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