Manage connections
Updated
Create, inspect, and destroy RTC connections using the Connection ID mechanism.
IoT SDK identifies each RTC connection with a connection ID (connection_id_t). You create a connection before joining a channel, use the connection ID to scope every subsequent call (join, send data, mute, leave) to that connection, and destroy the connection when you are done with it. This mechanism lets a single device manage multiple independent connections at once, for example to stream to multiple channels or push multiple streams to a single channel.
This page shows you how to create, inspect, and destroy connections in your IoT SDK app.
Prerequisites
In order to follow this procedure you must have:
- Implemented the basic IoT SDK functionality. See Build from scratch.
Create a connection
Call agora_rtc_create_connection after you initialize the engine and before you join a channel:
// Create a connection
rval = agora_rtc_create_connection(&g_conn_id);
if (rval < 0) {
printf("Failed to create connection, reason: %s\n", agora_rtc_err_2_str(rval));
return -1;
}Use g_conn_id in every subsequent call that is scoped to this connection, such as agora_rtc_join_channel, agora_rtc_send_audio_data, agora_rtc_send_video_data, agora_rtc_mute_local_audio, and agora_rtc_leave_channel.
Inspect connection info
Call agora_rtc_get_connection_info to retrieve details about an active connection, such as the channel it is joined to. This example logs the channel name when the connection successfully joins a channel:
static void __on_join_channel_success(connection_id_t conn_id, uint32_t uid, int elapsed) {
g_connected_flag = true;
connection_info_t conn_info = {0};
agora_rtc_get_connection_info(g_conn_id, &conn_info);
printf("[conn-%u] Join the channel %s successfully, uid %u elapsed %d ms\n", conn_id, conn_info.channel_name, uid, elapsed);
}Destroy a connection
When you are done with a connection, typically when the app shuts down or leaves a channel for good, leave the channel and then destroy the connection to release its resources:
agora_rtc_leave_channel(g_conn_id);
agora_rtc_destroy_connection(g_conn_id);
agora_rtc_fini();