Extensions

enableExtension

Enables or disables an extension.

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

By calling this method, you can dynamically enable or disable an extension without changing the processing flow. For example, enabling or disabling Extension_A means the data will be processed by or bypass Extension_A.

Note: For compatibility, if you have not called registerExtension, enableExtension will automatically register the specified extension. It is recommended to call registerExtension explicitly.

Parameters

provider
The name of the extension provider, for example, agora.io.
extension
The name of the extension, for example, agora.beauty.
extensionInfo
The ExtensionInfo object representing the extension information.
enable
Whether to enable the extension:
  • true: (Default) Enable the extension.
  • false: Disable the extension.

Return Values

  • 0: Success.
  • < 0: Failure.

getExtensionProperty

Gets the properties of an extension.

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

Parameters

provider
The name of the extension provider, for example, agora.io.
extension
The name of the extension, for example, agora.beauty.
extensionInfo
Extension information. See ExtensionInfo.
key
The key of the extension property.
value
Output parameter. The value corresponding to the extension property key.
buf_len
The maximum length of the extension property value (in JSON string format).

Return Values

  • 0: Success.
  • < 0: Failure.

loadExtensionProvider

Loads an extension.

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

This method loads external SDK extensions (e.g., from the cloud marketplace or SDK extensions) into the SDK.

Note: If you need to load multiple extensions, call this method multiple times. Only applicable to Windows and Android platforms.

Timing

Make sure to initialize IRtcEngine before calling this method.

Parameters

path
The path and name of the extension library. For example: /library/libagora_segmentation_extension.dll.
unload_after_use
Whether to unload the extension when it is no longer used:
  • true: Unload the extension when IRtcEngine is destroyed.
  • false: (Recommended) Do not unload the extension until the process terminates.

Return Values

  • 0: Success.
  • < 0: Failure.

registerExtension

Registers an extension.

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

For external SDK extensions (e.g., from the cloud marketplace or SDK extensions), you need to load them before calling this method. For internal SDK extensions (i.e., those included in the full SDK package), they are automatically loaded and registered after initializing IRtcEngine.

Note:
  • If you want to register multiple extensions, call this method multiple times.
  • The data processing order of different extensions in the SDK is determined by the registration order. The earlier an extension is registered, the earlier it processes data.

Timing

Agora recommends calling this method after initializing IRtcEngine and before joining the channel.

Parameters

provider
The name of the extension provider.
extension
The name of the extension.
type
The data source type of the extension. See MEDIA_SOURCE_TYPE.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -3: Extension library not loaded. Agora recommends checking the storage location or name of the dynamic library.

setExtensionProperty

Sets the properties of an extension.

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

Parameters

provider
The name of the extension provider, for example, agora.io.
extension
The name of the extension, for example, agora.beauty.
extensionInfo
Extension information. See ExtensionInfo.
key
The key of the extension property.
value
The value corresponding to the key of the extension property, in JSON format.

Return Values

  • 0: Success.
  • < 0: Failure.

setExtensionProviderProperty

Sets the properties of an extension provider.

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

Call this method to set the properties of the extension provider and initialize related parameters based on the provider type.

Note: If you want to set properties for multiple extensions, call this method multiple times.

Timing

Call this method after registerExtension but before enableExtension.

Parameters

provider
The name of the extension provider.
key
The key of the extension property.
value
The value corresponding to the extension property key.

Return Values

  • 0: Success.
  • < 0: Failure.

onExtensionErrorWithContext

Callback triggered when the extension encounters a runtime error.

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

This callback is triggered when the extension fails to enable or encounters a runtime error, returning the error code and reason.

Parameters

context
Context information of the extension. See ExtensionContext.
error
Error code. See the extension provider's documentation.
message
Error reason. See the extension provider's documentation.

onExtensionEventWithContext

Callback for extension events.

virtual void onExtensionEventWithContext(const ExtensionContext &context, const char* key, const char* value)

You need to register this callback when listening to events during the extension runtime.

Parameters

context
Context information of the extension. See ExtensionContext.
key
Key of the extension event.
value
Value corresponding to the extension event key.