Struct ClipHandle 

pub struct ClipHandle { /* private fields */ }

Handle to one box’s buffered-clip playback, from Device::clip. Clones share the append-sequence counter.

A trigger runs a clip verb on the box, with no host round trip. One set holds two kinds: an input trigger (bind) fires on a button, key or media edge; a packet trigger (bind_packet) on a packet crossing a traffic surface. clear_triggers removes both; query_config reads both back.

The keepalive keeps a loaded clip, a setting off its default and a bound trigger past the box’s silence window. A reconnect re-sends none of it and keeps what the box still holds: a link down longer than that window leaves nothing, so reload the clip and its config. A device-chip restart or a session release counted in Stats::session (the opt-in going off keeps the clip) can empty the ring: the crate re-sends the settings and triggers, and lost says to reload the clip.

Implementations

impl ClipHandle

pub fn append(&self, clip: &ClipBuilder) -> Result<()>

Append the builder’s entries to the ring, in whole-entry frames each stamped with the next append-sequence number. Fire-and-forget.

Every entry is checked before the first frame goes out, so a refusal sends nothing: a ClipFrame past its edge or raw-report count or encoding past CLIP_ENTRY_MAX, a raw report neither IN nor OUT, or a transfer whose data does not match its setup packet.

pub fn set_autolock(&self, scope: &[Blanket]) -> Result<()>

Auto-lock these physical-input groups while the clip plays (clip-owned, released on stop). Fire-and-forget.

pub fn set_loop(&self, on: bool) -> Result<()>

Loop playback at the clip end (retained mode only). Fire-and-forget.

pub fn set_retain(&self, on: bool) -> Result<()>

Retain the loaded clip so it can rewind and replay (false = streaming, the default). Set before the first append. Fire-and-forget.

pub fn set_ride(&self, on: bool) -> Result<()>

Clip motion waits to ride a native report under set_movement_riding (false = the box’s own clock, the default); only wheel and pan while rendering is on with a profile armed. Changeable mid-playback. Fire-and-forget.

pub fn bind(&self, trigger: ClipTrigger) -> Result<()>

Add or overwrite an input trigger: trigger’s edge fires its action on the box, no host round trip. Fire-and-forget.

pub fn unbind(&self, usage: impl Into<Usage>, edge: Edge) -> Result<()>

Remove the input trigger on usage’s edge. Fire-and-forget.

pub fn bind_packet(&self, trigger: &ClipPacketTrigger) -> Result<()>

Add or overwrite a packet trigger: a matching packet fires its action on the box’s next tick, no host round trip. Fire-and-forget.

Refused here, before anything is sent, with Error::ClipPacketTrigger, as the box would refuse:

• a class that is Bus or ClipTransfer;
• a match past PKT_MATCH_MAX bytes, or unlike its mask in length;
• a direction the class never carries: OUT on HidIn or Emit, IN on HidOut;
• a match bit outside its mask, which no packet can equal;
• consume on Control;
• a selector length without once_per_run;
• once_per_run without one stream (a report class, a concrete id, and IN or OUT), without match bytes past its selector, or with no masked bit in them.

A bearing-relative direction is Error::RelativeDirection. Match and mask go to the box as given, so the key named here is the key the box holds.

The box makes three checks this call cannot: a consuming trigger needs allow_imperfect_clones(true), the set holds CLIP_PKT_TRIG_MAX triggers, and their match bytes share a CLIP_PKT_MATCH_POOL pool. A refused bind leaves the set as it was: a new key is not held, and a held key keeps its trigger, action and flags. To confirm a bind, compare what query_config reads back with what was bound.

The crate records a bind once its frame is out, taken or not, and the keepalive runs for what it records. A refused bind stays recorded until unbind_packet, clear_triggers, or a reconnect that adopts what the box holds.

pub fn unbind_packet(&self, trigger: &ClipPacketTrigger) -> Result<()>

Remove the packet trigger keyed by trigger’s (class, id, direction, match_bytes, mask); other fields are ignored. A key the box cannot hold is refused as bind_packet refuses it: class, lengths, direction, and a match bit outside the mask. Fire-and-forget.

pub fn clear_triggers(&self) -> Result<()>

Remove every trigger of both kinds. Fire-and-forget.

pub fn start(&self) -> Result<()>

Rewind and play (resume from a pause). Fire-and-forget.

pub fn stop(&self) -> Result<()>

Stop, flush a streaming clip (rewind a retained one), release held input and the clip auto-lock. Fire-and-forget.

pub fn pause(&self) -> Result<()>

Halt mid-clip, retaining the cursor and any held input. Fire-and-forget.

pub fn resume(&self) -> Result<()>

Continue from the paused cursor. Fire-and-forget.

pub fn restart(&self) -> Result<()>

Force a rewind and play, even mid-playback. Fire-and-forget.

pub fn toggle(&self) -> Result<()>

Toggle: play if idle/paused, stop if playing. Fire-and-forget.

pub fn clear(&self) -> Result<()>

Discard the loaded clip, free the ring, and clear a fault. Fire-and-forget.

pub fn finalize(&self) -> Result<()>

Finalize a retained clip: fix its end so it can replay and loop. Fire-and-forget.

pub fn lost(&self) -> bool

Whether the box dropped the clip appended since the last clear: the device chip restarted, the box released the session, or a reconnect found it gone. Set once the box accepts a reload, reset by the next append or clear.

pub fn query_status(&self) -> Result<ClipStatus>

QUERY(CLIP): ring depth, progress and playback counters (§4.15).

pub fn query_config(&self) -> Result<ClipSettings>

QUERY(CLIP): clip config (autolock, loop, retain, finalized, both trigger kinds) (§4.15).

Trait Implementations

impl Clone for ClipHandle

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClipHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.