# 插件 (/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)