luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-03 07:53:39 +02:00
Code Issues Packages Projects Releases Wiki Activity

gdbusnameowning: Convert docs to gi-docgen linking syntax

Browse Source 
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:
Philip Withnall
2025-03-19 20:38:38 +00:00
parent 88e8ee515c
commit da12657e8b
2 changed files with 69 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
gio/gdbusnameowning.c
View File

@@ -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
*/

22
gio/gdbusnameowning.h
View File

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