Initialization

createAgoraRtcEngine

Creates an IRtcEngine object.

AGORA_API agora::rtc::IRtcEngine* AGORA_CALL createAgoraRtcEngine();

In Agora RTC SDK v4.x, each app supports creating only one IRtcEngine object.

Return Values

  • If the method call succeeds, returns the IRtcEngine object. See IRtcEngine.
  • If the method call fails, returns NULL.

initialize

Initializes the IRtcEngine.

virtual int initialize(const RtcEngineContext& context) = 0;
Note:
  • All methods provided by IRtcEngine are executed asynchronously. It is recommended to call these methods in the same thread.
  • The SDK supports creating only one IRtcEngine instance per app.

Timing

Before calling other APIs, you must call createAgoraRtcEngine and initialize to create and initialize the IRtcEngine object.

Parameters

context
Configuration for the IRtcEngine instance. See RtcEngineContext.

Return Values

  • 0: Success.
  • < 0: Failure.
    • -1: General error (no specific reason).
    • -2: Invalid parameter.
    • -7: SDK not initialized.
    • -22: Resource request failed. The SDK cannot allocate resources due to excessive system resource usage by your app or insufficient system resources.
    • -101: Invalid App ID.

release

Releases the IRtcEngine instance.

AGORA_CPP_API static void release(RtcEngineReleaseCallback callback = nullptr);

This method releases all resources occupied by the Agora SDK. It is suitable for scenarios where users occasionally make voice or video calls. When the user is no longer in a call, resources can be released for other operations. After calling this method successfully, you can no longer use any methods or callbacks in the SDK. To use real-time communication again, you must call createAgoraRtcEngine and initialize to create a new IRtcEngine instance.

Note: It is not recommended to call release within any SDK callback. Otherwise, the SDK must wait for the callback to return before releasing resources, which may cause a deadlock.

Parameters

callback
Pointer to the callback function used to set the engine destruction mode. See RtcEngineReleaseCallback.
  • Non-nullptr: asynchronous engine destruction. This method returns immediately, and the engine resources may not be fully released yet. The SDK triggers RtcEngineReleaseCallback after the engine is destroyed.
  • nullptr: synchronous engine destruction. This method returns only after the engine resources are fully released.

RtcEngineReleaseCallback

Callback triggered when IRtcEngine is released.

using RtcEngineReleaseCallback = void(*)();
Since
Available since v4.6.0.

Timing

This callback is triggered when calling the release method to asynchronously release the IRtcEngine object.