gio

Function bus_own_name

Source 
pub fn bus_own_name<BusAcquired, NameAcquired, NameLost>(
    bus_type: BusType,
    name: &str,
    flags: BusNameOwnerFlags,
    bus_acquired: BusAcquired,
    name_acquired: NameAcquired,
    name_lost: NameLost,
) -> OwnerId
where
    BusAcquired: Fn(DBusConnection, &str) + 'static,
    NameAcquired: Fn(DBusConnection, &str) + 'static,
    NameLost: Fn(Option<DBusConnection>, &str) + 'static,
Expand description

Requests ownership of @name on the bus specified by @bus_type.

It asynchronously calls @name_acquired_handler and @name_lost_handler when the name is acquired and lost, respectively.

Callbacks will be invoked in the thread-default main context (see [glib::MainContext::push_thread_default()][crate::glib::MainContext::push_thread_default()]) of the thread you are calling this function from.

You are guaranteed that one of the @name_acquired_handler and @name_lost_handler callbacks will be invoked after calling this function — there are three possible cases:

  • @name_lost_handler with a NULL connection (if a connection to the bus can’t be made).
  • @bus_acquired_handler then @name_lost_handler (if the name can’t be obtained).
  • @bus_acquired_handler then @name_acquired_handler (if the name was obtained).

When you are done owning the name, call bus_unown_name() with the owner ID this function returns.

If the name is acquired or lost (for example another application could acquire the name if you allow replacement or the application currently owning the name exits), the handlers are also invoked. If the DBusConnection that is used for attempting to own the name closes, then @name_lost_handler is invoked since it is no longer possible for other processes to access the process.

You cannot use bus_own_name() several times for the same name (unless interleaved with calls to bus_unown_name()) — only the first call will work.

Another guarantee is that invocations of @name_acquired_handler and @name_lost_handler are guaranteed to alternate; that is, if @name_acquired_handler is invoked then you are guaranteed that the next time one of the handlers is invoked, it will be @name_lost_handler. The reverse is also true.

If you plan on exporting objects (using, for example, DBusConnection::register_object()), note that it is generally too late to export the objects in @name_acquired_handler. Instead, you can do this in @bus_acquired_handler since you are guaranteed that this will run before @name is requested from the bus.

This behavior makes it very simple to write applications that want to own names and export objects. Simply register objects to be exported in @bus_acquired_handler and unregister the objects (if any) in @name_lost_handler.

§bus_type

the type of bus to own a name on

§name

the well-known name to own

§flags

a set of flags with ownership options

§bus_acquired_handler

handler to invoke when connected to the bus of type @bus_type, or NULL to ignore

§name_acquired_handler

handler to invoke when @name is acquired, or NULL to ignore

§name_lost_handler

handler to invoke when @name is lost, or NULL to ignore

§Returns

an identifier (never 0) that can be used with bus_unown_name() to stop owning the name

OSZAR »