Public Member Functions | |
virtual | ~IChannel () |
virtual int | release ()=0 |
virtual int | setChannelEventHandler (IChannelEventHandler *channelEh)=0 |
virtual int | joinChannel (const char *token, const char *info, uid_t uid, const ChannelMediaOptions &options)=0 |
virtual int | joinChannelWithUserAccount (const char *token, const char *userAccount, const ChannelMediaOptions &options)=0 |
virtual int | leaveChannel ()=0 |
virtual int | publish ()=0 |
virtual int | unpublish ()=0 |
virtual const char * | channelId ()=0 |
virtual int | getCallId (agora::util::AString &callId)=0 |
virtual int | renewToken (const char *token)=0 |
virtual int | setEncryptionSecret (const char *secret)=0 |
virtual int | setEncryptionMode (const char *encryptionMode)=0 |
virtual int | enableEncryption (bool enabled, const EncryptionConfig &config)=0 |
virtual int | registerPacketObserver (IPacketObserver *observer)=0 |
virtual int | registerMediaMetadataObserver (IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type)=0 |
virtual int | setClientRole (CLIENT_ROLE_TYPE role)=0 |
virtual int | setClientRole (CLIENT_ROLE_TYPE role, const ClientRoleOptions &options)=0 |
virtual int | setRemoteUserPriority (uid_t uid, PRIORITY_TYPE userPriority)=0 |
virtual int | setRemoteVoicePosition (uid_t uid, double pan, double gain)=0 |
virtual int | setRemoteRenderMode (uid_t userId, RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode)=0 |
virtual int | setDefaultMuteAllRemoteAudioStreams (bool mute)=0 |
virtual int | setDefaultMuteAllRemoteVideoStreams (bool mute)=0 |
virtual int | muteAllRemoteAudioStreams (bool mute)=0 |
virtual int | adjustUserPlaybackSignalVolume (uid_t userId, int volume)=0 |
virtual int | muteRemoteAudioStream (uid_t userId, bool mute)=0 |
virtual int | muteAllRemoteVideoStreams (bool mute)=0 |
virtual int | muteRemoteVideoStream (uid_t userId, bool mute)=0 |
virtual int | setRemoteVideoStreamType (uid_t userId, REMOTE_VIDEO_STREAM_TYPE streamType)=0 |
virtual int | setRemoteDefaultVideoStreamType (REMOTE_VIDEO_STREAM_TYPE streamType)=0 |
virtual int | createDataStream (int *streamId, bool reliable, bool ordered)=0 |
virtual int | createDataStream (int *streamId, DataStreamConfig &config)=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 | addInjectStreamUrl (const char *url, const InjectStreamConfig &config)=0 |
virtual int | removeInjectStreamUrl (const char *url)=0 |
virtual int | startChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0 |
virtual int | updateChannelMediaRelay (const ChannelMediaRelayConfiguration &configuration)=0 |
virtual int | stopChannelMediaRelay ()=0 |
virtual CONNECTION_STATE_TYPE | getConnectionState ()=0 |
The IChannel class.
|
inlinevirtual |
|
pure virtual |
Releases all IChannel resources.
ERR_NOT_INITIALIZED (7)
: The SDK is not initialized before calling this method.
|
pure virtual |
Sets the channel event handler.
After setting the channel event handler, you can listen for channel events and receive the statistics of the corresponding IChannel
object.
channelEh | The event handler of the IChannel object. For details, see IChannelEventHandler. |
|
pure virtual |
Joins the channel with a user ID.
This method differs from the joinChannel
method in the IRtcEngine
class in the following aspects:
IChannel::joinChannel | IRtcEngine::joinChannel |
---|---|
Does not contain the channelId parameter, because channelId is specified when creating the IChannel object. | Contains the channelId parameter, which specifies the channel to join. |
Contains the options parameter, which decides whether to subscribe to all streams before joining the channel. | Does not contain the options parameter. By default, users subscribe to all streams when joining the channel. |
Users can join multiple channels simultaneously by creating multiple IChannel objects and calling the joinChannel method of each object. | Users can join only one channel. |
By default, the SDK does not publish any stream after the user joins the channel. You need to call the publish method to do that. | By default, the SDK publishes streams once the user joins the channel. |
Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute
methods accordingly.
uid
.IRtcEngine
object.token | The token for authentication:
|
info | (Optional) Additional information about the channel. This parameter can be set as null. Other users in the channel do not receive this information. |
uid | The user ID. A 32-bit unsigned integer with a value ranging from 1 to (232-1). This parameter must be unique. If uid is not assigned (or set as 0 ), the SDK assigns a uid and reports it in the onJoinChannelSuccess callback. The app must maintain this user ID. |
options | The channel media options: ChannelMediaOptions |
|
pure virtual |
Joins the channel with a user account.
After the user successfully joins the channel, the SDK triggers the following callbacks:
COMMUNICATION
profile, or is a host in the LIVE_BROADCASTING
profile.Once the user joins the channel, the user subscribes to the audio and video streams of all the other users in the channel by default, giving rise to usage and billing calculation. If you do not want to subscribe to a specified stream or all remote streams, call the mute
methods accordingly.
token | The token generated at your server:
|
userAccount | The user account. The maximum length of this parameter is 255 bytes. Ensure that the user account is unique and do not set it as null. Supported character scopes are:
|
options | The channel media options: agora::rtc::ChannelMediaOptions::ChannelMediaOptions “ChannelMediaOptions”. |
|
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.
A successful leaveChannel method call triggers the following callbacks:
LIVE_BROADCASTING
profile.
|
pure virtual |
Publishes the local stream to the channel.
You must keep the following restrictions in mind when calling this method. Otherwise, the SDK returns the ERR_REFUSED (5):
IChannel
object.IChannel
object.
|
pure virtual |
Stops publishing a stream to the channel.
If you call this method in a channel where you are not publishing streams, the SDK returns ERR_REFUSED (5).
|
pure virtual |
|
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.
callId | The current call ID. |
|
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.
token | Pointer to the new token. |
|
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.
secret | Pointer to the encryption password. |
|
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.
encryptionMode | The set encryption mode:
|
|
pure virtual |
Enables/Disables the built-in encryption.
In scenarios requiring high security, Agora recommends calling this method to enable the built-in encryption before joining a channel.
All users in the same channel must use the same encryption mode and encryption key. Once all users leave the channel, the encryption key of this channel is automatically cleared.
enabled | Whether to enable the built-in encryption:
|
config | Configurations of built-in encryption schemas. See EncryptionConfig. |
IChannel
instance before calling this method.
|
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.
observer | The registered packet observer. See IPacketObserver. |
|
pure virtual |
Registers the metadata observer.
Registers the metadata observer. You need to implement the IMetadataObserver class and specify the metadata type in this method. A successful call of this method triggers the getMaxMetadataSize callback. This method enables you to add synchronized metadata in the video stream for more diversified interactive live streaming, such as sending shopping links, digital coupons, and online quizzes.
LIVE_BROADCASTING
channel profile.observer | The IMetadataObserver class. See the definition of IMetadataObserver for details. |
type | See METADATA_TYPE. The SDK supports VIDEO_METADATA (0) only for now. |
|
pure virtual |
Sets the role of the user, such as a host or an audience (default), before joining a channel in the interactive live streaming.
This method can be used to switch the user role in the interactive live streaming after the user joins a channel.
In the LIVE_BROADCASTING
profile, when a user switches user roles after joining a channel, a successful setClientRole method call triggers the following callbacks:
LIVE_BROADCASTING
profile.role | Sets the role of the user. See CLIENT_ROLE_TYPE. |
|
pure virtual |
Sets the role of a user in interactive live streaming.
You can call this method either before or after joining the channel to set the user role as audience or host. If you call this method to switch the user role after joining the channel, the SDK triggers the following callbacks:
LIVE_BROADCASTING
profile only.role | The role of a user in interactive live streaming. See CLIENT_ROLE_TYPE. |
options | The detailed options of a user, including user level. See ClientRoleOptions. |
|
pure virtual |
Prioritizes a remote user's stream.
The SDK ensures the high-priority user gets the best possible stream quality.
serPriority
as high for one user only.uid | The ID of the remote user. |
userPriority | Sets the priority of the remote user. See PRIORITY_TYPE. |
|
pure virtual |
Sets the sound position and gain of a remote user.
When the local user calls this method to set the sound position of a remote user, the sound difference between the left and right channels allows the local user to track the real-time position of the remote user, creating a real sense of space. This method applies to massively multiplayer online games, such as Battle Royale games.
uid | The ID of the remote user. |
pan | The sound position of the remote user. The value ranges from -1.0 to 1.0:
|
gain | Gain of the remote user. The value ranges from 0.0 to 100.0. The default value is 100.0 (the original gain of the remote user). The smaller the value, the less the gain. |
|
pure virtual |
Updates the display mode of the video view of a remote user.
After initializing the video view of a remote user, you can call this method to update its rendering and mirror modes. This method affects only the video view that the local user sees.
userId | The ID of the remote user. |
renderMode | The rendering mode of the remote video view. See RENDER_MODE_TYPE. |
mirrorMode |
|
|
pure virtual |
Stops or resumes subscribing to the audio streams of all remote users by default.
Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the audio streams of all subsequent users.
mute | Sets whether to stop subscribing to the audio streams of all remote users by default.
|
|
pure virtual |
Stops or resumes subscribing to the video streams of all remote users by default.
Call this method after joining a channel. After successfully calling this method, the local user stops or resumes subscribing to the video streams of all subsequent users.
mute | Sets whether to stop subscribing to the video streams of all remote users by default.
|
|
pure virtual |
Stops or resumes subscribing to the audio streams of all remote users.
As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the audio streams of all remote users, including all subsequent users.
mute | Sets whether to stop subscribing to the audio streams of all remote users.
|
|
pure virtual |
Adjust the playback signal volume of the specified remote user.
After joining a channel, call adjustPlaybackSignalVolume to adjust the playback volume of different remote users, or adjust multiple times for one remote user.
userId | The user ID, which should be the same as the uid of joinChannel |
volume | The playback volume of the voice. The value ranges from 0 to 100:
|
|
pure virtual |
Stops or resumes subscribing to the audio stream of a specified user.
userId | The user ID of the specified remote user. |
mute | Sets whether to stop subscribing to the audio stream of a specified user.
|
|
pure virtual |
Stops or resumes subscribing to the video streams of all remote users.
As of v3.3.0, after successfully calling this method, the local user stops or resumes subscribing to the video streams of all remote users, including all subsequent users.
mute | Sets whether to stop subscribing to the video streams of all remote users.
|
|
pure virtual |
Stops or resumes subscribing to the video stream of a specified user.
userId | The user ID of the specified remote user. |
mute | Sets whether to stop subscribing to the video stream of a specified user.
|
|
pure virtual |
Sets the stream type of the remote video.
Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).
By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources.
The aspect ratio of the low-video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.
The method result returns in the onApiCallExecuted callback.
userId | The ID of the remote user sending the video stream. |
streamType | Sets the video-stream type. See REMOTE_VIDEO_STREAM_TYPE. |
|
pure virtual |
Sets the default stream type of remote videos.
Under limited network conditions, if the publisher has not disabled the dual-stream mode using enableDualStreamMode (false), the receiver can choose to receive either the high-quality video stream (the high resolution, and high bitrate video stream) or the low-video stream (the low resolution, and low bitrate video stream).
By default, users receive the high-quality video stream. Call this method if you want to switch to the low-video stream. This method allows the app to adjust the corresponding video stream type based on the size of the video window to reduce the bandwidth and resources. The aspect ratio of the low-video stream is the same as the high-quality video stream. Once the resolution of the high-quality video stream is set, the system automatically sets the resolution, frame rate, and bitrate of the low-video stream.
The method result returns in the onApiCallExecuted callback.
streamType | Sets the default video-stream type. See REMOTE_VIDEO_STREAM_TYPE. |
|
pure virtual |
Creates a data stream.
Each user can create up to five data streams during the lifecycle of the IChannel.
reliable
as true
while setting ordered
as false
.[out] | streamId | The ID of the created data stream. |
reliable | Sets whether or not the recipients are guaranteed to receive the data stream from the sender within five seconds:
| |
ordered | Sets whether or not the recipients receive the data stream in the sent order:
|
|
pure virtual |
Creates a data stream.
Each user can create up to five data streams in a single channel.
This method does not support data reliability. If the receiver receives a data packet five seconds or more after it was sent, the SDK directly discards the data.
[out] | streamId | The ID of the created data stream. |
config | The configurations for the data stream: DataStreamConfig. |
|
pure virtual |
Sends data stream messages to all users in a channel.
The SDK has the following restrictions on this method:
A successful sendStreamMessage method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.
A failed sendStreamMessage method call triggers the onStreamMessage callback on the remote client.
COMMUNICATION
profile or to the hosts in the LIVE_BROADCASTING
profile. If an audience in the LIVE_BROADCASTING
profile calls this method, the audience may be switched to a host.streamId | The ID of the sent data stream, returned in the createDataStream method. |
data | The sent data. |
length | The length of the sent data. |
|
pure virtual |
Publishes the local stream to a specified CDN streaming URL. (CDN live only.)
The SDK returns the result of this method call in the onStreamPublished callback.
After calling this method, you can push media streams in RTMP or RTMPS protocol to the CDN. The SDK triggers the onRtmpStreamingStateChanged callback on the local client to report the state of adding a local stream to the CDN.
url | The CDN streaming URL in the RTMP or RTMPS format. The maximum length of this parameter is 1024 bytes. The CDN streaming URL must not contain special characters, such as Chinese language characters. |
transcodingEnabled | Sets whether transcoding is enabled/disabled:
|
IChannel
when publishing the stream.
|
pure virtual |
Removes an RTMP or RTMPS stream from the CDN.
This method removes the CDN streaming URL (added by the addPublishStreamUrl method) from a CDN live stream. The SDK returns the result of this method call in the onStreamUnpublished callback.
The removePublishStreamUrl method call triggers the onRtmpStreamingStateChanged callback on the local client to report the state of removing an RTMP or RTMPS stream from the CDN.
url | The CDN streaming URL to be removed. The maximum length of this parameter is 1024 bytes. |
|
pure virtual |
Sets the video layout and audio settings for CDN live. (CDN live only.)
The SDK triggers the onTranscodingUpdated callback when you call the setLiveTranscoding
method to update the transcoding setting.
setLiveTranscoding
method to set the transcoding setting for the first time, the SDK does not trigger the onTranscodingUpdated
callback.transcoding | Sets the CDN live audio/video transcoding settings. See LiveTranscoding. |
|
pure virtual |
Adds a voice or video stream URL address to the interactive live streaming.
The onStreamPublished callback returns the inject status. If this method call is successful, the server pulls the voice or video stream and injects it into a live channel. This is applicable to scenarios where all audience members in the channel can watch a live show and interact with each other.
The addInjectStreamUrl method call triggers the following callbacks:
The remote client:
LIVE_BROADCASTING
profile only.url | The URL address to be added to the ongoing live streaming. Valid protocols are RTMP, HLS, and HTTP-FLV.
|
config | The InjectStreamConfig object that contains the configuration of the added voice or video stream. |
LIVE_BROADCASTING
. Call the setChannelProfile method and set the channel profile to LIVE_BROADCASTING
before calling this method.
|
pure virtual |
Removes the voice or video stream URL address from a live streaming.
This method removes the URL address (added by the addInjectStreamUrl method) from the live streaming.
url | Pointer to the URL address of the added stream to be removed. |
|
pure virtual |
Starts to relay media streams across channels.
After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged and onChannelMediaRelayEvent callbacks, and these callbacks return the state and events of the media stream relay.
LIVE_BROADCASTING
channel.configuration | The configuration of the media stream relay: ChannelMediaRelayConfiguration. |
|
pure virtual |
Updates the channels for media stream relay.
After a successful startChannelMediaRelay method call, if you want to relay the media stream to more channels, or leave the current relay channel, you can call the updateChannelMediaRelay method.
After a successful method call, the SDK triggers the onChannelMediaRelayEvent callback with the RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7) state code.
configuration | The media stream relay configuration: ChannelMediaRelayConfiguration. |
|
pure virtual |
Stops the media stream relay.
Once the relay stops, the host quits all the destination channels.
After a successful method call, the SDK triggers the onChannelMediaRelayStateChanged callback. If the callback returns RELAY_STATE_IDLE (0) and RELAY_OK (0), the host successfully stops the relay.
|
pure virtual |
Gets the current connection state of the SDK.