Agora Server Gateway SDK Java API Reference
Public Member Functions | List of all members
io.agora.rtc.AgoraRtcConn Class Reference

Public Member Functions

 AgoraRtcConn (long cptr)
 
void destroy ()
 
native int connect (String token, String chan_id, String user_id)
 
native int disconnect ()
 
native int startLastmileProbeTest (LastmileProbeConfig config)
 
native int stopLastmileProbeTest ()
 
native int renewToken (String token)
 
native RtcConnInfo getConnInfo ()
 
native void destroyConnInfo (RtcConnInfo info)
 
native AgoraLocalUser getLocalUser ()
 
native UserInfo getUserInfo (String user_id)
 
native void destroyUserInfo (UserInfo info)
 
native int registerObserver (IRtcConnObserver observer)
 
native int unregisterObserver ()
 
native int registerNetworkObserver (INetworkObserver observer)
 
native int unregisterNetworkObserver ()
 
native int getConnId ()
 
native RtcStats getTransportStats ()
 
native void destroyTransportStats (RtcStats stats)
 
native AgoraParameter getAgoraParameter ()
 
native int createDataStream (Out stream_id, int reliable, int ordered)
 
native int sendStreamMessage (int stream_id, String data, int length)
 
native int enableEncryption (int enabled, EncryptionConfig config)
 
native int sendCustomReportMessage (String id, String category, String event, String label, int value)
 

Detailed Description

The AgoraRtcConn class.

You can use this class for managing the connection between your app and an Agora RTC channel.

Once connected, your app gets an AgoraLocalUser object for publishing and subscribing to media streams in the Agora Channel.

Connecting to a channel is done asynchronously, and your app can listen to the connection states or events through IRtcConnObserver. AgoraRtcConn also monitors remote users in the channel. The SDK notifies your app when a remote user joins or leaves the channel.

Constructor & Destructor Documentation

◆ AgoraRtcConn()

io.agora.rtc.AgoraRtcConn.AgoraRtcConn ( long  cptr)

Constructor.

Member Function Documentation

◆ connect()

native int io.agora.rtc.AgoraRtcConn.connect ( String  token,
String  chan_id,
String  user_id 
)

Connects to an Agora channel.

When the method call succeeds, the connection state changes from CONNECTION_STATE_DISCONNECTED(1) to CONNECTION_STATE_CONNECTING(2).

Depending on the whether the connection succeeds or not, the connection state changes to either CONNECTION_STATE_CONNECTED(3) or CONNECTION_STATE_FAILED(5). The SDK also triggers onConnected or onDisconnected to notify you of the state change.

Parameters
tokenThe app ID.
chan_idThe channel name. It must be in the string format and not exceed 64 bytes in length. Supported character scopes are:
  • All lowercase English letters: a to z.
  • All uppercase English letters: A to Z.
  • All numeric characters: 0 to 9.
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
user_idThe ID of the local user. If you do not specify a user ID or set this parameter as null, the SDK returns a user ID in the onConnected callback. Your app must record and maintain the ID since the SDK does not do so.
Returns
  • 0: Success.
  • < 0: Failure.

◆ createDataStream()

native int io.agora.rtc.AgoraRtcConn.createDataStream ( Out  stream_id,
int  reliable,
int  ordered 
)

Creates a data stream.

Each user can create up to five data streams in a single channel.

Note
  • Agora does not support setting reliable as 1 and ordered as 0.
  • Do not set the ordered parameter as 0 if you need the receiver to receive the data packet immediately.
Parameters
stream_idOutput parameter. A pointer to the ID of the created data stream.
reliableWhether or not the data stream is reliable:
  • 0: The recipients receive the data from the sender within five seconds.
  • 1: 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.
orderedWhether or not the recipients receive the data stream in the sent order:
  • 0: The recipients receive the data in the sent order.
  • 1: The recipients do not receive the data stream in the sent order.
Returns
  • 0: Success.
  • < 0: Failure.

◆ destroy()

void io.agora.rtc.AgoraRtcConn.destroy ( )

Destructor.

◆ destroyConnInfo()

native void io.agora.rtc.AgoraRtcConn.destroyConnInfo ( RtcConnInfo  info)

◆ destroyTransportStats()

native void io.agora.rtc.AgoraRtcConn.destroyTransportStats ( RtcStats  stats)

◆ destroyUserInfo()

native void io.agora.rtc.AgoraRtcConn.destroyUserInfo ( UserInfo  info)

◆ disconnect()

native int io.agora.rtc.AgoraRtcConn.disconnect ( )

Disconnects from the Agora channel.

Once your app successful disconnects from the channel, the connection state changes to CONNECTION_STATE_DISCONNECTED(1). You are also notified with the callback onDisconnected.

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

◆ enableEncryption()

native int io.agora.rtc.AgoraRtcConn.enableEncryption ( int  enabled,
EncryptionConfig  config 
)

Enables/Disables the built-in encryption.

In scenarios requiring high security, Agora recommends calling enableEncryption to enable the built-in encryption for a connection before connecting to a channel.

Parameters
enabledWhether to enable the built-in encryption.
  • true: Enable the built-in encryption.
  • false: Disable the built-in encryption.
configConfigurations of built-in encryption schemas. See EncryptionConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ getAgoraParameter()

native AgoraParameter io.agora.rtc.AgoraRtcConn.getAgoraParameter ( )

Gets the AgoraParameter object for a connection.

The AgoraParameter object obtained through this method is only effective for the current connection. For global settings, call the AgoraService.getAgoraParameter method.

Returns
  • AgoraParameter object: Success.
  • null: Failure.

◆ getConnId()

native int io.agora.rtc.AgoraRtcConn.getConnId ( )

Gets the ID of the connection.

Returns
The connection ID.

◆ getConnInfo()

native RtcConnInfo io.agora.rtc.AgoraRtcConn.getConnInfo ( )

Gets the connection information.

Returns
A RtcConnInfo object.

◆ getLocalUser()

native AgoraLocalUser io.agora.rtc.AgoraRtcConn.getLocalUser ( )

Gets the AgoraLocalUser object.

Returns
The AgoraLocalUser object.

◆ getTransportStats()

native RtcStats io.agora.rtc.AgoraRtcConn.getTransportStats ( )

Gets the transportation statistics of the RTC connection.

Returns
A RtcStats object.

◆ getUserInfo()

native UserInfo io.agora.rtc.AgoraRtcConn.getUserInfo ( String  user_id)

Gets the information of a specified remote user in the channel.

Parameters
user_idID of the user whose information you want to get.
Returns
The UserInfo object, which contains the information of the specified user.

◆ registerNetworkObserver()

native int io.agora.rtc.AgoraRtcConn.registerNetworkObserver ( INetworkObserver  observer)

Registers an network observer object.

Parameters
observerThe INetworkObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ registerObserver()

native int io.agora.rtc.AgoraRtcConn.registerObserver ( IRtcConnObserver  observer)

Registers an RTC connection observer. You can call this method only after creating an IRtcConnection object.

Parameters
observerThe IRtcConnObserver object.
Returns
  • 0: Success.
  • < 0: Failure.

◆ renewToken()

native int io.agora.rtc.AgoraRtcConn.renewToken ( String  token)

Renews the token.

The token expires after a certain period of time. When the onTokenPrivilegeWillExpire callback is triggered, you must generate a new token from the server and then call this method to renew it. Otherwise, the SDK disconnects from the Agora channel.

Parameters
tokenThe new token.

◆ sendCustomReportMessage()

native int io.agora.rtc.AgoraRtcConn.sendCustomReportMessage ( String  id,
String  category,
String  event,
String  label,
int  value 
)

Reports a custom event to Agora.

Parameters
idThe custom event ID.
categoryThe category of the custom event.
eventThe custom event to report.
labelThe label of the custom event.
valueThe value of the custom event.
Returns
  • 0: Success.
  • < 0: Failure.

◆ sendStreamMessage()

native int io.agora.rtc.AgoraRtcConn.sendStreamMessage ( int  stream_id,
String  data,
int  length 
)

Sends data stream messages.

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.

A successful method call triggers the onStreamMessage callback on the remote client, from which the remote user gets the stream message.

Note
  • Ensure that you call createDataStream to create a data channel before calling this method.
  • In live streaming scenarios, this method only applies to hosts.
Parameters
stream_idThe data stream ID. You can get the data stream ID by calling createDataStream.
dataThe message to be sent.
lengthThe length of the data.
Returns
  • 0: Success.
  • < 0: Failure.

◆ startLastmileProbeTest()

native int io.agora.rtc.AgoraRtcConn.startLastmileProbeTest ( LastmileProbeConfig  config)

Starts the last-mile network probe test.

Call this method before connecting to the channel to get the uplink and downlink last-mile network statistics, including the bandwidth, packet loss, jitter, and round-trip time (RTT).

After you enable the last-mile network probe test, the SDK triggers 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 reports the real-time statistics of the network conditions and is more objective.
Note
  • Do not call any other method 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 connecting to a channel.
Parameters
configThe configurations of the last-mile network probe test. See LastmileProbeConfig.
Returns
  • 0: Success.
  • < 0: Failure.

◆ stopLastmileProbeTest()

native int io.agora.rtc.AgoraRtcConn.stopLastmileProbeTest ( )

Stops the last-mile network probe test.

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

◆ unregisterNetworkObserver()

native int io.agora.rtc.AgoraRtcConn.unregisterNetworkObserver ( )

Releases the registered INetworkObserver object.

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

◆ unregisterObserver()

native int io.agora.rtc.AgoraRtcConn.unregisterObserver ( )

Releases the registered IRtcConnObserver object.

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

The documentation for this class was generated from the following file: