InfUserTable: libinfinity-0.7 Reference Manual

## InfUserTable InfUserTable — User information storage |

## Stability Level

Unstable, unless otherwise indicated

## Functions

void | (*InfUserTableForeachUserFunc) ()
InfUserTable * | inf_user_table_new ()
void | inf_user_table_add_user ()
void | inf_user_table_remove_user ()
InfUser * | inf_user_table_lookup_user_by_id ()
InfUser * | inf_user_table_lookup_user_by_name ()
void | inf_user_table_foreach_user ()
void | inf_user_table_foreach_local_user ()

## Signals

void | add-available-user | Run Last
void | add-local-user | Run Last
void | add-user | Run Last
void | remove-available-user | Run Last
void | remove-local-user | Run Last
void | remove-user | Run Last

## Types and Values

struct | InfUserTable
struct | InfUserTableClass

## Object Hierarchy

        GObject
        ╰── InfUserTable

## Includes

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

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

## Functions

### 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()`.

#### Parameters

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()`. |

### inf_user_table_new ()

    InfUserTable *
    inf_user_table_new (void);

Creates a new, empty user table.

[constructor]

#### Returns

A InfUserTable.

[transfer full]

### inf_user_table_add_user ()

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

Inserts `user` into `user_table` .

#### Parameters

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

#### Parameters

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

#### Parameters

user_table | A InfUserTable. |
id | User ID to lookup. |

#### Returns

A InfUser, or `NULL`.

[transfer none][allow-none]

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

#### Parameters

user_table | A InfUserTable. |
name | User name to lookup. |

#### Returns

A InfUser, or `NULL`.

[transfer none][allow-none]

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

#### Parameters

user_table | A InfUserTable. |
func | The function to call for each user. | [scope call]
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.

#### Parameters

user_table | A InfUserTable. |
func | The function to call for each user. | [scope call]
user_data | User data to pass to the function. |

## Types and Values

### struct InfUserTable

    struct 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_available_user)(InfUserTable* user_table,
                                InfUser* user);

      void(*remove_available_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.

#### Members

`add_user` () | Default signal handler for the “add_user” signal. |
`remove_user` () | Default signal handler for the “remove_user” signal. |
`add_available_user` () | Default signal handler for the “add-available-user” signal. |
`remove_available_user` () | Default signal handler for the “remove-available-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. |

## Signal Details

### The `“add-available-user”` signal

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

This signal is emitted when a user in the user table becomes available, i.e. its status is not `INF_USER_UNAVAILABLE`. The signal is also emitted when a new user is added to the user table who is available, in addition to “add-user” and possibly “add-local-user”.

#### Parameters

user_table | The InfUserTable in which `user` became available. |
user | The InfUser that became available. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“add-local-user”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“add-user”` signal

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

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.

#### Parameters

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

Flags: Run Last

### The `“remove-available-user”` signal

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

This signal is emitted when a user in the user table became unavailable, i.e. its status has changed to `INF_USER_UNAVAILABLE`. The signal is also emitted when a user who was available has been removed from the user table, in addition to “remove-user” and possibly “remove-local-user”.

#### Parameters

user_table | The InfUserTable in which `user` became unavailable. |
user | The InfUser that became unavailable. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“remove-local-user”` signal

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

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

#### Parameters

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

Flags: Run Last

### The `“remove-user”` signal

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

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.

#### Parameters

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

Flags: Run Last

## See Also

InfUser, InfSession