participant.h File Reference

👤 Client-side session participation abstraction More...

Go to the source code of this file.

Data Structures
struct	session_participant_callbacks_t
	Client-side event hooks for connection, media, settings, and errors. More...
struct	session_participant_config_t
	Client-side event hooks for connection, media, settings, and errors. More...

Typedefs
typedef struct acip_transport	acip_transport_t
	Forward declaration of ACIP transport.

Functions
session_participant_t *	session_participant_create (const session_participant_config_t *config)
	Server address, security, media, transport, and callback settings for a participant.
void	session_participant_destroy (session_participant_t *p)
	Destroy session participant and free resources.
asciichat_error_t	session_participant_connect (session_participant_t *p)
	Connect to session server.
void	session_participant_disconnect (session_participant_t *p)
	Disconnect from session server.
bool	session_participant_is_connected (session_participant_t *p)
	Check if participant is connected.
uint32_t	session_participant_get_client_id (session_participant_t *p)
	Get assigned client ID.
asciichat_error_t	session_participant_start_video (session_participant_t *p)
	Start video capture and streaming.
void	session_participant_stop_video (session_participant_t *p)
	Stop and join video capture, then release its resources Also stops audio when it may borrow the video media source.
bool	session_participant_is_video_active (session_participant_t *p)
	Check if video is streaming.
asciichat_error_t	session_participant_start_audio (session_participant_t *p)
	Start audio capture and streaming.
void	session_participant_stop_audio (session_participant_t *p)
	Stop audio capture and streaming.
bool	session_participant_is_audio_active (session_participant_t *p)
	Check if audio is streaming.
asciichat_error_t	session_participant_get_settings (session_participant_t *p, session_settings_t *settings)
	Get current session settings.
asciichat_error_t	session_participant_request_settings (session_participant_t *p, const session_settings_t *settings)
	Request this participant's remote rendering update.
asciichat_error_t	session_participant_set_transport (session_participant_t *p, acip_transport_t *transport, acip_transport_ownership_t ownership)
	Select a transport and its ownership mode for the participant.
asciichat_error_t	session_participant_set_connection (session_participant_t *p, network_connection_t **owner)
	Detach the selected transport and transfer its ownership responsibility.
asciichat_error_t	session_participant_take_connection (session_participant_t *, network_connection_t **)
acip_transport_t *	session_participant_get_transport (session_participant_t *p)
	Get the current transport for the participant.
bool	session_participant_has_transport (session_participant_t *p)
	Check if participant has a selected transport.
network_connection_t *	session_participant_connection (session_participant_t *p)
asciichat_error_t	session_participant_receive_settings (session_participant_t *p, const void *payload, size_t length)

Detailed Description

👤 Client-side session participation abstraction

Definition in file participant.h.

Function Documentation

session_participant_connection()

network_connection_t * session_participant_connection

(

session_participant_t *

p

)

Borrow the connection until the participant stops or transfers ownership.

Definition at line 815 of file participant.c.

                                                                               {
  return p ? p->network : NULL;
}

References session_participant::network.

session_participant_receive_settings()

asciichat_error_t session_participant_receive_settings	(	session_participant_t *	p,
		const void *	payload,
		size_t	length )

Dispatch SETTINGS_ACK on the connection owner thread; callbacks run outside locks.

Definition at line 819 of file participant.c.

                                                                                                                     {
  if (!p || !p->initialized)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant");
  acip_settings_header_t header;
  const char *json;
  size_t json_length;
  asciichat_error_t result = acip_settings_decode(payload, length, &header, &json, &json_length);
  if (result != ASCIICHAT_OK)
    return result;
  mutex_lock(&p->settings_mutex);
  if ((header.request && (header.request > p->settings_request || header.request < p->settings_applied_request)) ||
      header.revision < p->settings.version) {
    mutex_unlock(&p->settings_mutex);
    return ASCIICHAT_OK;
  }
  options_t *current = SAFE_MALLOC(sizeof(*current), options_t *),
            *candidate = SAFE_MALLOC(sizeof(*candidate), options_t *);
  session_settings_to_options(&p->settings, current);
  result = options_prepare_json(current, json, json_length, candidate, true);
  if (result == ASCIICHAT_OK) {
    session_settings_from_values(candidate, &p->settings);
    p->settings.version = header.revision;
    if (header.request)
      p->settings_applied_request = header.request;
  }
  session_settings_t effective = p->settings;
  SAFE_FREE(current);
  SAFE_FREE(candidate);
  mutex_unlock(&p->settings_mutex);
  if (result != ASCIICHAT_OK)
    return result;
  if (header.status && p->callbacks.on_error)
    p->callbacks.on_error(p, (asciichat_error_t)header.status, "Remote rendering update rejected", p->user_data);
  if (p->callbacks.on_settings_changed)
    p->callbacks.on_settings_changed(p, &effective, p->user_data);
  return ASCIICHAT_OK;
}

References acip_settings_decode(), ASCIICHAT_OK, session_participant::callbacks, ERROR_INVALID_PARAM, session_participant::initialized, session_participant_callbacks_t::on_error, session_participant_callbacks_t::on_settings_changed, options_prepare_json(), SAFE_FREE, SAFE_MALLOC, session_settings_from_values(), session_settings_to_options(), SET_ERRNO, session_participant::settings, session_participant::settings_applied_request, session_participant::settings_mutex, session_participant::settings_request, session_participant::user_data, and session_settings_t::version.

session_participant_set_connection()

asciichat_error_t session_participant_set_connection	(	session_participant_t *	p,
		network_connection_t **	owner )

Detach the selected transport and transfer its ownership responsibility.

Parameters

p	Participant whose media workers have been stopped
transport	Receives the detached transport, or NULL if none
ownership	Receives the detached transport's ownership mode

Returns

ASCIICHAT_OK on success; outputs are unchanged on failure

Definition at line 784 of file participant.c.

                                                                                                             {
  if (!owner || !*owner)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing participant connection");
  asciichat_error_t result = session_participant_set_transport(p, NULL, ACIP_TRANSPORT_BORROWED);
  if (result != ASCIICHAT_OK)
    return result;
  p->network = *owner;
  *owner = NULL;
  p->transport = network_connection_transport(p->network);
  p->transport_ownership = ACIP_TRANSPORT_OWNED;
  result = session_connection_start(&p->connection);
  p->connected = result == ASCIICHAT_OK && acip_transport_is_connected(p->transport);
  return result;
}

References ACIP_TRANSPORT_BORROWED, ACIP_TRANSPORT_OWNED, ASCIICHAT_OK, session_participant::connected, session_participant::connection, ERROR_INVALID_PARAM, session_participant::network, network_connection_transport(), session_connection_start(), session_participant_set_transport(), SET_ERRNO, session_participant::transport, and session_participant::transport_ownership.

session_participant_take_connection()

asciichat_error_t session_participant_take_connection	(	session_participant_t *	p,
		network_connection_t **	connection )

Definition at line 768 of file participant.c.

                                                                                                                   {
  if (!p || !p->initialized || !connection)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing participant connection output");
  if (session_av_state_should_run(&p->video) || session_av_state_should_run(&p->audio) || p->video_thread_created ||
      p->audio_thread_created)
    return SET_ERRNO(ERROR_INVALID_STATE, "Stop media before transferring its connection");
  if (!p->network)
    return SET_ERRNO(ERROR_INVALID_STATE, "Participant does not own a connection");
  *connection = p->network;
  p->network = NULL;
  p->transport = NULL;
  p->transport_ownership = ACIP_TRANSPORT_BORROWED;
  p->connected = false;
  return ASCIICHAT_OK;
}

References ACIP_TRANSPORT_BORROWED, ASCIICHAT_OK, session_participant::audio, session_participant::audio_thread_created, session_participant::connected, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, session_participant::initialized, session_participant::network, session_av_state_should_run(), SET_ERRNO, session_participant::transport, session_participant::transport_ownership, session_participant::video, and session_participant::video_thread_created.