Crate mx_remote_ffi

Expand description

C ABI for mx_remote.

The whole of this crate is one translation: it holds every unsafe in the workspace, and adds no protocol logic of its own. Anything a caller can do here is something the core crate already does; if a rule is not enforced in mx_remote, it is not enforced at all.

Three conventions run through the header, and knowing them is most of knowing the API:

A device is addressed by value. There is no handle for a device or a bay: a device is a mxr_uid_t, a bay is a mxr_bay_uid_t, and state is read by passing one in and having a struct filled out. Nothing hands back a pointer into state that a lock protects.
Every call returns, whatever happens. An unwind across the boundary is undefined behaviour, so each entry point catches: a panic becomes mxr_result_t::MXR_ERR_PANIC rather than a corrupted stack.
A borrowed pointer lives for one call. Strings and arrays handed to a callback point into memory the library owns and reuses. A caller that needs one afterwards copies it.

Every failure code is negative and mxr_result_t::MXR_OK is zero, so if (rc < 0) is a complete test, and a code added later cannot turn a failure into a success.

§From C

#include <mx_remote.h>

/* The client cannot be its own userdata: it does not exist when the table
 * is handed over, so it reaches the callbacks through a struct that does. */
struct app { mxr_remote_t *remote; };

static void on_device_update(void *userdata, mxr_uid_t device) {
    mxr_device_info_t info;
    if (mxr_device(((struct app *)userdata)->remote, device, &info) == MXR_OK)
        printf("%s %s\n", info.model, info.name);
}

int main(void) {
    struct app app = {0};
    mxr_callbacks_t cb = {0};
    cb.on_device_update = on_device_update;

    /* Zeroing a config asks for every default; NULL does the same. */
    app.remote = mxr_remote_new(NULL, &cb, &app);
    mxr_remote_start(app.remote);
    /* ... */
    mxr_remote_free(app.remote);
    return 0;
}

include/mx_remote.h is generated from this source by cbindgen and checked into the repository. include/mx_remote.hpp is a hand-written header-only C++ layer over it, with a move-only mxr::Remote that closes and joins in its destructor and an mxr::Handler base class carrying a virtual method per event.

Structs§

mxr_action_transmit_request_t: Asks one device to perform a remote-control action.
mxr_amp_zone_settings_t: A ProAmp8 zone’s gain, delay, tone and power settings.
mxr_audio_change_source_t: Which source endpoint an audio sink endpoint was switched to.
mxr_audio_endpoint_t: One node of a device’s audio tree.
mxr_audio_format_t: A stream’s sample rate and channel count.
mxr_bay_info_t: What a bay is, and what is connected to it.
mxr_bay_name_change_t: Asks a device to rename one of its bays.
mxr_bay_uid_t: A single bay: the device it is on, and its port number there.
mxr_blacklist_change_t: Registers or unregisters a device on the source blacklist.
mxr_cable_status_t: The diagnostic result for one UTP cable pair.
mxr_callbacks_t: What to call when something happens.
mxr_config_t: How a client finds the network.
mxr_device_info_t: What a device is, and what it is doing.
mxr_dolby_settings_t: A ProAmp8’s Dolby settings.
mxr_edid_profile_change_t: Asks a device to switch its input EDID profile.
mxr_edid_record_t: One EDID block from a device’s reply.
mxr_edid_request_t: Asks one device for its EDID.
mxr_factory_reset_request_t: Asks peers to factory-reset.
mxr_firmware_version_t: One firmware component a device reports.
mxr_ir_capture_t: Raw IR captured on a bay of the sending device.
mxr_ir_meta_t: The metadata shared by the raw-IR capture and transmit frames.
mxr_ir_transmit_request_t: Asks one device to blast raw IR on one of its local bays.
mxr_key_transmit_request_t: Asks one device to send a remote-control key on a bay.
mxr_multiviewer_command_t: A command addressed to a multiviewer.
mxr_multiviewer_status_t: What a multiviewer reports about itself.
mxr_network_port_t: The link state and diagnostics of one network port.
mxr_pdu_state_t: The electrical state a PDU reports.
mxr_power_save_request_t: Asks a sink to enter or leave power save.
mxr_rc_settings_t: The remote-control configuration of a source bay.
mxr_remote_t: A running client. Opaque: everything about it is reached through the functions below.
mxr_set_route_request_t: Asks a device, addressed by serial, to switch a sink.
mxr_signal_details_t: The signal a bay measures, beyond the description in mxr_bay_info_t::signal_type.
mxr_stream_source_t: One multicast stream address.
mxr_stream_sources_t: The streams one V2IP source advertises.
mxr_tiling_config_t: The window a sink is currently told to show.
mxr_topology_entry_t: One device in a topology report.
mxr_uid_t: The 16-byte identifier of a device on the network.
mxr_v2ip_details_t: A V2IP device’s own encoder configuration.
mxr_v2ip_rx_stats_t: Receiver stream statistics.
mxr_v2ip_sink_t: The streams a V2IP sink is subscribed to.
mxr_v2ip_stats_t: A device’s V2IP statistics, cumulative and over the last minute.
mxr_v2ip_tx_stats_t: Transmitter stream statistics.
mxr_video_wall_command_t: Asks one sink to crop its source to a wall window.

Enums§

mxr_arc_status_t: The audio return channel a bay is carrying.
mxr_device_status_t: The high-level state of a device on the network.
mxr_power_status_t: The CEC power state of whatever is connected to a bay.
mxr_result_t: How a call ended.
mxr_stream_kind_t: Which of a V2IP device’s streams an address describes.
mxr_tribool_t: A flag a device may not have reported.

Constants§

MXR_AMP_EQ_BANDS: Number of EQ bands an amplifier zone carries.
MXR_IP_STRING_LEN: Bytes an IPv4 address needs when written as text, the terminator included.
MXR_MESSAGE_LEN: Bytes a device’s system-status message needs, the terminator included.
MXR_MODEL_LEN: Bytes a model name needs, the terminator included.
MXR_MULTIVIEWER_INPUTS: How many inputs a multiviewer has.
MXR_NAME_LEN: Bytes a device, bay or port name needs, the terminator included.
MXR_PDU_OUTLETS: How many outlets a PDU reports.
MXR_SCALING_FLAG_AUTO_SCALING: Set when the output scales automatically.
MXR_SCALING_FLAG_MODE_VALID: Set when the frame carries a scaling mode and refresh rate.
MXR_SCALING_FLAG_OPTIONS_VALID: Set when the frame carries the scaling options.
MXR_SERIAL_LEN: Bytes a serial number needs, the terminator included.
MXR_SIGNAL_TYPE_LEN: Bytes a signal description such as 1080p60 444 8 needs, the terminator included.
MXR_UID_STRING_LEN: Bytes a mxr_uid_t needs when written as text, the terminator included.
MXR_UTP_PAIRS: How many pairs a UTP cable diagnostic covers.
MXR_VERSION_LEN: Bytes a firmware version string needs, the terminator included.

Functions§

mxr_audio_endpoint_children^⚠: Writes the endpoints hanging off one audio endpoint, and returns how many there are.
mxr_audio_endpoints^⚠: Writes a device’s audio endpoints, in the order it reported them, and returns how many there are.
mxr_bay^⚠: Fills out with what is known about a bay.
mxr_bay_amp_settings^⚠: Fills out with an amplifier zone’s settings.
mxr_bay_by_name^⚠: Finds a bay on a device by the name the device gives its port.
mxr_bay_by_stream_ip^⚠: Finds the source bay advertising a multicast group.
mxr_bay_filtered^⚠: Writes the devices whose signals a bay refuses, and returns how many there are.
mxr_bay_signal_details^⚠: Fills out with the signal a bay measures.
mxr_device^⚠: Fills out with what is known about a device.
mxr_device_bays^⚠: Writes a device’s bays in port order, and returns how many there are.
mxr_device_by_serial^⚠: Finds a device by its serial number.
mxr_device_firmware^⚠: Writes the firmware versions a device reports, and returns how many there are.
mxr_device_temperatures^⚠: Writes the temperatures a device reports, in its own order, in degrees Celsius, and returns how many there are.
mxr_devices^⚠: Writes every device heard from, and returns how many there are.
mxr_discover^⚠: Asks every device on the network to announce itself.
mxr_dolby_settings^⚠: Fills out with a ProAmp8’s Dolby settings.
mxr_last_error: Why the last call on this thread failed, or an empty string.
mxr_multiviewer_auto_route^⚠: Asks a multiviewer to map its inputs to the sources it can see.
mxr_multiviewer_status^⚠: Fills out with what a multiviewer reports about itself.
mxr_network_status^⚠: Writes a device’s network ports, and returns how many there are.
mxr_pdu_state^⚠: Fills out with the electrical state a PDU reports.
mxr_power_off^⚠: Powers off what is attached to a bay.
mxr_power_on^⚠: Powers on what is attached to a bay.
mxr_rc_settings^⚠: Fills out with a source bay’s remote-control configuration.
mxr_reboot^⚠: Reboots a device.
mxr_remote_close^⚠: Stops the threads and closes the socket. Idempotent.
mxr_remote_free^⚠: Closes the client and releases it. Null is ignored.
mxr_remote_name^⚠: Writes the name this client advertises.
mxr_remote_new^⚠: Creates a client, without opening a socket yet.
mxr_remote_start^⚠: Opens the socket and starts the receive and timer threads.
mxr_remote_target^⚠: Writes the address this client sends to.
mxr_remote_uid^⚠: Writes this client’s own identifier.
mxr_remote_update_config^⚠: Reopens the socket on a different interface, or in the other mode.
mxr_resolve_device^⚠: Finds a device by serial number, name or identifier, in that order.
mxr_select_audio_endpoint_input^⚠: Points one device’s audio endpoint at another device’s.
mxr_select_audio_source^⚠: Routes a V2IP sink’s audio to the stream a source port advertises, leaving its video where it is.
mxr_select_audio_source_addr^⚠: Routes a V2IP sink’s audio to a multicast group directly, for a source this client has not heard advertise it.
mxr_select_audio_source_by_name^⚠: Routes a V2IP sink’s audio to the source bay with this user-assigned name.
mxr_select_edid_profile^⚠: Switches an input bay’s EDID profile.
mxr_select_video_source^⚠: Routes a V2IP sink’s video to the stream a source port advertises.
mxr_select_video_source_by_name^⚠: Routes a V2IP sink’s video to the source bay with this user-assigned name.
mxr_send_action^⚠: Sends a remote-control action to whatever is attached to a bay.
mxr_send_monitoring_pulse^⚠: Sends the monitoring pulse that tells devices this client is watching.
mxr_set_amp_zone_settings^⚠: Writes an amplifier zone’s gain, delay, tone and power settings.
mxr_set_audio_endpoint_muted^⚠: Mutes or unmutes one of a device’s audio endpoints.
mxr_set_audio_endpoint_trigger^⚠: Activates or clears an audio endpoint’s trigger.
mxr_set_audio_endpoint_volume^⚠: Sets an audio endpoint’s volume.
mxr_set_bay_hidden^⚠: Hides a bay from the installation’s user interface, or shows it again.
mxr_set_bay_name^⚠: Renames a bay. The device stores the first 16 bytes.
mxr_set_multiviewer_aspect_ratio^⚠: Sets how a multiviewer fits a source into its window.
mxr_set_multiviewer_audio_source^⚠: Chooses which window a multiviewer takes its audio from.
mxr_set_multiviewer_audio_volume^⚠: Sets a multiviewer’s output volume and mute state.
mxr_set_multiviewer_auto_switch^⚠: Turns a multiviewer’s automatic source switching on or off.
mxr_set_multiviewer_edid_template^⚠: Switches the EDID a multiviewer presents to its sources.
mxr_set_multiviewer_hdcp_mode^⚠: Switches a multiviewer’s HDCP mode.
mxr_set_multiviewer_input_source^⚠: Maps one of a multiviewer’s inputs to a source device.
mxr_set_multiviewer_output_itc^⚠: Sets a multiviewer’s IT content flag.
mxr_set_multiviewer_output_mode^⚠: Switches a multiviewer’s output resolution.
mxr_set_multiviewer_pip_position^⚠: Sets which corner a multiviewer’s picture-in-picture window sits in.
mxr_set_multiviewer_pip_size^⚠: Sets the size of a multiviewer’s picture-in-picture window.
mxr_set_multiviewer_remote_control^⚠: Chooses which window a multiviewer forwards remote control to.
mxr_set_multiviewer_video_source^⚠: Puts a source in one of a multiviewer’s windows.
mxr_set_multiviewer_view_mode^⚠: Switches a multiviewer’s window layout.
mxr_set_muted^⚠: Mutes or unmutes a bay, leaving its volume alone.
mxr_set_volume^⚠: Sets a bay’s volume percentage, and its mute state when muted is not MXR_UNKNOWN.
mxr_subscribe_v2ip_stats^⚠: Subscribes to, or unsubscribes from, a device’s V2IP statistics.
mxr_topology^⚠: Writes a device’s view of the mesh topology, and returns how many entries there are.
mxr_uid_from_string^⚠: Reads the dotted-hex form mxr_uid_to_string() writes.
mxr_uid_is_zero: Reports whether uid is the empty identifier.
mxr_uid_to_string^⚠: Writes uid as dotted hex into out, which needs MXR_UID_STRING_LEN bytes.
mxr_v2ip_details^⚠: Fills out with a V2IP device’s own encoder configuration.
mxr_v2ip_sink^⚠: Fills out with the streams a V2IP sink is subscribed to.
mxr_v2ip_sources^⚠: Writes the streams a device’s source bays advertise, and returns how many there are.
mxr_v2ip_stats^⚠: Fills out with a device’s V2IP statistics.
mxr_v2ip_tiling^⚠: Fills out with the window a sink is told to show.
mxr_version: This library’s version, as MAJOR.MINOR.PATCH.
mxr_volume_down^⚠: Asks a bay to step its volume down.
mxr_volume_up^⚠: Asks a bay to step its volume up.

Type Aliases§

mxr_action_transmit_cb: Carries a request to perform a remote-control action.
mxr_arc_cb: Names a bay and its audio return channel.
mxr_audio_select_cb: Carries an audio input selection.
mxr_bay_bay_cb: Names a bay and another bay, the zero device standing for none.
mxr_bay_bool_cb: Names a bay and a flag.
mxr_bay_cb: Names only the bay the event concerns.
mxr_bay_linked_cb: Names a bay and the link that was made to it.
mxr_bay_name_change_cb: Carries a request to rename a bay.
mxr_bay_str_cb: Names a bay and a string, borrowed for the call.
mxr_bay_u8_cb: Names a bay and an 8-bit value.
mxr_bay_u16_cb: Names a bay and a 16-bit value.
mxr_bay_unlinked_cb: Names a bay and the link that was removed from it.
mxr_blacklist_cb: Carries a blacklist change.
mxr_device_bool_cb: Names a device and a flag.
mxr_device_cb: Names only the device the event concerns.
mxr_device_u16_cb: Names a device and a 16-bit value.
mxr_device_uid_cb: Names a device and a second device.
mxr_edid_profile_change_cb: Carries a request to switch an EDID profile.
mxr_edid_record_cb: Carries one EDID block a device replied with.
mxr_edid_request_cb: Carries a request for a device’s EDID.
mxr_endpoint_bool_cb: Names a device, one of its audio endpoints, and a flag.
mxr_endpoint_u32_cb: Names a device, one of its audio endpoints, and a 32-bit value.
mxr_factory_reset_cb: Carries a factory-reset request.
mxr_ir_capture_cb: Carries raw infrared captured on a bay.
mxr_ir_transmit_cb: Carries a request to blast raw infrared.
mxr_key_transmit_cb: Carries a request to send a remote-control key.
mxr_multiviewer_command_cb: Carries a multiviewer command.
mxr_power_cb: Names a bay and the power state of what is connected to it.
mxr_power_save_cb: Carries a power-save request.
mxr_set_route_cb: Carries a request addressed to a device.
mxr_system_status_cb: Names a device, a status code and a message.
mxr_video_wall_cb: Carries a video wall command.
mxr_volume_cb: Names a bay, its combined volume percentage and its mute state.