as a strong reference or owner of aGInputStream
instance.GInputStream
has functions to read from a stream (g_input_stream_read()
), to close a stream (g_input_stream_close()
) and to skip some content (g_input_stream_skip()
).To copy the content of an input stream to an output stream without manually handling the reads and writes, use
g_output_stream_splice()
.See the documentation for
GIOStream
for details of thread safety of streaming APIs.All of these functions have async variants too.
See moreDeclaration
Swift
open class InputStream : Object, InputStreamProtocol
-
The
ListStore
type acts as a reference-counted owner of an underlyingGListStore
instance. It provides the methods that can operate on this data type throughListStoreProtocol
conformance. UseListStore
as a strong reference or owner of aGListStore
instance.GListStore
is a simple implementation ofGListModel
that stores all items in memory.It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly.
See moreDeclaration
Swift
open class ListStore : Object, ListStoreProtocol
-
The
Initable
type acts as an owner of an underlyingGInitable
instance. It provides the methods that can operate on this data type throughInitableProtocol
conformance. UseInitable
as a strong reference or owner of aGInitable
instance.GInitable
is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, either viag_initable_init()
org_async_initable_init_async()
(the latter is only available if it also implementsGAsyncInitable
).If the object is not initialized, or initialization returns with an error, then all operations on the object except
g_object_ref()
andg_object_unref()
are considered to be invalid, and have undefined behaviour. They will often fail withg_critical()
org_warning()
, but this must not be relied on.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_initable_new()
directly, or indirectly via afoo_thing_new()
wrapper. This will callg_initable_init()
under the cover, returningnil
and setting aGError
on failure (at which point the instance is unreferenced).For bindings in languages where the native constructor supports exceptions the binding could check for objects implemention
See moreGInitable
during normal construction and automatically initialize them, throwing an exception on failure.Declaration
Swift
open class Initable : InitableProtocol
-
The
ListModel
type acts as an owner of an underlyingGListModel
instance. It provides the methods that can operate on this data type throughListModelProtocol
conformance. UseListModel
as a strong reference or owner of aGListModel
instance.GListModel
is an interface that represents a mutable list ofGObjects
. Its main intention is as a model for various widgets in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates.Each object in the list may also report changes in itself via some mechanism (normally the
GObject::notify
signal). Taken together with theGListModel::items
-changed signal, this provides for a list that can change its membership, and in which the members can change their individual properties.A good example would be the list of visible wireless network access points, where each access point can report dynamic properties such as signal strength.
It is important to note that the
GListModel
itself does not report changes to the individual items. It only reports changes to the list membership. If you want to observe changes to the objects themselves then you need to connect signals to the objects that you are interested in.All items in a
GListModel
are of (or derived from) the same type.g_list_model_get_item_type()
returns that type. The type may be an interface, in which case all objects in the list must implement it.The semantics are close to that of an array:
g_list_model_get_n_items()
returns the number of items in the list andg_list_model_get_item()
returns an item at a (0-based) position. In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly callg_list_model_get_item()
until it returnsnil
.An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone.
On the other side, a consumer is expected only to hold references on objects that are currently “user visible”, in order to faciliate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time.
This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns the thread-default main context in effect at the time that the model was created.
See moreDeclaration
Swift
open class ListModel : ListModelProtocol
-
The
See moreListStoreClass
type acts as an owner of an underlyingGListStoreClass
instance. It provides the methods that can operate on this data type throughListStoreClassProtocol
conformance. UseListStoreClass
as a strong reference or owner of aGListStoreClass
instance.Declaration
Swift
open class ListStoreClass : ListStoreClassProtocol
-
The
LoadableIconIface
type acts as an owner of an underlyingGLoadableIconIface
instance. It provides the methods that can operate on this data type throughLoadableIconIfaceProtocol
conformance. UseLoadableIconIface
as a strong reference or owner of aGLoadableIconIface
instance.Interface for icons that can be loaded as a stream.
See moreDeclaration
Swift
open class LoadableIconIface : LoadableIconIfaceProtocol
-
The
See moreMemoryInputStreamClass
type acts as an owner of an underlyingGMemoryInputStreamClass
instance. It provides the methods that can operate on this data type throughMemoryInputStreamClassProtocol
conformance. UseMemoryInputStreamClass
as a strong reference or owner of aGMemoryInputStreamClass
instance.Declaration
Swift
open class MemoryInputStreamClass : MemoryInputStreamClassProtocol
-
The
LoadableIcon
type acts as an owner of an underlyingGLoadableIcon
instance. It provides the methods that can operate on this data type throughLoadableIconProtocol
conformance. UseLoadableIcon
as a strong reference or owner of aGLoadableIcon
instance.Extends the
See moreGIcon
interface and adds the ability to load icons from streams.Declaration
Swift
open class LoadableIcon : Icon, LoadableIconProtocol
-
The
MemoryMonitor
type acts as an owner of an underlyingGMemoryMonitor
instance. It provides the methods that can operate on this data type throughMemoryMonitorProtocol
conformance. UseMemoryMonitor
as a strong reference or owner of aGMemoryMonitor
instance.GMemoryMonitor
will monitor system memory and suggest to the application when to free memory so as to leave more room for other applications. It is implemented on Linux using the Low Memory Monitor (API documentation).There is also an implementation for use inside Flatpak sandboxes.
Possible actions to take when the signal is received are:
- Free caches
- Save files that haven’t been looked at in a while to disk, ready to be reopened when needed
- Run a garbage collection cycle
- Try and compress fragmented allocations
- Exit on idle if the process has no reason to stay around
See
GMemoryMonitorWarningLevel
for details on the various warning levels.(C Language Example):
static void warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) { g_debug ("Warning level: %d", level); if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) drop_caches (); } static GMemoryMonitor * monitor_low_memory (void) { GMemoryMonitor *m; m = g_memory_monitor_dup_default (); g_signal_connect (G_OBJECT (m), "low-memory-warning", G_CALLBACK (warning_cb), NULL); return m; }
Don’t forget to disconnect the
See moreGMemoryMonitor::low
-memory-warning signal, and unref theGMemoryMonitor
itself when exiting.Declaration
Swift
open class MemoryMonitor : Initable, MemoryMonitorProtocol
-
The
MemoryInputStream
type acts as a reference-counted owner of an underlyingGMemoryInputStream
instance. It provides the methods that can operate on this data type throughMemoryInputStreamProtocol
conformance. UseMemoryInputStream
as a strong reference or owner of aGMemoryInputStream
instance.GMemoryInputStream
is a class for using arbitrary memory chunks as input for GIO streaming input operations.As of GLib 2.34,
See moreGMemoryInputStream
implementsGPollableInputStream
.Declaration
Swift
open class MemoryInputStream : InputStream, MemoryInputStreamProtocol
-
The
MemoryOutputStream
type acts as a reference-counted owner of an underlyingGMemoryOutputStream
instance. It provides the methods that can operate on this data type throughMemoryOutputStreamProtocol
conformance. UseMemoryOutputStream
as a strong reference or owner of aGMemoryOutputStream
instance.GMemoryOutputStream
is a class for using arbitrary memory chunks as output for GIO streaming output operations.As of GLib 2.34,
See moreGMemoryOutputStream
trivially implementsGPollableOutputStream:
it always polls as ready.Declaration
Swift
open class MemoryOutputStream : OutputStream, MemoryOutputStreamProtocol
-
The
Menu
type acts as a reference-counted owner of an underlyingGMenu
instance. It provides the methods that can operate on this data type throughMenuProtocol
conformance. UseMenu
as a strong reference or owner of aGMenu
instance.GMenu
is a simple implementation ofGMenuModel
. You populate aGMenu
by addingGMenuItem
instances to it.There are some convenience functions to allow you to directly add items (avoiding
See moreGMenuItem
) for the common cases. To add a regular item, useg_menu_insert()
. To add a section, useg_menu_insert_section()
. To add a submenu, useg_menu_insert_submenu()
.Declaration
Swift
open class Menu : MenuModel, MenuProtocol
-
The
MenuAttributeIter
type acts as a reference-counted owner of an underlyingGMenuAttributeIter
instance. It provides the methods that can operate on this data type throughMenuAttributeIterProtocol
conformance. UseMenuAttributeIter
as a strong reference or owner of aGMenuAttributeIter
instance.
See moreGMenuAttributeIter
is an opaque structure type. You must access it using the functions below.Declaration
Swift
open class MenuAttributeIter : Object, MenuAttributeIterProtocol
-
The
MenuItem
type acts as a reference-counted owner of an underlyingGMenuItem
instance. It provides the methods that can operate on this data type throughMenuItemProtocol
conformance. UseMenuItem
as a strong reference or owner of aGMenuItem
instance.
See moreGMenuItem
is an opaque structure type. You must access it using the functions below.Declaration
Swift
open class MenuItem : Object, MenuItemProtocol
-
The
MenuLinkIter
type acts as a reference-counted owner of an underlyingGMenuLinkIter
instance. It provides the methods that can operate on this data type throughMenuLinkIterProtocol
conformance. UseMenuLinkIter
as a strong reference or owner of aGMenuLinkIter
instance.
See moreGMenuLinkIter
is an opaque structure type. You must access it using the functions below.Declaration
Swift
open class MenuLinkIter : Object, MenuLinkIterProtocol
-
The
MenuModel
type acts as a reference-counted owner of an underlyingGMenuModel
instance. It provides the methods that can operate on this data type throughMenuModelProtocol
conformance. UseMenuModel
as a strong reference or owner of aGMenuModel
instance.GMenuModel
represents the contents of a menu – an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item.The conceptual model of menus in
GMenuModel
is hierarchical: sections and submenus are again represented byGMenuModels
. Menus themselves do not define their own roles. Rather, the role of a particularGMenuModel
is defined by the item that references it (or, in the case of the ‘root’ menu, is defined by the context in which it is used).As an example, consider the visible portions of this menu:
An example menu #
There are 8 “menus” visible in the screenshot: one menubar, two submenus and 5 sections:
- the toplevel menubar (containing 4 items)
- the View submenu (containing 3 sections)
- the first section of the View submenu (containing 2 items)
- the second section of the View submenu (containing 1 item)
- the final section of the View submenu (containing 1 item)
- the Highlight Mode submenu (containing 2 sections)
- the Sources section (containing 2 items)
- the Markup section (containing 2 items)
The example illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus.
A menu example #
Notice that the separators visible in the example appear nowhere in the menu model. This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, a display system may show a section header instead of a separator.
The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, dash boards, etc. To support such uses, it is necessary to ‘export’ information about actions and their representation in menus, which is exactly what the GActionGroup exporter and the GMenuModel exporter do for
GActionGroup
andGMenuModel
. The client-side counterparts to make use of the exported information areGDBusActionGroup
andGDBusMenuModel
.The API of
GMenuModel
is very generic, with iterators for the attributes and links of an item, seeg_menu_model_iterate_item_attributes()
andg_menu_model_iterate_item_links()
. The ‘standard’ attributes and link types have predefined names:G_MENU_ATTRIBUTE_LABEL
,G_MENU_ATTRIBUTE_ACTION
,G_MENU_ATTRIBUTE_TARGET
,G_MENU_LINK_SECTION
andG_MENU_LINK_SUBMENU
.Items in a
GMenuModel
represent active controls if they refer to an action that can get activated when the user interacts with the menu item. The reference to the action is encoded by the string id in theG_MENU_ATTRIBUTE_ACTION
attribute. An action id uniquely identifies an action in an action group. Which actiongroup(s)
provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of aGtkApplication
, actions can be application-wide or window-specific (and thus come from two different action groups). By convention, the application-wide actions have names that start with “app.”, while the names of window-specific actions start with “win.”.While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported menu information:
- an action with no parameter type and no state
- an action with no parameter type and boolean state
- an action with string parameter type and string state
Stateless
A stateless action typically corresponds to an ordinary menu item.
Selecting such a menu item will activate the action (with no parameter).
Boolean State
An action with a boolean state will most typically be used with a “toggle” or “switch” menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled.
Selecting a toggle menu item will activate the action. The menu item should be rendered as “checked” when the state is true.
String Parameter and State
Actions with string parameters and state will most typically be used to represent an enumerated choice over the items available for a group of radio menu items. Activating the action with a string parameter is equivalent to setting that parameter as the state.
Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should be rendered as “selected” when the state of the action is equal to the target value of the menu item.
See moreDeclaration
Swift
open class MenuModel : Object, MenuModelProtocol
-
The
MountOperation
type acts as a reference-counted owner of an underlyingGMountOperation
instance. It provides the methods that can operate on this data type throughMountOperationProtocol
conformance. UseMountOperation
as a strong reference or owner of aGMountOperation
instance.GMountOperation
provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing.Note that
GMountOperation
is used for more than justGMount
objects – for example it is also used ing_drive_start()
andg_drive_stop()
.Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as
GtkMountOperation
. If no user interaction is desired (for example when automounting filesystems at login time), usuallynil
can be passed, see each method taking aGMountOperation
for details.The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. TrueCrypt is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. VeraCrypt is a maintained fork of TrueCrypt with various improvements and auditing fixes.
See moreDeclaration
Swift
open class MountOperation : Object, MountOperationProtocol
-
The
NativeSocketAddress
type acts as a reference-counted owner of an underlyingGNativeSocketAddress
instance. It provides the methods that can operate on this data type throughNativeSocketAddressProtocol
conformance. UseNativeSocketAddress
as a strong reference or owner of aGNativeSocketAddress
instance.A socket address of some unknown native type.
See moreDeclaration
Swift
open class NativeSocketAddress : SocketAddress, NativeSocketAddressProtocol
-
The
See moreMemoryInputStreamPrivate
type acts as an owner of an underlyingGMemoryInputStreamPrivate
instance. It provides the methods that can operate on this data type throughMemoryInputStreamPrivateProtocol
conformance. UseMemoryInputStreamPrivate
as a strong reference or owner of aGMemoryInputStreamPrivate
instance.Declaration
Swift
open class MemoryInputStreamPrivate : MemoryInputStreamPrivateProtocol
-
The
MemoryMonitorInterface
type acts as an owner of an underlyingGMemoryMonitorInterface
instance. It provides the methods that can operate on this data type throughMemoryMonitorInterfaceProtocol
conformance. UseMemoryMonitorInterface
as a strong reference or owner of aGMemoryMonitorInterface
instance.The virtual function table for
See moreGMemoryMonitor
.Declaration
Swift
open class MemoryMonitorInterface : MemoryMonitorInterfaceProtocol
-
The
See moreMemoryOutputStreamClass
type acts as an owner of an underlyingGMemoryOutputStreamClass
instance. It provides the methods that can operate on this data type throughMemoryOutputStreamClassProtocol
conformance. UseMemoryOutputStreamClass
as a strong reference or owner of aGMemoryOutputStreamClass
instance.Declaration
Swift
open class MemoryOutputStreamClass : MemoryOutputStreamClassProtocol
-
The
See moreMemoryOutputStreamPrivate
type acts as an owner of an underlyingGMemoryOutputStreamPrivate
instance. It provides the methods that can operate on this data type throughMemoryOutputStreamPrivateProtocol
conformance. UseMemoryOutputStreamPrivate
as a strong reference or owner of aGMemoryOutputStreamPrivate
instance.Declaration
Swift
open class MemoryOutputStreamPrivate : MemoryOutputStreamPrivateProtocol
-
The
See moreMenuAttributeIterClass
type acts as an owner of an underlyingGMenuAttributeIterClass
instance. It provides the methods that can operate on this data type throughMenuAttributeIterClassProtocol
conformance. UseMenuAttributeIterClass
as a strong reference or owner of aGMenuAttributeIterClass
instance.Declaration
Swift
open class MenuAttributeIterClass : MenuAttributeIterClassProtocol
-
The
See moreMenuAttributeIterPrivate
type acts as an owner of an underlyingGMenuAttributeIterPrivate
instance. It provides the methods that can operate on this data type throughMenuAttributeIterPrivateProtocol
conformance. UseMenuAttributeIterPrivate
as a strong reference or owner of aGMenuAttributeIterPrivate
instance.Declaration
Swift
open class MenuAttributeIterPrivate : MenuAttributeIterPrivateProtocol
-
The
See moreMenuLinkIterClass
type acts as an owner of an underlyingGMenuLinkIterClass
instance. It provides the methods that can operate on this data type throughMenuLinkIterClassProtocol
conformance. UseMenuLinkIterClass
as a strong reference or owner of aGMenuLinkIterClass
instance.Declaration
Swift
open class MenuLinkIterClass : MenuLinkIterClassProtocol
-
The
See moreMenuLinkIterPrivate
type acts as an owner of an underlyingGMenuLinkIterPrivate
instance. It provides the methods that can operate on this data type throughMenuLinkIterPrivateProtocol
conformance. UseMenuLinkIterPrivate
as a strong reference or owner of aGMenuLinkIterPrivate
instance.Declaration
Swift
open class MenuLinkIterPrivate : MenuLinkIterPrivateProtocol
-
The
See moreMenuModelClass
type acts as an owner of an underlyingGMenuModelClass
instance. It provides the methods that can operate on this data type throughMenuModelClassProtocol
conformance. UseMenuModelClass
as a strong reference or owner of aGMenuModelClass
instance.Declaration
Swift
open class MenuModelClass : MenuModelClassProtocol
-
The
See moreMenuModelPrivate
type acts as an owner of an underlyingGMenuModelPrivate
instance. It provides the methods that can operate on this data type throughMenuModelPrivateProtocol
conformance. UseMenuModelPrivate
as a strong reference or owner of aGMenuModelPrivate
instance.Declaration
Swift
open class MenuModelPrivate : MenuModelPrivateProtocol
-
The
MountIface
type acts as an owner of an underlyingGMountIface
instance. It provides the methods that can operate on this data type throughMountIfaceProtocol
conformance. UseMountIface
as a strong reference or owner of aGMountIface
instance.Interface for implementing operations for mounts.
See moreDeclaration
Swift
open class MountIface : MountIfaceProtocol
-
The
See moreMountOperationClass
type acts as an owner of an underlyingGMountOperationClass
instance. It provides the methods that can operate on this data type throughMountOperationClassProtocol
conformance. UseMountOperationClass
as a strong reference or owner of aGMountOperationClass
instance.Declaration
Swift
open class MountOperationClass : MountOperationClassProtocol
-
The
See moreMountOperationPrivate
type acts as an owner of an underlyingGMountOperationPrivate
instance. It provides the methods that can operate on this data type throughMountOperationPrivateProtocol
conformance. UseMountOperationPrivate
as a strong reference or owner of aGMountOperationPrivate
instance.Declaration
Swift
open class MountOperationPrivate : MountOperationPrivateProtocol
-
The
See moreNativeSocketAddressClass
type acts as an owner of an underlyingGNativeSocketAddressClass
instance. It provides the methods that can operate on this data type throughNativeSocketAddressClassProtocol
conformance. UseNativeSocketAddressClass
as a strong reference or owner of aGNativeSocketAddressClass
instance.Declaration
Swift
open class NativeSocketAddressClass : NativeSocketAddressClassProtocol
-
The
Mount
type acts as an owner of an underlyingGMount
instance. It provides the methods that can operate on this data type throughMountProtocol
conformance. UseMount
as a strong reference or owner of aGMount
instance.The
GMount
interface represents user-visible mounts. Note, when porting from GnomeVFS,GMount
is the moral equivalent ofGnomeVFSVolume
.GMount
is a “mounted” filesystem that you can access. Mounted is in quotes because it’s not the same as a unix mount, it might be a gvfs mount, but you can still access the files on it if you use GIO. Might or might not be related to a volume object.Unmounting a
See moreGMount
instance is an asynchronous operation. For more information about asynchronous operations, seeGAsyncResult
andGTask
. To unmount aGMount
instance, first callg_mount_unmount_with_operation()
with (at least) theGMount
instance and aGAsyncReadyCallback
. The callback will be fired when the operation has resolved (either with success or failure), and aGAsyncResult
structure will be passed to the callback. That callback should then callg_mount_unmount_with_operation_finish()
with theGMount
and theGAsyncResult
data to see if the operation was completed successfully. If anerror
is present wheng_mount_unmount_with_operation_finish()
is called, then it will be filled with any error information.Declaration
Swift
open class Mount : MountProtocol
-
The
NetworkMonitor
type acts as an owner of an underlyingGNetworkMonitor
instance. It provides the methods that can operate on this data type throughNetworkMonitorProtocol
conformance. UseNetworkMonitor
as a strong reference or owner of aGNetworkMonitor
instance.GNetworkMonitor
provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the available implementations are based on the kernel’s netlink interface and on NetworkManager.There is also an implementation for use inside Flatpak sandboxes.
See moreDeclaration
Swift
open class NetworkMonitor : Initable, NetworkMonitorProtocol
-
The
See moreNativeSocketAddressPrivate
type acts as an owner of an underlyingGNativeSocketAddressPrivate
instance. It provides the methods that can operate on this data type throughNativeSocketAddressPrivateProtocol
conformance. UseNativeSocketAddressPrivate
as a strong reference or owner of aGNativeSocketAddressPrivate
instance.Declaration
Swift
open class NativeSocketAddressPrivate : NativeSocketAddressPrivateProtocol
-
The
See moreNativeVolumeMonitorClass
type acts as an owner of an underlyingGNativeVolumeMonitorClass
instance. It provides the methods that can operate on this data type throughNativeVolumeMonitorClassProtocol
conformance. UseNativeVolumeMonitorClass
as a strong reference or owner of aGNativeVolumeMonitorClass
instance.Declaration
Swift
open class NativeVolumeMonitorClass : NativeVolumeMonitorClassProtocol
-
The
See moreNetworkAddressClass
type acts as an owner of an underlyingGNetworkAddressClass
instance. It provides the methods that can operate on this data type throughNetworkAddressClassProtocol
conformance. UseNetworkAddressClass
as a strong reference or owner of aGNetworkAddressClass
instance.Declaration
Swift
open class NetworkAddressClass : NetworkAddressClassProtocol
-
The
See moreNetworkAddressPrivate
type acts as an owner of an underlyingGNetworkAddressPrivate
instance. It provides the methods that can operate on this data type throughNetworkAddressPrivateProtocol
conformance. UseNetworkAddressPrivate
as a strong reference or owner of aGNetworkAddressPrivate
instance.Declaration
Swift
open class NetworkAddressPrivate : NetworkAddressPrivateProtocol
-
The
NetworkMonitorInterface
type acts as an owner of an underlyingGNetworkMonitorInterface
instance. It provides the methods that can operate on this data type throughNetworkMonitorInterfaceProtocol
conformance. UseNetworkMonitorInterface
as a strong reference or owner of aGNetworkMonitorInterface
instance.The virtual function table for
See moreGNetworkMonitor
.Declaration
Swift
open class NetworkMonitorInterface : NetworkMonitorInterfaceProtocol
-
The
See moreNetworkServiceClass
type acts as an owner of an underlyingGNetworkServiceClass
instance. It provides the methods that can operate on this data type throughNetworkServiceClassProtocol
conformance. UseNetworkServiceClass
as a strong reference or owner of aGNetworkServiceClass
instance.Declaration
Swift
open class NetworkServiceClass : NetworkServiceClassProtocol
-
The
See moreNetworkServicePrivate
type acts as an owner of an underlyingGNetworkServicePrivate
instance. It provides the methods that can operate on this data type throughNetworkServicePrivateProtocol
conformance. UseNetworkServicePrivate
as a strong reference or owner of aGNetworkServicePrivate
instance.Declaration
Swift
open class NetworkServicePrivate : NetworkServicePrivateProtocol
-
The
See moreOsxAppInfoClass
type acts as an owner of an underlyingGOsxAppInfoClass
instance. It provides the methods that can operate on this data type throughOsxAppInfoClassProtocol
conformance. UseOsxAppInfoClass
as a strong reference or owner of aGOsxAppInfoClass
instance.Declaration
Swift
open class OsxAppInfoClass : OsxAppInfoClassProtocol
-
The
See moreNativeVolumeMonitor
type acts as a reference-counted owner of an underlyingGNativeVolumeMonitor
instance. It provides the methods that can operate on this data type throughNativeVolumeMonitorProtocol
conformance. UseNativeVolumeMonitor
as a strong reference or owner of aGNativeVolumeMonitor
instance.Declaration
Swift
open class NativeVolumeMonitor : VolumeMonitor, NativeVolumeMonitorProtocol
-
The
NetworkAddress
type acts as a reference-counted owner of an underlyingGNetworkAddress
instance. It provides the methods that can operate on this data type throughNetworkAddressProtocol
conformance. UseNetworkAddress
as a strong reference or owner of aGNetworkAddress
instance.GNetworkAddress
provides an easy way to resolve a hostname and then attempt to connect to that host, handling the possibility of multiple IP addresses and multiple address families.The enumeration results of resolved addresses may be cached as long as this object is kept alive which may have unexpected results if alive for too long.
See
See moreGSocketConnectable
for an example of using the connectable interface.Declaration
Swift
open class NetworkAddress : Object, NetworkAddressProtocol
-
The
NetworkService
type acts as a reference-counted owner of an underlyingGNetworkService
instance. It provides the methods that can operate on this data type throughNetworkServiceProtocol
conformance. UseNetworkService
as a strong reference or owner of aGNetworkService
instance.Like
GNetworkAddress
does with hostnames,GNetworkService
provides an easy way to resolve a SRV record, and then attempt to connect to one of the hosts that implements that service, handling service priority/weighting, multiple IP addresses, and multiple address families.See
See moreGSrvTarget
for more information about SRV records, and seeGSocketConnectable
for an example of using the connectable interface.Declaration
Swift
open class NetworkService : Object, NetworkServiceProtocol
-
The
Notification
type acts as a reference-counted owner of an underlyingGNotification
instance. It provides the methods that can operate on this data type throughNotificationProtocol
conformance. UseNotification
as a strong reference or owner of aGNotification
instance.GNotification
is a mechanism for creating a notification to be shown to the user – typically as a pop-up notification presented by the desktop environment shell.The key difference between
GNotification
and other similar APIs is that, if supported by the desktop environment, notifications sent withGNotification
will persist after the application has exited, and even across system reboots.Since the user may click on a notification while the application is not running, applications using
GNotification
should be able to be started as a D-Bus service, usingGApplication
.User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: “app.” actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked.
A notification can be sent with
See moreg_application_send_notification()
.Declaration
Swift
open class Notification : Object, NotificationProtocol
-
The
See moreOsxAppInfo
type acts as a reference-counted owner of an underlyingGOsxAppInfo
instance. It provides the methods that can operate on this data type throughOsxAppInfoProtocol
conformance. UseOsxAppInfo
as a strong reference or owner of aGOsxAppInfo
instance.Declaration
Swift
open class OsxAppInfo : Object, OsxAppInfoProtocol
-
The
OutputMessage
type acts as an owner of an underlyingGOutputMessage
instance. It provides the methods that can operate on this data type throughOutputMessageProtocol
conformance. UseOutputMessage
as a strong reference or owner of aGOutputMessage
instance.Structure used for scatter/gather data output when sending multiple messages or packets in one go. You generally pass in an array of
GOutputVectors
and the operation will use all the buffers as if they were one buffer.If
See moreaddress
isnil
then the message is sent to the default receiver (as previously set byg_socket_connect()
).Declaration
Swift
open class OutputMessage : OutputMessageProtocol
-
The
See moreOutputStreamClass
type acts as an owner of an underlyingGOutputStreamClass
instance. It provides the methods that can operate on this data type throughOutputStreamClassProtocol
conformance. UseOutputStreamClass
as a strong reference or owner of aGOutputStreamClass
instance.Declaration
Swift
open class OutputStreamClass : OutputStreamClassProtocol
-
The
See moreOutputStreamPrivate
type acts as an owner of an underlyingGOutputStreamPrivate
instance. It provides the methods that can operate on this data type throughOutputStreamPrivateProtocol
conformance. UseOutputStreamPrivate
as a strong reference or owner of aGOutputStreamPrivate
instance.Declaration
Swift
open class OutputStreamPrivate : OutputStreamPrivateProtocol
-
The
OutputVector
type acts as an owner of an underlyingGOutputVector
instance. It provides the methods that can operate on this data type throughOutputVectorProtocol
conformance. UseOutputVector
as a strong reference or owner of aGOutputVector
instance.Structure used for scatter/gather data output. You generally pass in an array of
See moreGOutputVectors
and the operation will use all the buffers as if they were one buffer.Declaration
Swift
open class OutputVector : OutputVectorProtocol
-
The
See morePermissionClass
type acts as an owner of an underlyingGPermissionClass
instance. It provides the methods that can operate on this data type throughPermissionClassProtocol
conformance. UsePermissionClass
as a strong reference or owner of aGPermissionClass
instance.Declaration
Swift
open class PermissionClass : PermissionClassProtocol
-
The
OutputStream
type acts as a reference-counted owner of an underlyingGOutputStream
instance. It provides the methods that can operate on this data type throughOutputStreamProtocol
conformance. UseOutputStream
as a strong reference or owner of aGOutputStream
instance.GOutputStream
has functions to write to a stream (g_output_stream_write()
), to close a stream (g_output_stream_close()
) and to flush pending writes (g_output_stream_flush()
).To copy the content of an input stream to an output stream without manually handling the reads and writes, use
g_output_stream_splice()
.See the documentation for
GIOStream
for details of thread safety of streaming APIs.All of these functions have async variants too.
See moreDeclaration
Swift
open class OutputStream : Object, OutputStreamProtocol
-
The
Permission
type acts as a reference-counted owner of an underlyingGPermission
instance. It provides the methods that can operate on this data type throughPermissionProtocol
conformance. UsePermission
as a strong reference or owner of aGPermission
instance.A
GPermission
represents the status of the caller’s permission to perform a certain action.You can query if the action is currently allowed and if it is possible to acquire the permission so that the action will be allowed in the future.
There is also an API to actually acquire the permission and one to release it.
As an example, a
See moreGPermission
might represent the ability for the user to write to aGSettings
object. ThisGPermission
object could then be used to decide if it is appropriate to show a “Click here to unlock” button in a dialog and to provide the mechanism to invoke when that button is clicked.Declaration
Swift
open class Permission : Object, PermissionProtocol
-
The
See morePermissionPrivate
type acts as an owner of an underlyingGPermissionPrivate
instance. It provides the methods that can operate on this data type throughPermissionPrivateProtocol
conformance. UsePermissionPrivate
as a strong reference or owner of aGPermissionPrivate
instance.Declaration
Swift
open class PermissionPrivate : PermissionPrivateProtocol
-
The
PollableInputStreamInterface
type acts as an owner of an underlyingGPollableInputStreamInterface
instance. It provides the methods that can operate on this data type throughPollableInputStreamInterfaceProtocol
conformance. UsePollableInputStreamInterface
as a strong reference or owner of aGPollableInputStreamInterface
instance.The interface for pollable input streams.
The default implementation of
can_poll
always returnstrue
.The default implementation of
See moreread_nonblocking
callsg_pollable_input_stream_is_readable()
, and then callsg_input_stream_read()
if it returnstrue
. This means you only need to override it if it is possible that youris_readable
implementation may returntrue
when the stream is not actually readable.Declaration
Swift
open class PollableInputStreamInterface : PollableInputStreamInterfaceProtocol
-
The
PollableOutputStreamInterface
type acts as an owner of an underlyingGPollableOutputStreamInterface
instance. It provides the methods that can operate on this data type throughPollableOutputStreamInterfaceProtocol
conformance. UsePollableOutputStreamInterface
as a strong reference or owner of aGPollableOutputStreamInterface
instance.The interface for pollable output streams.
The default implementation of
can_poll
always returnstrue
.The default implementation of
write_nonblocking
callsg_pollable_output_stream_is_writable()
, and then callsg_output_stream_write()
if it returnstrue
. This means you only need to override it if it is possible that youris_writable
implementation may returntrue
when the stream is not actually writable.The default implementation of
See morewritev_nonblocking
callsg_pollable_output_stream_write_nonblocking()
for each vector, and converts its return value and error (if set) to aGPollableReturn
. You should override this where possible to avoid having to allocate aGError
to returnG_IO_ERROR_WOULD_BLOCK
.Declaration
Swift
open class PollableOutputStreamInterface : PollableOutputStreamInterfaceProtocol
-
The
ProxyAddressClass
type acts as an owner of an underlyingGProxyAddressClass
instance. It provides the methods that can operate on this data type throughProxyAddressClassProtocol
conformance. UseProxyAddressClass
as a strong reference or owner of aGProxyAddressClass
instance.Class structure for
See moreGProxyAddress
.Declaration
Swift
open class ProxyAddressClass : ProxyAddressClassProtocol
-
The
ProxyAddressEnumeratorClass
type acts as an owner of an underlyingGProxyAddressEnumeratorClass
instance. It provides the methods that can operate on this data type throughProxyAddressEnumeratorClassProtocol
conformance. UseProxyAddressEnumeratorClass
as a strong reference or owner of aGProxyAddressEnumeratorClass
instance.Class structure for
See moreGProxyAddressEnumerator
.Declaration
Swift
open class ProxyAddressEnumeratorClass : ProxyAddressEnumeratorClassProtocol
-
The
See moreProxyAddressEnumeratorPrivate
type acts as an owner of an underlyingGProxyAddressEnumeratorPrivate
instance. It provides the methods that can operate on this data type throughProxyAddressEnumeratorPrivateProtocol
conformance. UseProxyAddressEnumeratorPrivate
as a strong reference or owner of aGProxyAddressEnumeratorPrivate
instance.Declaration
Swift
open class ProxyAddressEnumeratorPrivate : ProxyAddressEnumeratorPrivateProtocol
-
The
See moreProxyAddressPrivate
type acts as an owner of an underlyingGProxyAddressPrivate
instance. It provides the methods that can operate on this data type throughProxyAddressPrivateProtocol
conformance. UseProxyAddressPrivate
as a strong reference or owner of aGProxyAddressPrivate
instance.Declaration
Swift
open class ProxyAddressPrivate : ProxyAddressPrivateProtocol
-
The
ProxyInterface
type acts as an owner of an underlyingGProxyInterface
instance. It provides the methods that can operate on this data type throughProxyInterfaceProtocol
conformance. UseProxyInterface
as a strong reference or owner of aGProxyInterface
instance.Provides an interface for handling proxy connection and payload.
See moreDeclaration
Swift
open class ProxyInterface : ProxyInterfaceProtocol
-
The
ProxyResolverInterface
type acts as an owner of an underlyingGProxyResolverInterface
instance. It provides the methods that can operate on this data type throughProxyResolverInterfaceProtocol
conformance. UseProxyResolverInterface
as a strong reference or owner of aGProxyResolverInterface
instance.The virtual function table for
See moreGProxyResolver
.Declaration
Swift
open class ProxyResolverInterface : ProxyResolverInterfaceProtocol
-
The
RemoteActionGroupInterface
type acts as an owner of an underlyingGRemoteActionGroupInterface
instance. It provides the methods that can operate on this data type throughRemoteActionGroupInterfaceProtocol
conformance. UseRemoteActionGroupInterface
as a strong reference or owner of aGRemoteActionGroupInterface
instance.The virtual function table for
See moreGRemoteActionGroup
.Declaration
Swift
open class RemoteActionGroupInterface : RemoteActionGroupInterfaceProtocol
-
The
PollableInputStream
type acts as a reference-counted owner of an underlyingGPollableInputStream
instance. It provides the methods that can operate on this data type throughPollableInputStreamProtocol
conformance. UsePollableInputStream
as a strong reference or owner of aGPollableInputStream
instance.
See moreGPollableInputStream
is implemented byGInputStreams
that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.Declaration
Swift
open class PollableInputStream : InputStream, PollableInputStreamProtocol
-
The
PollableOutputStream
type acts as a reference-counted owner of an underlyingGPollableOutputStream
instance. It provides the methods that can operate on this data type throughPollableOutputStreamProtocol
conformance. UsePollableOutputStream
as a strong reference or owner of aGPollableOutputStream
instance.
See moreGPollableOutputStream
is implemented byGOutputStreams
that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style.Declaration
Swift
open class PollableOutputStream : OutputStream, PollableOutputStreamProtocol
-
The
Proxy
type acts as an owner of an underlyingGProxy
instance. It provides the methods that can operate on this data type throughProxyProtocol
conformance. UseProxy
as a strong reference or owner of aGProxy
instance.A
See moreGProxy
handles connecting to a remote host via a given type of proxy server. It is implemented by the ‘gio-proxy’ extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the name ‘socks5’ using the functiong_io_extension_point_get_extension_by_name()
.Declaration
Swift
open class Proxy : ProxyProtocol
-
The
ProxyResolver
type acts as an owner of an underlyingGProxyResolver
instance. It provides the methods that can operate on this data type throughProxyResolverProtocol
conformance. UseProxyResolver
as a strong reference or owner of aGProxyResolver
instance.GProxyResolver
provides synchronous and asynchronous network proxy resolution.GProxyResolver
is used withinGSocketClient
through the methodg_socket_connectable_proxy_enumerate()
.Implementations of
See moreGProxyResolver
based on libproxy and GNOME settings can be found in glib-networking. GIO comes with an implementation for use inside Flatpak portals.Declaration
Swift
open class ProxyResolver : ProxyResolverProtocol
-
The
RemoteActionGroup
type acts as an owner of an underlyingGRemoteActionGroup
instance. It provides the methods that can operate on this data type throughRemoteActionGroupProtocol
conformance. UseRemoteActionGroup
as a strong reference or owner of aGRemoteActionGroup
instance.The GRemoteActionGroup interface is implemented by
GActionGroup
instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes.The interface has
_full
variants of the two methods onGActionGroup
used to activate actions:g_action_group_activate_action()
andg_action_group_change_action_state()
. These variants allow a “platform data”GVariant
to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc).GDBusActionGroup
implementsGRemoteActionGroup
. This provides a mechanism to send platform data for action invocations over D-Bus.Additionally,
See moreg_dbus_connection_export_action_group()
will check if the exportedGActionGroup
implementsGRemoteActionGroup
and use the_full
variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus.Declaration
Swift
open class RemoteActionGroup : ActionGroup, RemoteActionGroupProtocol
-
The
PropertyAction
type acts as a reference-counted owner of an underlyingGPropertyAction
instance. It provides the methods that can operate on this data type throughPropertyActionProtocol
conformance. UsePropertyAction
as a strong reference or owner of aGPropertyAction
instance.A
GPropertyAction
is a way to get aGAction
with a state value reflecting and controlling the value of aGObject
property.The state of the action will correspond to the value of the property. Changing it will change the property (assuming the requested value matches the requirements as specified in the
GParamSpec
).Only the most common types are presently supported. Booleans are mapped to booleans, strings to strings, signed/unsigned integers to int32/uint32 and floats and doubles to doubles.
If the property is an enum then the state will be string-typed and conversion will automatically be performed between the enum value and “nick” string as per the
GEnumValue
table.Flags types are not currently supported.
Properties of object types, boxed types and pointer types are not supported and probably never will be.
Properties of
GVariant
types are not currently supported.If the property is boolean-valued then the action will have a NULL parameter type, and activating the action (with no parameter) will toggle the value of the property.
In all other cases, the parameter type will correspond to the type of the property.
The general idea here is to reduce the number of locations where a particular piece of state is kept (and therefore has to be synchronised between).
GPropertyAction
does not have a separate state that is kept in sync with the property value – its state is the property value.For example, it might be useful to create a
GAction
corresponding to the “visible-child-name” property of aGtkStack
so that the current page can be switched from a menu. The active radio indication in the menu is then directly determined from the active page of theGtkStack
.An anti-example would be binding the “active-id” property on a
GtkComboBox
. This is because the state of the combobox itself is probably uninteresting and is actually being used to control something else.Another anti-example would be to bind to the “visible-child-name” property of a
See moreGtkStack
if this value is actually stored inGSettings
. In that case, the real source of the value isGSettings
. If you want aGAction
to control a setting stored inGSettings
, seeg_settings_create_action()
instead, and possibly combine its use withg_settings_bind()
.Declaration
Swift
open class PropertyAction : Object, PropertyActionProtocol
-
The
ProxyAddress
type acts as a reference-counted owner of an underlyingGProxyAddress
instance. It provides the methods that can operate on this data type throughProxyAddressProtocol
conformance. UseProxyAddress
as a strong reference or owner of aGProxyAddress
instance.Support for proxied
See moreGInetSocketAddress
.Declaration
Swift
open class ProxyAddress : InetSocketAddress, ProxyAddressProtocol
-
The
ProxyAddressEnumerator
type acts as a reference-counted owner of an underlyingGProxyAddressEnumerator
instance. It provides the methods that can operate on this data type throughProxyAddressEnumeratorProtocol
conformance. UseProxyAddressEnumerator
as a strong reference or owner of aGProxyAddressEnumerator
instance.GProxyAddressEnumerator
is a wrapper aroundGSocketAddressEnumerator
which takes theGSocketAddress
instances returned by theGSocketAddressEnumerator
and wraps them inGProxyAddress
instances, using the givenGProxyAddressEnumerator:proxy
-resolver.This enumerator will be returned (for example, by
See moreg_socket_connectable_enumerate()
) as appropriate when a proxy is configured; there should be no need to manually wrap aGSocketAddressEnumerator
instance with one.Declaration
Swift
open class ProxyAddressEnumerator : SocketAddressEnumerator, ProxyAddressEnumeratorProtocol
-
The
Resolver
type acts as a reference-counted owner of an underlyingGResolver
instance. It provides the methods that can operate on this data type throughResolverProtocol
conformance. UseResolver
as a strong reference or owner of aGResolver
instance.GResolver
provides cancellable synchronous and asynchronous DNS resolution, for hostnames (g_resolver_lookup_by_address()
,g_resolver_lookup_by_name()
and their async variants) and SRV (service) records (g_resolver_lookup_service()
).
See moreGNetworkAddress
andGNetworkService
provide wrappers aroundGResolver
functionality that also implementGSocketConnectable
, making it easy to connect to a remote host/service.Declaration
Swift
open class Resolver : Object, ResolverProtocol
-
The
See moreResolverClass
type acts as an owner of an underlyingGResolverClass
instance. It provides the methods that can operate on this data type throughResolverClassProtocol
conformance. UseResolverClass
as a strong reference or owner of aGResolverClass
instance.Declaration
Swift
open class ResolverClass : ResolverClassProtocol
-
The
See moreResolverPrivate
type acts as an owner of an underlyingGResolverPrivate
instance. It provides the methods that can operate on this data type throughResolverPrivateProtocol
conformance. UseResolverPrivate
as a strong reference or owner of aGResolverPrivate
instance.Declaration
Swift
open class ResolverPrivate : ResolverPrivateProtocol
-
The
Resource
type acts as a reference-counted owner of an underlyingGResource
instance. It provides the methods that can operate on this data type throughResourceProtocol
conformance. UseResource
as a strong reference or owner of aGResource
instance.Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance
GtkBuilder
.ui files, splashscreen images, GMenu markup XML, CSS files, icons, etc. These are often shipped as files in$datadir/appname
, or manually included as literal strings in the code.The
GResource
API and the glib-compile-resources program provide a convenient and efficient alternative to this which has some nice properties. You maintain the files as normal files, so its easy to edit them, but during the build the files are combined into a binary bundle that is linked into the 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.Resource files can also be marked as compressed. Such files will be included in the resource bundle in a compressed form, but will be automatically 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
preprocess
attribute to a comma-separated list of preprocessing options. The only options currently supported are:xml-stripblanks
which will use the xmllint command to strip ignorable whitespace from the XML file. For this to work, theXMLLINT
environment variable must be set to the full path to the xmllint executable, or xmllint must be in thePATH
; otherwise the preprocessing step is skipped.to-pixdata
which will use the gdk-pixbuf-pixdata command to convert images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside the resource file, rather than an (uncompressed) copy of it. For this, the gdk-pixbuf-pixdata program must be in the PATH, or theGDK_PIXBUF_PIXDATA
environment variable must be set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will abort.Resource files will be exported in the GResource namespace using the combination of the given
prefix
and the filename from thefile
element. Thealias
attribute can be used to alter the filename to expose them at a different location in the resource namespace. Typically, this is used to include files from a different source directory without exposing the source directory in the resource namespace, as in the example below.Resource bundles are created by the glib-compile-resources program 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:
<?xml version="1.0" encoding="UTF-8"?> <gresources> <gresource prefix="/org/gtk/Example"> <file>data/splashscreen.png</file> <file compressed="true">dialog.ui</file> <file preprocess="xml-stripblanks">menumarkup.xml</file> <file alias="example.css">data/example.css</file> </gresource> </gresources>
This will create a resource bundle with the following files:
/org/gtk/Example/data/splashscreen.png /org/gtk/Example/dialog.ui /org/gtk/Example/menumarkup.xml /org/gtk/Example/example.css
Note that all resources in the process share the same namespace, so use Java-style path prefixes (like in the above example) to avoid conflicts.
You can then use glib-compile-resources to compile the XML to a binary bundle that you can load with
g_resource_load()
. However, its 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 generateget_resource()
,register_resource()
andunregister_resource()
functions, prefixed by the--c-name
argument passed to glib-compile-resources.get_resource()
returns the generatedGResource
object. The register and unregister functions register the resource so its files can be accessed usingg_resources_lookup_data()
.Once a
GResource
has been created and registered all the data in it can be accessed globally in the process by using API calls likeg_resources_open_stream()
to stream the data org_resources_lookup_data()
to get a direct pointer to the data. You can also use URIs like “resource:///org/gtk/Example/data/splashscreen.png” withGFile
to access the resource data.Some higher-level APIs, such as
GtkApplication
, will automatically load resources from certain well-known paths in the resource namespace as a 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 and destructor functions (where available) to automatically create and register the
GResource
on startup or library load time. If you pass--manual-register
, two functions to 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 during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes 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 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 resources with replacements from the filesystem. It is aG_SEARCHPATH_SEPARATOR
-separated list of substitutions to perform during resource lookups.A substitution has the form
/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 filesystem path which contains files and subdirectories as you would like to be loaded as resources with the equivalent names.In the example above, if an application tried to load a resource with the resource path
/org/gtk/libgtk/ui/gtkdialog.ui
then GResource would check the filesystem path/home/desrt/gtk-overlay/ui/gtkdialog.ui
. If a file was found there, it would be used instead. This is an overlay, not an outright 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 the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the location of a single resource with an individual file.
See moreDeclaration
Swift
open class Resource : ResourceProtocol
-
The
SeekableIface
type acts as an owner of an underlyingGSeekableIface
instance. It provides the methods that can operate on this data type throughSeekableIfaceProtocol
conformance. UseSeekableIface
as a strong reference or owner of aGSeekableIface
instance.Provides an interface for implementing seekable functionality on I/O Streams.
See moreDeclaration
Swift
open class SeekableIface : SeekableIfaceProtocol
-
The
Seekable
type acts as an owner of an underlyingGSeekable
instance. It provides the methods that can operate on this data type throughSeekableProtocol
conformance. UseSeekable
as a strong reference or owner of aGSeekable
instance.GSeekable
is implemented by streams (implementations ofGInputStream
orGOutputStream
) that support seeking.Seekable streams largely fall into two categories: resizable and fixed-size.
GSeekable
on fixed-sized streams is approximately the same as POSIXlseek()
on a block device (for example: attempting to seek past the end of the device is an error). Fixed streams typically cannot be truncated.
See moreGSeekable
on resizable streams is approximately the same as POSIXlseek()
on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes.Declaration
Swift
open class Seekable : SeekableProtocol
-
The
SocketConnectable
type acts as an owner of an underlyingGSocketConnectable
instance. It provides the methods that can operate on this data type throughSocketConnectableProtocol
conformance. UseSocketConnectable
as a strong reference or owner of aGSocketConnectable
instance.Objects that describe one or more potential socket endpoints implement
GSocketConnectable
. Callers can then useg_socket_connectable_enumerate()
to get aGSocketAddressEnumerator
to try out each socket address in turn until one succeeds, as shown in the sample code below.(C Language Example):
See moreMyConnectionType * connect_to_host (const char *hostname, guint16 port, GCancellable *cancellable, GError **error) { MyConnection *conn = NULL; GSocketConnectable *addr; GSocketAddressEnumerator *enumerator; GSocketAddress *sockaddr; GError *conn_error = NULL; addr = g_network_address_new (hostname, port); enumerator = g_socket_connectable_enumerate (addr); g_object_unref (addr); // Try each sockaddr until we succeed. Record the first connection error, // but not any further ones (since they'll probably be basically the same // as the first). while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) { conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); g_object_unref (sockaddr); } g_object_unref (enumerator); if (conn) { if (conn_error) { // We couldn't connect to the first address, but we succeeded // in connecting to a later address. g_error_free (conn_error); } return conn; } else if (error) { /// Either initial lookup failed, or else the caller cancelled us. if (conn_error) g_error_free (conn_error); return NULL; } else { g_error_propagate (error, conn_error); return NULL; } }
Declaration
Swift
open class SocketConnectable : SocketConnectableProtocol
-
The
TLSBackend
type acts as an owner of an underlyingGTlsBackend
instance. It provides the methods that can operate on this data type throughTLSBackendProtocol
conformance. UseTLSBackend
as a strong reference or owner of aGTlsBackend
instance.TLS (Transport Layer Security, aka SSL) and DTLS backend.
See moreDeclaration
Swift
open class TLSBackend : TLSBackendProtocol
-
The
Settings
type acts as a reference-counted owner of an underlyingGSettings
instance. It provides the methods that can operate on this data type throughSettingsProtocol
conformance. UseSettings
as a strong reference or owner of aGSettings
instance.The
GSettings
class provides a convenient API for storing and retrieving application settings.Reads and writes can be considered to be non-blocking. Reading settings with
GSettings
is typically extremely fast: on approximately the same order of magnitude (but slower than) aGHashTable
lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service doesn’t even need to be started in this case. For this reason, you should only ever modifyGSettings
keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup – for example, when setting the initial value of preferences widgets. The built-ing_settings_bind()
functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets.When creating a GSettings instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information.
Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas can also be ‘relocatable’, i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an 'account’, and you want to be able to store a arbitrary number of accounts.
Paths must start with and end with a forward slash character (‘/’) and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are “/org/gtk/settings/file-chooser/” and “/ca/desrt/dconf-editor/”. Paths should not start with “/apps/”, “/desktop/” or “/system/” as they often did in GConf.
Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores values as
GVariant
, and allows anyGVariantType
for keys. Key names are restricted to lowercase characters, numbers and ‘-’. Furthermore, the names must begin with a lowercase character, must not end with a ‘-’, and must not contain consecutive dashes.Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the
gettext-domain
attribute of theor elements and the category that is specified in the l10n
attribute of theelement. The string which is translated includes all text in the element, including any surrounding quotation marks. The
l10n
attribute must be set tomessages
ortime
, and sets the locale category for translation. Themessages
category should be used by default; usetime
for translatable date or time formats. A translation comment can be added as an XML comment immediately above theelement — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation context
attribute can be set on theelement to disambiguate multiple defaults which use the same string. For example:
<default l10n='messages' context='Banned words'>['bad', 'words']</default>
Translations of default values must remain syntactically valid serialized
GVariants
(e.g. retaining any surrounding quotation marks) or runtime errors will occur.GSettings uses schemas in a compact binary form that is created by the glib-compile-schemas utility. The input is a schema description in an XML format.
A DTD for the gschema XML format can be found here: gschema.dtd
The glib-compile-schemas tool expects schema files to have the extension
.gschema.xml
.At runtime, schemas are identified by their id (as specified in the id attribute of the
element). The convention for schema ids is to use a dotted name, similar in style to a D-Bus bus name, e.g. “org.gnome.SessionManager”. In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name and schema id should match. For schemas which deal with settings not associated with one named application, the id should not use StudlyCaps, e.g. “org.gnome.font-rendering”. In addition to
GVariant
types, keys can have types that have enumerated types. These can be described by a, or element, as seen in the example. The underlying type of such a key is string, but you can use g_settings_get_enum()
,g_settings_set_enum()
,g_settings_get_flags()
,g_settings_set_flags()
access the numeric values corresponding to the string value of enum and flags keys.An example for default value:
<schemalist> <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> <key name="greeting" type="s"> <default l10n="messages">"Hello, earthlings"</default> <summary>A greeting</summary> <description> Greeting of the invading martians </description> </key> <key name="box" type="(ii)"> <default>(20,30)</default> </key> <key name="empty-string" type="s"> <default>""</default> <summary>Empty strings have to be provided in GVariant form</summary> </key> </schema> </schemalist>
An example for ranges, choices and enumerated types:
<schemalist> <enum id="org.gtk.Test.myenum"> <value nick="first" value="1"/> <value nick="second" value="2"/> </enum> <flags id="org.gtk.Test.myflags"> <value nick="flag1" value="1"/> <value nick="flag2" value="2"/> <value nick="flag3" value="4"/> </flags> <schema id="org.gtk.Test"> <key name="key-with-range" type="i"> <range min="1" max="100"/> <default>10</default> </key> <key name="key-with-choices" type="s"> <choices> <choice value='Elisabeth'/> <choice value='Annabeth'/> <choice value='Joe'/> </choices> <aliases> <alias value='Anna' target='Annabeth'/> <alias value='Beth' target='Elisabeth'/> </aliases> <default>'Joe'</default> </key> <key name='enumerated-key' enum='org.gtk.Test.myenum'> <default>'first'</default> </key> <key name='flags-key' flags='org.gtk.Test.myflags'> <default>["flag1","flag2"]</default> </key> </schema> </schemalist>
Vendor overrides
Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, glib-compile-schemas reads so-called vendor override’ files. These are keyfiles in the same directory as the XML schema sources which can override default values. The schema id serves as the group name in the key file, and the values are expected in serialized GVariant form, as in the following example:
[org.gtk.Example] key1='string' key2=1.5
glib-compile-schemas expects schema files to have the extension
.gschema.override
.Binding
A very convenient feature of GSettings lets you bind
GObject
properties directly to settings, usingg_settings_bind()
. Once a GObject property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between GObject and GVariant types, and preventing infinite cycles.This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings looks for a boolean property with the name “sensitivity” and automatically binds it to the writability of the bound setting. If this ‘magic’ gets in the way, it can be suppressed with the
G_SETTINGS_BIND_NO_SENSITIVITY
flag.Relocatable schemas #
A relocatable schema is one with no
path
attribute specified on itselement. By using g_settings_new_with_path()
, aGSettings
object can be instantiated for a relocatable schema, assigning a path to the instance. Paths passed tog_settings_new_with_path()
will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a dependency library.For example, a relocatable schema could be used to store geometry information for different windows in an application. If the schema ID was
org.foo.MyApp.Window
, it could be instantiated for paths/org/foo/MyApp/main/
,/org/foo/MyApp/document-1/
,/org/foo/MyApp/document-2/
, etc. If any of the paths are well-known they can be specified aselements in the parent schema, e.g.: <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> <child name="main" schema="org.foo.MyApp.Window"/> </schema>
Build system integration #
GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your
configure.ac
:GLIB_GSETTINGS
In the appropriate
Makefile.am
, use the following snippet to compile and install the named schema:gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@
No changes are needed to the build system to mark a schema XML file for translation. Assuming it sets the
gettext-domain
attribute, a schema may be marked for translation by adding it toPOTFILES.in
, assuming gettext 0.19 is in use (the preferred method for translation):data/org.foo.MyApp.gschema.xml
Alternatively, if intltool 0.50.1 is in use:
[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml
GSettings will use gettext to look up translations for the
and elements, and also any elements which have a l10n
attribute set. Translations must not be included in the.gschema.xml
file by the build system, for example by using intltool XML rules with a.gschema.xml.in
template.If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an
element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant Makefile.am
:gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h
See moregsettings_ENUM_NAMESPACE
specifies the schema namespace for the enum files, which are specified ingsettings_ENUM_FILES
. This will generate aorg.foo.MyApp.enums.xml
file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included inEXTRA_DIST
.Declaration
Swift
open class Settings : Object, SettingsProtocol
-
The
SettingsBackend
type acts as a reference-counted owner of an underlyingGSettingsBackend
instance. It provides the methods that can operate on this data type throughSettingsBackendProtocol
conformance. UseSettingsBackend
as a strong reference or owner of aGSettingsBackend
instance.The
GSettingsBackend
interface defines a generic interface for non-strictly-typed data that is stored in a hierarchy. To implement an alternative storage backend forGSettings
, you need to implement theGSettingsBackend
interface and then make it implement the extension pointG_SETTINGS_BACKEND_EXTENSION_POINT_NAME
.The interface defines methods for reading and writing values, a method for determining if writing of certain values will fail (lockdown) and a change notification mechanism.
The semantics of the interface are very precisely defined and implementations must carefully adhere to the expectations of callers that are documented on each of the interface methods.
Some of the
GSettingsBackend
functions accept or return aGTree
. These trees always have strings as keys andGVariant
as values.g_settings_backend_create_tree()
is a convenience function to create suitable trees.The
See moreGSettingsBackend
API is exported to allow third-party implementations, but does not carry the same stability guarantees as the public GIO API. For this reason, you have to define the C preprocessor symbolG_SETTINGS_ENABLE_BACKEND
before includinggio/gsettingsbackend.h
.Declaration
Swift
open class SettingsBackend : Object, SettingsBackendProtocol
-
The
SimpleAction
type acts as a reference-counted owner of an underlyingGSimpleAction
instance. It provides the methods that can operate on this data type throughSimpleActionProtocol
conformance. UseSimpleAction
as a strong reference or owner of aGSimpleAction
instance.A
GSimpleAction
is the obvious simple implementation of theGAction
interface. This is the easiest way to create an action for purposes of adding it to aGSimpleActionGroup
.See also
See moreGtkAction
.Declaration
Swift
open class SimpleAction : Object, SimpleActionProtocol
-
The
SimpleActionGroup
type acts as a reference-counted owner of an underlyingGSimpleActionGroup
instance. It provides the methods that can operate on this data type throughSimpleActionGroupProtocol
conformance. UseSimpleActionGroup
as a strong reference or owner of aGSimpleActionGroup
instance.
See moreGSimpleActionGroup
is a hash table filled withGAction
objects, implementing theGActionGroup
andGActionMap
interfaces.Declaration
Swift
open class SimpleActionGroup : Object, SimpleActionGroupProtocol
-
The
SimpleAsyncResult
type acts as a reference-counted owner of an underlyingGSimpleAsyncResult
instance. It provides the methods that can operate on this data type throughSimpleAsyncResultProtocol
conformance. UseSimpleAsyncResult
as a strong reference or owner of aGSimpleAsyncResult
instance.As of GLib 2.46,
GSimpleAsyncResult
is deprecated in favor ofGTask
, which provides a simpler API.GSimpleAsyncResult
implementsGAsyncResult
.GSimpleAsyncResult handles
GAsyncReadyCallbacks
, error reporting, operation cancellation and the final state of an operation, completely transparent to the application. Results can be returned as a pointer e.g. for functions that return data that is collected asynchronously, a boolean value for checking the success or failure of an operation, or agssize
for operations which return the number of bytes modified by the operation; all of the simple return cases are covered.Most of the time, an application will not need to know of the details of this API; it is handled transparently, and any necessary operations are handled by
GAsyncResult
‘s interface. However, if implementing a new GIO module, for writing language bindings, or for complex applications that need better control of how asynchronous operations are completed, it is important to understand this functionality.GSimpleAsyncResults are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly.
To create a new
GSimpleAsyncResult
, callg_simple_async_result_new()
. If the result needs to be created for aGError
, useg_simple_async_result_new_from_error()
org_simple_async_result_new_take_error()
. If aGError
is not available (e.g. the asynchronous operation’s doesn’t take aGError
argument), but the result still needs to be created for an error condition, useg_simple_async_result_new_error()
(org_simple_async_result_set_error_va()
if your application or binding requires passing a variable argument list directly), and the error can then be propagated through the use ofg_simple_async_result_propagate_error()
.An asynchronous operation can be made to ignore a cancellation event by calling
g_simple_async_result_set_handle_cancellation()
with aGSimpleAsyncResult
for the operation andfalse
. This is useful for operations that are dangerous to cancel, such as close (which would cause a leak if cancelled before being run).GSimpleAsyncResult can integrate into GLib’s event loop,
GMainLoop
, or it can useGThreads
.g_simple_async_result_complete()
will finish an I/O task directly from the point where it is called.g_simple_async_result_complete_in_idle()
will finish it from an idle handler in the thread-default main context where theGSimpleAsyncResult
was created.g_simple_async_result_run_in_thread()
will run the job in a separate thread and then useg_simple_async_result_complete_in_idle()
to deliver the result.To set the results of an asynchronous function,
g_simple_async_result_set_op_res_gpointer()
,g_simple_async_result_set_op_res_gboolean()
, andg_simple_async_result_set_op_res_gssize()
are provided, setting the operation’s result to a gpointer, gboolean, or gssize, respectively.Likewise, to get the result of an asynchronous function,
g_simple_async_result_get_op_res_gpointer()
,g_simple_async_result_get_op_res_gboolean()
, andg_simple_async_result_get_op_res_gssize()
are provided, getting the operation’s result as a gpointer, gboolean, and gssize, respectively.For the details of the requirements implementations must respect, see
GAsyncResult
. A typical implementation of an asynchronous operation using GSimpleAsyncResult looks something like this:(C Language Example):
See morestatic void baked_cb (Cake *cake, gpointer user_data) { // In this example, this callback is not given a reference to the cake, // so the GSimpleAsyncResult has to take a reference to it. GSimpleAsyncResult *result = user_data; if (cake == NULL) g_simple_async_result_set_error (result, BAKER_ERRORS, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); else g_simple_async_result_set_op_res_gpointer (result, g_object_ref (cake), g_object_unref); // In this example, we assume that baked_cb is called as a callback from // the mainloop, so it's safe to complete the operation synchronously here. // If, however, _baker_prepare_cake () might call its callback without // first returning to the mainloop — inadvisable, but some APIs do so — // we would need to use g_simple_async_result_complete_in_idle(). g_simple_async_result_complete (result); g_object_unref (result); } void baker_bake_cake_async (Baker *self, guint radius, GAsyncReadyCallback callback, gpointer user_data) { GSimpleAsyncResult *simple; Cake *cake; if (radius < 3) { g_simple_async_report_error_in_idle (G_OBJECT (self), callback, user_data, BAKER_ERRORS, BAKER_ERROR_TOO_SMALL, "%ucm radius cakes are silly", radius); return; } simple = g_simple_async_result_new (G_OBJECT (self), callback, user_data, baker_bake_cake_async); cake = _baker_get_cached_cake (self, radius); if (cake != NULL) { g_simple_async_result_set_op_res_gpointer (simple, g_object_ref (cake), g_object_unref); g_simple_async_result_complete_in_idle (simple); g_object_unref (simple); // Drop the reference returned by _baker_get_cached_cake(); // the GSimpleAsyncResult has taken its own reference. g_object_unref (cake); return; } _baker_prepare_cake (self, radius, baked_cb, simple); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { GSimpleAsyncResult *simple; Cake *cake; g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (self), baker_bake_cake_async), NULL); simple = (GSimpleAsyncResult *) result; if (g_simple_async_result_propagate_error (simple, error)) return NULL; cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); return g_object_ref (cake); }
Declaration
Swift
open class SimpleAsyncResult : Object, SimpleAsyncResultProtocol
-
The
SimpleIOStream
type acts as a reference-counted owner of an underlyingGSimpleIOStream
instance. It provides the methods that can operate on this data type throughSimpleIOStreamProtocol
conformance. UseSimpleIOStream
as a strong reference or owner of aGSimpleIOStream
instance.GSimpleIOStream creates a
GIOStream
from an arbitraryGInputStream
andGOutputStream
. This allows any pair of input and output streams to be used withGIOStream
methods.This is useful when you obtained a
See moreGInputStream
and aGOutputStream
by other means, for instance creating them with platform specific methods asg_unix_input_stream_new()
org_win32_input_stream_new()
, and you want to take advantage of the methods provided byGIOStream
.Declaration
Swift
open class SimpleIOStream : IOStream, SimpleIOStreamProtocol
-
The
SimplePermission
type acts as a reference-counted owner of an underlyingGSimplePermission
instance. It provides the methods that can operate on this data type throughSimplePermissionProtocol
conformance. UseSimplePermission
as a strong reference or owner of aGSimplePermission
instance.GSimplePermission
is a trivial implementation ofGPermission
that represents a permission that is either always or never allowed. The value is given at construction and doesn’t change.Calling request or release will result in errors.
See moreDeclaration
Swift
open class SimplePermission : Permission, SimplePermissionProtocol
-
The
SimpleProxyResolver
type acts as a reference-counted owner of an underlyingGSimpleProxyResolver
instance. It provides the methods that can operate on this data type throughSimpleProxyResolverProtocol
conformance. UseSimpleProxyResolver
as a strong reference or owner of aGSimpleProxyResolver
instance.GSimpleProxyResolver
is a simpleGProxyResolver
implementation that handles a single default proxy, multiple URI-scheme-specific proxies, and a list of hosts that proxies should not be used for.
See moreGSimpleProxyResolver
is never the default proxy resolver, but it can be used as the base class for another proxy resolver implementation, or it can be created and used manually, such as withg_socket_client_set_proxy_resolver()
.Declaration
Swift
open class SimpleProxyResolver : Object, SimpleProxyResolverProtocol
-
The
Socket
type acts as a reference-counted owner of an underlyingGSocket
instance. It provides the methods that can operate on this data type throughSocketProtocol
conformance. UseSocket
as a strong reference or owner of aGSocket
instance.A
GSocket
is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows.GSocket
is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to use it directly, but rather through classes likeGSocketClient
,GSocketService
andGSocketConnection
. However there may be cases where direct use ofGSocket
is useful.GSocket
implements theGInitable
interface, so if it is manually constructed by e.g.g_object_new()
you must callg_initable_init()
and check the results before using the object. This is done automatically ing_socket_new()
andg_socket_new_from_fd()
, so these functions can returnnil
.Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that would block return immediately with a
G_IO_ERROR_WOULD_BLOCK
error. To know when a call would successfully run you can callg_socket_condition_check()
, org_socket_condition_wait()
. You can also useg_socket_create_source()
and attach it to aGMainContext
to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and blocking mode is emulated in GSocket.When working in non-blocking mode applications should always be able to 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 returnsG_IO_ERROR_WOULD_BLOCK
.GSockets
can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is specified or received in each I/O operation.All socket file descriptors are set to be close-on-exec.
Note that creating a
GSocket
causes the signalSIGPIPE
to be ignored for the remainder of the program. If you are writing a command-line utility that usesGSocket
, you may need to take into account the fact that your program will not automatically be killed if it tries to write tostdout
after it has been closed.Like most other APIs in GLib,
See moreGSocket
is not inherently thread safe. To use aGSocket
concurrently from multiple threads, you must implement your own locking.Declaration
Swift
open class Socket : Object, SocketProtocol
-
The
SocketAddress
type acts as a reference-counted owner of an underlyingGSocketAddress
instance. It provides the methods that can operate on this data type throughSocketAddressProtocol
conformance. UseSocketAddress
as a strong reference or owner of aGSocketAddress
instance.
See moreGSocketAddress
is the equivalent of struct sockaddr in the BSD sockets API. This is an abstract class; useGInetSocketAddress
for internet sockets, orGUnixSocketAddress
for UNIX domain sockets.Declaration
Swift
open class SocketAddress : Object, SocketAddressProtocol
-
The
SocketAddressEnumerator
type acts as a reference-counted owner of an underlyingGSocketAddressEnumerator
instance. It provides the methods that can operate on this data type throughSocketAddressEnumeratorProtocol
conformance. UseSocketAddressEnumerator
as a strong reference or owner of aGSocketAddressEnumerator
instance.GSocketAddressEnumerator
is an enumerator type forGSocketAddress
instances. It is returned by enumeration functions such asg_socket_connectable_enumerate()
, which returns aGSocketAddressEnumerator
to list eachGSocketAddress
which could be used to connect to thatGSocketConnectable
.Enumeration is typically a blocking operation, so the asynchronous methods
g_socket_address_enumerator_next_async()
andg_socket_address_enumerator_next_finish()
should be used where possible.Each
See moreGSocketAddressEnumerator
can only be enumerated once. Onceg_socket_address_enumerator_next()
has returnednil
(and no error), further enumeration with thatGSocketAddressEnumerator
is not possible, and it can be unreffed.Declaration
Swift
open class SocketAddressEnumerator : Object, SocketAddressEnumeratorProtocol
-
The
SocketClient
type acts as a reference-counted owner of an underlyingGSocketClient
instance. It provides the methods that can operate on this data type throughSocketClientProtocol
conformance. UseSocketClient
as a strong reference or owner of aGSocketClient
instance.GSocketClient
is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type.You create a
GSocketClient
object, set any options you want, and then call a sync or async connect operation, which returns aGSocketConnection
subclass on success.The type of the
GSocketConnection
object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be aGTcpConnection
.As
See moreGSocketClient
is a lightweight object, you don’t need to cache it. You can just create a new one any time you need one.Declaration
Swift
open class SocketClient : Object, SocketClientProtocol
-
The
SocketConnection
type acts as a reference-counted owner of an underlyingGSocketConnection
instance. It provides the methods that can operate on this data type throughSocketConnectionProtocol
conformance. UseSocketConnection
as a strong reference or owner of aGSocketConnection
instance.GSocketConnection
is aGIOStream
for a connected socket. They can be created either byGSocketClient
when connecting to a host, or byGSocketListener
when accepting a new client.The type of the
GSocketConnection
object returned from these calls depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be aGTcpConnection
.Choosing what type of object to construct is done with the socket connection factory, and it is possible for 3rd parties to register custom socket connection types for specific combination of socket family/type/protocol using
g_socket_connection_factory_register_type()
.To close a
See moreGSocketConnection
, useg_io_stream_close()
. Closing both substreams of theGIOStream
separately will not close the underlyingGSocket
.Declaration
Swift
open class SocketConnection : IOStream, SocketConnectionProtocol
-
The
SocketControlMessage
type acts as a reference-counted owner of an underlyingGSocketControlMessage
instance. It provides the methods that can operate on this data type throughSocketControlMessageProtocol
conformance. UseSocketControlMessage
as a strong reference or owner of aGSocketControlMessage
instance.A
GSocketControlMessage
is a special-purpose utility message that can be sent to or received from aGSocket
. These types of messages are often called “ancillary data”.The message can represent some sort of special instruction to or information from the socket or can represent a special kind of transfer to the peer (for example, sending a file descriptor over a UNIX socket).
These messages are sent with
g_socket_send_message()
and received withg_socket_receive_message()
.To extend the set of control message that can be sent, subclass this class and override the get_size, get_level, get_type and serialize methods.
To extend the set of control messages that can be received, subclass this class and implement the deserialize method. Also, make sure your class is registered with the GType typesystem before calling
See moreg_socket_receive_message()
to read such a message.Declaration
Swift
open class SocketControlMessage : Object, SocketControlMessageProtocol
-
The
SocketListener
type acts as a reference-counted owner of an underlyingGSocketListener
instance. It provides the methods that can operate on this data type throughSocketListenerProtocol
conformance. UseSocketListener
as a strong reference or owner of aGSocketListener
instance.A
GSocketListener
is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async.Add addresses and ports to listen on using
g_socket_listener_add_address()
andg_socket_listener_add_inet_port()
. These will be listened on untilg_socket_listener_close()
is called. Dropping your final reference to theGSocketListener
will not causeg_socket_listener_close()
to be called implicitly, as some references to theGSocketListener
may be held internally.If you want to implement a network server, also look at
See moreGSocketService
andGThreadedSocketService
which are subclasses ofGSocketListener
that make this even easier.Declaration
Swift
open class SocketListener : Object, SocketListenerProtocol
-
The
SocketService
type acts as a reference-counted owner of an underlyingGSocketService
instance. It provides the methods that can operate on this data type throughSocketServiceProtocol
conformance. UseSocketService
as a strong reference or owner of aGSocketService
instance.A
GSocketService
is an object that represents a service that is provided to the network or over local sockets. When a new connection is made to the service theGSocketService::incoming
signal is emitted.A
GSocketService
is a subclass ofGSocketListener
and you need to add the addresses you want to accept connections on with theGSocketListener
APIs.There are two options for implementing a network service based on
GSocketService
. The first is to create the service usingg_socket_service_new()
and to connect to theGSocketService::incoming
signal. The second is to subclassGSocketService
and override the default signal handler implementation.In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain blocking code then see
GThreadedSocketService
.The socket service runs on the main loop of the thread-default context of the thread it is created in, and is not threadsafe in general. However, the calls to start and stop the service are thread-safe so these can be used from threads that handle incoming clients.
See moreDeclaration
Swift
open class SocketService : SocketListener, SocketServiceProtocol
-
The
Subprocess
type acts as a reference-counted owner of an underlyingGSubprocess
instance. It provides the methods that can operate on this data type throughSubprocessProtocol
conformance. UseSubprocess
as a strong reference or owner of aGSubprocess
instance.GSubprocess
allows the creation of and interaction with child processes.Processes can be communicated with using standard GIO-style APIs (ie:
GInputStream
,GOutputStream
). There are GIO-style APIs to wait for process termination (ie: cancellable and with an asynchronous variant).There is an API to force a process to terminate, as well as a race-free API for sending UNIX signals to a subprocess.
One major advantage that GIO brings over the core GLib library is comprehensive API for asynchronous I/O, such
g_output_stream_splice_async()
. This makes GSubprocess significantly more powerful and flexible than equivalent APIs in some other languages such as thesubprocess.py
included with Python. For example, usingGSubprocess
one could create two child processes, reading standard output from the first, processing it, and writing to the input stream of the second, all without blocking the main loop.A powerful
g_subprocess_communicate()
API is provided similar to thecommunicate()
method ofsubprocess.py
. This enables very easy interaction with a subprocess that has been opened with pipes.GSubprocess
defaults to tight control over the file descriptors open in the child process, avoiding dangling-fd issues that are caused by a simplefork()
/exec()
. The only open file descriptors in the spawned process are ones that were explicitly specified by theGSubprocess
API (unlessG_SUBPROCESS_FLAGS_INHERIT_FDS
was specified).GSubprocess
will quickly reap all child processes as they exit, avoiding “zombie processes” remaining around for long periods of time.g_subprocess_wait()
can be used to wait for this to happen, but it will happen even without the call being explicitly made.As a matter of principle,
GSubprocess
has no API that accepts shell-style space-separated strings. It will, however, match the typical shell behaviour of searching the PATH for executables that do not contain a directory separator in their name.GSubprocess
attempts to have a very simple API for most uses (ie: spawning a subprocess with arguments and support for most typical kinds of input and output redirection). Seeg_subprocess_new()
. TheGSubprocessLauncher
API is provided for more complicated cases (advanced types of redirection, environment variable manipulation, change of working directory, child setup functions, etc).A typical use of
See moreGSubprocess
will involve callingg_subprocess_new()
, followed byg_subprocess_wait_async()
org_subprocess_wait()
. After the process exits, the status can be checked using functions such asg_subprocess_get_if_exited()
(which are similar to the familiar WIFEXITED-style POSIX macros).Declaration
Swift
open class Subprocess : Object, SubprocessProtocol
-
The
SubprocessLauncher
type acts as a reference-counted owner of an underlyingGSubprocessLauncher
instance. It provides the methods that can operate on this data type throughSubprocessLauncherProtocol
conformance. UseSubprocessLauncher
as a strong reference or owner of aGSubprocessLauncher
instance.This class contains a set of options for launching child processes, such as where its standard input and output will be directed, the argument list, the environment, and more.
While the
See moreGSubprocess
class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration.Declaration
Swift
open class SubprocessLauncher : Object, SubprocessLauncherProtocol
-
The
Task
type acts as a reference-counted owner of an underlyingGTask
instance. It provides the methods that can operate on this data type throughTaskProtocol
conformance. UseTask
as a strong reference or owner of aGTask
instance.A
GTask
represents and manages a cancellable “task”.Asynchronous operations
The most common usage of
GTask
is as aGAsyncResult
, to manage data during an asynchronous operation. You callg_task_new()
in the “start” method, followed byg_task_set_task_data()
and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such asg_task_return_pointer()
org_task_return_error()
, which will save the value you give it and then invoke the task’s callback function in the thread-default main context where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass theGTask
back to the operation’s finish function (as aGAsyncResult
), and you can useg_task_propagate_pointer()
or the like to extract the return value.Here is an example for using GTask as a GAsyncResult: (C Language Example):
typedef struct { CakeFrostingType frosting; char *message; } DecorationData; static void decoration_data_free (DecorationData *decoration) { g_free (decoration->message); g_slice_free (DecorationData, decoration); } static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; DecorationData *decoration = g_task_get_task_data (task); GError *error = NULL; if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; } if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) { g_object_unref (cake); // g_task_return_error() takes ownership of error g_task_return_error (task, error); g_object_unref (task); return; } g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; DecorationData *decoration; Cake *cake; task = g_task_new (self, cancellable, callback, user_data); if (radius < 3) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, "%ucm radius cakes are silly", radius); g_object_unref (task); return; } cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); if (cake != NULL) { // _baker_get_cached_cake() returns a reffed cake g_task_return_pointer (task, cake, g_object_unref); g_object_unref (task); return; } decoration = g_slice_new (DecorationData); decoration->frosting = frosting; decoration->message = g_strdup (message); g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); }
Chained asynchronous operations
GTask
also tries to simplify asynchronous operations that internally chain together several smaller asynchronous operations.g_task_get_cancellable()
,g_task_get_context()
, andg_task_get_priority()
allow you to get back the task’sGCancellable
,GMainContext
, and I/O priority when starting a new subtask, so you don’t have to keep track of them yourself.g_task_attach_source()
simplifies the case of waiting for a source to fire (automatically using the correctGMainContext
and priority).Here is an example for chained asynchronous operations:
(C Language Example):
typedef struct { Cake *cake; CakeFrostingType frosting; char *message; } BakingData; static void decoration_data_free (BakingData *bd) { if (bd->cake) g_object_unref (bd->cake); g_free (bd->message); g_slice_free (BakingData, bd); } static void decorated_cb (Cake *cake, GAsyncResult *result, gpointer user_data) { GTask *task = user_data; GError *error = NULL; if (!cake_decorate_finish (cake, result, &error)) { g_object_unref (cake); g_task_return_error (task, error); g_object_unref (task); return; } // baking_data_free() will drop its ref on the cake, so we have to // take another here to give to the caller. g_task_return_pointer (task, g_object_ref (cake), g_object_unref); g_object_unref (task); } static gboolean decorator_ready (gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task); cake_decorate_async (bd->cake, bd->frosting, bd->message, g_task_get_cancellable (task), decorated_cb, task); return G_SOURCE_REMOVE; } static void baked_cb (Cake *cake, gpointer user_data) { GTask *task = user_data; BakingData *bd = g_task_get_task_data (task); GError *error = NULL; if (cake == NULL) { g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, "Go to the supermarket"); g_object_unref (task); return; } bd->cake = cake; // Bail out now if the user has already cancelled if (g_task_return_error_if_cancelled (task)) { g_object_unref (task); return; } if (cake_decorator_available (cake)) decorator_ready (task); else { GSource *source; source = cake_decorator_wait_source_new (cake); // Attach @source to @task's GMainContext and have it call // decorator_ready() when it is ready. g_task_attach_source (task, source, decorator_ready); g_source_unref (source); } } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, gint priority, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { GTask *task; BakingData *bd; task = g_task_new (self, cancellable, callback, user_data); g_task_set_priority (task, priority); bd = g_slice_new0 (BakingData); bd->frosting = frosting; bd->message = g_strdup (message); g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); }
Asynchronous operations from synchronous ones
You can use
g_task_run_in_thread()
to turn a synchronous operation into an asynchronous one, by running it in a thread. When it completes, the result will be dispatched to the thread-default main context where theGTask
was created.Running a task in a thread:
(C Language Example):
typedef struct { guint radius; CakeFlavor flavor; CakeFrostingType frosting; char *message; } CakeData; static void cake_data_free (CakeData *cake_data) { g_free (cake_data->message); g_slice_free (CakeData, cake_data); } static void bake_cake_thread (GTask *task, gpointer source_object, gpointer task_data, GCancellable *cancellable) { Baker *self = source_object; CakeData *cake_data = task_data; Cake *cake; GError *error = NULL; cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, cancellable, &error); if (cake) g_task_return_pointer (task, cake, g_object_unref); else g_task_return_error (task, error); } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task; cake_data = g_slice_new (CakeData); cake_data->radius = radius; cake_data->flavor = flavor; cake_data->frosting = frosting; cake_data->message = g_strdup (message); task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_run_in_thread (task, bake_cake_thread); g_object_unref (task); } Cake * baker_bake_cake_finish (Baker *self, GAsyncResult *result, GError **error) { g_return_val_if_fail (g_task_is_valid (result, self), NULL); return g_task_propagate_pointer (G_TASK (result), error); }
Adding cancellability to uncancellable tasks
Finally,
g_task_run_in_thread()
andg_task_run_in_thread_sync()
can be used to turn an uncancellable operation into a cancellable one. If you callg_task_set_return_on_cancel()
, passingtrue
, then if the task’sGCancellable
is cancelled, it will return control back to the caller immediately, while allowing the task thread to continue running in the background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you to make “GLib-friendly” asynchronous and cancellable synchronous variants of blocking APIs.Cancelling a task:
(C Language Example):
static void bake_cake_thread (GTask *task, gpointer source_object, gpointer task_data, GCancellable *cancellable) { Baker *self = source_object; CakeData *cake_data = task_data; Cake *cake; GError *error = NULL; cake = bake_cake (baker, cake_data->radius, cake_data->flavor, cake_data->frosting, cake_data->message, &error); if (error) { g_task_return_error (task, error); return; } // If the task has already been cancelled, then we don't want to add // the cake to the cake cache. Likewise, we don't want to have the // task get cancelled in the middle of updating the cache. // g_task_set_return_on_cancel() will return %TRUE here if it managed // to disable return-on-cancel, or %FALSE if the task was cancelled // before it could. if (g_task_set_return_on_cancel (task, FALSE)) { // If the caller cancels at this point, their // GAsyncReadyCallback won't be invoked until we return, // so we don't have to worry that this code will run at // the same time as that code does. But if there were // other functions that might look at the cake cache, // then we'd probably need a GMutex here as well. baker_add_cake_to_cache (baker, cake); g_task_return_pointer (task, cake, g_object_unref); } } void baker_bake_cake_async (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data) { CakeData *cake_data; GTask *task; cake_data = g_slice_new (CakeData); ... task = g_task_new (self, cancellable, callback, user_data); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread (task, bake_cake_thread); } Cake * baker_bake_cake_sync (Baker *self, guint radius, CakeFlavor flavor, CakeFrostingType frosting, const char *message, GCancellable *cancellable, GError **error) { CakeData *cake_data; GTask *task; Cake *cake; cake_data = g_slice_new (CakeData); ... task = g_task_new (self, cancellable, NULL, NULL); g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); g_task_set_return_on_cancel (task, TRUE); g_task_run_in_thread_sync (task, bake_cake_thread); cake = g_task_propagate_pointer (task, error); g_object_unref (task); return cake; }
Porting from GSimpleAsyncResult
GTask
‘s API attempts to be simpler thanGSimpleAsyncResult
’s in several ways:- You can save task-specific data with
g_task_set_task_data()
, and retrieve it later withg_task_get_task_data()
. This replaces the abuse ofg_simple_async_result_set_op_res_gpointer()
for the same purpose withGSimpleAsyncResult
. - In addition to the task data,
GTask
also keeps track of the priority,GCancellable
, andGMainContext
associated with the task, so tasks that consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task. g_task_return_error_if_cancelled()
provides simplified handling for cancellation. In addition, cancellation overrides any otherGTask
return value by default, likeGSimpleAsyncResult
does wheng_simple_async_result_set_check_cancellable()
is called. (You can useg_task_set_check_cancellable()
to turn off that behavior.) On the other hand,g_task_run_in_thread()
guarantees that it will always run yourtask_func
, even if the task’sGCancellable
is already cancelled before the task gets a chance to run; you can start yourtask_func
with ag_task_return_error_if_cancelled()
check if you need the old behavior.- The “return” methods (eg,
g_task_return_pointer()
) automatically cause the task to be “completed” as well, and there is no need to worry about the “complete” vs “complete in idle” distinction. (GTask
automatically figures out whether the task’s callback can be invoked directly, or if it needs to be sent to anotherGMainContext
, or delayed until the next iteration of the currentGMainContext
.) - The “finish” functions for
GTask
based operations are generally much simpler thanGSimpleAsyncResult
ones, normally consisting of only a single call tog_task_propagate_pointer()
or the like. Sinceg_task_propagate_pointer()
“steals” the return value from theGTask
, it is not necessary to juggle pointers around to prevent it from being freed twice. - With
GSimpleAsyncResult
, it was common to callg_simple_async_result_propagate_error()
from the_finish()
wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it difficult for a subclass to chain to a parent class’s async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriateg_task_propagate_
function. Note that wrapper methods can now useg_async_result_legacy_propagate_error()
to do old-styleGSimpleAsyncResult
error-returning behavior, andg_async_result_is_tagged()
to check if a result is tagged as having come from the_async()
wrapper function (for “short-circuit” results, such as when passing 0 tog_input_stream_read_async()
).
Declaration
Swift
open class Task : Object, TaskProtocol
- You can save task-specific data with
-
The
SettingsBackendClass
type acts as an owner of an underlyingGSettingsBackendClass
instance. It provides the methods that can operate on this data type throughSettingsBackendClassProtocol
conformance. UseSettingsBackendClass
as a strong reference or owner of aGSettingsBackendClass
instance.Class structure for
See moreGSettingsBackend
.Declaration
Swift
open class SettingsBackendClass : SettingsBackendClassProtocol
-
The
See moreSettingsBackendPrivate
type acts as an owner of an underlyingGSettingsBackendPrivate
instance. It provides the methods that can operate on this data type throughSettingsBackendPrivateProtocol
conformance. UseSettingsBackendPrivate
as a strong reference or owner of aGSettingsBackendPrivate
instance.Declaration
Swift
open class SettingsBackendPrivate : SettingsBackendPrivateProtocol
-
The
See moreSettingsClass
type acts as an owner of an underlyingGSettingsClass
instance. It provides the methods that can operate on this data type throughSettingsClassProtocol
conformance. UseSettingsClass
as a strong reference or owner of aGSettingsClass
instance.Declaration
Swift
open class SettingsClass : SettingsClassProtocol
-
The
See moreSettingsPrivate
type acts as an owner of an underlyingGSettingsPrivate
instance. It provides the methods that can operate on this data type throughSettingsPrivateProtocol
conformance. UseSettingsPrivate
as a strong reference or owner of aGSettingsPrivate
instance.Declaration
Swift
open class SettingsPrivate : SettingsPrivateProtocol
-
The
SettingsSchema
type acts as a reference-counted owner of an underlyingGSettingsSchema
instance. It provides the methods that can operate on this data type throughSettingsSchemaProtocol
conformance. UseSettingsSchema
as a strong reference or owner of aGSettingsSchema
instance.The
GSettingsSchemaSource
andGSettingsSchema
APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content.Plugin loading systems that wish to provide plugins a way to access settings face the problem of how to make the schemas for these settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won’t be installed into the standard system directories for schemas.
GSettingsSchemaSource
provides a mechanism for dealing with this by allowing the creation of a new ‘schema source’ from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings.Consider the following example:
(C Language Example):
typedef struct { ... GSettingsSchemaSource *schema_source; ... } Plugin; Plugin * initialise_plugin (const gchar *dir) { Plugin *plugin; ... plugin->schema_source = g_settings_schema_source_new_from_directory (dir, g_settings_schema_source_get_default (), FALSE, NULL); ... return plugin; } ... GSettings * plugin_get_settings (Plugin *plugin, const gchar *schema_id) { GSettingsSchema *schema; if (schema_id == NULL) schema_id = plugin->identifier; schema = g_settings_schema_source_lookup (plugin->schema_source, schema_id, FALSE); if (schema == NULL) { ... disable the plugin or abort, etc ... } return g_settings_new_full (schema, NULL, NULL); }
The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and how an API can be added to the plugin system to provide a convenient way for the plugin to access its settings, using the schemas that it ships.
From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following:
(C Language Example):
{ GSettings *settings; gint some_value; settings = plugin_get_settings (self, NULL); some_value = g_settings_get_int (settings, "some-value"); ... }
It’s also possible that the plugin system expects the schema source files (ie: .gschema.xml files) instead of a gschemas.compiled file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source.
See moreDeclaration
Swift
open class SettingsSchema : SettingsSchemaProtocol
-
The
SettingsSchemaKey
type acts as a reference-counted owner of an underlyingGSettingsSchemaKey
instance. It provides the methods that can operate on this data type throughSettingsSchemaKeyProtocol
conformance. UseSettingsSchemaKey
as a strong reference or owner of aGSettingsSchemaKey
instance.
See moreGSettingsSchemaKey
is an opaque data structure and can only be accessed using the following functions.Declaration
Swift
open class SettingsSchemaKey : SettingsSchemaKeyProtocol
-
The
SettingsSchemaSource
type acts as a reference-counted owner of an underlyingGSettingsSchemaSource
instance. It provides the methods that can operate on this data type throughSettingsSchemaSourceProtocol
conformance. UseSettingsSchemaSource
as a strong reference or owner of aGSettingsSchemaSource
instance.This is an opaque structure type. You may not access it directly.
See moreDeclaration
Swift
open class SettingsSchemaSource : SettingsSchemaSourceProtocol
-
The
See moreSimpleActionGroupClass
type acts as an owner of an underlyingGSimpleActionGroupClass
instance. It provides the methods that can operate on this data type throughSimpleActionGroupClassProtocol
conformance. UseSimpleActionGroupClass
as a strong reference or owner of aGSimpleActionGroupClass
instance.Declaration
Swift
open class SimpleActionGroupClass : SimpleActionGroupClassProtocol
-
The
See moreSimpleActionGroupPrivate
type acts as an owner of an underlyingGSimpleActionGroupPrivate
instance. It provides the methods that can operate on this data type throughSimpleActionGroupPrivateProtocol
conformance. UseSimpleActionGroupPrivate
as a strong reference or owner of aGSimpleActionGroupPrivate
instance.Declaration
Swift
open class SimpleActionGroupPrivate : SimpleActionGroupPrivateProtocol
-
The
See moreSimpleAsyncResultClass
type acts as an owner of an underlyingGSimpleAsyncResultClass
instance. It provides the methods that can operate on this data type throughSimpleAsyncResultClassProtocol
conformance. UseSimpleAsyncResultClass
as a strong reference or owner of aGSimpleAsyncResultClass
instance.Declaration
Swift
open class SimpleAsyncResultClass : SimpleAsyncResultClassProtocol
-
The
See moreSimpleProxyResolverClass
type acts as an owner of an underlyingGSimpleProxyResolverClass
instance. It provides the methods that can operate on this data type throughSimpleProxyResolverClassProtocol
conformance. UseSimpleProxyResolverClass
as a strong reference or owner of aGSimpleProxyResolverClass
instance.Declaration
Swift
open class SimpleProxyResolverClass : SimpleProxyResolverClassProtocol
-
The
See moreSimpleProxyResolverPrivate
type acts as an owner of an underlyingGSimpleProxyResolverPrivate
instance. It provides the methods that can operate on this data type throughSimpleProxyResolverPrivateProtocol
conformance. UseSimpleProxyResolverPrivate
as a strong reference or owner of aGSimpleProxyResolverPrivate
instance.Declaration
Swift
open class SimpleProxyResolverPrivate : SimpleProxyResolverPrivateProtocol
-
The
See moreSocketAddressClass
type acts as an owner of an underlyingGSocketAddressClass
instance. It provides the methods that can operate on this data type throughSocketAddressClassProtocol
conformance. UseSocketAddressClass
as a strong reference or owner of aGSocketAddressClass
instance.Declaration
Swift
open class SocketAddressClass : SocketAddressClassProtocol
-
The
SocketAddressEnumeratorClass
type acts as an owner of an underlyingGSocketAddressEnumeratorClass
instance. It provides the methods that can operate on this data type throughSocketAddressEnumeratorClassProtocol
conformance. UseSocketAddressEnumeratorClass
as a strong reference or owner of aGSocketAddressEnumeratorClass
instance.Class structure for
See moreGSocketAddressEnumerator
.Declaration
Swift
open class SocketAddressEnumeratorClass : SocketAddressEnumeratorClassProtocol
-
The
See moreSocketClass
type acts as an owner of an underlyingGSocketClass
instance. It provides the methods that can operate on this data type throughSocketClassProtocol
conformance. UseSocketClass
as a strong reference or owner of aGSocketClass
instance.Declaration
Swift
open class SocketClass : SocketClassProtocol
-
The
See moreSocketClientClass
type acts as an owner of an underlyingGSocketClientClass
instance. It provides the methods that can operate on this data type throughSocketClientClassProtocol
conformance. UseSocketClientClass
as a strong reference or owner of aGSocketClientClass
instance.Declaration
Swift
open class SocketClientClass : SocketClientClassProtocol
-
The
See moreSocketClientPrivate
type acts as an owner of an underlyingGSocketClientPrivate
instance. It provides the methods that can operate on this data type throughSocketClientPrivateProtocol
conformance. UseSocketClientPrivate
as a strong reference or owner of aGSocketClientPrivate
instance.Declaration
Swift
open class SocketClientPrivate : SocketClientPrivateProtocol
-
The
SocketConnectableIface
type acts as an owner of an underlyingGSocketConnectableIface
instance. It provides the methods that can operate on this data type throughSocketConnectableIfaceProtocol
conformance. UseSocketConnectableIface
as a strong reference or owner of aGSocketConnectableIface
instance.Provides an interface for returning a
See moreGSocketAddressEnumerator
andGProxyAddressEnumerator
Declaration
Swift
open class SocketConnectableIface : SocketConnectableIfaceProtocol
-
The
See moreSocketConnectionClass
type acts as an owner of an underlyingGSocketConnectionClass
instance. It provides the methods that can operate on this data type throughSocketConnectionClassProtocol
conformance. UseSocketConnectionClass
as a strong reference or owner of aGSocketConnectionClass
instance.Declaration
Swift
open class SocketConnectionClass : SocketConnectionClassProtocol
-
The
See moreSocketConnectionPrivate
type acts as an owner of an underlyingGSocketConnectionPrivate
instance. It provides the methods that can operate on this data type throughSocketConnectionPrivateProtocol
conformance. UseSocketConnectionPrivate
as a strong reference or owner of aGSocketConnectionPrivate
instance.Declaration
Swift
open class SocketConnectionPrivate : SocketConnectionPrivateProtocol
-
The
SocketControlMessageClass
type acts as an owner of an underlyingGSocketControlMessageClass
instance. It provides the methods that can operate on this data type throughSocketControlMessageClassProtocol
conformance. UseSocketControlMessageClass
as a strong reference or owner of aGSocketControlMessageClass
instance.Class structure for
See moreGSocketControlMessage
.Declaration
Swift
open class SocketControlMessageClass : SocketControlMessageClassProtocol
-
The
See moreSocketControlMessagePrivate
type acts as an owner of an underlyingGSocketControlMessagePrivate
instance. It provides the methods that can operate on this data type throughSocketControlMessagePrivateProtocol
conformance. UseSocketControlMessagePrivate
as a strong reference or owner of aGSocketControlMessagePrivate
instance.Declaration
Swift
open class SocketControlMessagePrivate : SocketControlMessagePrivateProtocol
-
The
SocketListenerClass
type acts as an owner of an underlyingGSocketListenerClass
instance. It provides the methods that can operate on this data type throughSocketListenerClassProtocol
conformance. UseSocketListenerClass
as a strong reference or owner of aGSocketListenerClass
instance.Class structure for
See moreGSocketListener
.Declaration
Swift
open class SocketListenerClass : SocketListenerClassProtocol
-
The
See moreSocketListenerPrivate
type acts as an owner of an underlyingGSocketListenerPrivate
instance. It provides the methods that can operate on this data type throughSocketListenerPrivateProtocol
conformance. UseSocketListenerPrivate
as a strong reference or owner of aGSocketListenerPrivate
instance.Declaration
Swift
open class SocketListenerPrivate : SocketListenerPrivateProtocol
-
The
See moreSocketPrivate
type acts as an owner of an underlyingGSocketPrivate
instance. It provides the methods that can operate on this data type throughSocketPrivateProtocol
conformance. UseSocketPrivate
as a strong reference or owner of aGSocketPrivate
instance.Declaration
Swift
open class SocketPrivate : SocketPrivateProtocol
-
The
SocketServiceClass
type acts as an owner of an underlyingGSocketServiceClass
instance. It provides the methods that can operate on this data type throughSocketServiceClassProtocol
conformance. UseSocketServiceClass
as a strong reference or owner of aGSocketServiceClass
instance.Class structure for
See moreGSocketService
.Declaration
Swift
open class SocketServiceClass : SocketServiceClassProtocol
-
The
See moreSocketServicePrivate
type acts as an owner of an underlyingGSocketServicePrivate
instance. It provides the methods that can operate on this data type throughSocketServicePrivateProtocol
conformance. UseSocketServicePrivate
as a strong reference or owner of aGSocketServicePrivate
instance.Declaration
Swift
open class SocketServicePrivate : SocketServicePrivateProtocol
-
The
SrvTarget
type acts as an owner of an underlyingGSrvTarget
instance. It provides the methods that can operate on this data type throughSrvTargetProtocol
conformance. UseSrvTarget
as a strong reference or owner of aGSrvTarget
instance.SRV (service) records are used by some network protocols to provide service-specific aliasing and load-balancing. For example, XMPP (Jabber) uses SRV records to locate the XMPP server for a domain; rather than connecting directly to “example.com” or assuming a specific server hostname like “xmpp.example.com”, an XMPP client would look up the “xmpp-client” SRV record for “example.com”, and then connect to whatever host was pointed to by that record.
You can use
See moreg_resolver_lookup_service()
org_resolver_lookup_service_async()
to find theGSrvTargets
for a given service. However, if you are simply planning to connect to the remote service, you can useGNetworkService
‘sGSocketConnectable
interface and not need to worry aboutGSrvTarget
at all.Declaration
Swift
open class SrvTarget : SrvTargetProtocol
-
The
StaticResource
type acts as an owner of an underlyingGStaticResource
instance. It provides the methods that can operate on this data type throughStaticResourceProtocol
conformance. UseStaticResource
as a strong reference or owner of aGStaticResource
instance.
See moreGStaticResource
is an opaque data structure and can only be accessed using the following functions.Declaration
Swift
open class StaticResource : StaticResourceProtocol
-
The
See moreTaskClass
type acts as an owner of an underlyingGTaskClass
instance. It provides the methods that can operate on this data type throughTaskClassProtocol
conformance. UseTaskClass
as a strong reference or owner of aGTaskClass
instance.Declaration
Swift
open class TaskClass : TaskClassProtocol
-
The
TcpConnection
type acts as a reference-counted owner of an underlyingGTcpConnection
instance. It provides the methods that can operate on this data type throughTcpConnectionProtocol
conformance. UseTcpConnection
as a strong reference or owner of aGTcpConnection
instance.This is the subclass of
See moreGSocketConnection
that is created for TCP/IP sockets.Declaration
Swift