luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-25 19:52:10 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'migrate-to-gi-docgen4' into 'main'

Browse Source 
Switch to using gi-docgen for docs (batch 4)

See merge request GNOME/glib!3647
This commit is contained in:
Philip Withnall 2023-10-17 13:12:23 +00:00
commit 1a659d630d
40 changed files with 410 additions and 615 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
gio/gaction.c
View File

@ -28,47 +28,37 @@
G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT) G_DEFINE_INTERFACE (GAction, g_action, G_TYPE_OBJECT)
/** /**
* SECTION:gaction * GAction:
* @title: GAction
* @short_description: An action interface
* @include: gio/gio.h
* *
* #GAction represents a single named action. * `GAction` represents a single named action.
* *
* The main interface to an action is that it can be activated with * The main interface to an action is that it can be activated with
* g_action_activate(). This results in the 'activate' signal being * [method@Gio.Action.activate]. This results in the 'activate' signal being
* emitted. An activation has a #GVariant parameter (which may be * emitted. An activation has a `GVariant` parameter (which may be
* %NULL). The correct type for the parameter is determined by a static * `NULL`). The correct type for the parameter is determined by a static
* parameter type (which is given at construction time). * parameter type (which is given at construction time).
* *
* An action may optionally have a state, in which case the state may be * An action may optionally have a state, in which case the state may be
* set with g_action_change_state(). This call takes a #GVariant. The * set with [method@Gio.Action.change_state]. This call takes a #GVariant. The
* correct type for the state is determined by a static state type * correct type for the state is determined by a static state type
* (which is given at construction time). * (which is given at construction time).
* *
* The state may have a hint associated with it, specifying its valid * The state may have a hint associated with it, specifying its valid
* range. * range.
* *
* #GAction is merely the interface to the concept of an action, as * `GAction` is merely the interface to the concept of an action, as
* described above. Various implementations of actions exist, including * described above. Various implementations of actions exist, including
* #GSimpleAction. * [struct@Gio.SimpleAction].
* *
* In all cases, the implementing class is responsible for storing the * In all cases, the implementing class is responsible for storing the
* name of the action, the parameter type, the enabled state, the * name of the action, the parameter type, the enabled state, the optional
* optional state type and the state and emitting the appropriate * state type and the state and emitting the appropriate signals when these
* signals when these change. The implementor is responsible for filtering * change. The implementor is responsible for filtering calls to
* calls to g_action_activate() and g_action_change_state() for type * [method@Gio.Action.activate] and [method@Gio.Action.change_state]
* safety and for the state being enabled. * for type safety and for the state being enabled.
* *
* Probably the only useful thing to do with a #GAction is to put it * Probably the only useful thing to do with a `GAction` is to put it
* inside of a #GSimpleActionGroup. * inside of a [struct@Gio.SimpleActionGroup].
**/
/**
* GAction:
*
* #GAction is an opaque data structure and can only be accessed
* using the following functions.
**/ **/
/** /**

64
gio/gactiongroup.c
View File

@ -26,31 +26,26 @@
#include "gmarshal-internal.h" #include "gmarshal-internal.h"
/** /**
* SECTION:gactiongroup * GActionGroup:
* @title: GActionGroup
* @short_description: A group of actions
* @include: gio/gio.h
* @see_also: #GAction
* *
* #GActionGroup represents a group of actions. Actions can be used to * `GActionGroup` represents a group of actions.
* expose functionality in a structured way, either from one part of a
* program to another, or to the outside world. Action groups are often
* used together with a #GMenuModel that provides additional
* representation data for displaying the actions to the user, e.g. in
* a menu.
* *
* The main way to interact with the actions in a GActionGroup is to * Actions can be used to expose functionality in a structured way, either
* activate them with g_action_group_activate_action(). Activating an * from one part of a program to another, or to the outside world. Action
* action may require a #GVariant parameter. The required type of the * groups are often used together with a `GMenuModel` that provides additional
* parameter can be inquired with g_action_group_get_action_parameter_type(). * representation data for displaying the actions to the user, e.g. in a menu.
* Actions may be disabled, see g_action_group_get_action_enabled(). *
* The main way to interact with the actions in a `GActionGroup` is to
* activate them with [method@Gio.ActionGroup.activate_action]. Activating an
* action may require a `GVariant` parameter. The required type of the
* parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type].
* Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled].
* Activating a disabled action has no effect. * Activating a disabled action has no effect.
* *
* Actions may optionally have a state in the form of a #GVariant. The * Actions may optionally have a state in the form of a #GVariant. The current
* current state of an action can be inquired with * state of an action can be inquired with [method@Gio.ActionGroup.get_action_state].
* g_action_group_get_action_state(). Activating a stateful action may * Activating a stateful action may change its state, but it is also possible to
* change its state, but it is also possible to set the state by calling * set the state by calling [method@Gio.ActionGroup.change_action_state].
* g_action_group_change_action_state().
* *
* As typical example, consider a text editing application which has an * As typical example, consider a text editing application which has an
* option to change the current font to 'bold'. A good way to represent * option to change the current font to 'bold'. A good way to represent
@ -58,34 +53,27 @@
* action would toggle the state. * action would toggle the state.
* *
* Each action in the group has a unique name (which is a string). All * Each action in the group has a unique name (which is a string). All
* method calls, except g_action_group_list_actions() take the name of * method calls, except [method@Gio.ActionGroup.list_actions] take the name of
* an action as an argument. * an action as an argument.
* *
* The #GActionGroup API is meant to be the 'public' API to the action * The `GActionGroup` API is meant to be the 'public' API to the action
* group. The calls here are exactly the interaction that 'external * group. The calls here are exactly the interaction that 'external
* forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
* with actions. 'Internal' APIs (ie: ones meant only to be accessed by * with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is * the action group implementation) are found on subclasses. This is
* why you will find - for example - g_action_group_get_action_enabled() * why you will find - for example - [method@Gio.ActionGroup.get_action_enabled]
* but not an equivalent set() call. * but not an equivalent set() call.
* *
* Signals are emitted on the action group in response to state changes * Signals are emitted on the action group in response to state changes
* on individual actions. * on individual actions.
* *
* Implementations of #GActionGroup should provide implementations for * Implementations of `GActionGroup` should provide implementations for
* the virtual functions g_action_group_list_actions() and * the virtual functions [method@Gio.ActionGroup.list_actions] and
* g_action_group_query_action(). The other virtual functions should * [method@Gio.ActionGroup.query_action]. The other virtual functions should
* not be implemented - their "wrappers" are actually implemented with * not be implemented - their "wrappers" are actually implemented with
* calls to g_action_group_query_action(). * calls to [method@Gio.ActionGroup.query_action].
*/ */
/**
* GActionGroup:
*
* #GActionGroup is an opaque data structure and can only be accessed
* using the following functions.
**/
/** /**
* GActionGroupInterface: * GActionGroupInterface:
* @has_action: the virtual function pointer for g_action_group_has_action() * @has_action: the virtual function pointer for g_action_group_has_action()

22
gio/gactionmap.c
View File

@ -26,14 +26,13 @@
#include "gaction.h" #include "gaction.h"
/** /**
* SECTION:gactionmap * GActionMap:
* @title: GActionMap
* @include: gio/gio.h
* @short_description: Interface for action containers
* *
* The GActionMap interface is implemented by #GActionGroup * `GActionMap` is an interface for action containers.
* implementations that operate by containing a number of *
* named #GAction instances, such as #GSimpleActionGroup. * The `GActionMap` interface is implemented by [struct@Gio.ActionGroup]
* implementations that operate by containing a number of named
* [struct@Gio.Action] instances, such as [struct@Gio.SimpleActionGroup].
* *
* One useful application of this interface is to map the * One useful application of this interface is to map the
* names of actions from various action groups to unique, * names of actions from various action groups to unique,
@ -42,14 +41,7 @@
* name. * name.
* *
* Since: 2.32 * Since: 2.32
**/ */
/**
* GActionMap:
*
* #GActionMap is an opaque data structure and can only be accessed
* using the following functions.
**/
/** /**
* GActionMapInterface: * GActionMapInterface:

117
gio/gappinfo.c
View File

@ -45,37 +45,37 @@
#endif #endif
/** /**
* SECTION:gappinfo * GAppInfo:
* @short_description: Application information and launch contexts *
* @include: gio/gio.h * Information about an installed application and methods to launch
* @see_also: #GAppInfoMonitor * it (with file arguments).
*
* #GAppInfo and #GAppLaunchContext are used for describing and launching * `GAppInfo` and `GAppLaunchContext` are used for describing and launching
* applications installed on the system. * applications installed on the system.
* *
* As of GLib 2.20, URIs will always be converted to POSIX paths * As of GLib 2.20, URIs will always be converted to POSIX paths
* (using g_file_get_path()) when using g_app_info_launch() even if * (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch]
* the application requested an URI and not a POSIX path. For example * even if the application requested an URI and not a POSIX path. For example
* for a desktop-file based application with Exec key `totem * for a desktop-file based application with Exec key `totem
* %U` and a single URI, `sftp://foo/file.avi`, then * %U` and a single URI, `sftp://foo/file.avi`, then
* `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
* only work if a set of suitable GIO extensions (such as gvfs 2.26 * only work if a set of suitable GIO extensions (such as GVfs 2.26
* compiled with FUSE support), is available and operational; if this * compiled with FUSE support), is available and operational; if this
* is not the case, the URI will be passed unmodified to the application. * is not the case, the URI will be passed unmodified to the application.
* Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
* path (in gvfs there's no FUSE mount for it); such URIs will be * path (in GVfs there's no FUSE mount for it); such URIs will be
* passed unmodified to the application. * passed unmodified to the application.
* *
* Specifically for gvfs 2.26 and later, the POSIX URI will be mapped * Specifically for GVfs 2.26 and later, the POSIX URI will be mapped
* back to the GIO URI in the #GFile constructors (since gvfs * back to the GIO URI in the [struct@Gio.File] constructors (since GVfs
* implements the #GVfs extension point). As such, if the application * implements the GVfs extension point). As such, if the application
* needs to examine the URI, it needs to use g_file_get_uri() or * needs to examine the URI, it needs to use [method@Gio.File.get_uri]
* similar on #GFile. In other words, an application cannot assume * or similar on [struct@Gio.File]. In other words, an application cannot
* that the URI passed to e.g. g_file_new_for_commandline_arg() is * assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg]
* equal to the result of g_file_get_uri(). The following snippet * is equal to the result of [method@Gio.File.get_uri]. The following snippet
* illustrates this: * illustrates this:
* *
* |[ * ```c
* GFile *f; * GFile *f;
* char *uri; * char *uri;
* *
@ -90,7 +90,7 @@
* // do something special with uri * // do something special with uri
* } * }
* g_object_unref (file); * g_object_unref (file);
* ]| * ```
* *
* This code will work when both `cdda://sr0/Track 1.wav` and * This code will work when both `cdda://sr0/Track 1.wav` and
* `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
@ -1653,54 +1653,47 @@ g_app_launch_context_launch_failed (GAppLaunchContext *context,
} }
/**
* SECTION:gappinfomonitor
* @short_description: Monitor application information for changes
*
* #GAppInfoMonitor is a very simple object used for monitoring the app
* info database for changes (newly installed or removed applications).
*
* Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect
* to the #GAppInfoMonitor::changed signal. The signal will be emitted once when
* the app info database changes, and will not be emitted again until after the
* next call to g_app_info_get_all() or another `g_app_info_*()` function. This
* is because monitoring the app info database for changes is expensive.
*
* The following functions will re-arm the #GAppInfoMonitor::changed signal so
* it can be emitted again:
* - g_app_info_get_all()
* - g_app_info_get_all_for_type()
* - g_app_info_get_default_for_type()
* - g_app_info_get_fallback_for_type()
* - g_app_info_get_recommended_for_type()
* - g_desktop_app_info_get_implementations()
* - g_desktop_app_info_new()
* - g_desktop_app_info_new_from_filename()
* - g_desktop_app_info_new_from_keyfile()
* - g_desktop_app_info_search()
*
* In the usual case, applications should try to make note of the change
* (doing things like invalidating caches) but not act on it. In
* particular, applications should avoid making calls to #GAppInfo APIs
* in response to the change signal, deferring these until the time that
* the updated data is actually required. The exception to this case is when
* application information is actually being displayed on the screen
* (for example, during a search or when the list of all applications is shown).
* The reason for this is that changes to the list of installed
* applications often come in groups (like during system updates) and
* rescanning the list on every change is pointless and expensive.
*
* Since: 2.40
**/
/** /**
* GAppInfoMonitor: * GAppInfoMonitor:
* *
* The only thing you can do with this is to get it via * `GAppInfoMonitor` monitors application information for changes.
* g_app_info_monitor_get() and connect to the "changed" signal. *
* `GAppInfoMonitor` is a very simple object used for monitoring the app
* info database for changes (newly installed or removed applications).
*
* Call [func@Gio.AppInfoMonitor.get] to get a `GAppInfoMonitor` and connect
* to the [signal@Gio.AppInfoMonitor.changed] signal. The signal will be emitted once when
* the app info database changes, and will not be emitted again until after the
* next call to [func@Gio.AppInfo.get_all] or another `g_app_info_*()` function.
* This is because monitoring the app info database for changes is expensive.
*
* The following functions will re-arm the [signal@Gio.AppInfoMonitor.changed]
* signal so it can be emitted again:
*
* - [method@Gio.AppInfo.get_all]
* - [method@Gio.AppInfo.get_all_for_type]
* - [method@Gio.AppInfo.get_default_for_type]
* - [method@Gio.AppInfo.get_fallback_for_type]
* - [method@Gio.AppInfo.get_recommended_for_type]
* - [method@Gio.DesktopAppInfo.get_implementations]
* - [method@Gio.DesktopAppInfo.new]
* - [method@Gio.DesktopAppInfo.new_from_filename]
* - [method@Gio.DesktopAppInfo.new_from_keyfile]
* - [method@Gio.DesktopAppInfo.search]
*
* In the usual case, applications should try to make note of the change
* (doing things like invalidating caches) but not act on it. In
* particular, applications should avoid making calls to `GAppInfo` APIs
* in response to the change signal, deferring these until the time that
* the updated data is actually required. The exception to this case is when
* application information is actually being displayed on the screen
* (for example, during a search or when the list of all applications is shown).
* The reason for this is that changes to the list of installed applications
* often come in groups (like during system updates) and rescanning the list
* on every change is pointless and expensive.
* *
* Since: 2.40 * Since: 2.40
**/ */
typedef struct _GAppInfoMonitorClass GAppInfoMonitorClass; typedef struct _GAppInfoMonitorClass GAppInfoMonitorClass;

7
gio/gappinfo.h
View File

@ -46,13 +46,6 @@ G_BEGIN_DECLS
typedef struct _GAppLaunchContextClass GAppLaunchContextClass; typedef struct _GAppLaunchContextClass GAppLaunchContextClass;
typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate; typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate;
/**
* GAppInfo:
*
* Information about an installed application and methods to launch
* it (with file arguments).
*/
/** /**
* GAppInfoIface: * GAppInfoIface:
* @g_iface: The parent interface. * @g_iface: The parent interface.

114
gio/gapplication.c
View File

@ -45,25 +45,25 @@
#include <string.h> #include <string.h>
/** /**
* SECTION:gapplication * GApplication:
* @title: GApplication
* @short_description: Core application class
* @include: gio/gio.h
* *
* A #GApplication is the foundation of an application. It wraps some * `GApplication` is the core class for application support.
*
* A `GApplication` is the foundation of an application. It wraps some
* low-level platform-specific services and is intended to act as the * low-level platform-specific services and is intended to act as the
* foundation for higher-level application classes such as * foundation for higher-level application classes such as
* #GtkApplication or #MxApplication. In general, you should not use * `GtkApplication` or `MxApplication`. In general, you should not use
* this class outside of a higher level framework. * this class outside of a higher level framework.
* *
* GApplication provides convenient life cycle management by maintaining * `GApplication` provides convenient life-cycle management by maintaining
* a "use count" for the primary application instance. The use count can * a "use count" for the primary application instance. The use count can
* be changed using g_application_hold() and g_application_release(). If * be changed using [method@Gio.Application.hold] and
* it drops to zero, the application exits. Higher-level classes such as * [method@Gio.Application.release]. If it drops to zero, the application
* #GtkApplication employ the use count to ensure that the application * exits. Higher-level classes such as `GtkApplication` employ the use count
* stays alive as long as it has any opened windows. * to ensure that the application stays alive as long as it has any opened
* windows.
* *
* Another feature that GApplication (optionally) provides is process * Another feature that `GApplication` (optionally) provides is process
* uniqueness. Applications can make use of this functionality by * uniqueness. Applications can make use of this functionality by
* providing a unique application ID. If given, only one application * providing a unique application ID. If given, only one application
* with this ID can be running at a time per session. The session * with this ID can be running at a time per session. The session
@ -75,53 +75,54 @@
* always the current instance. On Linux, the D-Bus session bus * always the current instance. On Linux, the D-Bus session bus
* is used for communication. * is used for communication.
* *
* The use of #GApplication differs from some other commonly-used * The use of `GApplication` differs from some other commonly-used
* uniqueness libraries (such as libunique) in important ways. The * uniqueness libraries (such as libunique) in important ways. The
* application is not expected to manually register itself and check * application is not expected to manually register itself and check
* if it is the primary instance. Instead, the main() function of a * if it is the primary instance. Instead, the main() function of a
* #GApplication should do very little more than instantiating the * `GApplication` should do very little more than instantiating the
* application instance, possibly connecting signal handlers, then * application instance, possibly connecting signal handlers, then
* calling g_application_run(). All checks for uniqueness are done * calling [method@Gio.Application.run]. All checks for uniqueness are done
* internally. If the application is the primary instance then the * internally. If the application is the primary instance then the
* startup signal is emitted and the mainloop runs. If the application * startup signal is emitted and the mainloop runs. If the application
* is not the primary instance then a signal is sent to the primary * is not the primary instance then a signal is sent to the primary
* instance and g_application_run() promptly returns. See the code * instance and [method@Gio.Application.run] promptly returns. See the code
* examples below. * examples below.
* *
* If used, the expected form of an application identifier is the * If used, the expected form of an application identifier is the
* same as that of a * same as that of a
* [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). * [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
* Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, * Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`,
* `org._7_zip.Archiver`. * `org._7_zip.Archiver`.
* For details on valid application identifiers, see g_application_id_is_valid(). * For details on valid application identifiers, see [func@Gio.Application.id_is_valid].
* *
* On Linux, the application identifier is claimed as a well-known bus name * On Linux, the application identifier is claimed as a well-known bus name
* on the user's session bus. This means that the uniqueness of your * on the user's session bus. This means that the uniqueness of your
* application is scoped to the current session. It also means that your * application is scoped to the current session. It also means that your
* application may provide additional services (through registration of other * application may provide additional services (through registration of other
* object paths) at that bus name. The registration of these object paths * object paths) at that bus name. The registration of these object paths
* should be done with the shared GDBus session bus. Note that due to the * should be done with the shared GDBus session bus. Note that due to the
* internal architecture of GDBus, method calls can be dispatched at any time * internal architecture of GDBus, method calls can be dispatched at any time
* (even if a main loop is not running). For this reason, you must ensure that * (even if a main loop is not running). For this reason, you must ensure that
* any object paths that you wish to register are registered before #GApplication * any object paths that you wish to register are registered before #GApplication
* attempts to acquire the bus name of your application (which happens in * attempts to acquire the bus name of your application (which happens in
* g_application_register()). Unfortunately, this means that you cannot use * [method@Gio.Application.register]). Unfortunately, this means that you cannot
* g_application_get_is_remote() to decide if you want to register object paths. * use [method@Gio.Application.is_remote] to decide if you want to register
* object paths.
* *
* GApplication also implements the #GActionGroup and #GActionMap * `GApplication` also implements the [struct@Gio.ActionGroup] and [struct@Gio.ActionMap]
* interfaces and lets you easily export actions by adding them with * interfaces and lets you easily export actions by adding them with
* g_action_map_add_action(). When invoking an action by calling * [method@Gio.ActionMap.add_action]. When invoking an action by calling
* g_action_group_activate_action() on the application, it is always * [method@Gio.ActionGroup.activate_action] on the application, it is always
* invoked in the primary instance. The actions are also exported on * invoked in the primary instance. The actions are also exported on
* the session bus, and GIO provides the #GDBusActionGroup wrapper to * the session bus, and GIO provides the [struct@Gio.DBusActionGroup] wrapper to
* conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper * conveniently access them remotely. GIO provides a [struct@Gio.DBusMenuModel] wrapper
* for remote access to exported #GMenuModels. * for remote access to exported [struct@Gio.MenuModel]s.
* *
* Note: Due to the fact that actions are exported on the session bus, * Note: Due to the fact that actions are exported on the session bus,
* using `maybe` parameters is not supported, since D-Bus does not support * using `maybe` parameters is not supported, since D-Bus does not support
* `maybe` types. * `maybe` types.
* *
* There is a number of different entry points into a GApplication: * There is a number of different entry points into a `GApplication`:
* *
* - via 'Activate' (i.e. just starting the application) * - via 'Activate' (i.e. just starting the application)
* *
@ -131,50 +132,45 @@
* *
* - via activating an action * - via activating an action
* *
* The #GApplication::startup signal lets you handle the application * The [signal@Gio.Application.startup] signal lets you handle the application
* initialization for all of these in a single place. * initialization for all of these in a single place.
* *
* Regardless of which of these entry points is used to start the * Regardless of which of these entry points is used to start the
* application, GApplication passes some ‘platform data’ from the * application, `GApplication` passes some ‘platform data’ from the
* launching instance to the primary instance, in the form of a * launching instance to the primary instance, in the form of a
* #GVariant dictionary mapping strings to variants. To use platform * [struct@GLib.Variant] dictionary mapping strings to variants. To use platform
* data, override the @before_emit or @after_emit virtual functions * data, override the [vfunc@Gio.Application.before_emit] or
* in your #GApplication subclass. When dealing with * [vfunc@Gio.Application.after_emit] virtual functions
* #GApplicationCommandLine objects, the platform data is * in your `GApplication` subclass. When dealing with
* directly available via g_application_command_line_get_cwd(), * [struct@Gio.ApplicationCommandLine] objects, the platform data is
* g_application_command_line_get_environ() and * directly available via [method@Gio.ApplicationCommandLine.get_cwd],
* g_application_command_line_get_platform_data(). * [method@Gio.ApplicationCommandLine.get_environ] and
* [method@Gio.ApplicationCommandLine.get_platform_data].
* *
* As the name indicates, the platform data may vary depending on the * As the name indicates, the platform data may vary depending on the
* operating system, but it always includes the current directory (key * operating system, but it always includes the current directory (key
* "cwd"), and optionally the environment (ie the set of environment * `cwd`), and optionally the environment (ie the set of environment
* variables and their values) of the calling process (key "environ"). * variables and their values) of the calling process (key `environ`).
* The environment is only added to the platform data if the * The environment is only added to the platform data if the
* %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses * `G_APPLICATION_SEND_ENVIRONMENT` flag is set. `GApplication` subclasses
* can add their own platform data by overriding the @add_platform_data * can add their own platform data by overriding the
* virtual function. For instance, #GtkApplication adds startup notification * [vfunc@Gio.Application.add_platform_data] virtual function. For instance,
* data in this way. * `GtkApplication` adds startup notification data in this way.
* *
* To parse commandline arguments you may handle the * To parse commandline arguments you may handle the
* #GApplication::command-line signal or override the local_command_line() * [signal@Gio.Application.command-line] signal or override the
* vfunc, to parse them in either the primary instance or the local instance, * [vfunc@Gio.Application.local_command_line] virtual funcion, to parse them in
* respectively. * either the primary instance or the local instance, respectively.
* *
* For an example of opening files with a GApplication, see * For an example of opening files with a `GApplication`, see
* [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). * [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c).
* *
* For an example of using actions with GApplication, see * For an example of using actions with `GApplication`, see
* [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). * [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c).
* *
* For an example of using extra D-Bus hooks with GApplication, see * For an example of using extra D-Bus hooks with `GApplication`, see
* [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). * [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c).
*/
/**
* GApplication:
* *
* #GApplication is an opaque data structure and can only be accessed
* using the following functions.
* Since: 2.28 * Since: 2.28
*/ */

68
gio/gapplicationcommandline.c
View File

@ -40,36 +40,34 @@
#endif #endif
/** /**
* SECTION:gapplicationcommandline * GApplicationCommandLine:
* @title: GApplicationCommandLine
* @short_description: A command-line invocation of an application
* @include: gio/gio.h
* @see_also: #GApplication
* *
* #GApplicationCommandLine represents a command-line invocation of * `GApplicationCommandLine` represents a command-line invocation of
* an application. It is created by #GApplication and emitted * an application.
* in the #GApplication::command-line signal and virtual function. *
* It is created by [struct@Gio.Application] and emitted
* in the [signal@Gio.Application.command-line] signal and virtual function.
* *
* The class contains the list of arguments that the program was invoked * The class contains the list of arguments that the program was invoked
* with. It is also possible to query if the commandline invocation was * with. It is also possible to query if the commandline invocation was
* local (ie: the current process is running in direct response to the * local (ie: the current process is running in direct response to the
* invocation) or remote (ie: some other process forwarded the * invocation) or remote (ie: some other process forwarded the
* commandline to this process). * commandline to this process).
* *
* The GApplicationCommandLine object can provide the @argc and @argv * The `GApplicationCommandLine` object can provide the @argc and @argv
* parameters for use with the #GOptionContext command-line parsing API, * parameters for use with the [struct@Glib.OptionContext] command-line parsing API,
* with the g_application_command_line_get_arguments() function. See * with the [method@Gio.ApplicationCommandLine.get_arguments] function. See
* [gapplication-example-cmdline3.c][gapplication-example-cmdline3] * [gapplication-example-cmdline3.c][gapplication-example-cmdline3]
* for an example. * for an example.
* *
* The exit status of the originally-invoked process may be set and * The exit status of the originally-invoked process may be set and
* messages can be printed to stdout or stderr of that process. The * messages can be printed to stdout or stderr of that process. The
* lifecycle of the originally-invoked process is tied to the lifecycle * life-cycle of the originally-invoked process is tied to the lifecycle
* of this object (ie: the process exits when the last reference is * of this object (ie: the process exits when the last reference is
* dropped). * dropped).
* *
* The main use for #GApplicationCommandLine (and the * The main use for `GApplicationCommandLine` (and the
* #GApplication::command-line signal) is 'Emacs server' like use cases: * [signal@Gio.Application.command-line] signal) is 'Emacs server' like use cases:
* You can set the `EDITOR` environment variable to have e.g. git use * You can set the `EDITOR` environment variable to have e.g. git use
* your favourite editor to edit commit messages, and if you already * your favourite editor to edit commit messages, and if you already
* have an instance of the editor running, the editing will happen * have an instance of the editor running, the editing will happen
@ -78,11 +76,12 @@
* does not return until the editing is done. * does not return until the editing is done.
* *
* Normally, the commandline is completely handled in the * Normally, the commandline is completely handled in the
* #GApplication::command-line handler. The launching instance exits * [signal@Gio.Application.command-line handler]. The launching instance exits
* once the signal handler in the primary instance has returned, and * once the signal handler in the primary instance has returned, and
* the return value of the signal handler becomes the exit status * the return value of the signal handler becomes the exit status
* of the launching instance. * of the launching instance.
* |[<!-- language="C" --> *
* ```c
* static int * static int
* command_line (GApplication *application, * command_line (GApplication *application,
* GApplicationCommandLine *cmdline) * GApplicationCommandLine *cmdline)
@ -104,13 +103,15 @@
* *
* return 0; * return 0;
* } * }
* ]| * ```
* The complete example can be found here: *
* The complete example can be found here:
* [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
* *
* In more complicated cases, the handling of the commandline can be * In more complicated cases, the handling of the commandline can be
* split between the launcher and the primary instance. * split between the launcher and the primary instance.
* |[<!-- language="C" --> *
* ```c
* static gboolean * static gboolean
* test_local_cmdline (GApplication *application, * test_local_cmdline (GApplication *application,
* gchar ***arguments, * gchar ***arguments,
@ -156,18 +157,19 @@
* *
* ... * ...
* } * }
* ]| * ```
*
* In this example of split commandline handling, options that start * In this example of split commandline handling, options that start
* with `--local-` are handled locally, all other options are passed * with `--local-` are handled locally, all other options are passed
* to the #GApplication::command-line handler which runs in the primary * to the [signal@Gio.Application.command-line] handler which runs in the primary
* instance. * instance.
* *
* The complete example can be found here: * The complete example can be found here:
* [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
* *
* If handling the commandline requires a lot of work, it may * If handling the commandline requires a lot of work, it may be better to defer it.
* be better to defer it. *
* |[<!-- language="C" --> * ```c
* static gboolean * static gboolean
* my_cmdline_handler (gpointer data) * my_cmdline_handler (gpointer data)
* { * {
@ -197,10 +199,11 @@
* *
* return 0; * return 0;
* } * }
* ]| * ```
*
* In this example the commandline is not completely handled before * In this example the commandline is not completely handled before
* the #GApplication::command-line handler returns. Instead, we keep * the [signal@Gio.Application.command-line] handler returns. Instead, we keep
* a reference to the #GApplicationCommandLine object and handle it * a reference to the `GApplicationCommandLine` object and handle it
* later (in this example, in an idle). Note that it is necessary to * later (in this example, in an idle). Note that it is necessary to
* hold the application until you are done with the commandline. * hold the application until you are done with the commandline.
* *
@ -208,13 +211,6 @@
* [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
*/ */
/**
* GApplicationCommandLine:
*
* #GApplicationCommandLine is an opaque data structure and can only be accessed
* using the following functions.
*/
/** /**
* GApplicationCommandLineClass: * GApplicationCommandLineClass:
* *

25
gio/gasyncinitable.c
View File

@ -29,27 +29,26 @@
/** /**
* SECTION:gasyncinitable * GAsyncInitable:
* @short_description: Asynchronously failable object initialization interface
* @include: gio/gio.h
* @see_also: #GInitable
* *
* This is the asynchronous version of #GInitable; it behaves the same * `GAsyncInitable` is an interface for asynchronously initializable objects.
*
* This is the asynchronous version of [struct@Gio.Initable]; it behaves the same
* in all ways except that initialization is asynchronous. For more details * in all ways except that initialization is asynchronous. For more details
* see the descriptions on #GInitable. * see the descriptions on `GInitable`.
* *
* A class may implement both the #GInitable and #GAsyncInitable interfaces. * A class may implement both the `GInitable` and `GAsyncInitable` interfaces.
* *
* Users of objects implementing this are not intended to use the interface * Users of objects implementing this are not intended to use the interface
* method directly; instead it will be used automatically in various ways. * method directly; instead it will be used automatically in various ways.
* For C applications you generally just call g_async_initable_new_async() * For C applications you generally just call [func@Gio.AsyncInitiable.new_async]
* directly, or indirectly via a foo_thing_new_async() wrapper. This will call * directly, or indirectly via a foo_thing_new_async() wrapper. This will call
* g_async_initable_init_async() under the cover, calling back with %NULL and * [func@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL`
* a set %GError on failure. * and a set `GError` on failure.
* *
* A typical implementation might look something like this: * A typical implementation might look something like this:
* *
* |[<!-- language="C" --> * ```c
* enum { * enum {
* NOT_INITIALIZED, * NOT_INITIALIZED,
* INITIALIZING, * INITIALIZING,
@ -132,7 +131,9 @@
* iface->init_async = foo_init_async; * iface->init_async = foo_init_async;
* iface->init_finish = foo_init_finish; * iface->init_finish = foo_init_finish;
* } * }
* ]| * ```
*
* Since: 2.22
*/ */
static void g_async_initable_real_init_async (GAsyncInitable *initable, static void g_async_initable_real_init_async (GAsyncInitable *initable,

7
gio/gasyncinitable.h
View File

@ -38,13 +38,6 @@ G_BEGIN_DECLS
#define G_ASYNC_INITABLE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_INITABLE, GAsyncInitableIface)) #define G_ASYNC_INITABLE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_INITABLE, GAsyncInitableIface))
#define G_TYPE_IS_ASYNC_INITABLE(type) (g_type_is_a ((type), G_TYPE_ASYNC_INITABLE)) #define G_TYPE_IS_ASYNC_INITABLE(type) (g_type_is_a ((type), G_TYPE_ASYNC_INITABLE))
/**
* GAsyncInitable:
*
* Interface for asynchronously initializable objects.
*
* Since: 2.22
**/
typedef struct _GAsyncInitableIface GAsyncInitableIface; typedef struct _GAsyncInitableIface GAsyncInitableIface;
/** /**

52
gio/gasyncresult.c
View File

@ -27,42 +27,40 @@
/** /**
* SECTION:gasyncresult * GAsyncResult:
* @short_description: Asynchronous Function Results
* @include: gio/gio.h
* @see_also: #GTask
* *
* Provides a base class for implementing asynchronous function results. * `GAsyncResult` provides a base class for implementing asynchronous function results.
* *
* Asynchronous operations are broken up into two separate operations * Asynchronous operations are broken up into two separate operations
* which are chained together by a #GAsyncReadyCallback. To begin * which are chained together by a `GAsyncReadyCallback`. To begin
* an asynchronous operation, provide a #GAsyncReadyCallback to the * an asynchronous operation, provide a `GAsyncReadyCallback` to the
* asynchronous function. This callback will be triggered when the * asynchronous function. This callback will be triggered when the
* operation has completed, and must be run in a later iteration of * operation has completed, and must be run in a later iteration of
* the [thread-default main context][g-main-context-push-thread-default] * the thread-default main context (see
* from where the operation was initiated. It will be passed a * [method@GLib.MainContext.push_thread_default]) from where the operation was
* #GAsyncResult instance filled with the details of the operation's * initiated. It will be passed a `GAsyncResult` instance filled with the
* success or failure, the object the asynchronous function was * details of the operation's success or failure, the object the asynchronous
* started for and any error codes returned. The asynchronous callback * function was started for and any error codes returned. The asynchronous
* function is then expected to call the corresponding "_finish()" * callback function is then expected to call the corresponding `_finish()`
* function, passing the object the function was called for, the * function, passing the object the function was called for, the
* #GAsyncResult instance, and (optionally) an @error to grab any * `GAsyncResult` instance, and (optionally) an @error to grab any
* error conditions that may have occurred. * error conditions that may have occurred.
* *
* The "_finish()" function for an operation takes the generic result * The `_finish()` function for an operation takes the generic result
* (of type #GAsyncResult) and returns the specific result that the * (of type `GAsyncResult`) and returns the specific result that the
* operation in question yields (e.g. a #GFileEnumerator for a * operation in question yields (e.g. a [struct@Gio.FileEnumerator] for a
* "enumerate children" operation). If the result or error status of the * "enumerate children" operation). If the result or error status of the
* operation is not needed, there is no need to call the "_finish()" * operation is not needed, there is no need to call the `_finish()`
* function; GIO will take care of cleaning up the result and error * function; GIO will take care of cleaning up the result and error
* information after the #GAsyncReadyCallback returns. You can pass * information after the `GAsyncReadyCallback` returns. You can pass
* %NULL for the #GAsyncReadyCallback if you don't need to take any * `NULL` for the `GAsyncReadyCallback` if you don't need to take any
* action at all after the operation completes. Applications may also * action at all after the operation completes. Applications may also
* take a reference to the #GAsyncResult and call "_finish()" later; * take a reference to the `GAsyncResult` and call `_finish()` later;
* however, the "_finish()" function may be called at most once. * however, the `_finish()` function may be called at most once.
* *
* Example of a typical asynchronous operation flow: * Example of a typical asynchronous operation flow:
* |[<!-- language="C" --> *
* ```c
* void _theoretical_frobnitz_async (Theoretical *t, * void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c, * GCancellable *c,
* GAsyncReadyCallback cb, * GAsyncReadyCallback cb,
@ -101,20 +99,20 @@
* *
* ... * ...
* } * }
* ]| * ```
* *
* The callback for an asynchronous operation is called only once, and is * The callback for an asynchronous operation is called only once, and is
* always called, even in the case of a cancelled operation. On cancellation * always called, even in the case of a cancelled operation. On cancellation
* the result is a %G_IO_ERROR_CANCELLED error. * the result is a `G_IO_ERROR_CANCELLED` error.
* *
* ## I/O Priority # {#io-priority} * ## I/O Priority
* *
* Many I/O-related asynchronous operations have a priority parameter, * Many I/O-related asynchronous operations have a priority parameter,
* which is used in certain cases to determine the order in which * which is used in certain cases to determine the order in which
* operations are executed. They are not used to determine system-wide * operations are executed. They are not used to determine system-wide
* I/O scheduling. Priorities are integers, with lower numbers indicating * I/O scheduling. Priorities are integers, with lower numbers indicating
* higher priority. It is recommended to choose priorities between * higher priority. It is recommended to choose priorities between
* %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT * `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
* as a default. * as a default.
*/ */

6
gio/gasyncresult.h
View File

@ -36,12 +36,6 @@ G_BEGIN_DECLS
#define G_IS_ASYNC_RESULT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT)) #define G_IS_ASYNC_RESULT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT))
#define G_ASYNC_RESULT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface)) #define G_ASYNC_RESULT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface))
/**
* GAsyncResult:
*
* Holds results information for an asynchronous operation,
* usually passed directly to an asynchronous _finish() operation.
**/
typedef struct _GAsyncResultIface GAsyncResultIface; typedef struct _GAsyncResultIface GAsyncResultIface;

18
gio/gbufferedinputstream.c
View File

@ -34,25 +34,21 @@
/** /**
* SECTION:gbufferedinputstream * GBufferedInputStream:
* @short_description: Buffered Input Stream
* @include: gio/gio.h
* @see_also: #GFilterInputStream, #GInputStream
* *
* Buffered input stream implements #GFilterInputStream and provides * Buffered input stream implements #GFilterInputStream and provides
* for buffered reads. * for buffered reads.
* *
* By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. * By default, `GBufferedInputStream`'s buffer size is set at 4 kilobytes.
* *
* To create a buffered input stream, use g_buffered_input_stream_new(), * To create a buffered input stream, use [func@Gio.BufferedInputStream.new],
* or g_buffered_input_stream_new_sized() to specify the buffer's size at * or [func@Gio.BufferedInputStream.new_sized] to specify the buffer's size at
* construction. * construction.
* *
* To get the size of a buffer within a buffered input stream, use * To get the size of a buffer within a buffered input stream, use
* g_buffered_input_stream_get_buffer_size(). To change the size of a * [method@Gio.BufferedInputStream.get_buffer_size]. To change the size of a
* buffered input stream's buffer, use * buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_size].
* g_buffered_input_stream_set_buffer_size(). Note that the buffer's size * Note that the buffer's size cannot be reduced below the size of the data within the buffer.
* cannot be reduced below the size of the data within the buffer.
*/ */

5
gio/gbufferedinputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_BUFFERED_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_INPUT_STREAM)) #define G_IS_BUFFERED_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_INPUT_STREAM))
#define G_BUFFERED_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_INPUT_STREAM, GBufferedInputStreamClass)) #define G_BUFFERED_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_INPUT_STREAM, GBufferedInputStreamClass))
/**
* GBufferedInputStream:
*
* Implements #GFilterInputStream with a sized input buffer.
**/
typedef struct _GBufferedInputStreamClass GBufferedInputStreamClass; typedef struct _GBufferedInputStreamClass GBufferedInputStreamClass;
typedef struct _GBufferedInputStreamPrivate GBufferedInputStreamPrivate; typedef struct _GBufferedInputStreamPrivate GBufferedInputStreamPrivate;

34
gio/gbufferedoutputstream.c
View File

@ -30,26 +30,22 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gbufferedoutputstream * GBufferedOutputStream:
* @short_description: Buffered Output Stream *
* @include: gio/gio.h * Buffered output stream implements [struct@Gio.FilterOutputStream] and provides
* @see_also: #GFilterOutputStream, #GOutputStream * for buffered writes.
* *
* Buffered output stream implements #GFilterOutputStream and provides * By default, `GBufferedOutputStream`'s buffer size is set at 4 kilobytes.
* for buffered writes. *
* * To create a buffered output stream, use [func@Gio.BufferedOutputStream.new],
* By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. * or [func@Gio.BufferedOutputStream.new_sized] to specify the buffer's size
*
* To create a buffered output stream, use g_buffered_output_stream_new(),
* or g_buffered_output_stream_new_sized() to specify the buffer's size
* at construction. * at construction.
* *
* To get the size of a buffer within a buffered input stream, use * To get the size of a buffer within a buffered input stream, use
* g_buffered_output_stream_get_buffer_size(). To change the size of a * [method@Gio.BufferedOutputStream.get_buffer_size]. To change the size of a
* buffered output stream's buffer, use * buffered output stream's buffer, use [method@Gio.BufferedOutputStream.set_buffer_size].
* g_buffered_output_stream_set_buffer_size(). Note that the buffer's * Note that the buffer's size cannot be reduced below the size of the data within the buffer.
* size cannot be reduced below the size of the data within the buffer. */
**/
#define DEFAULT_BUFFER_SIZE 4096 #define DEFAULT_BUFFER_SIZE 4096

5
gio/gbufferedoutputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_BUFFERED_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_OUTPUT_STREAM)) #define G_IS_BUFFERED_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_OUTPUT_STREAM))
#define G_BUFFERED_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_OUTPUT_STREAM, GBufferedOutputStreamClass)) #define G_BUFFERED_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_OUTPUT_STREAM, GBufferedOutputStreamClass))
/**
* GBufferedOutputStream:
*
* An implementation of #GFilterOutputStream with a sized buffer.
**/
typedef struct _GBufferedOutputStreamClass GBufferedOutputStreamClass; typedef struct _GBufferedOutputStreamClass GBufferedOutputStreamClass;
typedef struct _GBufferedOutputStreamPrivate GBufferedOutputStreamPrivate; typedef struct _GBufferedOutputStreamPrivate GBufferedOutputStreamPrivate;

11
gio/gbytesicon.c
View File

@ -33,16 +33,13 @@
/** /**
* SECTION:gbytesicon * GBytesIcon:
* @short_description: An icon stored in memory as a GBytes
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon, #GBytes
* *
* #GBytesIcon specifies an image held in memory in a common format (usually * `GBytesIcon` specifies an image held in memory in a common format (usually
* png) to be used as icon. * PNG) to be used as icon.
* *
* Since: 2.38 * Since: 2.38
**/ */
typedef GObjectClass GBytesIconClass; typedef GObjectClass GBytesIconClass;

5
gio/gbytesicon.h
View File

@ -35,11 +35,6 @@ G_BEGIN_DECLS
#define G_BYTES_ICON(inst) (G_TYPE_CHECK_INSTANCE_CAST ((inst), G_TYPE_BYTES_ICON, GBytesIcon)) #define G_BYTES_ICON(inst) (G_TYPE_CHECK_INSTANCE_CAST ((inst), G_TYPE_BYTES_ICON, GBytesIcon))
#define G_IS_BYTES_ICON(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_BYTES_ICON)) #define G_IS_BYTES_ICON(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_BYTES_ICON))
/**
* GBytesIcon:
*
* Gets an icon for a #GBytes. Implements #GLoadableIcon.
**/
GIO_AVAILABLE_IN_2_38 GIO_AVAILABLE_IN_2_38
GType g_bytes_icon_get_type (void) G_GNUC_CONST; GType g_bytes_icon_get_type (void) G_GNUC_CONST;

8
gio/gcancellable.c
View File

@ -29,11 +29,11 @@
/** /**
* SECTION:gcancellable * GCancellable:
* @short_description: Thread-safe Operation Cancellation Stack
* @include: gio/gio.h
* *
* GCancellable is a thread-safe operation cancellation stack used * `GCancellable` allows operations to be cancelled.
*
* `GCancellable` is a thread-safe operation cancellation stack used
* throughout GIO to allow for cancellation of synchronous and * throughout GIO to allow for cancellation of synchronous and
* asynchronous operations. * asynchronous operations.
*/ */

5
gio/gcancellable.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_CANCELLABLE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CANCELLABLE)) #define G_IS_CANCELLABLE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CANCELLABLE))
#define G_CANCELLABLE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CANCELLABLE, GCancellableClass)) #define G_CANCELLABLE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CANCELLABLE, GCancellableClass))
/**
* GCancellable:
*
* Allows actions to be cancelled.
*/
typedef struct _GCancellableClass GCancellableClass; typedef struct _GCancellableClass GCancellableClass;
typedef struct _GCancellablePrivate GCancellablePrivate; typedef struct _GCancellablePrivate GCancellablePrivate;

13
gio/gcharsetconverter.c
View File

@ -39,22 +39,15 @@ enum {
}; };
/** /**
* SECTION:gcharsetconverter * GCharsetConverter:
* @short_description: Convert between charsets
* @include: gio/gio.h
* *
* #GCharsetConverter is an implementation of #GConverter based on * `GCharsetConverter` is an implementation of [iface@Gio.Converter] based on
* GIConv. * [class@GLib.IConv].
*/ */
static void g_charset_converter_iface_init (GConverterIface *iface); static void g_charset_converter_iface_init (GConverterIface *iface);
static void g_charset_converter_initable_iface_init (GInitableIface *iface); static void g_charset_converter_initable_iface_init (GInitableIface *iface);
/**
* GCharsetConverter:
*
* Conversions between character sets.
*/
struct _GCharsetConverter struct _GCharsetConverter
{ {
GObject parent_instance; GObject parent_instance;

11
gio/gconverter.c
View File

@ -26,12 +26,11 @@
/** /**
* SECTION:gconverter * GConverter:
* @short_description: Data conversion interface
* @include: gio/gio.h
* @see_also: #GInputStream, #GOutputStream
* *
* #GConverter is implemented by objects that convert * `GConverter` is an interface for streaming conversions.
*
* `GConverter` is implemented by objects that convert
* binary data in various ways. The conversion can be * binary data in various ways. The conversion can be
* stateful and may fail at any place. * stateful and may fail at any place.
* *
@ -40,7 +39,7 @@
* replace. * replace.
* *
* Since: 2.24 * Since: 2.24
**/ */
typedef GConverterIface GConverterInterface; typedef GConverterIface GConverterInterface;

7
gio/gconverter.h
View File

@ -36,13 +36,6 @@ G_BEGIN_DECLS
#define G_IS_CONVERTER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_CONVERTER)) #define G_IS_CONVERTER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_CONVERTER))
#define G_CONVERTER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_CONVERTER, GConverterIface)) #define G_CONVERTER_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_CONVERTER, GConverterIface))
/**
* GConverter:
*
* Seek object for streaming operations.
*
* Since: 2.24
**/
typedef struct _GConverterIface GConverterIface; typedef struct _GConverterIface GConverterIface;
/** /**

13
gio/gconverterinputstream.c
View File

@ -33,17 +33,14 @@
/** /**
* SECTION:gconverterinputstream * GConverterInputStream:
* @short_description: Converter Input Stream
* @include: gio/gio.h
* @see_also: #GInputStream, #GConverter
* *
* Converter input stream implements #GInputStream and allows * Converter input stream implements [iface@Gio.InputStream] and allows
* conversion of data of various types during reading. * conversion of data of various types during reading.
* *
* As of GLib 2.34, #GConverterInputStream implements * As of GLib 2.34, `GConverterInputStream` implements
* #GPollableInputStream. * [iface@Gio.PollableInputStream].
**/ */
#define INITIAL_BUFFER_SIZE 4096 #define INITIAL_BUFFER_SIZE 4096

6
gio/gconverterinputstream.h
View File

@ -39,12 +39,6 @@ G_BEGIN_DECLS
#define G_IS_CONVERTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CONVERTER_INPUT_STREAM)) #define G_IS_CONVERTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CONVERTER_INPUT_STREAM))
#define G_CONVERTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CONVERTER_INPUT_STREAM, GConverterInputStreamClass)) #define G_CONVERTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CONVERTER_INPUT_STREAM, GConverterInputStreamClass))
/**
* GConverterInputStream:
*
* An implementation of #GFilterInputStream that allows data
* conversion.
**/
typedef struct _GConverterInputStreamClass GConverterInputStreamClass; typedef struct _GConverterInputStreamClass GConverterInputStreamClass;
typedef struct _GConverterInputStreamPrivate GConverterInputStreamPrivate; typedef struct _GConverterInputStreamPrivate GConverterInputStreamPrivate;

13
gio/gconverteroutputstream.c
View File

@ -33,17 +33,14 @@
/** /**
* SECTION:gconverteroutputstream * GConverterOutputStream:
* @short_description: Converter Output Stream
* @include: gio/gio.h
* @see_also: #GOutputStream, #GConverter
* *
* Converter output stream implements #GOutputStream and allows * Converter output stream implements [iface@Gio.OutputStream] and allows
* conversion of data of various types during reading. * conversion of data of various types during reading.
* *
* As of GLib 2.34, #GConverterOutputStream implements * As of GLib 2.34, `GConverterOutputStream` implements
* #GPollableOutputStream. * [iface@Gio.PollableOutputStream].
**/ */
#define INITIAL_BUFFER_SIZE 4096 #define INITIAL_BUFFER_SIZE 4096

6
gio/gconverteroutputstream.h
View File

@ -39,12 +39,6 @@ G_BEGIN_DECLS
#define G_IS_CONVERTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CONVERTER_OUTPUT_STREAM)) #define G_IS_CONVERTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CONVERTER_OUTPUT_STREAM))
#define G_CONVERTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CONVERTER_OUTPUT_STREAM, GConverterOutputStreamClass)) #define G_CONVERTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CONVERTER_OUTPUT_STREAM, GConverterOutputStreamClass))
/**
* GConverterOutputStream:
*
* An implementation of #GFilterOutputStream that allows data
* conversion.
**/
typedef struct _GConverterOutputStreamClass GConverterOutputStreamClass; typedef struct _GConverterOutputStreamClass GConverterOutputStreamClass;
typedef struct _GConverterOutputStreamPrivate GConverterOutputStreamPrivate; typedef struct _GConverterOutputStreamPrivate GConverterOutputStreamPrivate;

82
gio/gcredentials.c
View File

@ -35,58 +35,48 @@
#include "glibintl.h" #include "glibintl.h"
/**
* SECTION:gcredentials
* @short_description: An object containing credentials
* @include: gio/gio.h
*
* The #GCredentials type is a reference-counted wrapper for native
* credentials. This information is typically used for identifying,
* authenticating and authorizing other processes.
*
* Some operating systems supports looking up the credentials of the
* remote peer of a communication endpoint - see e.g.
* g_socket_get_credentials().
*
* Some operating systems supports securely sending and receiving
* credentials over a Unix Domain Socket, see
* #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
* g_unix_connection_receive_credentials() for details.
*
* On Linux, the native credential type is a `struct ucred` - see the
* unix(7) man page for details. This corresponds to
* %G_CREDENTIALS_TYPE_LINUX_UCRED.
*
* On Apple operating systems (including iOS, tvOS, and macOS),
* the native credential type is a `struct xucred`.
* This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED.
*
* On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
* credential type is a `struct cmsgcred`. This corresponds
* to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
*
* On NetBSD, the native credential type is a `struct unpcbid`.
* This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID.
*
* On OpenBSD, the native credential type is a `struct sockpeercred`.
* This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
*
* On Solaris (including OpenSolaris and its derivatives), the native
* credential type is a `ucred_t`. This corresponds to
* %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
*
* Since GLib 2.72, on Windows, the native credentials may contain the PID of a
* process. This corresponds to %G_CREDENTIALS_TYPE_WIN32_PID.
*/
/** /**
* GCredentials: * GCredentials:
* *
* The #GCredentials structure contains only private data and * The `GCredentials` type is a reference-counted wrapper for native
* should only be accessed using the provided API. * credentials.
*
* The information in `GCredentials` is typically used for identifying,
* authenticating and authorizing other processes.
*
* Some operating systems supports looking up the credentials of the remote
* peer of a communication endpoint - see e.g. [method@Gio.Socket.get_credentials].
*
* Some operating systems supports securely sending and receiving
* credentials over a Unix Domain Socket, see [struct@Gio.UnixCredentialsMessage],
* [method@Gio.UnixConnection.send_credentials] and
* [method@Gio.UnixConnection.receive_credentials] for details.
*
* On Linux, the native credential type is a `struct ucred` - see the
* [`unix(7)` man page](man:unix(7)) for details. This corresponds to
* `G_CREDENTIALS_TYPE_LINUX_UCRED`.
*
* On Apple operating systems (including iOS, tvOS, and macOS), the native credential
* type is a `struct xucred`. This corresponds to `G_CREDENTIALS_TYPE_APPLE_XUCRED`.
*
* On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a
* `struct cmsgcred`. This corresponds to `G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED`.
*
* On NetBSD, the native credential type is a `struct unpcbid`.
* This corresponds to `G_CREDENTIALS_TYPE_NETBSD_UNPCBID`.
*
* On OpenBSD, the native credential type is a `struct sockpeercred`.
* This corresponds to `G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED`.
*
* On Solaris (including OpenSolaris and its derivatives), the native credential type
* is a `ucred_t`. This corresponds to `G_CREDENTIALS_TYPE_SOLARIS_UCRED`.
*
* Since GLib 2.72, on Windows, the native credentials may contain the PID of a
* process. This corresponds to `G_CREDENTIALS_TYPE_WIN32_PID`.
* *
* Since: 2.26 * Since: 2.26
*/ */
struct _GCredentials struct _GCredentials
{ {
/*< private >*/ /*< private >*/

47
gio/gdatagrambased.c
View File

@ -32,57 +32,56 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gdatagrambased * GDatagramBased:
* @short_description: Low-level datagram communications interface
* @include: gio/gio.h
* @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
* *
* A #GDatagramBased is a networking interface for representing datagram-based * Interface for socket-like objects with datagram semantics.
*
* A `GDatagramBased` is a networking interface for representing datagram-based
* communications. It is a more or less direct mapping of the core parts of the * communications. It is a more or less direct mapping of the core parts of the
* BSD socket API in a portable GObject interface. It is implemented by * BSD socket API in a portable GObject interface. It is implemented by
* #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. * [struct@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows.
* *
* #GDatagramBased is entirely platform independent, and is intended to be used * `GDatagramBased` is entirely platform independent, and is intended to be used
* alongside higher-level networking APIs such as #GIOStream. * alongside higher-level networking APIs such as [struct@Gio.IOStream].
* *
* It uses vectored scatter/gather I/O by default, allowing for many messages * It uses vectored scatter/gather I/O by default, allowing for many messages
* to be sent or received in a single call. Where possible, implementations of * to be sent or received in a single call. Where possible, implementations of
* the interface should take advantage of vectored I/O to minimise processing * the interface should take advantage of vectored I/O to minimise processing
* or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where * or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()`
* possible. Callers should take advantage of scatter/gather I/O (the use of * where possible. Callers should take advantage of scatter/gather I/O (the use of
* multiple buffers per message) to avoid unnecessary copying of data to * multiple buffers per message) to avoid unnecessary copying of data to
* assemble or disassemble a message. * assemble or disassemble a message.
* *
* Each #GDatagramBased operation has a timeout parameter which may be negative * Each `GDatagramBased` operation has a timeout parameter which may be negative
* for blocking behaviour, zero for non-blocking behaviour, or positive for * for blocking behaviour, zero for non-blocking behaviour, or positive for
* timeout behaviour. A blocking operation blocks until finished or there is an * timeout behaviour. A blocking operation blocks until finished or there is an
* error. A non-blocking operation will return immediately with a * error. A non-blocking operation will return immediately with a
* %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation * `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation
* will block until the operation is complete or the timeout expires; if the * will block until the operation is complete or the timeout expires; if the
* timeout expires it will return what progress it made, or * timeout expires it will return what progress it made, or
* %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would * `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would
* successfully run you can call g_datagram_based_condition_check() or * successfully run you can call [method@Gio.DatagramBased.condition_check] or
* g_datagram_based_condition_wait(). You can also use * [method@Gio.DatagramBased.condition_wait]. You can also use
* g_datagram_based_create_source() and attach it to a #GMainContext to get * [method@Gio.DatagramBased.create_source] and attach it to a [struct@Glib.MainContext]
* callbacks when I/O is possible. * to get callbacks when I/O is possible.
* *
* When running a non-blocking operation applications should always be able to * When running a non-blocking operation applications should always be able to
* handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function * handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function
* said that I/O was possible. This can easily happen in case of a race * said that I/O was possible. This can easily happen in case of a race
* condition in the application, but it can also happen for other reasons. For * condition in the application, but it can also happen for other reasons. For
* instance, on Windows a socket is always seen as writable until a write * instance, on Windows a socket is always seen as writable until a write
* returns %G_IO_ERROR_WOULD_BLOCK. * returns `G_IO_ERROR_WOULD_BLOCK`.
* *
* As with #GSocket, #GDatagramBaseds can be either connection oriented (for * As with `GSocket`, `GDatagramBased`s can be either connection oriented (for
* example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be * example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be
* datagram-based, not stream-based. The interface does not cover connection * datagram-based, not stream-based. The interface does not cover connection
* establishment — use methods on the underlying type to establish a connection * establishment — use methods on the underlying type to establish a connection
* before sending and receiving data through the #GDatagramBased API. For * before sending and receiving data through the `GDatagramBased` API. For
* connectionless socket types the target/source address is specified or * connectionless socket types the target/source address is specified or
* received in each I/O operation. * received in each I/O operation.
* *
* Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. * Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe.
* To use a #GDatagramBased concurrently from multiple threads, you must * To use a `GDatagramBased` concurrently from multiple threads, you must
* implement your own locking. * implement your own locking.
* *
* Since: 2.48 * Since: 2.48

7
gio/gdatagrambased.h
View File

@ -41,13 +41,6 @@ G_BEGIN_DECLS
#define G_TYPE_IS_DATAGRAM_BASED(type) (g_type_is_a ((type), \ #define G_TYPE_IS_DATAGRAM_BASED(type) (g_type_is_a ((type), \
G_TYPE_DATAGRAM_BASED)) G_TYPE_DATAGRAM_BASED))
/**
* GDatagramBased:
*
* Interface for socket-like objects with datagram semantics.
*
* Since: 2.48
*/
typedef struct _GDatagramBasedInterface GDatagramBasedInterface; typedef struct _GDatagramBasedInterface GDatagramBasedInterface;
/** /**

12
gio/gdatainputstream.c
View File

@ -33,15 +33,11 @@
#include <string.h> #include <string.h>
/** /**
* SECTION:gdatainputstream * GDataInputStream:
* @short_description: Data Input Stream
* @include: gio/gio.h
* @see_also: #GInputStream
*
* Data input stream implements #GInputStream and includes functions for
* reading structured data directly from a binary input stream.
* *
**/ * Data input stream implements [iface@Gio.InputStream] and includes functions
* for reading structured data directly from a binary input stream.
*/
struct _GDataInputStreamPrivate { struct _GDataInputStreamPrivate {
GDataStreamByteOrder byte_order; GDataStreamByteOrder byte_order;

6
gio/gdatainputstream.h
View File

@ -38,12 +38,6 @@ G_BEGIN_DECLS
#define G_IS_DATA_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_INPUT_STREAM)) #define G_IS_DATA_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_INPUT_STREAM))
#define G_DATA_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_INPUT_STREAM, GDataInputStreamClass)) #define G_DATA_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_INPUT_STREAM, GDataInputStreamClass))
/**
* GDataInputStream:
*
* An implementation of #GBufferedInputStream that allows for high-level
* data manipulation of arbitrary data (including binary operations).
**/
typedef struct _GDataInputStreamClass GDataInputStreamClass; typedef struct _GDataInputStreamClass GDataInputStreamClass;
typedef struct _GDataInputStreamPrivate GDataInputStreamPrivate; typedef struct _GDataInputStreamPrivate GDataInputStreamPrivate;

13
gio/gdataoutputstream.c
View File

@ -30,16 +30,11 @@
/** /**
* SECTION:gdataoutputstream * GDataOutputStream:
* @short_description: Data Output Stream
* @include: gio/gio.h
* @see_also: #GOutputStream
*
* Data output stream implements #GOutputStream and includes functions for
* writing data directly to an output stream.
* *
**/ * Data output stream implements [iface@Gio.OutputStream] and includes functions
* for writing data directly to an output stream.
*/
struct _GDataOutputStreamPrivate { struct _GDataOutputStreamPrivate {

6
gio/gdataoutputstream.h
View File

@ -38,12 +38,6 @@ G_BEGIN_DECLS
#define G_IS_DATA_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_OUTPUT_STREAM)) #define G_IS_DATA_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_OUTPUT_STREAM))
#define G_DATA_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_OUTPUT_STREAM, GDataOutputStreamClass)) #define G_DATA_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_OUTPUT_STREAM, GDataOutputStreamClass))
/**
* GDataOutputStream:
*
* An implementation of #GBufferedOutputStream that allows for high-level
* data manipulation of arbitrary data (including binary operations).
**/
typedef struct _GDataOutputStream GDataOutputStream; typedef struct _GDataOutputStream GDataOutputStream;
typedef struct _GDataOutputStreamClass GDataOutputStreamClass; typedef struct _GDataOutputStreamClass GDataOutputStreamClass;
typedef struct _GDataOutputStreamPrivate GDataOutputStreamPrivate; typedef struct _GDataOutputStreamPrivate GDataOutputStreamPrivate;

19
gio/gdbusactiongroup.c
View File

@ -28,23 +28,14 @@
#include "gdbusconnection.h" #include "gdbusconnection.h"
#include "gactiongroup.h" #include "gactiongroup.h"
/**
* SECTION:gdbusactiongroup
* @title: GDBusActionGroup
* @short_description: A D-Bus GActionGroup implementation
* @include: gio/gio.h
* @see_also: [GActionGroup exporter][gio-GActionGroup-exporter]
*
* #GDBusActionGroup is an implementation of the #GActionGroup
* interface that can be used as a proxy for an action group
* that is exported over D-Bus with g_dbus_connection_export_action_group().
*/
/** /**
* GDBusActionGroup: * GDBusActionGroup:
* *
* #GDBusActionGroup is an opaque data structure and can only be accessed * `GDBusActionGroup` is an implementation of the [iface@Gio.ActionGroup]
* using the following functions. * interface.
*
* `GDBusActionGroup` can be used as a proxy for an action group
* that is exported over D-Bus with [func@Gio.DBusConnection.export_action_group].
*/ */
struct _GDBusActionGroup struct _GDBusActionGroup

51
gio/gdbusauthobserver.c
View File

@ -32,26 +32,25 @@
#include "gmarshal-internal.h" #include "gmarshal-internal.h"
/** /**
* SECTION:gdbusauthobserver * GDBusAuthObserver:
* @short_description: Object used for authenticating connections
* @include: gio/gio.h
* *
* The #GDBusAuthObserver type provides a mechanism for participating * `GDBusAuthObserver` provides a mechanism for participating
* in how a #GDBusServer (or a #GDBusConnection) authenticates remote * in how a [class@Gio.DBusServer] (or a [class@Gio.DBusConnection])
* peers. Simply instantiate a #GDBusAuthObserver and connect to the * authenticates remote peers.
*
* Simply instantiate a `GDBusAuthObserver` and connect to the
* signals you are interested in. Note that new signals may be added * signals you are interested in. Note that new signals may be added
* in the future * in the future.
* *
* ## Controlling Authentication Mechanisms * ## Controlling Authentication Mechanisms
* *
* By default, a #GDBusServer or server-side #GDBusConnection will allow * By default, a `GDBusServer` or server-side `GDBusConnection` will allow
* any authentication mechanism to be used. If you only * any authentication mechanism to be used. If you only want to allow D-Bus
* want to allow D-Bus connections with the `EXTERNAL` mechanism, * connections with the `EXTERNAL` mechanism, which makes use of credentials
* which makes use of credentials passing and is the recommended * passing and is the recommended mechanism for modern Unix platforms such
* mechanism for modern Unix platforms such as Linux and the BSD family, * as Linux and the BSD family, you would use a signal handler like this:
* you would use a signal handler like this:
* *
* |[<!-- language="C" --> * ```c
* static gboolean * static gboolean
* on_allow_mechanism (GDBusAuthObserver *observer, * on_allow_mechanism (GDBusAuthObserver *observer,
* const gchar *mechanism, * const gchar *mechanism,
@ -64,19 +63,19 @@
* *
* return FALSE; * return FALSE;
* } * }
* ]| * ```
* *
* ## Controlling Authorization # {#auth-observer} * ## Controlling Authorization
* *
* By default, a #GDBusServer or server-side #GDBusConnection will accept * By default, a `GDBusServer` or server-side `GDBusConnection` will accept
* connections from any successfully authenticated user (but not from * connections from any successfully authenticated user (but not from
* anonymous connections using the `ANONYMOUS` mechanism). If you only * anonymous connections using the `ANONYMOUS` mechanism). If you only
* want to allow D-Bus connections from processes owned by the same uid * want to allow D-Bus connections from processes owned by the same uid
* as the server, since GLib 2.68, you should use the * as the server, since GLib 2.68, you should use the
* %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent * `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag. It’s equivalent
* to the following signal handler: * to the following signal handler:
* *
* |[<!-- language="C" --> * ```c
* static gboolean * static gboolean
* on_authorize_authenticated_peer (GDBusAuthObserver *observer, * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
* GIOStream *stream, * GIOStream *stream,
@ -97,7 +96,9 @@
* *
* return authorized; * return authorized;
* } * }
* ]| * ```
*
* Since: 2.26
*/ */
typedef struct _GDBusAuthObserverClass GDBusAuthObserverClass; typedef struct _GDBusAuthObserverClass GDBusAuthObserverClass;
@ -126,14 +127,6 @@ struct _GDBusAuthObserverClass
const gchar *mechanism); const gchar *mechanism);
}; };
/**
* GDBusAuthObserver:
*
* The #GDBusAuthObserver structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GDBusAuthObserver struct _GDBusAuthObserver
{ {
GObject parent_instance; GObject parent_instance;

64
gio/gdbusconnection.c
View File

@ -131,59 +131,61 @@
G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER) G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER)
/** /**
* SECTION:gdbusconnection * GDBusConnection:
* @short_description: D-Bus Connections
* @include: gio/gio.h
* *
* The #GDBusConnection type is used for D-Bus connections to remote * The `GDBusConnection` type is used for D-Bus connections to remote
* peers such as a message buses. It is a low-level API that offers a * peers such as a message buses.
* lot of flexibility. For instance, it lets you establish a connection *
* over any transport that can by represented as a #GIOStream. * It is a low-level API that offers a lot of flexibility. For instance,
* it lets you establish a connection over any transport that can by represented
* as a [struct@Gio.IOStream].
* *
* This class is rarely used directly in D-Bus clients. If you are writing * This class is rarely used directly in D-Bus clients. If you are writing
* a D-Bus client, it is often easier to use the g_bus_own_name(), * a D-Bus client, it is often easier to use the [func@g_bus_own_name],
* g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. * [func@g_bus_watch_name] or [ctor@Gio.DBusProxy.new_for_bus] APIs.
* *
* As an exception to the usual GLib rule that a particular object must not * As an exception to the usual GLib rule that a particular object must not
* be used by two threads at the same time, #GDBusConnection's methods may be * be used by two threads at the same time, `GDBusConnection`s methods may be
* called from any thread. This is so that g_bus_get() and g_bus_get_sync() * called from any thread. This is so that `g_bus_get()` and `g_bus_get_sync()`
* can safely return the same #GDBusConnection when called from any thread. * can safely return the same `GDBusConnection` when called from any thread.
* *
* Most of the ways to obtain a #GDBusConnection automatically initialize it * Most of the ways to obtain a `GDBusConnection` automatically initialize it
* (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and * (i.e. connect to D-Bus): for instance, [func@Gio.DBusConnection.new] and
* g_bus_get(), and the synchronous versions of those methods, give you an * `g_bus_get()`, and the synchronous versions of those methods, give you an
* initialized connection. Language bindings for GIO should use * initialized connection. Language bindings for GIO should use
* g_initable_new() or g_async_initable_new_async(), which also initialize the * [func@Gio.Initiable.new] or [func@Gio.AsyncInitable.new_async], which also
* connection. * initialize the connection.
* *
* If you construct an uninitialized #GDBusConnection, such as via * If you construct an uninitialized `GDBusConnection`, such as via
* g_object_new(), you must initialize it via g_initable_init() or * `g_object_new()`, you must initialize it via [method@Gio.Initable.init] or
* g_async_initable_init_async() before using its methods or properties. * [method@Gio.AsyncInitable.init_async] before using its methods or properties.
* Calling methods or accessing properties on a #GDBusConnection that has not * Calling methods or accessing properties on a `GDBusConnection` that has not
* completed initialization successfully is considered to be invalid, and leads * completed initialization successfully is considered to be invalid, and leads
* to undefined behaviour. In particular, if initialization fails with a * to undefined behaviour. In particular, if initialization fails with a
* #GError, the only valid thing you can do with that #GDBusConnection is to * `GError`, the only valid thing you can do with that `GDBusConnection` is to
* free it with g_object_unref(). * free it with `g_object_unref()`.
* *
* ## An example D-Bus server # {#gdbus-server} * ## An example D-Bus server
* *
* Here is an example for a D-Bus server: * Here is an example for a D-Bus server:
* [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) * [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c)
* *
* ## An example for exporting a subtree # {#gdbus-subtree-server} * ## An example for exporting a subtree
* *
* Here is an example for exporting a subtree: * Here is an example for exporting a subtree:
* [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) * [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c)
* *
* ## An example for file descriptor passing # {#gdbus-unix-fd-client} * ## An example for file descriptor passing
* *
* Here is an example for passing UNIX file descriptors: * Here is an example for passing UNIX file descriptors:
* [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) * [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c)
* *
* ## An example for exporting a GObject # {#gdbus-export} * ## An example for exporting a GObject
* *
* Here is an example for exporting a #GObject: * Here is an example for exporting a #GObject:
* [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) * [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c)
*
* Since: 2.26
*/ */
/* ---------------------------------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------------------------------- */
@ -312,14 +314,6 @@ enum {
FLAG_CLOSED = 1 << 2 FLAG_CLOSED = 1 << 2
}; };
/**
* GDBusConnection:
*
* The #GDBusConnection structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GDBusConnection struct _GDBusConnection
{ {
/*< private >*/ /*< private >*/

14
gio/gdbusinterface.c
View File

@ -28,13 +28,15 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gdbusinterface * GDBusInterface:
* @short_description: Base type for D-Bus interfaces
* @include: gio/gio.h
* *
* The #GDBusInterface type is the base type for D-Bus interfaces both * Base type for D-Bus interfaces.
* on the service side (see #GDBusInterfaceSkeleton) and client side *
* (see #GDBusProxy). * The `GDBusInterface` type is the base type for D-Bus interfaces both
* on the service side (see [struct@Gio.DBusInterfaceSkeleton]) and client side
* (see [struct@Gio.DBusProxy]).
*
* Since: 2.30
*/ */
typedef GDBusInterfaceIface GDBusInterfaceInterface; typedef GDBusInterfaceIface GDBusInterfaceInterface;

8
gio/gdbusinterface.h
View File

@ -32,14 +32,6 @@ G_BEGIN_DECLS
#define G_IS_DBUS_INTERFACE(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_INTERFACE)) #define G_IS_DBUS_INTERFACE(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_DBUS_INTERFACE))
#define G_DBUS_INTERFACE_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), G_TYPE_DBUS_INTERFACE, GDBusInterfaceIface)) #define G_DBUS_INTERFACE_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE((o), G_TYPE_DBUS_INTERFACE, GDBusInterfaceIface))
/**
* GDBusInterface:
*
* Base type for D-Bus interfaces.
*
* Since: 2.30
*/
typedef struct _GDBusInterfaceIface GDBusInterfaceIface; typedef struct _GDBusInterfaceIface GDBusInterfaceIface;
/** /**

6
gio/gdbusinterfaceskeleton.c
View File

@ -36,11 +36,11 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gdbusinterfaceskeleton * GDBusInterfaceSkeleton:
* @short_description: Service-side D-Bus interface
* @include: gio/gio.h
* *
* Abstract base class for D-Bus interfaces on the service side. * Abstract base class for D-Bus interfaces on the service side.
*
* Since: 2.30
*/ */
struct _GDBusInterfaceSkeletonPrivate struct _GDBusInterfaceSkeletonPrivate

8
gio/gdbusinterfaceskeleton.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusInterfaceSkeletonClass GDBusInterfaceSkeletonClass; typedef struct _GDBusInterfaceSkeletonClass GDBusInterfaceSkeletonClass;
typedef struct _GDBusInterfaceSkeletonPrivate GDBusInterfaceSkeletonPrivate; typedef struct _GDBusInterfaceSkeletonPrivate GDBusInterfaceSkeletonPrivate;
/**
* GDBusInterfaceSkeleton:
*
* The #GDBusInterfaceSkeleton structure contains private data and should
* only be accessed using the provided API.
*
* Since: 2.30
*/
struct _GDBusInterfaceSkeleton struct _GDBusInterfaceSkeleton
{ {
/*< private >*/ /*< private >*/