插件

enableExtensionWithVendor:extension:enabled:sourceType:

启用/禁用插件。

Objective-C

- (int)enableExtensionWithVendor:(NSString * __nonnull)provider
                       extension:(NSString * __nonnull)extension
                         enabled:(BOOL)enabled
                      sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(enableExtension(withVendor:extension:enabled:sourceType:));

调用时机

建议你在加入频道后调用该方法。

调用限制

• 如果要开启多个插件，需要多次调用该方法。
• 该方法调用成功后，无法再加载其他插件。

相关回调

频道内调用该方法成功时会触发插件启用回调 onExtensionStartedWithContext: 或插件禁用回调 onExtensionStoppedWithContext:。

参数

provider

提供插件的服务商名称。

extension

插件的名称。

enabled

是否启用插件：

• YES: 启用插件。
• NO: 禁用插件。

type

插件的媒体源类型。详见 AgoraMediaSourceType。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置，或该动态库名是否正确。

所属接口类

• AgoraRtcEngineKit

getExtensionPropertyWithVendor:extension:key:

获取插件的详细信息。

Objective-C

- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * __nonnull)provider
                                             extension:(NSString * __nonnull)extension
                                                   key:(NSString * __nonnull)key;

调用时机

加入频道前后均可调用。

调用限制

无。

参数

provider

提供插件的服务商名称。

extension

插件的名称。

key

插件属性的 Key。

返回值

• 方法调用成功，则返回插件信息。
• 方法调用失败，则返回空字符串。

所属接口类

• AgoraRtcEngineKit

getExtensionPropertyWithVendor:extension:key:sourceType:

获取插件的详细信息。

Objective-C

- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * __nonnull)provider
                                             extension:(NSString * __nonnull)extension
                                                   key:(NSString * __nonnull)key
                                            sourceType:(AgoraMediaSourceType)sourceType;

调用时机

加入频道前后均可调用。

调用限制

无。

参数

provider

提供插件的服务商名称。

extension

插件的名称。

key

插件属性的 Key。

sourceType

插件的媒体源类型。详见 AgoraMediaSourceType。

返回值

• 方法调用成功，则返回插件信息。
• 方法调用失败，则返回空字符串。

所属接口类

• AgoraRtcEngineKit

registerExtensionWithVendor:extension:sourceType:

注册插件。

Objective-C

- (int)registerExtensionWithVendor:(NSString * __nonnull)provider
                         extension:(NSString * __nonnull)extension
                        sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(registerExtension(withVendor:extension:sourceType:));

自从

v4.1.0

对于 SDK 外部的插件（例如云市场插件和 SDK 拓展插件），加载插件后，你需要调用该方法注册插件。SDK 内部插件（包含在 SDK 包中的插件）在初始化 AgoraRtcEngineKit 后会自动加载并注册，无需调用该方法。

调用时机

• 建议你在初始化 AgoraRtcEngineKit 后、加入频道前调用该方法。
• 对于视频相关插件（例如美颜插件），需要在启用视频模块（enableVideo/enableLocalVideo:）之前调用该方法。
• 调用该方法前，需要先在 Xcode 中将插件动态库（.xcframework）链接至工程以加载插件。

调用限制

• 如果要注册多个插件，需要多次调用该方法。
• 不同插件在 SDK 中处理数据的顺序由插件的注册顺序决定。即先注册的插件会先处理数据。

参数

provider

提供插件的服务商名称。

extension

插件的名称。

type

插件的媒体源类型。详见 AgoraMediaSourceType。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。详见错误码了解详情和解决建议。
  • -3: 该插件动态库没有被加载。声网推荐你检查该动态库是否存放在预期的位置，或该动态库名是否正确。

所属接口类

• AgoraRtcEngineKit

setExtensionPropertyWithVendor:extension:key:value:

设置插件的属性。

Objective-C

- (int)setExtensionPropertyWithVendor:(NSString * __nonnull)provider extension:(NSString * __nonnull)extension key:(NSString * __nonnull)key value:(NSString * __nonnull)value;

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

调用时机

请在调用 enableExtensionWithVendor:extension:enabled:sourceType: 开启插件后调用该方法。

调用限制

如果要设置多个插件的属性，需要多次调用该方法。

相关回调

调用该方法后，可能会触发插件事件回调 onEventWithContext:key:value:，具体触发逻辑与插件本身相关。

参数

provider

提供插件的服务商名称。

extension

插件的名称。

key

插件属性的 Key。

value

插件属性 Key 对应的值。

返回值

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

所属接口类

• AgoraRtcEngineKit

setExtensionProviderPropertyWithVendor:key:value:

设置插件服务商的属性。

Objective-C

- (int) setExtensionProviderPropertyWithVendor:(NSString * __nonnull)provider key:(NSString * __nonnull)key value:(NSString * __nonnull)value;

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

调用时机

请在调用 registerExtensionWithVendor:extension:sourceType: 之后、enableExtensionWithVendor:extension:enabled:sourceType: 之前调用该方法。

调用限制

如果要设置多个插件服务商的属性，需要多次调用该方法。

参数

provider

提供插件的服务商名称。

key

插件属性的 Key。

value

插件属性 Key 对应的值。

返回值

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

所属接口类

• AgoraRtcEngineKit

onExtensionErrorWithContext:error:message:

插件出错回调。

Objective-C

- (void)onExtensionErrorWithContext:(AgoraExtensionContext * __nonnull)context
                   error:(int)error
                 message:(NSString * __nullable)message NS_SWIFT_NAME(onExtensionErrorWithContext(_:error:message:));

详情

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

参数

context

插件上下文信息，详见 AgoraExtensionContext。

error

错误码。详见插件服务商提供的插件文档。

message

错误原因。详见插件服务商提供的插件文档。

所属接口类

• AgoraMediaFilterEventDelegate

onEventWithContext:key:value:

插件事件回调。

Objective-C

- (void)onEventWithContext:(AgoraExtensionContext * __nonnull)context
            key:(NSString * __nullable)key
          value:(NSString * __nullable)value NS_SWIFT_NAME(onEventWithContext(_:key:value:));

详情

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

参数

context

插件上下文信息，详见 AgoraExtensionContext。

key

插件属性的 Key。

value

插件属性 Key 对应的值。

所属接口类

• AgoraMediaFilterEventDelegate

onExtensionStartedWithContext:

插件已启用成功回调。

Objective-C

- (void)onExtensionStartedWithContext:(AgoraExtensionContext * __nonnull)context NS_SWIFT_NAME(onExtensionStartedWithContext(_:));

详情

成功启用插件后会触发该回调。

参数

context

插件上下文信息，详见 AgoraExtensionContext。

所属接口类

• AgoraMediaFilterEventDelegate

onExtensionStoppedWithContext:

插件已禁用回调。

Objective-C

- (void)onExtensionStoppedWithContext:(AgoraExtensionContext * __nonnull)context NS_SWIFT_NAME(onExtensionStoppedWithContext(_:));

详情

成功禁用插件后会触发该回调。

参数

context

插件上下文信息，详见 AgoraExtensionContext。

所属接口类

• AgoraMediaFilterEventDelegate