## InfUserTable InfUserTable — User information storage |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libinfinity/common/inf-user-table.h>

    void                (*InfUserTableForeachUserFunc)      (InfUser *user,
                                                             gpointer user_data);
                        InfUserTable;
    struct              InfUserTableClass;
    InfUserTable *      inf_user_table_new                  (void);
    void                inf_user_table_add_user             (InfUserTable *user_table,
                                                             InfUser *user);
    void                inf_user_table_remove_user          (InfUserTable *user_table,
                                                             InfUser *user);
    InfUser *           inf_user_table_lookup_user_by_id    (InfUserTable *user_table,
                                                             guint id);
    InfUser *           inf_user_table_lookup_user_by_name  (InfUserTable *user_table,
                                                             const gchar *name);
    void                inf_user_table_foreach_user         (InfUserTable *user_table,
                                                             InfUserTableForeachUserFunc func,
                                                             gpointer user_data);
    void                inf_user_table_foreach_local_user   (InfUserTable *user_table,
                                                             InfUserTableForeachUserFunc func,
                                                             gpointer user_data);

## Object Hierarchy

      GObject
       +----InfUserTable

## Signals

      "add-local-user"                                 : Run Last
      "add-user"                                       : Run Last
      "remove-local-user"                              : Run Last
      "remove-user"                                    : Run Last

## Description

InfUserTable manages multiple InfUser objects and provides an easy way to look up users by their ID and name. All users within a user table must have a unique ID and name. The user table is used by InfSession to store the users within the session.

## Details

### InfUserTableForeachUserFunc ()

    void                (*InfUserTableForeachUserFunc)      (InfUser *user,
                                                             gpointer user_data);

This callback is called for every user iterated by `inf_user_table_foreach_user()` or `inf_user_table_foreach_local_user()`.

`user` : | The InfUser for the current iteration.
`user_data` : | The user_data passed to `inf_user_table_foreach_user()` or `inf_user_table_foreach_local_user()`.

### InfUserTable

    typedef struct _InfUserTable InfUserTable;

InfUserTable is an opaque data type. You should only access it via the public API functions.

### struct InfUserTableClass

    struct InfUserTableClass {
      void(*add_user)(InfUserTable* user_table,
                      InfUser* user);

      void(*remove_user)(InfUserTable* user_table,
                         InfUser* user);

      void(*add_local_user)(InfUserTable* user_table,
                            InfUser* user);

      void(*remove_local_user)(InfUserTable* user_table,
                               InfUser* user);
    };

Signals for the InfUserTable class.

`add_user` () | Default signal handler for the "add_user" signal.
`remove_user` () | Default signal handler for the "remove_user" signal.
`add_local_user` () | Default signal handler for the "add_local_user" signal.
`remove_local_user` () | Default signal handler for the "remove_local_user" signal.

### inf_user_table_new ()

    InfUserTable *      inf_user_table_new                  (void);

Creates a new, empty user table.

Returns : | A InfUserTable.

### inf_user_table_add_user ()

    void                inf_user_table_add_user             (InfUserTable *user_table,
                                                             InfUser *user);

Inserts `user` into `user_table`.

`user_table` : | A InfUserTable.
`user` : | A InfUser not already contained in `user_table`.

### inf_user_table_remove_user ()

    void                inf_user_table_remove_user          (InfUserTable *user_table,
                                                             InfUser *user);

Removes `user` from `uesr_table`.

`user_table` : | A InfUserTable.
`user` : | A InfUser contained in `table`.

### inf_user_table_lookup_user_by_id ()

    InfUser *           inf_user_table_lookup_user_by_id    (InfUserTable *user_table,
                                                             guint id);

Returns the InfUser with the given User ID in `user_table`.

`user_table` : | A InfUserTable.
`id` : | User ID to lookup.
Returns : | A InfUser, or `NULL`.

### inf_user_table_lookup_user_by_name ()

    InfUser *           inf_user_table_lookup_user_by_name  (InfUserTable *user_table,
                                                             const gchar *name);

Returns an InfUser with the given name if there is one.

`user_table` : | A InfUserTable.
`name` : | User name to lookup.
Returns : | A InfUser, or `NULL`.

### inf_user_table_foreach_user ()

    void                inf_user_table_foreach_user         (InfUserTable *user_table,
                                                             InfUserTableForeachUserFunc func,
                                                             gpointer user_data);

Calls the given function for each user in the user_table. You should not add or remove users while this function is being executed.

`user_table` : | A InfUserTable.
`func` : | The function to call for each user.
`user_data` : | User data to pass to the function.

### inf_user_table_foreach_local_user ()

    void                inf_user_table_foreach_local_user   (InfUserTable *user_table,
                                                             InfUserTableForeachUserFunc func,
                                                             gpointer user_data);

Calls the given function for each local user in the user_table. A local user is a user that has the `INF_USER_LOCAL` flag set and that has not status `INF_USER_UNAVAILABLE`. You should not add or remove users while this function is being executed.

`user_table` : | A InfUserTable.
`func` : | The function to call for each user.
`user_data` : | User data to pass to the function.

## Signal Details

### The `"add-local-user"` signal

    void                user_function                      (InfUserTable *user_table,
                                                            InfUser      *user,
                                                            gpointer      user_data)       : Run Last

This signal is emitted when a user is added to the user table and has the `INF_USER_LOCAL` flag set. In this case, "add-user" is emitted as well.

This signal is also emitted when an existing user receives the `INF_USER_LOCAL` flag. This occurs when a user rejoins locally after leaving the session (possibly having the `INF_USER_LOCAL` flag removed during their absence). "add-user" is not emitted in this case.

`user_table` : | The InfUserTable in which `user` has been set as local
`user` : | The InfUser that has set as local
`user_data` : | user data set when the signal handler was connected.

### The `"add-user"` signal

    void                user_function                      (InfUserTable *user_table,
                                                            InfUser      *user,
                                                            gpointer      user_data)       : Run Last

This signal is emitted when `inf_user_table_add_user()` is called. Note that this does not happen if `user` rejoins the session and has already been added to `user_table` previously.

"add-local-user" may also be emitted at this point if `user` has the `INF_USER_LOCAL` flag set.

`user_table` : | The InfUserTable into which `user` has been added
`user` : | The InfUser that has been added into `user_table`
`user_data` : | user data set when the signal handler was connected.

### The `"remove-local-user"` signal

    void                user_function                      (InfUserTable *user_table,
                                                            InfUser      *user,
                                                            gpointer      user_data)       : Run Last

This signal is emitted when a user is removed from the user table and had the `INF_USER_LOCAL` flag set. In this case, "remove-user" is emitted as well.

This signal is also emitted when `user` loses the `INF_USER_LOCAL` flag. This occurs when the local `user` leaves the session. "remove-user" is not emitted and the status of `user` is set to `INF_USER_UNAVAILABLE`.

`user_table` : | The InfUserTable in which `user` is no longer local
`user` : | The InfUser that is no longer local
`user_data` : | user data set when the signal handler was connected.

### The `"remove-user"` signal

    void                user_function                      (InfUserTable *user_table,
                                                            InfUser      *user,
                                                            gpointer      user_data)       : Run Last

This signal is emitted when `inf_user_table_remove_user()` is called. This does not usually happen, as users leaving a session do not get removed from the table.

"remove-local-user" may also be emitted at this point if `user` has the `INF_USER_LOCAL` flag set.

`user_table` : | The InfUserTable from which `user` has been remove
`user` : | The InfUser that has been removed from `user_table`
`user_data` : | user data set when the signal handler was connected.

## See Also

InfUser, InfSession