## gnome-score

gnome-score — Tracking best scores for games

## Synopsis

    #include <libgnome/libgnome.h>

    gint        gnome_score_init                (const gchar *gamename);
    gint        gnome_score_log                 (gfloat score,
                                                 const gchar *level,
                                                 gboolean higher_to_lower_score_order);
    gint        gnome_score_get_notable         (const gchar *gamename,
                                                 const gchar *level,
                                                 gchar ***names,
                                                 gfloat **scores,
                                                 time_t **scoretimes);

## Description

The routines in this module provide a simple way to keep track of users' scores in a game.

In order to acommodate file ownership permissions, the game application should be installed setgid games and the scoretable should only be writable by the games group. The program should call `gnome_score_init()` as soon as possible inside the `main()` routine. This will open a pair of pipes to a child process which can read and write the score table and then will drop the group privileges of the main program back to the user's normal group id.

## Details

### gnome_score_init ()

    gint        gnome_score_init                (const gchar *gamename);

GNOME games should call this routine as the first statement in `main()` if they have been installed setgid to the "games" group. It performs the intialization required to later record information in the scores table and then drops the groups privileges.

`gamename` : | Identifies the game name.
Returns : | `0` on success, returns `-1` on failure.

### gnome_score_log ()

    gint        gnome_score_log                 (gfloat score,
                                                 const gchar *level,
                                                 gboolean higher_to_lower_score_order);

Logs a score entry for the user. You should call this every time a game ends. This function takes care of working out whether the user's score made it into the ten best scores and, if so, records it in the table.

`score` : | The score achieved by the user in this game
`level` : | The level on which the score was obtained
`higher_to_lower_score_order` : | Set to `TRUE` if high scores are better than low scores.
Returns : | `0` on failure or the status from the gnome-score helper program.

### gnome_score_get_notable ()

    gint        gnome_score_get_notable         (const gchar *gamename,
                                                 const gchar *level,
                                                 gchar ***names,
                                                 gfloat **scores,
                                                 time_t **scoretimes);

Fetches the most notable players on `gamename` at level `level`.

`gamename` : | The name of the game we want to fetch information from.
`level` : | The level for which we want to pull information.
`names` : | An array of strings is returned at the address pointed here
`scores` : | An array of gfloats is returned at the address pointed here
`scoretimes` : | An array of time_t is returned at the address pointed here
Returns : | The number of scores returned. The `names`, `scores` and `scoretime` pointers point to regions that were allocated with `g_malloc()` with the contents.