Struct mpv_client::Handle

pub struct Handle { /* private fields */ }

Representation of a borrowed client context used by the client API. Every client has its own private handle.

Implementations

impl Handle

pub fn from_ptr<'a>(ptr: *mut mpv_handle) -> &'a mut Self

Wrap a raw mpv_handle

This function will wrap the provided ptr with a Handle wrapper, which allows inspection and interoperation of non-owned mpv_handle.

Safety

• ptr must be non null.

• The memory referenced by the returned Handle must not be freed for the duration of lifetime 'a.

pub unsafe fn as_ptr(&self) -> *const mpv_handle

pub unsafe fn as_mut_ptr(&mut self) -> *mut mpv_handle

pub fn create_client<S: AsRef<str>>(&mut self, name: S) -> Result<Client>

pub fn create_weak_client<S: AsRef<str>>(&mut self, name: S) -> Result<Client>

pub fn initialize(&mut self) -> Result<()>

pub fn wait_event(&mut self, timeout: f64) -> Event

Wait for the next event, or until the timeout expires, or if another thread makes a call to mpv_wakeup(). Passing 0 as timeout will never wait, and is suitable for polling.

The internal event queue has a limited size (per client handle). If you don’t empty the event queue quickly enough with Handle::wait_event, it will overflow and silently discard further events. If this happens, making asynchronous requests will fail as well (with MPV_ERROR_EVENT_QUEUE_FULL).

Only one thread is allowed to call this on the same Handle at a time. The API won’t complain if more than one thread calls this, but it will cause race conditions in the client when accessing the shared mpv_event struct. Note that most other API functions are not restricted by this, and no API function internally calls mpv_wait_event(). Additionally, concurrent calls to different handles are always safe.

As long as the timeout is 0, this is safe to be called from mpv render API threads.

pub fn name<'a>(&mut self) -> &'a str

Return the name of this client handle. Every client has its own unique name, which is mostly used for user interface purposes.

pub fn id(&mut self) -> i64

Return the ID of this client handle. Every client has its own unique ID. This ID is never reused by the core, even if the mpv_handle at hand gets destroyed and new handles get allocated.

IDs are never 0 or negative.

Some mpv APIs (not necessarily all) accept a name in the form “@” in addition of the proper mpv_client_name(), where “” is the ID in decimal form (e.g. “@123”). For example, the “script-message-to” command takes the client name as first argument, but also accepts the client ID formatted in this manner.

pub fn command<I, S>(&mut self, args: I) -> Result<()>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Send a command to the player. Commands are the same as those used in input.conf, except that this function takes parameters in a pre-split form.

pub fn command_async<I, S>(&mut self, reply: u64, args: I) -> Result<()>

where I: IntoIterator<Item = S>, S: AsRef<str>,

Same as Handle::command, but run the command asynchronously.

Commands are executed asynchronously. You will receive a CommandReply event. This event will also have an error code set if running the command failed. For commands that return data, the data is put into mpv_event_command.result.

The only case when you do not receive an event is when the function call itself fails. This happens only if parsing the command itself (or otherwise validating it) fails, i.e. the return code of the API call is not 0 or positive.

Safe to be called from mpv render API threads.

pub fn set_property<T: Format, S: AsRef<str>>( &mut self, name: S, data: T ) -> Result<()>

pub fn get_property<T: Format, S: AsRef<str>>(&mut self, name: S) -> Result<T>

Read the value of the given property.

If the format doesn’t match with the internal format of the property, access usually will fail with MPV_ERROR_PROPERTY_FORMAT. In some cases, the data is automatically converted and access succeeds. For example, i64 is always converted to f64, and access using String usually invokes a string formatter.

pub fn observe_property<S: AsRef<str>>( &mut self, reply: u64, name: S, format: i32 ) -> Result<()>

pub fn unobserve_property(&mut self, registered_reply: u64) -> Result<()>

Undo Handle::observe_property. This will remove all observed properties for which the given number was passed as reply to Handle::observe_property.

Safe to be called from mpv render API threads.

pub fn hook_add(&mut self, reply: u64, name: &str, priority: i32) -> Result<()>

pub fn hook_continue(&mut self, id: u64) -> Result<()>