mx-remote-ffi 1.0.0

// Author: Lars Op den Kamp (lars@opdenkamp-it.nl)
// Copyright (c) 2026 Op den Kamp IT Solutions


#ifndef MX_REMOTE_H
#define MX_REMOTE_H

/*
 * Generated from the mx-remote-ffi crate by cbindgen. Do not edit: every
 * change belongs in the Rust source, and this file is regenerated and diffed
 * in CI.
 */


#include <stdarg.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * Bytes a [`mxr_uid_t`] needs when written as text, the terminator included.
 */
#define MXR_UID_STRING_LEN 36

/**
 * Bytes a device, bay or port name needs, the terminator included.
 *
 * The wire field is 16 bytes wide. The rest is headroom for the names this
 * library derives rather than reads, which that width does not bound.
 */
#define MXR_NAME_LEN 32

/**
 * Bytes a serial number needs, the terminator included.
 */
#define MXR_SERIAL_LEN 32

/**
 * Bytes a model name needs, the terminator included.
 */
#define MXR_MODEL_LEN 48

/**
 * Bytes a firmware version string needs, the terminator included.
 *
 * The wire field is 128 bytes and is not NUL-terminated when full.
 */
#define MXR_VERSION_LEN 129

/**
 * Bytes a signal description such as `1080p60 444 8` needs, the terminator
 * included.
 */
#define MXR_SIGNAL_TYPE_LEN 48

/**
 * Bytes a device's system-status message needs, the terminator included.
 */
#define MXR_MESSAGE_LEN 128

/**
 * Number of EQ bands an amplifier zone carries.
 *
 * Written as a literal because the generated header needs one, and checked
 * against the core crate's value below so the two cannot drift apart.
 */
#define MXR_AMP_EQ_BANDS 5

/**
 * Bytes an IPv4 address needs when written as text, the terminator included.
 */
#define MXR_IP_STRING_LEN 16

/**
 * How many inputs a multiviewer has.
 *
 * Written as a literal because the generated header needs one, and checked
 * against the core crate's value below so the two cannot drift apart.
 */
#define MXR_MULTIVIEWER_INPUTS 4

/**
 * How many pairs a UTP cable diagnostic covers.
 */
#define MXR_UTP_PAIRS 4

/**
 * How many outlets a PDU reports.
 */
#define MXR_PDU_OUTLETS 8

/**
 * Set when the frame carries a scaling mode and refresh rate.
 */
#define MXR_SCALING_FLAG_MODE_VALID (1 << 0)

/**
 * Set when the frame carries the scaling options.
 */
#define MXR_SCALING_FLAG_OPTIONS_VALID (1 << 1)

/**
 * Set when the output scales automatically.
 */
#define MXR_SCALING_FLAG_AUTO_SCALING (1 << 7)

/**
 * The audio return channel a bay is carrying.
 */
enum mxr_arc_status_t
#ifdef __cplusplus
  : int32_t
#endif // __cplusplus
 {
  /**
   * No audio is being returned.
   */
  MXR_ARC_INACTIVE = 0,
  /**
   * Returned over HDMI.
   */
  MXR_ARC_HDMI = 1,
  /**
   * Returned over optical.
   */
  MXR_ARC_OPTICAL = 2,
  /**
   * Returned over analogue.
   */
  MXR_ARC_ANALOG = 3,
};
#ifndef __cplusplus
typedef int32_t mxr_arc_status_t;
#endif // __cplusplus

/**
 * The high-level state of a device on the network.
 */
enum mxr_device_status_t
#ifdef __cplusplus
  : int32_t
#endif // __cplusplus
 {
  /**
   * Reachable and reporting.
   */
  MXR_DEVICE_ONLINE = 0,
  /**
   * Has stopped answering.
   */
  MXR_DEVICE_OFFLINE = 1,
  /**
   * Announced a reboot.
   */
  MXR_DEVICE_REBOOTING = 2,
  /**
   * Still coming up.
   */
  MXR_DEVICE_BOOTING = 3,
  /**
   * Present but not participating.
   */
  MXR_DEVICE_INACTIVE = 4,
};
#ifndef __cplusplus
typedef int32_t mxr_device_status_t;
#endif // __cplusplus

/**
 * The CEC power state of whatever is connected to a bay.
 */
enum mxr_power_status_t
#ifdef __cplusplus
  : int32_t
#endif // __cplusplus
 {
  /**
   * The bay has not reported a power state.
   */
  MXR_POWER_UNKNOWN = 0,
  /**
   * Powered on.
   */
  MXR_POWER_ON = 1,
  /**
   * Powered off.
   */
  MXR_POWER_OFF = 2,
};
#ifndef __cplusplus
typedef int32_t mxr_power_status_t;
#endif // __cplusplus

/**
 * How a call ended.
 *
 * Everything but [`mxr_result_t::MXR_OK`] is negative, so `if (rc < 0)` is a
 * complete test and a new code cannot turn a failure into a success.
 */
enum mxr_result_t
#ifdef __cplusplus
  : int32_t
#endif // __cplusplus
 {
  /**
   * The call did what was asked.
   */
  MXR_OK = 0,
  /**
   * A pointer was null, a buffer too small, or a string not UTF-8.
   */
  MXR_ERR_INVALID_ARGUMENT = -1,
  /**
   * No device, bay or source by that name has been heard from.
   *
   * A device reports itself when it feels like it, so this is as likely to
   * mean "not yet" as "never": the same call may succeed later.
   */
  MXR_ERR_NOT_FOUND = -2,
  /**
   * The addressed device speaks a protocol older than the command needs.
   *
   * It would discard the frame without answering, so nothing was sent.
   */
  MXR_ERR_PROTOCOL_TOO_OLD = -3,
  /**
   * The client has no socket, because it was never started or was closed.
   */
  MXR_ERR_NOT_CONNECTED = -4,
  /**
   * The socket write failed, or the socket could not be opened.
   */
  MXR_ERR_IO = -5,
  /**
   * The addressee does not do what was asked of it.
   */
  MXR_ERR_UNSUPPORTED = -6,
  /**
   * The device has not reported something the request is assembled from.
   */
  MXR_ERR_NOT_REPORTED = -7,
  /**
   * A panic was caught at the boundary. The library's state is unknown.
   */
  MXR_ERR_PANIC = -8,
};
#ifndef __cplusplus
typedef int32_t mxr_result_t;
#endif // __cplusplus

/**
 * Which of a V2IP device's streams an address describes.
 */
enum mxr_stream_kind_t
#ifdef __cplusplus
  : int32_t
#endif // __cplusplus
 {
  /**
   * The video stream.
   */
  MXR_STREAM_VIDEO = 0,
  /**
   * The audio stream.
   */
  MXR_STREAM_AUDIO = 1,
  /**
   * The ancillary-data stream.
   */
  MXR_STREAM_ANC = 2,
  /**
   * The audio-return stream.
   */
  MXR_STREAM_ARC = 3,
};
#ifndef __cplusplus
typedef int32_t mxr_stream_kind_t;
#endif // __cplusplus

/**
 * A flag a device may not have reported.
 *
 * Firmware sends only what it has, so "off" and "never said" are different
 * answers and a two-valued flag would have to pick one of them for both.
 */
enum mxr_tribool_t
#ifdef __cplusplus
  : int8_t
#endif // __cplusplus
 {
  /**
   * The device has not reported this.
   */
  MXR_UNKNOWN = -1,
  /**
   * Reported, and false.
   */
  MXR_FALSE = 0,
  /**
   * Reported, and true.
   */
  MXR_TRUE = 1,
};
#ifndef __cplusplus
typedef int8_t mxr_tribool_t;
#endif // __cplusplus

/**
 * A running client. Opaque: everything about it is reached through the
 * functions below.
 */
typedef struct mxr_remote_t mxr_remote_t;

/**
 * The 16-byte identifier of a device on the network.
 *
 * All zero is the empty identifier, which is how the protocol says "no
 * device" - see `mxr_uid_is_zero()`.
 */
typedef struct {
  /**
   * The raw identifier, in wire order.
   */
  uint8_t bytes[16];
} mxr_uid_t;

/**
 * A single bay: the device it is on, and its port number there.
 */
typedef struct {
  /**
   * The device the bay belongs to.
   */
  mxr_uid_t device;
  /**
   * The bay's port number on that device.
   */
  uint16_t port;
} mxr_bay_uid_t;

/**
 * A stream's sample rate and channel count.
 */
typedef struct {
  /**
   * Sample rate in Hz.
   */
  uint32_t sample_rate;
  /**
   * Channel count.
   */
  uint8_t channels;
} mxr_audio_format_t;

/**
 * A ProAmp8 zone's gain, delay, tone and power settings.
 *
 * Gains and volume limits run 0-248 in 0.5dB steps, with 200 as 0dB. Tone and
 * EQ values are neutral at 128.
 */
typedef struct {
  /**
   * Left channel gain.
   */
  uint8_t gain_left;
  /**
   * Right channel gain.
   */
  uint8_t gain_right;
  /**
   * Lowest volume the zone may be set to.
   */
  uint8_t volume_min;
  /**
   * Highest volume the zone may be set to.
   */
  uint8_t volume_max;
  /**
   * Bass tone control.
   */
  uint8_t bass;
  /**
   * Treble tone control.
   */
  uint8_t treble;
  /**
   * 0 = normal, 1 = bridged.
   */
  uint8_t bridged;
  /**
   * Power-on mode.
   */
  uint8_t power_mode;
  /**
   * Signal level that switches the zone on automatically.
   */
  uint8_t power_level;
  /**
   * Left channel delay, in 1/48000 second increments.
   */
  uint32_t delay_left;
  /**
   * Right channel delay, in 1/48000 second increments.
   */
  uint32_t delay_right;
  /**
   * Idle time before the zone powers down, in seconds.
   */
  uint32_t power_timeout;
  /**
   * Left channel EQ, from 100Hz to 10KHz.
   */
  uint8_t eq_left[MXR_AMP_EQ_BANDS];
  /**
   * Right channel EQ, from 100Hz to 10KHz.
   */
  uint8_t eq_right[MXR_AMP_EQ_BANDS];
} mxr_amp_zone_settings_t;

/**
 * What a device is, and what it is doing.
 */
typedef struct {
  /**
   * The device's identifier.
   */
  mxr_uid_t uid;
  /**
   * The name the device advertises.
   */
  char name[MXR_NAME_LEN];
  /**
   * Serial number.
   */
  char serial[MXR_SERIAL_LEN];
  /**
   * A friendly model name, derived from the advertised name and the bays
   * the device reports.
   */
  char model[MXR_MODEL_LEN];
  /**
   * Firmware version string from the hello frame.
   */
  char version[MXR_VERSION_LEN];
  /**
   * The highest protocol version the device can decode, or zero before it
   * has said. A command above it is refused rather than sent.
   */
  uint16_t supported_protocol;
  /**
   * What the device says it can do, as `MXR_FEATURE_*` bits.
   */
  uint32_t features;
  /**
   * The address the device was last heard from, empty when never.
   */
  char address[MXR_IP_STRING_LEN];
  /**
   * Online, offline, booting or rebooting.
   */
  mxr_device_status_t status;
  /**
   * Whether the device has been heard from recently enough to count as
   * present.
   */
  bool online;
  /**
   * Whether every part of the device's configuration has arrived.
   */
  bool configuration_complete;
  /**
   * Whether the device's firmware initialises the configuration it
   * broadcasts.
   *
   * Firmware without it builds some frames over uninitialised stack, so
   * those fields carry noise rather than values: the scaling flags and,
   * behind a spuriously set valid bit, the scaling mode and refresh; bay
   * zero's addresses in the V2IP sources frame; and the padding beside the
   * remote-control target.
   */
  bool config_initialised;
  /**
   * The mesh master this device follows, zero when it is in no mesh.
   */
  mxr_uid_t mesh_master;
  /**
   * How many HDBaseT outputs this model has.
   */
  uint8_t hdbt_outputs;
  /**
   * Whether installation was marked complete.
   */
  mxr_tribool_t setup_done;
  /**
   * The installer identifier, or -1 when the device has not reported one.
   */
  int32_t installer_id;
  /**
   * Whether the device has reported a status about itself.
   */
  bool has_system_status;
  /**
   * The status code, meaningful only when `has_system_status` is set.
   */
  uint16_t system_status;
  /**
   * The status message, empty when there is none.
   */
  char system_message[MXR_MESSAGE_LEN];
  /**
   * How many temperatures `mxr_device_temperatures()` would return.
   */
  size_t temperature_count;
  /**
   * How many bays `mxr_device_bays()` would return.
   */
  size_t bay_count;
} mxr_device_info_t;

/**
 * What a bay is, and what is connected to it.
 */
typedef struct {
  /**
   * How the bay is addressed.
   */
  mxr_bay_uid_t uid;
  /**
   * The name the device gives the port, such as `Output 1`.
   */
  char port_name[MXR_NAME_LEN];
  /**
   * The name the installer gave the bay, falling back to the port name.
   */
  char user_name[MXR_NAME_LEN];
  /**
   * The bay number the device's own API and topology use, which is not the
   * port number this library addresses it by.
   */
  uint8_t bay_num;
  /**
   * What the bay is wired for, as `MXR_BAY_*` bits.
   */
  uint32_t features;
  /**
   * Whether the bay takes a signal in.
   */
  bool is_input;
  /**
   * Whether the bay puts a signal out.
   */
  bool is_output;
  /**
   * Whether the bay carries audio and no video.
   */
  bool is_audio;
  /**
   * Whether the bay can decode Dolby.
   */
  bool has_dolby;
  /**
   * Whether the bay is on this device rather than reached through the mesh.
   */
  bool is_local;
  /**
   * The bay routed to this one for video, zero when unrouted.
   */
  mxr_bay_uid_t video_source;
  /**
   * The bay routed to this one for audio, which follows the video source
   * until the bay is told otherwise. Zero when unrouted.
   */
  mxr_bay_uid_t audio_source;
  /**
   * Power state of what is connected.
   */
  mxr_power_status_t power_status;
  /**
   * Whether the bay is hidden from the installation's user interface.
   */
  mxr_tribool_t hidden;
  /**
   * Whether the device reports the bay as faulty.
   */
  mxr_tribool_t faulty;
  /**
   * Whether the bay is delivering power over the link.
   */
  mxr_tribool_t poe_powered;
  /**
   * Whether an HDBaseT link is up.
   */
  mxr_tribool_t hdbt_connected;
  /**
   * Whether a signal is present.
   */
  mxr_tribool_t signal_detected;
  /**
   * Whether hot-plug detect is asserted.
   */
  mxr_tribool_t hpd_detected;
  /**
   * Whether a CEC device answered.
   */
  mxr_tribool_t cec_detected;
  /**
   * Whether the bay's encoder is switched off.
   */
  mxr_tribool_t encoder_disabled;
  /**
   * Whether the bay's decoder is switched off.
   */
  mxr_tribool_t decoder_disabled;
  /**
   * The signal as the device describes it, empty when it has not.
   */
  char signal_type[MXR_SIGNAL_TYPE_LEN];
  /**
   * The signal format the device reports, as an `mxr_signal_type_t` value.
   */
  uint16_t signal_mode;
  /**
   * Whether audio return is active, and over which connector.
   */
  mxr_arc_status_t arc;
  /**
   * Whether the bay has reported a volume.
   */
  bool has_volume;
  /**
   * The combined left/right volume percentage.
   */
  uint8_t volume;
  /**
   * Whether either channel is muted.
   */
  mxr_tribool_t muted;
  /**
   * Whether the bay has reported a remote-control type.
   */
  bool has_rc_type;
  /**
   * The kind of remote control attached, as an `rc_target_t` value.
   */
  uint8_t rc_type;
  /**
   * Whether the bay has reported an EDID profile.
   */
  bool has_edid_profile;
  /**
   * The EDID profile the bay presents.
   */
  uint16_t edid_profile;
  /**
   * The bay this one mirrors, zero when it mirrors nothing.
   */
  mxr_bay_uid_t mirror;
  /**
   * The audio endpoint this bay feeds, or -1 on a device without them.
   */
  int16_t audio_endpoint;
  /**
   * The bay on another device this one is linked to, zero when it is
   * linked to none or that bay is not yet known.
   *
   * The link is mesh configuration, not a route: it names the bay elsewhere
   * that belongs to this one, such as the amplifier zone carrying a OneIP
   * output's volume. `volume` is already read through it, and
   * `mxr_set_volume()` already writes through it.
   */
  mxr_bay_uid_t linked_bay;
  /**
   * The source device a V2IP bay maps to, zero when it maps to none.
   */
  mxr_uid_t v2ip_uid;
  /**
   * How many devices `mxr_bay_filtered()` would return.
   */
  size_t filtered_count;
} mxr_bay_info_t;

/**
 * The signal a bay measures, beyond the description in
 * [`mxr_bay_info_t::signal_type`].
 */
typedef struct {
  /**
   * Frame rate in Hz, already corrected for a 1000/1001 clock.
   */
  double frame_rate;
  /**
   * TMDS clock rate in Hz.
   */
  uint32_t tmds_clock;
  /**
   * Video clock rate in Hz.
   */
  uint32_t clock_rate;
  /**
   * The bay status word from the report's bay block.
   */
  uint32_t status;
  /**
   * The signal type the bay is scaling to.
   */
  uint16_t scaling;
} mxr_signal_details_t;

/**
 * How a client finds the network.
 *
 * Zeroing the whole struct asks for the default: multicast discovery on
 * whichever interface the host picks, which is the right answer on a machine
 * with one network and an arbitrary one on any other.
 */
typedef struct {
  /**
   * Where to send. Null means the multicast group, or the interface's
   * broadcast address when `broadcast` is set.
   */
  const char *target_ip;
  /**
   * UDP port. Zero means the default for the selected mode.
   */
  uint16_t port;
  /**
   * Use broadcast rather than multicast.
   */
  bool broadcast;
  /**
   * Selects the interface by address, as text. Null lets the host choose.
   *
   * It decides both which interface frames leave by and which one they are
   * accepted on. Getting it wrong on a multi-homed host fails one-sidedly:
   * devices are still discovered, because their broadcasts arrive by any
   * route, while every request this client sends leaves by the wrong
   * interface and is never answered.
   */
  const char *local_ip;
  /**
   * Selects the interface by name, taking precedence over `local_ip`.
   *
   * An interface with no address of its own - a tagged VLAN - can be named
   * only this way, and only on Linux.
   */
  const char *interface;
  /**
   * The name this client advertises to devices. Null means a default.
   */
  const char *name;
  /**
   * This client's identifier, in the form `mxr_uid_to_string()` writes.
   *
   * Null loads it from `uid_path`, generating and storing one on first run.
   * It must be stable across restarts, or every peer counts each run as a
   * new client.
   *
   * `mxr_uid_to_string()`: crate::mxr_uid_to_string
   */
  const char *uid;
  /**
   * Where the identifier is kept. Null means `.mxr-uid` in the user's home
   * directory.
   */
  const char *uid_path;
} mxr_config_t;

/**
 * Names only the device the event concerns.
 */
typedef void (*mxr_device_cb)(void *userdata, mxr_uid_t device);

/**
 * Names only the bay the event concerns.
 */
typedef void (*mxr_bay_cb)(void *userdata, mxr_bay_uid_t bay);

/**
 * Names a device and a flag.
 */
typedef void (*mxr_device_bool_cb)(void *userdata, mxr_uid_t device, bool value);

/**
 * Names a device, a status code and a message.
 */
typedef void (*mxr_system_status_cb)(void *userdata,
                                     mxr_uid_t device,
                                     uint16_t status,
                                     const char *message);

/**
 * Names a device and a second device.
 */
typedef void (*mxr_device_uid_cb)(void *userdata, mxr_uid_t device, mxr_uid_t other);

/**
 * Names a device and a 16-bit value.
 */
typedef void (*mxr_device_u16_cb)(void *userdata, mxr_uid_t device, uint16_t value);

/**
 * A command addressed to a multiviewer.
 *
 * The parameters are raw: the opcode belongs to the multiviewer module rather
 * than to MatrixOS, so there is no firmware source here to pin per-sub-command
 * field semantics against.
 */
typedef struct {
  /**
   * The multiviewer being addressed.
   */
  mxr_uid_t target;
  /**
   * The sub-opcode. A value this library has no name for still arrives.
   */
  uint8_t op;
  /**
   * Everything after the envelope, borrowed for the call.
   */
  const uint8_t *params;
  /**
   * Length of `params`.
   */
  size_t params_len;
} mxr_multiviewer_command_t;

/**
 * Carries a multiviewer command.
 */
typedef void (*mxr_multiviewer_command_cb)(void *userdata,
                                           mxr_uid_t device,
                                           const mxr_multiviewer_command_t *command);

/**
 * Which source endpoint an audio sink endpoint was switched to.
 */
typedef struct {
  /**
   * The device whose endpoint is being listened to.
   */
  mxr_uid_t source_uid;
  /**
   * The endpoint being listened to.
   */
  uint16_t source_id;
  /**
   * The device doing the listening.
   */
  mxr_uid_t target_uid;
  /**
   * The endpoint doing the listening.
   */
  uint16_t target_id;
} mxr_audio_change_source_t;

/**
 * Carries an audio input selection.
 */
typedef void (*mxr_audio_select_cb)(void *userdata,
                                    mxr_uid_t device,
                                    const mxr_audio_change_source_t *change);

/**
 * Names a device, one of its audio endpoints, and a flag.
 */
typedef void (*mxr_endpoint_bool_cb)(void *userdata, mxr_uid_t device, uint16_t endpoint, bool value);

/**
 * Names a device, one of its audio endpoints, and a 32-bit value.
 */
typedef void (*mxr_endpoint_u32_cb)(void *userdata,
                                    mxr_uid_t device,
                                    uint16_t endpoint,
                                    uint32_t value);

/**
 * Asks a device, addressed by serial, to switch a sink.
 */
typedef struct {
  /**
   * Serial of the device to act on, borrowed for the call.
   */
  const char *serial;
  /**
   * Output bay to switch.
   */
  uint16_t sink_bay;
  /**
   * Source bay to switch it to.
   */
  uint16_t source_bay;
  /**
   * Whether to skip the power-on commands that normally accompany a switch.
   */
  bool no_power_on;
  /**
   * Set when the request routes audio only.
   */
  bool audio_only;
} mxr_set_route_request_t;

/**
 * Carries a request addressed to a device.
 */
typedef void (*mxr_set_route_cb)(void *userdata,
                                 mxr_uid_t device,
                                 const mxr_set_route_request_t *request);

/**
 * Asks one device for its EDID.
 */
typedef struct {
  /**
   * The device being asked.
   */
  mxr_uid_t target;
  /**
   * Whether the sink's EDID is wanted rather than the source's.
   */
  bool output;
} mxr_edid_request_t;

/**
 * Carries a request for a device's EDID.
 */
typedef void (*mxr_edid_request_cb)(void *userdata,
                                    mxr_uid_t device,
                                    const mxr_edid_request_t *request);

/**
 * One EDID block from a device's reply.
 */
typedef struct {
  /**
   * True for a sink's EDID, false for a source's.
   */
  bool output;
  /**
   * A base block plus one extension block, borrowed for the call.
   */
  const uint8_t *data;
  /**
   * Length of `data`, normally 256.
   */
  size_t data_len;
} mxr_edid_record_t;

/**
 * Carries one EDID block a device replied with.
 */
typedef void (*mxr_edid_record_cb)(void *userdata, mxr_uid_t device, const mxr_edid_record_t *record);

/**
 * Asks a device to rename one of its bays.
 */
typedef struct {
  /**
   * The device to act on.
   */
  mxr_uid_t target;
  /**
   * The bay to rename.
   */
  uint16_t port;
  /**
   * The new name, borrowed for the call.
   */
  const char *name;
} mxr_bay_name_change_t;

/**
 * Carries a request to rename a bay.
 */
typedef void (*mxr_bay_name_change_cb)(void *userdata,
                                       mxr_uid_t device,
                                       const mxr_bay_name_change_t *change);

/**
 * Asks a device to switch its input EDID profile.
 */
typedef struct {
  /**
   * The device to act on.
   */
  mxr_uid_t target;
  /**
   * The profile to switch to.
   */
  uint16_t profile;
} mxr_edid_profile_change_t;

/**
 * Carries a request to switch an EDID profile.
 */
typedef void (*mxr_edid_profile_change_cb)(void *userdata,
                                           mxr_uid_t device,
                                           const mxr_edid_profile_change_t *change);

/**
 * Asks peers to factory-reset.
 */
typedef struct {
  /**
   * Set by the broadcast form, which targets every peer.
   */
  bool all;
  /**
   * The single device addressed, zero when `all` is set or when the request
   * addresses only its sender.
   */
  mxr_uid_t target;
} mxr_factory_reset_request_t;

/**
 * Carries a factory-reset request.
 */
typedef void (*mxr_factory_reset_cb)(void *userdata,
                                     mxr_uid_t device,
                                     const mxr_factory_reset_request_t *request);

/**
 * Asks a sink to enter or leave power save.
 */
typedef struct {
  /**
   * The sink to act on, zero on the broadcast form.
   */
  mxr_uid_t target;
  /**
   * Whether power save is being entered.
   */
  bool enabled;
} mxr_power_save_request_t;

/**
 * Carries a power-save request.
 */
typedef void (*mxr_power_save_cb)(void *userdata,
                                  mxr_uid_t device,
                                  const mxr_power_save_request_t *request);

/**
 * Asks one device to send a remote-control key on a bay.
 */
typedef struct {
  /**
   * The device to act on.
   */
  mxr_uid_t target;
  /**
   * Bay in the target's own numbering, which is not a port number.
   */
  uint16_t local_bay;
  /**
   * The key to send.
   */
  uint16_t key;
} mxr_key_transmit_request_t;

/**
 * Carries a request to send a remote-control key.
 */
typedef void (*mxr_key_transmit_cb)(void *userdata,
                                    mxr_uid_t device,
                                    const mxr_key_transmit_request_t *request);

/**
 * Asks one device to perform a remote-control action.
 */
typedef struct {
  /**
   * The device to act on.
   */
  mxr_uid_t target;
  /**
   * Bay in the target's own numbering, which is not a port number.
   */
  uint16_t local_bay;
  /**
   * The action to perform.
   */
  uint16_t action;
} mxr_action_transmit_request_t;

/**
 * Carries a request to perform a remote-control action.
 */
typedef void (*mxr_action_transmit_cb)(void *userdata,
                                       mxr_uid_t device,
                                       const mxr_action_transmit_request_t *request);

/**
 * The metadata shared by the raw-IR capture and transmit frames.
 */
typedef struct {
  /**
   * Tick length of the timing values.
   */
  uint16_t timer_resolution;
  /**
   * Carrier frequency in Hz.
   */
  uint16_t frequency;
  /**
   * Number of timing values that follow.
   */
  uint16_t nb_timings;
  /**
   * Index at which the repeat section starts.
   */
  uint16_t repeat_offset;
  /**
   * Capture status.
   */
  uint8_t status;
} mxr_ir_meta_t;

/**
 * Asks one device to blast raw IR on one of its local bays.
 */
typedef struct {
  /**
   * The device to act on.
   */
  mxr_uid_t target;
  /**
   * Bay mode in the target's own numbering, which is not a port number.
   */
  uint8_t local_mode;
  /**
   * Bay number in the target's own numbering, which is not a port number.
   */
  uint8_t local_bay;
  /**
   * Sender clock at send time.
   */
  uint32_t timestamp;
  /**
   * Metadata for the timings.
   */
  mxr_ir_meta_t meta;
  /**
   * The raw on/off timing blob, borrowed for the call.
   */
  const uint8_t *timings;
  /**
   * Length of `timings`.
   */
  size_t timings_len;
} mxr_ir_transmit_request_t;

/**
 * Carries a request to blast raw infrared.
 */
typedef void (*mxr_ir_transmit_cb)(void *userdata,
                                   mxr_uid_t device,
                                   const mxr_ir_transmit_request_t *request);

/**
 * Registers or unregisters a device on the source blacklist.
 */
typedef struct {
  /**
   * The device being listed.
   */
  mxr_uid_t target;
  /**
   * Whether it is being registered rather than removed.
   */
  bool registered;
} mxr_blacklist_change_t;

/**
 * Carries a blacklist change.
 */
typedef void (*mxr_blacklist_cb)(void *userdata,
                                 mxr_uid_t device,
                                 const mxr_blacklist_change_t *change);

/**
 * Asks one sink to crop its source to a wall window.
 *
 * The window replaces the sink's outright: a zero width or height is the wire
 * spelling of "clear the wall and show the full frame", not of "unset". A
 * revert carries no window, and the geometry in it means nothing.
 */
typedef struct {
  /**
   * The sink to act on.
   */
  mxr_uid_t target;
  /**
   * Window origin, horizontal.
   */
  uint16_t pos_x;
  /**
   * Window origin, vertical.
   */
  uint16_t pos_y;
  /**
   * Window width.
   */
  uint16_t width;
  /**
   * Window height.
   */
  uint16_t height;
  /**
   * Active picture width the window was authored against.
   */
  uint16_t raster_w;
  /**
   * Active picture height the window was authored against.
   */
  uint16_t raster_h;
  /**
   * 0 preview, 1 store, 2 revert.
   */
  uint8_t op;
} mxr_video_wall_command_t;

/**
 * Carries a video wall command.
 */
typedef void (*mxr_video_wall_cb)(void *userdata,
                                  mxr_uid_t device,
                                  const mxr_video_wall_command_t *command);

/**
 * Names a bay and another bay, the zero device standing for none.
 */
typedef void (*mxr_bay_bay_cb)(void *userdata, mxr_bay_uid_t bay, mxr_bay_uid_t other);

/**
 * Names a bay, its combined volume percentage and its mute state.
 */
typedef void (*mxr_volume_cb)(void *userdata, mxr_bay_uid_t bay, uint8_t volume, mxr_tribool_t muted);

/**
 * Names a bay and the power state of what is connected to it.
 */
typedef void (*mxr_power_cb)(void *userdata, mxr_bay_uid_t bay, mxr_power_status_t power);

/**
 * Names a bay and a string, borrowed for the call.
 */
typedef void (*mxr_bay_str_cb)(void *userdata, mxr_bay_uid_t bay, const char *value);

/**
 * Names a bay and a flag.
 */
typedef void (*mxr_bay_bool_cb)(void *userdata, mxr_bay_uid_t bay, bool value);

/**
 * Names a bay and its audio return channel.
 */
typedef void (*mxr_arc_cb)(void *userdata, mxr_bay_uid_t bay, mxr_arc_status_t arc);

/**
 * Names a bay and a 16-bit value.
 */
typedef void (*mxr_bay_u16_cb)(void *userdata, mxr_bay_uid_t bay, uint16_t value);

/**
 * Names a bay and an 8-bit value.
 */
typedef void (*mxr_bay_u8_cb)(void *userdata, mxr_bay_uid_t bay, uint8_t value);

/**
 * Raw IR captured on a bay of the sending device.
 */
typedef struct {
  /**
   * Sender clock at capture time.
   */
  uint32_t timestamp;
  /**
   * Sender clock at the last signal change.
   */
  uint32_t last_change;
  /**
   * Metadata for the timings.
   */
  mxr_ir_meta_t meta;
  /**
   * The raw on/off timing blob, borrowed for the call.
   */
  const uint8_t *timings;
  /**
   * Length of `timings`.
   */
  size_t timings_len;
} mxr_ir_capture_t;

/**
 * Carries raw infrared captured on a bay.
 */
typedef void (*mxr_ir_capture_cb)(void *userdata, mxr_bay_uid_t bay, const mxr_ir_capture_t *capture);

/**
 * Names a bay and the link that was made to it.
 */
typedef void (*mxr_bay_linked_cb)(void *userdata,
                                  mxr_bay_uid_t bay,
                                  const char *linked_serial,
                                  const char *bay_name,
                                  uint32_t features);

/**
 * Names a bay and the link that was removed from it.
 */
typedef void (*mxr_bay_unlinked_cb)(void *userdata,
                                    mxr_bay_uid_t bay,
                                    const char *linked_serial,
                                    const char *bay_name);

/**
 * What to call when something happens.
 *
 * Zero the whole struct and fill in only what is wanted: a null member drops
 * its event. `userdata` is whatever was passed to
 * `mxr_remote_new()` and is never examined here.
 */
typedef struct {
  /**
   * Fires after every device-level event below.
   */
  mxr_device_cb on_device_update;
  /**
   * Fires after every bay-level event below.
   */
  mxr_bay_cb on_bay_update;
  /**
   * The device's configuration changed.
   */
  mxr_device_cb on_device_config_changed;
  /**
   * The device has reported every part of its configuration.
   */
  mxr_device_cb on_device_config_complete;
  /**
   * The device started or stopped answering.
   */
  mxr_device_bool_cb on_device_online_changed;
  /**
   * The device reported new temperatures; read them with
   * `mxr_device_temperatures()`.
   */
  mxr_device_cb on_device_temperature_changed;
  /**
   * A firmware component reported its version; read it with
   * `mxr_device_firmware()`.
   */
  mxr_device_cb on_firmware_version_changed;
  /**
   * The device reported a status about itself.
   */
  mxr_system_status_cb on_system_status_changed;
  /**
   * A network port reported its link state; read it with
   * `mxr_network_status()`.
   */
  mxr_device_cb on_network_status_changed;
  /**
   * The device reported V2IP statistics; read them with
   * `mxr_v2ip_stats()`.
   */
  mxr_device_cb on_v2ip_stats_changed;
  /**
   * The streams the device's source bays advertise changed; read them with
   * `mxr_v2ip_sources()`.
   */
  mxr_device_cb on_v2ip_sources_changed;
  /**
   * The device's V2IP encoder configuration changed; read it with
   * `mxr_v2ip_details()`.
   */
  mxr_device_cb on_v2ip_details_changed;
  /**
   * The streams the device's sink is subscribed to changed; read them with
   * `mxr_v2ip_sink()`.
   */
  mxr_device_cb on_v2ip_sink_changed;
  /**
   * A multiviewer reported its state; read it with
   * `mxr_multiviewer_status()`.
   */
  mxr_device_cb on_multiviewer_status_changed;
  /**
   * The device reported its audio endpoint tree; read it with
   * `mxr_audio_endpoints()`.
   */
  mxr_device_cb on_audio_endpoints_changed;
  /**
   * The device reported its mesh master.
   */
  mxr_device_uid_cb on_mesh_master_changed;
  /**
   * The device reported its view of the mesh topology; read it with
   * `mxr_topology()`.
   */
  mxr_device_cb on_topology_changed;
  /**
   * A ProAmp8 reported its Dolby settings; read them with
   * `mxr_dolby_settings()`.
   */
  mxr_device_cb on_amp_dolby_settings_changed;
  /**
   * A PDU reported its electrical state; read it with
   * `mxr_pdu_state()`.
   */
  mxr_device_cb on_pdu_state_changed;
  /**
   * Installer setup was completed or cleared.
   */
  mxr_device_bool_cb on_setup_status_changed;
  /**
   * The installer identifier changed.
   */
  mxr_device_u16_cb on_installer_id_changed;
  /**
   * The sink was told to show a window; read it with
   * `mxr_v2ip_tiling()`.
   */
  mxr_device_cb on_tiling_changed;
  /**
   * A source bay's remote-control configuration changed; read it with
   * `mxr_rc_settings()`.
   */
  mxr_device_cb on_rc_settings_changed;
  /**
   * A V2IP device was linked to a remote peer.
   */
  mxr_device_uid_cb on_v2ip_link_changed;
  /**
   * A multiviewer command arrived.
   */
  mxr_multiviewer_command_cb on_multiviewer_command;
  /**
   * An audio endpoint was switched to a new source.
   */
  mxr_audio_select_cb on_audio_select_input;
  /**
   * An audio endpoint was muted or unmuted.
   */
  mxr_endpoint_bool_cb on_audio_endpoint_mute;
  /**
   * An audio endpoint's trigger changed.
   */
  mxr_endpoint_bool_cb on_audio_endpoint_trigger;
  /**
   * An audio endpoint's volume changed.
   */
  mxr_endpoint_u32_cb on_audio_endpoint_volume;
  /**
   * A peer asked every device to announce itself.
   */
  mxr_device_cb on_discover_request;
  /**
   * A peer asked a device to switch a sink.
   */
  mxr_set_route_cb on_set_route_requested;
  /**
   * A peer asked a device for its EDID.
   */
  mxr_edid_request_cb on_edid_requested;
  /**
   * A device answered with its EDID.
   */
  mxr_edid_record_cb on_edid_received;
  /**
   * A peer asked a device to rename a bay.
   */
  mxr_bay_name_change_cb on_bay_name_change_requested;
  /**
   * A peer asked a device to switch its EDID profile.
   */
  mxr_edid_profile_change_cb on_edid_profile_change_requested;
  /**
   * A peer asked a device to reboot. The second identifier is the device
   * being asked, which is not always the sender.
   */
  mxr_device_uid_cb on_reboot_requested;
  /**
   * A peer asked devices to factory-reset.
   */
  mxr_factory_reset_cb on_factory_reset_requested;
  /**
   * A device sent its monitoring pulse.
   */
  mxr_device_cb on_monitoring_pulse;
  /**
   * A peer asked a device to upgrade its FPGA.
   */
  mxr_device_cb on_upgrade_fpga_requested;
  /**
   * A peer asked a device to re-detect its bays.
   */
  mxr_device_cb on_detect_bays_requested;
  /**
   * A peer asked a sink to enter or leave power save.
   */
  mxr_power_save_cb on_power_save_requested;
  /**
   * A peer asked a device to send a remote-control key.
   */
  mxr_key_transmit_cb on_key_transmit_requested;
  /**
   * A peer asked a device to perform a remote-control action.
   */
  mxr_action_transmit_cb on_action_transmit_requested;
  /**
   * A peer asked a device to blast raw infrared.
   */
  mxr_ir_transmit_cb on_ir_transmit_requested;
  /**
   * A device was added to or removed from the source blacklist.
   */
  mxr_blacklist_cb on_blacklist_changed;
  /**
   * A video wall command arrived.
   */
  mxr_video_wall_cb on_video_wall_command;
  /**
   * A bay was seen for the first time.
   */
  mxr_bay_cb on_bay_registered;
  /**
   * The bay's routed video source changed, zero when it was unrouted.
   */
  mxr_bay_bay_cb on_video_source_changed;
  /**
   * The bay's routed audio source changed, zero when it was unrouted.
   */
  mxr_bay_bay_cb on_audio_source_changed;
  /**
   * The bay's volume or mute state changed.
   */
  mxr_volume_cb on_volume_changed;
  /**
   * The attached device's power state changed.
   */
  mxr_power_cb on_power_changed;
  /**
   * The bay was renamed.
   */
  mxr_bay_str_cb on_name_changed;
  /**
   * A signal appeared or disappeared.
   */
  mxr_bay_bool_cb on_signal_detected_changed;
  /**
   * The bay started or stopped reporting a fault.
   */
  mxr_bay_bool_cb on_faulty_changed;
  /**
   * The bay was hidden or shown.
   */
  mxr_bay_bool_cb on_hidden_changed;
  /**
   * Power over Ethernet started or stopped supplying the bay.
   */
  mxr_bay_bool_cb on_poe_powered_changed;
  /**
   * The HDBaseT link came up or went down.
   */
  mxr_bay_bool_cb on_hdbt_connected_changed;
  /**
   * The signal format description changed.
   */
  mxr_bay_str_cb on_signal_type_changed;
  /**
   * Hot-plug detect was asserted or released.
   */
  mxr_bay_bool_cb on_hpd_detected_changed;
  /**
   * A CEC device answered or stopped answering.
   */
  mxr_bay_bool_cb on_cec_detected_changed;
  /**
   * The audio return channel changed.
   */
  mxr_arc_cb on_arc_changed;
  /**
   * The input's EDID profile changed.
   */
  mxr_bay_u16_cb on_edid_profile_changed;
  /**
   * The input's remote-control type changed.
   */
  mxr_bay_u8_cb on_rc_type_changed;
  /**
   * A remote-control key was pressed on the bay.
   */
  mxr_bay_u16_cb on_key_pressed;
  /**
   * A remote-control action was received on the bay.
   */
  mxr_bay_u16_cb on_action_received;
  /**
   * The bay started or stopped mirroring another output, zero when it
   * stopped.
   */
  mxr_bay_bay_cb on_mirror_status_changed;
  /**
   * A ProAmp8 zone's settings changed; read them with
   * `mxr_bay_amp_settings()`.
   */
  mxr_bay_cb on_amp_zone_settings_changed;
  /**
   * A volume step was requested on the bay.
   */
  mxr_bay_bool_cb on_volume_step;
  /**
   * The bay detected audio clipping, at the reported level.
   */
  mxr_bay_u8_cb on_audio_clip;
  /**
   * Raw infrared was captured on the bay.
   */
  mxr_ir_capture_cb on_ir_captured;
  /**
   * The devices filtered out of this sink's picker changed; read them with
   * `mxr_bay_filtered()`.
   */
  mxr_bay_cb on_filtered_devices_changed;
  /**
   * The audio endpoint the bay carries changed.
   */
  mxr_bay_u8_cb on_audio_endpoint_changed;
  /**
   * The bay's V2IP encoder was enabled or disabled.
   */
  mxr_bay_bool_cb on_encoder_disabled_changed;
  /**
   * The bay's V2IP decoder was enabled or disabled.
   */
  mxr_bay_bool_cb on_decoder_disabled_changed;
  /**
   * The bay was linked to a bay on another device. Both ends are told, so
   * both fire: `bay_name` names the bay whose link record changed, which is
   * this bay on the device that reported the change and the far bay on its
   * peer.
   */
  mxr_bay_linked_cb on_bay_linked;
  /**
   * The bay's link to another device was removed. The arguments describe
   * the link that went, and mean what they do on `on_bay_linked`.
   */
  mxr_bay_unlinked_cb on_bay_unlinked;
} mxr_callbacks_t;

/**
 * Transmitter stream statistics.
 */
typedef struct {
  /**
   * Video packets sent.
   */
  uint32_t video;
  /**
   * Audio packets sent.
   */
  uint32_t audio;
  /**
   * Ancillary-data packets sent.
   */
  uint32_t anc;
  /**
   * Times the stream went down.
   */
  uint32_t stream_down;
  /**
   * Transmit overflows.
   */
  uint32_t overflow;
} mxr_v2ip_tx_stats_t;

/**
 * Receiver stream statistics.
 */
typedef struct {
  /**
   * Video packets received.
   */
  uint32_t video_total;
  /**
   * Video packets dropped.
   */
  uint32_t video_dropped;
  /**
   * Video sequence errors.
   */
  uint32_t video_seq_errors;
  /**
   * Watchdog timeouts.
   */
  uint32_t wdt_timeout;
  /**
   * Audio packets received.
   */
  uint32_t audio_total;
  /**
   * Audio packets dropped.
   */
  uint32_t audio_dropped;
  /**
   * Audio sequence errors.
   */
  uint32_t audio_seq_errors;
  /**
   * Ancillary-data packets received.
   */
  uint32_t anc_total;
  /**
   * Ancillary-data packets dropped.
   */
  uint32_t anc_dropped;
  /**
   * Ancillary-data sequence errors.
   */
  uint32_t anc_seq_errors;
  /**
   * The decoder's health state: 0 unknown, 1 healthy, 2 bad, 3 starting.
   *
   * Only healthy and bad are verdicts. Reading failure as "not healthy"
   * counts a decoder that is merely coming up as one that failed, which is
   * what every sink reports for a moment after a route change.
   */
  uint8_t decoder_state;
} mxr_v2ip_rx_stats_t;

/**
 * A device's V2IP statistics, cumulative and over the last minute.
 */
typedef struct {
  /**
   * Transmit totals since boot.
   */
  mxr_v2ip_tx_stats_t tx;
  /**
   * Transmit counts over the last minute.
   */
  mxr_v2ip_tx_stats_t tx_per_minute;
  /**
   * Receive totals since boot.
   */
  mxr_v2ip_rx_stats_t rx;
  /**
   * Receive counts over the last minute.
   */
  mxr_v2ip_rx_stats_t rx_per_minute;
} mxr_v2ip_stats_t;

/**
 * One multicast stream address.
 */
typedef struct {
  /**
   * Which stream this address is for.
   */
  mxr_stream_kind_t kind;
  /**
   * The multicast group, as a dotted quad.
   */
  char ip[MXR_IP_STRING_LEN];
  /**
   * The destination UDP port.
   */
  uint16_t port;
  /**
   * Whether this carries a usable address: a multicast group and a non-zero
   * port, both. A slot a device has not filled in is not an error, so this
   * is what separates an address from an empty slot.
   */
  bool valid;
} mxr_stream_source_t;

/**
 * A V2IP device's own encoder configuration.
 */
typedef struct {
  /**
   * The video stream this device sources.
   */
  mxr_stream_source_t video;
  /**
   * The audio stream this device sources.
   */
  mxr_stream_source_t audio;
  /**
   * The ancillary-data stream this device sources.
   */
  mxr_stream_source_t anc;
  /**
   * The audio-return stream this device sources.
   */
  mxr_stream_source_t arc;
  /**
   * Encoder rate in units of 10Mb/s, or -1 when no rate has been reported.
   */
  int16_t tx_rate;
  /**
   * DSCP marking for the video stream, or -1 when unmarked.
   */
  int16_t dscp_video;
  /**
   * DSCP marking for the audio stream, or -1 when unmarked.
   */
  int16_t dscp_audio;
  /**
   * DSCP marking for the ancillary-data stream, or -1 when unmarked.
   */
  int16_t dscp_anc;
  /**
   * The signal type the output scales to.
   */
  uint16_t scaling_mode;
  /**
   * Refresh rate in Hz.
   */
  uint16_t scaling_refresh;
  /**
   * `MXR_SCALING_FLAG_*` bits. Bits outside those are undefined and are not
   * reliably zero: firmware predating the fix builds this frame over an
   * uninitialised stack local.
   */
  uint8_t scaling_flags;
} mxr_v2ip_details_t;

/**
 * The streams one V2IP source advertises.
 */
typedef struct {
  /**
   * The originating device, zero when it is not known.
   */
  mxr_uid_t uid;
  /**
   * The video stream.
   */
  mxr_stream_source_t video;
  /**
   * The audio stream.
   */
  mxr_stream_source_t audio;
  /**
   * The ancillary-data stream.
   */
  mxr_stream_source_t anc;
  /**
   * Whether an audio-return stream is advertised.
   */
  bool has_arc;
  /**
   * The audio-return stream, meaningful only when `has_arc` is set.
   */
  mxr_stream_source_t arc;
} mxr_stream_sources_t;

/**
 * The streams a V2IP sink is subscribed to.
 */
typedef struct {
  /**
   * The streams the sink subscribes to.
   */
  mxr_stream_sources_t addresses;
  /**
   * Whether the sender reported a resolved audio format.
   */
  bool has_audio_format;
  /**
   * The audio format, meaningful only when `has_audio_format` is set.
   */
  mxr_audio_format_t audio_format;
} mxr_v2ip_sink_t;

/**
 * The window a sink is currently told to show.
 *
 * This is the pollable view of a sink's window, not the persisted video wall
 * setting: on a sink running the wall module a write here is transient,
 * because that module pushes its own target window back within about a
 * second.
 */
typedef struct {
  /**
   * The sink this window belongs to.
   */
  mxr_uid_t target;
  /**
   * Window origin, horizontal.
   */
  uint16_t pos_x;
  /**
   * Window origin, vertical.
   */
  uint16_t pos_y;
  /**
   * Window width.
   */
  uint16_t width;
  /**
   * Window height.
   */
  uint16_t height;
} mxr_tiling_config_t;

/**
 * What a multiviewer reports about itself.
 */
typedef struct {
  /**
   * The multiviewer.
   */
  mxr_uid_t uid;
  /**
   * The source device mapped to each input.
   */
  mxr_uid_t mappings[MXR_MULTIVIEWER_INPUTS];
  /**
   * The MCU firmware version.
   */
  char mcu_version[MXR_NAME_LEN];
  /**
   * The scaler firmware version.
   */
  char scaler_version[MXR_NAME_LEN];
  /**
   * The view mode the hardware reports, which is its own numbering rather
   * than `view_mode`'s.
   */
  uint8_t hw_view_mode;
  /**
   * The window layout.
   */
  uint8_t view_mode;
  /**
   * Which corner the picture-in-picture window sits in.
   */
  uint8_t pip_position;
  /**
   * The size of the picture-in-picture window.
   */
  uint8_t pip_size;
  /**
   * The output resolution.
   */
  uint8_t output_mode;
  /**
   * The HDCP mode.
   */
  uint8_t hdcp_mode;
  /**
   * The IT content flag.
   */
  uint8_t output_itc;
  /**
   * The EDID presented to sources.
   */
  uint8_t edid_template;
  /**
   * How a source is fitted into its window.
   */
  uint8_t aspect_ratio;
  /**
   * Whether automatic source switching is on.
   */
  uint8_t auto_switch;
  /**
   * Which window the audio is taken from.
   */
  uint8_t audio_source;
  /**
   * Whether a volume has been reported.
   */
  bool has_audio_volume;
  /**
   * The output volume.
   */
  uint8_t audio_volume;
  /**
   * Whether the output is muted.
   */
  uint8_t audio_muted;
  /**
   * The source shown in each window.
   */
  uint8_t video_sources[MXR_MULTIVIEWER_INPUTS];
  /**
   * Which window remote control is forwarded to.
   */
  uint8_t remote_control;
} mxr_multiviewer_status_t;

/**
 * A ProAmp8's Dolby settings.
 */
typedef struct {
  /**
   * 0 = standard, 1 = 3-zone Dolby, 2 = 4-zone Dolby.
   */
  uint8_t mode;
  /**
   * Whether PCM is up-mixed to 5.1 rather than passed through.
   */
  bool pcm_upmix;
  /**
   * Whether a Dolby stream was detected.
   */
  bool dolby_detected;
  /**
   * Whether up-mixing is currently running.
   */
  bool pcm_upmix_active;
} mxr_dolby_settings_t;

/**
 * The electrical state a PDU reports.
 */
typedef struct {
  /**
   * Current in amperes.
   */
  double current;
  /**
   * Voltage in volts.
   */
  double voltage;
  /**
   * Real power in watts.
   */
  double power;
  /**
   * Dissipation in watts.
   */
  double dissipation;
  /**
   * Mains frequency in Hz.
   */
  double frequency;
  /**
   * Per-outlet state.
   */
  uint8_t outlets[MXR_PDU_OUTLETS];
} mxr_pdu_state_t;

/**
 * The remote-control configuration of a source bay.
 */
typedef struct {
  /**
   * The device this configuration belongs to.
   */
  mxr_uid_t target;
  /**
   * The control method, as an `rc_target_t` value.
   */
  uint8_t rc_target;
  /**
   * The control target's address, empty when unset.
   */
  char ip[MXR_IP_STRING_LEN];
  /**
   * Whether CEC is enabled.
   */
  bool cec_enabled;
  /**
   * Whether CEC powers the sink on automatically.
   */
  bool cec_auto_on;
  /**
   * Whether remote-control commands are forwarded.
   */
  bool forward_rc;
  /**
   * Whether infrared is forwarded.
   */
  bool forward_ir;
  /**
   * The driver state on the source, as an `mxr_rc_status_t` value. One
   * above the last this library knows is passed through as it arrived.
   */
  uint8_t rc_status;
  /**
   * The driver-reported status string, empty when unknown.
   */
  char status_name[MXR_NAME_LEN];
} mxr_rc_settings_t;

/**
 * The diagnostic result for one UTP cable pair.
 */
typedef struct {
  /**
   * Whether the pair is wired with normal polarity.
   */
  bool polarity;
  /**
   * Which pair this describes.
   */
  uint8_t pair;
  /**
   * Measured skew.
   */
  uint32_t skew;
  /**
   * Measured length.
   */
  uint32_t length;
} mxr_cable_status_t;

/**
 * The link state and diagnostics of one network port.
 */
typedef struct {
  /**
   * Port number.
   */
  uint16_t port;
  /**
   * Port name.
   */
  char name[MXR_NAME_LEN];
  /**
   * Negotiated link speed.
   */
  uint8_t link_speed;
  /**
   * Whether the link negotiated full duplex.
   */
  bool link_full_duplex;
  /**
   * The port's own address, empty when it has not reported one.
   */
  char ip[MXR_IP_STRING_LEN];
  /**
   * The IGMP querier the port sees, empty when it sees none.
   */
  char querier[MXR_IP_STRING_LEN];
  /**
   * Whether the port reported a hardware address.
   */
  bool has_mac_address;
  /**
   * The hardware address, meaningful only when `has_mac_address` is set.
   */
  uint8_t mac_address[6];
  /**
   * Whether the port reported link errors.
   */
  bool has_errors;
  /**
   * Input errors.
   */
  bool in_error;
  /**
   * Input frame check errors.
   */
  bool in_fcs_error;
  /**
   * Input collisions.
   */
  bool in_collision;
  /**
   * Deferred transmissions.
   */
  bool out_deferred;
  /**
   * Excessive transmissions.
   */
  bool out_excessive;
  /**
   * Polarity errors.
   */
  bool polarity_error;
  /**
   * Skew warning.
   */
  bool skew_warning;
  /**
   * Length warning.
   */
  bool length_warning;
  /**
   * Whether the port reported a virtual cable test.
   */
  bool has_vct_status;
  /**
   * Whether each pair raised a warning, meaningful only when
   * `has_vct_status` is set.
   */
  bool vct_warning[MXR_UTP_PAIRS];
  /**
   * How many entries of `cable_status` the port filled in.
   */
  size_t cable_status_count;
  /**
   * Cable diagnostics per pair.
   */
  mxr_cable_status_t cable_status[MXR_UTP_PAIRS];
} mxr_network_port_t;

/**
 * One device in a topology report.
 */
typedef struct {
  /**
   * The device this entry describes.
   */
  mxr_uid_t uid;
  /**
   * Bitmask of the devices it is connected to.
   */
  uint32_t mask;
} mxr_topology_entry_t;

/**
 * One firmware component a device reports.
 */
typedef struct {
  /**
   * Which component this describes.
   */
  uint8_t firmware_type;
  /**
   * Build timestamp, in seconds since the Unix epoch.
   */
  uint32_t timestamp;
  /**
   * Source revision hash.
   */
  uint32_t hash;
  /**
   * Human-readable version string.
   */
  char version[MXR_VERSION_LEN];
} mxr_firmware_version_t;

/**
 * One node of a device's audio tree.
 */
typedef struct {
  /**
   * The endpoint's identifier on its device.
   */
  uint8_t id;
  /**
   * What the endpoint can do, as `MXR_AUDIO_*` bits.
   */
  uint32_t features;
  /**
   * Whether the endpoint carries a stream address.
   */
  bool has_address;
  /**
   * The stream address, meaningful only when `has_address` is set.
   */
  mxr_stream_source_t address;
  /**
   * The endpoint this one hangs off, or -1 at a root.
   */
  int16_t parent;
  /**
   * How many children this endpoint has; read them with
   * `mxr_audio_endpoint_children()`.
   */
  size_t child_count;
  /**
   * Whether the device reported which inputs are selectable.
   */
  bool has_inputs_available;
  /**
   * Bitmask of the endpoints this one may be switched to.
   */
  uint32_t inputs_available;
  /**
   * Whether the device reported which input is selected.
   */
  bool has_inputs_routed;
  /**
   * Bitmask of the endpoint this one is listening to.
   */
  uint32_t inputs_routed;
  /**
   * The device at the other end of the link, zero when unlinked.
   */
  mxr_uid_t linked_device;
  /**
   * The endpoint at the other end of the link, or -1 when unlinked.
   */
  int16_t linked_endpoint;
} mxr_audio_endpoint_t;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * This library's version, as `MAJOR.MINOR.PATCH`.
 *
 * The returned pointer is static and always valid.
 */
const char *mxr_version(void);

/**
 * Why the last call on this thread failed, or an empty string.
 *
 * The text is owned by the library and is replaced by the next failure on
 * this thread, so a caller that keeps it copies it first. It describes the
 * failure; the result code classifies it, and only the code should be
 * branched on.
 *
 * Never returns null.
 */
const char *mxr_last_error(void);

/**
 * Reports whether `uid` is the empty identifier.
 *
 * The protocol uses it wherever a device could be named and is not, so this
 * is the test for "no device" rather than a comparison against a constant.
 */
bool mxr_uid_is_zero(mxr_uid_t uid);

/**
 * Writes `uid` as dotted hex into `out`, which needs
 * [`MXR_UID_STRING_LEN`] bytes.
 *
 * # Safety
 *
 * `out` points at `cap` writable bytes.
 */
mxr_result_t mxr_uid_to_string(mxr_uid_t uid, char *out, size_t cap);

/**
 * Reads the dotted-hex form `mxr_uid_to_string()` writes.
 *
 * # Safety
 *
 * `text` points at a NUL-terminated string and `out` at a writable
 * [`mxr_uid_t`].
 */
mxr_result_t mxr_uid_from_string(const char *text, mxr_uid_t *out);

/**
 * Routes a V2IP sink's video to the stream a source port advertises.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_select_video_source(const mxr_remote_t *remote,
                                     mxr_bay_uid_t sink,
                                     uint16_t source_port);

/**
 * Routes a V2IP sink's audio to the stream a source port advertises,
 * leaving its video where it is.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_select_audio_source(const mxr_remote_t *remote,
                                     mxr_bay_uid_t sink,
                                     uint16_t source_port);

/**
 * Routes a V2IP sink's video to the source bay with this user-assigned name.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `name` is a NUL-terminated string.
 */
mxr_result_t mxr_select_video_source_by_name(const mxr_remote_t *remote,
                                             mxr_bay_uid_t sink,
                                             const char *name);

/**
 * Routes a V2IP sink's audio to the source bay with this user-assigned name.
 *
 * `format` may be null to leave the sink's audio format alone.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `name` is a NUL-terminated string, and
 * `format` is null or points at an initialised [`mxr_audio_format_t`].
 */
mxr_result_t mxr_select_audio_source_by_name(const mxr_remote_t *remote,
                                             mxr_bay_uid_t sink,
                                             const char *name,
                                             const mxr_audio_format_t *format);

/**
 * Routes a V2IP sink's audio to a multicast group directly, for a source this
 * client has not heard advertise it.
 *
 * `audio_port` may be zero for the default, and `format` may be null to leave
 * the sink's audio format alone.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `audio_ip` is a NUL-terminated dotted
 * quad, and `format` is null or points at an initialised
 * [`mxr_audio_format_t`].
 */
mxr_result_t mxr_select_audio_source_addr(const mxr_remote_t *remote,
                                          mxr_bay_uid_t sink,
                                          const char *audio_ip,
                                          uint16_t audio_port,
                                          const mxr_audio_format_t *format);

/**
 * Renames a bay. The device stores the first 16 bytes.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `name` is a NUL-terminated string.
 */
mxr_result_t mxr_set_bay_name(const mxr_remote_t *remote, mxr_bay_uid_t bay, const char *name);

/**
 * Hides a bay from the installation's user interface, or shows it again.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_bay_hidden(const mxr_remote_t *remote, mxr_bay_uid_t bay, bool hidden);

/**
 * Switches an input bay's EDID profile.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_select_edid_profile(const mxr_remote_t *remote,
                                     mxr_bay_uid_t bay,
                                     uint16_t profile);

/**
 * Sends a remote-control action to whatever is attached to a bay.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_send_action(const mxr_remote_t *remote, mxr_bay_uid_t bay, uint16_t action);

/**
 * Powers on what is attached to a bay.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_power_on(const mxr_remote_t *remote, mxr_bay_uid_t bay);

/**
 * Powers off what is attached to a bay.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_power_off(const mxr_remote_t *remote, mxr_bay_uid_t bay);

/**
 * Sets a bay's volume percentage, and its mute state when `muted` is not
 * `MXR_UNKNOWN`.
 *
 * A bay with no volume control of its own is set through its `linked_bay`,
 * so an output wired to an amplifier zone reaches that zone.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_volume(const mxr_remote_t *remote,
                            mxr_bay_uid_t bay,
                            uint8_t volume,
                            mxr_tribool_t muted);

/**
 * Asks a bay to step its volume up.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_volume_up(const mxr_remote_t *remote, mxr_bay_uid_t bay);

/**
 * Asks a bay to step its volume down.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_volume_down(const mxr_remote_t *remote, mxr_bay_uid_t bay);

/**
 * Mutes or unmutes a bay, leaving its volume alone.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_muted(const mxr_remote_t *remote, mxr_bay_uid_t bay, bool muted);

/**
 * Writes an amplifier zone's gain, delay, tone and power settings.
 *
 * This replaces every setting at once, so a caller changing one reads the
 * current set with `mxr_bay_amp_settings()`
 * first.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `settings` points at an initialised
 * [`mxr_amp_zone_settings_t`].
 */
mxr_result_t mxr_set_amp_zone_settings(const mxr_remote_t *remote,
                                       mxr_bay_uid_t bay,
                                       const mxr_amp_zone_settings_t *settings);

/**
 * Mutes or unmutes one of a device's audio endpoints.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_audio_endpoint_muted(const mxr_remote_t *remote,
                                          mxr_uid_t device,
                                          uint16_t endpoint,
                                          bool muted);

/**
 * Activates or clears an audio endpoint's trigger.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_audio_endpoint_trigger(const mxr_remote_t *remote,
                                            mxr_uid_t device,
                                            uint16_t endpoint,
                                            bool active);

/**
 * Sets an audio endpoint's volume.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_audio_endpoint_volume(const mxr_remote_t *remote,
                                           mxr_uid_t device,
                                           uint16_t endpoint,
                                           uint32_t volume);

/**
 * Points one device's audio endpoint at another device's.
 *
 * `sink` is the end doing the listening and `source` the end being
 * listened to.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_select_audio_endpoint_input(const mxr_remote_t *remote,
                                             mxr_uid_t sink,
                                             uint16_t sink_endpoint,
                                             mxr_uid_t source,
                                             uint16_t source_endpoint);

/**
 * Subscribes to, or unsubscribes from, a device's V2IP statistics.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_subscribe_v2ip_stats(const mxr_remote_t *remote, mxr_uid_t device, bool subscribe);

/**
 * Reboots a device.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_reboot(const mxr_remote_t *remote, mxr_uid_t device);

/**
 * Sends the monitoring pulse that tells devices this client is watching.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_send_monitoring_pulse(const mxr_remote_t *remote);

/**
 * Switches a multiviewer's window layout.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_view_mode(const mxr_remote_t *remote,
                                           mxr_uid_t device,
                                           uint8_t mode);

/**
 * Puts a source in one of a multiviewer's windows.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_video_source(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t screen,
                                              uint8_t source);

/**
 * Chooses which window a multiviewer takes its audio from.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_audio_source(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t source);

/**
 * Sets a multiviewer's output volume and mute state.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_audio_volume(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t volume,
                                              bool muted);

/**
 * Switches the EDID a multiviewer presents to its sources.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_edid_template(const mxr_remote_t *remote,
                                               mxr_uid_t device,
                                               uint8_t template_);

/**
 * Chooses which window a multiviewer forwards remote control to.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_remote_control(const mxr_remote_t *remote,
                                                mxr_uid_t device,
                                                uint8_t source);

/**
 * Sets the size of a multiviewer's picture-in-picture window.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_pip_size(const mxr_remote_t *remote,
                                          mxr_uid_t device,
                                          uint8_t size);

/**
 * Sets which corner a multiviewer's picture-in-picture window sits in.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_pip_position(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t position);

/**
 * Sets how a multiviewer fits a source into its window.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_aspect_ratio(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t aspect);

/**
 * Turns a multiviewer's automatic source switching on or off.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_auto_switch(const mxr_remote_t *remote,
                                             mxr_uid_t device,
                                             bool enable);

/**
 * Switches a multiviewer's output resolution.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_output_mode(const mxr_remote_t *remote,
                                             mxr_uid_t device,
                                             uint8_t mode);

/**
 * Sets a multiviewer's IT content flag.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_output_itc(const mxr_remote_t *remote,
                                            mxr_uid_t device,
                                            uint8_t mode);

/**
 * Switches a multiviewer's HDCP mode.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_hdcp_mode(const mxr_remote_t *remote,
                                           mxr_uid_t device,
                                           uint8_t mode);

/**
 * Maps one of a multiviewer's inputs to a source device.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_set_multiviewer_input_source(const mxr_remote_t *remote,
                                              mxr_uid_t device,
                                              uint8_t input,
                                              mxr_uid_t source);

/**
 * Asks a multiviewer to map its inputs to the sources it can see.
 *
 * # Safety
 *
 * `remote` is null or a live handle from `mxr_remote_new()`.
 */
mxr_result_t mxr_multiviewer_auto_route(const mxr_remote_t *remote, mxr_uid_t device);

/**
 * Fills `out` with what is known about a device.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_device_info_t`].
 */
mxr_result_t mxr_device(const mxr_remote_t *remote, mxr_uid_t uid, mxr_device_info_t *out);

/**
 * Fills `out` with what is known about a bay.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_bay_info_t`].
 */
mxr_result_t mxr_bay(const mxr_remote_t *remote, mxr_bay_uid_t bay, mxr_bay_info_t *out);

/**
 * Fills `out` with the signal a bay measures.
 *
 * Fails with `MXR_ERR_NOT_REPORTED` on a bay that has sent no signal report.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_signal_details_t`].
 */
mxr_result_t mxr_bay_signal_details(const mxr_remote_t *remote,
                                    mxr_bay_uid_t bay,
                                    mxr_signal_details_t *out);

/**
 * Fills `out` with an amplifier zone's settings.
 *
 * Fails with `MXR_ERR_NOT_REPORTED` on a bay that is not an amplifier zone or
 * has not reported its settings.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_amp_zone_settings_t`].
 */
mxr_result_t mxr_bay_amp_settings(const mxr_remote_t *remote,
                                  mxr_bay_uid_t bay,
                                  mxr_amp_zone_settings_t *out);

/**
 * Writes a device's bays in port order, and returns how many there are.
 *
 * Returns the full count even when it exceeds `cap`, so calling with `cap`
 * zero sizes the buffer. Returns zero for a device never heard from.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_bay_uid_t`].
 */
size_t mxr_device_bays(const mxr_remote_t *remote, mxr_uid_t uid, mxr_bay_uid_t *out, size_t cap);

/**
 * Writes the temperatures a device reports, in its own order, in degrees
 * Celsius, and returns how many there are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable bytes.
 */
size_t mxr_device_temperatures(const mxr_remote_t *remote, mxr_uid_t uid, uint8_t *out, size_t cap);

/**
 * Writes the devices whose signals a bay refuses, and returns how many there
 * are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_uid_t`].
 */
size_t mxr_bay_filtered(const mxr_remote_t *remote, mxr_bay_uid_t bay, mxr_uid_t *out, size_t cap);

/**
 * Creates a client, without opening a socket yet.
 *
 * `config` may be null for the defaults. `callbacks` may be null, and so may
 * any member of it: an event with no function pointer is dropped. `userdata`
 * is passed back to every callback and is never examined.
 *
 * Returns null on failure, with the reason in
 * `mxr_last_error()`. The client must be released with
 * `mxr_remote_free()`.
 *
 * # Safety
 *
 * `config` and `callbacks` are null or point at initialised structs that
 * outlive the call, and every string in them is NUL-terminated. `userdata`
 * must remain valid, and safe to use from the library's own threads, until
 * `mxr_remote_free()` returns.
 */
mxr_remote_t *mxr_remote_new(const mxr_config_t *config,
                             const mxr_callbacks_t *callbacks,
                             void *userdata);

/**
 * Opens the socket and starts the receive and timer threads.
 *
 * # Safety
 *
 * `remote` is null or a handle from `mxr_remote_new()` that has not been
 * freed.
 */
mxr_result_t mxr_remote_start(const mxr_remote_t *remote);

/**
 * Stops the threads and closes the socket. Idempotent.
 *
 * A handle that has been closed can be freed but not restarted.
 *
 * # Safety
 *
 * `remote` is null or a handle from `mxr_remote_new()` that has not been
 * freed.
 */
void mxr_remote_close(const mxr_remote_t *remote);

/**
 * Closes the client and releases it. Null is ignored.
 *
 * This waits for the receive and timer threads to finish, so a callback
 * running when it is called returns before it does - which means calling it
 * from inside a callback would deadlock.
 *
 * # Safety
 *
 * `remote` is null or a handle from `mxr_remote_new()` that has not already
 * been freed, and no other thread is using it.
 */
void mxr_remote_free(mxr_remote_t *remote);

/**
 * Writes this client's own identifier.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_uid_t`].
 */
mxr_result_t mxr_remote_uid(const mxr_remote_t *remote, mxr_uid_t *out);

/**
 * Writes the name this client advertises.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at `cap` writable bytes.
 */
mxr_result_t mxr_remote_name(const mxr_remote_t *remote, char *out, size_t cap);

/**
 * Writes the address this client sends to.
 *
 * Fails with `MXR_ERR_NOT_CONNECTED` before `mxr_remote_start()`. `ip` needs
 * [`MXR_IP_STRING_LEN`] bytes; either output may be null to skip it.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `ip` is null or points at `cap` writable
 * bytes, and `port` is null or points at a writable `uint16_t`.
 */
mxr_result_t mxr_remote_target(const mxr_remote_t *remote, char *ip, size_t cap, uint16_t *port);

/**
 * Writes every device heard from, and returns how many there are.
 *
 * Returns the full count even when it exceeds `cap`, so calling with `cap`
 * zero sizes the buffer. Returns zero on a null handle.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_uid_t`].
 */
size_t mxr_devices(const mxr_remote_t *remote, mxr_uid_t *out, size_t cap);

/**
 * Finds a device by its serial number.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `serial` is a NUL-terminated string, and
 * `out` points at a writable [`mxr_uid_t`].
 */
mxr_result_t mxr_device_by_serial(const mxr_remote_t *remote, const char *serial, mxr_uid_t *out);

/**
 * Finds a device by serial number, name or identifier, in that order.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `name` is a NUL-terminated string, and
 * `out` points at a writable [`mxr_uid_t`].
 */
mxr_result_t mxr_resolve_device(const mxr_remote_t *remote, const char *name, mxr_uid_t *out);

/**
 * Finds a bay on a device by the name the device gives its port.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `port_name` is a NUL-terminated string,
 * and `out` points at a writable [`mxr_bay_uid_t`].
 */
mxr_result_t mxr_bay_by_name(const mxr_remote_t *remote,
                             mxr_uid_t device,
                             const char *port_name,
                             mxr_bay_uid_t *out);

/**
 * Finds the source bay advertising a multicast group.
 *
 * `audio` picks which of the bay's two streams the address is matched
 * against.
 *
 * # Safety
 *
 * `remote` is null or a live handle, `ip` is a NUL-terminated string, and
 * `out` points at a writable [`mxr_bay_uid_t`].
 */
mxr_result_t mxr_bay_by_stream_ip(const mxr_remote_t *remote,
                                  const char *ip,
                                  bool audio,
                                  mxr_bay_uid_t *out);

/**
 * Reopens the socket on a different interface, or in the other mode.
 *
 * `local_ip` may be null to let the host choose again.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `local_ip` is null or a
 * NUL-terminated string.
 */
mxr_result_t mxr_remote_update_config(const mxr_remote_t *remote,
                                      const char *local_ip,
                                      bool broadcast);

/**
 * Asks every device on the network to announce itself.
 *
 * # Safety
 *
 * `remote` is null or a live handle.
 */
mxr_result_t mxr_discover(const mxr_remote_t *remote);

/**
 * Fills `out` with a device's V2IP statistics.
 *
 * A device sends these only while subscribed; see
 * `mxr_subscribe_v2ip_stats()`.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_v2ip_stats_t`].
 */
mxr_result_t mxr_v2ip_stats(const mxr_remote_t *remote, mxr_uid_t uid, mxr_v2ip_stats_t *out);

/**
 * Fills `out` with a V2IP device's own encoder configuration.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_v2ip_details_t`].
 */
mxr_result_t mxr_v2ip_details(const mxr_remote_t *remote, mxr_uid_t uid, mxr_v2ip_details_t *out);

/**
 * Fills `out` with the streams a V2IP sink is subscribed to.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_v2ip_sink_t`].
 */
mxr_result_t mxr_v2ip_sink(const mxr_remote_t *remote, mxr_uid_t uid, mxr_v2ip_sink_t *out);

/**
 * Fills `out` with the window a sink is told to show.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_tiling_config_t`].
 */
mxr_result_t mxr_v2ip_tiling(const mxr_remote_t *remote, mxr_uid_t uid, mxr_tiling_config_t *out);

/**
 * Fills `out` with what a multiviewer reports about itself.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_multiviewer_status_t`].
 */
mxr_result_t mxr_multiviewer_status(const mxr_remote_t *remote,
                                    mxr_uid_t uid,
                                    mxr_multiviewer_status_t *out);

/**
 * Fills `out` with a ProAmp8's Dolby settings.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_dolby_settings_t`].
 */
mxr_result_t mxr_dolby_settings(const mxr_remote_t *remote,
                                mxr_uid_t uid,
                                mxr_dolby_settings_t *out);

/**
 * Fills `out` with the electrical state a PDU reports.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_pdu_state_t`].
 */
mxr_result_t mxr_pdu_state(const mxr_remote_t *remote, mxr_uid_t uid, mxr_pdu_state_t *out);

/**
 * Fills `out` with a source bay's remote-control configuration.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` points at a writable
 * [`mxr_rc_settings_t`].
 */
mxr_result_t mxr_rc_settings(const mxr_remote_t *remote, mxr_uid_t uid, mxr_rc_settings_t *out);

/**
 * Writes the streams a device's source bays advertise, and returns how many
 * there are.
 *
 * Returns the full count even when it exceeds `cap`, so calling with `cap`
 * zero sizes the buffer.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_stream_sources_t`].
 */
size_t mxr_v2ip_sources(const mxr_remote_t *remote,
                        mxr_uid_t uid,
                        mxr_stream_sources_t *out,
                        size_t cap);

/**
 * Writes a device's network ports, and returns how many there are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_network_port_t`].
 */
size_t mxr_network_status(const mxr_remote_t *remote,
                          mxr_uid_t uid,
                          mxr_network_port_t *out,
                          size_t cap);

/**
 * Writes a device's view of the mesh topology, and returns how many entries
 * there are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_topology_entry_t`].
 */
size_t mxr_topology(const mxr_remote_t *remote,
                    mxr_uid_t uid,
                    mxr_topology_entry_t *out,
                    size_t cap);

/**
 * Writes the firmware versions a device reports, and returns how many there
 * are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_firmware_version_t`].
 */
size_t mxr_device_firmware(const mxr_remote_t *remote,
                           mxr_uid_t uid,
                           mxr_firmware_version_t *out,
                           size_t cap);

/**
 * Writes a device's audio endpoints, in the order it reported them, and
 * returns how many there are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable [`mxr_audio_endpoint_t`].
 */
size_t mxr_audio_endpoints(const mxr_remote_t *remote,
                           mxr_uid_t uid,
                           mxr_audio_endpoint_t *out,
                           size_t cap);

/**
 * Writes the endpoints hanging off one audio endpoint, and returns how many
 * there are.
 *
 * # Safety
 *
 * `remote` is null or a live handle, and `out` is null or points at `cap`
 * writable bytes.
 */
size_t mxr_audio_endpoint_children(const mxr_remote_t *remote,
                                   mxr_uid_t uid,
                                   uint8_t endpoint,
                                   uint8_t *out,
                                   size_t cap);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* MX_REMOTE_H */