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