PlayerctlPlayerManager: Playerctl Reference Manual

PlayerctlPlayerManager

PlayerctlPlayerManager — A class to watch for players appearing and vanishing.

Functions

PlayerctlPlayerManager *	playerctl_player_manager_new ()
void	playerctl_player_manager_manage_player ()
void	playerctl_player_manager_set_sort_func ()
void	playerctl_player_manager_move_player_to_top ()

Properties

gpointer	player-names	Read
gpointer	players	Read

Signals

void	name-appeared	Run Last
void	name-vanished	Run First
void	player-appeared	Run First
void	player-vanished	Run First

Object Hierarchy

    GObject
    ╰── PlayerctlPlayerManager

Description

The PlayerctlPlayerManager is a class to watch for players appearing and vanishing. When a player opens and is available to control by playerctl, the “name-appeared” event will be emitted on the manager during the main loop. You can inspect this PlayerctlPlayerName to see if you want to manage it. If you do, create a PlayerctlPlayer from it with the playerctl_player_new_from_name() function. The manager is also capable of keeping an up-to-date list of players you want it to manage in the “players” list. These players are connected and should be able to be controlled. Managing players is optional, and you can do so manually if you like.

When the player disconnects, the “name-vanished” event will be emitted. If the player is managed and is going to be removed from the list, the “player-vanished” event will also be emitted. After this event, the player will be cleaned up and removed from the manager.

The manager has other features such as being able to keep the players in a sorted order and moving a player to the top of the list. The “player-names” will always be in the order that they were known to appear after the manager was created.

For examples on how to use the manager, see the examples folder in the git repository.

Functions

playerctl_player_manager_new ()

PlayerctlPlayerManager *
playerctl_player_manager_new (GError **err);

Create a new player manager that contains a list of player names available in the “player-names” property. You can create new players from the names with the playerctl_player_new_from_name() function and then start managing them with the playerctl_player_manager_manage_player() function.

Parameters

err

The location of a GError or NULL.

[allow-none]

Returns

A new PlayerctlPlayerManager.

[transfer full]

playerctl_player_manager_manage_player ()

void
playerctl_player_manager_manage_player
                               (PlayerctlPlayerManager *manager,
                                PlayerctlPlayer *player);

Add the given player to the list of managed players. Takes a reference to the player (so you can unref it after you call this function). The player will automatically be unreffed and removed from the list of “players” when it disconnects and the “player-vanished” signal will be emitted on the manager.

Parameters

manager	A PlayerctlPlayerManager
player	A PlayerctlPlayer to manage

playerctl_player_manager_set_sort_func ()

void
playerctl_player_manager_set_sort_func
                               (PlayerctlPlayerManager *manager,
                                GCompareDataFunc sort_func,
                                gpointer sort_data,
                                GDestroyNotify notify);

Keeps the “players” list of this manager in sorted order which is useful for using this list as a priority queue.

Parameters

manager	A PlayerctlPlayerManager.
sort_func	The compare function to be used to sort the “players”.
sort_data	User data for the sort function.	[allow-none]
notify	A function to notify when the sort function will no longer be used.	[allow-none]

playerctl_player_manager_move_player_to_top ()

void
playerctl_player_manager_move_player_to_top
                               (PlayerctlPlayerManager *manager,
                                PlayerctlPlayer *player);

Moves the player to the top of the list of “players”. If this manager has a sort function set with playerctl_player_manager_set_sort_func(), the list of players will be sorted afterward, but will be on top of equal players in the sorted order.

Parameters

manager	A PlayerctlPlayerManager
player	A PlayerctlPlayer in the list of “players”

Property Details

The `“player-names”` property

  “player-names”             gpointer

A list of fully qualified player names that are currently available to control.

[type GList(PlayerctlPlayerName)]

Owner: PlayerctlPlayerManager

Flags: Read

The `“players”` property

  “players”                  gpointer

A list of players that are currently connected and managed by this class.

[type GList(PlayerctlPlayer)]

Owner: PlayerctlPlayerManager

Flags: Read

Signal Details

The `“name-appeared”` signal

void
user_function (PlayerctlPlayerManager *self,
               PlayerctlPlayerName    *name,
               gpointer                user_data)

Emitted when a new name has appeared and is available to connect to. Use playerctl_player_new_from_name() to connect to the player and playerctl_player_manager_manage_player() to add it to the managed list of players.

Parameters

self	the PlayerctlPlayerManager on which the signal was emitted
name	A PlayerctlPlayerName containing information about the name that has appeared.
user_data	user data set when the signal handler was connected.

Flags: Run Last

The `“name-vanished”` signal

void
user_function (PlayerctlPlayerManager *self,
               PlayerctlPlayerName    *name,
               gpointer                user_data)

Emitted when the name has vanished and is no longer available to be controlled by playerctl. If the player is managed, it will automatically be removed from the list of players and the “player-vanished” signal will be emitted automatically.

Parameters

self	the PlayerctlPlayerManager on which this signal was emitted.
name	The PlayerctlPlayerName containing connection information about the name that is going away.
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“player-appeared”` signal

void
user_function (PlayerctlPlayerManager *self,
               PlayerctlPlayer        *player,
               gpointer                user_data)

Emitted when a new player will be managed by this manager through a call to playerctl_player_manager_manage_player().

Parameters

self	The PlayerctlPlayerManager on which this event was emitted.
player	The PlayerctlPlayer that will be managed by this manager
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“player-vanished”` signal

void
user_function (PlayerctlPlayerManager *self,
               PlayerctlPlayer        *player,
               gpointer                user_data)

Emitted when a player has disconnected and will no longer be managed by this manager. The player is removed from the list of players automatically.

Parameters

self	The PlayerctlPlayerManager on which this event was emitted.
player	The PlayerctlPlayer that will no longer be managed by this manager
user_data	user data set when the signal handler was connected.

Flags: Run First