Initialization

addHandler

Adds an event handler.

public void addHandler(IRtcEngineEventHandler handler)

The SDK uses IRtcEngineEventHandler to send callbacks to the app. You can override methods in this class to receive callbacks. All methods in this class have default (empty) implementations, so you only need to override the ones you need. Avoid performing time-consuming operations or calling potentially blocking APIs such as sendStreamMessage in the callback, or the SDK may not function properly.

Parameters

handler: The callback event handler to add. See IRtcEngineEventHandler.

create [1/2]

Creates and initializes a RtcEngine instance.

public static synchronized RtcEngine create(Context context, String appId, IRtcEngineEventHandler handler) throws Exception

All methods in the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Note:

You must call this method to create a RtcEngine instance before calling any other APIs.
You can create a RtcEngine instance by calling this method or create [2/2]. Compared to this method, create [2/2] supports more configurations, such as specifying the region and setting the log file.
Each app supports creating only one RtcEngine instance.

Parameters

context: The context of the Android Activity.
appId: The App ID issued by Agora for your project. Only users with the same App ID can join the same channel and communicate. An App ID can only be used to create one RtcEngine instance. To change the App ID, call destroy [2/2] to destroy the current RtcEngine instance before creating a new one.
handler: The event handler for RtcEngine. See IRtcEngineEventHandler.

Return Values

If the method call succeeds, returns an initialized RtcEngine instance. If the method call fails, the SDK throws an exception and returns the corresponding error message. You need to catch the exception and handle it accordingly.

destroy [2/2]

Destroys the RtcEngine instance and releases related resources.

public static synchronized void destroy(@Nullable IRtcEngineReleaseCallback callback)

Since: Added since v4.6.0.

Call this method to release the RtcEngine instance when you no longer need real-time communication, so that the related resources can be used for other operations. Recommended for scenarios such as voice or video calls.

Parameters

callback

Configures synchronous or asynchronous destruction of the engine:

Non-null: Asynchronous destruction. The method returns immediately, but the engine resources may not be fully released. The onEngineReleased callback is triggered after the engine is destroyed.
null: Synchronous destruction. The method returns only after all engine resources are fully released. See IRtcEngineReleaseCallback.

create [2/2]

Creates and initializes a RtcEngine instance.

public static synchronized RtcEngine create(RtcEngineConfig config) throws Exception

You can create a RtcEngine instance by calling this method or the create [1/2] method. Compared to the latter, this method supports more configuration options, such as specifying the region and setting the log file.

Note: Each app supports creating only one RtcEngine instance. All methods in the RtcEngine class are executed asynchronously. Agora recommends calling these methods in the same thread.

Timing

You must call this method to create the RtcEngine object before calling any other APIs.

Parameters

config: The configuration parameters for the RtcEngine instance. See RtcEngineConfig.

Return Values

If the method call succeeds, returns the initialized RtcEngine object. If the method call fails, the SDK throws an exception and returns the corresponding error message. You need to catch the exception and handle it accordingly.

destroy [1/2]

Releases the RtcEngine instance.

public static synchronized void destroy()

This method releases all resources occupied by the Agora SDK. After the method is successfully called, you can no longer use any methods or callbacks in the SDK. To use real-time communication again, you must call create [2/2] to create a new RtcEngine instance.

Note: Do not call this method inside any SDK callback. Otherwise, the SDK must wait for the callback to return before releasing resources, which may cause a deadlock.

removeHandler

Removes the specified IRtcEngineEventHandler instance.

public void removeHandler(IRtcEngineEventHandler handler)

This method removes the specified callback handler. For callbacks that only need to be listened to once, you can call this method to remove the handler after receiving the event.

Parameters

handler: The callback handler to remove. See IRtcEngineEventHandler.

onEngineReleased

Callback triggered when RtcEngine is released.

@CalledByNative void onEngineReleased();

This callback is triggered when the RtcEngine object is asynchronously released by calling the destroy [2/2] method.

Trigger Timing

This callback is triggered when the RtcEngine object is asynchronously released by calling the destroy [2/2] method.