Send and receive data streams

In addition to audio and video, IoT SDK lets you send and receive your own data alongside a channel's media streams. Use a data stream to broadcast custom, application-specific payloads to other users in a channel, for example to synchronize state in real time or send control signaling, without needing a separate signaling channel.

Prerequisites

In order to follow this procedure you must have:

Implemented the basic IoT SDK functionality and joined a channel. See Build from scratch and Manage connections.

Initialize and join a channel

Initialize IoT SDK, create a connection, and join a channel:

int rval;
connection_id_t conn_id = 0;

// Initialize
rval = agora_rtc_init(appid, &event_handler, &service_opt);
if (rval < 0) {
    printf("Failed to initialize Agora SDK, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

// Create a connection
rval = agora_rtc_create_connection(&conn_id);
if (rval < 0) {
    printf("Failed to create connection, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

// Join a channel
rtc_channel_options_t channel_opt = { 0 };
rval = agora_rtc_join_channel(conn_id, "channel-xxx", uid, token, &channel_opt);
if (rval < 0) {
    printf("Failed to join channel, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

Create a data stream

Call agora_rtc_create_data_stream to create a data stream on an active connection:

int stream_id;
int rval = agora_rtc_create_data_stream(conn_id, &stream_id, reliable, ordered);
if (rval < 0) {
    printf("Failed to create data stream, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

You configure two properties for each stream:

reliable: When true, the SDK retransmits lost packets for up to 5 seconds.
ordered: When true, the SDK reorders out-of-order packets. Packets that stay unresolved for more than 5 seconds are skipped.

The SDK supports the following reliable/ordered combinations:

`reliable`	`ordered`	Supported	Description
`true`	`true`	Yes	Reliable and ordered.
`true`	`false`	No	Reliable without ordering has no practical value, so IoT SDK doesn't allow this combination.
`false`	`true`	Yes	Unreliable but ordered.
`false`	`false`	Yes	Unreliable and unordered.

You can create up to 5 data streams per client.

Send data

Call agora_rtc_send_stream_message to send a payload on a stream:

int rval = agora_rtc_send_stream_message(conn_id, stream_id, data, length);
if (rval < 0) {
    printf("Failed to send stream message, reason: %s\n", agora_rtc_err_2_str(rval));
    return -1;
}

Data streams are rate-limited:

Up to 60 packets per second, per channel.
Up to 1 KB per packet.
Up to 6 KB per second, per data stream.
Up to 30 Kbps in aggregate across all data streams on a connection.

Receive data

Handle the on_stream_message callback to receive data sent by a remote user:

static void __on_stream_message(connection_id_t conn_id, uint32_t uid, int stream_id, const char *data, size_t length, uint64_t sent_ts) {
    printf("[conn-%u] Received %zu bytes on stream %d from uid %u\n", conn_id, length, stream_id, uid);
}

Sample code

The IoT SDK package includes a complete data stream example. See the full implementation in hello_stream_message.c:

├── agora_rtsa_sdk  # Agora SDK libraries and header files
└── example
    └── hello_stream_message
        └── hello_stream_message.c  # Use data streams in a single channel