luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +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)
/**
* SECTION:gaction
* @title: GAction
* @short_description: An action interface
* @include: gio/gio.h
* GAction:
*
* #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
* g_action_activate(). This results in the 'activate' signal being
* emitted. An activation has a #GVariant parameter (which may be
* %NULL). The correct type for the parameter is determined by a static
* [method@Gio.Action.activate]. This results in the 'activate' signal being
* emitted. An activation has a `GVariant` parameter (which may be
* `NULL`). The correct type for the parameter is determined by a static
* parameter type (which is given at construction time).
*
* 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
* (which is given at construction time).
*
* The state may have a hint associated with it, specifying its valid
* 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
* #GSimpleAction.
* [struct@Gio.SimpleAction].
*
* In all cases, the implementing class is responsible for storing the
* name of the action, the parameter type, the enabled state, the
* optional state type and the state and emitting the appropriate
* signals when these change. The implementor is responsible for filtering
* calls to g_action_activate() and g_action_change_state() for type
* safety and for the state being enabled.
* name of the action, the parameter type, the enabled state, the optional
* state type and the state and emitting the appropriate signals when these
* change. The implementor is responsible for filtering calls to
* [method@Gio.Action.activate] and [method@Gio.Action.change_state]
* for type safety and for the state being enabled.
*
* Probably the only useful thing to do with a #GAction is to put it
* inside of a #GSimpleActionGroup.
**/
/**
* GAction:
*
* #GAction is an opaque data structure and can only be accessed
* using the following functions.
* Probably the only useful thing to do with a `GAction` is to put it
* inside of a [struct@Gio.SimpleActionGroup].
**/
/**

64
gio/gactiongroup.c
View File

@ -26,31 +26,26 @@
#include "gmarshal-internal.h"
/**
* SECTION:gactiongroup
* @title: GActionGroup
* @short_description: A group of actions
* @include: gio/gio.h
* @see_also: #GAction
* GActionGroup:
*
* #GActionGroup represents a group of actions. Actions can be used to
* 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.
* `GActionGroup` represents a group of actions.
*
* The main way to interact with the actions in a GActionGroup is to
* activate them with g_action_group_activate_action(). Activating an
* action may require a #GVariant parameter. The required type of the
* parameter can be inquired with g_action_group_get_action_parameter_type().
* Actions may be disabled, see g_action_group_get_action_enabled().
* Actions can be used to 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
* 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.
*
* Actions may optionally have a state in the form of a #GVariant. The
* current state of an action can be inquired with
* g_action_group_get_action_state(). Activating a stateful action may
* change its state, but it is also possible to set the state by calling
* g_action_group_change_action_state().
* Actions may optionally have a state in the form of a #GVariant. The current
* state of an action can be inquired with [method@Gio.ActionGroup.get_action_state].
* Activating a stateful action may change its state, but it is also possible to
* set the state by calling [method@Gio.ActionGroup.change_action_state].
*
* As typical example, consider a text editing application which has an
* option to change the current font to 'bold'. A good way to represent
@ -58,34 +53,27 @@
* action would toggle the state.
*
* 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.
*
* The #GActionGroup API is meant to be the 'public' API to the action
* group. The calls here are exactly the interaction that 'external
* The `GActionGroup` API is meant to be the 'public' API to the action
* group. The calls here are exactly the interaction that 'external
* forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
* with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is
* why you will find - for example - g_action_group_get_action_enabled()
* with actions. 'Internal' APIs (ie: ones meant only to be accessed by
* the action group implementation) are found on subclasses. This is
* why you will find - for example - [method@Gio.ActionGroup.get_action_enabled]
* but not an equivalent set() call.
*
* Signals are emitted on the action group in response to state changes
* on individual actions.
*
* Implementations of #GActionGroup should provide implementations for
* the virtual functions g_action_group_list_actions() and
* g_action_group_query_action(). The other virtual functions should
* Implementations of `GActionGroup` should provide implementations for
* the virtual functions [method@Gio.ActionGroup.list_actions] and
* [method@Gio.ActionGroup.query_action]. The other virtual functions should
* 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:
* @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"
/**
* SECTION:gactionmap
* @title: GActionMap
* @include: gio/gio.h
* @short_description: Interface for action containers
* GActionMap:
*
* The GActionMap interface is implemented by #GActionGroup
* implementations that operate by containing a number of
* named #GAction instances, such as #GSimpleActionGroup.
* `GActionMap` is an interface for action containers.
*
* 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
* names of actions from various action groups to unique,
@ -42,14 +41,7 @@
* name.
*
* Since: 2.32
**/
/**
* GActionMap:
*
* #GActionMap is an opaque data structure and can only be accessed
* using the following functions.
**/
*/
/**
* GActionMapInterface:

117
gio/gappinfo.c
View File

@ -45,37 +45,37 @@
#endif
/**
* SECTION:gappinfo
* @short_description: Application information and launch contexts
* @include: gio/gio.h
* @see_also: #GAppInfoMonitor
*
* #GAppInfo and #GAppLaunchContext are used for describing and launching
* GAppInfo:
*
* Information about an installed application and methods to launch
* it (with file arguments).
* `GAppInfo` and `GAppLaunchContext` are used for describing and launching
* applications installed on the system.
*
* 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
* the application requested an URI and not a POSIX path. For example
* (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch]
* even if the application requested an URI and not a POSIX path. For example
* for a desktop-file based application with Exec key `totem
* %U` and a single URI, `sftp://foo/file.avi`, then
* `/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
* 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
* 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.
*
* Specifically for gvfs 2.26 and later, the POSIX URI will be mapped
* back to the GIO URI in the #GFile constructors (since gvfs
* implements the #GVfs extension point). As such, if the application
* needs to examine the URI, it needs to use g_file_get_uri() or
* similar on #GFile. In other words, an application cannot assume
* that the URI passed to e.g. g_file_new_for_commandline_arg() is
* equal to the result of g_file_get_uri(). The following snippet
* Specifically for GVfs 2.26 and later, the POSIX URI will be mapped
* back to the GIO URI in the [struct@Gio.File] constructors (since GVfs
* implements the GVfs extension point). As such, if the application
* needs to examine the URI, it needs to use [method@Gio.File.get_uri]
* or similar on [struct@Gio.File]. In other words, an application cannot
* assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg]
* is equal to the result of [method@Gio.File.get_uri]. The following snippet
* illustrates this:
*
* |[
* ```c
* GFile *f;
* char *uri;
*
@ -90,7 +90,7 @@
* // do something special with uri
* }
* g_object_unref (file);
* ]|
* ```
*
* 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
@ -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:
*
* The only thing you can do with this is to get it via
* g_app_info_monitor_get() and connect to the "changed" signal.
* `GAppInfoMonitor` monitors 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 [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
**/
*/
typedef struct _GAppInfoMonitorClass GAppInfoMonitorClass;

7
gio/gappinfo.h
View File

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

114
gio/gapplication.c
View File

@ -45,25 +45,25 @@
#include <string.h>
/**
* SECTION:gapplication
* @title: GApplication
* @short_description: Core application class
* @include: gio/gio.h
* GApplication:
*
* 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
* 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.
*
* 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
* be changed using g_application_hold() and g_application_release(). If
* it drops to zero, the application exits. Higher-level classes such as
* #GtkApplication employ the use count to ensure that the application
* stays alive as long as it has any opened windows.
* be changed using [method@Gio.Application.hold] and
* [method@Gio.Application.release]. If it drops to zero, the application
* exits. Higher-level classes such as `GtkApplication` employ the use count
* 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
* providing a unique application ID. If given, only one application
* 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
* 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
* application is not expected to manually register itself and check
* 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
* 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
* startup signal is emitted and the mainloop runs. If the application
* 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.
*
* 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
* [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`,
* `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 the user's session bus. This means that the uniqueness of your
* application is scoped to the current session. It also means that 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 may provide additional services (through registration of other
* 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
* 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
* 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
* attempts to acquire the bus name of your application (which happens in
* g_application_register()). Unfortunately, this means that you cannot use
* g_application_get_is_remote() to decide if you want to register object paths.
* [method@Gio.Application.register]). Unfortunately, this means that you cannot
* 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
* g_action_map_add_action(). When invoking an action by calling
* g_action_group_activate_action() on the application, it is always
* [method@Gio.ActionMap.add_action]. When invoking an action by calling
* [method@Gio.ActionGroup.activate_action] on the application, it is always
* invoked in the primary instance. The actions are also exported on
* the session bus, and GIO provides the #GDBusActionGroup wrapper to
* conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper
* for remote access to exported #GMenuModels.
* the session bus, and GIO provides the [struct@Gio.DBusActionGroup] wrapper to
* conveniently access them remotely. GIO provides a [struct@Gio.DBusMenuModel] wrapper
* for remote access to exported [struct@Gio.MenuModel]s.
*
* 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
* `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)
*
@ -131,50 +132,45 @@
*
* - 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.
*
* 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
* #GVariant dictionary mapping strings to variants. To use platform
* data, override the @before_emit or @after_emit virtual functions
* in your #GApplication subclass. When dealing with
* #GApplicationCommandLine objects, the platform data is
* directly available via g_application_command_line_get_cwd(),
* g_application_command_line_get_environ() and
* g_application_command_line_get_platform_data().
* [struct@GLib.Variant] dictionary mapping strings to variants. To use platform
* data, override the [vfunc@Gio.Application.before_emit] or
* [vfunc@Gio.Application.after_emit] virtual functions
* in your `GApplication` subclass. When dealing with
* [struct@Gio.ApplicationCommandLine] objects, the platform data is
* directly available via [method@Gio.ApplicationCommandLine.get_cwd],
* [method@Gio.ApplicationCommandLine.get_environ] and
* [method@Gio.ApplicationCommandLine.get_platform_data].
*
* As the name indicates, the platform data may vary depending on the
* operating system, but it always includes the current directory (key
* "cwd"), and optionally the environment (ie the set of environment
* variables and their values) of the calling process (key "environ").
* `cwd`), and optionally the environment (ie the set of environment
* variables and their values) of the calling process (key `environ`).
* The environment is only added to the platform data if the
* %G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses
* can add their own platform data by overriding the @add_platform_data
* virtual function. For instance, #GtkApplication adds startup notification
* data in this way.
* `G_APPLICATION_SEND_ENVIRONMENT` flag is set. `GApplication` subclasses
* can add their own platform data by overriding the
* [vfunc@Gio.Application.add_platform_data] virtual function. For instance,
* `GtkApplication` adds startup notification data in this way.
*
* To parse commandline arguments you may handle the
* #GApplication::command-line signal or override the local_command_line()
* vfunc, to parse them in either the primary instance or the local instance,
* respectively.
* [signal@Gio.Application.command-line] signal or override the
* [vfunc@Gio.Application.local_command_line] virtual funcion, to parse them in
* 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).
*
* 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).
*
* 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:
*
* #GApplication is an opaque data structure and can only be accessed
* using the following functions.
* Since: 2.28
*/

68
gio/gapplicationcommandline.c
View File

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

25
gio/gasyncinitable.c
View File

@ -29,27 +29,26 @@
/**
* SECTION:gasyncinitable
* @short_description: Asynchronously failable object initialization interface
* @include: gio/gio.h
* @see_also: #GInitable
* GAsyncInitable:
*
* 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
* 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
* 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
* g_async_initable_init_async() under the cover, calling back with %NULL and
* a set %GError on failure.
* [func@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL`
* and a set `GError` on failure.
*
* A typical implementation might look something like this:
*
* |[<!-- language="C" -->
* ```c
* enum {
* NOT_INITIALIZED,
* INITIALIZING,
@ -132,7 +131,9 @@
* iface->init_async = foo_init_async;
* iface->init_finish = foo_init_finish;
* }
* ]|
* ```
*
* Since: 2.22
*/
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_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;
/**

52
gio/gasyncresult.c
View File

@ -27,42 +27,40 @@
/**
* SECTION:gasyncresult
* @short_description: Asynchronous Function Results
* @include: gio/gio.h
* @see_also: #GTask
* GAsyncResult:
*
* 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
* which are chained together by a #GAsyncReadyCallback. To begin
* an asynchronous operation, provide a #GAsyncReadyCallback to the
* which are chained together by a `GAsyncReadyCallback`. To begin
* an asynchronous operation, provide a `GAsyncReadyCallback` to the
* asynchronous function. This callback will be triggered when the
* operation has completed, and must be run in a later iteration of
* the [thread-default main context][g-main-context-push-thread-default]
* from where the operation was initiated. It will be passed a
* #GAsyncResult instance filled with the details of the operation's
* success or failure, the object the asynchronous function was
* started for and any error codes returned. The asynchronous callback
* function is then expected to call the corresponding "_finish()"
* the thread-default main context (see
* [method@GLib.MainContext.push_thread_default]) from where the operation was
* initiated. It will be passed a `GAsyncResult` instance filled with the
* details of the operation's success or failure, the object the asynchronous
* function was started for and any error codes returned. The asynchronous
* callback function is then expected to call the corresponding `_finish()`
* 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.
*
* The "_finish()" function for an operation takes the generic result
* (of type #GAsyncResult) and returns the specific result that the
* operation in question yields (e.g. a #GFileEnumerator for a
* The `_finish()` function for an operation takes the generic result
* (of type `GAsyncResult`) and returns the specific result that the
* operation in question yields (e.g. a [struct@Gio.FileEnumerator] for a
* "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
* information after the #GAsyncReadyCallback returns. You can pass
* %NULL for the #GAsyncReadyCallback if you don't need to take any
* information after the `GAsyncReadyCallback` returns. You can pass
* `NULL` for the `GAsyncReadyCallback` if you don't need to take any
* action at all after the operation completes. Applications may also
* take a reference to the #GAsyncResult and call "_finish()" later;
* however, the "_finish()" function may be called at most once.
* take a reference to the `GAsyncResult` and call `_finish()` later;
* however, the `_finish()` function may be called at most once.
*
* Example of a typical asynchronous operation flow:
* |[<!-- language="C" -->
*
* ```c
* void _theoretical_frobnitz_async (Theoretical *t,
* GCancellable *c,
* GAsyncReadyCallback cb,
@ -101,20 +99,20 @@
*
* ...
* }
* ]|
* ```
*
* The callback for an asynchronous operation is called only once, and is
* 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,
* which is used in certain cases to determine the order in which
* operations are executed. They are not used to determine system-wide
* I/O scheduling. Priorities are integers, with lower numbers indicating
* 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.
*/

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_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;

18
gio/gbufferedinputstream.c
View File

@ -34,25 +34,21 @@
/**
* SECTION:gbufferedinputstream
* @short_description: Buffered Input Stream
* @include: gio/gio.h
* @see_also: #GFilterInputStream, #GInputStream
* GBufferedInputStream:
*
* Buffered input stream implements #GFilterInputStream and provides
* 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(),
* or g_buffered_input_stream_new_sized() to specify the buffer's size at
* To create a buffered input stream, use [func@Gio.BufferedInputStream.new],
* or [func@Gio.BufferedInputStream.new_sized] to specify the buffer's size at
* construction.
*
* 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
* buffered input stream's buffer, use
* g_buffered_input_stream_set_buffer_size(). Note that the buffer's size
* cannot be reduced below the size of the data within the buffer.
* [method@Gio.BufferedInputStream.get_buffer_size]. To change the size of a
* buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_size].
* Note that the buffer's size 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_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 _GBufferedInputStreamPrivate GBufferedInputStreamPrivate;

34
gio/gbufferedoutputstream.c
View File

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

11
gio/gbytesicon.c
View File

@ -33,16 +33,13 @@
/**
* SECTION:gbytesicon
* @short_description: An icon stored in memory as a GBytes
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon, #GBytes
* GBytesIcon:
*
* #GBytesIcon specifies an image held in memory in a common format (usually
* png) to be used as icon.
* `GBytesIcon` specifies an image held in memory in a common format (usually
* PNG) to be used as icon.
*
* Since: 2.38
**/
*/
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_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
GType g_bytes_icon_get_type (void) G_GNUC_CONST;

8
gio/gcancellable.c
View File

@ -29,11 +29,11 @@
/**
* SECTION:gcancellable
* @short_description: Thread-safe Operation Cancellation Stack
* @include: gio/gio.h
* GCancellable:
*
* 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
* 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_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 _GCancellablePrivate GCancellablePrivate;

13
gio/gcharsetconverter.c
View File

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

11
gio/gconverter.c
View File

@ -26,12 +26,11 @@
/**
* SECTION:gconverter
* @short_description: Data conversion interface
* @include: gio/gio.h
* @see_also: #GInputStream, #GOutputStream
* GConverter:
*
* #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
* stateful and may fail at any place.
*
@ -40,7 +39,7 @@
* replace.
*
* Since: 2.24
**/
*/
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_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;
/**

13
gio/gconverterinputstream.c
View File

@ -33,17 +33,14 @@
/**
* SECTION:gconverterinputstream
* @short_description: Converter Input Stream
* @include: gio/gio.h
* @see_also: #GInputStream, #GConverter
* GConverterInputStream:
*
* Converter input stream implements #GInputStream and allows
* Converter input stream implements [iface@Gio.InputStream] and allows
* conversion of data of various types during reading.
*
* As of GLib 2.34, #GConverterInputStream implements
* #GPollableInputStream.
**/
* As of GLib 2.34, `GConverterInputStream` implements
* [iface@Gio.PollableInputStream].
*/
#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_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 _GConverterInputStreamPrivate GConverterInputStreamPrivate;

13
gio/gconverteroutputstream.c
View File

@ -33,17 +33,14 @@
/**
* SECTION:gconverteroutputstream
* @short_description: Converter Output Stream
* @include: gio/gio.h
* @see_also: #GOutputStream, #GConverter
* GConverterOutputStream:
*
* Converter output stream implements #GOutputStream and allows
* Converter output stream implements [iface@Gio.OutputStream] and allows
* conversion of data of various types during reading.
*
* As of GLib 2.34, #GConverterOutputStream implements
* #GPollableOutputStream.
**/
* As of GLib 2.34, `GConverterOutputStream` implements
* [iface@Gio.PollableOutputStream].
*/
#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_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 _GConverterOutputStreamPrivate GConverterOutputStreamPrivate;

82
gio/gcredentials.c
View File

@ -35,58 +35,48 @@
#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:
*
* The #GCredentials structure contains only private data and
* should only be accessed using the provided API.
* The `GCredentials` type is a reference-counted wrapper for native
* 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
*/
struct _GCredentials
{
/*< private >*/

47
gio/gdatagrambased.c
View File

@ -32,57 +32,56 @@
#include "glibintl.h"
/**
* SECTION:gdatagrambased
* @short_description: Low-level datagram communications interface
* @include: gio/gio.h
* @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
* GDatagramBased:
*
* 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
* 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
* alongside higher-level networking APIs such as #GIOStream.
* `GDatagramBased` is entirely platform independent, and is intended to be used
* alongside higher-level networking APIs such as [struct@Gio.IOStream].
*
* 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
* the interface should take advantage of vectored I/O to minimise processing
* or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
* possible. Callers should take advantage of scatter/gather I/O (the use of
* or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()`
* 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
* 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
* timeout behaviour. A blocking operation blocks until finished or there is an
* 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
* 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
* successfully run you can call g_datagram_based_condition_check() or
* g_datagram_based_condition_wait(). You can also use
* g_datagram_based_create_source() and attach it to a #GMainContext to get
* callbacks when I/O is possible.
* `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would
* successfully run you can call [method@Gio.DatagramBased.condition_check] or
* [method@Gio.DatagramBased.condition_wait]. You can also use
* [method@Gio.DatagramBased.create_source] and attach it to a [struct@Glib.MainContext]
* to get callbacks when I/O is possible.
*
* 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
* 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
* returns %G_IO_ERROR_WOULD_BLOCK.
* returns `G_IO_ERROR_WOULD_BLOCK`.
*
* As with #GSocket, #GDatagramBaseds can be either connection oriented (for
* example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
* As with `GSocket`, `GDatagramBased`s can be either connection oriented (for
* example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be
* datagram-based, not stream-based. The interface does not cover 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
* received in each I/O operation.
*
* Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
* To use a #GDatagramBased concurrently from multiple threads, you must
* Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe.
* To use a `GDatagramBased` concurrently from multiple threads, you must
* implement your own locking.
*
* 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), \
G_TYPE_DATAGRAM_BASED))
/**
* GDatagramBased:
*
* Interface for socket-like objects with datagram semantics.
*
* Since: 2.48
*/
typedef struct _GDatagramBasedInterface GDatagramBasedInterface;
/**

12
gio/gdatainputstream.c
View File

@ -33,15 +33,11 @@
#include <string.h>
/**
* SECTION: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.
* GDataInputStream:
*
**/
* Data input stream implements [iface@Gio.InputStream] and includes functions
* for reading structured data directly from a binary input stream.
*/
struct _GDataInputStreamPrivate {
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_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 _GDataInputStreamPrivate GDataInputStreamPrivate;

13
gio/gdataoutputstream.c
View File

@ -30,16 +30,11 @@
/**
* SECTION: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.
* GDataOutputStream:
*
**/
* Data output stream implements [iface@Gio.OutputStream] and includes functions
* for writing data directly to an output stream.
*/
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_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 _GDataOutputStreamClass GDataOutputStreamClass;
typedef struct _GDataOutputStreamPrivate GDataOutputStreamPrivate;

19
gio/gdbusactiongroup.c
View File

@ -28,23 +28,14 @@
#include "gdbusconnection.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 is an opaque data structure and can only be accessed
* using the following functions.
* `GDBusActionGroup` is an implementation of the [iface@Gio.ActionGroup]
* 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

51
gio/gdbusauthobserver.c
View File

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

64
gio/gdbusconnection.c
View File

@ -131,59 +131,61 @@
G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER)
/**
* SECTION:gdbusconnection
* @short_description: D-Bus Connections
* @include: gio/gio.h
* GDBusConnection:
*
* 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
* lot of flexibility. For instance, it lets you establish a connection
* over any transport that can by represented as a #GIOStream.
* 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 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
* a D-Bus client, it is often easier to use the g_bus_own_name(),
* g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
* a D-Bus client, it is often easier to use the [func@g_bus_own_name],
* [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
* 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()
* can safely return the same #GDBusConnection when called from any thread.
* 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()`
* can safely return the same `GDBusConnection` when called from any thread.
*
* Most of the ways to obtain a #GDBusConnection automatically initialize it
* (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
* g_bus_get(), and the synchronous versions of those methods, give you an
* Most of the ways to obtain a `GDBusConnection` automatically initialize it
* (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
* initialized connection. Language bindings for GIO should use
* g_initable_new() or g_async_initable_new_async(), which also initialize the
* connection.
* [func@Gio.Initiable.new] or [func@Gio.AsyncInitable.new_async], which also
* initialize the connection.
*
* If you construct an uninitialized #GDBusConnection, such as via
* g_object_new(), you must initialize it via g_initable_init() or
* g_async_initable_init_async() before using its methods or properties.
* Calling methods or accessing properties on a #GDBusConnection that has not
* If you construct an uninitialized `GDBusConnection`, such as via
* `g_object_new()`, you must initialize it via [method@Gio.Initable.init] or
* [method@Gio.AsyncInitable.init_async] before using its methods or properties.
* Calling methods or accessing properties on a `GDBusConnection` that has not
* completed initialization successfully is considered to be invalid, and leads
* to undefined behaviour. In particular, if initialization fails with a
* #GError, the only valid thing you can do with that #GDBusConnection is to
* free it with g_object_unref().
* `GError`, the only valid thing you can do with that `GDBusConnection` is to
* 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:
* [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:
* [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:
* [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:
* [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
};
/**
* GDBusConnection:
*
* The #GDBusConnection structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GDBusConnection
{
/*< private >*/

14
gio/gdbusinterface.c
View File

@ -28,13 +28,15 @@
#include "glibintl.h"
/**
* SECTION:gdbusinterface
* @short_description: Base type for D-Bus interfaces
* @include: gio/gio.h
* GDBusInterface:
*
* The #GDBusInterface type is the base type for D-Bus interfaces both
* on the service side (see #GDBusInterfaceSkeleton) and client side
* (see #GDBusProxy).
* Base type for D-Bus interfaces.
*
* 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;

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_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;
/**

6
gio/gdbusinterfaceskeleton.c
View File

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

8
gio/gdbusinterfaceskeleton.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusInterfaceSkeletonClass GDBusInterfaceSkeletonClass;
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
{
/*< private >*/