Metadata

Data Stream

createDataStream [1/2]

Creates a data stream.

virtual int createDataStream(int* streamId, bool reliable, bool ordered) = 0;

Note: Each user can create up to five data streams during the lifecycle of IRtcEngine. The data streams are destroyed when you leave the channel. To continue using them, you need to recreate them. If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, it is recommended to use real-time messaging.

Timing

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

Related Callbacks

After this method is successfully called, if the receiver does not receive the data within five seconds, the SDK triggers the onStreamMessageError callback and returns an error code.

Parameters

streamId

Output parameter. The ID of the created data stream.

reliable

Whether to ensure the data stream is received by the receiver within five seconds:

true: The receiver will receive the data from the sender within five seconds. If not received, the SDK triggers the onStreamMessageError callback and returns an error code.
false: The SDK does not guarantee that the data will be received within five seconds. Delay or loss will not return error information.

Note: Make sure reliable and ordered are either both true or both false.

ordered

Whether to receive the data stream in the order it was sent:

true: The receiver receives data in the order it was sent.
false: The receiver does not receive data in the order it was sent.

Return Values

0: The method call succeeds.
< 0: The method call fails.

createDataStream [2/2]

Creates a data stream.

virtual int createDataStream(int* streamId, const DataStreamConfig& config) = 0;

This method does not guarantee the reliability of data transmission. If a data packet is not received within five seconds after being sent, the SDK discards the packet. Compared with the createDataStream method, this method is suitable for scenarios with high real-time requirements but tolerable data loss.

Note: Each user can create up to five data streams during the lifecycle of IRtcEngine. The data streams are destroyed when you leave the channel. To use them again, you need to recreate them. If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, it is recommended to use real-time messaging.

Timing

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

Parameters

streamId: Output parameter. The ID of the created data stream.
config: Configuration of the data stream. See DataStreamConfig for details.

Return Values

0: The method call succeeds.
< 0: The method call fails.

createDataStreamEx [1/2]

Creates a data stream.

virtual int createDataStreamEx(int* streamId, bool reliable, bool ordered, const RtcConnection& connection) = 0;

Note: Each user can create up to five data streams during the lifecycle of IRtcEngine. 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 calling joinChannelEx.

Related Callbacks

After successfully calling this method, 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

streamId

Output parameter. The ID of the created data stream.

reliable

Whether to ensure the receiver receives the data stream within five seconds:

true: The receiver will receive the sender's data within five seconds. If not, the SDK triggers the onStreamMessageError callback and returns an error code.
false: The SDK does not guarantee the data stream is received within five seconds. Delays or losses will not return error information.

Note: Make sure reliable and ordered are both true or both false.

ordered

Whether the data stream is received 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

0: The method call succeeds.
< 0: The method call fails.

createDataStreamEx [2/2]

Creates a data stream.

virtual int createDataStreamEx(int* streamId, const DataStreamConfig& config, const RtcConnection& connection) = 0;

createDataStreamEx [2/2] does not guarantee the reliability of data transmission compared to createDataStreamEx [1/2]. If a data packet is not received within five seconds after being sent, the SDK discards the data directly. It is recommended to call this method after joinChannelEx.

Note: Each user can create up to five data streams during the lifecycle of IRtcEngine. The data streams are destroyed when leaving the channel. To use them again, you need to recreate them. If you require a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, consider using real-time messaging.

Scenario

This method applies to multi-channel scenarios.

Timing

Call after joinChannelEx.

Parameters

streamId: Output parameter. The ID of the created data stream.
config: Configuration of the data stream. See DataStreamConfig.
connection: Connection information. See RtcConnection.

Return Values

0: The method call succeeds.
< 0: The method call fails.

sendStreamMessage

Sends a data stream message.

virtual int sendStreamMessage(int streamId, const char* data, size_t length) = 0;

After calling createDataStream, you can call this method to send data stream messages to all users in the channel.

Note:

If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, we recommend using Real-time Messaging.
This method must be called after createDataStream and joining the channel.
This method is only applicable to the host role.

Related Callbacks

After this method is successfully called, the SDK triggers the onStreamMessage callback. Remote users can receive the data stream message through this callback. If the call fails, the SDK triggers the remote onStreamMessageError callback.

Parameters

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

Return Values

0: The method call succeeds.
< 0: The method call fails.

sendStreamMessageEx

Sends a data stream message.

virtual int sendStreamMessageEx(int streamId, const char* data, size_t length, const RtcConnection& connection) = 0;

After calling createDataStreamEx to create a data channel, you can call this method to send data stream messages to all users in the channel. The SDK imposes the following limitations on this method:

Each client can have up to 5 data channels in a channel at the same time, 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, with each packet being a maximum of 1 KB.

Note:

If you need a more comprehensive solution for low-latency, high-concurrency, and scalable real-time messaging and state synchronization, we recommend using Real-time Messaging.
Call this method after calling joinChannelEx.
Make sure to create the data channel using createDataStreamEx before calling this method.

Scenario

This method applies to multi-channel scenarios.

Related Callbacks

After this method is successfully called, the SDK triggers the onStreamMessage callback on the remote client. The remote user can receive the data stream message through this callback. If the call fails, the SDK triggers the onStreamMessageError callback on the remote client.

Parameters

streamId: The data stream ID, obtained by calling createDataStreamEx.
data: The content of the message to be sent.
length: The length of the data.
connection: Connection information. See RtcConnection.

Return Values

0: Success.
< 0: Failure.

onStreamMessage

onStreamMessage callback: Triggered when a remote user sends a data stream.

virtual void onStreamMessage(uid_t uid, int streamId, const char* data, size_t length, uint64_t sentTs)

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

Note: If you need a more comprehensive solution for low latency, high concurrency, and scalable real-time messaging and state synchronization, consider using Real-time Messaging.

Parameters

uid: The ID of the remote user who sent the data stream.
streamId: The ID of the received data stream.
data: The content of the received data.
length: The length of the received data in bytes.
sentTs: The timestamp when the data stream was sent.

onStreamMessageError

Callback triggered when the local user fails to receive a data stream message sent by a remote user.

virtual void onStreamMessageError(uid_t uid, int streamId, int code, int missed, int cached)

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

Note: If you need a more comprehensive solution for low latency, high concurrency, and scalable real-time messaging and state synchronization, consider using Real-time Messaging.

Parameters

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

Metadata (SEI)

getMaxMetadataSize

Callback triggered when the SDK requests the maximum size of metadata.

virtual int getMaxMetadataSize() { return DEFAULT_METADATA_SIZE_IN_BYTE; }

After successfully registering by calling registerMediaMetadataObserver, the SDK triggers this callback every time it sends a video frame. You need to specify the maximum size of the metadata in the return value of this callback.

Return Values

If the method call succeeds, returns the maximum size in bytes of the metadata buffer you want to use. The maximum value is 1024 bytes.

registerMediaMetadataObserver

Registers a metadata observer.

virtual int registerMediaMetadataObserver(IMetadataObserver *observer, IMetadataObserver::METADATA_TYPE type) = 0;

You need to implement the IMetadataObserver class and specify the metadata type in this method. This method supports adding synchronized metadata to video streams for richer interactive live streaming scenarios, such as sending shopping links, digital coupons, and online quizzes. After a successful call, the SDK triggers the getMaxMetadataSize callback.

Note: Call this method before joinChannel.

Parameters

observer: The metadata observer. See IMetadataObserver.
type: The metadata type. See METADATA_TYPE. Currently, the SDK only supports VIDEO_METADATA.

Return Values

0: Success.
< 0: Failure.

unregisterMediaMetadataObserver

Unregisters the specified metadata observer.

virtual int unregisterMediaMetadataObserver(IMetadataObserver* observer, IMetadataObserver::METADATA_TYPE type) = 0;

Parameters

observer: The metadata observer. See IMetadataObserver.
type: The metadata type. Currently, the SDK only supports VIDEO_METADATA.

Return Values

0: Success.
< 0: Failure.

onMetadataReceived

Callback triggered when the local user receives metadata.

virtual void onMetadataReceived(const Metadata& metadata) = 0;

Parameters

metadata: The received metadata. See Metadata.

onReadyToSendMetadata

Callback triggered when the SDK is ready to send metadata.

virtual bool onReadyToSendMetadata(Metadata &metadata, VIDEO_SOURCE_TYPE source_type) = 0;

Note: Make sure the size of the metadata does not exceed the value set in the getMaxMetadataSize callback.

Trigger Timing

Triggered when the SDK is ready to send metadata.

Parameters

metadata: Metadata you want to send. See Metadata.
source_type: Type of video data. See VIDEO_SOURCE_TYPE.

Return Values

true: Send this video frame.
false: Do not send this video frame.