luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-14 19:55:12 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into 'ebassi/girepository'

Browse Source 
This needs to be done as a merge rather than a rebase because !3642 cannot be rebased.

Conflicts:
  meson_options.txt
This commit is contained in:
Philip Withnall 2023-11-08 11:54:28 +00:00
commit 342b654e35
336 changed files with 6713 additions and 258509 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
.gitlab-ci.yml
View File

@ -11,18 +11,18 @@ cache:
- _ccache/
variables:
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v21"
FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/glib/fedora:v22"
COVERITY_IMAGE: "registry.gitlab.gnome.org/gnome/glib/coverity:v7"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v15"
MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v11"
DEBIAN_IMAGE: "registry.gitlab.gnome.org/gnome/glib/debian-stable:v16"
MINGW_IMAGE: "registry.gitlab.gnome.org/gnome/glib/mingw:v12"
MESON_TEST_TIMEOUT_MULTIPLIER: 4
G_MESSAGES_DEBUG: all
MESON_COMMON_OPTIONS: "--buildtype debug --wrap-mode=nodownload --fatal-meson-warnings"
# Default CI job setup; contrast with `.only-origin`.
#
# Don’t execute the pipeline when a merge request is merged into `main`, as it
# will have already been tested
# Don’t execute the pipeline when a merge request is merged into `origin/main`,
# as it will have already been tested
.only-default:
only:
- branches
@ -30,7 +30,7 @@ variables:
refs:
- tags
variables:
- $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
- $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_NAMESPACE == "GNOME"
# Some jobs run on CI runners which don’t have good isolation between CI jobs,
# and don’t have much available resource. Limit those jobs to only ones on the
@ -180,6 +180,36 @@ debian-stable-x86_64:
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
hurd-i386:
extends:
- .only-schedules
stage: build
tags:
- hurd
needs: []
script:
- meson setup ${MESON_COMMON_OPTIONS}
--werror
--default-library=both
--prefix=$HOME/glib-installed
--localstatedir=/var
--libdir=lib
_build
- meson compile -C _build
- .gitlab-ci/run-tests.sh
artifacts:
reports:
junit:
- _build/meson-logs/testlog.junit.xml
- _build/meson-logs/testlog-*.junit.xml
name: "glib-${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
when: always
expire_in: 1 week
paths:
- "_build/config.h"
- "_build/glib/glibconfig.h"
- "_build/meson-logs"
installed-tests:
extends:
- .build-linux
@ -341,10 +371,6 @@ msys2-mingw32:
CHERE_INVOKING: "yes"
CFLAGS: -coverage -ftest-coverage -fprofile-arcs
PYTHONUTF8: "1"
# FIXME: For some reason enabling jit debugging "fixes" random python crashes
# see https://github.com/msys2/MINGW-packages/issues/11864 and
# https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
MSYS: "winjitdebug"
script:
- C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
- C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@ -371,10 +397,6 @@ msys2-clang64:
MSYSTEM: "CLANG64"
CHERE_INVOKING: "yes"
PYTHONUTF8: "1"
# FIXME: For some reason enabling jit debugging "fixes" random python crashes
# see https://github.com/msys2/MINGW-packages/issues/11864 and
# https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3280#note_1678973
MSYS: "winjitdebug"
script:
- C:\msys64\usr\bin\pacman --noconfirm -Syyuu --ask 20
- C:\msys64\usr\bin\bash .gitlab-ci/show-execution-environment.sh
@ -551,7 +573,7 @@ macos-x86_64:
- ln -s /opt/cmake/CMake.app/Contents/bin/cmake .venv/bin
- ln -s /opt/ccache/ccache .venv/bin
- source .venv/bin/activate
- pip3 install meson==1.2.0
- pip3 install meson==1.2.3
- pip3 install ninja==1.11.1
script:
# FIXME: Use --wrap-mode=default so we download dependencies each time,

2
.gitlab-ci/debian-stable.Dockerfile
View File

@ -68,7 +68,7 @@ RUN locale-gen de_DE.UTF-8 \
ENV LANG=C.UTF-8 LANGUAGE=C.UTF-8 LC_ALL=C.UTF-8
RUN pip3 install --break-system-packages meson==0.60.3
RUN pip3 install --break-system-packages meson==1.2.3
ARG HOST_USER_ID=5555
ENV HOST_USER_ID ${HOST_USER_ID}

5
.gitlab-ci/fedora.Dockerfile
View File

@ -22,12 +22,11 @@ RUN dnf -y update \
glibc-headers \
glibc-langpack-de \
glibc-langpack-el \
glibc-langpack-el \
glibc-langpack-en \
glibc-langpack-es \
glibc-langpack-es \
glibc-langpack-fa \
glibc-langpack-fr \
glibc-langpack-gu \
glibc-langpack-hr \
glibc-langpack-ja \
glibc-langpack-lt \
@ -76,7 +75,7 @@ RUN dnf -y update \
make \
&& dnf clean all
RUN pip3 install meson==0.60.3
RUN pip3 install meson==1.2.3
COPY install-gitlab-cobertura-tools.sh .
RUN ./install-gitlab-cobertura-tools.sh

2
.gitlab-ci/mingw.Dockerfile
View File

@ -1,4 +1,4 @@
FROM registry.gitlab.gnome.org/gnome/glib/fedora:v21
FROM registry.gitlab.gnome.org/gnome/glib/fedora:v22
USER root

2
.gitlab-ci/run-style-check-diff.sh
View File

@ -9,7 +9,7 @@ ancestor_horizon=28 # days (4 weeks)
source .gitlab-ci/search-common-ancestor.sh
git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-11" -p1
git diff -U0 --no-color "${newest_common_ancestor_sha}" | .gitlab-ci/clang-format-diff.py -binary "clang-format-14" -p1
)
exit_status=$?

2
.gitlab-ci/test-msvc.bat
View File

@ -12,7 +12,7 @@ for %%x in (%*) do (
set args=%args:~1%
:: FIXME: make warnings fatal
pip3 install --upgrade --user meson==1.0.0 || goto :error
pip3 install --upgrade --user meson==1.2.3 || goto :error
meson setup %args% _build || goto :error
python .gitlab-ci/check-missing-install-tag.py _build || goto :error
meson compile -C _build || goto :error

12
.gitlab-ci/test-msys2.sh
View File

@ -26,20 +26,14 @@ CCACHE_BASEDIR="$(pwd)"
CCACHE_DIR="${CCACHE_BASEDIR}/_ccache"
export CCACHE_BASEDIR CCACHE_DIR
pip3 install --upgrade --user meson==1.0.0
pip3 install --upgrade --user meson==1.2.3
PATH="$(cygpath "$USERPROFILE")/.local/bin:$HOME/.local/bin:$PATH"
DIR="$(pwd)"
export PATH CFLAGS
if [[ "$MSYSTEM" == "CLANG64" ]]; then
# FIXME: fix the clang build warnings
# shellcheck disable=SC2086
meson setup ${MESON_COMMON_OPTIONS} _build
else
# shellcheck disable=SC2086
meson setup ${MESON_COMMON_OPTIONS} --werror _build
fi
# shellcheck disable=SC2086
meson setup ${MESON_COMMON_OPTIONS} --werror _build
meson compile -C _build

136814
docs/reference/gio/Gio-2.0.gir
View File

File diff suppressed because it is too large Load Diff

111
docs/reference/gio/file-attributes.md Normal file
View File

@ -0,0 +1,111 @@
Title: File Attributes
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Andrew Walton
SPDX-FileCopyrightText: 2007 Alexander Larsson
SPDX-FileCopyrightText: 2008, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2011 Murray Cumming
SPDX-FileCopyrightText: 2012 David King
# File Attributes
File attributes in GIO consist of a list of key-value pairs.
Keys are strings that contain a key namespace and a key name, separated
by a colon, e.g. `namespace::keyname`. Namespaces are included to sort
key-value pairs by namespaces for relevance. Keys can be retrieved
using wildcards, e.g. `standard::*` will return all of the keys in the
`standard` namespace.
The list of possible attributes for a filesystem (pointed to by a
[iface@Gio.File]) is available as a [struct@Gio.FileAttributeInfoList]. This
list is queryable by key names as indicated earlier.
Information is stored within the list in [struct@Gio.FileAttributeInfo]
structures. The info structure can store different types, listed in the enum
[type@Gio.FileAttributeType]. Upon creation of a [struct@Gio.FileAttributeInfo],
the type will be set to `G_FILE_ATTRIBUTE_TYPE_INVALID`.
Classes that implement [iface@Gio.File] will create a
[struct@Gio.FileAttributeInfoList] and install default keys and values for their
given file system, architecture, and other possible implementation details
(e.g., on a UNIX system, a file attribute key will be registered for the user ID
for a given file).
## Default Namespaces
- `"standard"`: The ‘Standard’ namespace. General file information that
any application may need should be put in this namespace. Examples
include the file’s name, type, and size.
- `"etag`: The [Entity Tag](gfile.html#entity-tags) namespace. Currently, the
only key in this namespace is `value`, which contains the value of the current
entity tag.
- `"id"`: The ‘Identification’ namespace. This namespace is used by file
managers and applications that list directories to check for loops and
to uniquely identify files.
- `"access"`: The ‘Access’ namespace. Used to check if a user has the
proper privileges to access files and perform file operations. Keys in
this namespace are made to be generic and easily understood, e.g. the
`can_read` key is true if the current user has permission to read the
file. UNIX permissions and NTFS ACLs in Windows should be mapped to
these values.
- `"mountable"`: The ‘Mountable’ namespace. Includes simple boolean keys
for checking if a file or path supports mount operations, e.g. mount,
unmount, eject. These are used for files of type `G_FILE_TYPE_MOUNTABLE`.
- `"time"`: The ‘Time’ namespace. Includes file access, changed, created
times.
- `"unix"`: The ‘Unix’ namespace. Includes UNIX-specific information and
may not be available for all files. Examples include the UNIX UID,
GID, etc.
- `"dos"`: The ‘DOS’ namespace. Includes DOS-specific information and may
not be available for all files. Examples include `is_system` for checking
if a file is marked as a system file, and `is_archive` for checking if a
file is marked as an archive file.
- `"owner"`: The ‘Owner’ namespace. Includes information about who owns a
file. May not be available for all file systems. Examples include `user`
for getting the user name of the file owner. This information is often
mapped from some backend specific data such as a UNIX UID.
- `"thumbnail"`: The ‘Thumbnail’ namespace. Includes information about file
thumbnails and their location within the file system. Examples of keys in
this namespace include `path` to get the location of a thumbnail, `failed`
to check if thumbnailing of the file failed, and `is-valid` to check if
the thumbnail is outdated.
- `"filesystem"`: The ‘Filesystem’ namespace. Gets information about the
file system where a file is located, such as its type, how much space is
left available, and the overall size of the file system.
- `"gvfs"`: The ‘GVFS’ namespace. Keys in this namespace contain information
about the current GVFS backend in use.
- `"xattr"`: The ‘xattr’ namespace. Gets information about extended user
attributes. See [`attr(5)`](man:attr(5)). The `user.` prefix of the extended
user attribute name is stripped away when constructing keys in this namespace,
e.g. `xattr::mime_type` for the extended attribute with the name
`user.mime_type`. Note that this information is only available if
GLib has been built with extended attribute support.
- `"xattr-sys"`: The ‘xattr-sys’ namespace. Gets information about
extended attributes which are not user-specific. See [`attr(5)`](man:attr(5)).
Note that this information is only available if GLib has been built with
extended attribute support.
- `"selinux"`: The ‘SELinux’ namespace. Includes information about the
SELinux context of files. Note that this information is only available
if GLib has been built with SELinux support.
Please note that these are not all of the possible namespaces.
More namespaces can be added from GIO modules or by individual applications.
For more information about writing GIO modules, see [class@Gio.IOModule].
<!-- TODO: Implementation note about using extended attributes on supported
file systems -->
## Default Keys
For a list of the built-in keys and their types, see the [class@Gio.FileInfo]
documentation.
Note that there are no predefined keys in the `xattr` and `xattr-sys`
namespaces. Keys for the `xattr` namespace are constructed by stripping
away the `user.` prefix from the extended user attribute, and prepending
`xattr::`. Keys for the `xattr-sys` namespace are constructed by
concatenating `xattr-sys::` with the extended attribute name. All extended
attribute values are returned as hex-encoded strings in which bytes outside
the ASCII range are encoded as escape sequences of the form `\xnn`
where `nn` is a 2-digit hexadecimal number.

2
docs/reference/gio/gio-sections-common.txt
View File

@ -3366,6 +3366,8 @@ g_application_command_line_get_exit_status
<SUBSECTION>
g_application_command_line_print
g_application_command_line_printerr
g_application_command_line_print_literal
g_application_command_line_printerr_literal
<SUBSECTION Standard>
G_TYPE_APPLICATION_COMMAND_LINE
G_APPLICATION_COMMAND_LINE

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

@ -41,6 +41,8 @@ urlmap_file = "urlmap.js"
# The same order will be used when generating the index
content_files = [
"overview.md",
"file-attributes.md",
"tls-overview.md",
"migrating-gdbus.md",
"migrating-gconf.md",

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

@ -154,11 +154,7 @@ if get_option('gtk_doc')
command : [concat_files_helper, '@OUTPUT@', '@INPUT@'],
)
configure_file(
output : 'gio-docs-platform.xml',
input : platform_file,
copy : true,
)
fs.copyfile(platform_file, 'gio-docs-platform.xml')
content_files = [
'migrating-posix.xml',
@ -229,17 +225,18 @@ endif
# gi-docgen version
expand_content_files = [
'file-attributes.md',
'migrating-gconf.md',
'migrating-gdbus.md',
'migrating-gnome-vfs.md',
'overview.md',
'tls-overview.md',
]
gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'
gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf)
custom_target('gio-docs',
input: [ gio_toml, gio_gir ],
input: [ gio_toml, gio_gir[0] ],
output: 'gio',
command: [
gidocgen,
@ -248,8 +245,9 @@ custom_target('gio-docs',
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
'--add-include-path=@0@'.format(meson.current_source_dir() / '../gobject'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gmodule'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gio'),
'@INPUT1@',
],
build_by_default: true,

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.

1
docs/reference/gio/urlmap.js
View File

@ -1,6 +1,7 @@
// SPDX-License-Identifier: LGPL-2.1-or-later
// SPDX-FileCopyrightText: 2023 Matthias Clasen
var baseURLs = [
[ 'GdkPixbuf', 'https://docs.gtk.org/gdk-pixbuf/' ],
[ 'GLib', 'https://docs.gtk.org/glib/' ],
[ 'GModule', 'https://docs.gtk.org/gmodule/' ],
[ 'GObject', 'https://docs.gtk.org/gobject/' ],

86561
docs/reference/glib/GLib-2.0.gir
View File

File diff suppressed because it is too large Load Diff

11
docs/reference/glib/building.md
View File

@ -108,6 +108,17 @@ libraries.
where GLib installs the SystemTap probes, using the
`-Dtapset_install_dir=DIR` option.
- [gobject-introspection](https://gitlab.gnome.org/GNOME/gobject-introspection/)
is needed to generate introspection data for consumption by other projects,
and to generate the GLib documentation via
[gi-docgen](https://gitlab.gnome.org/GNOME/gi-docgen). There is a dependency
cycle between GLib and gobject-introspection. This can be broken by building
GLib first with `-Dintrospection=disabled`, then building
gobject-introspection against this copy of GLib, then re-building GLib against
the new gobject-introspection with `-Dintrospection=enabled`. The GLib API
documentation can be built during this second build process if
`-Dgtk_doc=true` is also set.
## Extra Configuration Options
In addition to the normal options, these additional ones are supported when

4
docs/reference/glib/meson.build
View File

@ -166,11 +166,10 @@ expand_content_files = [
'unicode.md',
]
glib_gir = meson.current_source_dir() / 'GLib-2.0.gir'
glib_toml = configure_file(input: 'glib.toml.in', output: 'glib.toml', configuration: toml_conf)
custom_target('glib-docs',
input: [ glib_toml, glib_gir ],
input: [ glib_toml, glib_gir[0] ],
output: 'glib',
command: [
gidocgen,
@ -179,6 +178,7 @@ custom_target('glib-docs',
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
'@INPUT1@',
],
build_by_default: true,

535
docs/reference/gmodule/GModule-2.0.gir
View File

@ -1,535 +0,0 @@
<?xml version="1.0"?>
<!-- This file was automatically generated from C sources - DO NOT EDIT!
To affect the contents of this file, edit the original C definitions,
and/or use gtk-doc annotations. -->
<repository version="1.2"
xmlns="http://www.gtk.org/introspection/core/1.0"
xmlns:c="http://www.gtk.org/introspection/c/1.0"
xmlns:glib="http://www.gtk.org/introspection/glib/1.0">
<include name="GLib" version="2.0"/>
<package name="gmodule-2.0"/>
<c:include name="gmodule.h"/>
<namespace name="GModule"
version="2.0"
shared-library="libgmodule-2.0.so.0"
c:identifier-prefixes="G"
c:symbol-prefixes="g">
<record name="Module" c:type="GModule" disguised="1" opaque="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="5">The #GModule struct is an opaque data structure to represent a
[dynamically-loaded module][glib-Dynamic-Loading-of-Modules].
It should only be accessed via the following functions.</doc>
<source-position filename="gmodule.h" line="70"/>
<method name="close" c:identifier="g_module_close">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="207">Closes a module.</doc>
<source-position filename="gmodule.h" line="110"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="213">%TRUE on success</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
<parameters>
<instance-parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="209">a #GModule to close</doc>
<type name="Module" c:type="GModule*"/>
</instance-parameter>
</parameters>
</method>
<method name="make_resident" c:identifier="g_module_make_resident">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="226">Ensures that a module will never be unloaded.
Any future g_module_close() calls on the module will be ignored.</doc>
<source-position filename="gmodule.h" line="114"/>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
</return-value>
<parameters>
<instance-parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="228">a #GModule to make permanently resident</doc>
<type name="Module" c:type="GModule*"/>
</instance-parameter>
</parameters>
</method>
<method name="name" c:identifier="g_module_name">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="235">Returns the filename that the module was opened with.
If @module refers to the application itself, "main" is returned.</doc>
<source-position filename="gmodule.h" line="128"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="243">the filename of the module</doc>
<type name="utf8" c:type="const gchar*"/>
</return-value>
<parameters>
<instance-parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="237">a #GModule</doc>
<type name="Module" c:type="GModule*"/>
</instance-parameter>
</parameters>
</method>
<method name="symbol" c:identifier="g_module_symbol">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="299">Gets a symbol pointer from a module, such as one exported
by %G_MODULE_EXPORT. Note that a valid symbol can be %NULL.</doc>
<source-position filename="gmodule.h" line="122"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="308">%TRUE on success</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
<parameters>
<instance-parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="301">a #GModule</doc>
<type name="Module" c:type="GModule*"/>
</instance-parameter>
<parameter name="symbol_name" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="302">the name of the symbol to find</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
<parameter name="symbol"
direction="out"
caller-allocates="0"
transfer-ownership="full"
nullable="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="303">returns the pointer to the symbol value</doc>
<type name="gpointer" c:type="gpointer*"/>
</parameter>
</parameters>
</method>
<function name="build_path"
c:identifier="g_module_build_path"
deprecated="1"
deprecated-version="2.76">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="179">A portable way to build the filename of a module. The platform-specific
prefix and suffix are added to the filename, if needed, and the result
is added to the directory, using the correct separator character.
The directory should specify the directory where the module can be found.
It can be %NULL or an empty string to indicate that the module is in a
standard platform-specific directory, though this is not recommended
since the wrong module may be found.
For example, calling g_module_build_path() on a Linux system with a
@directory of `/lib` and a @module_name of "mylibrary" will return
`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
directory it will return `\Windows\mylibrary.dll`.</doc>
<doc-deprecated xml:space="preserve">Use g_module_open() instead with @module_name as the
basename of the file_name argument. See %G_MODULE_SUFFIX for why.</doc-deprecated>
<source-position filename="gmodule.h" line="142"/>
<return-value transfer-ownership="full">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="200">the complete path of the module, including the standard library
prefix and suffix. This should be freed when no longer needed</doc>
<type name="utf8" c:type="gchar*"/>
</return-value>
<parameters>
<parameter name="directory"
transfer-ownership="none"
nullable="1"
allow-none="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="181">the directory where the module is. This can be
%NULL or the empty string to indicate that the standard platform-specific
directories will be used, though that is not recommended</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
<parameter name="module_name" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="184">the name of the module</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</function>
<function name="error" c:identifier="g_module_error">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="217">Gets a string describing the last module error.</doc>
<source-position filename="gmodule.h" line="118"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="222">a string describing the last module error</doc>
<type name="utf8" c:type="const gchar*"/>
</return-value>
</function>
<function name="error_quark" c:identifier="g_module_error_quark">
<return-value transfer-ownership="none">
<type name="GLib.Quark" c:type="GQuark"/>
</return-value>
</function>
<function name="open" c:identifier="g_module_open" introspectable="0">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="247">A thin wrapper function around g_module_open_full()</doc>
<source-position filename="gmodule.h" line="100"/>
<return-value>
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="256">a #GModule on success, or %NULL on failure</doc>
<type name="Module" c:type="GModule*"/>
</return-value>
<parameters>
<parameter name="file_name"
transfer-ownership="none"
nullable="1"
allow-none="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="249">the name or path to the file containing the module,
or %NULL to obtain a #GModule representing the main program itself</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
<parameter name="flags" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="251">the flags used for opening the module. This can be the
logical OR of any of the #GModuleFlags.</doc>
<type name="ModuleFlags" c:type="GModuleFlags"/>
</parameter>
</parameters>
</function>
<function name="open_full"
c:identifier="g_module_open_full"
version="2.70"
introspectable="0"
throws="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="260">Opens a module. If the module has already been opened, its reference count
is incremented. If not, the module is searched in the following order:
1. If @file_name exists as a regular file, it is used as-is; else
2. If @file_name doesn't have the correct suffix and/or prefix for the
platform, then possible suffixes and prefixes will be added to the
basename till a file is found and whatever is found will be used; else
3. If @file_name doesn't have the ".la"-suffix, ".la" is appended. Either
way, if a matching .la file exists (and is a libtool archive) the
libtool archive is parsed to find the actual file name, and that is
used.
At the end of all this, we would have a file path that we can access on
disk, and it is opened as a module. If not, @file_name is opened as
a module verbatim in the hopes that the system implementation will somehow
be able to access it.</doc>
<source-position filename="gmodule.h" line="104"/>
<return-value>
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="285">a #GModule on success, or %NULL on failure</doc>
<type name="Module" c:type="GModule*"/>
</return-value>
<parameters>
<parameter name="file_name"
transfer-ownership="none"
nullable="1"
allow-none="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="262">the name or path to the file containing the module,
or %NULL to obtain a #GModule representing the main program itself</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
<parameter name="flags" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="264">the flags used for opening the module. This can be the
logical OR of any of the #GModuleFlags</doc>
<type name="ModuleFlags" c:type="GModuleFlags"/>
</parameter>
</parameters>
</function>
<function name="supported" c:identifier="g_module_supported">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="290">Checks if modules are supported on the current platform.</doc>
<source-position filename="gmodule.h" line="96"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="295">%TRUE if modules are supported</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
</function>
</record>
<callback name="ModuleCheckInit" c:type="GModuleCheckInit">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="14">Specifies the type of the module initialization function.
If a module contains a function named g_module_check_init() it is called
automatically when the module is loaded. It is passed the #GModule structure
and should return %NULL on success or a string describing the initialization
error.</doc>
<source-position filename="gmodule.h" line="71"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="24">%NULL on success, or a string describing the initialization error</doc>
<type name="utf8" c:type="const gchar*"/>
</return-value>
<parameters>
<parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="16">the #GModule corresponding to the module which has just been loaded</doc>
<type name="Module" c:type="GModule*"/>
</parameter>
</parameters>
</callback>
<enumeration name="ModuleError"
version="2.70"
c:type="GModuleError"
glib:error-domain="g-module-error-quark">
<doc xml:space="preserve"
filename="gmodule.h"
line="78">Errors returned by g_module_open_full().</doc>
<source-position filename="gmodule.h" line="91"/>
<member name="failed" value="0" c:identifier="G_MODULE_ERROR_FAILED">
<doc xml:space="preserve"
filename="gmodule.h"
line="80">there was an error loading or opening a module file</doc>
</member>
<member name="check_failed"
value="1"
c:identifier="G_MODULE_ERROR_CHECK_FAILED">
<doc xml:space="preserve"
filename="gmodule.h"
line="81">a module returned an error from its `g_module_check_init()` function</doc>
</member>
</enumeration>
<bitfield name="ModuleFlags" c:type="GModuleFlags">
<doc xml:space="preserve"
filename="gmodule.h"
line="49">Flags passed to g_module_open().
Note that these flags are not supported on all platforms.</doc>
<source-position filename="gmodule.h" line="68"/>
<member name="lazy" value="1" c:identifier="G_MODULE_BIND_LAZY">
<doc xml:space="preserve"
filename="gmodule.h"
line="51">specifies that symbols are only resolved when
needed. The default action is to bind all symbols when the module
is loaded.</doc>
</member>
<member name="local" value="2" c:identifier="G_MODULE_BIND_LOCAL">
<doc xml:space="preserve"
filename="gmodule.h"
line="54">specifies that symbols in the module should
not be added to the global name space. The default action on most
platforms is to place symbols in the module in the global name space,
which may cause conflicts with existing symbols.</doc>
</member>
<member name="mask" value="3" c:identifier="G_MODULE_BIND_MASK">
<doc xml:space="preserve"
filename="gmodule.h"
line="58">mask for all flags.</doc>
</member>
</bitfield>
<callback name="ModuleUnload" c:type="GModuleUnload">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="28">Specifies the type of the module function called when it is unloaded.
If a module contains a function named g_module_unload() it is called
automatically when the module is unloaded.
It is passed the #GModule structure.</doc>
<source-position filename="gmodule.h" line="72"/>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
</return-value>
<parameters>
<parameter name="module" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="30">the #GModule about to be unloaded</doc>
<type name="Module" c:type="GModule*"/>
</parameter>
</parameters>
</callback>
<function name="module_build_path"
c:identifier="g_module_build_path"
moved-to="Module.build_path"
deprecated="1"
deprecated-version="2.76">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="179">A portable way to build the filename of a module. The platform-specific
prefix and suffix are added to the filename, if needed, and the result
is added to the directory, using the correct separator character.
The directory should specify the directory where the module can be found.
It can be %NULL or an empty string to indicate that the module is in a
standard platform-specific directory, though this is not recommended
since the wrong module may be found.
For example, calling g_module_build_path() on a Linux system with a
@directory of `/lib` and a @module_name of "mylibrary" will return
`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
directory it will return `\Windows\mylibrary.dll`.</doc>
<doc-deprecated xml:space="preserve">Use g_module_open() instead with @module_name as the
basename of the file_name argument. See %G_MODULE_SUFFIX for why.</doc-deprecated>
<source-position filename="gmodule.h" line="142"/>
<return-value transfer-ownership="full">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="200">the complete path of the module, including the standard library
prefix and suffix. This should be freed when no longer needed</doc>
<type name="utf8" c:type="gchar*"/>
</return-value>
<parameters>
<parameter name="directory"
transfer-ownership="none"
nullable="1"
allow-none="1">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="181">the directory where the module is. This can be
%NULL or the empty string to indicate that the standard platform-specific
directories will be used, though that is not recommended</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
<parameter name="module_name" transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="184">the name of the module</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</function>
<function name="module_error"
c:identifier="g_module_error"
moved-to="Module.error">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="217">Gets a string describing the last module error.</doc>
<source-position filename="gmodule.h" line="118"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="222">a string describing the last module error</doc>
<type name="utf8" c:type="const gchar*"/>
</return-value>
</function>
<function name="module_error_quark"
c:identifier="g_module_error_quark"
moved-to="Module.error_quark">
<return-value transfer-ownership="none">
<type name="GLib.Quark" c:type="GQuark"/>
</return-value>
</function>
<function name="module_supported"
c:identifier="g_module_supported"
moved-to="Module.supported">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="290">Checks if modules are supported on the current platform.</doc>
<source-position filename="gmodule.h" line="96"/>
<return-value transfer-ownership="none">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="295">%TRUE if modules are supported</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
</function>
<docsection name="modules">
<doc xml:space="preserve"
filename="gmodule-2.0.c"
line="99">These functions provide a portable way to dynamically load object files
(commonly known as 'plug-ins'). The current implementation supports all
systems that provide an implementation of dlopen() (e.g. Linux/Sun), as
well as Windows platforms via DLLs.
A program which wants to use these functions must be linked to the
libraries output by the command `pkg-config --libs gmodule-2.0`.
To use them you must first determine whether dynamic loading
is supported on the platform by calling g_module_supported().
If it is, you can open a module with g_module_open(),
find the module's symbols (e.g. function names) with g_module_symbol(),
and later close the module with g_module_close().
g_module_name() will return the file name of a currently opened module.
If any of the above functions fail, the error status can be found with
g_module_error().
The #GModule implementation features reference counting for opened modules,
and supports hook functions within a module which are called when the
module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
If your module introduces static data to common subsystems in the running
program, e.g. through calling
`g_quark_from_static_string ("my-module-stuff")`,
it must ensure that it is never unloaded, by calling g_module_make_resident().
Example: Calling a function defined in a GModule
|[&lt;!-- language="C" --&gt;
// the function signature for 'say_hello'
typedef void (* SayHelloFunc) (const char *message);
gboolean
just_say_hello (const char *filename, GError **error)
{
SayHelloFunc say_hello;
GModule *module;
module = g_module_open (filename, G_MODULE_BIND_LAZY);
if (!module)
{
g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
"%s", g_module_error ());
return FALSE;
}
if (!g_module_symbol (module, "say_hello", (gpointer *)&amp;say_hello))
{
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
"%s: %s", filename, g_module_error ());
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return FALSE;
}
if (say_hello == NULL)
{
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
"symbol say_hello is NULL");
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return FALSE;
}
// call our function in the module
say_hello ("Hello world!");
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return TRUE;
}
]|</doc>
</docsection>
</namespace>
</repository>

6
docs/reference/gmodule/meson.build
View File

@ -2,11 +2,10 @@ expand_content_files = [
'modules.md',
]
gmodule_gir = meson.current_source_dir() / 'GModule-2.0.gir'
gmodule_toml = configure_file(input: 'gmodule.toml.in', output: 'gmodule.toml', configuration: toml_conf)
custom_target('gmodule-docs',
input: [ gmodule_toml, gmodule_gir ],
input: [ gmodule_toml, gmodule_gir[0] ],
output: 'gmodule',
command: [
gidocgen,
@ -15,7 +14,8 @@ custom_target('gmodule-docs',
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gmodule'),
'@INPUT1@',
],
build_by_default: true,

27587
docs/reference/gobject/GObject-2.0.gir
View File

File diff suppressed because it is too large Load Diff

3
docs/reference/gobject/gobject-sections.txt
View File

@ -48,6 +48,8 @@ G_TYPE_CHECK_CLASS_TYPE
G_TYPE_CHECK_VALUE
G_TYPE_CHECK_VALUE_TYPE
G_TYPE_FLAG_RESERVED_ID_BIT
GPOINTER_TO_TYPE
GTYPE_TO_POINTER
g_type_init
GTypeDebugFlags
g_type_init_with_debug_flags
@ -717,6 +719,7 @@ g_value_take_string
g_value_set_string_take_ownership
g_value_get_string
g_value_dup_string
g_value_steal_string
g_value_set_interned_string
<SUBSECTION GParamSpec>

3
docs/reference/gobject/gobject.toml.in
View File

@ -44,10 +44,13 @@ urlmap_file = "urlmap.js"
content_files = [
"concepts.md",
"tutorial.md",
"types.md",
"signals.md",
"floating-refs.md",
"boxed.md",
"enum-types.md",
"gvalue.md",
"value-collection.md",
]
content_images = [
"images/glue.png",

8
docs/reference/gobject/meson.build
View File

@ -72,13 +72,15 @@ expand_content_files = [
'floating-refs.md',
'gvalue.md',
'tutorial.md',
'types.md',
'signals.md',
'value-collection.md',
]
gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'
gobject_toml = configure_file(input: 'gobject.toml.in', output: 'gobject.toml', configuration: toml_conf)
custom_target('gobject-docs',
input: [ gobject_toml, gobject_gir ],
input: [ gobject_toml, gobject_gir[0] ],
output: 'gobject',
command: [
gidocgen,
@ -87,7 +89,7 @@ custom_target('gobject-docs',
'--config=@INPUT0@',
'--output-dir=@OUTPUT@',
'--content-dir=@0@'.format(meson.current_source_dir()),
'--add-include-path=@0@'.format(meson.current_source_dir() / '../glib'),
'--add-include-path=@0@'.format(meson.current_build_dir() / '../../../gobject'),
'@INPUT1@',
],
build_by_default: true,

95
docs/reference/gobject/signals.md Normal file
View File

@ -0,0 +1,95 @@
Title: Signals
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2000, 2001 Tim Janik
SPDX-FileCopyrightText: 2000 Owen Taylor
SPDX-FileCopyrightText: 2002, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2014 Collabora, Ltd.
SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
# Signals
The basic concept of the signal system is that of the emission
of a signal. Signals are introduced per-type and are identified
through strings. Signals introduced for a parent type are available
in derived types as well, so basically they are a per-type facility
that is inherited.
A signal emission mainly involves invocation of a certain set of
callbacks in precisely defined manner. There are two main categories
of such callbacks, per-object ones and user provided ones.
(Although signals can deal with any kind of instantiatable type, I'm
referring to those types as "object types" in the following, simply
because that is the context most users will encounter signals in.)
The per-object callbacks are most often referred to as "object method
handler" or "default (signal) handler", while user provided callbacks are
usually just called "signal handler".
The object method handler is provided at signal creation time (this most
frequently happens at the end of an object class' creation), while user
provided handlers are frequently connected and disconnected to/from a
certain signal on certain object instances.
A signal emission consists of five stages, unless prematurely stopped:
1. Invocation of the object method handler for `G_SIGNAL_RUN_FIRST` signals
2. Invocation of normal user-provided signal handlers (where the @after
flag is not set)
3. Invocation of the object method handler for `G_SIGNAL_RUN_LAST` signals
4. Invocation of user provided signal handlers (where the @after flag is set)
5. Invocation of the object method handler for `G_SIGNAL_RUN_CLEANUP` signals
The user-provided signal handlers are called in the order they were
connected in.
All handlers may prematurely stop a signal emission, and any number of
handlers may be connected, disconnected, blocked or unblocked during
a signal emission.
There are certain criteria for skipping user handlers in stages 2 and 4
of a signal emission.
First, user handlers may be blocked. Blocked handlers are omitted during
callback invocation, to return from the blocked state, a handler has to
get unblocked exactly the same amount of times it has been blocked before.
Second, upon emission of a `G_SIGNAL_DETAILED` signal, an additional
`detail` argument passed in to [func@GObject.signal_emit] has to match
the detail argument of the signal handler currently subject to invocation.
Specification of no detail argument for signal handlers (omission of the
detail part of the signal specification upon connection) serves as a
wildcard and matches any detail argument passed in to emission.
While the `detail` argument is typically used to pass an object property name
(as with `GObject::notify`), no specific format is mandated for the detail
string, other than that it must be non-empty.
## Memory management of signal handlers
If you are connecting handlers to signals and using a `GObject` instance as
your signal handler user data, you should remember to pair calls to
[func@GObject.signal_connect] with calls to [func@GObject.signal_handler_disconnect]
or [func@GObject.signal_handlers_disconnect_by_func]. While signal handlers are
automatically disconnected when the object emitting the signal is finalised,
they are not automatically disconnected when the signal handler user data is
destroyed. If this user data is a `GObject` instance, using it from a
signal handler after it has been finalised is an error.
There are two strategies for managing such user data. The first is to
disconnect the signal handler (using [func@GObject.signal_handler_disconnect]
or [func@GObject.signal_handlers_disconnect_by_func]) when the user data (object)
is finalised; this has to be implemented manually. For non-threaded programs,
[func@GObject.signal_connect_object] can be used to implement this automatically.
Currently, however, it is unsafe to use in threaded programs.
The second is to hold a strong reference on the user data until after the
signal is disconnected for other reasons. This can be implemented
automatically using [func@GObject.signal_connect_data].
The first approach is recommended, as the second approach can result in
effective memory leaks of the user data if the signal handler is never
disconnected for some reason.

64
docs/reference/gobject/types.md Normal file
View File

@ -0,0 +1,64 @@
Title: Types
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2001, 2003 Owen Taylor
SPDX-FileCopyrightText: 2002, 2003, 2004, 2005 Matthias Clasen
SPDX-FileCopyrightText: 2003, 2006 Josh Parsons
SPDX-FileCopyrightText: 2005 Stefan Kost
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2021 Emmanuele Bassi
SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC
# Types
The GType API is the foundation of the GObject system. It provides the
facilities for registering and managing all fundamental data types,
user-defined object and interface types.
For type creation and registration purposes, all types fall into one of
two categories: static or dynamic. Static types are never loaded or
unloaded at run-time as dynamic types may be. Static types are created
with [func@GObject.type_register_static] that gets type specific
information passed in via a `GTypeInfo` structure.
Dynamic types are created with [func@GObject.type_register_dynamic],
which takes a `GTypePlugin` structure instead. The remaining type information
(the `GTypeInfo` structure) is retrieved during runtime through `GTypePlugin`
and the `g_type_plugin_*()` API.
These registration functions are usually called only once from a
function whose only purpose is to return the type identifier for a
specific class. Once the type (or class or interface) is registered,
it may be instantiated, inherited, or implemented depending on exactly
what sort of type it is.
There is also a third registration function for registering fundamental
types called [func@GObject.type_register_fundamental], which requires
both a `GTypeInfo` structure and a `GTypeFundamentalInfo` structure, but it
is rarely used since most fundamental types are predefined rather than user-defined.
Type instance and class structs are limited to a total of 64 KiB,
including all parent types. Similarly, type instances' private data
(as created by `G_ADD_PRIVATE()`) are limited to a total of
64 KiB. If a type instance needs a large static buffer, allocate it
separately (typically by using [`struct@GLib.Array`] or [`struct@GLib.PtrArray`])
and put a pointer to the buffer in the structure.
As mentioned in the [GType conventions](concepts.html#conventions), type names must
be at least three characters long. There is no upper length limit. The first
character must be a letter (a–z or A–Z) or an underscore (‘\_’). Subsequent
characters can be letters, numbers or any of ‘-\_+’.
# Runtime Debugging
When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
supports an environment variable `GOBJECT_DEBUG` that can be set to a
combination of flags to trigger debugging messages about
object bookkeeping and signal emissions during runtime.
The currently supported flags are:
- `objects`: Tracks all `GObject` instances in a global hash table called
`debug_objects_ht`, and prints the still-alive objects on exit.
- `instance-count`: Tracks the number of instances of every `GType` and makes
it available via the [func@GObject.type_get_instance_count] function.
- `signals`: Currently unused.

56
docs/reference/gobject/value-collection.md Normal file
View File

@ -0,0 +1,56 @@
Title: Value Collection
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2005 Matthias Clasen
# Value Collection
GLib provides a set of macros for the varargs parsing support needed
in variadic GObject functions such as [ctor@GObject.Object.new] or
[method@GObject.Object.set]
They currently support the collection of integral types, floating point
types and pointers.
## Macros
`G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error)`
: Collects a variable argument value from a `va_list`.
We have to implement the varargs collection as a macro, because on some
systems `va_list` variables cannot be passed by reference.
Since: 2.24
`G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error)`
: A variant of `G_VALUE_COLLECT_INIT` that provides the [struct@GObject.TypeValueTable]
to the caller.
Since: 2.74
`G_VALUE_COLLECT(value, var_args, flags, __error)`
: Collects a variable argument value from a `va_list`.
We have to implement the varargs collection as a macro, because on some systems
`va_list` variables cannot be passed by reference.
Note: If you are creating the `value argument` just before calling this macro,
you should use the `G_VALUE_COLLECT_INIT` variant and pass the uninitialized
`GValue`. That variant is faster than `G_VALUE_COLLECT`.
`G_VALUE_COLLECT_SKIP(_value_type, var_args)`
: Skip an argument of type `_value_type` from `var_args`.
`G_VALUE_LCOPY(value, var_args, flags, __error)`
: Stores a value’s value into one or more argument locations from a `va_list`.
This is the inverse of G_VALUE_COLLECT().
`G_VALUE_COLLECT_FORMAT_MAX_LENGTH`
: The maximal number of [type@GObject.TypeCValue]s which can be collected for a
single `GValue`.

2
docs/reference/meson.build
View File

@ -54,7 +54,7 @@ if get_option('gtk_doc')
endif
# gi-docgen version
if get_option('gtk_doc')
if get_option('gtk_doc') and enable_gir
gidocgen_dep = dependency('gi-docgen', version: '>= 2023.1',
fallback: ['gi-docgen', 'dummy_dep'],
required: true)

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.
* [class@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 [class@Gio.SimpleActionGroup].
**/
/**

67
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()
@ -96,13 +84,12 @@
* @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
* @get_action_state: the virtual function pointer for g_action_group_get_action_state()
* @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @query_action: the virtual function pointer for g_action_group_query_action()
* @activate_action: the virtual function pointer for g_action_group_activate_action()
* @change_action_state: the virtual function pointer for g_action_group_change_action_state()
* @action_added: the class closure for the #GActionGroup::action-added signal
* @action_removed: the class closure for the #GActionGroup::action-removed signal
* @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
* @action_state_changed: the class closure for the #GActionGroup::action-enabled-changed signal
* @query_action: the virtual function pointer for g_action_group_query_action()
*
* The virtual function table for #GActionGroup.
*

12
gio/gactiongroupexporter.c
View File

@ -32,18 +32,14 @@
#include "gdbuserror.h"
/**
* SECTION:gactiongroupexporter
* @title: GActionGroup exporter
* @include: gio/gio.h
* @short_description: Export GActionGroups on D-Bus
* @see_also: #GActionGroup, #GDBusActionGroup
* GActionGroupExporter:
*
* These functions support exporting a #GActionGroup on D-Bus.
* These functions support exporting a [class@Gio.ActionGroup] on D-Bus.
* The D-Bus interface that is used is a private implementation
* detail.
*
* To access an exported #GActionGroup remotely, use
* g_dbus_action_group_get() to obtain a #GDBusActionGroup.
* To access an exported `GActionGroup` remotely, use
* [method@Gio.DBusActionGroup.get] to obtain a [class@Gio.DBusActionGroup].
*/
static GVariant *

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 [iface@Gio.ActionGroup]
* implementations that operate by containing a number of named
* [iface@Gio.Action] instances, such as [class@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:

120
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 [iface@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 [iface@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
@ -1304,7 +1304,7 @@ g_app_info_can_delete (GAppInfo *appinfo)
/**
* g_app_info_delete:
* g_app_info_delete: (virtual do_delete)
* @appinfo: a #GAppInfo
*
* Tries to delete a #GAppInfo.
@ -1313,7 +1313,6 @@ g_app_info_can_delete (GAppInfo *appinfo)
* #GAppInfos which can be deleted, and system-wide ones which cannot.
* See g_app_info_can_delete().
*
* Virtual: do_delete
* Returns: %TRUE if @appinfo has been deleted
*
* Since: 2.20
@ -1653,54 +1652,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:
*
* - [func@Gio.AppInfo.get_all]
* - [func@Gio.AppInfo.get_all_for_type]
* - [func@Gio.AppInfo.get_default_for_type]
* - [func@Gio.AppInfo.get_fallback_for_type]
* - [func@Gio.AppInfo.get_recommended_for_type]
* - [func@Gio.DesktopAppInfo.get_implementations]
* - [ctor@Gio.DesktopAppInfo.new]
* - [ctor@Gio.DesktopAppInfo.new_from_filename]
* - [ctor@Gio.DesktopAppInfo.new_from_keyfile]
* - [func@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.

118
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 [property@Gio.Application:is-remote] to decide if you want to register
* object paths.
*
* GApplication also implements the #GActionGroup and #GActionMap
* `GApplication` also implements the [iface@Gio.ActionGroup] and [iface@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 [class@Gio.DBusActionGroup] wrapper to
* conveniently access them remotely. GIO provides a [class@Gio.DBusMenuModel] wrapper
* for remote access to exported [class@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
* [class@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
*/
@ -658,8 +654,8 @@ add_packed_option (GApplication *application,
/**
* g_application_add_main_option_entries:
* @application: a #GApplication
* @entries: (array zero-terminated=1) (element-type GOptionEntry) a
* %NULL-terminated list of #GOptionEntrys
* @entries: (array zero-terminated=1) (element-type GOptionEntry): the
* main options for the application
*
* Adds main option entries to be handled by @application.
*

116
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 [class@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:
*
@ -658,6 +654,54 @@ g_application_command_line_get_is_remote (GApplicationCommandLine *cmdline)
return IS_REMOTE (cmdline);
}
/**
* g_application_command_line_print_literal:
* @cmdline: a #GApplicationCommandLine
* @message: the message
*
* Prints a message using the stdout print handler in the invoking process.
*
* Unlike g_application_command_line_print(), @message is not a `printf()`-style
* format string. Use this function if @message contains text you don't have
* control over, that could include `printf()` escape sequences.
*
* Since: 2.80
**/
void
g_application_command_line_print_literal (GApplicationCommandLine *cmdline,
const gchar *message)
{
g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
g_return_if_fail (message != NULL);
G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
->print_literal (cmdline, message);
}
/**
* g_application_command_line_printerr_literal:
* @cmdline: a #GApplicationCommandLine
* @message: the message
*
* Prints a message using the stderr print handler in the invoking process.
*
* Unlike g_application_command_line_printerr(), @message is not
* a `printf()`-style format string. Use this function if @message contains text
* you don't have control over, that could include `printf()` escape sequences.
*
* Since: 2.80
**/
void
g_application_command_line_printerr_literal (GApplicationCommandLine *cmdline,
const gchar *message)
{
g_return_if_fail (G_IS_APPLICATION_COMMAND_LINE (cmdline));
g_return_if_fail (message != NULL);
G_APPLICATION_COMMAND_LINE_GET_CLASS (cmdline)
->printerr_literal (cmdline, message);
}
/**
* g_application_command_line_print:
* @cmdline: a #GApplicationCommandLine

7
gio/gapplicationcommandline.h
View File

@ -97,6 +97,13 @@ const gchar * g_application_command_line_get_cwd (GApplic
GIO_AVAILABLE_IN_ALL
gboolean g_application_command_line_get_is_remote (GApplicationCommandLine *cmdline);
GIO_AVAILABLE_IN_2_80
void g_application_command_line_print_literal (GApplicationCommandLine *cmdline,
const gchar *message);
GIO_AVAILABLE_IN_2_80
void g_application_command_line_printerr_literal (GApplicationCommandLine *cmdline,
const gchar *message);
GIO_AVAILABLE_IN_ALL
void g_application_command_line_print (GApplicationCommandLine *cmdline,
const gchar *format,

8
gio/gasynchelper.c
View File

@ -26,14 +26,10 @@
/*< private >
* SECTION:gasynchelper
* @short_description: Asynchronous Helper Functions
* @include: gio/gio.h
* @see_also: #GAsyncResult
* GAsyncHelper:
*
* Provides helper functions for asynchronous operations.
*
**/
*/
#ifdef G_OS_WIN32
gboolean

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 [iface@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.AsyncInitable.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.
* [method@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 [class@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 [ctor@Gio.BufferedInputStream.new],
* or [ctor@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 [class@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 [ctor@Gio.BufferedOutputStream.new],
* or [ctor@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
* [struct@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;

4
gio/gcontenttype.c
View File

@ -38,9 +38,7 @@
/**
* SECTION:gcontenttype
* @short_description: Platform-specific content typing
* @include: gio/gio.h
* GContentType:
*
* A content type is a platform specific string that defines the type
* of a file. On UNIX it is a

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 [class@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 [class@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 [class@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.
* [class@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 [class@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 [class@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 [class@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;

4
gio/gdbus-2.0/codegen/codegen.py
View File

@ -5160,12 +5160,12 @@ class CodeGenerator:
)
for i in self.ifaces:
self.outfile.write(
' g_hash_table_insert (lookup_hash, (gpointer) "%s", GSIZE_TO_POINTER (%sTYPE_%s_PROXY));\n'
' g_hash_table_insert (lookup_hash, (gpointer) "%s", (gpointer) (guintptr) (%sTYPE_%s_PROXY));\n'
% (i.name, i.ns_upper, i.name_upper)
)
self.outfile.write(" g_once_init_leave (&once_init_value, 1);\n" " }\n")
self.outfile.write(
" ret = (GType) GPOINTER_TO_SIZE (g_hash_table_lookup (lookup_hash, interface_name));\n"
" ret = (GType) (guintptr) (g_hash_table_lookup (lookup_hash, interface_name));\n"
" if (ret == (GType) 0)\n"
" ret = G_TYPE_DBUS_PROXY;\n"
)

9
gio/gdbus-2.0/codegen/meson.build
View File

@ -30,6 +30,7 @@ meson.override_find_program('gdbus-codegen', gdbus_codegen)
codegen_dir = join_paths(glib_datadir, 'glib-2.0', 'codegen')
gdbus_codegen_built_files = []
gdbus_codegen_built_targets = []
gdbus_codegen_built_files += configure_file(input : 'config.py.in',
output : 'config.py',
install_dir : codegen_dir,
@ -39,8 +40,8 @@ gdbus_codegen_built_files += configure_file(input : 'config.py.in',
foreach f : gdbus_codegen_files
# Copy these into the builddir so that gdbus-codegen can be used uninstalled
# and then install it too so that it can be used after installation
gdbus_codegen_built_files += configure_file(input : f, output : f,
install_dir : codegen_dir,
install_tag : 'bin-devel',
copy : true)
gdbus_codegen_built_targets += fs.copyfile(f, f,
install : true,
install_dir : codegen_dir,
install_tag : 'bin-devel')
endforeach

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 [method@Gio.DBusConnection.export_action_group].
*/
struct _GDBusActionGroup

5
gio/gdbusaddress.c
View File

@ -62,10 +62,7 @@
#include "glibintl.h"
/**
* SECTION:gdbusaddress
* @title: D-Bus Addresses
* @short_description: D-Bus connection endpoints
* @include: gio/gio.h
* GDBusAddress:
*
* Routines for working with D-Bus addresses. A D-Bus address is a string
* like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses

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;

67
gio/gdbusconnection.c
View File

@ -131,59 +131,62 @@
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 [class@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@Gio.bus_own_name],
* [func@Gio.bus_watch_name] or [func@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 [func@Gio.bus_get] and
* [func@Gio.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
* initialized connection. Language bindings for GIO should use
* g_initable_new() or g_async_initable_new_async(), which also initialize the
* connection.
* Most of the ways to obtain a `GDBusConnection` automatically initialize it
* (i.e. connect to D-Bus): for instance, [func@Gio.DBusConnection.new] and
* [func@Gio.bus_get], and the synchronous versions of those methods, give you
* an initialized connection. Language bindings for GIO should use
* [func@Gio.Initable.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
* [ctor@GObject.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 [method@GObject.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 +315,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 [class@Gio.DBusInterfaceSkeleton]) and client side
* (see [class@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 >*/

14
gio/gdbusmessage.c
View File

@ -462,16 +462,6 @@ g_memory_buffer_put_string (GMemoryBuffer *mbuf,
return g_memory_buffer_write (mbuf, str, strlen (str));
}
/**
* SECTION:gdbusmessage
* @short_description: D-Bus Message
* @include: gio/gio.h
*
* A type for representing D-Bus messages that can be sent or received
* on a #GDBusConnection.
*/
typedef struct _GDBusMessageClass GDBusMessageClass;
/**
@ -490,8 +480,8 @@ struct _GDBusMessageClass
/**
* GDBusMessage:
*
* The #GDBusMessage structure contains only private data and should
* only be accessed using the provided API.
* A type for representing D-Bus messages that can be sent or received
* on a [class@Gio.DBusConnection].
*
* Since: 2.26
*/

23
gio/gdbusmethodinvocation.c
View File

@ -40,17 +40,18 @@
#include "glibintl.h"
/**
* SECTION:gdbusmethodinvocation
* @short_description: Object for handling remote calls
* @include: gio/gio.h
* GDBusMethodInvocation:
*
* Instances of the #GDBusMethodInvocation class are used when
* Instances of the `GDBusMethodInvocation` class are used when
* handling D-Bus method calls. It provides a way to asynchronously
* return results and errors.
*
* The normal way to obtain a #GDBusMethodInvocation object is to receive
* it as an argument to the handle_method_call() function in a
* #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
* The normal way to obtain a `GDBusMethodInvocation` object is to receive
* it as an argument to the `handle_method_call()` function in a
* [type@Gio.DBusInterfaceVTable] that was passed to
* [method@Gio.DBusConnection.register_object].
*
* Since: 2.26
*/
typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass;
@ -68,14 +69,6 @@ struct _GDBusMethodInvocationClass
GObjectClass parent_class;
};
/**
* GDBusMethodInvocation:
*
* The #GDBusMethodInvocation structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.26
*/
struct _GDBusMethodInvocation
{
/*< private >*/

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;

111
gio/gdbusobjectmanagerclient.c
View File

@ -43,85 +43,88 @@
#include "gmarshal-internal.h"
/**
* SECTION:gdbusobjectmanagerclient
* @short_description: Client-side object manager
* @include: gio/gio.h
* GDBusObjectManagerClient:
*
* #GDBusObjectManagerClient is used to create, monitor and delete object
* proxies for remote objects exported by a #GDBusObjectManagerServer (or any
* code implementing the
* `GDBusObjectManagerClient` is used to create, monitor and delete object
* proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer]
* (or any code implementing the
* [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
* interface).
*
* Once an instance of this type has been created, you can connect to
* the #GDBusObjectManager::object-added and
* #GDBusObjectManager::object-removed signals and inspect the
* #GDBusObjectProxy objects returned by
* g_dbus_object_manager_get_objects().
* the [signal@Gio.DBusObjectManager::object-added] and
* [signal@Gio.DBusObjectManager::object-removed signals] and inspect the
* [class@Gio.DBusObjectProxy] objects returned by
* [method@Gio.DBusObjectManager.get_objects].
*
* If the name for a #GDBusObjectManagerClient is not owned by anyone at
* If the name for a `GDBusObjectManagerClient` is not owned by anyone at
* object construction time, the default behavior is to request the
* message bus to launch an owner for the name. This behavior can be
* disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START
* flag. It's also worth noting that this only works if the name of
* disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START`
* flag. It’s also worth noting that this only works if the name of
* interest is activatable in the first place. E.g. in some cases it
* is not possible to launch an owner for the requested name. In this
* case, #GDBusObjectManagerClient object construction still succeeds but
* case, `GDBusObjectManagerClient` object construction still succeeds but
* there will be no object proxies
* (e.g. g_dbus_object_manager_get_objects() returns the empty list) and
* the #GDBusObjectManagerClient:name-owner property is %NULL.
* (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and
* the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`.
*
* The owner of the requested name can come and go (for example
* consider a system service being restarted) – #GDBusObjectManagerClient
* handles this case too; simply connect to the #GObject::notify
* signal to watch for changes on the #GDBusObjectManagerClient:name-owner
* property. When the name owner vanishes, the behavior is that
* #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
* emission of the #GObject::notify signal) and then
* #GDBusObjectManager::object-removed signals are synthesized
* consider a system service being restarted) – `GDBusObjectManagerClient`
* handles this case too; simply connect to the [signal@GObject.Object::notify]
* signal to watch for changes on the
* [property@Gio.DBusObjectManagerClient:name-owner] property. When the name
* owner vanishes, the behavior is that
* [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this
* includes emission of the [signal@GObject.Object::notify] signal) and then
* [signal@Gio.DBusObjectManager::object-removed] signals are synthesized
* for all currently existing object proxies. Since
* #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can
* use this information to disambiguate a synthesized signal from a
* genuine signal caused by object removal on the remote
* #GDBusObjectManager. Similarly, when a new name owner appears,
* #GDBusObjectManager::object-added signals are synthesized
* while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
* object proxies have been added, the #GDBusObjectManagerClient:name-owner
* is set to the new name owner (this includes emission of the
* #GObject::notify signal). Furthermore, you are guaranteed that
* #GDBusObjectManagerClient:name-owner will alternate between a name owner
* (e.g. `:1.42`) and %NULL even in the case where
* [property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this
* happens, you can use this information to disambiguate a synthesized signal
* from a genuine signal caused by object removal on the remote
* [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears,
* [signal@Gio.DBusObjectManager::object-added] signals are synthesized
* while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only
* when all object proxies have been added, the
* [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name
* owner (this includes emission of the [signal@GObject.Object::notify] signal).
* Furthermore, you are guaranteed that
* [property@Gio.DBusObjectManagerClient:name-owner] will alternate between a
* name owner (e.g. `:1.42`) and `NULL` even in the case where
* the name of interest is atomically replaced
*
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
* instances. All signals (including the
* org.freedesktop.DBus.Properties::PropertiesChanged signal)
* delivered to #GDBusProxy instances are guaranteed to originate
* Ultimately, `GDBusObjectManagerClient` is used to obtain
* [class@Gio.DBusProxy] instances. All signals (including the
* `org.freedesktop.DBus.Properties::PropertiesChanged` signal)
* delivered to [class@Gio.DBusProxy] instances are guaranteed to originate
* from the name owner. This guarantee along with the behavior
* described above, means that certain race conditions including the
* "half the proxy is from the old owner and the other half is from
* the new owner" problem cannot happen.
* “half the proxy is from the old owner and the other half is from
* the new owner” problem cannot happen.
*
* To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the
* #GDBusObject::interface-added,
* #GDBusObject::interface-removed,
* #GDBusProxy::g-properties-changed and
* #GDBusProxy::g-signal signals
* are also emitted on the #GDBusObjectManagerClient instance managing these
* [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the
* [signal@Gio.DBusObject::interface-added],
* [signal@Gio.DBusObject::interface-removed],
* [signal@Gio.DBusProxy::g-properties-changed] and
* [signal@Gio.DBusProxy::g-signal] signals
* are also emitted on the `GDBusObjectManagerClient` instance managing these
* objects. The signals emitted are
* #GDBusObjectManager::interface-added,
* #GDBusObjectManager::interface-removed,
* #GDBusObjectManagerClient::interface-proxy-properties-changed and
* #GDBusObjectManagerClient::interface-proxy-signal.
* [signal@Gio.DBusObjectManager::interface-added],
* [signal@Gio.DBusObjectManager::interface-removed],
* [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and
* [signal@Gio.DBusObjectManagerClient::interface-proxy-signal].
*
* Note that all callbacks and signals are emitted in the
* [thread-default main context][g-main-context-push-thread-default]
* that the #GDBusObjectManagerClient object was constructed
* in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
* originating from the #GDBusObjectManagerClient object will be created in
* thread-default main context (see
* [method@GLib.MainContext.push_thread_default]) that the
* `GDBusObjectManagerClient` object was constructed in. Additionally, the
* [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects
* originating from the `GDBusObjectManagerClient` object will be created in
* the same context and, consequently, will deliver signals in the
* same main loop.
*
* Since: 2.30
*/
struct _GDBusObjectManagerClientPrivate

8
gio/gdbusobjectmanagerclient.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass;
typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate;
/**
* GDBusObjectManagerClient:
*
* The #GDBusObjectManagerClient structure contains private data and should
* only be accessed using the provided API.
*
* Since: 2.30
*/
struct _GDBusObjectManagerClient
{
/*< private >*/

10
gio/gdbusobjectproxy.c
View File

@ -32,13 +32,11 @@
#include "glibintl.h"
/**
* SECTION:gdbusobjectproxy
* @short_description: Client-side D-Bus object
* @include: gio/gio.h
* GDBusObjectProxy:
*
* A #GDBusObjectProxy is an object used to represent a remote object
* with one or more D-Bus interfaces. Normally, you don't instantiate
* a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient
* A `GDBusObjectProxy` is an object used to represent a remote object
* with one or more D-Bus interfaces. Normally, you don’t instantiate
* a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient]
* is used to obtain it.
*
* Since: 2.30

8
gio/gdbusobjectproxy.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectProxyClass GDBusObjectProxyClass;
typedef struct _GDBusObjectProxyPrivate GDBusObjectProxyPrivate;
/**
* GDBusObjectProxy:
*
* The #GDBusObjectProxy structure contains private data and should
* only be accessed using the provided API.
*
* Since: 2.30
*/
struct _GDBusObjectProxy
{
/*< private >*/

31
gio/gdbusserver.c
View File

@ -63,35 +63,28 @@
G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER)
/**
* SECTION:gdbusserver
* @short_description: Helper for accepting connections
* @include: gio/gio.h
* GDBusServer:
*
* #GDBusServer is a helper for listening to and accepting D-Bus
* `GDBusServer` is a helper for listening to and accepting D-Bus
* connections. This can be used to create a new D-Bus server, allowing two
* peers to use the D-Bus protocol for their own specialized communication.
* A server instance provided in this way will not perform message routing or
* implement the org.freedesktop.DBus interface.
* implement the
* [`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages).
*
* To just export an object on a well-known name on a message bus, such as the
* session or system bus, you should instead use g_bus_own_name().
* session or system bus, you should instead use [func@Gio.bus_own_name].
*
* An example of peer-to-peer communication with GDBus can be found
* in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
*
* Note that a minimal #GDBusServer will accept connections from any
* peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
* that only accepts connections that have successfully authenticated
* as the same user that is running the #GDBusServer. Since GLib 2.68 this can
* be achieved more simply by passing the
* %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.
*/
/**
* GDBusServer:
*
* The #GDBusServer structure contains only private data and
* should only be accessed using the provided API.
* Note that a minimal `GDBusServer` will accept connections from any
* peer. In many use-cases it will be necessary to add a
* [class@Gio.DBusAuthObserver] that only accepts connections that have
* successfully authenticated as the same user that is running the
* `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing
* the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the
* server.
*
* Since: 2.26
*/

20
gio/gdebugcontroller.c
View File

@ -29,25 +29,23 @@
#include "giomodule-priv.h"
/**
* SECTION:gdebugcontroller
* @title: GDebugController
* @short_description: Debugging controller
* @include: gio/gio.h
* GDebugController:
*
* #GDebugController is an interface to expose control of debugging features and
* `GDebugController` is an interface to expose control of debugging features and
* debug output.
*
* It is implemented on Linux using #GDebugControllerDBus, which exposes a D-Bus
* interface to allow authenticated peers to control debug features in this
* process.
* It is implemented on Linux using [class@Gio.DebugControllerDBus], which
* exposes a D-Bus interface to allow authenticated peers to control debug
* features in this process.
*
* Whether debug output is enabled is exposed as
* #GDebugController:debug-enabled. This controls g_log_set_debug_enabled() by
* default. Application code may connect to the #GObject::notify signal for it
* [property@Gio.DebugController:debug-enabled]. This controls
* [func@GLib.log_set_debug_enabled] by default. Application code may
* connect to the [signal@GObject.Object::notify] signal for it
* to control other parts of its debug infrastructure as necessary.
*
* If your application or service is using the default GLib log writer function,
* creating one of the built-in implementations of #GDebugController should be
* creating one of the built-in implementations of `GDebugController` should be
* all that’s needed to dynamically enable or disable debug output.
*
* Since: 2.72

8
gio/gdebugcontroller.h
View File

@ -41,14 +41,6 @@ G_BEGIN_DECLS
*/
#define G_DEBUG_CONTROLLER_EXTENSION_POINT_NAME "gio-debug-controller"
/**
* GDebugController:
*
* #GDebugController is an interface to expose control of debugging features and
* debug output.
*
* Since: 2.72
*/
#define G_TYPE_DEBUG_CONTROLLER (g_debug_controller_get_type ())
GIO_AVAILABLE_IN_2_72
G_DECLARE_INTERFACE(GDebugController, g_debug_controller, g, debug_controller, GObject)

42
gio/gdebugcontrollerdbus.c
View File

@ -31,35 +31,34 @@
#include "gio/gmarshal-internal.h"
/**
* SECTION:gdebugcontrollerdbus
* @title: GDebugControllerDBus
* @short_description: Debugging controller D-Bus implementation
* @include: gio/gio.h
* GDebugControllerDBus:
*
* #GDebugControllerDBus is an implementation of #GDebugController which exposes
* debug settings as a D-Bus object.
* `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController]
* which exposes debug settings as a D-Bus object.
*
* It is a #GInitable object, and will register an object at
* It is a [iface@Gio.Initable] object, and will register an object at
* `/org/gtk/Debugging` on the bus given as
* #GDebugControllerDBus:connection once it’s initialized. The object will be
* unregistered when the last reference to the #GDebugControllerDBus is dropped.
* [property@Gio.DebugControllerDBus:connection] once it’s initialized. The
* object will be unregistered when the last reference to the
* `GDebugControllerDBus` is dropped.
*
* This D-Bus object can be used by remote processes to enable or disable debug
* output in this process. Remote processes calling
* `org.gtk.Debugging.SetDebugEnabled()` will affect the value of
* #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled().
* default.
* [property@Gio.DebugController:debug-enabled] and, by default,
* [func@GLib.log_get_debug_enabled].
*
* By default, no processes are allowed to call `SetDebugEnabled()` unless a
* #GDebugControllerDBus::authorize signal handler is installed. This is because
* the process may be privileged, or might expose sensitive information in its
* debug output. You may want to restrict the ability to enable debug output to
* privileged users or processes.
* [signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This
* is because the process may be privileged, or might expose sensitive
* information in its debug output. You may want to restrict the ability to
* enable debug output to privileged users or processes.
*
* One option is to install a D-Bus security policy which restricts access to
* `SetDebugEnabled()`, installing something like the following in
* `$datadir/dbus-1/system.d/`:
* |[<!-- language="XML" -->
*
* ```xml
* <?xml version="1.0"?> <!--*-nxml-*-->
* <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
* "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
@ -71,7 +70,7 @@
* <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
* </policy>
* </busconfig>
* ]|
* ```
*
* This will prevent the `SetDebugEnabled()` method from being called by all
* except root. It will not prevent the `DebugEnabled` property from being read,
@ -79,9 +78,10 @@
*
* Another option is to use polkit to allow or deny requests on a case-by-case
* basis, allowing for the possibility of dynamic authorisation. To do this,
* connect to the #GDebugControllerDBus::authorize signal and query polkit in
* it:
* |[<!-- language="C" -->
* connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query
* polkit in it:
*
* ```c
* g_autoptr(GError) child_error = NULL;
* g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
* gulong debug_controller_authorize_id = 0;
@ -142,7 +142,7 @@
*
* return polkit_authorization_result_get_is_authorized (auth_result);
* }
* ]|
* ```
*
* Since: 2.72
*/

7
gio/gdebugcontrollerdbus.h
View File

@ -28,13 +28,6 @@
G_BEGIN_DECLS
/**
* GDebugControllerDBus:
*
* #GDebugControllerDBus is an implementation of #GDebugController over D-Bus.
*
* Since: 2.72
*/
#define G_TYPE_DEBUG_CONTROLLER_DBUS (g_debug_controller_dbus_get_type ())
GIO_AVAILABLE_IN_2_72
G_DECLARE_DERIVABLE_TYPE (GDebugControllerDBus, g_debug_controller_dbus, G, DEBUG_CONTROLLER_DBUS, GObject)

12
gio/gdesktopappinfo.c
View File

@ -63,12 +63,9 @@
#endif
/**
* SECTION:gdesktopappinfo
* @title: GDesktopAppInfo
* @short_description: Application information from desktop files
* @include: gio/gdesktopappinfo.h
* GDesktopAppInfo:
*
* #GDesktopAppInfo is an implementation of #GAppInfo based on
* `GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on
* desktop files.
*
* Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
@ -95,11 +92,6 @@ static gboolean g_desktop_app_info_ensure_saved (GDesktopAppInfo *info,
GError **error);
static gboolean g_desktop_app_info_load_file (GDesktopAppInfo *self);
/**
* GDesktopAppInfo:
*
* Information about an installed application from a desktop file.
*/
struct _GDesktopAppInfo
{
GObject parent_instance;

24
gio/gdrive.c
View File

@ -31,36 +31,34 @@
/**
* SECTION:gdrive
* @short_description: Drive management
* @include: gio/gio.h
* GDrive:
*
* #GDrive - this represent a piece of hardware connected to the machine.
* It's generally only created for removable hardware or hardware with
* `GDrive` represents a piece of hardware connected to the machine.
* It’s generally only created for removable hardware or hardware with
* removable media.
*
* #GDrive is a container class for #GVolume objects that stem from
* the same piece of media. As such, #GDrive abstracts a drive with
* `GDrive` is a container class for [class@Gio.Volume] objects that stem from
* the same piece of media. As such, `GDrive` abstracts a drive with
* (or without) removable media and provides operations for querying
* whether media is available, determining whether media change is
* automatically detected and ejecting the media.
*
* If the #GDrive reports that media isn't automatically detected, one
* If the `GDrive` reports that media isn’t automatically detected, one
* can poll for media; typically one should not do this periodically
* as a poll for media operation is potentially expensive and may
* spin up the drive creating noise.
*
* #GDrive supports starting and stopping drives with authentication
* `GDrive` supports starting and stopping drives with authentication
* support for the former. This can be used to support a diverse set
* of use cases including connecting/disconnecting iSCSI devices,
* powering down external disk enclosures and starting/stopping
* multi-disk devices such as RAID devices. Note that the actual
* semantics and side-effects of starting/stopping a #GDrive may vary
* semantics and side-effects of starting/stopping a `GDrive` may vary
* according to implementation. To choose the correct verbs in e.g. a
* file manager, use g_drive_get_start_stop_type().
* file manager, use [method@Gio.Drive.get_start_stop_type].
*
* For porting from GnomeVFS note that there is no equivalent of
* #GDrive in that API.
* For [porting from GnomeVFS](migrating-gnome-vfs.html) note that there is no
* equivalent of `GDrive` in that API.
**/
typedef GDriveIface GDriveInterface;

16
gio/gdtlsclientconnection.c
View File

@ -31,26 +31,14 @@
#include "gtlscertificate.h"
#include "glibintl.h"
/**
* SECTION:gdtlsclientconnection
* @short_description: DTLS client-side connection
* @include: gio/gio.h
*
* #GDtlsClientConnection is the client-side subclass of
* #GDtlsConnection, representing a client-side DTLS connection.
*
* Since: 2.48
*/
/**
* GDtlsClientConnection:
*
* Abstract base class for the backend-specific client connection
* type.
* `GDtlsClientConnection` is the client-side subclass of
* [iface@Gio.DtlsConnection], representing a client-side DTLS connection.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsClientConnection, g_dtls_client_connection,
G_TYPE_DTLS_CONNECTION)

52
gio/gdtlsconnection.c
View File

@ -35,43 +35,33 @@
#include "glibintl.h"
#include "gmarshal-internal.h"
/**
* SECTION:gdtlsconnection
* @short_description: DTLS connection type
* @include: gio/gio.h
*
* #GDtlsConnection is the base DTLS connection class type, which wraps
* a #GDatagramBased and provides DTLS encryption on top of it. Its
* subclasses, #GDtlsClientConnection and #GDtlsServerConnection,
* implement client-side and server-side DTLS, respectively.
*
* For TLS support, see #GTlsConnection.
*
* As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased,
* presenting a datagram-socket-like API for the encrypted connection. This
* operates over a base datagram connection, which is also a #GDatagramBased
* (#GDtlsConnection:base-socket).
*
* To close a DTLS connection, use g_dtls_connection_close().
*
* Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address
* on their base #GDatagramBased if it is a #GSocket — it is up to the caller to
* do that if they wish. If they do not, and g_socket_close() is called on the
* base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED
* error on further I/O.
*
* Since: 2.48
*/
/**
* GDtlsConnection:
*
* Abstract base class for the backend-specific #GDtlsClientConnection
* and #GDtlsServerConnection types.
* `GDtlsConnection` is the base DTLS connection class type, which wraps
* a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its
* subclasses, [iface@Gio.DtlsClientConnection] and
* [iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS,
* respectively.
*
* For TLS support, see [class@Gio.TlsConnection].
*
* As DTLS is datagram based, `GDtlsConnection` implements
* [iface@Gio.DatagramBased], presenting a datagram-socket-like API for the
* encrypted connection. This operates over a base datagram connection, which is
* also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]).
*
* To close a DTLS connection, use [method@Gio.DtlsConnection.close].
*
* Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection]
* set the peer address on their base [iface@Gio.DatagramBased] if it is a
* [class@Gio.Socket] — it is up to the caller to do that if they wish. If they
* do not, and [method@Gio.Socket.close] is called on the base socket, the
* `GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on
* further I/O.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsConnection, g_dtls_connection, G_TYPE_DATAGRAM_BASED)
enum {

9
gio/gdtlsserverconnection.c
View File

@ -31,16 +31,13 @@
#include "glibintl.h"
/**
* SECTION:gdtlsserverconnection
* @short_description: DTLS server-side connection
* @include: gio/gio.h
* GDtlsServerConnection:
*
* #GDtlsServerConnection is the server-side subclass of #GDtlsConnection,
* representing a server-side DTLS connection.
* `GDtlsServerConnection` is the server-side subclass of
* [iface@Gio.DtlsConnection], representing a server-side DTLS connection.
*
* Since: 2.48
*/
G_DEFINE_INTERFACE (GDtlsServerConnection, g_dtls_server_connection,
G_TYPE_DTLS_CONNECTION)

8
gio/gdtlsserverconnection.h
View File

@ -35,14 +35,6 @@ G_BEGIN_DECLS
#define G_IS_DTLS_SERVER_CONNECTION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_DTLS_SERVER_CONNECTION))
#define G_DTLS_SERVER_CONNECTION_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), G_TYPE_DTLS_SERVER_CONNECTION, GDtlsServerConnectionInterface))
/**
* GDtlsServerConnection:
*
* DTLS server-side connection. This is the server-side implementation
* of a #GDtlsConnection.
*
* Since: 2.48
*/
typedef struct _GDtlsServerConnectionInterface GDtlsServerConnectionInterface;
/**

9
gio/gemblem.c
View File

@ -31,14 +31,11 @@
/**
* SECTION:gemblem
* @short_description: An object for emblems
* @include: gio/gio.h
* @see_also: #GIcon, #GEmblemedIcon, #GLoadableIcon, #GThemedIcon
* GEmblem:
*
* #GEmblem is an implementation of #GIcon that supports
* `GEmblem` is an implementation of [iface@Gio.Icon] that supports
* having an emblem, which is an icon with additional properties.
* It can than be added to a #GEmblemedIcon.
* It can than be added to a [class@Gio.EmblemedIcon].
*
* Currently, only metainformation about the emblem's origin is
* supported. More may be added in the future.

5
gio/gemblem.h
View File

@ -37,11 +37,6 @@ G_BEGIN_DECLS
#define G_IS_EMBLEM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_EMBLEM))
#define G_EMBLEM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_EMBLEM, GEmblemClass))
/**
* GEmblem:
*
* An object for Emblems
*/
typedef struct _GEmblem GEmblem;
typedef struct _GEmblemClass GEmblemClass;

13
gio/gemblemedicon.c
View File

@ -33,17 +33,14 @@
/**
* SECTION:gemblemedicon
* @short_description: Icon with emblems
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon, #GThemedIcon, #GEmblem
* GEmblemedIcon:
*
* #GEmblemedIcon is an implementation of #GIcon that supports
* `GEmblemedIcon` is an implementation of [iface@Gio.Icon] that supports
* adding an emblem to an icon. Adding multiple emblems to an
* icon is ensured via g_emblemed_icon_add_emblem().
* icon is ensured via [method@Gio.EmblemedIcon.add_emblem].
*
* Note that #GEmblemedIcon allows no control over the position
* of the emblems. See also #GEmblem for more information.
* Note that `GEmblemedIcon` allows no control over the position
* of the emblems. See also [class@Gio.Emblem] for more information.
**/
enum {

5
gio/gemblemedicon.h
View File

@ -40,11 +40,6 @@ G_BEGIN_DECLS
#define G_IS_EMBLEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_EMBLEMED_ICON))
#define G_EMBLEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_EMBLEMED_ICON, GEmblemedIconClass))
/**
* GEmblemedIcon:
*
* An implementation of #GIcon for icons with emblems.
**/
typedef struct _GEmblemedIcon GEmblemedIcon;
typedef struct _GEmblemedIconClass GEmblemedIconClass;
typedef struct _GEmblemedIconPrivate GEmblemedIconPrivate;

59
gio/gfile.c
View File

@ -747,14 +747,13 @@ g_file_dup (GFile *file)
}
/**
* g_file_hash:
* g_file_hash: (virtual hash)
* @file: (type GFile): #gconstpointer to a #GFile
*
* Creates a hash value for a #GFile.
*
* This call does no blocking I/O.
*
* Virtual: hash
* Returns: 0 if @file is not a valid #GFile, otherwise an
* integer that can be used as hash value for the #GFile.
* This function is intended for easily hashing a #GFile to
@ -939,7 +938,7 @@ g_file_get_child_for_display_name (GFile *file,
}
/**
* g_file_has_prefix:
* g_file_has_prefix: (virtual prefix_matches)
* @file: input #GFile
* @prefix: input #GFile
*
@ -958,7 +957,6 @@ g_file_get_child_for_display_name (GFile *file,
* filesystem point of view), because the prefix of @file is an alias
* of @prefix.
*
* Virtual: prefix_matches
* Returns: %TRUE if the @file's parent, grandparent, etc is @prefix,
* %FALSE otherwise.
*/
@ -1674,7 +1672,7 @@ g_file_find_enclosing_mount_finish (GFile *file,
/**
* g_file_read:
* g_file_read: (virtual read_fn)
* @file: #GFile to read
* @cancellable: (nullable): a #GCancellable
* @error: a #GError, or %NULL
@ -1691,7 +1689,6 @@ g_file_find_enclosing_mount_finish (GFile *file,
* error will be returned. Other errors are possible too, and depend
* on what kind of filesystem the file is on.
*
* Virtual: read_fn
* Returns: (transfer full): #GFileInputStream or %NULL on error.
* Free the returned object with g_object_unref().
*/
@ -2743,10 +2740,12 @@ open_source_for_copy (GFile *source,
static gboolean
should_copy (GFileAttributeInfo *info,
gboolean copy_all_attributes,
gboolean skip_perms)
gboolean skip_perms,
gboolean skip_modified_time)
{
if (skip_perms && strcmp(info->name, "unix::mode") == 0)
return FALSE;
if ((skip_perms && strcmp(info->name, "unix::mode") == 0) ||
(skip_modified_time && strncmp(info->name, "time::modified", 14) == 0))
return FALSE;
if (copy_all_attributes)
return info->flags & G_FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED;
@ -2789,6 +2788,7 @@ g_file_build_attribute_list_for_copy (GFile *file,
int i;
gboolean copy_all_attributes;
gboolean skip_perms;
gboolean skip_modified_time;
g_return_val_if_fail (G_IS_FILE (file), NULL);
g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL);
@ -2796,6 +2796,7 @@ g_file_build_attribute_list_for_copy (GFile *file,
copy_all_attributes = flags & G_FILE_COPY_ALL_METADATA;
skip_perms = (flags & G_FILE_COPY_TARGET_DEFAULT_PERMS) != 0;
skip_modified_time = (flags & G_FILE_COPY_TARGET_DEFAULT_MODIFIED_TIME) != 0;
/* Ignore errors here, if the target supports no attributes there is
* nothing to copy. We still honor the cancellable though.
@ -2823,7 +2824,7 @@ g_file_build_attribute_list_for_copy (GFile *file,
{
for (i = 0; i < attributes->n_infos; i++)
{
if (should_copy (&attributes->infos[i], copy_all_attributes, skip_perms))
if (should_copy (&attributes->infos[i], copy_all_attributes, skip_perms, skip_modified_time))
{
if (first)
first = FALSE;
@ -2839,7 +2840,7 @@ g_file_build_attribute_list_for_copy (GFile *file,
{
for (i = 0; i < namespaces->n_infos; i++)
{
if (should_copy (&namespaces->infos[i], copy_all_attributes, FALSE))
if (should_copy (&namespaces->infos[i], copy_all_attributes, FALSE, FALSE))
{
if (first)
first = FALSE;
@ -4093,7 +4094,7 @@ g_file_make_directory (GFile *file,
}
/**
* g_file_make_directory_async:
* g_file_make_directory_async: (virtual make_directory_async)
* @file: input #GFile
* @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (nullable): optional #GCancellable object,
@ -4104,7 +4105,6 @@ g_file_make_directory (GFile *file,
*
* Asynchronously creates a directory.
*
* Virtual: make_directory_async
* Since: 2.38
*/
void
@ -4127,7 +4127,7 @@ g_file_make_directory_async (GFile *file,
}
/**
* g_file_make_directory_finish:
* g_file_make_directory_finish: (virtual make_directory_finish)
* @file: input #GFile
* @result: a #GAsyncResult
* @error: a #GError, or %NULL
@ -4135,7 +4135,6 @@ g_file_make_directory_async (GFile *file,
* Finishes an asynchronous directory creation, started with
* g_file_make_directory_async().
*
* Virtual: make_directory_finish
* Returns: %TRUE on successful directory creation, %FALSE otherwise.
* Since: 2.38
*/
@ -4367,7 +4366,7 @@ g_file_real_make_symbolic_link_async (GFile *file,
}
/**
* g_file_make_symbolic_link_async:
* g_file_make_symbolic_link_async: (virtual make_symbolic_link_async)
* @file: a #GFile with the name of the symlink to create
* @symlink_value: (type filename): a string with the path for the target
* of the new symlink
@ -4381,7 +4380,6 @@ g_file_real_make_symbolic_link_async (GFile *file,
* Asynchronously creates a symbolic link named @file which contains the
* string @symlink_value.
*
* Virtual: make_symbolic_link_async
* Since: 2.74
*/
void
@ -4418,7 +4416,7 @@ g_file_real_make_symbolic_link_finish (GFile *file,
}
/**
* g_file_make_symbolic_link_finish:
* g_file_make_symbolic_link_finish: (virtual make_symbolic_link_finish)
* @file: input #GFile
* @result: a #GAsyncResult
* @error: a #GError, or %NULL
@ -4426,7 +4424,6 @@ g_file_real_make_symbolic_link_finish (GFile *file,
* Finishes an asynchronous symbolic link creation, started with
* g_file_make_symbolic_link_async().
*
* Virtual: make_symbolic_link_finish
* Returns: %TRUE on successful directory creation, %FALSE otherwise.
* Since: 2.74
*/
@ -4448,7 +4445,7 @@ g_file_make_symbolic_link_finish (GFile *file,
}
/**
* g_file_delete:
* g_file_delete: (virtual delete_file)
* @file: input #GFile
* @cancellable: (nullable): optional #GCancellable object,
* %NULL to ignore
@ -4476,7 +4473,6 @@ g_file_make_symbolic_link_finish (GFile *file,
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
* Virtual: delete_file
* Returns: %TRUE if the file was deleted. %FALSE otherwise.
*/
gboolean
@ -4505,7 +4501,7 @@ g_file_delete (GFile *file,
}
/**
* g_file_delete_async:
* g_file_delete_async: (virtual delete_file_async)
* @file: input #GFile
* @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (nullable): optional #GCancellable object,
@ -4518,7 +4514,6 @@ g_file_delete (GFile *file,
* only be deleted if it is empty. This has the same semantics as
* g_unlink().
*
* Virtual: delete_file_async
* Since: 2.34
*/
void
@ -4541,14 +4536,13 @@ g_file_delete_async (GFile *file,
}
/**
* g_file_delete_finish:
* g_file_delete_finish: (virtual delete_file_finish)
* @file: input #GFile
* @result: a #GAsyncResult
* @error: a #GError, or %NULL
*
* Finishes deleting a file started with g_file_delete_async().
*
* Virtual: delete_file_finish
* Returns: %TRUE if the file was deleted. %FALSE otherwise.
* Since: 2.34
**/
@ -4570,7 +4564,7 @@ g_file_delete_finish (GFile *file,
}
/**
* g_file_trash:
* g_file_trash: (virtual trash)
* @file: #GFile to send to trash
* @cancellable: (nullable): optional #GCancellable object,
* %NULL to ignore
@ -4587,7 +4581,6 @@ g_file_delete_finish (GFile *file,
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
* Virtual: trash
* Returns: %TRUE on successful trash, %FALSE otherwise.
*/
gboolean
@ -4616,7 +4609,7 @@ g_file_trash (GFile *file,
}
/**
* g_file_trash_async:
* g_file_trash_async: (virtual trash_async)
* @file: input #GFile
* @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (nullable): optional #GCancellable object,
@ -4627,7 +4620,6 @@ g_file_trash (GFile *file,
*
* Asynchronously sends @file to the Trash location, if possible.
*
* Virtual: trash_async
* Since: 2.38
*/
void
@ -4650,7 +4642,7 @@ g_file_trash_async (GFile *file,
}
/**
* g_file_trash_finish:
* g_file_trash_finish: (virtual trash_finish)
* @file: input #GFile
* @result: a #GAsyncResult
* @error: a #GError, or %NULL
@ -4658,7 +4650,6 @@ g_file_trash_async (GFile *file,
* Finishes an asynchronous file trashing operation, started with
* g_file_trash_async().
*
* Virtual: trash_finish
* Returns: %TRUE on successful trash, %FALSE otherwise.
* Since: 2.38
*/
@ -5794,7 +5785,7 @@ g_file_eject_mountable_with_operation_finish (GFile *file,
}
/**
* g_file_monitor_directory:
* g_file_monitor_directory: (virtual monitor_dir)
* @file: input #GFile
* @flags: a set of #GFileMonitorFlags
* @cancellable: (nullable): optional #GCancellable object,
@ -5814,10 +5805,8 @@ g_file_eject_mountable_with_operation_finish (GFile *file,
* directory for changes made via hard links; if you want to do this then
* you must register individual watches with g_file_monitor().
*
* Virtual: monitor_dir
* Returns: (transfer full): a #GFileMonitor for the given @file,
* or %NULL on error.
* Free the returned object with g_object_unref().
* or %NULL on error. Free the returned object with g_object_unref().
*/
GFileMonitor *
g_file_monitor_directory (GFile *file,

107
gio/gfileattribute.c
View File

@ -30,113 +30,6 @@
#include "glibintl.h"
/**
* SECTION:gfileattribute
* @short_description: Key-Value Paired File Attributes
* @include: gio/gio.h
* @see_also: #GFile, #GFileInfo
*
* File attributes in GIO consist of a list of key-value pairs.
*
* Keys are strings that contain a key namespace and a key name, separated
* by a colon, e.g. "namespace::keyname". Namespaces are included to sort
* key-value pairs by namespaces for relevance. Keys can be retrieved
* using wildcards, e.g. "standard::*" will return all of the keys in the
* "standard" namespace.
*
* The list of possible attributes for a filesystem (pointed to by a #GFile) is
* available as a #GFileAttributeInfoList. This list is queryable by key names
* as indicated earlier.
*
* Information is stored within the list in #GFileAttributeInfo structures.
* The info structure can store different types, listed in the enum
* #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will
* be set to %G_FILE_ATTRIBUTE_TYPE_INVALID.
*
* Classes that implement #GFileIface will create a #GFileAttributeInfoList and
* install default keys and values for their given file system, architecture,
* and other possible implementation details (e.g., on a UNIX system, a file
* attribute key will be registered for the user id for a given file).
*
* ## Default Namespaces
*
* - `"standard"`: The "Standard" namespace. General file information that
* any application may need should be put in this namespace. Examples
* include the file's name, type, and size.
* - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key
* in this namespace is "value", which contains the value of the current
* entity tag.
* - `"id"`: The "Identification" namespace. This namespace is used by file
* managers and applications that list directories to check for loops and
* to uniquely identify files.
* - `"access"`: The "Access" namespace. Used to check if a user has the
* proper privileges to access files and perform file operations. Keys in
* this namespace are made to be generic and easily understood, e.g. the
* "can_read" key is %TRUE if the current user has permission to read the
* file. UNIX permissions and NTFS ACLs in Windows should be mapped to
* these values.
* - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys
* for checking if a file or path supports mount operations, e.g. mount,
* unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.
* - `"time"`: The "Time" namespace. Includes file access, changed, created
* times.
* - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and
* may not be available for all files. Examples include the UNIX "UID",
* "GID", etc.
* - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may
* not be available for all files. Examples include "is_system" for checking
* if a file is marked as a system file, and "is_archive" for checking if a
* file is marked as an archive file.
* - `"owner"`: The "Owner" namespace. Includes information about who owns a
* file. May not be available for all file systems. Examples include "user"
* for getting the user name of the file owner. This information is often
* mapped from some backend specific data such as a UNIX UID.
* - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file
* thumbnails and their location within the file system. Examples of keys in
* this namespace include "path" to get the location of a thumbnail, "failed"
* to check if thumbnailing of the file failed, and "is-valid" to check if
* the thumbnail is outdated.
* - `"filesystem"`: The "Filesystem" namespace. Gets information about the
* file system where a file is located, such as its type, how much space is
* left available, and the overall size of the file system.
* - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information
* about the current GVFS backend in use.
* - `"xattr"`: The "xattr" namespace. Gets information about extended
* user attributes. See attr(5). The "user." prefix of the extended user
* attribute name is stripped away when constructing keys in this namespace,
* e.g. "xattr::mime_type" for the extended attribute with the name
* "user.mime_type". Note that this information is only available if
* GLib has been built with extended attribute support.
* - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about
* extended attributes which are not user-specific. See attr(5). Note
* that this information is only available if GLib has been built with
* extended attribute support.
* - `"selinux"`: The "SELinux" namespace. Includes information about the
* SELinux context of files. Note that this information is only available
* if GLib has been built with SELinux support.
*
* Please note that these are not all of the possible namespaces.
* More namespaces can be added from GIO modules or by individual applications.
* For more information about writing GIO modules, see #GIOModule.
*
* <!-- TODO: Implementation note about using extended attributes on supported
* file systems -->
*
* ## Default Keys
*
* For a list of the built-in keys and their types, see the
* [GFileInfo][GFileInfo] documentation.
*
* Note that there are no predefined keys in the "xattr" and "xattr-sys"
* namespaces. Keys for the "xattr" namespace are constructed by stripping
* away the "user." prefix from the extended user attribute, and prepending
* "xattr::". Keys for the "xattr-sys" namespace are constructed by
* concatenating "xattr-sys::" with the extended attribute name. All extended
* attribute values are returned as hex-encoded strings in which bytes outside
* the ASCII range are encoded as escape sequences of the form \x`nn`
* where `nn` is a 2-digit hexadecimal number.
*/
/**
* _g_file_attribute_value_free:
* @attr: a #GFileAttributeValue.

12
gio/gfiledescriptorbased.c
View File

@ -26,20 +26,18 @@
/**
* SECTION:gfiledescriptorbased
* @short_description: Interface for file descriptor based IO
* @include: gio/gfiledescriptorbased.h
* @see_also: #GInputStream, #GOutputStream
* GFileDescriptorBased:
*
* #GFileDescriptorBased is implemented by streams (implementations of
* #GInputStream or #GOutputStream) that are based on file descriptors.
* `GFileDescriptorBased` is an interface for file descriptor based IO.
*
* It is implemented by streams (implementations of [class@Gio.InputStream] or
* [class@Gio.OutputStream]) that are based on file descriptors.
*
* Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
* GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*
* Since: 2.24
*
**/
typedef GFileDescriptorBasedIface GFileDescriptorBasedInterface;

5
gio/gfiledescriptorbased.h
View File

@ -33,11 +33,6 @@ G_BEGIN_DECLS
#define G_FILE_DESCRIPTOR_BASED_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE_DESCRIPTOR_BASED, GFileDescriptorBasedIface))
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GFileDescriptorBased, g_object_unref)
/**
* GFileDescriptorBased:
*
* An interface for file descriptor based io objects.
**/
typedef struct _GFileDescriptorBasedIface GFileDescriptorBasedIface;
/**

Some files were not shown because too many files have changed in this diff Show More