Public Types

typedef unsigned int WindowIDType
 
typedef HWND WindowIDType
 

Public Member Functions

virtual int initialize (const RtcEngineContext &context)=0
 
virtual void release (bool sync=false)=0
 
virtual int setChannelProfile (CHANNEL_PROFILE_TYPE profile)=0
 
virtual int setClientRole (CLIENT_ROLE_TYPE role)=0
 
virtual int joinChannel (const char *token, const char *channelId, const char *info, uid_t uid)=0
 
virtual int leaveChannel ()=0
 
virtual int renewToken (const char *token)=0
 
virtual int queryInterface (INTERFACE_ID_TYPE iid, void **inter)=0
 
virtual int startEchoTest ()=0
 
virtual int startEchoTest (int intervalInSeconds)=0
 
virtual int stopEchoTest ()=0
 
virtual int enableVideo ()=0
 
virtual int disableVideo ()=0
 
virtual int setVideoProfile (VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight)=0
 
virtual int setVideoEncoderConfiguration (const VideoEncoderConfiguration &config)=0
 
virtual int setupLocalVideo (const VideoCanvas &canvas)=0
 
virtual int setupRemoteVideo (const VideoCanvas &canvas)=0
 
virtual int startPreview ()=0
 
virtual int setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0
 
virtual int stopPreview ()=0
 
virtual int enableAudio ()=0
 
virtual int enableLocalAudio (bool enabled)=0
 
virtual int disableAudio ()=0
 
virtual int setAudioProfile (AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario)=0
 
virtual int startScreenCaptureByDisplayId (unsigned int displayId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByScreenRect (const Rectangle &screenRect, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int startScreenCaptureByWindowId (view_t windowId, const Rectangle &regionRect, const ScreenCaptureParameters &captureParams)=0
 
virtual int setScreenCaptureContentHint (VideoContentHint contentHint)=0
 
virtual int updateScreenCaptureParameters (const ScreenCaptureParameters &captureParams)=0
 
virtual int updateScreenCaptureRegion (const Rectangle &regionRect)=0
 
virtual int stopScreenCapture ()=0
 
virtual int startScreenCapture (WindowIDType windowId, int captureFreq, const Rect *rect, int bitrate)=0
 
virtual int updateScreenCaptureRegion (const Rect *rect)=0
 
virtual int getCallId (agora::util::AString &callId)=0
 
virtual int rate (const char *callId, int rating, const char *description)=0
 
virtual int complain (const char *callId, const char *description)=0
 
virtual const char * getVersion (int *build)=0
 
virtual int enableLastmileTest ()=0
 
virtual int disableLastmileTest ()=0
 
virtual int startLastmileProbeTest (const LastmileProbeConfig &config)=0
 
virtual int stopLastmileProbeTest ()=0
 
virtual const char * getErrorDescription (int code)=0
 
virtual int setEncryptionSecret (const char *secret)=0
 
virtual int setEncryptionMode (const char *encryptionMode)=0
 
virtual int registerPacketObserver (IPacketObserver *observer)=0
 
virtual int createDataStream (int *streamId, bool reliable, bool ordered)=0
 
virtual int sendStreamMessage (int streamId, const char *data, size_t length)=0
 
virtual int addPublishStreamUrl (const char *url, bool transcodingEnabled)=0
 
virtual int removePublishStreamUrl (const char *url)=0
 
virtual int setLiveTranscoding (const LiveTranscoding &transcoding)=0
 
virtual int configPublisher (const PublisherConfiguration &config)=0
 
virtual int setVideoCompositingLayout (const VideoCompositingLayout &sei)=0
 
virtual int clearVideoCompositingLayout ()=0
 
virtual int addVideoWatermark (const RtcImage &watermark)=0
 
virtual int clearVideoWatermarks ()=0
 
virtual int setBeautyEffectOptions (bool enabled, BeautyOptions options)=0
 
virtual int addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0
 
virtual int removeInjectStreamUrl (const char *url)=0
 
virtual bool registerEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual bool unregisterEventHandler (IRtcEngineEventHandler *eventHandler)=0
 
virtual CONNECTION_STATE_TYPE getConnectionState ()=0
 

Protected Member Functions

virtual ~IRtcEngine ()
 

Detailed Description

IRtcEngine is the base interface class of the Agora SDK that provides the main Agora SDK methods invoked by your application.

Enable the Agora SDK's communication functionality through the creation of an IRtcEngine object, then call the methods of this object.

Member Typedef Documentation

◆ WindowIDType [1/2]

◆ WindowIDType [2/2]

Constructor & Destructor Documentation

◆ ~IRtcEngine()

virtual agora::rtc::IRtcEngine::~IRtcEngine ( )
inlineprotectedvirtual

Member Function Documentation

◆ initialize()

virtual int agora::rtc::IRtcEngine::initialize ( const RtcEngineContext context)
pure virtual

Initializes the Agora SDK service.

After calling the createAgoraRtcEngine() method to create an IRtcEngine object, call this method to initialize the Agora SDK service before calling any method. After initialization, the service is set to voice mode by default. Use the issued Agora App ID in RtcEngineContext.

Warning
  • Only users with the same App ID can call each other.
  • Each IRtcEngine instance can use only one App ID. If you need to change the App ID, call the release method to release the current IRtcEngine instance first, and then call this method to create a new IRtcEngine instance.
Parameters
contextPointer to the RTC engine context. See RtcEngineContext.
Returns
  • 0: Success.
  • < 0: Failure.

◆ release()

virtual void agora::rtc::IRtcEngine::release ( bool  sync = false)
pure virtual

Releases all IRtcEngine resources.

Parameters
sync
  • true: (Synchronous call) The result returns after the IRtcEngine resources are released. The application should not call this method in the SDK generated callbacks. Otherwise, the SDK must wait for the callbacks to return to recover the associated IRtcEngine resources, resulting in a deadlock. The SDK automatically detects the deadlock and converts this method into an asynchronous call, causing the test to take additional time.
  • false: (Asynchronous call) The result returns immediately, even when the IRtcEngine resources have not been released. The SDK releases all resources.
Note
Do not immediately uninstall the SDK's dynamic library after the call, or it may cause a crash due to the SDK clean-up thread not quitting.

◆ setChannelProfile()

virtual int agora::rtc::IRtcEngine::setChannelProfile ( CHANNEL_PROFILE_TYPE  profile)
pure virtual

Sets the channel profile.

The SDK needs to know the application scenario to set the appropriate channel profile to apply different optimization methods.

Note
  • Users in the same channel must use the same channel profile.
  • Before calling this method to set a new channel profile, release the current engine and create a new engine using createAgoraRtcEngine() and initialize.
  • Call this method before a user joins a channel because you cannot configure the channel profile when the channel is in use.
  • In the Communication profile, the Agora SDK supports encoding only in raw data, not in texture.
Parameters
profileSets the channel profile. See CHANNEL_PROFILE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setClientRole()

virtual int agora::rtc::IRtcEngine::setClientRole ( CLIENT_ROLE_TYPE  role)
pure virtual

Sets the role of the user, such as a host or an audience (default), before joining a channel in a live broadcast.

This method can be used to switch the user role in a live broadcast after the user joins a channel.

Parameters
roleSets the role of the user. See CLIENT_ROLE_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ joinChannel()

virtual int agora::rtc::IRtcEngine::joinChannel ( const char *  token,
const char *  channelId,
const char *  info,
uid_t  uid 
)
pure virtual

Allows a user to join a channel.

Users in the same channel can talk to each other, and multiple users in the same channel can start a group chat. Users with different App IDs cannot call each other.

You must call the leaveChannel method to exit the current call before entering another channel.

Note
A channel does not accept duplicate uids, such as two users with the same uid. If you set uid as 0, the system automatically assigns a uid.
Warning
Ensure that the App ID used for creating the token is the same App ID used by the initialize method for initializing the RTC engine. Otherwise, the CDN live streaming may fail.
Parameters
tokenPointer to the token generated by the application server. In most circumstances, a static App ID suffices. For added security, use a Channel Key.
  • If the user uses a static App ID, token is optional and can be set as NULL.
  • If the user uses a Channel Key, Agora issues an additional App Certificate for you to generate a user key based on the algorithm and App Certificate for user authentication on the server.
channelIdPointer to the unique channel name for the Agora RTC session in the string format smaller than 64 bytes. Supported characters:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • The space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
info(Optional) Pointer to additional information about the channel. This parameter can be set to NULL or contain channel related information. Other users in the channel will not receive this message.
uid(Optional) User ID. A 32-bit unsigned integer with a value ranging from 1 to 232-1. The uid must be unique. If a uid is not assigned (or set to 0), the SDK assigns and returns a uid in the onJoinChannelSuccess callback. Your application must record and maintain the returned uid since the SDK does not do so.
Returns

◆ leaveChannel()

virtual int agora::rtc::IRtcEngine::leaveChannel ( )
pure virtual

Allows a user to leave a channel, such as hanging up or exiting a call.

After joining a channel, the user must call the leaveChannel method to end the call before joining another channel.

This method returns 0 if the user leaves the channel and releases all resources related to the call.

This method call is asynchronous, and the user has not left the channel when the method call returns. Once the user leaves the channel, the SDK triggers the onLeaveChannel callback.

Note
  • If you call the release method immediately after the leaveChannel method, the leaveChannel process interrupts, and the onLeaveChannel callback is not triggered.
  • If you call the leaveChannel method during a CDN live streaming, the SDK triggers the removePublishStreamUrl method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

virtual int agora::rtc::IRtcEngine::renewToken ( const char *  token)
pure virtual

Gets a new token when the current token expires after a period of time.

The token expires after a period of time once the token schema is enabled when:

The application should call this method to get the new token. Failure to do so will result in the SDK disconnecting from the server.

Parameters
tokenPointer to the new token.
Returns
  • 0: Success.
  • < 0: Failure.

◆ queryInterface()

virtual int agora::rtc::IRtcEngine::queryInterface ( INTERFACE_ID_TYPE  iid,
void **  inter 
)
pure virtual

Retrieves the pointer to the device manager object.

Parameters
iidID of the interface.
interPointer to the DeviceManager object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [1/2]

virtual int agora::rtc::IRtcEngine::startEchoTest ( )
pure virtual

DEPRECATED Starts an audio call test.

This method is deprecated as of v2.4.0.

This method starts an audio call test to check whether the audio devices (for example, headset and speaker) and the network connection are working properly.

To conduct the test:

  • The user speaks and the recording is played back within 10 seconds.
  • If the user can hear the recording within 10 seconds, the audio devices and network connection are working properly.
Note
  • After calling this method, always call the stopEchoTest method to end the test. Otherwise, the application cannot run the next echo test.
  • In the Live-broadcast profile, only the hosts can call this method. If the user switches from the Communication to Live-broadcast profile, the user must call the setClientRole method to change the user role from the audience (default) to the host before calling this method.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startEchoTest() [2/2]

virtual int agora::rtc::IRtcEngine::startEchoTest ( int  intervalInSeconds)
pure virtual

Starts an audio call test.

This method starts an audio call test to determine whether the audio devices (for example, headset and speaker) and the network connection are working properly.

In the audio call test, you record your voice. If the recording plays back within the set time interval, the audio devices and the network connection are working properly.

Note
  • Call this method before joining a channel.
  • After calling this method, call the stopEchoTest method to end the test. Otherwise, the app cannot run the next echo test, or call the joinChannel method.
  • In the Live-broadcast profile, only a host can call this method.
Parameters
intervalInSecondsThe time interval (s) between when you speak and when the recording plays back.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopEchoTest()

virtual int agora::rtc::IRtcEngine::stopEchoTest ( )
pure virtual

Stops the audio call test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ enableVideo()

virtual int agora::rtc::IRtcEngine::enableVideo ( )
pure virtual

Enables the video module.

Call this method either before joining a channel or during a call. If this method is called before joining a channel, the call starts in the video mode. If this method is called during an audio call, the audio mode switches to the video mode. To disable the video module, call the disableVideo method.

Note
  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableVideo()

virtual int agora::rtc::IRtcEngine::disableVideo ( )
pure virtual

Disables the video module.

This method can be called before joining a channel or during a call. If this method is called before joining a channel, the call starts in audio mode. If this method is called during a video call, the video mode switches to the audio mode. To enable the video module, call the enableVideo method.

Note
  • This method affects the internal engine and can be called after the leaveChannel method.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the video engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoProfile()

virtual int agora::rtc::IRtcEngine::setVideoProfile ( VIDEO_PROFILE_TYPE  profile,
bool  swapWidthAndHeight 
)
pure virtual

DEPRECATED Sets the video profile.

This method is deprecated as of v2.3. Use the setVideoEncoderConfiguration method instead.

Each video profile includes a set of parameters, such as the resolution, frame rate, and bitrate. If the camera device does not support the specified resolution, the SDK automatically chooses a suitable camera resolution, keeping the encoder resolution specified by the setVideoProfile method.

Note
  • If you do not need to set the video profile after joining the channel, call this method before the enableVideo method to reduce the render time of the first video frame.
  • Always set the video profile before calling the joinChannel or startPreview method.
Parameters
profileSets the video profile. See VIDEO_PROFILE_TYPE.
swapWidthAndHeightSets whether to swap the width and height of the video stream:
  • true: Swap the width and height.
  • false: (Default) Do not swap the width and height. The width and height of the output video are consistent with the set video profile.
Note
Since the landscape or portrait mode of the output video can be decided directly by the video profile, We recommend setting swapWidthAndHeight to false (default).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoEncoderConfiguration()

virtual int agora::rtc::IRtcEngine::setVideoEncoderConfiguration ( const VideoEncoderConfiguration config)
pure virtual

Sets the video encoder configuration.

Each video encoder configuration corresponds to a set of video parameters, including the resolution, frame rate, bitrate, and video orientation.

The parameters specified in this method are the maximum values under ideal network conditions. If the video engine cannot render the video using the specified parameters due to poor network conditions, the parameters further down the list are considered until a successful configuration is found.

Note
If you do not need to set the video encoder configuration after joining the channel, you can call this method before the enableVideo method to reduce the render time of the first video frame.
Parameters
configSets the local video encoder configuration. See VideoEncoderConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupLocalVideo()

virtual int agora::rtc::IRtcEngine::setupLocalVideo ( const VideoCanvas canvas)
pure virtual

Sets the local video view and configures the video display settings on the local machine.

The application calls this method to bind each video window (view) of the local video streams and configures the video display settings. Call this method after initialization to configure the local video display settings before joining a channel. The binding is still valid after the user leaves the channel, which means that the window still displays. To unbind the view, set the view in VideoCanvas to NULL.

Parameters
canvasPointer to the local video view and settings. See VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setupRemoteVideo()

virtual int agora::rtc::IRtcEngine::setupRemoteVideo ( const VideoCanvas canvas)
pure virtual

Sets the remote video view.

This method binds the remote user to the video display window (sets the view for the remote user by the specified uid in VideoCanvas).

The application specifies the uid of the remote video in this method before the remote user joins the channel.

If the remote uid is unknown to the application, set it after the application receives the onUserJoined callback.

If the Video Recording function is enabled, the Video Recording Service joins the channel as a dummy client, causing other clients to also receive the onUserJoined callback. Do not bind the dummy client to the application view because the dummy client does not send any video streams. If your application does not recognize the dummy client, bind the remote user to the view when the SDK triggers the onFirstRemoteVideoDecoded callback.

To unbind the remote user from the view, set the view in VideoCanvas to NULL. Once the remote user leaves the channel, the SDK unbinds the remote user.

Parameters
canvasPointer to the remote video view and settings. See VideoCanvas.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startPreview()

virtual int agora::rtc::IRtcEngine::startPreview ( )
pure virtual

Starts the local video preview before joining the channel.

Before calling this method, you must:

  • Call the setupLocalVideo method to set up the local preview window and configure the attributes.
  • Call the enableVideo method to enable video.
Note
Once the startPreview method is called to start the local video preview, if you leave the channel by calling the leaveChannel method, the local video preview remains until you call the stopPreview method to disable it.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setRemoteUserPriority()

virtual int agora::rtc::IRtcEngine::setRemoteUserPriority ( uid_t  uid,
PRIORITY_TYPE  userPriority 
)
pure virtual

Prioritizes a remote user's stream.

Use this method with the setRemoteSubscribeFallbackOption method. If the fallback function is enabled for a subscribed stream, the SDK ensures the high-priority user gets the best possible stream quality.

Note
The Agora SDK supports setting userPriority as high for one user only.
Parameters
uidThe ID of the remote user.
userPrioritySets the priority of the remote user. See PRIORITY_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopPreview()

virtual int agora::rtc::IRtcEngine::stopPreview ( )
pure virtual

Stops the local video preview and disables video.

Returns
  • 0: Success.
  • < 0: Failure.

◆ enableAudio()

virtual int agora::rtc::IRtcEngine::enableAudio ( )
pure virtual

Enables the audio module.

The audio mode is enabled by default.

Note
  • This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. We recommend using the following API methods to control the audio engine modules separately:
Returns
  • 0: Success.
  • < 0: Failure.

◆ enableLocalAudio()

virtual int agora::rtc::IRtcEngine::enableLocalAudio ( bool  enabled)
pure virtual

Disables/Re-enables the local audio function.

The audio function is enabled by default. This method disables or re-enables the local audio function, that is, to stop or restart local audio capturing.

This method does not affect receiving or playing the remote audio streams.

The SDK triggers the onMicrophoneEnabled callback once the local audio function is disabled or enabled.

Note
Parameters
enabledSets whether to disable/re-enable the local audio function:
  • true: (Default) Re-enable the local audio function, that is, to start the local audio capturing device (for example, the microphone).
  • false: Disable the local audio function, that is, to stop local audio capturing.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableAudio()

virtual int agora::rtc::IRtcEngine::disableAudio ( )
pure virtual

Disables the audio module.

Note
  • This method affects the internal engine and can be called after the leaveChannel method. You can call this method either before or after joining a channel.
  • This method resets the internal engine and takes some time to take effect. We recommend using the enableLocalAudio and muteLocalAudioStream methods to capture, process, and send the local audio streams.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioProfile()

virtual int agora::rtc::IRtcEngine::setAudioProfile ( AUDIO_PROFILE_TYPE  profile,
AUDIO_SCENARIO_TYPE  scenario 
)
pure virtual

Sets the audio parameters and application scenarios.

Note
  • The setAudioProfile method must be called before the joinChannel method.
  • In the Communication profile, you can set the profile but not the scenario.
  • In the Communication and Live-broadcast profiles, the bitrate may be different from your settings due to network self-adaptation.
  • In scenarios involving music education, we recommend setting profile as AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) and scenario as AUDIO_SCENARIO_GAME_STREAMING (3).
Parameters
profileSets the sample rate, bitrate, encoding mode, and the number of channels. See AUDIO_PROFILE_TYPE.
scenarioSets the audio application scenario. See AUDIO_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startScreenCaptureByDisplayId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByDisplayId ( unsigned int  displayId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a screen by specifying the display ID.

Parameters
displayIdThe display ID of the screen to be shared. This parameter specifies which screen you want to share. For information on how to get the displayId, see [Share the Screen].
regionRect(Optional) Sets the relative location of the region to the screen. NIL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParamsSets the screen sharing encoding parameters. See ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being shared. Call stopScreenCapture to stop the current screen sharing.
    • ERR_INVALID_ARGUMENT: the argument is invalid.

◆ startScreenCaptureByScreenRect()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByScreenRect ( const Rectangle screenRect,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a screen by specifying the screen rect.

Parameters
screenRectSets the relative location of the screen to the virtual screen. For information on how to get screenRect, see [Share the Screen].
regionRect(Optional) Sets the relative location of the region to the screen. NULL means sharing the whole screen. See Rectangle. If the specified region overruns the screen, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen.
captureParamsSets the screen sharing encoding parameters. See ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_INVALID_STATE: the screen sharing state is invalid, probably because another screen or window is being shared. Call stopScreenCapture to stop the current screen sharing.
    • ERR_INVALID_ARGUMENT: the argument is invalid.

◆ startScreenCaptureByWindowId()

virtual int agora::rtc::IRtcEngine::startScreenCaptureByWindowId ( view_t  windowId,
const Rectangle regionRect,
const ScreenCaptureParameters captureParams 
)
pure virtual

Shares the whole or part of a window by specifying the window ID.

Parameters
windowIdThe ID of the window to be shared. For information on how to get the windowId, see [Share the Window].
regionRect(Optional) The relative location of the region to the window. NULL/NIL means sharing the whole window. See Rectangle. If the specified region overruns the window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole window.
captureParamsWindow sharing encoding parameters. See ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_INVALID_STATE: the window sharing state is invalid, probably because another screen or window is being shared. Call stopScreenCapture to stop sharing the current window.
    • ERR_INVALID_ARGUMENT: the argument is invalid.

◆ setScreenCaptureContentHint()

virtual int agora::rtc::IRtcEngine::setScreenCaptureContentHint ( VideoContentHint  contentHint)
pure virtual

Sets the content hint for screen sharing.

A content hint suggests the type of the content being shared, so that the SDK applies different optimization algorithm to different types of content.

Parameters
contentHintSets the content hint for screen sharing. See VideoContentHint.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateScreenCaptureParameters()

virtual int agora::rtc::IRtcEngine::updateScreenCaptureParameters ( const ScreenCaptureParameters captureParams)
pure virtual

Updates the screen sharing parameters.

Parameters
captureParamsSets the screen sharing encoding parameters. See ScreenCaptureParameters.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_NOT_READY: no screen or windows is being shared.

◆ updateScreenCaptureRegion() [1/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rectangle regionRect)
pure virtual

Updates the screen sharing region.

Parameters
regionRectSets the relative location of the region to the screen or window. NULL means sharing the whole screen or window. See Rectangle. If the specified region overruns the screen or window, the SDK shares only the region within it; if you set width or height as 0, the SDK shares the whole screen or window.
Returns
  • 0: Success.
  • < 0: Failure:
    • ERR_NOT_READY: no screen or window is being shared.

◆ stopScreenCapture()

virtual int agora::rtc::IRtcEngine::stopScreenCapture ( )
pure virtual

Stop screen sharing.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startScreenCapture()

virtual int agora::rtc::IRtcEngine::startScreenCapture ( WindowIDType  windowId,
int  captureFreq,
const Rect rect,
int  bitrate 
)
pure virtual

DEPRECATED Starts screen sharing.

This method is deprecated as of v2.4.0. See the following methods instead:

This method shares the whole screen, specified window, or specified region:

  • Whole screen: Set windowId as 0 and rect as NULL.
  • Specified window: Set windowId as a value other than 0. Each window has a windowId that is not 0.
  • Specified region: Set windowId as 0 and rect not as NULL. In this case, you can share the specified region, for example by dragging the mouse or implementing your own logic.
Note
The specified region is a region on the whole screen. Currently, sharing a specified region in a specific window is not supported. captureFreq* is the captured frame rate once the screen-sharing function is enabled. The mandatory value ranges between 1 fps and 15 fps.
Parameters
windowIdSets the screen sharing area. See WindowIDType.
captureFreq(Mandatory) The captured frame rate. The value ranges between 1 fps and 15 fps.
rectSpecifies the screen-sharing region. rect is valid when windowsId is set as 0. When rect is set as NULL, the whole screen is shared.
bitrateThe captured bitrate.
Returns
  • 0: Success.
  • < 0: Failure.

◆ updateScreenCaptureRegion() [2/2]

virtual int agora::rtc::IRtcEngine::updateScreenCaptureRegion ( const Rect rect)
pure virtual

DEPRECATED Updates the screen capture region.

Parameters
rectSpecifies the required region inside the screen or window.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getCallId()

virtual int agora::rtc::IRtcEngine::getCallId ( agora::util::AString callId)
pure virtual

Retrieves the current call ID.

When a user joins a channel on a client, a callId is generated to identify the call from the client. Feedback methods, such as rate and complain, must be called after the call ends to submit feedback to the SDK.

The rate and complain methods require the callId parameter retrieved from the getCallId method during a call. callId is passed as an argument into the rate and complain methods after the call ends.

Parameters
callIdPointer to the current call ID.
Returns
  • 0: Success.
  • < 0: Failure.

◆ rate()

virtual int agora::rtc::IRtcEngine::rate ( const char *  callId,
int  rating,
const char *  description 
)
pure virtual

Allows a user to rate a call after the call ends.

Parameters
callIdPointer to the ID of the call, retrieved from the getCallId method.
ratingRating of the call. The value is between 1 (lowest score) and 5 (highest score). If you set a value out of this range, the ERR_INVALID_ARGUMENT (2) error returns.
description(Optional) Pointer to the description of the rating, with a string length of less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ complain()

virtual int agora::rtc::IRtcEngine::complain ( const char *  callId,
const char *  description 
)
pure virtual

Allows a user to complain about the call quality after a call ends.

Parameters
callIdPointer to the ID of the call, retrieved from the getCallId method.
description(Optional) Pointer to the description of the complaint, with a string length of less than 800 bytes.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getVersion()

virtual const char* agora::rtc::IRtcEngine::getVersion ( int *  build)
pure virtual

Retrieves the SDK version number.

Parameters
buildPointer to the build number.
Returns
The version of the current SDK in the string format. For example, 2.3.1.

◆ enableLastmileTest()

virtual int agora::rtc::IRtcEngine::enableLastmileTest ( )
pure virtual

Enables the network connection quality test.

This method tests the quality of the users’ network connections and is disabled by default.

Before a user joins a channel or before an audience switches to a host, call this method to check the uplink network quality.

This method consumes additional network traffic, and hence may affect communication quality.

Call the disableLastmileTest method to disable this test after receiving the onLastmileQuality callback, and before joining a channel.

Note
  • Do not call any other methods before receiving the onLastmileQuality callback. Otherwise, the callback may be interrupted by other methods, and hence may not be triggered.
  • A host should not call this method after joining a channel (when in a call).
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableLastmileTest()

virtual int agora::rtc::IRtcEngine::disableLastmileTest ( )
pure virtual

Disables the network connection quality test.

Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::startLastmileProbeTest ( const LastmileProbeConfig config)
pure virtual

Starts the last-mile network probe test.

This method starts the last-mile network probe test before joining a channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

Call this method to check the uplink network quality before users join a channel or before an audience switches to a host. Once this method is enabled, the SDK returns the following callbacks:

  • onLastmileQuality: the SDK triggers this callback within two seconds depending on the network conditions. This callback rates the network conditions and is more closely linked to the user experience.
  • onLastmileProbeResult: the SDK triggers this callback within 30 seconds depending on the network conditions. This callback returns the real-time statistics of the network conditions and is more objective.
Note
  • This method consumes extra network traffic and may affect communication quality. We do not recommend calling this method together with enableLastmileTest.
  • Do not call other methods before receiving the onLastmileQuality and onLastmileProbeResult callbacks. Otherwise, the callbacks may be interrupted.
  • In the Live-broadcast profile, a host should not call this method after joining a channel.
Parameters
configSets the configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

virtual int agora::rtc::IRtcEngine::stopLastmileProbeTest ( )
pure virtual

Stops the last-mile network probe test.

◆ getErrorDescription()

virtual const char* agora::rtc::IRtcEngine::getErrorDescription ( int  code)
pure virtual

Retrieves the warning or error description.

Returns
code WARN_CODE_TYPE or ERROR_CODE_TYPE returned in the onWarning or onError callback.

◆ setEncryptionSecret()

virtual int agora::rtc::IRtcEngine::setEncryptionSecret ( const char *  secret)
pure virtual

Enables built-in encryption with an encryption password before users join a channel.

All users in a channel must use the same encryption password. The encryption password is automatically cleared once a user leaves the channel.

If an encryption password is not specified, the encryption functionality will be disabled.

Note
Do not use this method for CDN live streaming.
Parameters
secretPointer to the encryption password.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setEncryptionMode()

virtual int agora::rtc::IRtcEngine::setEncryptionMode ( const char *  encryptionMode)
pure virtual

Sets the built-in encryption mode.

The Agora SDK supports built-in encryption, which is set to the aes-128-xts mode by default. Call this method to use other encryption modes.

All users in the same channel must use the same encryption mode and password.

Refer to the information related to the AES encryption algorithm on the differences between the encryption modes.

Note
Call the setEncryptionSecret method to enable the built-in encryption function before calling this method.
Parameters
encryptionModePointer to the set encryption mode:
  • "aes-128-xts": (Default) 128-bit AES encryption, XTS mode.
  • "aes-128-ecb": 128-bit AES encryption, ECB mode.
  • "aes-256-xts": 256-bit AES encryption, XTS mode.
  • "": When encryptionMode is set as NULL, the encryption mode is set as "aes-128-xts" by default.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerPacketObserver()

virtual int agora::rtc::IRtcEngine::registerPacketObserver ( IPacketObserver observer)
pure virtual

Registers a packet observer.

The Agora SDK allows your application to register a packet observer to receive callbacks for voice or video packet transmission.

Parameters
observerPointer to the registered packet observer. See IPacketObserver.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream()

virtual int agora::rtc::IRtcEngine::createDataStream ( int *  streamId,
bool  reliable,
bool  ordered 
)
pure virtual

Creates a data stream.

Each user can have up to five simultaneous data streams in a channel.

Note
Set both the reliable and ordered parameters to true or false. Do not set one as true and the other as false.
Parameters
streamIdPointer to the ID of the created data stream.
reliableSets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
  • true: The recipients receive the data stream from the sender within five seconds. If the recipient does not receive the data stream within five seconds, an error is reported to the application.
  • false: There is no guarantee that the recipients receive the data stream within five seconds and no error message is reported for any delay or missing data stream.
orderedSets whether or not the recipients receive the data stream in the sent order:
  • true: The recipients receive the data stream in the sent order.
  • false: The recipients do not receive the data stream in the sent order.
Returns
  • Returns the ID of the data stream, if this method call succeeds.
  • < 0: Failure.

◆ sendStreamMessage()

virtual int agora::rtc::IRtcEngine::sendStreamMessage ( int  streamId,
const char *  data,
size_t  length 
)
pure virtual

Sends data stream messages to all users in a channel.

The SDK has the following restrictions on this method:

  • Up to 30 packets can be sent per second in a channel with each packet having a maximum size of 1 kB.
  • Each client can send up to 6 kB of data per second.
  • Each user can have up to five data streams simultaneously.
Note
This method applies only to the Communication profile or to the hosts in the Live-broadcast profile. If an audience in the Live-broadcast profile calls this method, the audience may be switched to a host.
Parameters
streamIdID of the sent data stream, returned in the createDataStream method.
dataPointer to the sent data.
lengthLength of the sent data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ addPublishStreamUrl()

virtual int agora::rtc::IRtcEngine::addPublishStreamUrl ( const char *  url,
bool  transcodingEnabled 
)
pure virtual

Adds a stream RTMP URL address, to which the host publishes the stream. (CDN live only.)

The host publishes the stream to the specified CDN live RTMP address. The corresponding callback is: onStreamPublished.

Note
  • Ensure that the user joins the channel before calling this method.
  • This method adds only one stream RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
Parameters
urlPointer to the RTMP URL address, to which the host publishes the stream.
transcodingEnabledSets whether transcoding is enabled/disabled:
  • true: Enable transcoding. To transcode the audio or video streams when publishing them to CDN live, often used for combining the audio and video streams of multiple hosts in CDN live.
  • false: Disable transcoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ removePublishStreamUrl()

virtual int agora::rtc::IRtcEngine::removePublishStreamUrl ( const char *  url)
pure virtual

Removes a stream RTMP URL address. (CDN live only.)

This method removes the RTMP URL address (added by the addPublishStreamUrl method) from a CDN live stream.

Note
  • This method removes only one RTMP URL address each time it is called.
  • The RTMP URL address must not contain special characters, such as Chinese language characters.
Parameters
urlPointer to the RTMP URL address to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLiveTranscoding()

virtual int agora::rtc::IRtcEngine::setLiveTranscoding ( const LiveTranscoding transcoding)
pure virtual

Sets the video layout and audio settings for CDN live. (CDN live only.)

Parameters
transcodingSets the CDN live audio/video transcoding settings. See LiveTranscoding.
Returns
  • 0: Success.
  • < 0: Failure.

◆ configPublisher()

virtual int agora::rtc::IRtcEngine::configPublisher ( const PublisherConfiguration config)
pure virtual

DEPRECATED Configures the CDN live stream before the user joins a channel.

This method is deprecated. We recommend using the following methods instead:

Parameters
configPointer to the CDN live streaming settings. See PublisherConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setVideoCompositingLayout()

virtual int agora::rtc::IRtcEngine::setVideoCompositingLayout ( const VideoCompositingLayout sei)
pure virtual

DEPRECATED Sets the picture-in-picture layouts for CDN live broadcasts. (CDN live only.)

Note
This method is deprecated and we recommend using the setLiveTranscoding method instead. This method is only applicable when you want to push streams to the Agora server. When you push the stream to the server, you need to:
  1. Define a canvas, the width and height (video resolution), background color, and the total number of video streams you want to display.
  2. Define the position and size for each video stream on the canvas, and indicate whether the view is cropped or zoomed to fit.
Note
  • Call this method after the user joins the channel.
  • The application should only allow one user to call this method in the same channel. If more than one user calls this method, the other users must call the clearVideoCompositingLayout method to remove the settings.
Parameters
seiPointer to the video compositing layout. See VideoCompositingLayout.
Returns
  • 0: Success.
  • < 0: Failure.

◆ clearVideoCompositingLayout()

virtual int agora::rtc::IRtcEngine::clearVideoCompositingLayout ( )
pure virtual

DEPRECATED Removes the picture-in-picture layout settings created by the setVideoCompositingLayout method. (CDN live only.)

Returns
  • 0: Success.
  • < 0: Failure.

◆ addVideoWatermark()

virtual int agora::rtc::IRtcEngine::addVideoWatermark ( const RtcImage watermark)
pure virtual

Adds a watermark image to the local video or CDN live stream.

This method adds a PNG watermark image to the local video stream for the recording device, channel audience, and CDN live audience to view and capture.

To add the PNG file to the CDN live publishing stream, see the setLiveTranscoding method.

Parameters
watermarkPointer to the watermark image to be added to the local video stream. See RtcImage.
Note
  • The URL descriptions are different for the local video and CDN live streams:
    • In a local video stream, url in RtcImage refers to the absolute path of the added watermark image file in the local video stream.
    • In a CDN live stream, url in RtcImage refers to the URL address of the added watermark image in the CDN live broadcast.
  • The source file of the watermark image must be in the PNG file format. If the width and height of the PNG file differ from your settings in this method, the PNG file will be cropped to conform to your settings.
  • The Agora SDK supports adding only one watermark image onto a local video or CDN live stream. The newly added watermark image replaces the previous one.
Returns
  • 0: Success.
  • < 0: Failure.

◆ clearVideoWatermarks()

virtual int agora::rtc::IRtcEngine::clearVideoWatermarks ( )
pure virtual

Removes the watermark image from the video stream added by the addVideoWatermark method.

Returns
  • 0: Success.
  • < 0: Failure.

◆ setBeautyEffectOptions()

virtual int agora::rtc::IRtcEngine::setBeautyEffectOptions ( bool  enabled,
BeautyOptions  options 
)
pure virtual

Enables/Disables image enhancement and sets the options.

Parameters
enabledSets whether or not to enable image enhancement:
  • true: enables image enhancement.
  • false: disables image enhancement.
optionsSets the image enhancement option. See BeautyOptions.

◆ addInjectStreamUrl()

virtual int agora::rtc::IRtcEngine::addInjectStreamUrl ( const char *  url,
const InjectStreamConfig config 
)
pure virtual

Adds a voice or video stream URL address to a live broadcast.

Parameters
urlPointer to the URL address to be added to the ongoing live broadcast. Valid protocols are RTMP, HLS, and FLV.
  • Supported FLV audio codec type: AAC.
  • Supported FLV video codec type: H264 (AVC).
configPointer to the InjectStreamConfig object that contains the configuration of the added voice or video stream.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT (2): The injected URL does not exist. Call this method again to inject the stream and ensure that the URL is valid.
    • ERR_NOT_READY (3): The user is not in the channel.
    • ERR_NOT_SUPPORTED (4): The channel profile is not live broadcast. Call the setChannelProfile method and set the channel profile to live broadcast before calling this method.
    • ERR_NOT_INITIALIZED (7): The SDK is not initialized. Ensure that the IRtcEngine object is initialized before calling this method.

◆ removeInjectStreamUrl()

virtual int agora::rtc::IRtcEngine::removeInjectStreamUrl ( const char *  url)
pure virtual

Removes the voice or video stream URL address from a live broadcast.

This method removes the URL address (added by the addInjectStreamUrl method) from the live broadcast.

Note
If this method is called successfully, the SDK triggers the onUserOffline callback and returns a stream uid of 666.
Parameters
urlPointer to the URL address of the added stream to be removed.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerEventHandler()

virtual bool agora::rtc::IRtcEngine::registerEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

◆ unregisterEventHandler()

virtual bool agora::rtc::IRtcEngine::unregisterEventHandler ( IRtcEngineEventHandler eventHandler)
pure virtual

◆ getConnectionState()

virtual CONNECTION_STATE_TYPE agora::rtc::IRtcEngine::getConnectionState ( )
pure virtual

Gets the connection state of the SDK.

Returns
CONNECTION_STATE_TYPE.