Trait mpris_server::RootInterface

pub trait RootInterface: Send + Sync {
    // Required methods
    fn raise(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn quit(&self) -> impl Future<Output = Result<()>> + Send + Sync;
    fn can_quit(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn fullscreen(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn set_fullscreen(
        &self,
        fullscreen: bool,
    ) -> impl Future<Output = Result<()>> + Send + Sync;
    fn can_set_fullscreen(
        &self,
    ) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn can_raise(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn has_track_list(&self) -> impl Future<Output = Result<bool>> + Send + Sync;
    fn identity(&self) -> impl Future<Output = Result<String>> + Send + Sync;
    fn desktop_entry(
        &self,
    ) -> impl Future<Output = Result<String>> + Send + Sync;
    fn supported_uri_schemes(
        &self,
    ) -> impl Future<Output = Result<Vec<String>>> + Send + Sync;
    fn supported_mime_types(
        &self,
    ) -> impl Future<Output = Result<Vec<String>>> + Send + Sync;
}

Used to implement org.mpris.MediaPlayer2 interface.

Required Methods

fn raise(&self) -> impl Future<Output = Result<()>> + Send + Sync

Brings the media player’s user interface to the front using any appropriate mechanism available.

The media player may be unable to control how its user interface is displayed, or it may not have a graphical user interface at all. In this case, the CanRaise property is false and this method does nothing.

fn quit(&self) -> impl Future<Output = Result<()>> + Send + Sync

Causes the media player to stop running.

The media player may refuse to allow clients to shut it down. In this case, the CanQuit property is false and this method does nothing.

Note: Media players which can be D-Bus activated, or for which there is no sensibly easy way to terminate a running instance (via the main interface or a notification area icon for example) should allow clients to use this method. Otherwise, it should not be needed.

If the media player does not have a UI, this should be implemented.

fn can_quit(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Whether the player may be asked to quit.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

If false, calling Quit will have no effect, and may raise a NotSupported error. If true, calling Quit will cause the media application to attempt to quit (although it may still be prevented from quitting by the user, for example).

fn fullscreen(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Whether the media player is occupying the fullscreen.

This property is optional. Clients should handle its absence gracefully.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

This is typically used for videos. A value of true indicates that the media player is taking up the full screen.

Media centre software may well have this value fixed to true

If CanSetFullscreen is true, clients may set this property to true to tell the media player to enter fullscreen mode, or to false to return to windowed mode.

If CanSetFullscreen is false, then attempting to set this property should have no effect, and may raise an error. However, even if it is true, the media player may still be unable to fulfil the request, in which case attempting to set this property will have no effect (but should not raise an error).

Rationale

This allows remote control interfaces, such as LIRC or mobile devices like phones, to control whether a video is shown in fullscreen.

fn set_fullscreen( &self, fullscreen: bool, ) -> impl Future<Output = Result<()>> + Send + Sync

Sets whether the media player is occupying the fullscreen.

See Fullscreen for more details.

fn can_set_fullscreen(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Whether the player may be asked to enter or leave fullscreen.

This property is optional. Clients should handle its absence gracefully.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

If false, attempting to set Fullscreen will have no effect, and may raise an error. If true, attempting to set Fullscreen will not raise an error, and (if it is different from the current value) will cause the media player to attempt to enter or exit fullscreen mode.

Note that the media player may be unable to fulfil the request. In this case, the value will not change. If the media player knows in advance that it will not be able to fulfil the request, however, this property should be false.

Rationale

This allows clients to choose whether to display controls for entering or exiting fullscreen mode.

fn can_raise(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Whether the media player may be asked to be raised.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

If false, calling Raise will have no effect, and may raise a NotSupported error. If true, calling Raise will cause the media application to attempt to bring its user interface to the front, although it may be prevented from doing so (by the window manager, for example).

fn has_track_list(&self) -> impl Future<Output = Result<bool>> + Send + Sync

Indicates whether the /org/mpris/MediaPlayer2 object implements the TrackList interface.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

fn identity(&self) -> impl Future<Output = Result<String>> + Send + Sync

A friendly name to identify the media player to users (eg: “VLC media player”).

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

This should usually match the name found in .desktop files

fn desktop_entry(&self) -> impl Future<Output = Result<String>> + Send + Sync

The basename of an installed .desktop file which complies with the Desktop entry specification, with the “.desktop” extension stripped.

This property is optional. Clients should handle its absence gracefully.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

Example: The desktop entry file is “/usr/share/applications/vlc.desktop”, and this property contains “vlc”

fn supported_uri_schemes( &self, ) -> impl Future<Output = Result<Vec<String>>> + Send + Sync

The URI schemes supported by the media player.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

This can be viewed as protocols supported by the player in almost all cases. Almost every media player will include support for the “file” scheme. Other common schemes are “http” and “rtsp”.

Note that URI schemes should be lower-case.

Rationale

This is important for clients to know when using the editing capabilities of the Playlists interface, for example.

fn supported_mime_types( &self, ) -> impl Future<Output = Result<Vec<String>>> + Send + Sync

The mime-types supported by the media player.

When this property changes, the org.freedesktop.DBus.Properties.PropertiesChanged signal via properties_changed must be emitted with the new value.

Mime-types should be in the standard format (eg: audio/mpeg or application/ogg).

Rationale

This is important for clients to know when using the editing capabilities of the Playlists interface, for example.

Object Safety

This trait is not object safe.

Implementors