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

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

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

See merge request GNOME/glib!3667
This commit is contained in:
Philip Withnall 2023-10-25 14:28:43 +00:00
commit 58cce38f37
37 changed files with 344 additions and 510 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
gio/gdbusmethodinvocation.c
View File

@ -40,17 +40,18 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gdbusmethodinvocation * GDBusMethodInvocation:
* @short_description: Object for handling remote calls
* @include: gio/gio.h
* *
* 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 * handling D-Bus method calls. It provides a way to asynchronously
* return results and errors. * return results and errors.
* *
* The normal way to obtain a #GDBusMethodInvocation object is to receive * The normal way to obtain a `GDBusMethodInvocation` object is to receive
* it as an argument to the handle_method_call() function in a * it as an argument to the `handle_method_call()` function in a
* #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). * [type@Gio.DBusInterfaceVTable] that was passed to
* [method@Gio.DBusConnection.register_object].
*
* Since: 2.26
*/ */
typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass; typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass;
@ -68,14 +69,6 @@ struct _GDBusMethodInvocationClass
GObjectClass parent_class; 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 struct _GDBusMethodInvocation
{ {
/*< private >*/ /*< private >*/

111
gio/gdbusobjectmanagerclient.c
View File

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

8
gio/gdbusobjectmanagerclient.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass; typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass;
typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate; 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 struct _GDBusObjectManagerClient
{ {
/*< private >*/ /*< private >*/

10
gio/gdbusobjectproxy.c
View File

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

8
gio/gdbusobjectproxy.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectProxyClass GDBusObjectProxyClass; typedef struct _GDBusObjectProxyClass GDBusObjectProxyClass;
typedef struct _GDBusObjectProxyPrivate GDBusObjectProxyPrivate; 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 struct _GDBusObjectProxy
{ {
/*< private >*/ /*< private >*/

12
gio/gdesktopappinfo.c
View File

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

15
gio/gfileinputstream.c
View File

@ -33,20 +33,17 @@
/** /**
* SECTION:gfileinputstream * GFileInputStream:
* @short_description: File input streaming operations
* @include: gio/gio.h
* @see_also: #GInputStream, #GDataInputStream, #GSeekable
* *
* GFileInputStream provides input streams that take their * `GFileInputStream` provides input streams that take their
* content from a file. * content from a file.
* *
* GFileInputStream implements #GSeekable, which allows the input * `GFileInputStream` implements [iface@Gio.Seekable], which allows the input
* stream to jump to arbitrary positions in the file, provided the * stream to jump to arbitrary positions in the file, provided the
* filesystem of the file allows it. To find the position of a file * filesystem of the file allows it. To find the position of a file
* input stream, use g_seekable_tell(). To find out if a file input * input stream, use [method@Gio.Seekable.tell]. To find out if a file input
* stream supports seeking, use g_seekable_can_seek(). * stream supports seeking, use [iface@Gio.Seekable.can_seek].
* To position a file input stream, use g_seekable_seek(). * To position a file input stream, use [iface@Gio.Seekable.seek].
**/ **/
static void g_file_input_stream_seekable_iface_init (GSeekableIface *iface); static void g_file_input_stream_seekable_iface_init (GSeekableIface *iface);

8
gio/gfileinputstream.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM)) #define G_IS_FILE_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM))
#define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass)) #define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass))
/**
* GFileInputStream:
*
* A subclass of GInputStream for opened files. This adds
* a few file-specific operations and seeking.
*
* #GFileInputStream implements #GSeekable.
**/
typedef struct _GFileInputStreamClass GFileInputStreamClass; typedef struct _GFileInputStreamClass GFileInputStreamClass;
typedef struct _GFileInputStreamPrivate GFileInputStreamPrivate; typedef struct _GFileInputStreamPrivate GFileInputStreamPrivate;

19
gio/gfileoutputstream.c
View File

@ -33,25 +33,22 @@
/** /**
* SECTION:gfileoutputstream * GFileOutputStream:
* @short_description: File output streaming operations
* @include: gio/gio.h
* @see_also: #GOutputStream, #GDataOutputStream, #GSeekable
* *
* GFileOutputStream provides output streams that write their * `GFileOutputStream` provides output streams that write their
* content to a file. * content to a file.
* *
* GFileOutputStream implements #GSeekable, which allows the output * `GFileOutputStream` implements [iface@Gio.Seekable], which allows the output
* stream to jump to arbitrary positions in the file and to truncate * stream to jump to arbitrary positions in the file and to truncate
* the file, provided the filesystem of the file supports these * the file, provided the filesystem of the file supports these
* operations. * operations.
* *
* To find the position of a file output stream, use g_seekable_tell(). * To find the position of a file output stream, use [method@Gio.Seekable.tell].
* To find out if a file output stream supports seeking, use * To find out if a file output stream supports seeking, use
* g_seekable_can_seek().To position a file output stream, use * [method@Gio.Seekable.can_seek].To position a file output stream, use
* g_seekable_seek(). To find out if a file output stream supports * [method@Gio.Seekable.seek]. To find out if a file output stream supports
* truncating, use g_seekable_can_truncate(). To truncate a file output * truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output
* stream, use g_seekable_truncate(). * stream, use [method@Gio.Seekable.truncate].
**/ **/
static void g_file_output_stream_seekable_iface_init (GSeekableIface *iface); static void g_file_output_stream_seekable_iface_init (GSeekableIface *iface);

8
gio/gfileoutputstream.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILE_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM)) #define G_IS_FILE_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM))
#define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass)) #define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass))
/**
* GFileOutputStream:
*
* A subclass of GOutputStream for opened files. This adds
* a few file-specific operations and seeking and truncating.
*
* #GFileOutputStream implements GSeekable.
**/
typedef struct _GFileOutputStreamClass GFileOutputStreamClass; typedef struct _GFileOutputStreamClass GFileOutputStreamClass;
typedef struct _GFileOutputStreamPrivate GFileOutputStreamPrivate; typedef struct _GFileOutputStreamPrivate GFileOutputStreamPrivate;

4
gio/gfilterinputstream.c
View File

@ -27,9 +27,7 @@
/** /**
* SECTION:gfilterinputstream * GFilterInputStream:
* @short_description: Filter Input Stream
* @include: gio/gio.h
* *
* Base class for input stream implementations that perform some * Base class for input stream implementations that perform some
* kind of filtering operation on a base stream. Typical examples * kind of filtering operation on a base stream. Typical examples

5
gio/gfilterinputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM)) #define G_IS_FILTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM))
#define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass)) #define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass))
/**
* GFilterInputStream:
*
* A base class for all input streams that work on an underlying stream.
**/
typedef struct _GFilterInputStreamClass GFilterInputStreamClass; typedef struct _GFilterInputStreamClass GFilterInputStreamClass;
struct _GFilterInputStream struct _GFilterInputStream

4
gio/gfilteroutputstream.c
View File

@ -27,9 +27,7 @@
/** /**
* SECTION:gfilteroutputstream * GFilterOutputStream:
* @short_description: Filter Output Stream
* @include: gio/gio.h
* *
* Base class for output stream implementations that perform some * Base class for output stream implementations that perform some
* kind of filtering operation on a base stream. Typical examples * kind of filtering operation on a base stream. Typical examples

5
gio/gfilteroutputstream.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_FILTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM)) #define G_IS_FILTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM))
#define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass)) #define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass))
/**
* GFilterOutputStream:
*
* A base class for all output streams that work on an underlying stream.
**/
typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass; typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass;
struct _GFilterOutputStream struct _GFilterOutputStream

17
gio/gnetworkservice.c
View File

@ -43,28 +43,19 @@
/** /**
* SECTION:gnetworkservice * GNetworkService:
* @short_description: A GSocketConnectable for resolving SRV records
* @include: gio/gio.h
* *
* Like #GNetworkAddress does with hostnames, #GNetworkService * Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService`
* provides an easy way to resolve a SRV record, and then attempt to * provides an easy way to resolve a SRV record, and then attempt to
* connect to one of the hosts that implements that service, handling * connect to one of the hosts that implements that service, handling
* service priority/weighting, multiple IP addresses, and multiple * service priority/weighting, multiple IP addresses, and multiple
* address families. * address families.
* *
* See #GSrvTarget for more information about SRV records, and see * See [struct@Gio.SrvTarget] for more information about SRV records, and see
* #GSocketConnectable for an example of using the connectable * [iface@Gio.SocketConnectable] for an example of using the connectable
* interface. * interface.
*/ */
/**
* GNetworkService:
*
* A #GSocketConnectable for resolving a SRV record and connecting to
* that service.
*/
struct _GNetworkServicePrivate struct _GNetworkServicePrivate
{ {
gchar *service, *protocol, *domain, *scheme; gchar *service, *protocol, *domain, *scheme;

12
gio/gproxy.c
View File

@ -29,16 +29,14 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gproxy * GProxy:
* @short_description: Interface for proxy handling
* @include: gio/gio.h
* *
* A #GProxy handles connecting to a remote host via a given type of * A `GProxy` handles connecting to a remote host via a given type of
* proxy server. It is implemented by the 'gio-proxy' extension point. * proxy server. It is implemented by the `gio-proxy` extension point.
* The extensions are named after their proxy protocol name. As an * The extensions are named after their proxy protocol name. As an
* example, a SOCKS5 proxy implementation can be retrieved with the * example, a SOCKS5 proxy implementation can be retrieved with the
* name 'socks5' using the function * name `socks5` using the function
* g_io_extension_point_get_extension_by_name(). * [method@Gio.IOExtensionPoint.get_extension_by_name].
* *
* Since: 2.26 * Since: 2.26
**/ **/

7
gio/gproxy.h
View File

@ -48,13 +48,6 @@ G_BEGIN_DECLS
*/ */
#define G_PROXY_EXTENSION_POINT_NAME "gio-proxy" #define G_PROXY_EXTENSION_POINT_NAME "gio-proxy"
/**
* GProxy:
*
* Interface that handles proxy connection and payload.
*
* Since: 2.26
*/
typedef struct _GProxyInterface GProxyInterface; typedef struct _GProxyInterface GProxyInterface;
/** /**

19
gio/gproxyaddressenumerator.c
View File

@ -42,19 +42,18 @@
#include "gsocketconnectable.h" #include "gsocketconnectable.h"
/** /**
* SECTION:gproxyaddressenumerator * GProxyAddressEnumerator:
* @short_description: Proxy wrapper enumerator for socket addresses
* @include: gio/gio.h
* *
* #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which * `GProxyAddressEnumerator` is a wrapper around
* takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator * [class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress]
* and wraps them in #GProxyAddress instances, using the given * instances returned by the [class@Gio.SocketAddressEnumerator]
* #GProxyAddressEnumerator:proxy-resolver. * and wraps them in [class@Gio.ProxyAddress] instances, using the given
* [property@Gio.ProxyAddressEnumerator:proxy-resolver].
* *
* This enumerator will be returned (for example, by * This enumerator will be returned (for example, by
* g_socket_connectable_enumerate()) as appropriate when a proxy is configured; * [method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is
* there should be no need to manually wrap a #GSocketAddressEnumerator instance * configured; there should be no need to manually wrap a
* with one. * [class@Gio.SocketAddressEnumerator] instance with one.
*/ */
#define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv) #define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv)

8
gio/gproxyaddressenumerator.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_PROXY_ADDRESS_ENUMERATOR)) #define G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_PROXY_ADDRESS_ENUMERATOR))
#define G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_PROXY_ADDRESS_ENUMERATOR, GProxyAddressEnumeratorClass)) #define G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_PROXY_ADDRESS_ENUMERATOR, GProxyAddressEnumeratorClass))
/**
* GProxyAddressEnumerator:
*
* A subclass of #GSocketAddressEnumerator that takes another address
* enumerator and wraps each of its results in a #GProxyAddress as
* directed by the default #GProxyResolver.
*/
typedef struct _GProxyAddressEnumeratorClass GProxyAddressEnumeratorClass; typedef struct _GProxyAddressEnumeratorClass GProxyAddressEnumeratorClass;
typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate; typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate;

17
gio/gproxyresolver.c
View File

@ -36,17 +36,16 @@
#include "gnetworkingprivate.h" #include "gnetworkingprivate.h"
/** /**
* SECTION:gproxyresolver * GProxyResolver:
* @short_description: Asynchronous and cancellable network proxy resolver
* @include: gio/gio.h
* *
* #GProxyResolver provides synchronous and asynchronous network proxy * `GProxyResolver` provides synchronous and asynchronous network proxy
* resolution. #GProxyResolver is used within #GSocketClient through * resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through
* the method g_socket_connectable_proxy_enumerate(). * the method [method@Gio.SocketConnectable.proxy_enumerate].
* *
* Implementations of #GProxyResolver based on libproxy and GNOME settings can * Implementations of `GProxyResolver` based on
* be found in glib-networking. GIO comes with an implementation for use inside * [libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be
* Flatpak portals. * found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking).
* GIO comes with an implementation for use inside Flatpak portals.
*/ */
/** /**

40
gio/gresolver.c
View File

@ -43,22 +43,27 @@
/** /**
* SECTION:gresolver * GResolver:
* @short_description: Asynchronous and cancellable DNS resolver
* @include: gio/gio.h
* *
* #GResolver provides cancellable synchronous and asynchronous DNS * The object that handles DNS resolution. Use [func@Gio.Resolver.get_default]
* resolution, for hostnames (g_resolver_lookup_by_address(), * to get the default resolver.
* g_resolver_lookup_by_name() and their async variants) and SRV
* (service) records (g_resolver_lookup_service()).
* *
* #GNetworkAddress and #GNetworkService provide wrappers around * `GResolver` provides cancellable synchronous and asynchronous DNS
* #GResolver functionality that also implement #GSocketConnectable, * resolution, for hostnames ([method@Gio.Resolver.lookup_by_address],
* making it easy to connect to a remote host/service. * [method@Gio.Resolver.lookup_by_name] and their async variants) and SRV
* (service) records ([method@Gio.Resolver.lookup_service]).
* *
* The default resolver (see g_resolver_get_default()) has a timeout of 30s set * [class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers
* on it since GLib 2.78. Earlier versions of GLib did not support resolver * around `GResolver` functionality that also implement
* timeouts. * [iface@Gio.SocketConnectable], making it easy to connect to a remote
* host/service.
*
* The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of
* 30s set on it since GLib 2.78. Earlier versions of GLib did not support
* resolver timeouts.
*
* This is an abstract type; subclasses of it implement different resolvers for
* different platforms and situations.
*/ */
typedef enum { typedef enum {
@ -83,15 +88,6 @@ struct _GResolverPrivate {
#endif #endif
}; };
/**
* GResolver:
*
* The object that handles DNS resolution. Use g_resolver_get_default()
* to get the default resolver.
*
* This is an abstract type; subclasses of it implement different resolvers for
* different platforms and situations.
*/
G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GResolver, g_resolver, G_TYPE_OBJECT, G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GResolver, g_resolver, G_TYPE_OBJECT,
G_ADD_PRIVATE (GResolver) G_ADD_PRIVATE (GResolver)
g_networking_init ();) g_networking_init ();)

193
gio/gresource.c
View File

@ -48,69 +48,72 @@ static void register_lazy_static_resources (void);
G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
/** /**
* SECTION:gresource * GResource:
* @short_description: Resource framework
* @include: gio/gio.h
* *
* Applications and libraries often contain binary or textual data that is * Applications and libraries often contain binary or textual data that is
* really part of the application, rather than user data. For instance * really part of the application, rather than user data. For instance
* #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, * [class@Gtk.Builder] `.ui` files, splashscreen images, [class@Gio.Menu] markup
* icons, etc. These are often shipped as files in `$datadir/appname`, or * XML, CSS files, icons, etc. These are often shipped as files in
* manually included as literal strings in the code. * `$datadir/appname`, or manually included as literal strings in the code.
* *
* The #GResource API and the [glib-compile-resources][glib-compile-resources] program * The `GResource` API and the
* provide a convenient and efficient alternative to this which has some nice properties. You * [`glib-compile-resources`](glib-compile-resources.html) program provide a
* maintain the files as normal files, so its easy to edit them, but during the build the files * convenient and efficient alternative to this which has some nice properties.
* are combined into a binary bundle that is linked into the executable. This means that loading * You maintain the files as normal files, so it’s easy to edit them, but during
* the resource files are efficient (as they are already in memory, shared with other instances) and * the build the files are combined into a binary bundle that is linked into the
* simple (no need to check for things like I/O errors or locate the files in the filesystem). It * executable. This means that loading the resource files are efficient (as they
* are already in memory, shared with other instances) and simple (no need to
* check for things like I/O errors or locate the files in the filesystem). It
* also makes it easier to create relocatable applications. * also makes it easier to create relocatable applications.
* *
* Resource files can also be marked as compressed. Such files will be included in the resource bundle * Resource files can also be marked as compressed. Such files will be included
* in a compressed form, but will be automatically uncompressed when the resource is used. This * in the resource bundle in a compressed form, but will be automatically
* is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. * uncompressed when the resource is used. This is very useful e.g. for larger
* text files that are parsed once (or rarely) and then thrown away.
* *
* Resource files can also be marked to be preprocessed, by setting the value of the * Resource files can also be marked to be preprocessed, by setting the value of the
* `preprocess` attribute to a comma-separated list of preprocessing options. * `preprocess` attribute to a comma-separated list of preprocessing options.
* The only options currently supported are: * The only options currently supported are:
* *
* `xml-stripblanks` which will use the xmllint command * - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command
* to strip ignorable whitespace from the XML file. For this to work, * to strip ignorable whitespace from the XML file. For this to work,
* the `XMLLINT` environment variable must be set to the full path to * the `XMLLINT` environment variable must be set to the full path to
* the xmllint executable, or xmllint must be in the `PATH`; otherwise * the xmllint executable, or xmllint must be in the `PATH`; otherwise
* the preprocessing step is skipped. * the preprocessing step is skipped.
* *
* `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the * - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
* `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format, * `gdk-pixbuf-pixdata` command to convert images to the [class@Gdk.Pixdata]
* which allows you to create pixbufs directly using the data inside the * format, which allows you to create pixbufs directly using the data inside
* resource file, rather than an (uncompressed) copy of it. For this, the * the resource file, rather than an (uncompressed) copy of it. For this, the
* `gdk-pixbuf-pixdata` program must be in the `PATH`, or the * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
* `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to
* `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. * the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will
* `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource * abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as
* supports embedding modern image formats just as well. Instead of using it, * `GResource` supports embedding modern image formats just as well. Instead
* embed a PNG or SVG file in your #GResource. * of using it, embed a PNG or SVG file in your `GResource`.
* *
* `json-stripblanks` which will use the `json-glib-format` command to strip * - `json-stripblanks` which will use the
* ignorable whitespace from the JSON file. For this to work, the * [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable
* `JSON_GLIB_FORMAT` environment variable must be set to the full path to the * whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT`
* `json-glib-format` executable, or it must be in the `PATH`; * environment variable must be set to the full path to the
* otherwise the preprocessing step is skipped. In addition, at least version * `json-glib-format` executable, or it must be in the `PATH`; otherwise the
* 1.6 of `json-glib-format` is required. * preprocessing step is skipped. In addition, at least version 1.6 of
* `json-glib-format` is required.
* *
* Resource files will be exported in the GResource namespace using the * Resource files will be exported in the `GResource` namespace using the
* combination of the given `prefix` and the filename from the `file` element. * combination of the given `prefix` and the filename from the `file` element.
* The `alias` attribute can be used to alter the filename to expose them at a * The `alias` attribute can be used to alter the filename to expose them at a
* different location in the resource namespace. Typically, this is used to * different location in the resource namespace. Typically, this is used to
* include files from a different source directory without exposing the source * include files from a different source directory without exposing the source
* directory in the resource namespace, as in the example below. * directory in the resource namespace, as in the example below.
* *
* Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program * Resource bundles are created by the
* which takes an XML file that describes the bundle, and a set of files that the XML references. These * [`glib-compile-resources`](glib-compile-resources.html) program
* are combined into a binary resource bundle. * which takes an XML file that describes the bundle, and a set of files that
* the XML references. These are combined into a binary resource bundle.
* *
* An example resource description: * An example resource description:
* |[ * ```xml
* <?xml version="1.0" encoding="UTF-8"?> * <?xml version="1.0" encoding="UTF-8"?>
* <gresources> * <gresources>
* <gresource prefix="/org/gtk/Example"> * <gresource prefix="/org/gtk/Example">
@ -120,74 +123,92 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref)
* <file alias="example.css">data/example.css</file> * <file alias="example.css">data/example.css</file>
* </gresource> * </gresource>
* </gresources> * </gresources>
* ]| * ```
* *
* This will create a resource bundle with the following files: * This will create a resource bundle with the following files:
* |[ * ```
* /org/gtk/Example/data/splashscreen.png * /org/gtk/Example/data/splashscreen.png
* /org/gtk/Example/dialog.ui * /org/gtk/Example/dialog.ui
* /org/gtk/Example/menumarkup.xml * /org/gtk/Example/menumarkup.xml
* /org/gtk/Example/example.css * /org/gtk/Example/example.css
* ]| * ```
* *
* Note that all resources in the process share the same namespace, so use Java-style * Note that all resources in the process share the same namespace, so use
* path prefixes (like in the above example) to avoid conflicts. * Java-style path prefixes (like in the above example) to avoid conflicts.
* *
* You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a * You can then use [`glib-compile-resources`](glib-compile-resources.html) to
* binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and * compile the XML to a binary bundle that you can load with
* --generate-header arguments to create a source file and header to link directly into your application. * [func@Gio.Resource.load]. However, it’s more common to use the
* `--generate-source` and `--generate-header` arguments to create a source file
* and header to link directly into your application.
* This will generate `get_resource()`, `register_resource()` and * This will generate `get_resource()`, `register_resource()` and
* `unregister_resource()` functions, prefixed by the `--c-name` argument passed * `unregister_resource()` functions, prefixed by the `--c-name` argument passed
* to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns * to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()`
* the generated #GResource object. The register and unregister functions * returns the generated `GResource` object. The register and unregister
* register the resource so its files can be accessed using * functions register the resource so its files can be accessed using
* g_resources_lookup_data(). * [func@Gio.resources_lookup_data].
* *
* Once a #GResource has been created and registered all the data in it can be accessed globally in the process by * Once a `GResource` has been created and registered all the data in it can be
* using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer * accessed globally in the process by using API calls like
* to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access * [func@Gio.resources_open_stream] to stream the data or
* the resource data. * [func@Gio.resources_lookup_data] to get a direct pointer to the data. You can
* also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with
* [iface@Gio.File] to access the resource data.
* *
* Some higher-level APIs, such as #GtkApplication, will automatically load * Some higher-level APIs, such as [class@Gtk.Application], will automatically
* resources from certain well-known paths in the resource namespace as a * load resources from certain well-known paths in the resource namespace as a
* convenience. See the documentation for those APIs for details. * convenience. See the documentation for those APIs for details.
* *
* There are two forms of the generated source, the default version uses the compiler support for constructor * There are two forms of the generated source, the default version uses the
* and destructor functions (where available) to automatically create and register the #GResource on startup * compiler support for constructor and destructor functions (where available)
* or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created * to automatically create and register the `GResource` on startup or library
* instead. This requires an explicit initialization call in your application/library, but it works on all platforms, * load time. If you pass `--manual-register`, two functions to
* even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) * register/unregister the resource are created instead. This requires an
* explicit initialization call in your application/library, but it works on all
* platforms, even on the minor ones where constructors are not supported.
* (Constructor support is available for at least Win32, Mac OS and Linux.)
* *
* Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries * Note that resource data can point directly into the data segment of e.g. a
* during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away * library, so if you are unloading libraries during runtime you need to be very
* when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses * careful with keeping around pointers to data from a resource, as this goes
* are for your own resources, and resource data is often used once, during parsing, and then released. * away when the library is unloaded. However, in practice this is not generally
* a problem, since most resource accesses are for your own resources, and
* resource data is often used once, during parsing, and then released.
* *
* When debugging a program or testing a change to an installed version, it is often useful to be able to * # Overlays
* replace resources in the program or library, without recompiling, for debugging or quick hacking and testing *
* purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay * When debugging a program or testing a change to an installed version, it is
* resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform * often useful to be able to replace resources in the program or library,
* during resource lookups. It is ignored when running in a setuid process. * without recompiling, for debugging or quick hacking and testing purposes.
* Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment
* variable to selectively overlay resources with replacements from the
* filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions
* to perform during resource lookups. It is ignored when running in a setuid
* process.
* *
* A substitution has the form * A substitution has the form
* *
* |[ * ```
* /org/gtk/libgtk=/home/desrt/gtk-overlay * /org/gtk/libgtk=/home/desrt/gtk-overlay
* ]| * ```
* *
* The part before the `=` is the resource subpath for which the overlay applies. The part after is a * The part before the `=` is the resource subpath for which the overlay
* filesystem path which contains files and subdirectories as you would like to be loaded as resources with the * applies. The part after is a filesystem path which contains files and
* subdirectories as you would like to be loaded as resources with the
* equivalent names. * equivalent names.
* *
* In the example above, if an application tried to load a resource with the resource path * In the example above, if an application tried to load a resource with the
* `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path * resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check
* `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an * the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was
* overlay, not an outright replacement, which means that if a file is not found at that path, the built-in * found there, it would be used instead. This is an overlay, not an outright
* version will be used instead. Whiteouts are not currently supported. * replacement, which means that if a file is not found at that path, the
* built-in version will be used instead. Whiteouts are not currently
* supported.
* *
* Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after * Substitutions must start with a slash, and must not contain a trailing slash
* the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the * before the `=`. The path after the slash should ideally be absolute, but
* location of a single resource with an individual file. * this is not strictly required. It is possible to overlay the location of a
* single resource with an individual file.
* *
* Since: 2.32 * Since: 2.32
*/ */

22
gio/gsimpleaction.c
View File

@ -26,25 +26,15 @@
#include "gaction.h" #include "gaction.h"
#include "glibintl.h" #include "glibintl.h"
/**
* SECTION:gsimpleaction
* @title: GSimpleAction
* @short_description: A simple GAction implementation
* @include: gio/gio.h
*
* A #GSimpleAction is the obvious simple implementation of the #GAction
* interface. This is the easiest way to create an action for purposes of
* adding it to a #GSimpleActionGroup.
*
* See also #GtkAction.
*/
/** /**
* GSimpleAction: * GSimpleAction:
* *
* #GSimpleAction is an opaque data structure and can only be accessed * A `GSimpleAction` is the obvious simple implementation of the
* using the following functions. * [iface@Gio.Action] interface. This is the easiest way to create an action for
**/ * purposes of adding it to a [class@Gio.SimpleActionGroup].
*
* See also [class@Gtk.Action].
*/
struct _GSimpleAction struct _GSimpleAction
{ {

12
gio/gsimpleactiongroup.c
View File

@ -28,13 +28,13 @@
#include "gaction.h" #include "gaction.h"
/** /**
* SECTION:gsimpleactiongroup * GSimpleActionGroup:
* @title: GSimpleActionGroup
* @short_description: A simple GActionGroup implementation
* @include: gio/gio.h
* *
* #GSimpleActionGroup is a hash table filled with #GAction objects, * `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects,
* implementing the #GActionGroup and #GActionMap interfaces. * implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap]
* interfaces.
*
* Since: 2.28
**/ **/
struct _GSimpleActionGroupPrivate struct _GSimpleActionGroupPrivate

7
gio/gsimpleactiongroup.h
View File

@ -46,13 +46,6 @@ G_BEGIN_DECLS
typedef struct _GSimpleActionGroupPrivate GSimpleActionGroupPrivate; typedef struct _GSimpleActionGroupPrivate GSimpleActionGroupPrivate;
typedef struct _GSimpleActionGroupClass GSimpleActionGroupClass; typedef struct _GSimpleActionGroupClass GSimpleActionGroupClass;
/**
* GSimpleActionGroup:
*
* The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API.
*
* Since: 2.28
*/
struct _GSimpleActionGroup struct _GSimpleActionGroup
{ {
/*< private >*/ /*< private >*/

28
gio/gsrvtarget.c
View File

@ -31,24 +31,24 @@
/** /**
* SECTION:gsrvtarget * GSrvTarget:
* @short_description: DNS SRV record target *
* @include: gio/gio.h * A single target host/port that a network service is running on.
* *
* SRV (service) records are used by some network protocols to provide * SRV (service) records are used by some network protocols to provide
* service-specific aliasing and load-balancing. For example, XMPP * service-specific aliasing and load-balancing. For example, XMPP
* (Jabber) uses SRV records to locate the XMPP server for a domain; * (Jabber) uses SRV records to locate the XMPP server for a domain;
* rather than connecting directly to "example.com" or assuming a * rather than connecting directly to ‘example.com’ or assuming a
* specific server hostname like "xmpp.example.com", an XMPP client * specific server hostname like ‘xmpp.example.com’, an XMPP client
* would look up the "xmpp-client" SRV record for "example.com", and * would look up the `xmpp-client` SRV record for ‘example.com’, and
* then connect to whatever host was pointed to by that record. * then connect to whatever host was pointed to by that record.
* *
* You can use g_resolver_lookup_service() or * You can use [method@Gio.Resolver.lookup_service] or
* g_resolver_lookup_service_async() to find the #GSrvTargets * [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s
* for a given service. However, if you are simply planning to connect * for a given service. However, if you are simply planning to connect
* to the remote service, you can use #GNetworkService's * to the remote service, you can use [class@Gio.NetworkService]’s
* #GSocketConnectable interface and not need to worry about * [iface@Gio.SocketConnectable] interface and not need to worry about
* #GSrvTarget at all. * `GSrvTarget` at all.
*/ */
struct _GSrvTarget { struct _GSrvTarget {
@ -59,12 +59,6 @@ struct _GSrvTarget {
guint16 weight; guint16 weight;
}; };
/**
* GSrvTarget:
*
* A single target host/port that a network service is running on.
*/
G_DEFINE_BOXED_TYPE (GSrvTarget, g_srv_target, G_DEFINE_BOXED_TYPE (GSrvTarget, g_srv_target,
g_srv_target_copy, g_srv_target_free) g_srv_target_copy, g_srv_target_free)

7
gio/gsubprocesslauncher.c
View File

@ -17,16 +17,13 @@
*/ */
/** /**
* SECTION:gsubprocesslauncher * GSubprocessLauncher:
* @title: GSubprocess Launcher
* @short_description: Environment options for launching a child process
* @include: gio/gio.h
* *
* This class contains a set of options for launching child processes, * This class contains a set of options for launching child processes,
* such as where its standard input and output will be directed, the * such as where its standard input and output will be directed, the
* argument list, the environment, and more. * argument list, the environment, and more.
* *
* While the #GSubprocess class has high level functions covering * While the [class@Gio.Subprocess] class has high level functions covering
* popular cases, use of this class allows access to more advanced * popular cases, use of this class allows access to more advanced
* options. It can also be used to launch multiple subprocesses with * options. It can also be used to launch multiple subprocesses with
* a similar configuration. * a similar configuration.

8
gio/gtcpconnection.c
View File

@ -13,13 +13,9 @@
*/ */
/** /**
* SECTION:gtcpconnection * GTcpConnection:
* @title: GTcpConnection
* @short_description: A TCP GSocketConnection
* @include: gio/gio.h
* @see_also: #GSocketConnection.
* *
* This is the subclass of #GSocketConnection that is created * This is the subclass of [class@Gio.SocketConnection] that is created
* for TCP/IP sockets. * for TCP/IP sockets.
* *
* Since: 2.22 * Since: 2.22

25
gio/gtcpwrapperconnection.c
View File

@ -21,29 +21,18 @@
*/ */
/** /**
* SECTION:gtcpwrapperconnection * GTcpWrapperConnection:
* @title: GTcpWrapperConnection
* @short_description: Wrapper for non-GSocketConnection-based,
* GSocket-based GIOStreams
* @include: gio/gio.h
* @see_also: #GSocketConnection.
* *
* A #GTcpWrapperConnection can be used to wrap a #GIOStream that is * A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is
* based on a #GSocket, but which is not actually a * based on a [class@Gio.Socket], but which is not actually a
* #GSocketConnection. This is used by #GSocketClient so that it can * [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so
* always return a #GSocketConnection, even when the connection it has * that it can always return a [class@Gio.SocketConnection], even when the
* actually created is not directly a #GSocketConnection. * connection it has actually created is not directly a
* [class@Gio.SocketConnection].
* *
* Since: 2.28 * Since: 2.28
*/ */
/**
* GTcpWrapperConnection:
*
* #GTcpWrapperConnection is an opaque data structure and can only be accessed
* using the following functions.
**/
#include "config.h" #include "config.h"
#include "gtcpwrapperconnection.h" #include "gtcpwrapperconnection.h"

81
gio/gtestdbus.c
View File

@ -333,25 +333,23 @@ _g_test_watcher_remove_pid (GPid pid)
/* GTestDBus object implementation */ /* GTestDBus object implementation */
/** /**
* SECTION:gtestdbus * GTestDBus:
* @short_description: D-Bus testing helper
* @include: gio/gio.h
* *
* A helper class for testing code which uses D-Bus without touching the user's * A helper class for testing code which uses D-Bus without touching the user’s
* session bus. * session bus.
* *
* Note that #GTestDBus modifies the user’s environment, calling setenv(). * Note that `GTestDBus` modifies the user’s environment, calling
* This is not thread-safe, so all #GTestDBus calls should be completed before * [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus`
* threads are spawned, or should have appropriate locking to ensure no access * calls should be completed before threads are spawned, or should have
* conflicts to environment variables shared between #GTestDBus and other * appropriate locking to ensure no access conflicts to environment variables
* threads. * shared between `GTestDBus` and other threads.
* *
* ## Creating unit tests using GTestDBus * ## Creating unit tests using `GTestDBus`
* *
* Testing of D-Bus services can be tricky because normally we only ever run * Testing of D-Bus services can be tricky because normally we only ever run
* D-Bus services over an existing instance of the D-Bus daemon thus we * D-Bus services over an existing instance of the D-Bus daemon thus we
* usually don't activate D-Bus services that are not yet installed into the * usually don’t activate D-Bus services that are not yet installed into the
* target system. The #GTestDBus object makes this easier for us by taking care * target system. The `GTestDBus` object makes this easier for us by taking care
* of the lower level tasks such as running a private D-Bus daemon and looking * of the lower level tasks such as running a private D-Bus daemon and looking
* up uninstalled services in customizable locations, typically in your source * up uninstalled services in customizable locations, typically in your source
* code tree. * code tree.
@ -364,20 +362,24 @@ _g_test_watcher_remove_pid (GPid pid)
* uninstalled service executable in your source tree. Using autotools we would * uninstalled service executable in your source tree. Using autotools we would
* achieve this by adding a file such as `my-server.service.in` in the services * achieve this by adding a file such as `my-server.service.in` in the services
* directory and have it processed by configure. * directory and have it processed by configure.
* |[ *
* [D-BUS Service] * ```
* Name=org.gtk.GDBus.Examples.ObjectManager * [D-BUS Service]
* Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server * Name=org.gtk.GDBus.Examples.ObjectManager
* ]| * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
* ```
*
* You will also need to indicate this service directory in your test * You will also need to indicate this service directory in your test
* fixtures, so you will need to pass the path while compiling your * fixtures, so you will need to pass the path while compiling your
* test cases. Typically this is done with autotools with an added * test cases. Typically this is done with autotools with an added
* preprocessor flag specified to compile your tests such as: * preprocessor flag specified to compile your tests such as:
* |[ *
* -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" * ```
* ]| * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
* Once you have a service definition file which is local to your source tree, * ```
* you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. *
* Once you have a service definition file which is local to your source tree,
* you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
* *
* An example of a test fixture for D-Bus services can be found * An example of a test fixture for D-Bus services can be found
* here: * here:
@ -386,42 +388,39 @@ _g_test_watcher_remove_pid (GPid pid)
* Note that these examples only deal with isolating the D-Bus aspect of your * Note that these examples only deal with isolating the D-Bus aspect of your
* service. To successfully run isolated unit tests on your service you may need * service. To successfully run isolated unit tests on your service you may need
* some additional modifications to your test case fixture. For example; if your * some additional modifications to your test case fixture. For example; if your
* service uses GSettings and installs a schema then it is important that your test service * service uses [class@Gio.Settings] and installs a schema then it is important
* not load the schema in the ordinary installed location (chances are that your service * that your test service not load the schema in the ordinary installed location
* and schema files are not yet installed, or worse; there is an older version of the * (chances are that your service and schema files are not yet installed, or
* schema file sitting in the install location). * worse; there is an older version of the schema file sitting in the install
* location).
* *
* Most of the time we can work around these obstacles using the * Most of the time we can work around these obstacles using the
* environment. Since the environment is inherited by the D-Bus daemon * environment. Since the environment is inherited by the D-Bus daemon
* created by #GTestDBus and then in turn inherited by any services the * created by `GTestDBus` and then in turn inherited by any services the
* D-Bus daemon activates, using the setup routine for your fixture is * D-Bus daemon activates, using the setup routine for your fixture is
* a practical place to help sandbox your runtime environment. For the * a practical place to help sandbox your runtime environment. For the
* rather typical GSettings case we can work around this by setting * rather typical GSettings case we can work around this by setting
* `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
* in the above fixture_setup() routine. * in the above `fixture_setup()` routine.
* *
* The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved * The GSettings schemas need to be locally pre-compiled for this to work. This
* by compiling the schemas locally as a step before running test cases, an autotools setup might * can be achieved by compiling the schemas locally as a step before running
* do the following in the directory holding schemas: * test cases, an autotools setup might do the following in the directory
* |[ * holding schemas:
*
* ```
* all-am: * all-am:
* $(GLIB_COMPILE_SCHEMAS) . * $(GLIB_COMPILE_SCHEMAS) .
* *
* CLEANFILES += gschemas.compiled * CLEANFILES += gschemas.compiled
* ]| * ```
*
* Since: 2.34
*/ */
typedef struct _GTestDBusClass GTestDBusClass; typedef struct _GTestDBusClass GTestDBusClass;
typedef struct _GTestDBusPrivate GTestDBusPrivate; typedef struct _GTestDBusPrivate GTestDBusPrivate;
/**
* GTestDBus:
*
* The #GTestDBus structure contains only private data and
* should only be accessed using the provided API.
*
* Since: 2.34
*/
struct _GTestDBus { struct _GTestDBus {
GObject parent; GObject parent;

15
gio/gthemedicon.c
View File

@ -31,16 +31,15 @@
/** /**
* SECTION:gthemedicon * GThemedIcon:
* @short_description: Icon theming support
* @include: gio/gio.h
* @see_also: #GIcon, #GLoadableIcon
* *
* #GThemedIcon is an implementation of #GIcon that supports icon themes. * `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon
* #GThemedIcon contains a list of all of the icons present in an icon * themes.
* theme, so that icons can be looked up quickly. #GThemedIcon does *
* `GThemedIcon` contains a list of all of the icons present in an icon
* theme, so that icons can be looked up quickly. `GThemedIcon` does
* not provide actual pixmaps for icons, just the icon names. * not provide actual pixmaps for icons, just the icon names.
* Ideally something like gtk_icon_theme_choose_icon() should be used to * Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to
* resolve the list of names so that fallback icons work nicely with * resolve the list of names so that fallback icons work nicely with
* themes that inherit other themes. * themes that inherit other themes.
**/ **/

5
gio/gthemedicon.h
View File

@ -38,11 +38,6 @@ G_BEGIN_DECLS
#define G_IS_THEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON)) #define G_IS_THEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON))
#define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass)) #define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass))
/**
* GThemedIcon:
*
* An implementation of #GIcon for themed icons.
**/
typedef struct _GThemedIconClass GThemedIconClass; typedef struct _GThemedIconClass GThemedIconClass;
GIO_AVAILABLE_IN_ALL GIO_AVAILABLE_IN_ALL

19
gio/gthreadedsocketservice.c
View File

@ -23,27 +23,24 @@
*/ */
/** /**
* SECTION:gthreadedsocketservice * GThreadedSocketService:
* @title: GThreadedSocketService
* @short_description: A threaded GSocketService
* @include: gio/gio.h
* @see_also: #GSocketService.
* *
* A #GThreadedSocketService is a simple subclass of #GSocketService * A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService]
* that handles incoming connections by creating a worker thread and * that handles incoming connections by creating a worker thread and
* dispatching the connection to it by emitting the * dispatching the connection to it by emitting the
* #GThreadedSocketService::run signal in the new thread. * [signal@Gio.ThreadedSocketService::run signal] in the new thread.
* *
* The signal handler may perform blocking IO and need not return * The signal handler may perform blocking I/O and need not return
* until the connection is closed. * until the connection is closed.
* *
* The service is implemented using a thread pool, so there is a * The service is implemented using a thread pool, so there is a
* limited amount of threads available to serve incoming requests. * limited amount of threads available to serve incoming requests.
* The service automatically stops the #GSocketService from accepting * The service automatically stops the [class@Gio.SocketService] from accepting
* new connections when all threads are busy. * new connections when all threads are busy.
* *
* As with #GSocketService, you may connect to #GThreadedSocketService::run, * As with [class@Gio.SocketService], you may connect to
* or subclass and override the default handler. * [signal@Gio.ThreadedSocketService::run], or subclass and override the default
* handler.
*/ */
#include "config.h" #include "config.h"

16
gio/gtlsfiledatabase.c
View File

@ -30,25 +30,15 @@
#include "glibintl.h" #include "glibintl.h"
/** /**
* SECTION:gtlsfiledatabase * GTlsFileDatabase:
* @short_description: TLS file based database type
* @include: gio/gio.h
* *
* #GTlsFileDatabase is implemented by #GTlsDatabase objects which load * `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which
* their certificate information from a file. It is an interface which * load their certificate information from a file. It is an interface which
* TLS library specific subtypes implement. * TLS library specific subtypes implement.
* *
* Since: 2.30 * Since: 2.30
*/ */
/**
* GTlsFileDatabase:
*
* Implemented by a #GTlsDatabase which allows you to load certificates
* from a file.
*
* Since: 2.30
*/
G_DEFINE_INTERFACE (GTlsFileDatabase, g_tls_file_database, G_TYPE_TLS_DATABASE) G_DEFINE_INTERFACE (GTlsFileDatabase, g_tls_file_database, G_TYPE_TLS_DATABASE)
static void static void

25
gio/gtlsinteraction.c
View File

@ -36,37 +36,28 @@
/** /**
* SECTION:gtlsinteraction * GTlsInteraction:
* @short_description: Interaction with the user during TLS operations.
* @include: gio/gio.h
* *
* #GTlsInteraction provides a mechanism for the TLS connection and database * `GTlsInteraction` provides a mechanism for the TLS connection and database
* code to interact with the user. It can be used to ask the user for passwords. * code to interact with the user. It can be used to ask the user for passwords.
* *
* To use a #GTlsInteraction with a TLS connection use * To use a `GTlsInteraction` with a TLS connection use
* g_tls_connection_set_interaction(). * [method@Gio.TlsConnection.set_interaction].
* *
* Callers should instantiate a derived class that implements the various * Callers should instantiate a derived class that implements the various
* interaction methods to show the required dialogs. * interaction methods to show the required dialogs.
* *
* Callers should use the 'invoke' functions like * Callers should use the 'invoke' functions like
* g_tls_interaction_invoke_ask_password() to run interaction methods. These * [method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods.
* functions make sure that the interaction is invoked in the main loop * These functions make sure that the interaction is invoked in the main loop
* and not in the current thread, if the current thread is not running the * and not in the current thread, if the current thread is not running the
* main loop. * main loop.
* *
* Derived classes can choose to implement whichever interactions methods they'd * Derived classes can choose to implement whichever interactions methods they’d
* like to support by overriding those virtual methods in their class * like to support by overriding those virtual methods in their class
* initialization function. Any interactions not implemented will return * initialization function. Any interactions not implemented will return
* %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, * `G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method,
* it must also implement the corresponding finish method. * it must also implement the corresponding finish method.
*/
/**
* GTlsInteraction:
*
* An object representing interaction that the TLS connection and database
* might have with the user.
* *
* Since: 2.30 * Since: 2.30
*/ */

9
gio/gtlspassword.c
View File

@ -29,15 +29,6 @@
#include <string.h> #include <string.h>
/**
* SECTION:gtlspassword
* @title: GTlsPassword
* @short_description: TLS Passwords for prompting
* @include: gio/gio.h
*
* Holds a password used in TLS.
*/
/** /**
* GTlsPassword: * GTlsPassword:
* *

22
gio/gunixfdlist.c
View File

@ -15,18 +15,15 @@
*/ */
/** /**
* SECTION:gunixfdlist * GUnixFDList:
* @title: GUnixFDList
* @short_description: An object containing a set of UNIX file descriptors
* @include: gio/gunixfdlist.h
* @see_also: #GUnixFDMessage
* *
* A #GUnixFDList contains a list of file descriptors. It owns the file * A `GUnixFDList` contains a list of file descriptors. It owns the file
* descriptors that it contains, closing them when finalized. * descriptors that it contains, closing them when finalized.
* *
* It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in * It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a
* the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() * [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using
* and received using g_socket_receive_message(). * [method@Gio.Socket.send_message] and received using
* [method@Gio.Socket.receive_message].
* *
* Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO * Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO
* interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when * interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when
@ -35,13 +32,6 @@
* Since 2.74, the API is available for Windows. * Since 2.74, the API is available for Windows.
*/ */
/**
* GUnixFDList:
*
* #GUnixFDList is an opaque data structure and can only be accessed
* using the following functions.
**/
#include "config.h" #include "config.h"
#include <fcntl.h> #include <fcntl.h>