## gva-nplayers

gva-nplayers — Number of Players Information

## Synopsis

    gboolean            gva_nplayers_init                   (GError **error);
    gboolean            gva_nplayers_lookup                 (const gchar *game,
                                                             gint *max_alternating,
                                                             gint *max_simultaneous,
                                                             GError **error);
    const gchar *       gva_nplayers_describe               (gint max_alternating,
                                                             gint max_simultaneous);

## Description

These functions provide a the maximum number of players for a game and whether the play is alternating or simultaneous. The information is read from a `nplayers.ini` file.

## Details

### gva_nplayers_init ()

    gboolean            gva_nplayers_init                   (GError **error);

Loads the number of players file. If an error occurs, it returns `FALSE` and sets `error`.

This function should be called once when the application starts.

`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_nplayers_lookup ()

    gboolean            gva_nplayers_lookup                 (const gchar *game,
                                                             gint *max_alternating,
                                                             gint *max_simultaneous,
                                                             GError **error);

Returns the maximum number of alternating and/or simultaneous players for `game`. If `game` only allows alternating players, `max_simultaneous` will be zero. If `game` only allows simultaneous players, `max_alternating` will be zero. If `game` is listed in the file but the number of players is unknown or cannot be parsed, both `max_alternating` and `max_simultaneous` will be zero. In all of these cases the function returns `TRUE`.

If an error occurs, the function returns `FALSE` and sets `error`, leaving `max_alternating` and `max_simultaneous` unaltered.

`game` : | the name of a game
`max_alternating` : | return location for the maximum alternating players
`max_simultaneous` : | return location for the maximum simultaneous players
`error` : | return location for a GError, or `NULL`
Returns : | `TRUE` on success, `FALSE` if an error occurred

### gva_nplayers_describe ()

    const gchar *       gva_nplayers_describe               (gint max_alternating,
                                                             gint max_simultaneous);

Returns a human-readable description of the number of players a game supports and whether the players alternate, play simultaneously, or both. If a description can not be formed, the function returns `NULL`.

`max_alternating` : | the maximum alternating players
`max_simultaneous` : | the maximum simultaneous players
Returns : | a human-readable description