## 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.