Agora Java API Reference for Android
Public Member Functions | List of all members
agora::base::IAgoraService Class Referenceabstract

#include <IAgoraService.h>

Public Member Functions

virtual int initialize (const AgoraServiceConfiguration &config)=0
 
virtual void atExit ()=0
 
virtual int release ()=0
 
virtual int setAudioSessionPreset (agora::rtc::AUDIO_SCENARIO_TYPE scenario)=0
 
virtual int setAudioSessionConfiguration (const AudioSessionConfiguration &config)=0
 
virtual int getAudioSessionConfiguration (AudioSessionConfiguration *config)=0
 
virtual int setLogFile (const char *filePath, unsigned int fileSize)=0
 
virtual int setLogFilter (unsigned int filters)=0
 
virtual agora_refptr< rtc::IRtcConnectioncreateRtcConnection (const rtc::RtcConnectionConfiguration &cfg)=0
 
virtual agora_refptr< rtc::IRtmpConnectioncreateRtmpConnection (const rtc::RtmpConnectionConfiguration &cfg)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateLocalAudioTrack ()=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateCustomAudioTrack (agora_refptr< rtc::IAudioPcmDataSender > audioSource)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateCustomAudioTrack (agora_refptr< rtc::IAudioPcmDataSender > audioSource, bool enableAec)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateCustomAudioTrack (agora_refptr< rtc::IRemoteAudioMixerSource > audioSource)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateCustomAudioTrack (agora_refptr< rtc::IAudioEncodedFrameSender > audioSource, TMixMode mixMode)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateCustomAudioTrack (agora_refptr< rtc::IMediaPacketSender > source)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateMediaPlayerAudioTrack (agora_refptr< rtc::IMediaPlayerSource > audioSource)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateMediaStreamingAudioTrack (agora_refptr< rtc::IMediaStreamingSource > streamingSource)=0
 
virtual agora_refptr< rtc::ILocalAudioTrackcreateRecordingDeviceAudioTrack (agora_refptr< rtc::IRecordingDeviceSource > audioSource, bool enableAec)=0
 
virtual agora_refptr< rtc::INGAudioDeviceManagercreateAudioDeviceManager ()=0
 
virtual agora_refptr< rtc::IMediaNodeFactorycreateMediaNodeFactory ()=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateCameraVideoTrack (agora_refptr< rtc::ICameraCapturer > videoSource)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateScreenVideoTrack (agora_refptr< rtc::IScreenCapturer > videoSource)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateMixedVideoTrack (agora_refptr< rtc::IVideoMixerSource > videoSource)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateTranscodedVideoTrack (agora_refptr< rtc::IVideoFrameTransceiver > transceiver)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateCustomVideoTrack (agora_refptr< rtc::IVideoFrameSender > videoSource)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateCustomVideoTrack (agora_refptr< rtc::IVideoEncodedImageSender > videoSource, SenderOptions &options)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateCustomVideoTrack (agora_refptr< rtc::IMediaPacketSender > source)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateMediaPlayerVideoTrack (agora_refptr< rtc::IMediaPlayerSource > videoSource)=0
 
virtual agora_refptr< rtc::ILocalVideoTrackcreateMediaStreamingVideoTrack (agora_refptr< rtc::IMediaStreamingSource > streamingSource)=0
 
virtual agora_refptr< rtc::IRtmpStreamingServicecreateRtmpStreamingService (agora_refptr< rtc::IRtcConnection > rtcConnection, const char *appId)=0
 
virtual agora_refptr< rtc::IMediaRelayServicecreateMediaRelayService (agora_refptr< rtc::IRtcConnection > rtcConnection, const char *appId)=0
 
virtual rtm::IRtmServicecreateRtmService ()=0
 
virtual int addExtensionObserver (agora::agora_refptr< agora::rtc::IMediaExtensionObserver > observer)=0
 
virtual int removeExtensionObserver (agora::agora_refptr< agora::rtc::IMediaExtensionObserver > observer)=0
 
virtual agora_refptr< rtc::IAudioDeviceManager > createAudioDeviceManagerComponent (rtc::IAudioDeviceManagerObserver *observer)=0
 
virtual const char * getExtensionId (const char *provider_name, const char *extension_name)=0
 Get the ID of the registered extension. More...
 
virtual int enableExtension (const char *provider_name, const char *extension_name, const char *track_id=NULL, bool auto_enable_on_track=false)=0
 
virtual int disableExtension (const char *provider_name, const char *extension_name, const char *track_id=NULL)=0
 

Detailed Description

The IAgoraService class.

IAgoraService is the entry point of Agora low-level APIs. Use this interface to create access points to Agora interfaces, including RTC connections and media tracks.

You can create an IAgoraService object by calling createAgoraService.

You can configure the IAgoraService object for different user scenarios on the global level by using AgoraServiceConfiguration.

Member Function Documentation

◆ initialize()

virtual int agora::base::IAgoraService::initialize ( const AgoraServiceConfiguration config)
pure virtual

Initializes the AgoraService object.

Parameters
configThe configuration of the initialization. For details, see AgoraServiceConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.
    • ERR_INVALID_ARGUMENT, if context in AgoraServiceConfiguration is not provided for Android.
    • ERR_INIT_NET_ENGINE, if the network engine cannot be initialized. On Windows, the error occurs mostly because the connection to the local port is disabled by the firewall. In this case, turn off the firewall and then turn it on again.

◆ atExit()

virtual void agora::base::IAgoraService::atExit ( )
pure virtual

Flush log & cache before exit

◆ release()

virtual int agora::base::IAgoraService::release ( )
pure virtual

Releases the AgoraService object.

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

◆ setAudioSessionPreset()

virtual int agora::base::IAgoraService::setAudioSessionPreset ( agora::rtc::AUDIO_SCENARIO_TYPE  scenario)
pure virtual

Configures the preset audio scenario.

Parameters
scenarioThe preset audio scenario: AUDIO_SCENARIO_TYPE.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setAudioSessionConfiguration()

virtual int agora::base::IAgoraService::setAudioSessionConfiguration ( const AudioSessionConfiguration config)
pure virtual

Customizes the audio session configuration.

Parameters
configThe reference to the audio session configuration: AudioSessionConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAudioSessionConfiguration()

virtual int agora::base::IAgoraService::getAudioSessionConfiguration ( AudioSessionConfiguration config)
pure virtual

Gets the audio session configuration.

Parameters
[out]configThe pointer to the audio session configuration: AudioSessionConfiguration.
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFile()

virtual int agora::base::IAgoraService::setLogFile ( const char *  filePath,
unsigned int  fileSize 
)
pure virtual

Sets the path and size of the SDK log files.

The SDK records all the log data during the SDK runtime in two log files, each with a default size of 512 KB. If you set fileSize as 1024 KB, the SDK outputs log files with a maximum size of 2 MB. If the total size of the log files exceeds the set value, the new output log overwrites the old output log.

Note
To ensure that the output log is complete, call this method immediately after calling initialize.
Parameters
filePathThe pointer to the log file. Ensure that the directory of the log file exists and is writable.
fileSizeThe size of the SDK log file size (KB).
Returns
  • 0: Success.
  • < 0: Failure.

◆ setLogFilter()

virtual int agora::base::IAgoraService::setLogFilter ( unsigned int  filters)
pure virtual

Sets the SDK log output filter.

The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, INFO, and DEBUG.

Select a level to output the logs in and above the selected level. For example, if you set the log level to WARNING, you can see the logs in the levels of CRITICAL, ERROR, and WARNING.

Parameters
filtersThe log output filter.
  • LOG_LEVEL_NONE (0x0000): Do not output any log file.
  • LOG_LEVEL_INFO (0x0001): (Recommended) Output log files of the INFO level.
  • LOG_LEVEL_WARN (0x0002): Output log files of the WARN level.
  • LOG_LEVEL_ERROR (0x0004): Output log files of the ERROR level.
  • LOG_LEVEL_FATAL (0x0008): Output log files of the FATAL level.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createRtcConnection()

virtual agora_refptr<rtc::IRtcConnection> agora::base::IAgoraService::createRtcConnection ( const rtc::RtcConnectionConfiguration cfg)
pure virtual

Creates an RtcConnection object and returns the pointer.

Parameters
cfgThe reference to the RTC connection configuration: RtcConnectionConfiguration.
Returns

◆ createLocalAudioTrack()

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createLocalAudioTrack ( )
pure virtual

Creates a local audio track object and returns the pointer.

By default, the audio track is created from the selected audio input device, such as the built-in microphone on a mobile device.

Returns

◆ createCustomAudioTrack() [1/5]

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createCustomAudioTrack ( agora_refptr< rtc::IAudioPcmDataSender audioSource)
pure virtual

Creates a local audio track object with a PCM data sender and returns the pointer.

Once created, this track can be used to send PCM audio data.

Parameters
audioSourceThe pointer to the PCM audio data sender: IAudioPcmDataSender.
Returns

◆ createCustomAudioTrack() [2/5]

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createCustomAudioTrack ( agora_refptr< rtc::IAudioPcmDataSender audioSource,
bool  enableAec 
)
pure virtual

Creates a local audio track object with a PCM data sender and returns the pointer.

Once created, this track can be used to send PCM audio data.

Parameters
audioSourceThe pointer to the PCM audio data sender: IAudioPcmDataSender.
enableAecWhether enable audio echo cancellation for PCM audio data.
Returns

◆ createCustomAudioTrack() [3/5]

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createCustomAudioTrack ( agora_refptr< rtc::IRemoteAudioMixerSource audioSource)
pure virtual

Creates a local audio track object with a audio mixer source and returns the pointer.

Once created, this track can be used to send PCM audio data.

Parameters
audioSourceThe pointer to the audio mixer source : IRemoteAudioMixerSource.
Returns

◆ createCustomAudioTrack() [4/5]

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createCustomAudioTrack ( agora_refptr< rtc::IAudioEncodedFrameSender audioSource,
TMixMode  mixMode 
)
pure virtual

Creates a local audio track object with an encoded audio frame sender and returns the pointer.

Once created, this track can be used to send encoded audio frames, such as Opus frames.

Parameters
audioSourceThe pointer to the encoded audio frame sender: IAudioEncoderFrameSender.
mixModeThe mixing mode of the encoded audio in the channel: #TMixMode.
Returns

◆ createCustomAudioTrack() [5/5]

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createCustomAudioTrack ( agora_refptr< rtc::IMediaPacketSender source)
pure virtual

Creates a local audio track object with a media packet sender and returns the pointer.

Once created, this track can be used to send audio packets, such as customized UDP/RTP packets.

Parameters
sourceThe pointer to the media packet sender: IMediaPacketSender.
Returns

◆ createMediaPlayerAudioTrack()

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createMediaPlayerAudioTrack ( agora_refptr< rtc::IMediaPlayerSource audioSource)
pure virtual

Creates a local audio track object with an IMediaPlayerSource object and returns the pointer.

Once created, this track can be used to send PCM audio data decoded from a media player.

Parameters
audioSourceThe pointer to the player source. See IMediaPlayerSource.
Returns

◆ createMediaStreamingAudioTrack()

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createMediaStreamingAudioTrack ( agora_refptr< rtc::IMediaStreamingSource streamingSource)
pure virtual

Creates a local audio track object with an IMediaStreamingSource object and returns the pointer.

Once created, this track can be used to send encoded audio data which demuxed from a media streaming.

Parameters
streamingSourceThe pointer to the streaming source. See IMediaStreamingSource.
Returns

◆ createRecordingDeviceAudioTrack()

virtual agora_refptr<rtc::ILocalAudioTrack> agora::base::IAgoraService::createRecordingDeviceAudioTrack ( agora_refptr< rtc::IRecordingDeviceSource audioSource,
bool  enableAec 
)
pure virtual

Creates a local audio track object with the recording device source and returns the pointer.

Once created, this track can be used to send audio data got from a recording device.

Parameters
audioSourceThe pointer to the recording device source. See IRecordingDeviceSource.
enableAecWhether enable audio echo cancellation for loopback recording. If loopback recording device is a virtual sound card, it should be false, or it should be true.
Returns

◆ createAudioDeviceManager()

virtual agora_refptr<rtc::INGAudioDeviceManager> agora::base::IAgoraService::createAudioDeviceManager ( )
pure virtual

Creates an audio device manager object and returns the pointer.

Returns

◆ createMediaNodeFactory()

virtual agora_refptr<rtc::IMediaNodeFactory> agora::base::IAgoraService::createMediaNodeFactory ( )
pure virtual

Creates a media node factory object and returns the pointer.

Returns

◆ createCameraVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createCameraVideoTrack ( agora_refptr< rtc::ICameraCapturer videoSource)
pure virtual

Creates a local video track object with a camera capturer and returns the pointer.

Once created, this track can be used to send video data captured by the camera.

Parameters
videoSourceThe pointer to the camera capturer: ICameraCapturer.
Returns

◆ createScreenVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createScreenVideoTrack ( agora_refptr< rtc::IScreenCapturer videoSource)
pure virtual

Creates a local video track object with a screen capturer and returns the pointer.

Once created, this track can be used to send video data for screen sharing.

Parameters
videoSourceThe pointer to the screen capturer: IScreenCapturer.
Returns

◆ createMixedVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createMixedVideoTrack ( agora_refptr< rtc::IVideoMixerSource videoSource)
pure virtual

Creates a local video track object with a video mixer and returns the pointer.

Once created, this track can be used to send video data processed by the video mixer.

Parameters
videoSourceThe pointer to the video mixer. See IVideoMixerSource.
Returns

◆ createTranscodedVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createTranscodedVideoTrack ( agora_refptr< rtc::IVideoFrameTransceiver transceiver)
pure virtual

Creates a local video track object with a video frame transceiver and returns the pointer.

Once created, this track can be used to send video data processed by the transceiver.

Parameters
transceiverThe pointer to the video transceiver. See IVideoFrameTransceiver.
Returns

◆ createCustomVideoTrack() [1/3]

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createCustomVideoTrack ( agora_refptr< rtc::IVideoFrameSender videoSource)
pure virtual

Creates a local video track object with a customized video source and returns the pointer.

Once created, this track can be used to send video data from a customized source.

Parameters
videoSourceThe pointer to the customized video frame sender: IVideoFrameSender.
Returns

◆ createCustomVideoTrack() [2/3]

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createCustomVideoTrack ( agora_refptr< rtc::IVideoEncodedImageSender videoSource,
SenderOptions options 
)
pure virtual

Creates a local video track object with an encoded video image sender and returns the pointer.

Once created, this track can be used to send encoded video images, such as H.264 or VP8 frames.

Parameters
videoSourceThe pointer to the encoded video frame sender. See IVideoEncodedImageSender.
optionsThe configuration for creating video encoded image track.
Returns

◆ createCustomVideoTrack() [3/3]

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createCustomVideoTrack ( agora_refptr< rtc::IMediaPacketSender source)
pure virtual

Creates a local video track object with a media packet sender and returns the pointer.

Once created, this track can be used to send video packets, such as customized UDP/RTP packets.

Parameters
sourceThe pointer to the media packet sender: IMediaPacketSender.
Returns

◆ createMediaPlayerVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createMediaPlayerVideoTrack ( agora_refptr< rtc::IMediaPlayerSource videoSource)
pure virtual

Creates a local video track object with an IMediaPlayerSource object and returns the pointer.

Once created, this track can be used to send YUV frames decoded from a player.

Parameters
videoSourceThe pointer to the player source. See IMediaPlayerSource.
Returns

◆ createMediaStreamingVideoTrack()

virtual agora_refptr<rtc::ILocalVideoTrack> agora::base::IAgoraService::createMediaStreamingVideoTrack ( agora_refptr< rtc::IMediaStreamingSource streamingSource)
pure virtual

Creates a local video track object with an IMediaStreamingSource object and returns the pointer.

Once created, this track can be used to send H264 frames which demuxed from a streaming.

Parameters
streamingSourceThe pointer to the player source. See IMediaStreamingSource.
Returns

◆ createRtmpStreamingService()

virtual agora_refptr<rtc::IRtmpStreamingService> agora::base::IAgoraService::createRtmpStreamingService ( agora_refptr< rtc::IRtcConnection rtcConnection,
const char *  appId 
)
pure virtual

Creates an RTMP streaming service object and returns the pointer.

Parameters
rtcConnectionThe pointer to IRtcConnection.
appIdThe App ID of the live streaming service.
Returns

◆ createMediaRelayService()

virtual agora_refptr<rtc::IMediaRelayService> agora::base::IAgoraService::createMediaRelayService ( agora_refptr< rtc::IRtcConnection rtcConnection,
const char *  appId 
)
pure virtual

Creates an Media Relay service object and returns the pointer.

Parameters
rtcConnectionThe pointer to IRtcConnection.
appIdThe App ID of the media relay service.
Returns
  • The pointer to IMediaRelayService, if the method call succeeds.
  • A null pointer, if the method call fails.

◆ createRtmService()

virtual rtm::IRtmService* agora::base::IAgoraService::createRtmService ( )
pure virtual

Creates an RTM servive object and returns the pointer.

Returns
  • The pointer to IRtmService: Success.
  • A null pointer: Failure.

◆ createAudioDeviceManagerComponent()

virtual agora_refptr<rtc::IAudioDeviceManager> agora::base::IAgoraService::createAudioDeviceManagerComponent ( rtc::IAudioDeviceManagerObserver observer)
pure virtual

Creates an audio device manager and returns the pointer.

Returns
  • The pointer to IAudioDeviceManager: Success.
  • A null pointer: Failure.

◆ getExtensionId()

virtual const char* agora::base::IAgoraService::getExtensionId ( const char *  provider_name,
const char *  extension_name 
)
pure virtual

Get the ID of the registered extension.

Parameters
provider_nameThe pointer to provider name string (null-terminated)
extension_nameThe pointer to extension name string (null-terminated)
Returns
  • Pointer to the extension id string (null-terminated). The pointer will be valid during service's lifetime

◆ enableExtension()

virtual int agora::base::IAgoraService::enableExtension ( const char *  provider_name,
const char *  extension_name,
const char *  track_id = NULL,
bool  auto_enable_on_track = false 
)
pure virtual

Enable extension. If the extension is enabled, the track loads the extension automatically.

Parameters
provider_namename for provider, e.g. agora.io.
extension_namename for extension, e.g. agora.beauty.
track_idid for the track, nullptr means effective on all tracks
auto_enable_on_trackif the extension is automatically open on track.
Returns
  • 0: Success.
  • < 0: Failure.

◆ disableExtension()

virtual int agora::base::IAgoraService::disableExtension ( const char *  provider_name,
const char *  extension_name,
const char *  track_id = NULL 
)
pure virtual

Disable extension.

Parameters
provider_namename for provider, e.g. agora.io.
extension_namename for extension, e.g. agora.beauty.
track_idid for the track, nullptr means effective on all tracks
Returns
  • 0: Success.
  • < 0: Failure.