数据流 Datastream

createDataStream [1/2]

创建一个数据流，用于提升数据传输的可靠性和顺序性。

Java

public abstract int createDataStream(boolean reliable, boolean ordered);

信息

每个用户在 RtcEngine 的生命周期内最多可创建五个数据流。离开频道时，数据流会被销毁，如需继续使用需重新创建。如果你需要一个更全面的低延迟、高并发、可扩展的实时消息和状态同步解决方案，建议使用实时消息。

调用时机

你可以在加入频道前或后调用此方法。

相关回调

将 reliable 设置为 true 后，如果接收端在五秒内未收到数据，SDK 会触发 onStreamMessageError 回调并返回错误码。

参数

reliable

信息

请确保 reliable 和 ordered 同时设置为 true 或同时设置为 false。

是否保证接收端在五秒内收到数据流：

• true：接收端会在五秒内收到发送端的数据。如果未收到，SDK 会触发 onStreamMessageError 回调并返回错误码。
• false：不保证接收端在五秒内收到数据，延迟或丢失不会触发错误回调。

ordered

是否按发送顺序接收数据流：

• true：接收端按发送顺序接收数据。
• false：接收端不按发送顺序接收数据。

返回值

• 方法调用成功，返回创建的数据流 ID。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

createDataStream [2/2]

创建一个数据流。

Java

public abstract int createDataStream(DataStreamConfig config);

该方法不保证数据传输的可靠性。如果数据包在发送后五秒内未被接收，SDK 会直接丢弃该数据。

信息

每个用户在 RtcEngine 的生命周期内最多可以创建五个数据流。离开频道时数据流会被销毁，如需继续使用需重新创建。如果你需要一个更全面的低延迟、高并发、可扩展的实时消息和状态同步解决方案，建议使用声网实时消息。

调用时机

你可以在加入频道前或加入频道后调用该方法。

参数

config

数据流的配置，详见 DataStreamConfig。

返回值

• 方法调用成功，返回创建的数据流 ID。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

createDataStreamEx [1/2]

创建数据流以提升数据传输的可靠性和顺序性。

Java

public abstract int createDataStreamEx(boolean reliable, boolean ordered, RtcConnection connection);

废弃

该方法已废弃，请改用 createDataStreamEx [2/2]

信息

每个用户在 RtcEngine 的生命周期内最多可创建五个数据流。离开频道时数据流会被销毁，如需继续使用需重新创建。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用此方法。

相关回调

将 reliable 设置为 true 后，如果接收端在五秒内未收到数据，SDK 会触发 onStreamMessageError 回调并返回错误码。

参数

reliable

信息

请确保 reliable 和 ordered 同时设置为 true 或同时设置为 false。

是否保证接收端在五秒内接收到数据流：

• true：接收端会在五秒内接收到发送端的数据。如果接收端在五秒内未收到数据，SDK 会触发 onStreamMessageError 回调并返回错误码。
• false：不保证接收端在五秒内接收到数据流，延迟或丢失数据不会返回错误信息。

ordered

是否按发送顺序接收数据流：

• true：接收端按发送顺序接收数据。
• false：接收端不按发送顺序接收数据。

connection

连接信息。详见 RtcConnection。

返回值

• 方法调用成功，返回创建的数据流 ID。
• 方法调用失败，返回小于 0 的值。

所属接口类

• RtcEngineEx

createDataStreamEx [2/2]

创建一个数据流。

Java

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

与 createDataStreamEx [1/2] 相比，该方法不保证数据传输的可靠性。如果数据包在发送后五秒内未被接收，SDK 会直接丢弃该数据。

信息

每个用户在 RtcEngine 的生命周期内最多可创建五个数据流。离开频道时数据流会被销毁，如需继续使用需重新创建。如果你需要一个更全面的低延迟、高并发、可扩展的实时消息和状态同步解决方案，建议使用实时消息。

适用场景

该方法适用于多频道场景。

调用时机

请在调用 joinChannelEx 后调用该方法。

参数

config

数据流的配置，详见 DataStreamConfig。

connection

连接信息，详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

sendStreamMessage

发送数据流消息。

Java

public abstract int sendStreamMessage(int streamId, byte[] message);

调用 createDataStream 后，可以使用该方法向频道内的所有用户发送数据流消息。SDK 对该方法有限制：

• 每个频道内的客户端实例最多可同时拥有 5 个数据通道，所有数据通道共享的总包比特率上限为 30 KB/s。
• 每个数据通道每秒最多可发送 60 个数据包，每个数据包最大为 1 KB。

信息

• 如果你需要更全面的低延迟、高并发、可扩展的实时消息和状态同步解决方案，建议使用实时消息。
• 必须在调用 createDataStream 并加入频道后调用该方法。
• 该方法仅适用于主播角色。

相关回调

调用成功后会触发远端客户端的 onStreamMessage 回调，远端用户可通过该回调获取数据流消息。调用失败则会触发远端客户端的 onStreamMessageError 回调。

参数

streamId

数据流 ID，通过调用 createDataStream 获取。

message

要发送的消息内容。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngine

sendStreamMessageEx

发送数据流消息。

Java

public abstract int sendStreamMessageEx(int streamId, byte[] message, RtcConnection connection);

调用 createDataStreamEx 后，可以使用该方法向频道内的所有用户发送数据流消息。SDK 对该方法有限制：

• 每个频道内的客户端实例最多可同时拥有 5 个数据通道，所有数据通道共享的总包比特率上限为 30 KB/s。
• 每个数据通道每秒最多可发送 60 个数据包，每个数据包最大为 1 KB。

信息

• 如果你需要一个更全面的低延迟、高并发、可扩展的实时消息和状态同步解决方案，建议使用声网的实时消息。
• 请在调用 joinChannelEx 后再调用该方法。
• 请确保在调用该方法前已通过 createDataStreamEx 创建数据通道。

适用场景

该方法适用于多频道场景。

相关回调

调用成功后会触发远端客户端的 onStreamMessage 回调，远端用户可通过该回调获取数据流消息。调用失败则会触发远端客户端的 onStreamMessageError 回调。

参数

streamId

数据流 ID。你可以通过调用 createDataStreamEx 获取该 ID。

message

要发送的消息内容。

connection

连接信息。详见 RtcConnection。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• RtcEngineEx

onStreamMessage

远端用户发送数据流时的回调。

Java

public void onStreamMessage(int uid, int streamId, byte[] data)

信息

如果你需要一个更全面的低延迟、高并发和可扩展的实时消息和状态同步解决方案，建议使用声网的实时消息。

触发时机

该回调在本地用户收到远端用户通过 sendStreamMessage 方法发送的数据流消息时被触发。

参数

uid

发送该消息的远端用户 ID。

streamId

接收到的消息所属的数据流 ID。

data

接收到的数据内容。

所属接口类

• IRtcEngineEventHandler

onStreamMessageError

onStreamMessageError 回调：本地用户未收到远端用户发送的数据流时触发。

Java

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

该回调在本地用户未能接收到远端用户通过调用 sendStreamMessage 发送的流消息时触发。

信息

如果你需要一个更全面的低延迟、高并发和可扩展的实时消息和状态同步解决方案，建议使用实时消息。

触发时机

该回调在本地用户未能接收到远端用户通过 sendStreamMessage 发送的流消息时被触发。

参数

uid

发送消息的远端用户 ID。

streamId

接收消息对应的数据流 ID。

error

错误码。

missed

丢失的消息数量。

cached

数据流中断时缓存的传入消息数量。

所属接口类

• IRtcEngineEventHandler