插件
enableExtension
启用或禁用插件。
C++
virtual int enableExtension(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, bool enable = true) = 0;
通过调用该方法，你可以在不更改处理流程的情况下动态启用或禁用插件。例如，启用或禁用 Extension_A 表示数据将被 Extension_A 处理或绕过。
信息
参数
- provider
- 插件提供方的名称，例如
agora.io。 - extension
- 插件名称，例如
agora.beauty。 - extensionInfo
ExtensionInfo对象，表示插件的信息。- enable
- 是否启用插件：
- true：（默认）启用插件。
- false：禁用插件。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
getExtensionProperty
获取扩展属性。
C++
virtual int getExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, char* value, int buf_len) = 0;
参数
- provider
- 扩展提供方的名称，例如声网（agora.io）。
- extension
- 扩展的名称，例如
agora.beauty。 - extensionInfo
- 扩展信息。详见
ExtensionInfo。 - key
- 扩展属性的键名。
- value
- 输出参数，表示扩展属性键对应的值。
- buf_len
- 扩展属性值的最大长度（以 JSON 字符串形式表示）。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
loadExtensionProvider
加载扩展。
C++
virtual int loadExtensionProvider(const char* path, bool unload_after_use = false) = 0;
该方法用于将 SDK 外部的扩展（例如来自云市场或 SDK 扩展）加载到 SDK 中。
信息
如果你需要加载多个扩展，需要多次调用该方法。仅适用于 Windows 和 Android 平台。
调用时机
请确保在调用该方法前已初始化 IRtcEngine。
参数
- path
- 扩展库的路径和名称。例如：
/library/libagora_segmentation_extension.dll。 - unload_after_use
- 是否在不再使用当前扩展时卸载该扩展：
- true：当 IRtcEngine 被销毁时卸载该扩展。
- false：（推荐）直到进程终止前都不卸载该扩展。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
registerExtension
注册一个扩展。
C++
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 后会自动加载并注册。
信息
- 如果你想注册多个扩展，需要多次调用此方法。
- SDK 中不同扩展的数据处理顺序由注册顺序决定，即先注册的扩展会优先处理数据。
调用时机
声网建议你在初始化 IRtcEngine 后、加入频道前调用此方法。
- 对于视频扩展（如美颜特效扩展），你需要在调用 enableVideo 或 enableLocalVideo 启用视频模块后再调用此方法。
- 在调用此方法前，你需要先调用 loadExtensionProvider 加载扩展。
参数
- provider
- 扩展提供方的名称。
- extension
- 扩展的名称。
- type
- 扩展的数据源类型，详见 MEDIA_SOURCE_TYPE。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
- -3：扩展库未加载。声网建议你检查动态库的存储位置或名称。
setExtensionProperty
设置插件的属性。
C++
virtual int setExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, const char* value) = 0;
参数
- provider
- 插件提供方的名称，例如
agora.io。 - extension
- 插件名称，例如
agora.beauty。 - extensionInfo
- 插件信息，详见
ExtensionInfo。 - key
- 插件属性的键名。
- value
- 插件属性键对应的值，采用 JSON 格式。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
setExtensionProviderProperty
设置扩展提供方的属性。
C++
virtual int setExtensionProviderProperty(const char* provider, const char* key, const char* value) = 0;
调用该方法可设置扩展提供方的属性，并根据提供方的类型初始化相关参数。
信息
如果你想为多个扩展设置扩展提供方的属性，需要多次调用该方法。
调用时机
在调用 enableExtension 之前，调用 registerExtension 之后。
参数
- provider
- 扩展提供方的名称。
- key
- 扩展属性的键名。
- value
- 扩展属性键对应的值。
返回值
- 0：方法调用成功。
- < 0：方法调用失败。详见错误码了解详情和解决建议。
onExtensionErrorWithContext
扩展运行异常时触发的回调。
C++
virtual void onExtensionErrorWithContext(const ExtensionContext &context, int error, const char* message)
当扩展启用失败或运行时发生错误时，会触发该回调，并返回错误码和错误原因。
参数
- context
- 扩展的上下文信息。详见 ExtensionContext。
- error
- 错误码。详见扩展提供方的扩展文档。
- message
- 错误原因。详见扩展提供方的扩展文档。
onExtensionEventWithContext
扩展事件回调。
C++
virtual void onExtensionEventWithContext(const ExtensionContext &context, const char* key, const char* value)
在扩展运行期间监听事件时，你需要注册该回调。
参数
- context
- 扩展的上下文信息。详见 ExtensionContext。
- key
- 扩展事件的键。
- value
- 扩展事件键对应的值。
onExtensionStartedWithContext
onExtensionStartedWithContext 回调。当扩展启用成功时触发。
C++
virtual void onExtensionStartedWithContext(const ExtensionContext &context)
参数
- context
- 扩展的上下文信息。详见 ExtensionContext。
onExtensionStoppedWithContext
onExtensionStoppedWithContext 回调：扩展被禁用时触发。
C++
virtual void onExtensionStoppedWithContext(const ExtensionContext &context)
触发时机
当扩展被成功禁用后触发该回调。
参数
- context
- 扩展的上下文信息。详见 ExtensionContext。