# 插件 (/zh-CN/api-reference/rtc/macos/extension)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<a id="toc_extension"></a>

<a id="api_irtcengine_enableextension"></a>

<a id="ariaid-title2"></a>

## enableExtensionWithVendor\:extension\:enabled\:sourceType: [#enableextensionwithvendorextensionenabledsourcetype]

启用或禁用扩展功能。

<a id="api_irtcengine_enableextension__prototype"></a>

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

<a id="api_irtcengine_enableextension__detailed_desc"></a>

:::note
注：

- 如果你想启用多个扩展，需要多次调用该方法。
- 成功调用该方法后，不能再加载其他扩展。
:::

<a id="api_irtcengine_enableextension__timing"></a>

### 调用时机 [#调用时机]

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

<a id="api_irtcengine_enableextension__parameters"></a>

### 参数 [#参数]

<ParameterList>
<a id="provider"></a>
<Parameter name="provider">

扩展提供方的名称。

</Parameter>
<a id="extension"></a>
<Parameter name="extension">

扩展的名称。

</Parameter>
<a id="enabled"></a>
<Parameter name="enabled">

是否启用该扩展：

- YES：启用扩展。
- NO：禁用扩展。

</Parameter>
<a id="sourcetype"></a>
<Parameter name="sourceType">

扩展的来源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_enableextension__return_values"></a>

### 返回值 [#返回值]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -3：扩展库未加载。声网建议你检查动态库的存储位置或名称。

### 所属接口类 [#所属接口类]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getextensionproperty"></a>

<a id="ariaid-title3"></a>

## getExtensionPropertyWithVendor\:extension\:key: [#getextensionpropertywithvendorextensionkey]

获取扩展组件的详细信息。

<a id="api_irtcengine_getextensionproperty__prototype"></a>

```objc
- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * _Nonnull)provider
                                             extension:(NSString * _Nonnull)extension
                                                   key:(NSString * _Nonnull)key NS_SWIFT_NAME(getExtensionProperty(withVendor:extension:key:));
```

<a id="api_irtcengine_getextensionproperty__detailed_desc"></a>

<a id="api_irtcengine_getextensionproperty__timing"></a>

### 调用时机 [#调用时机-1]

该方法可以在加入频道前或加入频道后调用。

<a id="api_irtcengine_getextensionproperty__parameters"></a>

### 参数 [#参数-1]

<ParameterList>
<a id="provider-1"></a>
<Parameter name="provider">

扩展组件提供方的名称。

</Parameter>
<a id="extension-1"></a>
<Parameter name="extension">

扩展组件的名称。

</Parameter>
<a id="key"></a>
<Parameter name="key">

扩展组件的键值。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getextensionproperty__return_values"></a>

### 返回值 [#返回值-1]

- 方法调用成功时，返回扩展组件的信息。
- 方法调用失败时，返回空字符串。

### 所属接口类 [#所属接口类-1]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_getextensionproperty2"></a>

<a id="ariaid-title4"></a>

## getExtensionPropertyWithVendor\:extension\:key\:sourceType: [#getextensionpropertywithvendorextensionkeysourcetype]

获取扩展的详细信息。

<a id="api_irtcengine_getextensionproperty2__prototype"></a>

```objc
- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * _Nonnull)provider
                                             extension:(NSString * _Nonnull)extension
                                                   key:(NSString * _Nonnull)key
                                            sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(getExtensionProperty(withVendor:extension:key:sourceType:));
```

<a id="api_irtcengine_getextensionproperty2__detailed_desc"></a>

<a id="api_irtcengine_getextensionproperty2__timing"></a>

### 调用时机 [#调用时机-2]

该方法可以在加入频道前或后调用。

<a id="api_irtcengine_getextensionproperty2__parameters"></a>

### 参数 [#参数-2]

<ParameterList>
<a id="provider-2"></a>
<Parameter name="provider">

扩展提供方的名称。

</Parameter>
<a id="extension-2"></a>
<Parameter name="extension">

扩展的名称。

</Parameter>
<a id="key-1"></a>
<Parameter name="key">

扩展的键值。

</Parameter>
<a id="sourcetype-1"></a>
<Parameter name="sourceType">

扩展的来源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_getextensionproperty2__return_values"></a>

### 返回值 [#返回值-2]

- 方法调用成功时，返回扩展信息。
- 方法调用失败时，返回空字符串。

### 所属接口类 [#所属接口类-2]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_registerextension"></a>

<a id="ariaid-title5"></a>

## registerExtensionWithVendor\:extension\:sourceType: [#registerextensionwithvendorextensionsourcetype]

注册一个扩展。

<a id="api_irtcengine_registerextension__prototype"></a>

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

<a id="api_irtcengine_registerextension__detailed_desc"></a>

对于 SDK 外部的扩展（例如来自 Extensions Marketplace 和 SDK Extensions 的扩展），你需要在调用此方法前加载它们。对于 SDK 内部的扩展（即包含在完整 SDK 包中的扩展），在初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 后会自动加载并注册。

:::note
注：

- 如果你想注册多个扩展，需要多次调用此方法。
- SDK 中不同扩展的数据处理顺序由注册顺序决定。即先注册的扩展会先处理数据。
:::

<a id="api_irtcengine_registerextension__timing"></a>

### 调用时机 [#调用时机-3]

声网建议你在初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 后、加入频道前调用此方法。

- 对于视频扩展（如美颜特效扩展），你需要在调用 [enableVideo](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_enablevideo) 或 [enableLocalVideo:](/zh-CN/api-reference/rtc/macos/video/video-basic#api_irtcengine_enablelocalvideo) 启用视频模块后调用此方法。
- 在调用此方法之前，你需要将扩展动态库（.xcframework）链接到 Xcode 项目中以加载扩展。

<a id="api_irtcengine_registerextension__parameters"></a>

### 参数 [#参数-3]

<ParameterList>
<a id="provider-3"></a>
<Parameter name="provider">

扩展提供方的名称。

</Parameter>
<a id="extension-3"></a>
<Parameter name="extension">

扩展的名称。

</Parameter>
<a id="sourcetype-2"></a>
<Parameter name="sourceType">

扩展的数据源类型，详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。

</Parameter>
</ParameterList>

<a id="api_irtcengine_registerextension__return_values"></a>

### 返回值 [#返回值-3]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

  - -3：扩展库未加载。声网建议你检查动态库的存储位置或名称。

### 所属接口类 [#所属接口类-3]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setextensionproperty"></a>

<a id="ariaid-title6"></a>

## setExtensionPropertyWithVendor\:extension\:key\:value: [#setextensionpropertywithvendorextensionkeyvalue]

设置扩展属性。

<a id="api_irtcengine_setextensionproperty__prototype"></a>

```objc
- (int)setExtensionPropertyWithVendor:(NSString * _Nonnull)provider
                            extension:(NSString * _Nonnull)extension
                                  key:(NSString * _Nonnull)key
                                value:(NSString * _Nonnull)value NS_SWIFT_NAME(setExtensionPropertyWithVendor(_:extension:key:value:));
```

<a id="api_irtcengine_setextensionproperty__detailed_desc"></a>

启用扩展后，可以调用该方法设置扩展的属性。

:::note
注： 如果需要为多个扩展设置属性，需要多次调用该方法。
:::

<a id="api_irtcengine_setextensionproperty__timing"></a>

### 调用时机 [#调用时机-4]

在调用 [enableExtensionWithVendor\:extension\:enabled\:sourceType:](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 方法之后调用。

<a id="api_irtcengine_setextensionproperty__parameters"></a>

### 参数 [#参数-4]

<ParameterList>
<a id="provider-4"></a>
<Parameter name="provider">

扩展提供方的名称。

</Parameter>
<a id="extension-4"></a>
<Parameter name="extension">

扩展的名称。

</Parameter>
<a id="key-2"></a>
<Parameter name="key">

扩展属性的键。

</Parameter>
<a id="value"></a>
<Parameter name="value">

扩展属性键对应的值。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setextensionproperty__return_values"></a>

### 返回值 [#返回值-4]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-4]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_setextensionproviderproperty"></a>

<a id="ariaid-title7"></a>

## setExtensionProviderPropertyWithVendor\:key\:value: [#setextensionproviderpropertywithvendorkeyvalue]

设置扩展提供方的属性。

<a id="api_irtcengine_setextensionproviderproperty__prototype"></a>

```objc
- (int)setExtensionProviderPropertyWithVendor:(NSString * _Nonnull)provider
                                          key:(NSString * _Nonnull)key
                                        value:(NSString * _Nonnull)value NS_SWIFT_NAME(setExtensionProviderPropertyWithVendor(_:key:value:));
```

<a id="api_irtcengine_setextensionproviderproperty__detailed_desc"></a>

你可以调用此方法根据扩展提供方的类型初始化相关参数。

:::note
注： 如果你想为多个扩展设置扩展提供方的属性，需要多次调用此方法。
:::

<a id="api_irtcengine_setextensionproviderproperty__timing"></a>

### 调用时机 [#调用时机-5]

在调用 [enableExtensionWithVendor\:extension\:enabled\:sourceType:](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 之前，且在调用 [registerExtensionWithVendor\:extension\:sourceType:](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_registerextension) 之后调用此方法。

<a id="api_irtcengine_setextensionproviderproperty__parameters"></a>

### 参数 [#参数-5]

<ParameterList>
<a id="provider-5"></a>
<Parameter name="provider">

扩展提供方的名称。

</Parameter>
<a id="key-3"></a>
<Parameter name="key">

扩展的键名。

</Parameter>
<a id="value-1"></a>
<Parameter name="value">

扩展键的值。

</Parameter>
</ParameterList>

<a id="api_irtcengine_setextensionproviderproperty__return_values"></a>

### 返回值 [#返回值-5]

- 0：方法调用成功。
- &lt; 0：方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。

### 所属接口类 [#所属接口类-5]

- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)

<a id="callback_irtcengineeventhandler_onextensionerrorwithcontext"></a>

<a id="ariaid-title8"></a>

## onExtensionErrorWithContext\:error\:message: [#onextensionerrorwithcontexterrormessage]

当扩展运行异常时触发的回调。

<a id="callback_irtcengineeventhandler_onextensionerrorwithcontext__prototype"></a>

```objc
- (void)onExtensionErrorWithContext:(AgoraExtensionContext * _Nonnull)context
                   error:(int)error
                 message:(NSString * _Nullable)message NS_SWIFT_NAME(onExtensionErrorWithContext(_:error:message:));
```

<a id="callback_irtcengineeventhandler_onextensionerrorwithcontext__detailed_desc"></a>

当扩展启用失败或运行时发生错误时，会触发该回调，并报告错误码及原因。

<a id="callback_irtcengineeventhandler_onextensionerrorwithcontext__timing"></a>

### 触发时机 [#触发时机]

该回调在扩展启用失败或运行时发生错误时被触发。

<a id="callback_irtcengineeventhandler_onextensionerrorwithcontext__parameters"></a>

### 参数 [#参数-6]

<ParameterList>
<a id="context"></a>
<Parameter name="context">

扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。

</Parameter>
<a id="error"></a>
<Parameter name="error">

错误码。详情请参见扩展提供方提供的扩展文档。

</Parameter>
<a id="message"></a>
<Parameter name="message">

错误原因。详情请参见扩展提供方提供的扩展文档。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-6]

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onextensioneventwithcontext"></a>

<a id="ariaid-title9"></a>

## onEventWithContext\:key\:value: [#oneventwithcontextkeyvalue]

扩展的事件回调。

<a id="callback_irtcengineeventhandler_onextensioneventwithcontext__prototype"></a>

```objc
- (void)onEventWithContext:(AgoraExtensionContext * _Nonnull)context
            key:(NSString * _Nullable)key
          value:(NSString * _Nullable)value NS_SWIFT_NAME(onEventWithContext(_:key:value:));
```

<a id="callback_irtcengineeventhandler_onextensioneventwithcontext__detailed_desc"></a>

你需要注册该回调以在扩展运行期间监听事件。

<a id="callback_irtcengineeventhandler_onextensioneventwithcontext__parameters"></a>

### 参数 [#参数-7]

<ParameterList>
<a id="context-1"></a>
<Parameter name="context">

扩展的上下文信息，详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。

</Parameter>
<a id="key-4"></a>
<Parameter name="key">

扩展事件的键。

</Parameter>
<a id="value-2"></a>
<Parameter name="value">

扩展事件键对应的值。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-7]

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onextensionstartedwithcontext"></a>

<a id="ariaid-title10"></a>

## onExtensionStartedWithContext: [#onextensionstartedwithcontext]

扩展启用成功时触发的回调。

<a id="callback_irtcengineeventhandler_onextensionstartedwithcontext__prototype"></a>

```objc
- (void)onExtensionStartedWithContext:(AgoraExtensionContext * _Nonnull)context NS_SWIFT_NAME(onExtensionStartedWithContext(_:));
```

<a id="callback_irtcengineeventhandler_onextensionstartedwithcontext__detailed_desc"></a>

<a id="callback_irtcengineeventhandler_onextensionstartedwithcontext__timing"></a>

### 触发时机 [#触发时机-1]

该回调在扩展成功启用后被触发。

<a id="callback_irtcengineeventhandler_onextensionstartedwithcontext__parameters"></a>

### 参数 [#参数-8]

<ParameterList>
<a id="context-2"></a>
<Parameter name="context">

扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-8]

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)

<a id="callback_irtcengineeventhandler_onextensionstoppedwithcontext"></a>

<a id="ariaid-title11"></a>

## onExtensionStoppedWithContext: [#onextensionstoppedwithcontext]

当扩展被禁用时触发的回调。

<a id="callback_irtcengineeventhandler_onextensionstoppedwithcontext__prototype"></a>

```objc
- (void)onExtensionStoppedWithContext:(AgoraExtensionContext * _Nonnull)context NS_SWIFT_NAME(onExtensionStoppedWithContext(_:));
```

<a id="callback_irtcengineeventhandler_onextensionstoppedwithcontext__detailed_desc"></a>

<a id="callback_irtcengineeventhandler_onextensionstoppedwithcontext__timing"></a>

### 触发时机 [#触发时机-2]

该回调在扩展成功被禁用后触发。

<a id="callback_irtcengineeventhandler_onextensionstoppedwithcontext__parameters"></a>

### 参数 [#参数-9]

<ParameterList>
<a id="context-3"></a>
<Parameter name="context">

扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。

</Parameter>
</ParameterList>

### 所属接口类 [#所属接口类-9]

- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)