Data Stream

createDataStream [1/2]

Creates a data stream to improve reliability and ordering of data transmission.

public abstract int createDataStream(boolean reliable, boolean ordered);
Note: Each user can create up to five data streams during the lifecycle of RtcEngine. Data streams are destroyed when leaving the channel. To continue using them, you need to recreate them. If you require a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, consider using Real-time Messaging.

Timing

You can call this method before or after joining a channel.

Related Callbacks

When reliable is set to true, if the receiver does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code.

Parameters

reliable
Note: Make sure reliable and ordered are both set to true or both set to false.
Whether to guarantee that the receiver receives the data within five seconds:
  • true: The receiver will receive the data from the sender within five seconds. If not, the SDK triggers the onStreamMessageError callback and returns an error code.
  • false: No guarantee that the receiver receives the data within five seconds. No error callback is triggered for delay or loss.
ordered
Whether to receive data in the order it was sent:
  • true: The receiver receives data in the order it was sent.
  • false: The receiver may receive data out of order.

Return Values

  • On success, returns the ID of the created data stream.
  • < 0: Failure.

createDataStream [2/2]

Creates a data stream.

public abstract int createDataStream(DataStreamConfig config);

This method does not guarantee reliable data transmission. If the data packet is not received within five seconds after being sent, the SDK discards the data.

Note: Each user can create up to five data streams during the lifecycle of RtcEngine. Data streams are destroyed when leaving the channel. To continue using them, you need to recreate them. If you require a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, consider using Agora Real-time Messaging.

Timing

You can call this method before or after joining a channel.

Parameters

config
The configuration of the data stream. See DataStreamConfig.

Return Values

  • On success, returns the ID of the created data stream.
  • < 0: Failure.

createDataStreamEx [1/2]

Creates a data stream to improve reliability and ordering of data transmission.

public abstract int createDataStreamEx(boolean reliable, boolean ordered, RtcConnection connection);
Deprecated
This method is deprecated. Use createDataStreamEx [2/2] instead.
Note: Each user can create up to five data streams during the lifecycle of the RtcEngine. The data streams are destroyed when leaving the channel. To continue using them, you need to recreate them.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after joinChannelEx.

Related Callbacks

If reliable is set to true and the receiver does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code.

Parameters

reliable
Note: Make sure reliable and ordered are both set to true or both set to false.
Whether to ensure the receiver receives the data stream within five seconds:
  • true: The receiver receives the data from the sender within five seconds. If not, the SDK triggers the onStreamMessageError callback and returns an error code.
  • false: Does not guarantee delivery within five seconds. Delays or losses will not return error information.
ordered
Whether to receive the data stream in the order it was sent:
  • true: The receiver receives the data in the order it was sent.
  • false: The receiver does not receive the data in order.
connection
Connection information. See RtcConnection.

Return Values

  • If the method call succeeds, returns the created data stream ID.
  • If the method call fails, returns a value less than 0.

createDataStreamEx [2/2]

Creates a data stream.

public abstract int createDataStreamEx(DataStreamConfig config, RtcConnection connection);

Compared with createDataStreamEx [1/2], this method does not guarantee data transmission reliability. If the data packet is not received within five seconds after being sent, the SDK discards it.

Note: Each user can create up to five data streams during the lifecycle of the RtcEngine. The data streams are destroyed when leaving the channel. To continue using them, you need to recreate them. If you need a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, we recommend using real-time messaging.

Scenario

This method applies to multi-channel scenarios.

Timing

Call this method after joinChannelEx.

Parameters

config
The configuration of the data stream. See DataStreamConfig.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

sendStreamMessage

Sends a data stream message.

public abstract int sendStreamMessage(int streamId, byte[] message);
After calling createDataStream, you can use this method to send data stream messages to all users in the channel. The SDK imposes the following limits:
  • Each client instance in the channel can have up to 5 data channels. The total bitrate shared by all channels is limited to 30 KB/s.
  • Each data channel can send up to 60 data packets per second, with a maximum size of 1 KB per packet.
Note:
  • If you require a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, consider using Real-time Messaging.
  • You must call this method after calling createDataStream and joining a channel.
  • This method is only applicable to the broadcaster role.

Related Callbacks

If the call succeeds, the remote client receives the onStreamMessage callback and can get the message. If it fails, the remote client receives the onStreamMessageError callback.

Parameters

streamId
The ID of the data stream, obtained by calling createDataStream.
message
The content of the message to be sent.

Return Values

  • 0: Success.
  • < 0: Failure.

sendStreamMessageEx

Sends data stream messages.

public abstract int sendStreamMessageEx(int streamId, byte[] message, RtcConnection connection);
After calling createDataStreamEx, you can use this method to send data stream messages to all users in the channel. The SDK imposes the following limits on this method:
  • Each client instance can have up to 5 data channels in a channel, and the total bitrate shared by all data channels is limited to 30 KB/s.
  • Each data channel can send up to 60 data packets per second, and each packet must not exceed 1 KB.
Note:
  • If you need a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, we recommend using Agora's real-time messaging.
  • Call this method after joinChannelEx.
  • Make sure to create the data channel using createDataStreamEx before calling this method.

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

If the call succeeds, the remote client receives the onStreamMessage callback, from which the user can get the data stream message. If the call fails, the remote client receives the onStreamMessageError callback.

Parameters

streamId
The data stream ID. You can get this ID by calling createDataStreamEx.
message
The message content to be sent.
connection
Connection information. See RtcConnection.

Return Values

  • 0: Success.
  • < 0: Failure.

onStreamMessage

Callback when a remote user sends a data stream.

public void onStreamMessage(int uid, int streamId, byte[] data)
Note: If you need a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, we recommend using Agora's Real-time Messaging.

Trigger Timing

This callback is triggered when the local user receives a data stream message sent by a remote user via sendStreamMessage.

Parameters

uid
The remote user ID who sent the message.
streamId
The stream ID of the received message.
data
The received data content.

onStreamMessageError

onStreamMessageError callback: triggered when the local user fails to receive a data stream sent by a remote user.

public void onStreamMessageError(int uid, int streamId, int error, int missed, int cached)

This callback is triggered when the local user fails to receive a stream message sent by a remote user via sendStreamMessage.

Note: If you need a more comprehensive real-time messaging and state synchronization solution with low latency, high concurrency, and scalability, we recommend using Real-time Messaging.

Trigger Timing

This callback is triggered when the local user fails to receive a stream message sent by a remote user via sendStreamMessage.

Parameters

uid
The remote user ID who sent the message.
streamId
The stream ID corresponding to the received message.
error
Error code.
missed
Number of lost messages.
cached
Number of incoming messages cached during stream interruption.