settings.h File Reference

Go to the source code of this file.

Data Structures
struct	acip_render_settings_t
	acip render settings keeps the values that move through the subsystem: caps, width, height, revision. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself. More...
struct	acip_settings_header_t
	acip settings header keeps the values that move through the subsystem: schema, request, expected_revision, revision. Some members are pointers into caller- or subsystem-owned memory, so lifetime follows the API that populated them rather than the struct copy itself. More...

Macros
#define	NETWORK_ACIP_SETTINGS_PALETTE_BUFFER_SIZE   256
#define	NETWORK_ACIP_SETTINGS_LUMINANCE_BUFFER_SIZE   256
#define	ACIP_SETTINGS_SCHEMA   1
#define	ACIP_SETTINGS_HEADER_SIZE   20
#define	ACIP_SETTINGS_MAX_SIZE   4116

Functions
asciichat_error_t	acip_render_settings_capabilities (acip_render_settings_t *state, const terminal_capabilities_packet_t *packet)
terminal_color_mode_t	acip_render_settings_normalize_color_mode (terminal_color_mode_t mode)
asciichat_error_t	acip_render_settings_prepare (acip_render_settings_t *candidate, const options_t *values)
void	acip_render_settings_options (const acip_render_settings_t *state, options_t *values)
asciichat_error_t	acip_settings_decode (const void *payload, size_t length, acip_settings_header_t *header, const char **json, size_t *json_length)
asciichat_error_t	acip_settings_encode (const acip_settings_header_t *header, const char *json, uint8_t *buffer, size_t capacity, size_t *length)
asciichat_error_t	acip_settings_request (acip_render_settings_t *state, const void *payload, size_t length, uint8_t *reply, size_t capacity, size_t *reply_length)
asciichat_error_t	acip_settings_send (acip_transport_t *transport, const options_t *values, uint32_t request, uint32_t expected_revision)

Macro Definition Documentation

ACIP_SETTINGS_HEADER_SIZE

#define ACIP_SETTINGS_HEADER_SIZE   20

Definition at line 12 of file include/ascii-chat/network/acip/settings.h.

Referenced by acip_settings_decode(), acip_settings_encode(), handle_client_capabilities_packet(), and session_host_receive_packet().

ACIP_SETTINGS_MAX_SIZE

#define ACIP_SETTINGS_MAX_SIZE   4116

Definition at line 13 of file include/ascii-chat/network/acip/settings.h.

Referenced by acip_settings_decode(), acip_settings_send(), handle_runtime_settings(), and session_host_receive_packet().

ACIP_SETTINGS_SCHEMA

#define ACIP_SETTINGS_SCHEMA   1

Definition at line 11 of file include/ascii-chat/network/acip/settings.h.

Referenced by acip_settings_decode(), and acip_settings_send().

NETWORK_ACIP_SETTINGS_LUMINANCE_BUFFER_SIZE

#define NETWORK_ACIP_SETTINGS_LUMINANCE_BUFFER_SIZE   256

Definition at line 5 of file include/ascii-chat/network/acip/settings.h.

NETWORK_ACIP_SETTINGS_PALETTE_BUFFER_SIZE

#define NETWORK_ACIP_SETTINGS_PALETTE_BUFFER_SIZE   256

Definition at line 4 of file include/ascii-chat/network/acip/settings.h.

Function Documentation

acip_render_settings_capabilities()

asciichat_error_t acip_render_settings_capabilities	(	acip_render_settings_t *	state,
		const terminal_capabilities_packet_t *	packet )

Definition at line 93 of file lib/network/acip/settings.c.

                                                                                                  {
  if (!state || !packet || !memchr(packet->palette_custom, 0, sizeof(packet->palette_custom)))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid render capabilities");
  options_t *values = SAFE_MALLOC(sizeof(*values), options_t *);
  acip_render_settings_options(state, values);
  values->width = NET_TO_HOST_U16(packet->width);
  values->height = NET_TO_HOST_U16(packet->height);
  values->fps = packet->desired_fps;
  values->color_mode = NET_TO_HOST_U32(packet->color_level);
  values->color_filter = packet->color_filter;
  values->render_mode = NET_TO_HOST_U32(packet->render_mode);
  values->palette_type = NET_TO_HOST_U32(packet->palette_type);
  // AUTO is a local option sentinel, but older/native/browser senders may
  // still advertise it. Resolve it at the shared wire boundary so the peer
  // cannot reject an otherwise valid capabilities packet.
  values->color_mode = acip_render_settings_normalize_color_mode(values->color_mode);
  if (values->palette_type == PALETTE_UNSET)
    values->palette_type = PALETTE_STANDARD;
  SAFE_STRNCPY(values->palette_custom, packet->palette_custom, sizeof(values->palette_custom));
  values->matrix_rain = (NET_TO_HOST_U32(packet->capabilities) & TERM_CAP_MATRIX_RAIN) != 0;
  acip_render_settings_t next = *state;
  next.caps.capabilities = NET_TO_HOST_U32(packet->capabilities);
  next.caps.utf8_support = NET_TO_HOST_U32(packet->utf8_support) != 0;
  next.caps.wants_padding = packet->wants_padding != 0;
  asciichat_error_t result = prepare_for_viewer(&next, values);
  if (result == ASCIICHAT_OK)
    *state = next;
  SAFE_FREE(values);
  return result;
}

References acip_render_settings_normalize_color_mode(), acip_render_settings_options(), ASCIICHAT_OK, terminal_capabilities_packet_t::capabilities, acip_render_settings_t::caps, options_state::color_filter, terminal_capabilities_packet_t::color_filter, terminal_capabilities_packet_t::color_level, options_state::color_mode, terminal_capabilities_packet_t::desired_fps, ERROR_INVALID_PARAM, options_state::fps, options_state::height, terminal_capabilities_packet_t::height, options_state::matrix_rain, NET_TO_HOST_U16, NET_TO_HOST_U32, options_state::palette_custom, terminal_capabilities_packet_t::palette_custom, PALETTE_STANDARD, options_state::palette_type, terminal_capabilities_packet_t::palette_type, PALETTE_UNSET, options_state::render_mode, terminal_capabilities_packet_t::render_mode, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, terminal_capabilities_packet_t::utf8_support, terminal_capabilities_packet_t::wants_padding, options_state::width, and terminal_capabilities_packet_t::width.

Referenced by handle_client_capabilities_packet(), and session_host_receive_packet().

acip_render_settings_normalize_color_mode()

terminal_color_mode_t acip_render_settings_normalize_color_mode

(

terminal_color_mode_t

mode

)

Resolve local-only color sentinels before render settings cross the ACIP boundary.

Definition at line 26 of file lib/network/acip/settings.c.

                                                                                            {
  return mode == TERM_COLOR_AUTO ? TERM_COLOR_TRUECOLOR : mode;
}

Referenced by acip_render_settings_capabilities(), acip_settings_request(), and session_protocol_build_capabilities().

acip_render_settings_options()

void acip_render_settings_options	(	const acip_render_settings_t *	state,
		options_t *	values )

Definition at line 9 of file lib/network/acip/settings.c.

                                                                                          {
  *values = options_t_new();
  values->width = state->width;
  values->height = state->height;
  values->fps = state->caps.desired_fps;
  values->color_mode = (terminal_color_mode_t)state->caps.color_level;
  values->color_filter = state->caps.color_filter;
  values->render_mode = state->caps.render_mode;
  values->renderer = state->caps.text_renderer;
  values->stabilize = state->caps.stabilize;
  values->palette_explicit = state->caps.palette_explicit;
  values->palette_type = state->caps.palette_type ? state->caps.palette_type : PALETTE_STANDARD;
  SAFE_STRNCPY(values->palette_custom, state->caps.palette_custom, sizeof(values->palette_custom));
  values->palette_custom_set = values->palette_custom[0] != 0;
  values->matrix_rain = (state->caps.capabilities & TERM_CAP_MATRIX_RAIN) != 0;
}

References options_state::color_filter, options_state::color_mode, options_state::fps, options_state::height, options_state::matrix_rain, options_t_new(), options_state::palette_custom, options_state::palette_custom_set, options_state::palette_explicit, PALETTE_STANDARD, options_state::palette_type, options_state::render_mode, options_state::renderer, SAFE_STRNCPY, options_state::stabilize, and options_state::width.

Referenced by acip_render_settings_capabilities(), acip_settings_request(), client_settings_receive(), client_settings_values(), and session_protocol_dispatch().

acip_render_settings_prepare()

asciichat_error_t acip_render_settings_prepare	(	acip_render_settings_t *	candidate,
		const options_t *	values )

Definition at line 30 of file lib/network/acip/settings.c.

                                                                                                           {
  if (!candidate || !values || values->width < 1 || values->width > 4096 || values->height < 1 ||
      values->height > 4096 || (uint64_t)values->width * values->height > 1048576 || values->fps < 0 ||
      values->fps > 144 || values->color_mode < TERM_COLOR_NONE || values->color_mode > TERM_COLOR_TRUECOLOR ||
      values->color_filter < 0 || values->color_filter >= COLOR_FILTER_COUNT || values->render_mode < 0 ||
      values->render_mode > RENDER_MODE_HALF_BLOCK || values->palette_type < PALETTE_STANDARD ||
      values->palette_type >= PALETTE_COUNT || strlen(values->palette_custom) >= sizeof(candidate->caps.palette_custom))
    return SET_ERRNO(
        ERROR_INVALID_PARAM,
        "Invalid remote render settings (size=%dx%d fps=%d color=%d filter=%d mode=%d palette=%d custom=%zu)",
        values->width, values->height, values->fps, values->color_mode, values->color_filter, values->render_mode,
        values->palette_type, strlen(values->palette_custom));
  acip_render_settings_t next = *candidate;
  next.width = (uint16_t)values->width;
  next.height = (uint16_t)values->height;
  next.caps.desired_fps =
      candidate->fps_limit && values->fps > candidate->fps_limit ? candidate->fps_limit : values->fps;
  next.caps.color_level = values->color_mode;
  next.caps.color_count = values->color_mode == TERM_COLOR_TRUECOLOR ? 16777216
                          : values->color_mode == TERM_COLOR_256     ? 256
                          : values->color_mode == TERM_COLOR_16      ? 16
                                                                     : 2;
  next.caps.color_filter = values->color_filter;
  next.caps.render_mode = values->render_mode;
  next.caps.text_renderer = values->renderer;
  next.caps.stabilize = values->stabilize;
  next.caps.palette_explicit = values->palette_explicit;
  next.caps.wants_background = values->render_mode == RENDER_MODE_BACKGROUND;
  next.caps.palette_type = values->palette_type;
  SAFE_STRNCPY(next.caps.palette_custom, values->palette_custom, sizeof(next.caps.palette_custom));
  if (values->matrix_rain)
    next.caps.capabilities |= TERM_CAP_MATRIX_RAIN;
  else
    next.caps.capabilities &= ~(uint32_t)TERM_CAP_MATRIX_RAIN;
  if (initialize_client_palette(next.caps.palette_type, values->palette_custom, next.palette, &next.palette_length,
                                next.luminance))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid rendering palette");
  if (values->renderer == ASCII_RENDERER_GLYPH && values->palette_explicit &&
      !ascii_glyph_palette_supported(next.palette))
    return SET_ERRNO(ERROR_INVALID_PARAM, "Glyph palette contains characters without glyph masks");
  if (values->renderer == ASCII_RENDERER_GLYPH && !values->palette_explicit) {
    SAFE_STRNCPY(next.palette,
                 " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~",
                 sizeof(next.palette));
    next.palette_length = strlen(next.palette);
  }
  next.revision = candidate->revision + 1;
  *candidate = next;
  return ASCIICHAT_OK;
}

References ascii_glyph_palette_supported(), ASCII_RENDERER_GLYPH, ASCIICHAT_OK, acip_render_settings_t::caps, options_state::color_filter, options_state::color_mode, ERROR_INVALID_PARAM, options_state::fps, acip_render_settings_t::fps_limit, acip_render_settings_t::height, options_state::height, initialize_client_palette(), acip_render_settings_t::luminance, options_state::matrix_rain, acip_render_settings_t::palette, PALETTE_COUNT, options_state::palette_custom, options_state::palette_explicit, acip_render_settings_t::palette_length, PALETTE_STANDARD, options_state::palette_type, options_state::render_mode, options_state::renderer, acip_render_settings_t::revision, SAFE_STRNCPY, SET_ERRNO, options_state::stabilize, acip_render_settings_t::width, and options_state::width.

Referenced by client_settings_receive(), session_participant_request_settings(), and session_protocol_dispatch().

acip_settings_decode()

asciichat_error_t acip_settings_decode	(	const void *	payload,
		size_t	length,
		acip_settings_header_t *	header,
		const char **	json,
		size_t *	json_length )

Definition at line 125 of file lib/network/acip/settings.c.

                                                                               {
  if (!payload || !header || !json || !json_length || length < ACIP_SETTINGS_HEADER_SIZE ||
      length > ACIP_SETTINGS_MAX_SIZE)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid settings packet length");
  uint32_t fields[5];
  memcpy(fields, payload, sizeof(fields));
  *header = (acip_settings_header_t){NET_TO_HOST_U32(fields[0]), NET_TO_HOST_U32(fields[1]), NET_TO_HOST_U32(fields[2]),
                                     NET_TO_HOST_U32(fields[3]), NET_TO_HOST_U32(fields[4])};
  if (header->schema != ACIP_SETTINGS_SCHEMA)
    return SET_ERRNO(ERROR_NOT_SUPPORTED, "Unsupported settings schema");
  *json = (const char *)payload + ACIP_SETTINGS_HEADER_SIZE;
  *json_length = length - ACIP_SETTINGS_HEADER_SIZE;
  return ASCIICHAT_OK;
}

References ACIP_SETTINGS_HEADER_SIZE, ACIP_SETTINGS_MAX_SIZE, ACIP_SETTINGS_SCHEMA, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, NET_TO_HOST_U32, and SET_ERRNO.

Referenced by acip_settings_request(), client_settings_receive(), session_participant_receive_settings(), and session_protocol_dispatch().

acip_settings_encode()

asciichat_error_t acip_settings_encode	(	const acip_settings_header_t *	header,
		const char *	json,
		uint8_t *	buffer,
		size_t	capacity,
		size_t *	length )

Definition at line 141 of file lib/network/acip/settings.c.

                                                                        {
  if (!header || !json || !buffer || !length)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Missing settings encoding argument");
  size_t size = strlen(json);
  if (size > 4096 || capacity < ACIP_SETTINGS_HEADER_SIZE + size)
    return SET_ERRNO(ERROR_INVALID_PARAM, "Settings output too small");
  uint32_t fields[5] = {HOST_TO_NET_U32(header->schema), HOST_TO_NET_U32(header->request),
                        HOST_TO_NET_U32(header->expected_revision), HOST_TO_NET_U32(header->revision),
                        HOST_TO_NET_U32(header->status)};
  memcpy(buffer, fields, sizeof(fields));
  memcpy(buffer + sizeof(fields), json, size);
  *length = sizeof(fields) + size;
  return ASCIICHAT_OK;
}

References ACIP_SETTINGS_HEADER_SIZE, ASCIICHAT_OK, ERROR_INVALID_PARAM, HOST_TO_NET_U32, and SET_ERRNO.

Referenced by acip_settings_request(), acip_settings_send(), handle_client_capabilities_packet(), and session_host_receive_packet().

acip_settings_request()

asciichat_error_t acip_settings_request	(	acip_render_settings_t *	state,
		const void *	payload,
		size_t	length,
		uint8_t *	reply,
		size_t	capacity,
		size_t *	reply_length )

A rejected request returns current effective values without changing state.

Definition at line 157 of file lib/network/acip/settings.c.

                                                                                               {
  acip_settings_header_t header = {0};
  const char *json = NULL;
  size_t json_length = 0;
  asciichat_error_t result = acip_settings_decode(payload, length, &header, &json, &json_length);
  if (result != ASCIICHAT_OK)
    return result;
  asciichat_errno_scope_t request_scope = errno_scope_begin();
  options_t *current = SAFE_MALLOC(sizeof(*current), options_t *),
            *candidate = SAFE_MALLOC(sizeof(*candidate), options_t *);
  acip_render_settings_options(state, current);
  if (header.status)
    result = SET_ERRNO(ERROR_INVALID_PARAM, "Unexpected settings request status");
  else if (header.expected_revision != UINT32_MAX && header.expected_revision != state->revision)
    result = SET_ERRNO(ERROR_INVALID_STATE, "Remote settings changed; refresh and retry");
  else if (json_length) {
    result = options_prepare_json(current, json, json_length, candidate, true);
    if (result == ASCIICHAT_OK) {
      // AUTO is a local option sentinel and is not valid in the negotiated
      // render state. Keep legacy settings updates from invalidating a live
      // session when they serialize the raw AUTO option.
      candidate->color_mode = acip_render_settings_normalize_color_mode(candidate->color_mode);
      result = prepare_for_viewer(state, candidate);
    }
  }
  header.status = result;
  header.revision = state->revision;
  // The rejection is represented by the response status, preserving older errors.
  errno_scope_end(request_scope, ASCIICHAT_ERRNO_HANDLED);
  acip_render_settings_options(state, current);
  char *effective = options_values_json(current, true);
  asciichat_error_t encoded =
      effective ? acip_settings_encode(&header, effective, reply, capacity, reply_length) : ERROR_MEMORY;
  SAFE_FREE(effective);
  SAFE_FREE(candidate);
  SAFE_FREE(current);
  return encoded;
}

References acip_render_settings_normalize_color_mode(), acip_render_settings_options(), acip_settings_decode(), acip_settings_encode(), ASCIICHAT_ERRNO_HANDLED, ASCIICHAT_OK, errno_scope_begin(), errno_scope_end(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, options_prepare_json(), options_values_json(), SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

Referenced by handle_runtime_settings(), and session_host_receive_packet().

acip_settings_send()

asciichat_error_t acip_settings_send	(	acip_transport_t *	transport,
		const options_t *	values,
		uint32_t	request,
		uint32_t	expected_revision )

Definition at line 197 of file lib/network/acip/settings.c.

                                                                 {
  char *json = options_values_json(values, true);
  if (!json)
    return SET_ERRNO(ERROR_MEMORY, "Cannot encode render preferences");
  uint8_t buffer[ACIP_SETTINGS_MAX_SIZE];
  size_t length = 0;
  acip_settings_header_t header = {
      .schema = ACIP_SETTINGS_SCHEMA, .request = request, .expected_revision = expected_revision};
  asciichat_error_t result = acip_settings_encode(&header, json, buffer, sizeof(buffer), &length);
  if (result == ASCIICHAT_OK)
    result = packet_send_via_transport(transport, PACKET_TYPE_ACIP_SETTINGS_SYNC, buffer, length, 0);
  SAFE_FREE(json);
  return result;
}

References acip_settings_encode(), ACIP_SETTINGS_MAX_SIZE, ACIP_SETTINGS_SCHEMA, ASCIICHAT_OK, ERROR_MEMORY, options_values_json(), packet_send_via_transport(), PACKET_TYPE_ACIP_SETTINGS_SYNC, SAFE_FREE, and SET_ERRNO.

Referenced by client_protocol_start(), and session_participant_request_settings().