mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-08-01 15:03:39 +02:00
gdbusnameowning: Convert docs to gi-docgen linking syntax
Improve formatting while I’m there, and try and ensure all the docs in these two files matches the [guidelines](https://developer.gnome.org/documentation/guidelines/devel-docs.html#writing-api-references). Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3250
This commit is contained in:
@@ -502,22 +502,21 @@ connection_get_cb (GObject *source_object,
|
||||
|
||||
/**
|
||||
* g_bus_own_name_on_connection:
|
||||
* @connection: a #GDBusConnection
|
||||
* @connection: a bus connection
|
||||
* @name: the well-known name to own
|
||||
* @flags: a set of flags from the #GBusNameOwnerFlags enumeration
|
||||
* @flags: a set of flags with ownership options
|
||||
* @name_acquired_handler: (nullable) (scope notified): handler to invoke when
|
||||
* @name is acquired or %NULL
|
||||
* @name is acquired, or `NULL` to ignore
|
||||
* @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
|
||||
* is lost or %NULL
|
||||
* is lost, or `NULL` to ignore
|
||||
* @user_data: user data to pass to handlers
|
||||
* @user_data_free_func: (nullable): function for freeing @user_data or %NULL
|
||||
* @user_data_free_func: (nullable): function for freeing @user_data
|
||||
*
|
||||
* Like g_bus_own_name() but takes a #GDBusConnection instead of a
|
||||
* #GBusType.
|
||||
* Like [func@Gio.bus_own_name] but takes a [class@Gio.DBusConnection] instead
|
||||
* of a [enum@Gio.BusType].
|
||||
*
|
||||
* Returns: an identifier (never 0) that can be used with
|
||||
* g_bus_unown_name() to stop owning the name
|
||||
*
|
||||
* [func@Gio.bus_unown_name] to stop owning the name
|
||||
* Since: 2.26
|
||||
*/
|
||||
guint
|
||||
@@ -568,47 +567,48 @@ g_bus_own_name_on_connection (GDBusConnection *connection,
|
||||
* g_bus_own_name:
|
||||
* @bus_type: the type of bus to own a name on
|
||||
* @name: the well-known name to own
|
||||
* @flags: a set of flags from the #GBusNameOwnerFlags enumeration
|
||||
* @flags: a set of flags with ownership options
|
||||
* @bus_acquired_handler: (nullable) (scope notified): handler to invoke when
|
||||
* connected to the bus of type @bus_type or %NULL
|
||||
* connected to the bus of type @bus_type, or `NULL` to ignore
|
||||
* @name_acquired_handler: (nullable) (scope notified): handler to invoke when
|
||||
* @name is acquired or %NULL
|
||||
* @name is acquired, or `NULL` to ignore
|
||||
* @name_lost_handler: (nullable) (scope notified): handler to invoke when @name
|
||||
* is lost or %NULL
|
||||
* is lost, or `NULL` to ignore
|
||||
* @user_data: user data to pass to handlers
|
||||
* @user_data_free_func: (nullable): function for freeing @user_data or %NULL
|
||||
* @user_data_free_func: (nullable): function for freeing @user_data
|
||||
*
|
||||
* Starts acquiring @name on the bus specified by @bus_type and calls
|
||||
* @name_acquired_handler and @name_lost_handler when the name is
|
||||
* acquired respectively lost. Callbacks will be invoked in the thread-default
|
||||
* 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 [method@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
|
||||
* 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)
|
||||
*
|
||||
* - @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, just call g_bus_unown_name()
|
||||
* with the owner id this function returns.
|
||||
* When you are done owning the name, call [func@Gio.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 #GDBusConnection that is used for attempting to own the name
|
||||
* If the [class@Gio.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 g_bus_own_name() several times for the same name (unless
|
||||
* interleaved with calls to g_bus_unown_name()) - only the first call
|
||||
* You cannot use [func@Gio.bus_own_name] several times for the same name (unless
|
||||
* interleaved with calls to [func@Gio.bus_unown_name]) — only the first call
|
||||
* will work.
|
||||
*
|
||||
* Another guarantee is that invocations of @name_acquired_handler
|
||||
@@ -617,20 +617,19 @@ g_bus_own_name_on_connection (GDBusConnection *connection,
|
||||
* 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 e.g.
|
||||
* g_dbus_connection_register_object()), note that it is generally too late
|
||||
* If you plan on exporting objects (using, for example,
|
||||
* [method@Gio.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 wants
|
||||
* This behavior makes it very simple to write applications that want
|
||||
* to [own names](dbus-name-owning.html#d-bus-name-owning) and export objects.
|
||||
* Simply register objects to be exported in @bus_acquired_handler and
|
||||
* unregister the objects (if any) in @name_lost_handler.
|
||||
*
|
||||
* Returns: an identifier (never 0) that can be used with
|
||||
* g_bus_unown_name() to stop owning the name.
|
||||
*
|
||||
* [func@Gio.bus_unown_name] to stop owning the name
|
||||
* Since: 2.26
|
||||
*/
|
||||
guint
|
||||
@@ -802,20 +801,19 @@ bus_own_name_free_func (gpointer user_data)
|
||||
* g_bus_own_name_with_closures: (rename-to g_bus_own_name)
|
||||
* @bus_type: the type of bus to own a name on
|
||||
* @name: the well-known name to own
|
||||
* @flags: a set of flags from the #GBusNameOwnerFlags enumeration
|
||||
* @bus_acquired_closure: (nullable): #GClosure to invoke when connected to
|
||||
* the bus of type @bus_type or %NULL
|
||||
* @name_acquired_closure: (nullable): #GClosure to invoke when @name is
|
||||
* acquired or %NULL
|
||||
* @name_lost_closure: (nullable): #GClosure to invoke when @name is lost or
|
||||
* %NULL
|
||||
* @flags: a set of flags with ownership options
|
||||
* @bus_acquired_closure: (nullable): closure to invoke when connected to
|
||||
* the bus of type @bus_type, or `NULL` to ignore
|
||||
* @name_acquired_closure: (nullable): closure to invoke when @name is
|
||||
* acquired, or `NULL` to ignore
|
||||
* @name_lost_closure: (nullable): closure to invoke when @name is lost, or
|
||||
* `NULL` to ignore
|
||||
*
|
||||
* Version of g_bus_own_name() using closures instead of callbacks for
|
||||
* Version of [func@Gio.bus_own_name using closures instead of callbacks for
|
||||
* easier binding in other languages.
|
||||
*
|
||||
* Returns: an identifier (never 0) that can be used with
|
||||
* g_bus_unown_name() to stop owning the name.
|
||||
*
|
||||
* [func@Gio.bus_unown_name] to stop owning the name.
|
||||
* Since: 2.26
|
||||
*/
|
||||
guint
|
||||
@@ -840,20 +838,19 @@ g_bus_own_name_with_closures (GBusType bus_type,
|
||||
|
||||
/**
|
||||
* g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
|
||||
* @connection: a #GDBusConnection
|
||||
* @connection: a bus connection
|
||||
* @name: the well-known name to own
|
||||
* @flags: a set of flags from the #GBusNameOwnerFlags enumeration
|
||||
* @name_acquired_closure: (nullable): #GClosure to invoke when @name is
|
||||
* acquired or %NULL
|
||||
* @name_lost_closure: (nullable): #GClosure to invoke when @name is lost
|
||||
* or %NULL
|
||||
* @flags: a set of flags with ownership options
|
||||
* @name_acquired_closure: (nullable): closure to invoke when @name is
|
||||
* acquired, or `NULL` to ignore
|
||||
* @name_lost_closure: (nullable): closure to invoke when @name is lost,
|
||||
* or `NULL` to ignore
|
||||
*
|
||||
* Version of g_bus_own_name_on_connection() using closures instead of
|
||||
* Version of [func@Gio.bus_own_name_on_connection] using closures instead of
|
||||
* callbacks for easier binding in other languages.
|
||||
*
|
||||
* Returns: an identifier (never 0) that can be used with
|
||||
* g_bus_unown_name() to stop owning the name.
|
||||
*
|
||||
* [func@Gio.bus_unown_name] to stop owning the name.
|
||||
* Since: 2.26
|
||||
*/
|
||||
guint
|
||||
@@ -876,16 +873,17 @@ g_bus_own_name_on_connection_with_closures (GDBusConnection *connection,
|
||||
|
||||
/**
|
||||
* g_bus_unown_name:
|
||||
* @owner_id: an identifier obtained from g_bus_own_name()
|
||||
* @owner_id: an identifier obtained from [func@Gio.bus_own_name]
|
||||
*
|
||||
* Stops owning a name.
|
||||
*
|
||||
* Note that there may still be D-Bus traffic to process (relating to owning
|
||||
* and unowning the name) in the current thread-default #GMainContext after
|
||||
* this function has returned. You should continue to iterate the #GMainContext
|
||||
* until the #GDestroyNotify function passed to g_bus_own_name() is called, in
|
||||
* order to avoid memory leaks through callbacks queued on the #GMainContext
|
||||
* after it’s stopped being iterated.
|
||||
* and unowning the name) in the current thread-default
|
||||
* [struct@GLib.MainContext] after this function has returned. You should
|
||||
* continue to iterate the [struct@GLib.MainContext] until the
|
||||
* [callback@GLib.DestroyNotify] function passed to [func@Gio.bus_own_name] is
|
||||
* called, in order to avoid memory leaks through callbacks queued on the
|
||||
* [struct@GLib.MainContext] after it’s stopped being iterated.
|
||||
*
|
||||
* Since: 2.26
|
||||
*/
|
||||
|
@@ -33,9 +33,9 @@ G_BEGIN_DECLS
|
||||
|
||||
/**
|
||||
* GBusAcquiredCallback:
|
||||
* @connection: The #GDBusConnection to a message bus.
|
||||
* @name: The name that is requested to be owned.
|
||||
* @user_data: User data passed to g_bus_own_name().
|
||||
* @connection: the connection to a message bus
|
||||
* @name: the name that is requested to be owned
|
||||
* @user_data: user data passed to [func@Gio.bus_own_name]
|
||||
*
|
||||
* Invoked when a connection to a message bus has been obtained.
|
||||
*
|
||||
@@ -47,9 +47,10 @@ typedef void (*GBusAcquiredCallback) (GDBusConnection *connection,
|
||||
|
||||
/**
|
||||
* GBusNameAcquiredCallback:
|
||||
* @connection: The #GDBusConnection on which to acquired the name.
|
||||
* @name: The name being owned.
|
||||
* @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
|
||||
* @connection: the connection on which to acquired the name
|
||||
* @name: the name being owned
|
||||
* @user_data: user data passed to [func@Gio.bus_own_name] or
|
||||
* [func@Gio.bus_own_name_on_connection]
|
||||
*
|
||||
* Invoked when the name is acquired.
|
||||
*
|
||||
@@ -61,10 +62,11 @@ typedef void (*GBusNameAcquiredCallback) (GDBusConnection *connection,
|
||||
|
||||
/**
|
||||
* GBusNameLostCallback:
|
||||
* @connection: The #GDBusConnection on which to acquire the name or %NULL if
|
||||
* the connection was disconnected.
|
||||
* @name: The name being owned.
|
||||
* @user_data: User data passed to g_bus_own_name() or g_bus_own_name_on_connection().
|
||||
* @connection: the connect on which to acquire the name or `NULL` if
|
||||
* the connection was disconnected
|
||||
* @name: the name being owned
|
||||
* @user_data: user data passed to [func@Gio.bus_own_name] or
|
||||
* [func@Gio.bus_own_name_on_connection]
|
||||
*
|
||||
* Invoked when the name is lost or @connection has been closed.
|
||||
*
|
||||
|
Reference in New Issue
Block a user