# 插件 (/zh-CN/api-reference/rtc/cpp-all-platforms/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>

## enableExtension [#enableextension]

启用或禁用插件。

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

```cpp
virtual int enableExtension(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, bool enable = true) = 0;
```

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

通过调用该方法，你可以在不更改处理流程的情况下动态启用或禁用插件。例如，启用或禁用 `Extension_A` 表示数据将被 `Extension_A` 处理或绕过。

:::note
注： 出于兼容性考虑，如果你尚未调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension)，[enableExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_enableextension) 会自动注册指定的插件。建议你显式调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension)。
:::

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

### 参数 [#参数]

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

插件提供方的名称，例如 `agora.io`。

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

插件名称，例如 `agora.beauty`。

</Parameter>
<a id="extensioninfo"></a>
<Parameter name="extensionInfo">

`ExtensionInfo` 对象，表示插件的信息。

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

是否启用插件：

- true：（默认）启用插件。
- false：禁用插件。

</Parameter>
</ParameterList>

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

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

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

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

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

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

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

## getExtensionProperty [#getextensionproperty]

获取扩展属性。

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

```cpp
virtual int getExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, char* value, int buf_len) = 0;
```

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

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

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

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

扩展提供方的名称，例如声网（agora.io）。

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

扩展的名称，例如 `agora.beauty`。

</Parameter>
<a id="extensioninfo-1"></a>
<Parameter name="extensionInfo">

扩展信息。详见 `ExtensionInfo`。

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

扩展属性的键名。

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

输出参数，表示扩展属性键对应的值。

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

扩展属性值的最大长度（以 JSON 字符串形式表示）。

</Parameter>
</ParameterList>

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

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

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

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

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

<a id="api_irtcengine_loadextensionprovider"></a>

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

## loadExtensionProvider [#loadextensionprovider]

加载扩展。

<a id="api_irtcengine_loadextensionprovider__prototype"></a>

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

<a id="api_irtcengine_loadextensionprovider__detailed_desc"></a>

该方法用于将 SDK 外部的扩展（例如来自云市场或 SDK 扩展）加载到 SDK 中。

:::note
注： 如果你需要加载多个扩展，需要多次调用该方法。仅适用于 Windows 和 Android 平台。
:::

<a id="api_irtcengine_loadextensionprovider__timing"></a>

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

请确保在调用该方法前已初始化 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)。

<a id="api_irtcengine_loadextensionprovider__parameters"></a>

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

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

扩展库的路径和名称。例如：`/library/libagora_segmentation_extension.dll`。

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

是否在不再使用当前扩展时卸载该扩展：

- true：当 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 被销毁时卸载该扩展。
- false：（推荐）直到进程终止前都不卸载该扩展。

</Parameter>
</ParameterList>

<a id="api_irtcengine_loadextensionprovider__return_values"></a>

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

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

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

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

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

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

## registerExtension [#registerextension]

注册一个扩展。

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

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

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

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

:::note
注：

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

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

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

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

- 对于视频扩展（如美颜特效扩展），你需要在调用 [enableVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablevideo) 或 [enableLocalVideo](/zh-CN/api-reference/rtc/cpp-all-platforms/video/video-basic#api_irtcengine_enablelocalvideo) 启用视频模块后再调用此方法。
- 在调用此方法前，你需要先调用 [loadExtensionProvider](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_loadextensionprovider) 加载扩展。

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

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

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

扩展提供方的名称。

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

扩展的名称。

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

扩展的数据源类型，详见 [MEDIA_SOURCE_TYPE](/zh-CN/api-reference/rtc/cpp-all-platforms/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]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

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

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

## setExtensionProperty [#setextensionproperty]

设置插件的属性。

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

```cpp
virtual int setExtensionProperty(const char* provider, const char* extension, const ExtensionInfo& extensionInfo, const char* key, const char* value) = 0;
```

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

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

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

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

插件提供方的名称，例如 `agora.io`。

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

插件名称，例如 `agora.beauty`。

</Parameter>
<a id="extensioninfo-2"></a>
<Parameter name="extensionInfo">

插件信息，详见 `ExtensionInfo`。

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

插件属性的键名。

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

插件属性键对应的值，采用 JSON 格式。

</Parameter>
</ParameterList>

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

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

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

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

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

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

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

## setExtensionProviderProperty [#setextensionproviderproperty]

设置扩展提供方的属性。

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

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

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

调用该方法可设置扩展提供方的属性，并根据提供方的类型初始化相关参数。

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

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

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

在调用 [enableExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_enableextension) 之前，调用 [registerExtension](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#api_irtcengine_registerextension) 之后。

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

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

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

扩展提供方的名称。

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

扩展属性的键名。

</Parameter>
<a id="value-2"></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]

- [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine)

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

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

## onExtensionErrorWithContext [#onextensionerrorwithcontext]

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

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

```cpp
virtual void onExtensionErrorWithContext(const ExtensionContext &context, int error, const char* message)
```

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

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

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

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

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

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

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

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

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

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

</Parameter>
</ParameterList>

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

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

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

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

## onExtensionEventWithContext [#onextensioneventwithcontext]

扩展事件回调。

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

```cpp
virtual void onExtensionEventWithContext(const ExtensionContext &context, const char* key, const char* 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">

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

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

扩展事件的键。

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

扩展事件键对应的值。

</Parameter>
</ParameterList>

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

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

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

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

## onExtensionStartedWithContext [#onextensionstartedwithcontext]

[onExtensionStartedWithContext](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstartedwithcontext) 回调。当扩展启用成功时触发。

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

```cpp
virtual void onExtensionStartedWithContext(const ExtensionContext &context)
```

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

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

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

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

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

</Parameter>
</ParameterList>

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

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)

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

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

## onExtensionStoppedWithContext [#onextensionstoppedwithcontext]

[onExtensionStoppedWithContext](/zh-CN/api-reference/rtc/cpp-all-platforms/extension#callback_irtcengineeventhandler_onextensionstoppedwithcontext) 回调：扩展被禁用时触发。

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

```cpp
virtual void onExtensionStoppedWithContext(const ExtensionContext &context)
```

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

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

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

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

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

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

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

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

</Parameter>
</ParameterList>

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

- [IRtcEngineEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengineeventhandler)