Every fallible call returns a MediusStatus and writes its real result through an out-param. MEDIUS_STATUS_OK is 0; anything else is a failure and the out-param is untouched. Fetch the human-readable detail separately. What each code means lives on Errors.

  call ──▶ MediusStatus
             │
             ├─ == OK ──▶ the out-param is valid, carry on
             └─ != OK ──▶ medius_last_error_message(buf, cap)   text (this thread)
                          medius_last_error_proto_ver()         byte (BadProtoVer only)

uintptr_t medius_last_error_message(char *buf, uintptr_t cap);
uint8_t   medius_last_error_proto_ver(void);

MediusDevice *dev = NULL;
if (medius_device_find(&dev) != MEDIUS_STATUS_OK) {
    char buf[256];
    medius_last_error_message(buf, sizeof buf);   /* NUL-terminated, truncated to cap */
    fprintf(stderr, "open failed: %s\n", buf);
    return 1;
}

medius_last_error_message returns the full message length in bytes (excluding the NUL), so a caller can size a buffer and retry on truncation. medius_last_error_proto_ver returns the offending version byte after a BadProtoVer, else 0.

Handles are opaque pointers you own. There's no destructor or RAII: medius_*_clone makes another owner of the same underlying object (reference-counted), and you must call the matching medius_*_free on every handle you hold. See Connection and Lifecycle.

  medius_device_open / _find  ──▶  MediusDevice *    (you own it)
                                        │  medius_device_clone
                                        ▼
                                   MediusDevice *    (2nd owner, same link)

  medius_device_free(handle)  ──▶  drop one owner    (NULL = no-op)
  free the last owner         ──▶  joins the reader + keepalive threads

MediusDevice *dev = NULL;
if (medius_device_find(&dev) != MEDIUS_STATUS_OK) { return 1; }

MediusDevice *worker = medius_device_clone(dev);  /* same link, ref-counted */
/* ... use either handle from either thread ... */

medius_device_free(worker);   /* drop one owner */
medius_device_free(dev);      /* last owner -> joins the background threads */

Rust's generic inject / move_axis / lock targets are built structs in C: MediusUsage, MediusMotion, and MediusLockTarget, plus MediusCatchFilter, each with a helper constructor.

A MediusUsage holds a button id, keycode, or Consumer usage, and the same value drives an inject, a lock, or a catch test.

/* inject: build a usage, then apply an Action */
MediusUsage lmb = medius_usage_button(MEDIUS_BUTTON_LEFT);
medius_device_inject(dev, lmb, MEDIUS_ACTION_PRESS);
medius_device_press(dev, medius_usage_key(MEDIUS_KEY_W));   /* keys and media inject the same way */

/* move: build a motion arm */
MediusMotion m = medius_motion_cursor(100, -50);
medius_device_move_axis(dev, m, MEDIUS_MOVE_TIMING_RIDE, MEDIUS_PENDING_MOTION_KEEP);

/* lock: an axis, or any usage */
MediusLockTarget x = medius_lock_target_axis(MEDIUS_LOCK_TARGET_KIND_X);
medius_device_lock(dev, x, MEDIUS_DIRECTION_BOTH);

MediusLockTarget side = medius_lock_target_usage(medius_usage_button(MEDIUS_BUTTON_SIDE1));
medius_device_lock(dev, side, MEDIUS_DIRECTION_BOTH);

A catch filter narrows the same way: a base names what to observe, a modifier returns a narrowed copy. Nothing is mutated, so one blanket can be the base for several entries. Fields are on Types & errors.

/* every key edge, whole report */
MediusCatchFilter keys = medius_catch_filter_watch_class(MEDIUS_CLASS_KEY);

/* one vendor endpoint's IN packets, first 16 bytes each */
MediusCatchFilter ep = medius_catch_filter_with_capture(
    medius_catch_filter_inbound(
        medius_catch_filter_traffic(MEDIUS_CATCH_CLASS_VENDOR_INTERRUPT, 0x83)),
    16);

MediusCatchFilter filters[2] = { keys, ep };
MediusEventStream *events = NULL;
medius_device_catch_events(dev, filters, 2, &events);   /* the array is not retained */

Two return shapes, both yielding a MediusStatus. The badge on each row of the API index says which is which.