# 插件 (/zh-CN/api-reference/rtc/macos/extension)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## enableExtensionWithVendor\:extension\:enabled\:sourceType: [#enableextensionwithvendorextensionenabledsourcetype]
启用或禁用扩展功能。
```objc
- (int)enableExtensionWithVendor:(NSString * _Nonnull)provider
extension:(NSString * _Nonnull)extension
enabled:(BOOL)enabled
sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(enableExtension(withVendor:extension:enabled:sourceType:));
```
:::note
注:
- 如果你想启用多个扩展,需要多次调用该方法。
- 成功调用该方法后,不能再加载其他扩展。
:::
### 调用时机 [#调用时机]
该方法建议在你加入频道后调用。
### 参数 [#参数]
扩展提供方的名称。
扩展的名称。
是否启用该扩展:
- YES:启用扩展。
- NO:禁用扩展。
扩展的来源类型,详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。
### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -3:扩展库未加载。声网建议你检查动态库的存储位置或名称。
### 所属接口类 [#所属接口类]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## getExtensionPropertyWithVendor\:extension\:key: [#getextensionpropertywithvendorextensionkey]
获取扩展组件的详细信息。
```objc
- (NSString * _Nullable)getExtensionPropertyWithVendor:(NSString * _Nonnull)provider
extension:(NSString * _Nonnull)extension
key:(NSString * _Nonnull)key NS_SWIFT_NAME(getExtensionProperty(withVendor:extension:key:));
```
### 调用时机 [#调用时机-1]
该方法可以在加入频道前或加入频道后调用。
### 参数 [#参数-1]
扩展组件提供方的名称。
扩展组件的名称。
扩展组件的键值。
### 返回值 [#返回值-1]
- 方法调用成功时,返回扩展组件的信息。
- 方法调用失败时,返回空字符串。
### 所属接口类 [#所属接口类-1]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## getExtensionPropertyWithVendor\:extension\:key\:sourceType: [#getextensionpropertywithvendorextensionkeysourcetype]
获取扩展的详细信息。
```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:));
```
### 调用时机 [#调用时机-2]
该方法可以在加入频道前或后调用。
### 参数 [#参数-2]
扩展提供方的名称。
扩展的名称。
扩展的键值。
扩展的来源类型,详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。
### 返回值 [#返回值-2]
- 方法调用成功时,返回扩展信息。
- 方法调用失败时,返回空字符串。
### 所属接口类 [#所属接口类-2]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## registerExtensionWithVendor\:extension\:sourceType: [#registerextensionwithvendorextensionsourcetype]
注册一个扩展。
```objc
- (int)registerExtensionWithVendor:(NSString * _Nonnull)provider
extension:(NSString * _Nonnull)extension
sourceType:(AgoraMediaSourceType)sourceType NS_SWIFT_NAME(registerExtension(withVendor:extension:sourceType:));
```
对于 SDK 外部的扩展(例如来自 Extensions Marketplace 和 SDK Extensions 的扩展),你需要在调用此方法前加载它们。对于 SDK 内部的扩展(即包含在完整 SDK 包中的扩展),在初始化 [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine) 后会自动加载并注册。
:::note
注:
- 如果你想注册多个扩展,需要多次调用此方法。
- SDK 中不同扩展的数据处理顺序由注册顺序决定。即先注册的扩展会先处理数据。
:::
### 调用时机 [#调用时机-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 项目中以加载扩展。
### 参数 [#参数-3]
扩展提供方的名称。
扩展的名称。
扩展的数据源类型,详见 [AgoraMediaSourceType](/zh-CN/api-reference/rtc/macos/enum-mediasourcetype)。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -3:扩展库未加载。声网建议你检查动态库的存储位置或名称。
### 所属接口类 [#所属接口类-3]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## setExtensionPropertyWithVendor\:extension\:key\:value: [#setextensionpropertywithvendorextensionkeyvalue]
设置扩展属性。
```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:));
```
启用扩展后,可以调用该方法设置扩展的属性。
:::note
注: 如果需要为多个扩展设置属性,需要多次调用该方法。
:::
### 调用时机 [#调用时机-4]
在调用 [enableExtensionWithVendor\:extension\:enabled\:sourceType:](/zh-CN/api-reference/rtc/macos/extension#api_irtcengine_enableextension) 方法之后调用。
### 参数 [#参数-4]
扩展提供方的名称。
扩展的名称。
扩展属性的键。
扩展属性键对应的值。
### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## setExtensionProviderPropertyWithVendor\:key\:value: [#setextensionproviderpropertywithvendorkeyvalue]
设置扩展提供方的属性。
```objc
- (int)setExtensionProviderPropertyWithVendor:(NSString * _Nonnull)provider
key:(NSString * _Nonnull)key
value:(NSString * _Nonnull)value NS_SWIFT_NAME(setExtensionProviderPropertyWithVendor(_:key:value:));
```
你可以调用此方法根据扩展提供方的类型初始化相关参数。
:::note
注: 如果你想为多个扩展设置扩展提供方的属性,需要多次调用此方法。
:::
### 调用时机 [#调用时机-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) 之后调用此方法。
### 参数 [#参数-5]
扩展提供方的名称。
扩展的键名。
扩展键的值。
### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [AgoraRtcEngineKit](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengine)
## onExtensionErrorWithContext\:error\:message: [#onextensionerrorwithcontexterrormessage]
当扩展运行异常时触发的回调。
```objc
- (void)onExtensionErrorWithContext:(AgoraExtensionContext * _Nonnull)context
error:(int)error
message:(NSString * _Nullable)message NS_SWIFT_NAME(onExtensionErrorWithContext(_:error:message:));
```
当扩展启用失败或运行时发生错误时,会触发该回调,并报告错误码及原因。
### 触发时机 [#触发时机]
该回调在扩展启用失败或运行时发生错误时被触发。
### 参数 [#参数-6]
扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。
错误码。详情请参见扩展提供方提供的扩展文档。
错误原因。详情请参见扩展提供方提供的扩展文档。
### 所属接口类 [#所属接口类-6]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)
## onEventWithContext\:key\:value: [#oneventwithcontextkeyvalue]
扩展的事件回调。
```objc
- (void)onEventWithContext:(AgoraExtensionContext * _Nonnull)context
key:(NSString * _Nullable)key
value:(NSString * _Nullable)value NS_SWIFT_NAME(onEventWithContext(_:key:value:));
```
你需要注册该回调以在扩展运行期间监听事件。
### 参数 [#参数-7]
扩展的上下文信息,详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。
扩展事件的键。
扩展事件键对应的值。
### 所属接口类 [#所属接口类-7]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)
## onExtensionStartedWithContext: [#onextensionstartedwithcontext]
扩展启用成功时触发的回调。
```objc
- (void)onExtensionStartedWithContext:(AgoraExtensionContext * _Nonnull)context NS_SWIFT_NAME(onExtensionStartedWithContext(_:));
```
### 触发时机 [#触发时机-1]
该回调在扩展成功启用后被触发。
### 参数 [#参数-8]
扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。
### 所属接口类 [#所属接口类-8]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)
## onExtensionStoppedWithContext: [#onextensionstoppedwithcontext]
当扩展被禁用时触发的回调。
```objc
- (void)onExtensionStoppedWithContext:(AgoraExtensionContext * _Nonnull)context NS_SWIFT_NAME(onExtensionStoppedWithContext(_:));
```
### 触发时机 [#触发时机-2]
该回调在扩展成功被禁用后触发。
### 参数 [#参数-9]
扩展的上下文信息。详见 [AgoraExtensionContext](/zh-CN/api-reference/rtc/macos/class-extensioncontext)。
### 所属接口类 [#所属接口类-9]
- [AgoraRtcEngineDelegate](/zh-CN/api-reference/rtc/macos/rtc-interface-class#class_irtcengineeventhandler)