插件

enableExtension

启用/禁用插件。

C++

virtual int enableExtension(
                    const char* provider, const char* extension, bool enable=true, agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;
                

如需调用本方法，请在初始化 IRtcEngine 对象后立即调用。

注：

• 如果要开启多个插件，需要多次调用该方法。

• 不同插件在 SDK 中处理数据的顺序由插件的开通顺序决定。即先开启的插件会先处理数据。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件的名称。
enable	是否启用插件： true: 启用插件。 false: 禁用插件。
type	媒体资源类型。详见 MEDIA_SOURCE_TYPE。 注意： 在该方法中，该参数仅支持以下两种设置： 默认值为 UNKNOWN_MEDIA_SOURCE。 如果要使用第二个摄像头采集视频，将该参数设置为 SECONDARY_CAMERA_SOURCE。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败

  • -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置或该动态库名是否正确。

所属接口类

• IRtcEngine

getExtensionProperty

获取插件的详细信息。

C++

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;

参数

参数名	描述
provider	输出参数。提供插件的服务商名称。
extension	输出参数。插件的名称。
key	输出参数。插件属性的 Key。
value	输出参数。插件属性 Key 对应的值。
type	插件的媒体源类型。详见 MEDIA_SOURCE_TYPE。
buf_len	插件属性 JSON 字符串的最大长度。最大值为 512 字节。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

loadExtensionProvider

将插件添加到 SDK 中。

C++

virtual int loadExtensionProvider(const char* path, bool unload_after_use = false) = 0;

注意： 该方法仅适用于 Windows 和 Android。

参数

参数名	描述
path	插件的动态库路径和名称。例如：/library/libagora_segmentation_extension.dll。
unload_after_use	是否在插件使用完毕后自动卸载： true: 当 IRtcEngine 销毁时自动卸载插件。 false: 不自动卸载插件，直到进程退出（推荐）。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

registerExtension

注册插件。

C++

virtual int registerExtension(const char* provider, const char* extension,
                        agora::media::MEDIA_SOURCE_TYPE type = agora::media::UNKNOWN_MEDIA_SOURCE) = 0;

自从

v4.1.0

加载插件后，你可以通过该方法注册插件。

该方法仅适用于 Windows。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件的名称。
type	媒体资源类型。详见 MEDIA_SOURCE_TYPE。 注意： 在该方法中，该参数仅支持以下两种设置： 默认值为 UNKNOWN_MEDIA_SOURCE。 如果要使用第二个摄像头采集视频，将该参数设置为 SECONDARY_CAMERA_SOURCE。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setExtensionProperty

设置插件的属性。

C++

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;

开启插件后，你可以调用该方法设置插件的属性。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件的名称。
key	插件属性的 Key。
value	插件属性 Key 对应的值。
type	媒体资源类型。详见 MEDIA_SOURCE_TYPE。 注意： 在该方法中，该参数仅支持以下两种设置： 默认值为 UNKNOWN_MEDIA_SOURCE。 如果要使用第二个摄像头采集视频，将该参数设置为 SECONDARY_CAMERA_SOURCE。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

setExtensionProviderProperty

设置插件服务商的属性。

C++

virtual int setExtensionProviderProperty(
      const char* provider, const char* key, const char* value) = 0;

你可以调用该方法设置插件服务商的属性，并根据服务商的类型初始化相关参数。

注意：
该方法需要在 enableExtension 之后、且启用音频（enableAudio/enableLocalAudio）或启用视频（enableVideo/enableLocalVideo）之前调用。

参数

参数名	描述
provider	提供插件的服务商名称。
key	插件属性的 Key。
value	插件属性 Key 对应的值。

返回值

• 0: 方法调用成功。

• < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IRtcEngine

onExtensionError

插件出错回调。

C++

virtual void onExtensionError(const char* provider, const char* extension, int error, const char* message) {
    (void)provider;
    (void)extension;
    (void)error;
    (void)message;
  }

当调用 enableExtension(true) 启用插件失败或者插件运行出错时， 插件会触发该回调并上报错误码和错误原因。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件的名称。
error	错误码。详见插件服务商提供的插件文档。
message	错误原因。详见插件服务商提供的插件文档。

所属接口类

• IRtcEngineEventHandler

onExtensionEvent

插件事件回调。

C++

virtual void onExtensionEvent(const char* provider, const char* extension, const char* key, const char* value) {
 (void)provider;
  (void)extension;
  (void)key;
  (void)value;
  }

为监听插件事件，你需要注册该回调。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件名称。
key	插件属性的 Key。
value	插件属性 Key 对应的值。

所属接口类

• IRtcEngineEventHandler

onExtensionStarted

插件启用回调。

C++

virtual void onExtensionStarted(const char* provider, const char* extension) {
  (void)provider;
  (void)extension;
}

当调用 enableExtension(true) 启用插件成功时，插件会触发该回调。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件名称。

所属接口类

• IRtcEngineEventHandler

onExtensionStopped

插件禁用回调。

C++

virtual void onExtensionStopped(const char* provider, const char* extension) {
    (void)provider;
    (void)extension;
  }

当调用 enableExtension(false) 禁用插件成功时，插件会触发该回调。

参数

参数名	描述
provider	提供插件的服务商名称。
extension	插件名称。

所属接口类

• IRtcEngineEventHandler