luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 07:26:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

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

See merge request GNOME/glib!3690
This commit is contained in:
Philip Withnall 2023-11-02 17:01:19 +00:00
commit 7e7a6271fe
42 changed files with 326 additions and 539 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gio/gio.toml.in
View File

@ -42,6 +42,7 @@ urlmap_file = "urlmap.js"
content_files = [
"overview.md",
"file-attributes.md",
"tls-overview.md",
"migrating-gdbus.md",
"migrating-gconf.md",

1
docs/reference/gio/meson.build
View File

@ -230,6 +230,7 @@ expand_content_files = [
'migrating-gdbus.md',
'migrating-gnome-vfs.md',
'overview.md',
'tls-overview.md',
]
gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)

37
docs/reference/gio/tls-overview.md Normal file
View File

@ -0,0 +1,37 @@
Title: TLS Overview
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2010 Dan Winship
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
# TLS Overview
[class@Gio.TlsConnection] and related classes provide TLS (Transport Layer
Security, previously known as SSL, Secure Sockets Layer) support for GIO-based
network streams.
[iface@Gio.DtlsConnection] and related classes provide DTLS (Datagram TLS)
support for GIO-based network sockets, using the [iface@Gio.DatagramBased]
interface. The TLS and DTLS APIs are almost identical, except TLS is
stream-based and DTLS is datagram-based. They share certificate and backend
infrastructure.
In the simplest case, for a client TLS connection, you can just set the
[property@Gio.SocketClient:tls] flag on a [class@Gio.SocketClient], and then any
connections created by that client will have TLS negotiated automatically, using
appropriate default settings, and rejecting any invalid or self-signed
certificates (unless you change that default by setting the
[property@Gio.SocketClient:tls-validation-flags] property). The returned object
will be a [class@Gio.TcpWrapperConnection], which wraps the underlying
[iface@Gio.TlsClientConnection].
For greater control, you can create your own [iface@Gio.TlsClientConnection],
wrapping a [class@Gio.SocketConnection] (or an arbitrary [class@Gio.IOStream]
with pollable input and output streams) and then connect to its signals,
such as [signal@Gio.TlsConnection::accept-certificate], before starting the
handshake.
Server-side TLS is similar, using [iface@Gio.TlsServerConnection]. At the
moment, there is no support for automatically wrapping server-side
connections in the way [class@Gio.SocketClient] does for client-side
connections.

17
gio/gdbusobject.c
View File

@ -28,22 +28,13 @@
#include "glibintl.h"
/**
* SECTION:gdbusobject
* @short_description: Base type for D-Bus objects
* @include: gio/gio.h
*
* The #GDBusObject type is the base type for D-Bus objects on both
* the service side (see #GDBusObjectSkeleton) and the client side
* (see #GDBusObjectProxy). It is essentially just a container of
* interfaces.
*/
/**
* GDBusObject:
*
* #GDBusObject is an opaque data structure and can only be accessed
* using the following functions.
* The `GDBusObject` type is the base type for D-Bus objects on both
* the service side (see [class@Gio.DBusObjectSkeleton]) and the client side
* (see [class@Gio.DBusObjectProxy]). It is essentially just a container of
* interfaces.
*/
typedef GDBusObjectIface GDBusObjectInterface;

30
gio/gremoteactiongroup.c
View File

@ -27,43 +27,33 @@
#include "gaction.h"
/**
* SECTION:gremoteactiongroup
* @title: GRemoteActionGroup
* @short_description: A GActionGroup that interacts with other processes
* @include: gio/gio.h
* GRemoteActionGroup:
*
* The GRemoteActionGroup interface is implemented by #GActionGroup
* The `GRemoteActionGroup` interface is implemented by [iface@Gio.ActionGroup]
* instances that either transmit action invocations to other processes
* or receive action invocations in the local process from other
* processes.
*
* The interface has `_full` variants of the two
* methods on #GActionGroup used to activate actions:
* g_action_group_activate_action() and
* g_action_group_change_action_state(). These variants allow a
* "platform data" #GVariant to be specified: a dictionary providing
* methods on [iface@Gio.ActionGroup] used to activate actions:
* [method@Gio.ActionGroup.activate_action] and
* [method@Gio.ActionGroup.change_action_state]. These variants allow a
* ‘platform data’ [struct@GLib.Variant] to be specified: a dictionary providing
* context for the action invocation (for example: timestamps, startup
* notification IDs, etc).
*
* #GDBusActionGroup implements #GRemoteActionGroup. This provides a
* [class@Gio.DBusActionGroup] implements `GRemoteActionGroup`. This provides a
* mechanism to send platform data for action invocations over D-Bus.
*
* Additionally, g_dbus_connection_export_action_group() will check if
* the exported #GActionGroup implements #GRemoteActionGroup and use the
* `_full` variants of the calls if available. This
* Additionally, [method@Gio.DBusConnection.export_action_group] will check if
* the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use
* the `_full` variants of the calls if available. This
* provides a mechanism by which to receive platform data for action
* invocations that arrive by way of D-Bus.
*
* Since: 2.32
**/
/**
* GRemoteActionGroup:
*
* #GRemoteActionGroup is an opaque data structure and can only be accessed
* using the following functions.
**/
/**
* GRemoteActionGroupInterface:
* @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full()

193
gio/gsettings.c
View File

@ -37,116 +37,115 @@
#include "strinfo.c"
/**
* SECTION:gsettings
* @short_description: High-level API for application settings
* @include: gio/gio.h
* GSettings:
*
* The #GSettings class provides a convenient API for storing and retrieving
* The `GSettings` class provides a convenient API for storing and retrieving
* application settings.
*
* Reads and writes can be considered to be non-blocking. Reading
* settings with #GSettings is typically extremely fast: on
* settings with `GSettings` is typically extremely fast: on
* approximately the same order of magnitude (but slower than) a
* #GHashTable lookup. Writing settings is also extremely fast in terms
* of time to return to your application, but can be extremely expensive
* [struct@GLib.HashTable] lookup. Writing settings is also extremely fast in
* terms of time to return to your application, but can be extremely expensive
* for other threads and other processes. Many settings backends
* (including dconf) have lazy initialisation which means in the common
* case of the user using their computer without modifying any settings
* a lot of work can be avoided. For dconf, the D-Bus service doesn't
* a lot of work can be avoided. For dconf, the D-Bus service doesn’t
* even need to be started in this case. For this reason, you should
* only ever modify #GSettings keys in response to explicit user action.
* only ever modify `GSettings` keys in response to explicit user action.
* Particular care should be paid to ensure that modifications are not
* made during startup -- for example, when setting the initial value
* of preferences widgets. The built-in g_settings_bind() functionality
* is careful not to write settings in response to notify signals as a
* result of modifications that it makes to widgets.
* made during startup — for example, when setting the initial value
* of preferences widgets. The built-in [method@Gio.Settings.bind]
* functionality is careful not to write settings in response to notify signals
* as a result of modifications that it makes to widgets.
*
* When creating a GSettings instance, you have to specify a schema
* When creating a `GSettings` instance, you have to specify a schema
* that describes the keys in your settings and their types and default
* values, as well as some other information.
*
* Normally, a schema has a fixed path that determines where the settings
* are stored in the conceptual global tree of settings. However, schemas
* can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with
* can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with
* a fixed path. This is
* useful e.g. when the schema describes an 'account', and you want to be
* useful e.g. when the schema describes an ‘account’, and you want to be
* able to store a arbitrary number of accounts.
*
* Paths must start with and end with a forward slash character ('/')
* Paths must start with and end with a forward slash character (`/`)
* and must not contain two sequential slash characters. Paths should
* be chosen based on a domain name associated with the program or
* library to which the settings belong. Examples of paths are
* "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/".
* Paths should not start with "/apps/", "/desktop/" or "/system/" as
* `/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`.
* Paths should not start with `/apps/`, `/desktop/` or `/system/` as
* they often did in GConf.
*
* Unlike other configuration systems (like GConf), GSettings does not
* restrict keys to basic types like strings and numbers. GSettings stores
* values as #GVariant, and allows any #GVariantType for keys. Key names
* are restricted to lowercase characters, numbers and '-'. Furthermore,
* the names must begin with a lowercase character, must not end
* with a '-', and must not contain consecutive dashes.
* values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for
* keys. Key names are restricted to lowercase characters, numbers and `-`.
* Furthermore, the names must begin with a lowercase character, must not end
* with a `-`, and must not contain consecutive dashes.
*
* Similar to GConf, the default values in GSettings schemas can be
* localized, but the localized values are stored in gettext catalogs
* and looked up with the domain that is specified in the
* `gettext-domain` attribute of the <schemalist> or <schema>
* `gettext-domain` attribute of the `<schemalist>` or `<schema>`
* elements and the category that is specified in the `l10n` attribute of
* the <default> element. The string which is translated includes all text in
* the <default> element, including any surrounding quotation marks.
* the `<default>` element. The string which is translated includes all text in
* the `<default>` element, including any surrounding quotation marks.
*
* The `l10n` attribute must be set to `messages` or `time`, and sets the
* [locale category for
* translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1).
* The `messages` category should be used by default; use `time` for
* translatable date or time formats. A translation comment can be added as an
* XML comment immediately above the <default> element — it is recommended to
* XML comment immediately above the `<default>` element — it is recommended to
* add these comments to aid translators understand the meaning and
* implications of the default value. An optional translation `context`
* attribute can be set on the <default> element to disambiguate multiple
* attribute can be set on the `<default>` element to disambiguate multiple
* defaults which use the same string.
*
* For example:
* |[
* ```xml
* <!-- Translators: A list of words which are not allowed to be typed, in
* GVariant serialization syntax.
* See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
* <default l10n='messages' context='Banned words'>['bad', 'words']</default>
* ]|
* ```
*
* Translations of default values must remain syntactically valid serialized
* #GVariants (e.g. retaining any surrounding quotation marks) or runtime
* errors will occur.
* [struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or
* runtime errors will occur.
*
* GSettings uses schemas in a compact binary form that is created
* by the [glib-compile-schemas][glib-compile-schemas]
* by the [`glib-compile-schemas`](glib-compile-schemas.html)
* utility. The input is a schema description in an XML format.
*
* A DTD for the gschema XML format can be found here:
* [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)
*
* The [glib-compile-schemas][glib-compile-schemas] tool expects schema
* The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema
* files to have the extension `.gschema.xml`.
*
* At runtime, schemas are identified by their id (as specified in the
* id attribute of the <schema> element). The convention for schema
* ids is to use a dotted name, similar in style to a D-Bus bus name,
* e.g. "org.gnome.SessionManager". In particular, if the settings are
* At runtime, schemas are identified by their ID (as specified in the
* `id` attribute of the `<schema>` element). The convention for schema
* IDs is to use a dotted name, similar in style to a D-Bus bus name,
* e.g. `org.gnome.SessionManager`. In particular, if the settings are
* for a specific service that owns a D-Bus bus name, the D-Bus bus name
* and schema id should match. For schemas which deal with settings not
* associated with one named application, the id should not use
* StudlyCaps, e.g. "org.gnome.font-rendering".
* and schema ID should match. For schemas which deal with settings not
* associated with one named application, the ID should not use
* StudlyCaps, e.g. `org.gnome.font-rendering`.
*
* In addition to #GVariant types, keys can have types that have
* enumerated types. These can be described by a <choice>,
* <enum> or <flags> element, as seen in the
* [example][schema-enumerated]. The underlying type of such a key
* is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
* g_settings_get_flags(), g_settings_set_flags() access the numeric values
* corresponding to the string value of enum and flags keys.
* In addition to [struct@GLib.Variant] types, keys can have types that have
* enumerated types. These can be described by a `<choice>`,
* `<enum>` or `<flags>` element, as seen in the
* second example below. The underlying type of such a key
* is string, but you can use [method@Gio.Settings.get_enum],
* [method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags],
* [method@Gio.Settings.set_flags] access the numeric values corresponding to
* the string value of enum and flags keys.
*
* An example for default value:
* |[
* ```xml
* <schemalist>
* <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
*
@ -169,10 +168,10 @@
*
* </schema>
* </schemalist>
* ]|
* ```
*
* An example for ranges, choices and enumerated types:
* |[
* ```xml
* <schemalist>
*
* <enum id="org.gtk.Test.myenum">
@ -215,7 +214,7 @@
* </key>
* </schema>
* </schemalist>
* ]|
* ```
*
* ## Vendor overrides
*
@ -223,41 +222,42 @@
* an application. Sometimes, it is necessary for a vendor or distributor
* to adjust these defaults. Since patching the XML source for the schema
* is inconvenient and error-prone,
* [glib-compile-schemas][glib-compile-schemas] reads so-called vendor
* override' files. These are keyfiles in the same directory as the XML
* schema sources which can override default values. The schema id serves
* [`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor
* override’ files. These are keyfiles in the same directory as the XML
* schema sources which can override default values. The schema ID serves
* as the group name in the key file, and the values are expected in
* serialized GVariant form, as in the following example:
* |[
* [org.gtk.Example]
* key1='string'
* key2=1.5
* ]|
* serialized [struct@GLib.Variant] form, as in the following example:
* ```
* [org.gtk.Example]
* key1='string'
* key2=1.5
* ```
*
* glib-compile-schemas expects schema files to have the extension
* `glib-compile-schemas` expects schema files to have the extension
* `.gschema.override`.
*
* ## Binding
*
* A very convenient feature of GSettings lets you bind #GObject properties
* directly to settings, using g_settings_bind(). Once a GObject property
* has been bound to a setting, changes on either side are automatically
* propagated to the other side. GSettings handles details like mapping
* between GObject and GVariant types, and preventing infinite cycles.
* A very convenient feature of GSettings lets you bind [class@GObject.Object]
* properties directly to settings, using [method@Gio.Settings.bind]. Once a
* [class@GObject.Object] property has been bound to a setting, changes on
* either side are automatically propagated to the other side. GSettings handles
* details like mapping between [class@GObject.Object] and [struct@GLib.Variant]
* types, and preventing infinite cycles.
*
* This makes it very easy to hook up a preferences dialog to the
* underlying settings. To make this even more convenient, GSettings
* looks for a boolean property with the name "sensitivity" and
* looks for a boolean property with the name `sensitivity` and
* automatically binds it to the writability of the bound setting.
* If this 'magic' gets in the way, it can be suppressed with the
* %G_SETTINGS_BIND_NO_SENSITIVITY flag.
* If this ‘magic’ gets in the way, it can be suppressed with the
* `G_SETTINGS_BIND_NO_SENSITIVITY` flag.
*
* ## Relocatable schemas # {#gsettings-relocatable}
* ## Relocatable schemas
*
* A relocatable schema is one with no `path` attribute specified on its
* <schema> element. By using g_settings_new_with_path(), a #GSettings object
* can be instantiated for a relocatable schema, assigning a path to the
* instance. Paths passed to g_settings_new_with_path() will typically be
* `<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings`
* object can be instantiated for a relocatable schema, assigning a path to the
* instance. Paths passed to [ctor@Gio.Settings.new_with_path] will typically be
* constructed dynamically from a constant prefix plus some form of instance
* identifier; but they must still be valid GSettings paths. Paths could also
* be constant and used with a globally installed schema originating from a
@ -268,59 +268,59 @@
* `org.foo.MyApp.Window`, it could be instantiated for paths
* `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`,
* `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known
* they can be specified as <child> elements in the parent schema, e.g.:
* |[
* they can be specified as `<child>` elements in the parent schema, e.g.:
* ```xml
* <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
* <child name="main" schema="org.foo.MyApp.Window"/>
* </schema>
* ]|
* ```
*
* ## Build system integration # {#gsettings-build-system}
* ## Build system integration
*
* GSettings comes with autotools integration to simplify compiling and
* installing schemas. To add GSettings support to an application, add the
* following to your `configure.ac`:
* |[
* ```
* GLIB_GSETTINGS
* ]|
* ```
*
* In the appropriate `Makefile.am`, use the following snippet to compile and
* install the named schema:
* |[
* ```
* gsettings_SCHEMAS = org.foo.MyApp.gschema.xml
* EXTRA_DIST = $(gsettings_SCHEMAS)
*
* @GSETTINGS_RULES@
* ]|
* ```
*
* No changes are needed to the build system to mark a schema XML file for
* translation. Assuming it sets the `gettext-domain` attribute, a schema may
* be marked for translation by adding it to `POTFILES.in`, assuming gettext
* 0.19 is in use (the preferred method for translation):
* |[
* ```
* data/org.foo.MyApp.gschema.xml
* ]|
* ```
*
* Alternatively, if intltool 0.50.1 is in use:
* |[
* ```
* [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
* ]|
* ```
*
* GSettings will use gettext to look up translations for the <summary> and
* <description> elements, and also any <default> elements which have a `l10n`
* attribute set. Translations must not be included in the `.gschema.xml` file
* by the build system, for example by using intltool XML rules with a
* GSettings will use gettext to look up translations for the `<summary>` and
* `<description>` elements, and also any `<default>` elements which have a
* `l10n` attribute set. Translations must not be included in the `.gschema.xml`
* file by the build system, for example by using intltool XML rules with a
* `.gschema.xml.in` template.
*
* If an enumerated type defined in a C header file is to be used in a GSettings
* schema, it can either be defined manually using an <enum> element in the
* schema, it can either be defined manually using an `<enum>` element in the
* schema XML, or it can be extracted automatically from the C header. This
* approach is preferred, as it ensures the two representations are always
* synchronised. To do so, add the following to the relevant `Makefile.am`:
* |[
* ```
* gsettings_ENUM_NAMESPACE = org.foo.MyApp
* gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
* ]|
* ```
*
* `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files,
* which are specified in `gsettings_ENUM_FILES`. This will generate a
@ -330,13 +330,6 @@
* `EXTRA_DIST`.
*/
/**
* GSettings:
*
* #GSettings is an opaque data structure and can only be accessed
* using the following functions.
**/
struct _GSettingsPrivate
{
/* where the signals go... */

25
gio/gsettingsbackend.c
View File

@ -52,17 +52,13 @@ G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GSettingsBackend, g_settings_backend, G_TYP
static gboolean g_settings_has_backend;
/**
* SECTION:gsettingsbackend
* @title: GSettingsBackend
* @short_description: Interface for settings backend implementations
* @include: gio/gsettingsbackend.h
* @see_also: #GSettings, #GIOExtensionPoint
* GSettingsBackend:
*
* The #GSettingsBackend interface defines a generic interface for
* The `GSettingsBackend` interface defines a generic interface for
* non-strictly-typed data that is stored in a hierarchy. To implement
* an alternative storage backend for #GSettings, you need to implement
* the #GSettingsBackend interface and then make it implement the
* extension point %G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
* an alternative storage backend for [class@Gio.Settings], you need to
* implement the `GSettingsBackend` interface and then make it implement the
* extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`.
*
* The interface defines methods for reading and writing values, a
* method for determining if writing of certain values will fail
@ -72,15 +68,14 @@ static gboolean g_settings_has_backend;
* implementations must carefully adhere to the expectations of
* callers that are documented on each of the interface methods.
*
* Some of the #GSettingsBackend functions accept or return a #GTree.
* These trees always have strings as keys and #GVariant as values.
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
* Some of the `GSettingsBackend` functions accept or return a
* [struct@GLib.Tree]. These trees always have strings as keys and
* [struct@GLib.Variant] as values.
*
* The #GSettingsBackend API is exported to allow third-party
* The `GSettingsBackend` API is exported to allow third-party
* implementations, but does not carry the same stability guarantees
* as the public GIO API. For this reason, you have to define the
* C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
* C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including
* `gio/gsettingsbackend.h`.
**/

5
gio/gsettingsbackend.h
View File

@ -53,11 +53,6 @@ G_BEGIN_DECLS
**/
#define G_SETTINGS_BACKEND_EXTENSION_POINT_NAME "gsettings-backend"
/**
* GSettingsBackend:
*
* An implementation of a settings storage repository.
**/
typedef struct _GSettingsBackendPrivate GSettingsBackendPrivate;
typedef struct _GSettingsBackendClass GSettingsBackendClass;

42
gio/gsettingsschema.c
View File

@ -38,12 +38,9 @@
#endif
/**
* SECTION:gsettingsschema
* @short_description: Introspecting and controlling the loading
* of GSettings schemas
* @include: gio/gio.h
* GSettingsSchema:
*
* The #GSettingsSchemaSource and #GSettingsSchema APIs provide a
* The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a
* mechanism for advanced control over the loading of schemas and a
* mechanism for introspecting their content.
*
@ -53,20 +50,20 @@
* the schema along with itself and it won't be installed into the
* standard system directories for schemas.
*
* #GSettingsSchemaSource provides a mechanism for dealing with this by
* allowing the creation of a new 'schema source' from which schemas can
* [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this
* by allowing the creation of a new ‘schema source’ from which schemas can
* be acquired. This schema source can then become part of the metadata
* associated with the plugin and queried whenever the plugin requires
* access to some settings.
*
* Consider the following example:
*
* |[<!-- language="C" -->
* ```c
* typedef struct
* {
* ...
* …
* GSettingsSchemaSource *schema_source;
* ...
* …
* } Plugin;
*
* Plugin *
@ -74,18 +71,18 @@
* {
* Plugin *plugin;
*
* ...
* …
*
* plugin->schema_source =
* g_settings_schema_source_new_from_directory (dir,
* g_settings_schema_source_get_default (), FALSE, NULL);
*
* ...
* …
*
* return plugin;
* }
*
* ...
* …
*
* GSettings *
* plugin_get_settings (Plugin *plugin,
@ -101,12 +98,12 @@
*
* if (schema == NULL)
* {
* ... disable the plugin or abort, etc ...
* … disable the plugin or abort, etc …
* }
*
* return g_settings_new_full (schema, NULL, NULL);
* }
* ]|
* ```
*
* The code above shows how hooks should be added to the code that
* initialises (or enables) the plugin to create the schema source and
@ -118,19 +115,19 @@
* ships a gschemas.compiled file as part of itself, and then simply do
* the following:
*
* |[<!-- language="C" -->
* ```c
* {
* GSettings *settings;
* gint some_value;
*
* settings = plugin_get_settings (self, NULL);
* some_value = g_settings_get_int (settings, "some-value");
* ...
* …
* }
* ]|
* ```
*
* It's also possible that the plugin system expects the schema source
* files (ie: .gschema.xml files) instead of a gschemas.compiled file.
* files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file.
* In that case, the plugin loading system must compile the schemas for
* itself before attempting to create the settings source.
*
@ -144,13 +141,6 @@
* using the following functions.
**/
/**
* GSettingsSchema:
*
* This is an opaque structure type. You may not access it directly.
*
* Since: 2.32
**/
struct _GSettingsSchema
{
GSettingsSchemaSource *source;

11
gio/gsimpleproxyresolver.c
View File

@ -33,19 +33,16 @@
#include "glibintl.h"
/**
* SECTION:gsimpleproxyresolver
* @short_description: Simple proxy resolver implementation
* @include: gio/gio.h
* @see_also: g_socket_client_set_proxy_resolver()
* GSimpleProxyResolver:
*
* #GSimpleProxyResolver is a simple #GProxyResolver implementation
* `GSimpleProxyResolver` is a simple [iface@Gio.ProxyResolver] implementation
* that handles a single default proxy, multiple URI-scheme-specific
* proxies, and a list of hosts that proxies should not be used for.
*
* #GSimpleProxyResolver is never the default proxy resolver, but it
* `GSimpleProxyResolver` is never the default proxy resolver, but it
* can be used as the base class for another proxy resolver
* implementation, or it can be created and used manually, such as
* with g_socket_client_set_proxy_resolver().
* with [method@Gio.SocketClient.set_proxy_resolver].
*
* Since: 2.36
*/

5
gio/gsimpleproxyresolver.h
View File

@ -36,11 +36,6 @@ G_BEGIN_DECLS
#define G_IS_SIMPLE_PROXY_RESOLVER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SIMPLE_PROXY_RESOLVER))
#define G_SIMPLE_PROXY_RESOLVER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SIMPLE_PROXY_RESOLVER, GSimpleProxyResolverClass))
/**
* GSimpleProxyResolver:
*
* A #GProxyResolver implementation for using a fixed set of proxies.
**/
typedef struct _GSimpleProxyResolver GSimpleProxyResolver;
typedef struct _GSimpleProxyResolverPrivate GSimpleProxyResolverPrivate;
typedef struct _GSimpleProxyResolverClass GSimpleProxyResolverClass;

25
gio/gsocketaddressenumerator.c
View File

@ -25,23 +25,22 @@
#include "gtask.h"
/**
* SECTION:gsocketaddressenumerator
* @short_description: Enumerator for socket addresses
* @include: gio/gio.h
* GSocketAddressEnumerator:
*
* #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
* instances. It is returned by enumeration functions such as
* g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
* to list each #GSocketAddress which could be used to connect to that
* #GSocketConnectable.
* `GSocketAddressEnumerator` is an enumerator type for
* [class@Gio.SocketAddress] instances. It is returned by enumeration functions
* such as [method@Gio.SocketConnectable.enumerate], which returns a
* `GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could
* be used to connect to that [iface@Gio.SocketConnectable].
*
* Enumeration is typically a blocking operation, so the asynchronous methods
* g_socket_address_enumerator_next_async() and
* g_socket_address_enumerator_next_finish() should be used where possible.
* [method@Gio.SocketAddressEnumerator.next_async] and
* [method@Gio.SocketAddressEnumerator.next_finish] should be used where
* possible.
*
* Each #GSocketAddressEnumerator can only be enumerated once. Once
* g_socket_address_enumerator_next() has returned %NULL, further
* enumeration with that #GSocketAddressEnumerator is not possible, and it can
* Each `GSocketAddressEnumerator` can only be enumerated once. Once
* [method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further
* enumeration with that `GSocketAddressEnumerator` is not possible, and it can
* be unreffed.
*/

6
gio/gsocketaddressenumerator.h
View File

@ -36,12 +36,6 @@ G_BEGIN_DECLS
#define G_IS_SOCKET_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_ADDRESS_ENUMERATOR))
#define G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_ADDRESS_ENUMERATOR, GSocketAddressEnumeratorClass))
/**
* GSocketAddressEnumerator:
*
* Enumerator type for objects that contain or generate
* #GSocketAddress instances.
*/
typedef struct _GSocketAddressEnumeratorClass GSocketAddressEnumeratorClass;
struct _GSocketAddressEnumerator

25
gio/gsocketlistener.c
View File

@ -42,26 +42,23 @@
/**
* SECTION:gsocketlistener
* @title: GSocketListener
* @short_description: Helper for accepting network client connections
* @include: gio/gio.h
* @see_also: #GThreadedSocketService, #GSocketService.
* GSocketListener:
*
* A #GSocketListener is an object that keeps track of a set
* A `GSocketListener` is an object that keeps track of a set
* of server sockets and helps you accept sockets from any of the
* socket, either sync or async.
*
* Add addresses and ports to listen on using g_socket_listener_add_address()
* and g_socket_listener_add_inet_port(). These will be listened on until
* g_socket_listener_close() is called. Dropping your final reference to the
* #GSocketListener will not cause g_socket_listener_close() to be called
* implicitly, as some references to the #GSocketListener may be held
* Add addresses and ports to listen on using
* [method@Gio.SocketListener.add_address] and
* [method@Gio.SocketListener.add_inet_port]. These will be listened on until
* [method@Gio.SocketListener.close] is called. Dropping your final reference to
* the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be
* called implicitly, as some references to the `GSocketListener` may be held
* internally.
*
* If you want to implement a network server, also look at #GSocketService
* and #GThreadedSocketService which are subclasses of #GSocketListener
* that make this even easier.
* If you want to implement a network server, also look at
* [class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are
* subclasses of `GSocketListener` that make this even easier.
*
* Since: 2.22
*/

32
gio/gsocketservice.c
View File

@ -23,37 +23,33 @@
*/
/**
* SECTION:gsocketservice
* @title: GSocketService
* @short_description: Make it easy to implement a network service
* @include: gio/gio.h
* @see_also: #GThreadedSocketService, #GSocketListener.
* GSocketService:
*
* A #GSocketService is an object that represents a service that
* A `GSocketService` is an object that represents a service that
* is provided to the network or over local sockets. When a new
* connection is made to the service the #GSocketService::incoming
* connection is made to the service the [signal@Gio.SocketService::incoming]
* signal is emitted.
*
* A #GSocketService is a subclass of #GSocketListener and you need
* A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need
* to add the addresses you want to accept connections on with the
* #GSocketListener APIs.
* [class@Gio.SocketListener] APIs.
*
* There are two options for implementing a network service based on
* #GSocketService. The first is to create the service using
* g_socket_service_new() and to connect to the #GSocketService::incoming
* signal. The second is to subclass #GSocketService and override the
* default signal handler implementation.
* `GSocketService`. The first is to create the service using
* [ctor@Gio.SocketService.new] and to connect to the
* [signal@Gio.SocketService::incoming] signal. The second is to subclass
* `GSocketService` and override the default signal handler implementation.
*
* In either case, the handler must immediately return, or else it
* will block additional incoming connections from being serviced.
* If you are interested in writing connection handlers that contain
* blocking code then see #GThreadedSocketService.
* blocking code then see [class@Gio.ThreadedSocketService].
*
* The socket service runs on the main loop of the
* [thread-default context][g-main-context-push-thread-default-context]
* of the thread it is created in, and is not
* threadsafe in general. However, the calls to start and stop the
* service are thread-safe so these can be used from threads that
* thread-default context (see
* [method@GLib.MainContext.push_thread_default_context]) of the thread it is
* created in, and is not threadsafe in general. However, the calls to start and
* stop the service are thread-safe so these can be used from threads that
* handle incoming clients.
*
* Since: 2.22

47
gio/gtlsbackend.c
View File

@ -28,53 +28,6 @@
#include "gioenumtypes.h"
#include "giomodule-priv.h"
/**
* SECTION:gtls
* @title: TLS Overview
* @short_description: TLS (aka SSL) support for GSocketConnection
* @include: gio/gio.h
*
* #GTlsConnection and related classes provide TLS (Transport Layer
* Security, previously known as SSL, Secure Sockets Layer) support for
* gio-based network streams.
*
* #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for
* GIO-based network sockets, using the #GDatagramBased interface. The TLS and
* DTLS APIs are almost identical, except TLS is stream-based and DTLS is
* datagram-based. They share certificate and backend infrastructure.
*
* In the simplest case, for a client TLS connection, you can just set the
* #GSocketClient:tls flag on a #GSocketClient, and then any
* connections created by that client will have TLS negotiated
* automatically, using appropriate default settings, and rejecting
* any invalid or self-signed certificates (unless you change that
* default by setting the #GSocketClient:tls-validation-flags
* property). The returned object will be a #GTcpWrapperConnection,
* which wraps the underlying #GTlsClientConnection.
*
* For greater control, you can create your own #GTlsClientConnection,
* wrapping a #GSocketConnection (or an arbitrary #GIOStream with
* pollable input and output streams) and then connect to its signals,
* such as #GTlsConnection::accept-certificate, before starting the
* handshake.
*
* Server-side TLS is similar, using #GTlsServerConnection. At the
* moment, there is no support for automatically wrapping server-side
* connections in the way #GSocketClient does for client-side
* connections.
*/
/**
* SECTION:gtlsbackend
* @title: GTlsBackend
* @short_description: TLS backend implementation
* @include: gio/gio.h
*
* TLS (Transport Layer Security, aka SSL) and DTLS backend.
*
* Since: 2.28
*/
/**
* GTlsBackend:
*

16
gio/gtlscertificate.c
View File

@ -29,25 +29,13 @@
#include "glibintl.h"
/**
* SECTION:gtlscertificate
* @title: GTlsCertificate
* @short_description: TLS certificate
* @include: gio/gio.h
* @see_also: #GTlsConnection
* GTlsCertificate:
*
* A certificate used for TLS authentication and encryption.
* This can represent either a certificate only (eg, the certificate
* received by a client from a server), or the combination of
* a certificate and a private key (which is needed when acting as a
* #GTlsServerConnection).
*
* Since: 2.28
*/
/**
* GTlsCertificate:
*
* Abstract base class for TLS certificate types.
* [iface@Gio.TlsServerConnection]).
*
* Since: 2.28
*/

13
gio/gtlsclientconnection.c
View File

@ -30,20 +30,11 @@
#include "gtlscertificate.h"
#include "glibintl.h"
/**
* SECTION:gtlsclientconnection
* @short_description: TLS client-side connection
* @include: gio/gio.h
*
* #GTlsClientConnection is the client-side subclass of
* #GTlsConnection, representing a client-side TLS connection.
*/
/**
* GTlsClientConnection:
*
* Abstract base class for the backend-specific client connection
* type.
* `GTlsClientConnection` is the client-side subclass of
* [class@Gio.TlsConnection], representing a client-side TLS connection.
*
* Since: 2.28
*/

18
gio/gtlsdatabase.c
View File

@ -33,27 +33,17 @@
#include "gtlsinteraction.h"
/**
* SECTION:gtlsdatabase
* @short_description: TLS database type
* @include: gio/gio.h
* GTlsDatabase:
*
* #GTlsDatabase is used to look up certificates and other information
* `GTlsDatabase` is used to look up certificates and other information
* from a certificate or key store. It is an abstract base class which
* TLS library specific subtypes override.
*
* A #GTlsDatabase may be accessed from multiple threads by the TLS backend.
* A `GTlsDatabase` may be accessed from multiple threads by the TLS backend.
* All implementations are required to be fully thread-safe.
*
* Most common client applications will not directly interact with
* #GTlsDatabase. It is used internally by #GTlsConnection.
*
* Since: 2.30
*/
/**
* GTlsDatabase:
*
* Abstract base class for the backend-specific database types.
* `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection].
*
* Since: 2.30
*/

8
gio/gtlsserverconnection.c
View File

@ -30,12 +30,10 @@
#include "glibintl.h"
/**
* SECTION:gtlsserverconnection
* @short_description: TLS server-side connection
* @include: gio/gio.h
* GTlsServerConnection:
*
* #GTlsServerConnection is the server-side subclass of #GTlsConnection,
* representing a server-side TLS connection.
* `GTlsServerConnection` is the server-side subclass of
* [class@Gio.TlsConnection], representing a server-side TLS connection.
*
* Since: 2.28
*/

8
gio/gtlsserverconnection.h
View File

@ -34,14 +34,6 @@ G_BEGIN_DECLS
#define G_IS_TLS_SERVER_CONNECTION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_TLS_SERVER_CONNECTION))
#define G_TLS_SERVER_CONNECTION_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), G_TYPE_TLS_SERVER_CONNECTION, GTlsServerConnectionInterface))
/**
* GTlsServerConnection:
*
* TLS server-side connection. This is the server-side implementation
* of a #GTlsConnection.
*
* Since: 2.28
*/
typedef struct _GTlsServerConnectionInterface GTlsServerConnectionInterface;
/**

17
gio/gunixconnection.c
View File

@ -31,19 +31,15 @@
#endif
/**
* SECTION:gunixconnection
* @title: GUnixConnection
* @short_description: A UNIX domain GSocketConnection
* @include: gio/gunixconnection.h
* @see_also: #GSocketConnection.
* GUnixConnection:
*
* This is the subclass of #GSocketConnection that is created
* This is the subclass of [class@Gio.SocketConnection] that is created
* for UNIX domain sockets.
*
* It contains functions to do some of the UNIX socket specific
* functionality like passing file descriptors.
*
* Since GLib 2.72, #GUnixConnection is available on all platforms. It requires
* Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires
* underlying system support (such as Windows 10 with `AF_UNIX`) at run time.
*
* Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO
@ -53,13 +49,6 @@
* Since: 2.22
*/
/**
* GUnixConnection:
*
* #GUnixConnection is an opaque data structure and can only be accessed
* using the following functions.
**/
G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection,
G_TYPE_SOCKET_CONNECTION,
g_socket_connection_factory_register_type (g_define_type_id,

24
gio/gunixcredentialsmessage.c
View File

@ -16,31 +16,29 @@
*/
/**
* SECTION:gunixcredentialsmessage
* @title: GUnixCredentialsMessage
* @short_description: A GSocketControlMessage containing credentials
* @include: gio/gunixcredentialsmessage.h
* @see_also: #GUnixConnection, #GSocketControlMessage
* GUnixCredentialsMessage:
*
* This #GSocketControlMessage contains a #GCredentials instance. It
* may be sent using g_socket_send_message() and received using
* g_socket_receive_message() over UNIX sockets (ie: sockets in the
* %G_SOCKET_FAMILY_UNIX family).
* This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials]
* instance. It may be sent using [method@Gio.Socket.send_message] and received
* using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in
* the `G_SOCKET_FAMILY_UNIX` family).
*
* For an easier way to send and receive credentials over
* stream-oriented UNIX sockets, see
* g_unix_connection_send_credentials() and
* g_unix_connection_receive_credentials(). To receive credentials of
* [method@Gio.UnixConnection.send_credentials] and
* [method@Gio.UnixConnection.receive_credentials]. To receive credentials of
* a foreign process connected to a socket, use
* g_socket_get_credentials().
* [method@Gio.Socket.get_credentials].
*
* Since GLib 2.72, #GUnixCredentialMessage is available on all platforms. It
* Since GLib 2.72, `GUnixCredentialMessage` is available on all platforms. It
* requires underlying system support (such as Windows 10 with `AF_UNIX`) at run
* time.
*
* Before GLib 2.72, `<gio/gunixcredentialsmessage.h>` belonged to the UNIX-specific
* GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file
* when using it. This is no longer necessary since GLib 2.72.
*
* Since: 2.26
*/
#include "config.h"

8
gio/gunixcredentialsmessage.h
View File

@ -58,14 +58,6 @@ struct _GUnixCredentialsMessageClass
void (*_g_reserved2) (void);
};
/**
* GUnixCredentialsMessage:
*
* The #GUnixCredentialsMessage structure contains only private data
* and should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GUnixCredentialsMessage
{
GSocketControlMessage parent_instance;

9
gio/gunixinputstream.c
View File

@ -39,14 +39,11 @@
/**
* SECTION:gunixinputstream
* @short_description: Streaming input operations for UNIX file descriptors
* @include: gio/gunixinputstream.h
* @see_also: #GInputStream
* GUnixInputStream:
*
* #GUnixInputStream implements #GInputStream for reading from a UNIX
* `GUnixInputStream` implements [class@Gio.InputStream] for reading from a UNIX
* file descriptor, including asynchronous operations. (If the file
* descriptor refers to a socket or pipe, this will use poll() to do
* descriptor refers to a socket or pipe, this will use `poll()` to do
* asynchronous I/O. If it refers to a regular file, it will fall back
* to doing asynchronous I/O in another thread.)
*

5
gio/gunixinputstream.h
View File

@ -34,11 +34,6 @@ G_BEGIN_DECLS
#define G_IS_UNIX_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_UNIX_INPUT_STREAM))
#define G_UNIX_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_UNIX_INPUT_STREAM, GUnixInputStreamClass))
/**
* GUnixInputStream:
*
* Implements #GInputStream for reading from selectable unix file descriptors
**/
typedef struct _GUnixInputStream GUnixInputStream;
typedef struct _GUnixInputStreamClass GUnixInputStreamClass;
typedef struct _GUnixInputStreamPrivate GUnixInputStreamPrivate;

9
gio/gunixoutputstream.c
View File

@ -41,14 +41,11 @@
/**
* SECTION:gunixoutputstream
* @short_description: Streaming output operations for UNIX file descriptors
* @include: gio/gunixoutputstream.h
* @see_also: #GOutputStream
* GUnixOutputStream:
*
* #GUnixOutputStream implements #GOutputStream for writing to a UNIX
* `GUnixOutputStream` implements [class@Gio.OutputStream] for writing to a UNIX
* file descriptor, including asynchronous operations. (If the file
* descriptor refers to a socket or pipe, this will use poll() to do
* descriptor refers to a socket or pipe, this will use `poll()` to do
* asynchronous I/O. If it refers to a regular file, it will fall back
* to doing asynchronous I/O in another thread.)
*

5
gio/gunixoutputstream.h
View File

@ -34,11 +34,6 @@ G_BEGIN_DECLS
#define G_IS_UNIX_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_UNIX_OUTPUT_STREAM))
#define G_UNIX_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_UNIX_OUTPUT_STREAM, GUnixOutputStreamClass))
/**
* GUnixOutputStream:
*
* Implements #GOutputStream for outputting to selectable unix file descriptors
**/
typedef struct _GUnixOutputStream GUnixOutputStream;
typedef struct _GUnixOutputStreamClass GUnixOutputStreamClass;
typedef struct _GUnixOutputStreamPrivate GUnixOutputStreamPrivate;

20
gio/gunixsocketaddress.c
View File

@ -35,22 +35,21 @@
#endif
/**
* SECTION:gunixsocketaddress
* @short_description: UNIX GSocketAddress
* @include: gio/gunixsocketaddress.h
* GUnixSocketAddress:
*
* Support for UNIX-domain (also known as local) sockets.
* Support for UNIX-domain (also known as local) sockets, corresponding to
* `struct sockaddr_un`.
*
* UNIX domain sockets are generally visible in the filesystem.
* However, some systems support abstract socket names which are not
* visible in the filesystem and not affected by the filesystem
* permissions, visibility, etc. Currently this is only supported
* under Linux. If you attempt to use abstract sockets on other
* systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED
* errors. You can use g_unix_socket_address_abstract_names_supported()
* systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED`
* errors. You can use [func@Gio.UnixSocketAddress.abstract_names_supported]
* to see if abstract names are supported.
*
* Since GLib 2.72, #GUnixSocketAddress is available on all platforms. It
* Since GLib 2.72, `GUnixSocketAddress` is available on all platforms. It
* requires underlying system support (such as Windows 10 with `AF_UNIX`) at
* run time.
*
@ -59,13 +58,6 @@
* when using it. This is no longer necessary since GLib 2.72.
*/
/**
* GUnixSocketAddress:
*
* A UNIX-domain (local) socket address, corresponding to a
* struct sockaddr_un.
*/
enum
{
PROP_0,

60
gio/gvolume.c
View File

@ -32,51 +32,49 @@
/**
* SECTION:gvolume
* @short_description: Volume management
* @include: gio/gio.h
* GVolume:
*
* The #GVolume interface represents user-visible objects that can be
* mounted. Note, when porting from GnomeVFS, #GVolume is the moral
* equivalent of #GnomeVFSDrive.
* The `GVolume` interface represents user-visible objects that can be
* mounted. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html),
* `GVolume` is the moral equivalent of `GnomeVFSDrive`.
*
* Mounting a #GVolume instance is an asynchronous operation. For more
* information about asynchronous operations, see #GAsyncResult and
* #GTask. To mount a #GVolume, first call g_volume_mount() with (at
* least) the #GVolume instance, optionally a #GMountOperation object
* and a #GAsyncReadyCallback.
* Mounting a `GVolume` instance is an asynchronous operation. For more
* information about asynchronous operations, see [class@Gio.AsyncResult] and
* [class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount]
* with (at least) the `GVolume` instance, optionally a
* [class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback].
*
* Typically, one will only want to pass %NULL for the
* #GMountOperation if automounting all volumes when a desktop session
* starts since it's not desirable to put up a lot of dialogs asking
* Typically, one will only want to pass `NULL` for the
* [class@Gio.MountOperation] if automounting all volumes when a desktop session
* starts since it’s not desirable to put up a lot of dialogs asking
* for credentials.
*
* The callback will be fired when the operation has resolved (either
* with success or failure), and a #GAsyncResult instance will be
* with success or failure), and a [class@Gio.AsyncResult] instance will be
* passed to the callback. That callback should then call
* g_volume_mount_finish() with the #GVolume instance and the
* #GAsyncResult data to see if the operation was completed
* successfully. If an @error is present when g_volume_mount_finish()
* is called, then it will be filled with any error information.
* [method@Gio.Volume.mount_finish] with the `GVolume` instance and the
* [class@Gio.AsyncResult] data to see if the operation was completed
* successfully. If a [type@GLib.Error] is present when
* [method@Gio.Volume.mount_finish] is called, then it will be filled with any
* error information.
*
* ## Volume Identifiers # {#volume-identifier}
* ## Volume Identifiers
*
* It is sometimes necessary to directly access the underlying
* operating system object behind a volume (e.g. for passing a volume
* to an application via the commandline). For this purpose, GIO
* allows to obtain an 'identifier' for the volume. There can be
* to an application via the command line). For this purpose, GIO
* allows to obtain an ‘identifier’ for the volume. There can be
* different kinds of identifiers, such as Hal UDIs, filesystem labels,
* traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
* strings as names for the different kinds of identifiers:
* %G_VOLUME_IDENTIFIER_KIND_UUID, %G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
* Use g_volume_get_identifier() to obtain an identifier for a volume.
* `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc.
* Use [method@Gio.Volume.get_identifier] to obtain an identifier for a volume.
*
*
* Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
* when the gvfs hal volume monitor is in use. Other volume monitors
* will generally be able to provide the %G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
* Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available
* when the GVFS hal volume monitor is in use. Other volume monitors
* will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE`
* identifier, which can be used to obtain a hal device by means of
* libhal_manager_find_device_string_match().
* `libhal_manager_find_device_string_match()`.
*/
typedef GVolumeIface GVolumeInterface;
@ -563,7 +561,7 @@ g_volume_eject_with_operation_finish (GVolume *volume,
* @kind: the kind of identifier to return
*
* Gets the identifier of the given kind for @volume.
* See the [introduction][volume-identifier] for more
* See the [introduction](#volume-identifiers) for more
* information about volume identifiers.
*
* Returns: (nullable) (transfer full): a newly allocated string containing the
@ -591,7 +589,7 @@ g_volume_get_identifier (GVolume *volume,
* g_volume_enumerate_identifiers:
* @volume: a #GVolume
*
* Gets the kinds of [identifiers][volume-identifier] that @volume has.
* Gets the kinds of [identifiers](#volume-identifiers) that @volume has.
* Use g_volume_get_identifier() to obtain the identifiers themselves.
*
* Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array

4
gio/gvolume.h
View File

@ -109,10 +109,10 @@ G_BEGIN_DECLS
* @mount_finish: Finishes a mount operation.
* @eject: Ejects a given #GVolume.
* @eject_finish: Finishes an eject operation.
* @get_identifier: Returns the [identifier][volume-identifier] of the given kind, or %NULL if
* @get_identifier: Returns the [identifier](#volume-identifiers) of the given kind, or %NULL if
* the #GVolume doesn't have one.
* @enumerate_identifiers: Returns an array strings listing the kinds
* of [identifiers][volume-identifier] which the #GVolume has.
* of [identifiers](#volume-identifiers) which the #GVolume has.
* @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
* @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if
* it is not known.

17
gio/gvolumemonitor.c
View File

@ -32,19 +32,16 @@
/**
* SECTION:gvolumemonitor
* @short_description: Volume Monitor
* @include: gio/gio.h
* @see_also: #GFileMonitor
* GVolumeMonitor:
*
* #GVolumeMonitor is for listing the user interesting devices and volumes
* `GVolumeMonitor` is for listing the user interesting devices and volumes
* on the computer. In other words, what a file selector or file manager
* would show in a sidebar.
* would show in a sidebar.
*
* #GVolumeMonitor is not
* [thread-default-context aware][g-main-context-push-thread-default],
* and so should not be used other than from the main thread, with no
* thread-default-context active.
* `GVolumeMonitor` is not
* thread-default-context aware (see
* [method@GLib.MainContext.push_thread_default]), and so should not be used
* other than from the main thread, with no thread-default-context active.
*
* In order to receive updates about volumes and mounts monitored through GVFS,
* a main loop must be running.

5
gio/gvolumemonitor.h
View File

@ -49,11 +49,6 @@ G_BEGIN_DECLS
*/
#define G_VOLUME_MONITOR_EXTENSION_POINT_NAME "gio-volume-monitor"
/**
* GVolumeMonitor:
*
* A Volume Monitor that watches for volume events.
**/
typedef struct _GVolumeMonitorClass GVolumeMonitorClass;
struct _GVolumeMonitor

7
gio/gwin32inputstream.c
View File

@ -36,12 +36,9 @@
#include "glibintl.h"
/**
* SECTION:gwin32inputstream
* @short_description: Streaming input operations for Windows file handles
* @include: gio/gwin32inputstream.h
* @see_also: #GInputStream
* GWin32InputStream:
*
* #GWin32InputStream implements #GInputStream for reading from a
* `GWin32InputStream` implements [class@Gio.InputStream] for reading from a
* Windows file handle.
*
* Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO

5
gio/gwin32inputstream.h
View File

@ -35,11 +35,6 @@ G_BEGIN_DECLS
#define G_IS_WIN32_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_WIN32_INPUT_STREAM))
#define G_WIN32_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_WIN32_INPUT_STREAM, GWin32InputStreamClass))
/**
* GWin32InputStream:
*
* Implements #GInputStream for reading from selectable Windows file handles
**/
typedef struct _GWin32InputStream GWin32InputStream;
typedef struct _GWin32InputStreamClass GWin32InputStreamClass;
typedef struct _GWin32InputStreamPrivate GWin32InputStreamPrivate;

7
gio/gwin32outputstream.c
View File

@ -37,12 +37,9 @@
#include "glibintl.h"
/**
* SECTION:gwin32outputstream
* @short_description: Streaming output operations for Windows file handles
* @include: gio/gwin32outputstream.h
* @see_also: #GOutputStream
* GWin32OutputStream:
*
* #GWin32OutputStream implements #GOutputStream for writing to a
* `GWin32OutputStream` implements [class@Gio.OutputStream] for writing to a
* Windows file handle.
*
* Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO

5
gio/gwin32outputstream.h
View File

@ -35,11 +35,6 @@ G_BEGIN_DECLS
#define G_IS_WIN32_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_WIN32_OUTPUT_STREAM))
#define G_WIN32_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_WIN32_OUTPUT_STREAM, GWin32OutputStreamClass))
/**
* GWin32OutputStream:
*
* Implements #GOutputStream for outputting to Windows file handles
**/
typedef struct _GWin32OutputStream GWin32OutputStream;
typedef struct _GWin32OutputStreamClass GWin32OutputStreamClass;
typedef struct _GWin32OutputStreamPrivate GWin32OutputStreamPrivate;

34
gio/gwin32registrykey.c
View File

@ -347,23 +347,21 @@ G_DEFINE_BOXED_TYPE (GWin32RegistryValueIter, g_win32_registry_value_iter,
g_win32_registry_value_iter_free)
/**
* SECTION:gwin32registrykey
* @title: GWin32RegistryKey
* @short_description: W32 registry access helper
* @include: gio/win32/gwin32registrykey.h
* GWin32RegistryKey:
*
* #GWin32RegistryKey represents a single Windows Registry key.
* `GWin32RegistryKey` represents a single Windows Registry key.
*
* #GWin32RegistryKey is used by a number of helper functions that read
* `GWin32RegistryKey` is used by a number of helper functions that read
* Windows Registry. All keys are opened with read-only access, and at
* the moment there is no API for writing into registry keys or creating
* new ones.
*
* #GWin32RegistryKey implements the #GInitable interface, so if it is manually
* constructed by e.g. g_object_new() you must call g_initable_init() and check
* the results before using the object. This is done automatically
* in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these
* functions can return %NULL.
* `GWin32RegistryKey` implements the [iface@Gio.Initable] interface, so if it
* is manually constructed by e.g. [ctor@GObject.Object.new] you must call
* [method@Gio.Initable.init] and check the results before using the object.
* This is done automatically in [ctor@Gio.Win32RegistryKey.new] and
* [method@Gio.Win32RegistryKey.get_child], so these functions can return
* `NULL`.
*
* To increase efficiency, a UTF-16 variant is available for all functions
* that deal with key or value names in the registry. Use these to perform
@ -372,17 +370,17 @@ G_DEFINE_BOXED_TYPE (GWin32RegistryValueIter, g_win32_registry_value_iter,
* of UTF-16 functions avoids the overhead of converting names to UTF-8 and
* back.
*
* All functions operate in current user's context (it is not possible to
* access registry tree of a different user).
* All functions operate in the current user’s context (it is not possible to
* access the registry tree of a different user).
*
* Key paths must use '\\' as a separator, '/' is not supported. Key names
* must not include '\\', because it's used as a separator. Value names
* can include '\\'.
* Key paths must use `\\` as a separator, `/` is not supported. Key names
* must not include `\\`, because it’s used as a separator. Value names
* can include `\\`.
*
* Key and value names are not case sensitive.
*
* Full key name (excluding the pre-defined ancestor's name) can't exceed
* 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16
* A full key name (excluding the pre-defined ancestor’s name) can’t exceed
* 255 UTF-16 characters, give or take. A value name can’t exceed 16383 UTF-16
* characters. Tree depth is limited to 512 levels.
**/

11
gio/gzlibcompressor.c
View File

@ -43,21 +43,14 @@ enum {
};
/**
* SECTION:gzlibcompressor
* @short_description: Zlib compressor
* @include: gio/gio.h
* GZlibCompressor:
*
* #GZlibCompressor is an implementation of #GConverter that
* `GZlibCompressor` is an implementation of [iface@Gio.Converter] that
* compresses data using zlib.
*/
static void g_zlib_compressor_iface_init (GConverterIface *iface);
/**
* GZlibCompressor:
*
* Zlib decompression
*/
struct _GZlibCompressor
{
GObject parent_instance;

11
gio/gzlibdecompressor.c
View File

@ -42,11 +42,9 @@ enum {
};
/**
* SECTION:gzlibdecompressor
* @short_description: Zlib decompressor
* @include: gio/gio.h
* GZlibDecompressor:
*
* #GZlibDecompressor is an implementation of #GConverter that
* `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that
* decompresses data compressed with zlib.
*/
@ -58,11 +56,6 @@ typedef struct {
GFileInfo *file_info;
} HeaderData;
/**
* GZlibDecompressor:
*
* Zlib decompression
*/
struct _GZlibDecompressor
{
GObject parent_instance;

27
glib/gchecksum.c
View File

@ -33,25 +33,26 @@
/**
* SECTION:checksum
* @title: Data Checksums
* @short_description: computes the checksum for data
* GChecksum:
*
* GLib provides a generic API for computing checksums (or "digests")
* GLib provides a generic API for computing checksums (or ‘digests’)
* for a sequence of arbitrary bytes, using various hashing algorithms
* like MD5, SHA-1 and SHA-256. Checksums are commonly used in various
* environments and specifications.
*
* GLib supports incremental checksums using the GChecksum data
* structure, by calling g_checksum_update() as long as there's data
* available and then using g_checksum_get_string() or
* g_checksum_get_digest() to compute the checksum and return it either
* as a string in hexadecimal form, or as a raw sequence of bytes. To
* compute the checksum for binary blobs and NUL-terminated strings in
* one go, use the convenience functions g_compute_checksum_for_data()
* and g_compute_checksum_for_string(), respectively.
* To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free
* a `GChecksum`, use [method@GLib.Checksum.free].
*
* Support for checksums has been added in GLib 2.16
* GLib supports incremental checksums using the `GChecksum` data
* structure, by calling [method@GLib.Checksum.update] as long as there’s data
* available and then using [method@GLib.Checksum.get_string] or
* [method@GLib.Checksum.get_digest] to compute the checksum and return it
* either as a string in hexadecimal form, or as a raw sequence of bytes. To
* compute the checksum for binary blobs and nul-terminated strings in
* one go, use the convenience functions [func@GLib.compute_checksum_for_data]
* and [func@GLib.compute_checksum_for_string], respectively.
*
* Since: 2.16
**/
#define IS_VALID_TYPE(type) ((type) >= G_CHECKSUM_MD5 && (type) <= G_CHECKSUM_SHA384)

10
glib/gchecksum.h
View File

@ -54,16 +54,6 @@ typedef enum {
G_CHECKSUM_SHA384
} GChecksumType;
/**
* GChecksum:
*
* An opaque structure representing a checksumming operation.
*
* To create a new GChecksum, use g_checksum_new(). To free
* a GChecksum, use g_checksum_free().
*
* Since: 2.16
*/
typedef struct _GChecksum GChecksum;
GLIB_AVAILABLE_IN_ALL