## EggDBusBusNameTracker EggDBusBusNameTracker — Track bus names |

## Synopsis

                        EggDBusBusNameTracker;
    EggDBusBusNameTracker * egg_dbus_bus_name_tracker_new   (EggDBusBus *bus);
    void                egg_dbus_bus_name_tracker_watch_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);
    void                egg_dbus_bus_name_tracker_stop_watching_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);
    gboolean            egg_dbus_bus_name_tracker_has_info_for_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);
    gchar *             egg_dbus_bus_name_tracker_get_owner_for_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);
    gchar **            egg_dbus_bus_name_tracker_get_known_well_known_bus_names_for_unique_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *unique_bus_name);

## Object Hierarchy

      GObject
       +----EggDBusBusNameTracker

## Properties

      "bus"                      EggDBusBus*           : Read / Write / Construct Only

## Signals

      "bus-name-gained-owner"                          : Run Last
      "bus-name-has-info"                              : Run Last
      "bus-name-lost-owner"                            : Run Last

## Description

The EggDBusBusNameTracker class is used for tracking bus names on a message bus.

If you are writing a D-Bus client there's no need to use this class as it's used internally by EggDBusConnection to maintain the "name-owner" property on object proxies.

## Details

### EggDBusBusNameTracker

    typedef struct _EggDBusBusNameTracker EggDBusBusNameTracker;

### egg_dbus_bus_name_tracker_new ()

    EggDBusBusNameTracker * egg_dbus_bus_name_tracker_new   (EggDBusBus *bus);

Creates a new bus name tracker for `bus`.

`bus` : | A EggDBusBus object that represents a message bus daemon.
Returns : | A EggDBusBusNameTracker.

### egg_dbus_bus_name_tracker_watch_bus_name ()

    void                egg_dbus_bus_name_tracker_watch_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);

Starts watching `bus_name`.

This function can be called multiple times for the same name; `bus_name_tracker` internally maintains a count of watchers for each watched name.

TODO: it would be useful to pass callback functions as well.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A unique or well-known name.

### egg_dbus_bus_name_tracker_stop_watching_bus_name ()

    void                egg_dbus_bus_name_tracker_stop_watching_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);

Stops watching `bus_name`.

This function can be called multiple times for the same name; `bus_name_tracker` internally maintains a count of watchers for each watched name.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A name being watched.

### egg_dbus_bus_name_tracker_has_info_for_bus_name ()

    gboolean            egg_dbus_bus_name_tracker_has_info_for_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);

Checks if information has been retrieved for `bus_name`. If this function returns `FALSE`, you can connect to the "bus-name-has-info" signal and use `egg_dbus_bus_name_tracker_get_owner_for_bus_name()` to retrieve the owner when information is available.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A name being watched.
Returns : | `TRUE` if `bus_name_tracker` has information about `bus_name`.

### egg_dbus_bus_name_tracker_get_owner_for_bus_name ()

    gchar *             egg_dbus_bus_name_tracker_get_owner_for_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *bus_name);

Gets owner of `bus_name`.

If `bus_name_tracker` recently started watching `bus_name`, a call to `egg_dbus_bus_get_name_owner()` call may be still be pending. This function will block in a main loop until the owner is resolved.

If this synchronous behavior is not desired, use call `egg_dbus_bus_name_tracker_has_info_for_bus_name()` and connect to the "bus-name-has-info" signal to get informed when owner information is available.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A name being watched.
Returns : | The owner of `bus_name` or `NULL` if there is no owner. Free with `g_free()`.

### egg_dbus_bus_name_tracker_get_known_well_known_bus_names_for_unique_bus_name ()

    gchar **            egg_dbus_bus_name_tracker_get_known_well_known_bus_names_for_unique_bus_name
                                                            (EggDBusBusNameTracker *bus_name_tracker,
                                                             const gchar *unique_bus_name);

Returns the known set (e.g. only the set of well-known bus names currently being watched) of well-known bus names that `unique_bus_name` owns.

This function is used to dispatch signals to proxies in EggDBusConnection; it is probably not of much general use.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`unique_bus_name` : | A unique or well-known bus name earlier passed to `egg_dbus_bus_name_tracker_watch_bus_name()`.
Returns : | An `NULL` terminated array of well-known bus names or `NULL` if there are no known well-known bus names owned by `unique_bus_name`. Free with `g_strfreev()`.

## Property Details

### The `"bus"` property

      "bus"                      EggDBusBus*           : Read / Write / Construct Only

The bus we're tracking names for.

## Signal Details

### The `"bus-name-gained-owner"` signal

    void                user_function                      (EggDBusBusNameTracker *bus_name_tracker,
                                                            gchar                 *bus_name,
                                                            gchar                 *new_owner,
                                                            gpointer               user_data)             : Run Last

Emitted when `new_owner` gains ownership of `bus_name`.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A bus name being watched.
`new_owner` : | A unique bus name.
`user_data` : | user data set when the signal handler was connected.

### The `"bus-name-has-info"` signal

    void                user_function                      (EggDBusBusNameTracker *bus_name_tracker,
                                                            gchar                 *bus_name,
                                                            gpointer               user_data)             : Run Last

Emitted when `bus_name_tracker` has information about `bus_name`.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A bus name being watched.
`user_data` : | user data set when the signal handler was connected.

### The `"bus-name-lost-owner"` signal

    void                user_function                      (EggDBusBusNameTracker *bus_name_tracker,
                                                            gchar                 *bus_name,
                                                            gchar                 *old_owner,
                                                            gpointer               user_data)             : Run Last

Emitted when `old_owner` loses ownership of `bus_name`.

`bus_name_tracker` : | A EggDBusBusNameTracker.
`bus_name` : | A bus name being watched.
`old_owner` : | A unique bus name.
`user_data` : | user data set when the signal handler was connected.