Connection

Connect and disconnect from a room. More...

Enumerations
enum	livekit_connection_state_t {   LIVEKIT_CONNECTION_STATE_DISCONNECTED = 0 , LIVEKIT_CONNECTION_STATE_CONNECTING = 1 , LIVEKIT_CONNECTION_STATE_CONNECTED = 2 , LIVEKIT_CONNECTION_STATE_RECONNECTING = 3 ,   LIVEKIT_CONNECTION_STATE_FAILED = 4 }
	Connection state of a room. More...
enum	livekit_failure_reason_t {   LIVEKIT_FAILURE_REASON_NONE , LIVEKIT_FAILURE_REASON_UNREACHABLE , LIVEKIT_FAILURE_REASON_BAD_TOKEN , LIVEKIT_FAILURE_REASON_UNAUTHORIZED ,   LIVEKIT_FAILURE_REASON_RTC , LIVEKIT_FAILURE_REASON_MAX_RETRIES , LIVEKIT_FAILURE_REASON_PING_TIMEOUT , LIVEKIT_FAILURE_REASON_DUPLICATE_IDENTITY ,   LIVEKIT_FAILURE_REASON_SERVER_SHUTDOWN , LIVEKIT_FAILURE_REASON_PARTICIPANT_REMOVED , LIVEKIT_FAILURE_REASON_ROOM_DELETED , LIVEKIT_FAILURE_REASON_STATE_MISMATCH ,   LIVEKIT_FAILURE_REASON_JOIN_INCOMPLETE , LIVEKIT_FAILURE_REASON_MIGRATION , LIVEKIT_FAILURE_REASON_SIGNAL_CLOSE , LIVEKIT_FAILURE_REASON_ROOM_CLOSED ,   LIVEKIT_FAILURE_REASON_SIP_USER_UNAVAILABLE , LIVEKIT_FAILURE_REASON_SIP_USER_REJECTED , LIVEKIT_FAILURE_REASON_SIP_TRUNK_FAILURE , LIVEKIT_FAILURE_REASON_CONNECTION_TIMEOUT ,   LIVEKIT_FAILURE_REASON_MEDIA_FAILURE , LIVEKIT_FAILURE_REASON_OTHER }
	Reason why room connection failed. More...

Functions
livekit_err_t	livekit_room_connect (livekit_room_handle_t handle, const char *server_url, const char *token)
	Connects to a room asynchronously.
livekit_err_t	livekit_room_close (livekit_room_handle_t handle)
	Disconnects from a room asynchronously.
livekit_connection_state_t	livekit_room_get_state (livekit_room_handle_t handle)
	Gets the current connection state of a room.
const char *	livekit_connection_state_str (livekit_connection_state_t state)
	Gets a string representation of a connection state.
livekit_failure_reason_t	livekit_room_get_failure_reason (livekit_room_handle_t handle)
	Gets the reason why the room connection failed.
const char *	livekit_failure_reason_str (livekit_failure_reason_t reason)
	Gets a string representation for a failure reason.

Detailed Description

Connect and disconnect from a room.

The connection state of a room can be monitored by setting a handler for livekit_room_options_t::on_state_changed, for example:

static void on_state_changed(livekit_connection_state_t state, void* ctx)
{
    ESP_LOGI(TAG, "Room state changed: %s", livekit_connection_state_str(state));
 
    // If the connection failed, find out why:
    livekit_failure_reason_t reason = livekit_room_get_failure_reason(room_handle);
    if (reason != LIVEKIT_FAILURE_REASON_NONE) {
        ESP_LOGE(TAG, "Failure reason: %s", livekit_failure_reason_str(reason));
    }
}

Enumeration Type Documentation

livekit_connection_state_t

enum livekit_connection_state_t

Connection state of a room.

Enumerator
LIVEKIT_CONNECTION_STATE_DISCONNECTED	Disconnected.
LIVEKIT_CONNECTION_STATE_CONNECTING	Establishing connection.
LIVEKIT_CONNECTION_STATE_CONNECTED	Connected.
LIVEKIT_CONNECTION_STATE_RECONNECTING	Reestablishing connection after a failure.
LIVEKIT_CONNECTION_STATE_FAILED	Connection failed after maximum number of retries.

livekit_failure_reason_t

enum livekit_failure_reason_t

Reason why room connection failed.

Enumerator
LIVEKIT_FAILURE_REASON_NONE	No failure has occurred.
LIVEKIT_FAILURE_REASON_UNREACHABLE	Unreachable. LiveKit server could not be reached: this may occur due to network connectivity issues, incorrect URL, TLS handshake failure, or an offline server.
LIVEKIT_FAILURE_REASON_BAD_TOKEN	Bad Token. Token is malformed: this can occur if the token has missing/empty identity or room fields, or if either of these fields exceeds the maximum length.
LIVEKIT_FAILURE_REASON_UNAUTHORIZED	Unauthorized. Token is not valid to join the room: this can be caused by an expired token, or a token that lacks necessary claims.
LIVEKIT_FAILURE_REASON_RTC	RTC. WebRTC establishment failure: required peer connection(s) could not be established or failed.
LIVEKIT_FAILURE_REASON_MAX_RETRIES	Max Retries. Maximum number of retries reached: room connection failed after CONFIG_LK_MAX_RETRIES retries.
LIVEKIT_FAILURE_REASON_PING_TIMEOUT	Ping Timeout. Server did not respond to ping within the timeout window.
LIVEKIT_FAILURE_REASON_DUPLICATE_IDENTITY	Duplicate Identity. Another participant already has the same identity. Protocol equivalent: DisconnectReason.DUPLICATE_IDENTITY.
LIVEKIT_FAILURE_REASON_SERVER_SHUTDOWN	Server Shutdown. LiveKit server instance is shutting down. Protocol equivalent: DisconnectReason.SERVER_SHUTDOWN.
LIVEKIT_FAILURE_REASON_PARTICIPANT_REMOVED	Participant Removed. Participant was removed using room services API. Protocol equivalent: DisconnectReason.PARTICIPANT_REMOVED.
LIVEKIT_FAILURE_REASON_ROOM_DELETED	Room Deleted. Room was deleted using room services API. Protocol equivalent: DisconnectReason.ROOM_DELETED.
LIVEKIT_FAILURE_REASON_STATE_MISMATCH	State Mismatch. Client attempted to resume, but server is not aware of it. Protocol equivalent: DisconnectReason.STATE_MISMATCH.
LIVEKIT_FAILURE_REASON_JOIN_INCOMPLETE	Join Incomplete. Client was unable to fully establish a connection. Protocol equivalent: DisconnectReason.JOIN_FAILURE.
LIVEKIT_FAILURE_REASON_MIGRATION	Migration. The server requested the client to migrate the connection elsewhere (cloud only). Protocol equivalent: DisconnectReason.MIGRATION.
LIVEKIT_FAILURE_REASON_SIGNAL_CLOSE	Signal Close. The signal connection was closed unexpectedly. Protocol equivalent: DisconnectReason.SIGNAL_CLOSE.
LIVEKIT_FAILURE_REASON_ROOM_CLOSED	Room Closed. The room was closed, due to all Standard and Ingress participants having left. Protocol equivalent: DisconnectReason.ROOM_CLOSED.
LIVEKIT_FAILURE_REASON_SIP_USER_UNAVAILABLE	SIP User Unavailable. SIP callee did not respond in time. Protocol equivalent: DisconnectReason.USER_UNAVAILABLE.
LIVEKIT_FAILURE_REASON_SIP_USER_REJECTED	SIP User Rejected. SIP callee rejected the call (busy). Protocol equivalent: DisconnectReason.USER_REJECTED.
LIVEKIT_FAILURE_REASON_SIP_TRUNK_FAILURE	SIP Trunk Failure. SIP protocol failure or unexpected response. Protocol equivalent: DisconnectReason.SIP_TRUNK_FAILURE.
LIVEKIT_FAILURE_REASON_CONNECTION_TIMEOUT	Connection Timeout. Server timed out a participant session. Protocol equivalent: DisconnectReason.CONNECTION_TIMEOUT.
LIVEKIT_FAILURE_REASON_MEDIA_FAILURE	Media Failure. Media stream failure or media timeout. Protocol equivalent: DisconnectReason.MEDIA_FAILURE.
LIVEKIT_FAILURE_REASON_OTHER	Other failure reason. Any other failure not covered by other reasons. Check console output for more details, and please report the issue on GitHub.

Function Documentation

livekit_connection_state_str()

const char * livekit_connection_state_str

(

livekit_connection_state_t

state

)

Gets a string representation of a connection state.

Parameters

state[in]

Connection state.

Returns

String representation of the connection state.

livekit_failure_reason_str()

const char * livekit_failure_reason_str

(

livekit_failure_reason_t

reason

)

Gets a string representation for a failure reason.

Parameters

reason[in]

Failure reason.

Returns

String representation of the failure reason.

livekit_room_close()

livekit_err_t livekit_room_close

(

livekit_room_handle_t

handle

)

Disconnects from a room asynchronously.

Parameters

handle[in]

Room handle.

Returns

LIVEKIT_ERR_NONE if successful, otherwise an error code.

livekit_room_connect()

livekit_err_t livekit_room_connect	(	livekit_room_handle_t	handle,
		const char *	server_url,
		const char *	token )

Connects to a room asynchronously.

Parameters

handle[in]	Room handle.
server_url[in]	URL of the LiveKit server beginning with "wss://" or "ws://".
token[in]	Server-generated token for authentication.

Returns

LIVEKIT_ERR_NONE, otherwise an error code.

livekit_room_get_failure_reason()

livekit_failure_reason_t livekit_room_get_failure_reason

(

livekit_room_handle_t

handle

)

Gets the reason why the room connection failed.

Use this to check why the room connection failed after the room's state changes to LIVEKIT_CONNECTION_STATE_FAILED or LIVEKIT_CONNECTION_STATE_RECONNECTING.

Parameters

handle[in]

Room handle.

Returns

Failure reason.

livekit_room_get_state()

livekit_connection_state_t livekit_room_get_state

(

livekit_room_handle_t

handle

)

Gets the current connection state of a room.

Parameters

handle[in]

Room handle.

Returns

Current connection state.