gio

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2024 License: MPL-2.0 Imports: 13 Imported by: 81

Documentation

Index

Constants

View Source 
const DBUS_METHOD_INVOCATION_HANDLED = true

DBUS_METHOD_INVOCATION_HANDLED: value returned by handlers of the signals generated by the gdbus-codegen tool to indicate that a method call has been handled by an implementation. It is equal to TRUE, but using this macro is sometimes more readable.

In code that needs to be backwards-compatible with older GLib, use TRUE instead, often written like this: 

g_dbus_method_invocation_return_error (invocation, ...);
return TRUE;    // handled.
View Source 
const DBUS_METHOD_INVOCATION_UNHANDLED = false

DBUS_METHOD_INVOCATION_UNHANDLED: value returned by handlers of the signals generated by the gdbus-codegen tool to indicate that a method call has not been handled by an implementation. It is equal to FALSE, but using this macro is sometimes more readable.

In code that needs to be backwards-compatible with older GLib, use FALSE instead.

View Source 
const DEBUG_CONTROLLER_EXTENSION_POINT_NAME = "gio-debug-controller"

DEBUG_CONTROLLER_EXTENSION_POINT_NAME: extension point for debug control functionality. See [Extending GIO][extending-gio].

View Source 
const DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME = "gio-desktop-app-info-lookup"

DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME: extension point for default handler to URI association. See [Extending GIO][extending-gio].

Deprecated: The AppInfoLookup interface is deprecated and unused by GIO.

View Source 
const DRIVE_IDENTIFIER_KIND_UNIX_DEVICE = "unix-device"

DRIVE_IDENTIFIER_KIND_UNIX_DEVICE: string used to obtain a Unix device path with g_drive_get_identifier().

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_DELETE = "access::can-delete"

FILE_ATTRIBUTE_ACCESS_CAN_DELETE: key in the "access" namespace for checking deletion privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to delete the file.

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE = "access::can-execute"

FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: key in the "access" namespace for getting execution privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to execute the file.

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_READ = "access::can-read"

FILE_ATTRIBUTE_ACCESS_CAN_READ: key in the "access" namespace for getting read privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to read the file.

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_RENAME = "access::can-rename"

FILE_ATTRIBUTE_ACCESS_CAN_RENAME: key in the "access" namespace for checking renaming privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to rename the file.

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_TRASH = "access::can-trash"

FILE_ATTRIBUTE_ACCESS_CAN_TRASH: key in the "access" namespace for checking trashing privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to move the file to the trash.

View Source 
const FILE_ATTRIBUTE_ACCESS_CAN_WRITE = "access::can-write"

FILE_ATTRIBUTE_ACCESS_CAN_WRITE: key in the "access" namespace for getting write privileges.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

This attribute will be TRUE if the user is able to write to the file.

View Source 
const FILE_ATTRIBUTE_DOS_IS_ARCHIVE = "dos::is-archive"

FILE_ATTRIBUTE_DOS_IS_ARCHIVE: key in the "dos" namespace for checking if the file's archive flag is set.

This attribute is TRUE if the archive flag is set.

This attribute is only available for DOS file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_DOS_IS_MOUNTPOINT = "dos::is-mountpoint"

FILE_ATTRIBUTE_DOS_IS_MOUNTPOINT: key in the "dos" namespace for checking if the file is a NTFS mount point (a volume mount or a junction point).

This attribute is TRUE if file is a reparse point of type IO_REPARSE_TAG_MOUNT_POINT (https://msdn.microsoft.com/en-us/library/dd541667.aspx).

This attribute is only available for DOS file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_DOS_IS_SYSTEM = "dos::is-system"

FILE_ATTRIBUTE_DOS_IS_SYSTEM: key in the "dos" namespace for checking if the file's backup flag is set.

This attribute is TRUE if the backup flag is set.

This attribute is only available for DOS file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG = "dos::reparse-point-tag"

FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG: key in the "dos" namespace for getting the file NTFS reparse tag.

This value is 0 for files that are not reparse points.

See the Reparse Tags (https://msdn.microsoft.com/en-us/library/dd541667.aspx) page for possible reparse tag values.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_ETAG_VALUE = "etag::value"

FILE_ATTRIBUTE_ETAG_VALUE: key in the "etag" namespace for getting the value of the file's entity tag.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_FREE = "filesystem::free"

FILE_ATTRIBUTE_FILESYSTEM_FREE: key in the "filesystem" namespace for getting the number of bytes of free space left on the file system.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_READONLY = "filesystem::readonly"

FILE_ATTRIBUTE_FILESYSTEM_READONLY: key in the "filesystem" namespace for checking if the file system is read only.

Is set to TRUE if the file system is read only.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_REMOTE = "filesystem::remote"

FILE_ATTRIBUTE_FILESYSTEM_REMOTE: key in the "filesystem" namespace for checking if the file system is remote.

Is set to TRUE if the file system is remote.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_SIZE = "filesystem::size"

FILE_ATTRIBUTE_FILESYSTEM_SIZE: key in the "filesystem" namespace for getting the total size (in bytes) of the file system, used in g_file_query_filesystem_info().

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_TYPE = "filesystem::type"

FILE_ATTRIBUTE_FILESYSTEM_TYPE: key in the "filesystem" namespace for getting the file system's type.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_USED = "filesystem::used"

FILE_ATTRIBUTE_FILESYSTEM_USED: key in the "filesystem" namespace for getting the number of bytes used by data on the file system.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW = "filesystem::use-preview"

FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW: key in the "filesystem" namespace for hinting a file manager application whether it should preview (e.g. thumbnail) files on the file system.

The value for this key contain a PreviewType.

View Source 
const FILE_ATTRIBUTE_GVFS_BACKEND = "gvfs::backend"

FILE_ATTRIBUTE_GVFS_BACKEND: key in the "gvfs" namespace that gets the name of the current GVFS backend in use.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_ID_FILE = "id::file"

FILE_ATTRIBUTE_ID_FILE: key in the "id" namespace for getting a file identifier.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

An example use would be during listing files, to avoid recursive directory scanning.

View Source 
const FILE_ATTRIBUTE_ID_FILESYSTEM = "id::filesystem"

FILE_ATTRIBUTE_ID_FILESYSTEM: key in the "id" namespace for getting the file system identifier.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

An example use would be during drag and drop to see if the source and target are on the same filesystem (default to move) or not (default to copy).

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT = "mountable::can-eject"

FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT = "mountable::can-mount"

FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL = "mountable::can-poll"

FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_START = "mountable::can-start"

FILE_ATTRIBUTE_MOUNTABLE_CAN_START: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED = "mountable::can-start-degraded"

FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started degraded.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP = "mountable::can-stop"

FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT = "mountable::can-unmount"

FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI = "mountable::hal-udi"

FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: key in the "mountable" namespace for getting the HAL UDI for the mountable file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC = "mountable::is-media-check-automatic"

FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC: key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is automatically polled for media.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE = "mountable::start-stop-type"

FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE: key in the "mountable" namespace for getting the StartStopType.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE = "mountable::unix-device"

FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: key in the "mountable" namespace for getting the unix device.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE = "mountable::unix-device-file"

FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE: key in the "mountable" namespace for getting the unix device file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_OWNER_GROUP = "owner::group"

FILE_ATTRIBUTE_OWNER_GROUP: key in the "owner" namespace for getting the file owner's group.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_OWNER_USER = "owner::user"

FILE_ATTRIBUTE_OWNER_USER: key in the "owner" namespace for getting the user name of the file's owner.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_OWNER_USER_REAL = "owner::user-real"

FILE_ATTRIBUTE_OWNER_USER_REAL: key in the "owner" namespace for getting the real name of the user that owns the file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_PREVIEW_ICON = "preview::icon"

FILE_ATTRIBUTE_PREVIEW_ICON: key in the "preview" namespace for getting a #GIcon that can be used to get preview of the file.

For example, it may be a low resolution thumbnail without metadata.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_OBJECT.

The value for this key should contain a #GIcon.

View Source 
const FILE_ATTRIBUTE_RECENT_MODIFIED = "recent::modified"

FILE_ATTRIBUTE_RECENT_MODIFIED: key in the "recent" namespace for getting time, when the metadata for the file in recent:/// was last changed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_INT64.

View Source 
const FILE_ATTRIBUTE_SELINUX_CONTEXT = "selinux::context"

FILE_ATTRIBUTE_SELINUX_CONTEXT: key in the "selinux" namespace for getting the file's SELinux context.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

Note that this attribute is only available if GLib has been built with SELinux support.

View Source 
const FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE = "standard::allocated-size"

FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE: key in the "standard" namespace for getting the amount of disk space that is consumed by the file (in bytes).

This will generally be larger than the file size (due to block size overhead) but can occasionally be smaller (for example, for sparse files).

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE = "standard::content-type"

FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE: key in the "standard" namespace for getting the content type of the file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

The value for this key should contain a valid content type.

View Source 
const FILE_ATTRIBUTE_STANDARD_COPY_NAME = "standard::copy-name"

FILE_ATTRIBUTE_STANDARD_COPY_NAME: key in the "standard" namespace for getting the copy name of the file.

The copy name is an optional version of the name. If available it's always in UTF8, and corresponds directly to the original filename (only transcoded to UTF8). This is useful if you want to copy the file to another filesystem that might have a different encoding. If the filename is not a valid string in the encoding selected for the filesystem it is in then the copy name will not be set.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_DESCRIPTION = "standard::description"

FILE_ATTRIBUTE_STANDARD_DESCRIPTION: key in the "standard" namespace for getting the description of the file.

The description is a utf8 string that describes the file, generally containing the filename, but can also contain further information. Example descriptions could be "filename (on hostname)" for a remote file or "filename (in trash)" for a file in the trash. This is useful for instance as the window title when displaying a directory or for a bookmarks menu.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME = "standard::display-name"

FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME: key in the "standard" namespace for getting the display name of the file.

A display name is guaranteed to be in UTF-8 and can thus be displayed in the UI. It is guaranteed to be set on every file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_EDIT_NAME = "standard::edit-name"

FILE_ATTRIBUTE_STANDARD_EDIT_NAME: key in the "standard" namespace for edit name of the file.

An edit name is similar to the display name, but it is meant to be used when you want to rename the file in the UI. The display name might contain information you don't want in the new filename (such as "(invalid unicode)" if the filename was in an invalid encoding).

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE = "standard::fast-content-type"

FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE: key in the "standard" namespace for getting the fast content type.

The fast content type isn't as reliable as the regular one, as it only uses the filename to guess it, but it is faster to calculate than the regular content type.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_ICON = "standard::icon"

FILE_ATTRIBUTE_STANDARD_ICON: key in the "standard" namespace for getting the icon for the file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_OBJECT.

The value for this key should contain a #GIcon.

View Source 
const FILE_ATTRIBUTE_STANDARD_IS_BACKUP = "standard::is-backup"

FILE_ATTRIBUTE_STANDARD_IS_BACKUP: key in the "standard" namespace for checking if a file is a backup file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_STANDARD_IS_HIDDEN = "standard::is-hidden"

FILE_ATTRIBUTE_STANDARD_IS_HIDDEN: key in the "standard" namespace for checking if a file is hidden.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_STANDARD_IS_SYMLINK = "standard::is-symlink"

FILE_ATTRIBUTE_STANDARD_IS_SYMLINK: key in the "standard" namespace for checking if the file is a symlink. Typically the actual type is something else, if we followed the symlink to get the type.

On Windows NTFS mountpoints are considered to be symlinks as well.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL = "standard::is-virtual"

FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL: key in the "standard" namespace for checking if a file is virtual.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_STANDARD_IS_VOLATILE = "standard::is-volatile"

FILE_ATTRIBUTE_STANDARD_IS_VOLATILE: key in the "standard" namespace for checking if a file is volatile. This is meant for opaque, non-POSIX-like backends to indicate that the URI is not persistent. Applications should look at G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_STANDARD_NAME = "standard::name"

FILE_ATTRIBUTE_STANDARD_NAME: key in the "standard" namespace for getting the name of the file.

The name is the on-disk filename which may not be in any known encoding, and can thus not be generally displayed as is. It is guaranteed to be set on every file.

Use G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user interface.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_SIZE = "standard::size"

FILE_ATTRIBUTE_STANDARD_SIZE: key in the "standard" namespace for getting the file's size (in bytes).

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_STANDARD_SORT_ORDER = "standard::sort-order"

FILE_ATTRIBUTE_STANDARD_SORT_ORDER: key in the "standard" namespace for setting the sort order of a file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_INT32.

An example use would be in file managers, which would use this key to set the order files are displayed. Files with smaller sort order should be sorted first, and files without sort order as if sort order was zero.

View Source 
const FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON = "standard::symbolic-icon"

FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON: key in the "standard" namespace for getting the symbolic icon for the file.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_OBJECT.

The value for this key should contain a #GIcon.

View Source 
const FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET = "standard::symlink-target"

FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET: key in the "standard" namespace for getting the symlink target, if the file is a symlink.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_TARGET_URI = "standard::target-uri"

FILE_ATTRIBUTE_STANDARD_TARGET_URI: key in the "standard" namespace for getting the target URI for the file, in the case of G_FILE_TYPE_SHORTCUT or G_FILE_TYPE_MOUNTABLE files.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_STANDARD_TYPE = "standard::type"

FILE_ATTRIBUTE_STANDARD_TYPE: key in the "standard" namespace for storing file types.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

The value for this key should contain a Type.

View Source 
const FILE_ATTRIBUTE_THUMBNAILING_FAILED = "thumbnail::failed"

FILE_ATTRIBUTE_THUMBNAILING_FAILED: key in the "thumbnail" namespace for checking if thumbnailing failed.

This attribute is TRUE if thumbnailing failed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE = "thumbnail::failed-large"

FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE: key in the "thumbnail" namespace for checking if thumbnailing failed for the large image.

This attribute is TRUE if thumbnailing failed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL = "thumbnail::failed-normal"

FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL: key in the "thumbnail" namespace for checking if thumbnailing failed for the normal image.

This attribute is TRUE if thumbnailing failed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE = "thumbnail::failed-xlarge"

FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE: key in the "thumbnail" namespace for checking if thumbnailing failed for the x-large image.

This attribute is TRUE if thumbnailing failed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE = "thumbnail::failed-xxlarge"

FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE: key in the "thumbnail" namespace for checking if thumbnailing failed for the xx-large image.

This attribute is TRUE if thumbnailing failed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_IS_VALID = "thumbnail::is-valid"

FILE_ATTRIBUTE_THUMBNAIL_IS_VALID: key in the "thumbnail" namespace for checking whether the thumbnail is outdated.

This attribute is TRUE if the thumbnail is up-to-date with the file it represents, and FALSE if the file has been modified since the thumbnail was generated.

If G_FILE_ATTRIBUTE_THUMBNAILING_FAILED is TRUE and this attribute is FALSE, it indicates that thumbnailing may be attempted again and may succeed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_LARGE = "thumbnail::is-valid-large"

FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_LARGE: key in the "thumbnail" namespace for checking whether the large thumbnail is outdated.

This attribute is TRUE if the large thumbnail is up-to-date with the file it represents, and FALSE if the file has been modified since the thumbnail was generated.

If G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_LARGE is TRUE and this attribute is FALSE, it indicates that thumbnailing may be attempted again and may succeed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_NORMAL = "thumbnail::is-valid-normal"

FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_NORMAL: key in the "thumbnail" namespace for checking whether the normal thumbnail is outdated.

This attribute is TRUE if the normal thumbnail is up-to-date with the file it represents, and FALSE if the file has been modified since the thumbnail was generated.

If G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_NORMAL is TRUE and this attribute is FALSE, it indicates that thumbnailing may be attempted again and may succeed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XLARGE = "thumbnail::is-valid-xlarge"

FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XLARGE: key in the "thumbnail" namespace for checking whether the x-large thumbnail is outdated.

This attribute is TRUE if the x-large thumbnail is up-to-date with the file it represents, and FALSE if the file has been modified since the thumbnail was generated.

If G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XLARGE is TRUE and this attribute is FALSE, it indicates that thumbnailing may be attempted again and may succeed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XXLARGE = "thumbnail::is-valid-xxlarge"

FILE_ATTRIBUTE_THUMBNAIL_IS_VALID_XXLARGE: key in the "thumbnail" namespace for checking whether the xx-large thumbnail is outdated.

This attribute is TRUE if the x-large thumbnail is up-to-date with the file it represents, and FALSE if the file has been modified since the thumbnail was generated.

If G_FILE_ATTRIBUTE_THUMBNAILING_FAILED_XXLARGE is TRUE and this attribute is FALSE, it indicates that thumbnailing may be attempted again and may succeed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_PATH = "thumbnail::path"

FILE_ATTRIBUTE_THUMBNAIL_PATH: key in the "thumbnail" namespace for getting the path to the thumbnail image with the biggest size available.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_PATH_LARGE = "thumbnail::path-large"

FILE_ATTRIBUTE_THUMBNAIL_PATH_LARGE: key in the "thumbnail" namespace for getting the path to the large thumbnail image.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_PATH_NORMAL = "thumbnail::path-normal"

FILE_ATTRIBUTE_THUMBNAIL_PATH_NORMAL: key in the "thumbnail" namespace for getting the path to the normal thumbnail image.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_PATH_XLARGE = "thumbnail::path-xlarge"

FILE_ATTRIBUTE_THUMBNAIL_PATH_XLARGE: key in the "thumbnail" namespace for getting the path to the x-large thumbnail image.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_THUMBNAIL_PATH_XXLARGE = "thumbnail::path-xxlarge"

FILE_ATTRIBUTE_THUMBNAIL_PATH_XXLARGE: key in the "thumbnail" namespace for getting the path to the xx-large thumbnail image.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_TIME_ACCESS = "time::access"

FILE_ATTRIBUTE_TIME_ACCESS: key in the "time" namespace for getting the time the file was last accessed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was last accessed, in seconds since the UNIX epoch.

View Source 
const FILE_ATTRIBUTE_TIME_ACCESS_NSEC = "time::access-nsec"

FILE_ATTRIBUTE_TIME_ACCESS_NSEC: key in the "time" namespace for getting the nanoseconds of the time the file was last accessed. This should be used in conjunction with FILE_ATTRIBUTE_TIME_ACCESS. Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_ACCESS_USEC = "time::access-usec"

FILE_ATTRIBUTE_TIME_ACCESS_USEC: key in the "time" namespace for getting the microseconds of the time the file was last accessed.

This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_ACCESS.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_CHANGED = "time::changed"

FILE_ATTRIBUTE_TIME_CHANGED: key in the "time" namespace for getting the time the file was last changed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was last changed, in seconds since the UNIX epoch.

This corresponds to the traditional UNIX ctime.

View Source 
const FILE_ATTRIBUTE_TIME_CHANGED_NSEC = "time::changed-nsec"

FILE_ATTRIBUTE_TIME_CHANGED_NSEC: key in the "time" namespace for getting the nanoseconds of the time the file was last changed. This should be used in conjunction with FILE_ATTRIBUTE_TIME_CHANGED. Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_CHANGED_USEC = "time::changed-usec"

FILE_ATTRIBUTE_TIME_CHANGED_USEC: key in the "time" namespace for getting the microseconds of the time the file was last changed.

This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_CHANGED.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_CREATED = "time::created"

FILE_ATTRIBUTE_TIME_CREATED: key in the "time" namespace for getting the time the file was created.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was created, in seconds since the UNIX epoch.

This may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD st_birthtime or NTFS ctime.

View Source 
const FILE_ATTRIBUTE_TIME_CREATED_NSEC = "time::created-nsec"

FILE_ATTRIBUTE_TIME_CREATED_NSEC: key in the "time" namespace for getting the nanoseconds of the time the file was created. This should be used in conjunction with FILE_ATTRIBUTE_TIME_CREATED. Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_CREATED_USEC = "time::created-usec"

FILE_ATTRIBUTE_TIME_CREATED_USEC: key in the "time" namespace for getting the microseconds of the time the file was created.

This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_CREATED.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_MODIFIED = "time::modified"

FILE_ATTRIBUTE_TIME_MODIFIED: key in the "time" namespace for getting the time the file was last modified.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was modified, in seconds since the UNIX epoch.

View Source 
const FILE_ATTRIBUTE_TIME_MODIFIED_NSEC = "time::modified-nsec"

FILE_ATTRIBUTE_TIME_MODIFIED_NSEC: key in the "time" namespace for getting the nanoseconds of the time the file was last modified. This should be used in conjunction with FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TIME_MODIFIED_USEC = "time::modified-usec"

FILE_ATTRIBUTE_TIME_MODIFIED_USEC: key in the "time" namespace for getting the microseconds of the time the file was last modified.

This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_MODIFIED.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TRASH_DELETION_DATE = "trash::deletion-date"

FILE_ATTRIBUTE_TRASH_DELETION_DATE: key in the "trash" namespace for getting the deletion date and time of a file inside the trash:/// folder.

The format of the returned string is YYYY-MM-DDThh:mm:ss.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_STRING.

View Source 
const FILE_ATTRIBUTE_TRASH_ITEM_COUNT = "trash::item-count"

FILE_ATTRIBUTE_TRASH_ITEM_COUNT: key in the "trash" namespace for getting the number of (toplevel) items that are present in the trash:/// folder.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_TRASH_ORIG_PATH = "trash::orig-path"

FILE_ATTRIBUTE_TRASH_ORIG_PATH: key in the "trash" namespace for getting the original path of a file inside the trash:/// folder before it was trashed.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.

View Source 
const FILE_ATTRIBUTE_UNIX_BLOCKS = "unix::blocks"

FILE_ATTRIBUTE_UNIX_BLOCKS: key in the "unix" namespace for getting the number of blocks allocated for the file.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_UNIX_BLOCK_SIZE = "unix::block-size"

FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: key in the "unix" namespace for getting the block size for the file system.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_DEVICE = "unix::device"

FILE_ATTRIBUTE_UNIX_DEVICE: key in the "unix" namespace for getting the device id of the device the file is located on (see stat() documentation).

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_GID = "unix::gid"

FILE_ATTRIBUTE_UNIX_GID: key in the "unix" namespace for getting the group ID for the file.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_INODE = "unix::inode"

FILE_ATTRIBUTE_UNIX_INODE: key in the "unix" namespace for getting the inode of the file.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT64.

View Source 
const FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT = "unix::is-mountpoint"

FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: key in the "unix" namespace for checking if the file represents a UNIX mount point.

This attribute is TRUE if the file is a UNIX mount point.

Since 2.58, / is considered to be a mount point.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_BOOLEAN.

View Source 
const FILE_ATTRIBUTE_UNIX_MODE = "unix::mode"

FILE_ATTRIBUTE_UNIX_MODE: key in the "unix" namespace for getting the mode of the file (e.g. whether the file is a regular file, symlink, etc).

See the documentation for lstat(): this attribute is equivalent to the st_mode member of struct stat, and includes both the file type and permissions.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_NLINK = "unix::nlink"

FILE_ATTRIBUTE_UNIX_NLINK: key in the "unix" namespace for getting the number of hard links for a file.

See the documentation for lstat().

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_RDEV = "unix::rdev"

FILE_ATTRIBUTE_UNIX_RDEV: key in the "unix" namespace for getting the device ID for the file (if it is a special file).

See the documentation for lstat().

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const FILE_ATTRIBUTE_UNIX_UID = "unix::uid"

FILE_ATTRIBUTE_UNIX_UID: key in the "unix" namespace for getting the user ID for the file.

This attribute is only available for UNIX file systems.

Corresponding AttributeType is G_FILE_ATTRIBUTE_TYPE_UINT32.

View Source 
const MEMORY_MONITOR_EXTENSION_POINT_NAME = "gio-memory-monitor"

MEMORY_MONITOR_EXTENSION_POINT_NAME: extension point for memory usage monitoring functionality. See [Extending GIO][extending-gio].

View Source 
const MENU_ATTRIBUTE_ACTION = "action"

MENU_ATTRIBUTE_ACTION: menu item attribute which holds the action name of the item. Action names are namespaced with an identifier for the action group in which the action resides. For example, "win." for window-specific actions and "app." for application-wide actions.

See also g_menu_model_get_item_attribute() and g_menu_item_set_attribute().

View Source 
const MENU_ATTRIBUTE_ACTION_NAMESPACE = "action-namespace"

MENU_ATTRIBUTE_ACTION_NAMESPACE: menu item attribute that holds the namespace for all action names in menus that are linked from this item.

View Source 
const MENU_ATTRIBUTE_ICON = "icon"

MENU_ATTRIBUTE_ICON: menu item attribute which holds the icon of the item.

The icon is stored in the format returned by g_icon_serialize().

This attribute is intended only to represent 'noun' icons such as favicons for a webpage, or application icons. It should not be used for 'verbs' (ie: stock icons).

View Source 
const MENU_ATTRIBUTE_LABEL = "label"

MENU_ATTRIBUTE_LABEL: menu item attribute which holds the label of the item.

View Source 
const MENU_ATTRIBUTE_TARGET = "target"

MENU_ATTRIBUTE_TARGET: menu item attribute which holds the target with which the item's action will be activated.

See also g_menu_item_set_action_and_target().

View Source 
const MENU_EXPORTER_MAX_SECTION_SIZE = 1000

MENU_EXPORTER_MAX_SECTION_SIZE: maximum number of entries in a menu section supported by g_dbus_connection_export_menu_model().

The exact value of the limit may change in future GLib versions.

View Source 
const MENU_LINK_SECTION = "section"

MENU_LINK_SECTION: name of the link that associates a menu item with a section. The linked menu will usually be shown in place of the menu item, using the item's label as a header.

See also g_menu_item_set_link().

View Source 
const MENU_LINK_SUBMENU = "submenu"

MENU_LINK_SUBMENU: name of the link that associates a menu item with a submenu.

See also g_menu_item_set_link().

View Source 
const NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME = "gio-native-volume-monitor"
View Source 
const NETWORK_MONITOR_EXTENSION_POINT_NAME = "gio-network-monitor"

NETWORK_MONITOR_EXTENSION_POINT_NAME: extension point for network status monitoring functionality. See [Extending GIO][extending-gio].

View Source 
const POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME = "gio-power-profile-monitor"

POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME: extension point for power profile usage monitoring functionality. See [Extending GIO][extending-gio].

View Source 
const PROXY_EXTENSION_POINT_NAME = "gio-proxy"

PROXY_EXTENSION_POINT_NAME: extension point for proxy functionality. See [Extending GIO][extending-gio].

View Source 
const PROXY_RESOLVER_EXTENSION_POINT_NAME = "gio-proxy-resolver"

PROXY_RESOLVER_EXTENSION_POINT_NAME: extension point for proxy resolving functionality. See [Extending GIO][extending-gio].

View Source 
const SETTINGS_BACKEND_EXTENSION_POINT_NAME = "gsettings-backend"

SETTINGS_BACKEND_EXTENSION_POINT_NAME: extension point for Backend functionality.

View Source 
const TLS_BACKEND_EXTENSION_POINT_NAME = "gio-tls-backend"

TLS_BACKEND_EXTENSION_POINT_NAME: extension point for TLS functionality via Backend. See [Extending GIO][extending-gio].

View Source 
const TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT = "1.3.6.1.5.5.7.3.2"

TLS_DATABASE_PURPOSE_AUTHENTICATE_CLIENT: purpose used to verify the client certificate in a TLS connection. Used by TLS servers.

View Source 
const TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER = "1.3.6.1.5.5.7.3.1"

TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER: purpose used to verify the server certificate in a TLS connection. This is the most common purpose in use. Used by TLS clients.

View Source 
const VFS_EXTENSION_POINT_NAME = "gio-vfs"

VFS_EXTENSION_POINT_NAME: extension point for #GVfs functionality. See [Extending GIO][extending-gio].

View Source 
const VOLUME_IDENTIFIER_KIND_CLASS = "class"

VOLUME_IDENTIFIER_KIND_CLASS: string used to obtain the volume class with g_volume_get_identifier().

Known volume classes include device, network, and loop. Other classes may be added in the future.

This is intended to be used by applications to classify #GVolume instances into different sections - for example a file manager or file chooser can use this information to show network volumes under a "Network" heading and device volumes under a "Devices" heading.

View Source 
const VOLUME_IDENTIFIER_KIND_HAL_UDI = "hal-udi"

VOLUME_IDENTIFIER_KIND_HAL_UDI: string used to obtain a Hal UDI with g_volume_get_identifier().

Deprecated: Do not use, HAL is deprecated.

View Source 
const VOLUME_IDENTIFIER_KIND_LABEL = "label"

VOLUME_IDENTIFIER_KIND_LABEL: string used to obtain a filesystem label with g_volume_get_identifier().

View Source 
const VOLUME_IDENTIFIER_KIND_NFS_MOUNT = "nfs-mount"

VOLUME_IDENTIFIER_KIND_NFS_MOUNT: string used to obtain a NFS mount with g_volume_get_identifier().

View Source 
const VOLUME_IDENTIFIER_KIND_UNIX_DEVICE = "unix-device"

VOLUME_IDENTIFIER_KIND_UNIX_DEVICE: string used to obtain a Unix device path with g_volume_get_identifier().

View Source 
const VOLUME_IDENTIFIER_KIND_UUID = "uuid"

VOLUME_IDENTIFIER_KIND_UUID: string used to obtain a UUID with g_volume_get_identifier().

View Source 
const VOLUME_MONITOR_EXTENSION_POINT_NAME = "gio-volume-monitor"

VOLUME_MONITOR_EXTENSION_POINT_NAME: extension point for volume monitor functionality. See [Extending GIO][extending-gio].

Variables

View Source 
var (
	GTypeBusType                      = coreglib.Type(C.g_bus_type_get_type())
	GTypeConverterResult              = coreglib.Type(C.g_converter_result_get_type())
	GTypeCredentialsType              = coreglib.Type(C.g_credentials_type_get_type())
	GTypeDBusError                    = coreglib.Type(C.g_dbus_error_get_type())
	GTypeDBusMessageByteOrder         = coreglib.Type(C.g_dbus_message_byte_order_get_type())
	GTypeDBusMessageHeaderField       = coreglib.Type(C.g_dbus_message_header_field_get_type())
	GTypeDBusMessageType              = coreglib.Type(C.g_dbus_message_type_get_type())
	GTypeDataStreamByteOrder          = coreglib.Type(C.g_data_stream_byte_order_get_type())
	GTypeDataStreamNewlineType        = coreglib.Type(C.g_data_stream_newline_type_get_type())
	GTypeDriveStartStopType           = coreglib.Type(C.g_drive_start_stop_type_get_type())
	GTypeEmblemOrigin                 = coreglib.Type(C.g_emblem_origin_get_type())
	GTypeFileAttributeStatus          = coreglib.Type(C.g_file_attribute_status_get_type())
	GTypeFileAttributeType            = coreglib.Type(C.g_file_attribute_type_get_type())
	GTypeFileMonitorEvent             = coreglib.Type(C.g_file_monitor_event_get_type())
	GTypeFileType                     = coreglib.Type(C.g_file_type_get_type())
	GTypeFilesystemPreviewType        = coreglib.Type(C.g_filesystem_preview_type_get_type())
	GTypeIOErrorEnum                  = coreglib.Type(C.g_io_error_enum_get_type())
	GTypeIOModuleScopeFlags           = coreglib.Type(C.g_io_module_scope_flags_get_type())
	GTypeMemoryMonitorWarningLevel    = coreglib.Type(C.g_memory_monitor_warning_level_get_type())
	GTypeMountOperationResult         = coreglib.Type(C.g_mount_operation_result_get_type())
	GTypeNetworkConnectivity          = coreglib.Type(C.g_network_connectivity_get_type())
	GTypeNotificationPriority         = coreglib.Type(C.g_notification_priority_get_type())
	GTypePasswordSave                 = coreglib.Type(C.g_password_save_get_type())
	GTypePollableReturn               = coreglib.Type(C.g_pollable_return_get_type())
	GTypeResolverError                = coreglib.Type(C.g_resolver_error_get_type())
	GTypeResolverRecordType           = coreglib.Type(C.g_resolver_record_type_get_type())
	GTypeResourceError                = coreglib.Type(C.g_resource_error_get_type())
	GTypeSocketClientEvent            = coreglib.Type(C.g_socket_client_event_get_type())
	GTypeSocketFamily                 = coreglib.Type(C.g_socket_family_get_type())
	GTypeSocketListenerEvent          = coreglib.Type(C.g_socket_listener_event_get_type())
	GTypeSocketProtocol               = coreglib.Type(C.g_socket_protocol_get_type())
	GTypeSocketType                   = coreglib.Type(C.g_socket_type_get_type())
	GTypeTLSAuthenticationMode        = coreglib.Type(C.g_tls_authentication_mode_get_type())
	GTypeTLSCertificateRequestFlags   = coreglib.Type(C.g_tls_certificate_request_flags_get_type())
	GTypeTLSChannelBindingError       = coreglib.Type(C.g_tls_channel_binding_error_get_type())
	GTypeTLSChannelBindingType        = coreglib.Type(C.g_tls_channel_binding_type_get_type())
	GTypeTLSDatabaseLookupFlags       = coreglib.Type(C.g_tls_database_lookup_flags_get_type())
	GTypeTLSError                     = coreglib.Type(C.g_tls_error_get_type())
	GTypeTLSInteractionResult         = coreglib.Type(C.g_tls_interaction_result_get_type())
	GTypeTLSProtocolVersion           = coreglib.Type(C.g_tls_protocol_version_get_type())
	GTypeTLSRehandshakeMode           = coreglib.Type(C.g_tls_rehandshake_mode_get_type())
	GTypeZlibCompressorFormat         = coreglib.Type(C.g_zlib_compressor_format_get_type())
	GTypeAppInfoCreateFlags           = coreglib.Type(C.g_app_info_create_flags_get_type())
	GTypeApplicationFlags             = coreglib.Type(C.g_application_flags_get_type())
	GTypeAskPasswordFlags             = coreglib.Type(C.g_ask_password_flags_get_type())
	GTypeBusNameOwnerFlags            = coreglib.Type(C.g_bus_name_owner_flags_get_type())
	GTypeBusNameWatcherFlags          = coreglib.Type(C.g_bus_name_watcher_flags_get_type())
	GTypeConverterFlags               = coreglib.Type(C.g_converter_flags_get_type())
	GTypeDBusCallFlags                = coreglib.Type(C.g_dbus_call_flags_get_type())
	GTypeDBusCapabilityFlags          = coreglib.Type(C.g_dbus_capability_flags_get_type())
	GTypeDBusConnectionFlags          = coreglib.Type(C.g_dbus_connection_flags_get_type())
	GTypeDBusInterfaceSkeletonFlags   = coreglib.Type(C.g_dbus_interface_skeleton_flags_get_type())
	GTypeDBusMessageFlags             = coreglib.Type(C.g_dbus_message_flags_get_type())
	GTypeDBusObjectManagerClientFlags = coreglib.Type(C.g_dbus_object_manager_client_flags_get_type())
	GTypeDBusPropertyInfoFlags        = coreglib.Type(C.g_dbus_property_info_flags_get_type())
	GTypeDBusProxyFlags               = coreglib.Type(C.g_dbus_proxy_flags_get_type())
	GTypeDBusSendMessageFlags         = coreglib.Type(C.g_dbus_send_message_flags_get_type())
	GTypeDBusServerFlags              = coreglib.Type(C.g_dbus_server_flags_get_type())
	GTypeDBusSignalFlags              = coreglib.Type(C.g_dbus_signal_flags_get_type())
	GTypeDBusSubtreeFlags             = coreglib.Type(C.g_dbus_subtree_flags_get_type())
	GTypeDriveStartFlags              = coreglib.Type(C.g_drive_start_flags_get_type())
	GTypeFileAttributeInfoFlags       = coreglib.Type(C.g_file_attribute_info_flags_get_type())
	GTypeFileCopyFlags                = coreglib.Type(C.g_file_copy_flags_get_type())
	GTypeFileCreateFlags              = coreglib.Type(C.g_file_create_flags_get_type())
	GTypeFileMeasureFlags             = coreglib.Type(C.g_file_measure_flags_get_type())
	GTypeFileMonitorFlags             = coreglib.Type(C.g_file_monitor_flags_get_type())
	GTypeFileQueryInfoFlags           = coreglib.Type(C.g_file_query_info_flags_get_type())
	GTypeIOStreamSpliceFlags          = coreglib.Type(C.g_io_stream_splice_flags_get_type())
	GTypeMountMountFlags              = coreglib.Type(C.g_mount_mount_flags_get_type())
	GTypeMountUnmountFlags            = coreglib.Type(C.g_mount_unmount_flags_get_type())
	GTypeOutputStreamSpliceFlags      = coreglib.Type(C.g_output_stream_splice_flags_get_type())
	GTypeResolverNameLookupFlags      = coreglib.Type(C.g_resolver_name_lookup_flags_get_type())
	GTypeResourceFlags                = coreglib.Type(C.g_resource_flags_get_type())
	GTypeResourceLookupFlags          = coreglib.Type(C.g_resource_lookup_flags_get_type())
	GTypeSettingsBindFlags            = coreglib.Type(C.g_settings_bind_flags_get_type())
	GTypeSocketMsgFlags               = coreglib.Type(C.g_socket_msg_flags_get_type())
	GTypeSubprocessFlags              = coreglib.Type(C.g_subprocess_flags_get_type())
	GTypeTestDBusFlags                = coreglib.Type(C.g_test_dbus_flags_get_type())
	GTypeTLSCertificateFlags          = coreglib.Type(C.g_tls_certificate_flags_get_type())
	GTypeTLSDatabaseVerifyFlags       = coreglib.Type(C.g_tls_database_verify_flags_get_type())
	GTypeTLSPasswordFlags             = coreglib.Type(C.g_tls_password_flags_get_type())
	GTypeAction                       = coreglib.Type(C.g_action_get_type())
	GTypeActionGroup                  = coreglib.Type(C.g_action_group_get_type())
	GTypeActionMap                    = coreglib.Type(C.g_action_map_get_type())
	GTypeAppInfo                      = coreglib.Type(C.g_app_info_get_type())
	GTypeAsyncInitable                = coreglib.Type(C.g_async_initable_get_type())
	GTypeAsyncResult                  = coreglib.Type(C.g_async_result_get_type())
	GTypeConverter                    = coreglib.Type(C.g_converter_get_type())
	GTypeDBusInterface                = coreglib.Type(C.g_dbus_interface_get_type())
	GTypeDBusObject                   = coreglib.Type(C.g_dbus_object_get_type())
	GTypeDBusObjectManager            = coreglib.Type(C.g_dbus_object_manager_get_type())
	GTypeDatagramBased                = coreglib.Type(C.g_datagram_based_get_type())
	GTypeDebugController              = coreglib.Type(C.g_debug_controller_get_type())
	GTypeDrive                        = coreglib.Type(C.g_drive_get_type())
	GTypeDTLSClientConnection         = coreglib.Type(C.g_dtls_client_connection_get_type())
	GTypeDTLSConnection               = coreglib.Type(C.g_dtls_connection_get_type())
	GTypeDTLSServerConnection         = coreglib.Type(C.g_dtls_server_connection_get_type())
	GTypeFile                         = coreglib.Type(C.g_file_get_type())
	GTypeIcon                         = coreglib.Type(C.g_icon_get_type())
	GTypeInitable                     = coreglib.Type(C.g_initable_get_type())
	GTypeListModel                    = coreglib.Type(C.g_list_model_get_type())
	GTypeLoadableIcon                 = coreglib.Type(C.g_loadable_icon_get_type())
	GTypeMemoryMonitor                = coreglib.Type(C.g_memory_monitor_get_type())
	GTypeMount                        = coreglib.Type(C.g_mount_get_type())
	GTypeNetworkMonitor               = coreglib.Type(C.g_network_monitor_get_type())
	GTypePollableInputStream          = coreglib.Type(C.g_pollable_input_stream_get_type())
	GTypePollableOutputStream         = coreglib.Type(C.g_pollable_output_stream_get_type())
	GTypePowerProfileMonitor          = coreglib.Type(C.g_power_profile_monitor_get_type())
	GTypeProxy                        = coreglib.Type(C.g_proxy_get_type())
	GTypeProxyResolver                = coreglib.Type(C.g_proxy_resolver_get_type())
	GTypeRemoteActionGroup            = coreglib.Type(C.g_remote_action_group_get_type())
	GTypeSeekable                     = coreglib.Type(C.g_seekable_get_type())
	GTypeSocketConnectable            = coreglib.Type(C.g_socket_connectable_get_type())
	GTypeTLSBackend                   = coreglib.Type(C.g_tls_backend_get_type())
	GTypeTLSClientConnection          = coreglib.Type(C.g_tls_client_connection_get_type())
	GTypeTLSFileDatabase              = coreglib.Type(C.g_tls_file_database_get_type())
	GTypeTLSServerConnection          = coreglib.Type(C.g_tls_server_connection_get_type())
	GTypeVolume                       = coreglib.Type(C.g_volume_get_type())
	GTypeAppInfoMonitor               = coreglib.Type(C.g_app_info_monitor_get_type())
	GTypeAppLaunchContext             = coreglib.Type(C.g_app_launch_context_get_type())
	GTypeApplication                  = coreglib.Type(C.g_application_get_type())
	GTypeApplicationCommandLine       = coreglib.Type(C.g_application_command_line_get_type())
	GTypeBufferedInputStream          = coreglib.Type(C.g_buffered_input_stream_get_type())
	GTypeBufferedOutputStream         = coreglib.Type(C.g_buffered_output_stream_get_type())
	GTypeBytesIcon                    = coreglib.Type(C.g_bytes_icon_get_type())
	GTypeCancellable                  = coreglib.Type(C.g_cancellable_get_type())
	GTypeCharsetConverter             = coreglib.Type(C.g_charset_converter_get_type())
	GTypeConverterInputStream         = coreglib.Type(C.g_converter_input_stream_get_type())
	GTypeConverterOutputStream        = coreglib.Type(C.g_converter_output_stream_get_type())
	GTypeCredentials                  = coreglib.Type(C.g_credentials_get_type())
	GTypeDBusActionGroup              = coreglib.Type(C.g_dbus_action_group_get_type())
	GTypeDBusAuthObserver             = coreglib.Type(C.g_dbus_auth_observer_get_type())
	GTypeDBusConnection               = coreglib.Type(C.g_dbus_connection_get_type())
	GTypeDBusInterfaceSkeleton        = coreglib.Type(C.g_dbus_interface_skeleton_get_type())
	GTypeDBusMenuModel                = coreglib.Type(C.g_dbus_menu_model_get_type())
	GTypeDBusMessage                  = coreglib.Type(C.g_dbus_message_get_type())
	GTypeDBusMethodInvocation         = coreglib.Type(C.g_dbus_method_invocation_get_type())
	GTypeDBusObjectManagerClient      = coreglib.Type(C.g_dbus_object_manager_client_get_type())
	GTypeDBusObjectManagerServer      = coreglib.Type(C.g_dbus_object_manager_server_get_type())
	GTypeDBusObjectProxy              = coreglib.Type(C.g_dbus_object_proxy_get_type())
	GTypeDBusObjectSkeleton           = coreglib.Type(C.g_dbus_object_skeleton_get_type())
	GTypeDBusProxy                    = coreglib.Type(C.g_dbus_proxy_get_type())
	GTypeDBusServer                   = coreglib.Type(C.g_dbus_server_get_type())
	GTypeDataInputStream              = coreglib.Type(C.g_data_input_stream_get_type())
	GTypeDataOutputStream             = coreglib.Type(C.g_data_output_stream_get_type())
	GTypeDebugControllerDBus          = coreglib.Type(C.g_debug_controller_dbus_get_type())
	GTypeEmblem                       = coreglib.Type(C.g_emblem_get_type())
	GTypeEmblemedIcon                 = coreglib.Type(C.g_emblemed_icon_get_type())
	GTypeFileEnumerator               = coreglib.Type(C.g_file_enumerator_get_type())
	GTypeFileIOStream                 = coreglib.Type(C.g_file_io_stream_get_type())
	GTypeFileIcon                     = coreglib.Type(C.g_file_icon_get_type())
	GTypeFileInfo                     = coreglib.Type(C.g_file_info_get_type())
	GTypeFileInputStream              = coreglib.Type(C.g_file_input_stream_get_type())
	GTypeFileMonitor                  = coreglib.Type(C.g_file_monitor_get_type())
	GTypeFileOutputStream             = coreglib.Type(C.g_file_output_stream_get_type())
	GTypeFilenameCompleter            = coreglib.Type(C.g_filename_completer_get_type())
	GTypeFilterInputStream            = coreglib.Type(C.g_filter_input_stream_get_type())
	GTypeFilterOutputStream           = coreglib.Type(C.g_filter_output_stream_get_type())
	GTypeIOStream                     = coreglib.Type(C.g_io_stream_get_type())
	GTypeInetAddress                  = coreglib.Type(C.g_inet_address_get_type())
	GTypeInetAddressMask              = coreglib.Type(C.g_inet_address_mask_get_type())
	GTypeInetSocketAddress            = coreglib.Type(C.g_inet_socket_address_get_type())
	GTypeInputStream                  = coreglib.Type(C.g_input_stream_get_type())
	GTypeListStore                    = coreglib.Type(C.g_list_store_get_type())
	GTypeMemoryInputStream            = coreglib.Type(C.g_memory_input_stream_get_type())
	GTypeMemoryOutputStream           = coreglib.Type(C.g_memory_output_stream_get_type())
	GTypeMenu                         = coreglib.Type(C.g_menu_get_type())
	GTypeMenuAttributeIter            = coreglib.Type(C.g_menu_attribute_iter_get_type())
	GTypeMenuItem                     = coreglib.Type(C.g_menu_item_get_type())
	GTypeMenuLinkIter                 = coreglib.Type(C.g_menu_link_iter_get_type())
	GTypeMenuModel                    = coreglib.Type(C.g_menu_model_get_type())
	GTypeMountOperation               = coreglib.Type(C.g_mount_operation_get_type())
	GTypeNativeSocketAddress          = coreglib.Type(C.g_native_socket_address_get_type())
	GTypeNativeVolumeMonitor          = coreglib.Type(C.g_native_volume_monitor_get_type())
	GTypeNetworkAddress               = coreglib.Type(C.g_network_address_get_type())
	GTypeNetworkService               = coreglib.Type(C.g_network_service_get_type())
	GTypeNotification                 = coreglib.Type(C.g_notification_get_type())
	GTypeOutputStream                 = coreglib.Type(C.g_output_stream_get_type())
	GTypePermission                   = coreglib.Type(C.g_permission_get_type())
	GTypePropertyAction               = coreglib.Type(C.g_property_action_get_type())
	GTypeProxyAddress                 = coreglib.Type(C.g_proxy_address_get_type())
	GTypeProxyAddressEnumerator       = coreglib.Type(C.g_proxy_address_enumerator_get_type())
	GTypeResolver                     = coreglib.Type(C.g_resolver_get_type())
	GTypeSettings                     = coreglib.Type(C.g_settings_get_type())
	GTypeSimpleAction                 = coreglib.Type(C.g_simple_action_get_type())
	GTypeSimpleActionGroup            = coreglib.Type(C.g_simple_action_group_get_type())
	GTypeSimpleAsyncResult            = coreglib.Type(C.g_simple_async_result_get_type())
	GTypeSimpleIOStream               = coreglib.Type(C.g_simple_io_stream_get_type())
	GTypeSimplePermission             = coreglib.Type(C.g_simple_permission_get_type())
	GTypeSimpleProxyResolver          = coreglib.Type(C.g_simple_proxy_resolver_get_type())
	GTypeSocket                       = coreglib.Type(C.g_socket_get_type())
	GTypeSocketAddress                = coreglib.Type(C.g_socket_address_get_type())
	GTypeSocketAddressEnumerator      = coreglib.Type(C.g_socket_address_enumerator_get_type())
	GTypeSocketClient                 = coreglib.Type(C.g_socket_client_get_type())
	GTypeSocketConnection             = coreglib.Type(C.g_socket_connection_get_type())
	GTypeSocketControlMessage         = coreglib.Type(C.g_socket_control_message_get_type())
	GTypeSocketListener               = coreglib.Type(C.g_socket_listener_get_type())
	GTypeSocketService                = coreglib.Type(C.g_socket_service_get_type())
	GTypeTask                         = coreglib.Type(C.g_task_get_type())
	GTypeTCPConnection                = coreglib.Type(C.g_tcp_connection_get_type())
	GTypeTCPWrapperConnection         = coreglib.Type(C.g_tcp_wrapper_connection_get_type())
	GTypeTestDBus                     = coreglib.Type(C.g_test_dbus_get_type())
	GTypeThemedIcon                   = coreglib.Type(C.g_themed_icon_get_type())
	GTypeThreadedSocketService        = coreglib.Type(C.g_threaded_socket_service_get_type())
	GTypeTLSCertificate               = coreglib.Type(C.g_tls_certificate_get_type())
	GTypeTLSConnection                = coreglib.Type(C.g_tls_connection_get_type())
	GTypeTLSDatabase                  = coreglib.Type(C.g_tls_database_get_type())
	GTypeTLSInteraction               = coreglib.Type(C.g_tls_interaction_get_type())
	GTypeTLSPassword                  = coreglib.Type(C.g_tls_password_get_type())
	GTypeVFS                          = coreglib.Type(C.g_vfs_get_type())
	GTypeVolumeMonitor                = coreglib.Type(C.g_volume_monitor_get_type())
	GTypeZlibCompressor               = coreglib.Type(C.g_zlib_compressor_get_type())
	GTypeZlibDecompressor             = coreglib.Type(C.g_zlib_decompressor_get_type())
	GTypeDBusAnnotationInfo           = coreglib.Type(C.g_dbus_annotation_info_get_type())
	GTypeDBusArgInfo                  = coreglib.Type(C.g_dbus_arg_info_get_type())
	GTypeDBusInterfaceInfo            = coreglib.Type(C.g_dbus_interface_info_get_type())
	GTypeDBusMethodInfo               = coreglib.Type(C.g_dbus_method_info_get_type())
	GTypeDBusNodeInfo                 = coreglib.Type(C.g_dbus_node_info_get_type())
	GTypeDBusPropertyInfo             = coreglib.Type(C.g_dbus_property_info_get_type())
	GTypeDBusSignalInfo               = coreglib.Type(C.g_dbus_signal_info_get_type())
	GTypeFileAttributeInfoList        = coreglib.Type(C.g_file_attribute_info_list_get_type())
	GTypeFileAttributeMatcher         = coreglib.Type(C.g_file_attribute_matcher_get_type())
	GTypeResource                     = coreglib.Type(C.g_resource_get_type())
	GTypeSettingsSchema               = coreglib.Type(C.g_settings_schema_get_type())
	GTypeSettingsSchemaKey            = coreglib.Type(C.g_settings_schema_key_get_type())
	GTypeSettingsSchemaSource         = coreglib.Type(C.g_settings_schema_source_get_type())
	GTypeSrvTarget                    = coreglib.Type(C.g_srv_target_get_type())
)

GType values.

Functions

func ActionNameIsValid 

func ActionNameIsValid(actionName string) bool

ActionNameIsValid checks if action_name is valid.

action_name is valid if it consists only of alphanumeric characters, plus '-' and '.'. The empty string is not a valid action name.

It is an error to call this function with a non-utf8 action_name. action_name must not be NULL.

The function takes the following parameters:

  • actionName: potential action name.

The function returns the following values:

  • ok: TRUE if action_name is valid.

func ActionParseDetailedName 

func ActionParseDetailedName(detailedName string) (string, *glib.Variant, error)

ActionParseDetailedName parses a detailed action name into its separate name and target components.

Detailed action names can have three formats.

The first format is used to represent an action name with no target value and consists of just an action name containing no whitespace nor the characters :, ( or ). For example: app.action.

The second format is used to represent an action with a target value that is a non-empty string consisting only of alphanumerics, plus - and .. In that case, the action name and target value are separated by a double colon (::). For example: app.action::target.

The third format is used to represent an action with any type of target value, including strings. The target value follows the action name, surrounded in parens. For example: app.action(42). The target value is parsed using g_variant_parse(). If a tuple-typed value is desired, it must be specified in the same way, resulting in two sets of parens, for example: app.action((1,2,3)). A string target can be specified this way as well: app.action('target'). For strings, this third format must be used if target value is empty or contains characters other than alphanumerics, - and ..

If this function returns TRUE, a non-NULL value is guaranteed to be returned in action_name (if a pointer is passed in). A NULL value may still be returned in target_value, as the detailed_name may not contain a target.

If returned, the #GVariant in target_value is guaranteed to not be floating.

The function takes the following parameters:

  • detailedName: detailed action name.

The function returns the following values:

  • actionName (optional): action name.
  • targetValue (optional): target value, or NULL for no target.

func ActionPrintDetailedName 

func ActionPrintDetailedName(actionName string, targetValue *glib.Variant) string

ActionPrintDetailedName formats a detailed action name from action_name and target_value.

It is an error to call this function with an invalid action name.

This function is the opposite of g_action_parse_detailed_name(). It will produce a string that can be parsed back to the action_name and target_value by that function.

See that function for the types of strings that will be printed by this function.

The function takes the following parameters:

  • actionName: valid action name.
  • targetValue (optional) target value, or NULL.

The function returns the following values:

  • utf8: detailed format string.

func AppInfoGetDefaultForTypeAsync added in v0.3.1 

func AppInfoGetDefaultForTypeAsync(ctx context.Context, contentType string, mustSupportUris bool, callback AsyncReadyCallback)

AppInfoGetDefaultForTypeAsync: asynchronously gets the default Info for a given content type.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • contentType: content type to find a Info for.
  • mustSupportUris: if TRUE, the Info is expected to support URIs.
  • callback (optional) to call when the request is done.

func AppInfoGetDefaultForURISchemeAsync added in v0.3.1 

func AppInfoGetDefaultForURISchemeAsync(ctx context.Context, uriScheme string, callback AsyncReadyCallback)

AppInfoGetDefaultForURISchemeAsync: asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', e.g. "http", "ftp" or "sip".

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • uriScheme: string containing a URI scheme.
  • callback (optional) to call when the request is done.

func AppInfoLaunchDefaultForURI 

func AppInfoLaunchDefaultForURI(uri string, context *AppLaunchContext) error

AppInfoLaunchDefaultForURI: utility function that launches the default application registered to handle the specified uri. Synchronous I/O is done on the uri to detect the type of the file if required.

The D-Bus–activated applications don't have to be started if your application terminates too soon after this function. To prevent this, use g_app_info_launch_default_for_uri_async() instead.

The function takes the following parameters:

  • uri to show.
  • context (optional): optional LaunchContext.

func AppInfoLaunchDefaultForURIAsync 

func AppInfoLaunchDefaultForURIAsync(ctx context.Context, uri string, context *AppLaunchContext, callback AsyncReadyCallback)

AppInfoLaunchDefaultForURIAsync: async version of g_app_info_launch_default_for_uri().

This version is useful if you are interested in receiving error information in the case where the application is sandboxed and the portal may present an application chooser dialog to the user.

This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested in receiving error information from their activation.

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • uri to show.
  • context (optional): optional LaunchContext.
  • callback (optional) to call when the request is done.

func AppInfoLaunchDefaultForURIFinish 

func AppInfoLaunchDefaultForURIFinish(result AsyncResulter) error

AppInfoLaunchDefaultForURIFinish finishes an asynchronous launch-default-for-uri operation.

The function takes the following parameters:

  • result: Result.

func AppInfoResetTypeAssociations 

func AppInfoResetTypeAssociations(contentType string)

AppInfoResetTypeAssociations removes all changes to the type associations done by g_app_info_set_as_default_for_type(), g_app_info_set_as_default_for_extension(), g_app_info_add_supports_type() or g_app_info_remove_supports_type().

The function takes the following parameters:

  • contentType: content type.

func ApplicationIDIsValid 

func ApplicationIDIsValid(applicationId string) bool

ApplicationIDIsValid checks if application_id is a valid application identifier.

A valid ID is required for calls to g_application_new() and g_application_set_application_id().

Application identifiers follow the same format as D-Bus well-known bus names (https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). For convenience, the restrictions on application identifiers are reproduced here:

- Application identifiers are composed of 1 or more elements separated by a period (.) character. All elements must contain at least one character.

- Each element must only contain the ASCII characters [A-Z][a-z][0-9]_-, with - discouraged in new application identifiers. Each element must not begin with a digit.

- Application identifiers must contain at least one . (period) character (and thus at least two elements).

- Application identifiers must not begin with a . (period) character.

- Application identifiers must not exceed 255 characters.

Note that the hyphen (-) character is allowed in application identifiers, but is problematic or not allowed in various specifications and APIs that refer to D-Bus, such as Flatpak application IDs (http://docs.flatpak.org/en/latest/introduction.html#identifiers), the DBusActivatable interface in the Desktop Entry Specification (https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus), and the convention that an application's "main" interface and object path resemble its application identifier and bus name. To avoid situations that require special-case handling, it is recommended that new application identifiers consistently replace hyphens with underscores.

Like D-Bus interface names, application identifiers should start with the reversed DNS domain name of the author of the interface (in lower-case), and it is conventional for the rest of the application identifier to consist of words run together, with initial capital letters.

As with D-Bus interface names, if the author's DNS domain name contains hyphen/minus characters they should be replaced by underscores, and if it contains leading digits they should be escaped by prepending an underscore. For example, if the owner of 7-zip.org used an application identifier for an archiving application, it might be named org._7_zip.Archiver.

The function takes the following parameters:

  • applicationId: potential application identifier.

The function returns the following values:

  • ok: TRUE if application_id is valid.

func BusGet 

func BusGet(ctx context.Context, busType BusType, callback AsyncReadyCallback)

BusGet: asynchronously connects to the message bus specified by bus_type.

When the operation is finished, callback will be invoked. You can then call g_bus_get_finish() to get the result of the operation.

This is an asynchronous failable function. See g_bus_get_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busType: Type.
  • callback (optional) to call when the request is satisfied.

func BusUnownName 

func BusUnownName(ownerId uint)

BusUnownName stops owning a name.

Note that there may still be D-Bus traffic to process (relating to owning and unowning the name) in the current thread-default Context after this function has returned. You should continue to iterate the Context until the Notify function passed to g_bus_own_name() is called, in order to avoid memory leaks through callbacks queued on the Context after it’s stopped being iterated.

The function takes the following parameters:

  • ownerId: identifier obtained from g_bus_own_name().

func BusUnwatchName 

func BusUnwatchName(watcherId uint)

BusUnwatchName stops watching a name.

Note that there may still be D-Bus traffic to process (relating to watching and unwatching the name) in the current thread-default Context after this function has returned. You should continue to iterate the Context until the Notify function passed to g_bus_watch_name() is called, in order to avoid memory leaks through callbacks queued on the Context after it’s stopped being iterated.

The function takes the following parameters:

  • watcherId: identifier obtained from g_bus_watch_name().

func ContentTypeCanBeExecutable 

func ContentTypeCanBeExecutable(typ string) bool

ContentTypeCanBeExecutable checks if a content type can be executable. Note that for instance things like text files can be executables (i.e. scripts and batch files).

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • ok: TRUE if the file type corresponds to a type that can be executable, FALSE otherwise.

func ContentTypeEquals 

func ContentTypeEquals(type1, type2 string) bool

ContentTypeEquals compares two content types for equality.

The function takes the following parameters:

  • type1: content type string.
  • type2: content type string.

The function returns the following values:

  • ok: TRUE if the two strings are identical or equivalent, FALSE otherwise.

func ContentTypeFromMIMEType 

func ContentTypeFromMIMEType(mimeType string) string

ContentTypeFromMIMEType tries to find a content type based on the mime type name.

The function takes the following parameters:

  • mimeType: mime type string.

The function returns the following values:

  • utf8 (optional): newly allocated string with content type or NULL. Free with g_free().

func ContentTypeGetDescription 

func ContentTypeGetDescription(typ string) string

ContentTypeGetDescription gets the human readable description of the content type.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • utf8: short description of the content type type. Free the returned string with g_free().

func ContentTypeGetGenericIconName 

func ContentTypeGetGenericIconName(typ string) string

ContentTypeGetGenericIconName gets the generic icon name for a content type.

See the shared-mime-info (http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on the generic icon name.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • utf8 (optional): registered generic icon name for the given type, or NULL if unknown. Free with g_free().

func ContentTypeGetMIMEDirs 

func ContentTypeGetMIMEDirs() []string

ContentTypeGetMIMEDirs: get the list of directories which MIME data is loaded from. See g_content_type_set_mime_dirs() for details.

The function returns the following values:

  • utf8s: NULL-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first.

func ContentTypeGetMIMEType 

func ContentTypeGetMIMEType(typ string) string

ContentTypeGetMIMEType gets the mime type for the content type, if one is registered.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • utf8 (optional): registered mime type for the given type, or NULL if unknown; free with g_free().

func ContentTypeGuess 

func ContentTypeGuess(filename string, data []byte) (bool, string)

ContentTypeGuess guesses the content type based on example data. If the function is uncertain, result_uncertain will be set to TRUE. Either filename or data may be NULL, in which case the guess will be based solely on the other argument.

The function takes the following parameters:

  • filename (optional): path, or NULL.
  • data (optional): stream of data, or NULL.

The function returns the following values:

  • resultUncertain (optional): return location for the certainty of the result, or NULL.
  • utf8: string indicating a guessed content type for the given data. Free with g_free().

func ContentTypeGuessForTree 

func ContentTypeGuessForTree(root Filer) []string

ContentTypeGuessForTree tries to guess the type of the tree with root root, by looking at the files it contains. The result is an array of content types, with the best guess coming first.

The types returned all have the form x-content/foo, e.g. x-content/audio-cdda (for audio CDs) or x-content/image-dcf (for a camera memory card). See the shared-mime-info (http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types.

This function is useful in the implementation of g_mount_guess_content_type().

The function takes the following parameters:

  • root of the tree to guess a type for.

The function returns the following values:

  • utf8s: NULL-terminated array of zero or more content types. Free with g_strfreev().

func ContentTypeIsA 

func ContentTypeIsA(typ, supertype string) bool

ContentTypeIsA determines if type is a subset of supertype.

The function takes the following parameters:

  • typ: content type string.
  • supertype: content type string.

The function returns the following values:

  • ok: TRUE if type is a kind of supertype, FALSE otherwise.

func ContentTypeIsMIMEType 

func ContentTypeIsMIMEType(typ, mimeType string) bool

ContentTypeIsMIMEType determines if type is a subset of mime_type. Convenience wrapper around g_content_type_is_a().

The function takes the following parameters:

  • typ: content type string.
  • mimeType: mime type string.

The function returns the following values:

  • ok: TRUE if type is a kind of mime_type, FALSE otherwise.

func ContentTypeIsUnknown 

func ContentTypeIsUnknown(typ string) bool

ContentTypeIsUnknown checks if the content type is the generic "unknown" type. On UNIX this is the "application/octet-stream" mimetype, while on win32 it is "*" and on OSX it is a dynamic type or octet-stream.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • ok: TRUE if the type is the unknown type.

func ContentTypeSetMIMEDirs 

func ContentTypeSetMIMEDirs(dirs []string)

ContentTypeSetMIMEDirs: set the list of directories used by GIO to load the MIME database. If dirs is NULL, the directories used are the default:

  • the mime subdirectory of the directory in $XDG_DATA_HOME
  • the mime subdirectory of every directory in $XDG_DATA_DIRS

This function is intended to be used when writing tests that depend on information stored in the MIME database, in order to control the data.

Typically, in case your tests use G_TEST_OPTION_ISOLATE_DIRS, but they depend on the system’s MIME database, you should call this function with dirs set to NULL before calling g_test_init(), for instance: 

// Load MIME data from the system
g_content_type_set_mime_dirs (NULL);
// Isolate the environment
g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL);

…

return g_test_run ();.

The function takes the following parameters:

  • dirs (optional): NULL-terminated list of directories to load MIME data from, including any mime/ subdirectory, and with the first directory to try listed first.

func ContentTypesGetRegistered 

func ContentTypesGetRegistered() []string

ContentTypesGetRegistered gets a list of strings containing all the registered content types known to the system. The list and its data should be freed using g_list_free_full (list, g_free).

The function returns the following values:

  • list of the registered content types.

func DBusAddressEscapeValue 

func DBusAddressEscapeValue(str string) string

DBusAddressEscapeValue: escape string so it can appear in a D-Bus address as the value part of a key-value pair.

For instance, if string is /run/bus-for-:0, this function would return /run/bus-for-3A0, which could be used in a D-Bus address like unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-3A0.

The function takes the following parameters:

  • str: unescaped string to be included in a D-Bus address as the value in a key-value pair.

The function returns the following values:

  • utf8: copy of string with all non-optionally-escaped bytes escaped.

func DBusAddressGetForBusSync 

func DBusAddressGetForBusSync(ctx context.Context, busType BusType) (string, error)

DBusAddressGetForBusSync: synchronously looks up the D-Bus address for the well-known message bus instance specified by bus_type. This may involve using various platform specific mechanisms.

The returned address will be in the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busType: Type.

The function returns the following values:

  • utf8: valid D-Bus address string for bus_type or NULL if error is set.

func DBusAddressGetStream 

func DBusAddressGetStream(ctx context.Context, address string, callback AsyncReadyCallback)

DBusAddressGetStream: asynchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. address must be in the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

When the operation is finished, callback will be invoked. You can then call g_dbus_address_get_stream_finish() to get the result of the operation.

This is an asynchronous failable function. See g_dbus_address_get_stream_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address: valid D-Bus address.
  • callback (optional) to call when the request is satisfied.

func DBusAnnotationInfoLookup 

func DBusAnnotationInfoLookup(annotations []*DBusAnnotationInfo, name string) string

DBusAnnotationInfoLookup looks up the value of an annotation.

The cost of this function is O(n) in number of annotations.

The function takes the following parameters:

  • annotations (optional): NULL-terminated array of annotations or NULL.
  • name of the annotation to look up.

The function returns the following values:

  • utf8 (optional): value or NULL if not found. Do not free, it is owned by annotations.

func DBusErrorEncodeGError 

func DBusErrorEncodeGError(err error) string

DBusErrorEncodeGError creates a D-Bus error name to use for error. If error matches a registered error (cf. g_dbus_error_register_error()), the corresponding D-Bus error name will be returned.

Otherwise the a name of the form org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE will be used. This allows other GDBus applications to map the error on the wire back to a #GError using g_dbus_error_new_for_dbus_error().

This function is typically only used in object mappings to put a #GError on the wire. Regular applications should not use it.

The function takes the following parameters:

  • err: #GError.

The function returns the following values:

  • utf8 d-Bus error name (never NULL). Free with g_free().

func DBusErrorGetRemoteError 

func DBusErrorGetRemoteError(err error) string

DBusErrorGetRemoteError gets the D-Bus error name used for error, if any.

This function is guaranteed to return a D-Bus error name for all #GErrors returned from functions handling remote method calls (e.g. g_dbus_connection_call_finish()) unless g_dbus_error_strip_remote_error() has been used on error.

The function takes the following parameters:

  • err: #GError.

The function returns the following values:

  • utf8 (optional): allocated string or NULL if the D-Bus error name could not be found. Free with g_free().

func DBusErrorIsRemoteError 

func DBusErrorIsRemoteError(err error) bool

DBusErrorIsRemoteError checks if error represents an error received via D-Bus from a remote peer. If so, use g_dbus_error_get_remote_error() to get the name of the error.

The function takes the following parameters:

  • err: #GError.

The function returns the following values:

  • ok: TRUE if error represents an error from a remote peer, FALSE otherwise.

func DBusErrorQuark 

func DBusErrorQuark() glib.Quark

func DBusErrorRegisterError 

func DBusErrorRegisterError(errorDomain glib.Quark, errorCode int, dbusErrorName string) bool

DBusErrorRegisterError creates an association to map between dbus_error_name and #GErrors specified by error_domain and error_code.

This is typically done in the routine that returns the #GQuark for an error domain.

The function takes the following parameters:

  • errorDomain for an error domain.
  • errorCode: error code.
  • dbusErrorName d-Bus error name.

The function returns the following values:

  • ok: TRUE if the association was created, FALSE if it already exists.

func DBusErrorRegisterErrorDomain 

func DBusErrorRegisterErrorDomain(errorDomainQuarkName string, quarkVolatile *uint, entries []DBusErrorEntry)

DBusErrorRegisterErrorDomain: helper function for associating a #GError error domain with D-Bus error names.

While quark_volatile has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

The function takes the following parameters:

  • errorDomainQuarkName: error domain name.
  • quarkVolatile: pointer where to store the #GQuark.
  • entries: pointer to num_entries BusErrorEntry struct items.

func DBusErrorStripRemoteError 

func DBusErrorStripRemoteError(err error) bool

DBusErrorStripRemoteError looks for extra information in the error message used to recover the D-Bus error name and strips it if found. If stripped, the message field in error will correspond exactly to what was received on the wire.

This is typically used when presenting errors to the end user.

The function takes the following parameters:

  • err: #GError.

The function returns the following values:

  • ok: TRUE if information was stripped, FALSE otherwise.

func DBusErrorUnregisterError 

func DBusErrorUnregisterError(errorDomain glib.Quark, errorCode int, dbusErrorName string) bool

DBusErrorUnregisterError destroys an association previously set up with g_dbus_error_register_error().

The function takes the following parameters:

  • errorDomain for an error domain.
  • errorCode: error code.
  • dbusErrorName d-Bus error name.

The function returns the following values:

  • ok: TRUE if the association was destroyed, FALSE if it wasn't found.

func DBusEscapeObjectPath 

func DBusEscapeObjectPath(s string) string

DBusEscapeObjectPath: this is a language binding friendly version of g_dbus_escape_object_path_bytestring().

The function takes the following parameters:

  • s: string to escape.

The function returns the following values:

  • utf8: escaped version of s. Free with g_free().

func DBusEscapeObjectPathBytestring 

func DBusEscapeObjectPathBytestring(bytes []byte) string

DBusEscapeObjectPathBytestring escapes bytes for use in a D-Bus object path component. bytes is an array of zero or more nonzero bytes in an unspecified encoding, followed by a single zero byte.

The escaping method consists of replacing all non-alphanumeric characters (see g_ascii_isalnum()) with their hexadecimal value preceded by an underscore (_). For example: foo.bar.baz will become foo_2ebar_2ebaz.

This method is appropriate to use when the input is nearly a valid object path component but is not when your input is far from being a valid object path component. Other escaping algorithms are also valid to use with D-Bus object paths.

This can be reversed with g_dbus_unescape_object_path().

The function takes the following parameters:

  • bytes: string of bytes to escape.

The function returns the following values:

  • utf8: escaped version of bytes. Free with g_free().

func DBusGValueToGVariant 

func DBusGValueToGVariant(gvalue *coreglib.Value, typ *glib.VariantType) *glib.Variant

DBusGValueToGVariant converts a #GValue to a #GVariant of the type indicated by the type parameter.

The conversion is using the following rules:

- G_TYPE_STRING: 's', 'o', 'g' or 'ay'

- G_TYPE_STRV: 'as', 'ao' or 'aay'

- G_TYPE_BOOLEAN: 'b'

- G_TYPE_UCHAR: 'y'

- G_TYPE_INT: 'i', 'n'

- G_TYPE_UINT: 'u', 'q'

- G_TYPE_INT64: 'x'

- G_TYPE_UINT64: 't'

- G_TYPE_DOUBLE: 'd'

- G_TYPE_VARIANT: Any Type

This can fail if e.g. gvalue is of type G_TYPE_STRING and type is 'i', i.e. G_VARIANT_TYPE_INT32. It will also fail for any #GType (including e.g. G_TYPE_OBJECT and G_TYPE_BOXED derived-types) not in the table above.

Note that if gvalue is of type G_TYPE_VARIANT and its value is NULL, the empty #GVariant instance (never NULL) for type is returned (e.g. 0 for scalar types, the empty string for string types, '/' for object path types, the empty array for any array type and so on).

See the g_dbus_gvariant_to_gvalue() function for how to convert a #GVariant to a #GValue.

The function takes the following parameters:

  • gvalue to convert to a #GVariant.
  • typ: Type.

The function returns the following values:

  • variant (never floating) of Type type holding the data from gvalue or an empty #GVariant in case of failure. Free with g_variant_unref().

func DBusGVariantToGValue 

func DBusGVariantToGValue(value *glib.Variant) coreglib.Value

DBusGVariantToGValue converts a #GVariant to a #GValue. If value is floating, it is consumed.

The rules specified in the g_dbus_gvalue_to_gvariant() function are used - this function is essentially its reverse form. So, a #GVariant containing any basic or string array type will be converted to a #GValue containing a basic value or string array. Any other #GVariant (handle, variant, tuple, dict entry) will be converted to a #GValue containing that #GVariant.

The conversion never fails - a valid #GValue is always returned in out_gvalue.

The function takes the following parameters:

  • value: #GVariant.

The function returns the following values:

  • outGvalue: return location pointing to a zero-filled (uninitialized) #GValue.

func DBusGenerateGUID 

func DBusGenerateGUID() string

DBusGenerateGUID: generate a D-Bus GUID that can be used with e.g. g_dbus_connection_new().

See the D-Bus specification (https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) regarding what strings are valid D-Bus GUIDs. The specification refers to these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as ‘GUIDs’. The terms are interchangeable.

Note that D-Bus GUIDs do not follow RFC 4122 (https://datatracker.ietf.org/doc/html/rfc4122).

The function returns the following values:

  • utf8: valid D-Bus GUID. Free with g_free().

func DBusIsAddress 

func DBusIsAddress(str string) bool

DBusIsAddress checks if string is a D-Bus address (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

This doesn't check if string is actually supported by BusServer or BusConnection - use g_dbus_is_supported_address() to do more checks.

The function takes the following parameters:

  • str: string.

The function returns the following values:

  • ok: TRUE if string is a valid D-Bus address, FALSE otherwise.

func DBusIsErrorName added in v0.3.0 

func DBusIsErrorName(str string) bool

DBusIsErrorName: check whether string is a valid D-Bus error name.

This function returns the same result as g_dbus_is_interface_name(), because D-Bus error names are defined to have exactly the same syntax as interface names.

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if valid, FALSE otherwise.

func DBusIsGUID 

func DBusIsGUID(str string) bool

DBusIsGUID checks if string is a D-Bus GUID.

See the documentation for g_dbus_generate_guid() for more information about the format of a GUID.

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if string is a GUID, FALSE otherwise.

func DBusIsInterfaceName 

func DBusIsInterfaceName(str string) bool

DBusIsInterfaceName checks if string is a valid D-Bus interface name.

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if valid, FALSE otherwise.

func DBusIsMemberName 

func DBusIsMemberName(str string) bool

DBusIsMemberName checks if string is a valid D-Bus member (e.g. signal or method) name.

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if valid, FALSE otherwise.

func DBusIsName 

func DBusIsName(str string) bool

DBusIsName checks if string is a valid D-Bus bus name (either unique or well-known).

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if valid, FALSE otherwise.

func DBusIsSupportedAddress 

func DBusIsSupportedAddress(str string) error

DBusIsSupportedAddress: like g_dbus_is_address() but also checks if the library supports the transports in string and that key/value pairs for each transport are valid. See the specification of the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

The function takes the following parameters:

  • str: string.

func DBusIsUniqueName 

func DBusIsUniqueName(str string) bool

DBusIsUniqueName checks if string is a valid D-Bus unique bus name.

The function takes the following parameters:

  • str: string to check.

The function returns the following values:

  • ok: TRUE if valid, FALSE otherwise.

func DBusMessageBytesNeeded 

func DBusMessageBytesNeeded(blob []byte) (int, error)

DBusMessageBytesNeeded: utility function to calculate how many bytes are needed to completely deserialize the D-Bus message stored at blob.

The function takes the following parameters:

  • blob representing a binary D-Bus message.

The function returns the following values:

  • gssize: number of bytes needed or -1 if error is set (e.g. if blob contains invalid data or not enough data is available to determine the size).

func DBusUnescapeObjectPath 

func DBusUnescapeObjectPath(s string) []byte

DBusUnescapeObjectPath unescapes an string that was previously escaped with g_dbus_escape_object_path(). If the string is in a format that could not have been returned by g_dbus_escape_object_path(), this function returns NULL.

Encoding alphanumeric characters which do not need to be encoded is not allowed (e.g _63 is not valid, the string should contain c instead).

The function takes the following parameters:

  • s: string to unescape.

The function returns the following values:

  • guint8s (optional): an unescaped version of s, or NULL if s is not a string returned from g_dbus_escape_object_path(). Free with g_free().

func IOErrorQuark 

func IOErrorQuark() glib.Quark

IOErrorQuark gets the GIO Error Quark.

The function returns the following values:

  • quark: #GQuark.

func IOModulesScanAllInDirectory 

func IOModulesScanAllInDirectory(dirname string)

IOModulesScanAllInDirectory scans all the modules in the specified directory, ensuring that any extension point implemented by a module is registered.

This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when an extension point it implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name().

If you need to guarantee that all types are loaded in all the modules, use g_io_modules_load_all_in_directory().

The function takes the following parameters:

  • dirname: pathname for a directory containing modules to scan.

func IOSchedulerCancelAllJobs deprecated 

func IOSchedulerCancelAllJobs()

IOSchedulerCancelAllJobs cancels all cancellable I/O jobs.

A job is cancellable if a #GCancellable was passed into g_io_scheduler_push_job().

Deprecated: You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler.

func IOStreamSpliceFinish 

func IOStreamSpliceFinish(result AsyncResulter) error

IOStreamSpliceFinish finishes an asynchronous io stream splice operation.

The function takes the following parameters:

  • result: Result.

func NewDBusConnection 

func NewDBusConnection(ctx context.Context, stream IOStreamer, guid string, flags DBusConnectionFlags, observer *DBusAuthObserver, callback AsyncReadyCallback)

NewDBusConnection: asynchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If stream is a Connection, then the corresponding #GSocket will be put into non-blocking mode.

The D-Bus connection will interact with stream from a worker thread. As a result, the caller should not interact with stream after this method has been called, except by calling g_object_unref() on it.

If observer is not NULL it may be used to control the authentication process.

When the operation is finished, callback will be invoked. You can then call g_dbus_connection_new_finish() to get the result of the operation.

This is an asynchronous failable constructor. See g_dbus_connection_new_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • stream: OStream.
  • guid (optional): GUID to use if authenticating as a server or NULL.
  • flags describing how to make the connection.
  • observer (optional) or NULL.
  • callback (optional) to call when the request is satisfied.

func NewDBusConnectionForAddress 

func NewDBusConnectionForAddress(ctx context.Context, address string, flags DBusConnectionFlags, observer *DBusAuthObserver, callback AsyncReadyCallback)

NewDBusConnectionForAddress: asynchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

This constructor can only be used to initiate client-side connections - use g_dbus_connection_new() if you need to act as the server. In particular, flags cannot contain the G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.

When the operation is finished, callback will be invoked. You can then call g_dbus_connection_new_for_address_finish() to get the result of the operation.

If observer is not NULL it may be used to control the authentication process.

This is an asynchronous failable constructor. See g_dbus_connection_new_for_address_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address d-Bus address.
  • flags describing how to make the connection.
  • observer (optional) or NULL.
  • callback (optional) to call when the request is satisfied.

func NewDBusErrorForDBusError 

func NewDBusErrorForDBusError(dbusErrorName, dbusErrorMessage string) error

NewDBusErrorForDBusError creates a #GError based on the contents of dbus_error_name and dbus_error_message.

Errors registered with g_dbus_error_register_error() will be looked up using dbus_error_name and if a match is found, the error domain and code is used. Applications can use g_dbus_error_get_remote_error() to recover dbus_error_name.

If a match against a registered error is not found and the D-Bus error name is in a form as returned by g_dbus_error_encode_gerror() the error domain and code encoded in the name is used to create the #GError. Also, dbus_error_name is added to the error message such that it can be recovered with g_dbus_error_get_remote_error().

Otherwise, a #GError with the error code G_IO_ERROR_DBUS_ERROR in the G_IO_ERROR error domain is returned. Also, dbus_error_name is added to the error message such that it can be recovered with g_dbus_error_get_remote_error().

In all three cases, dbus_error_name can always be recovered from the returned #GError using the g_dbus_error_get_remote_error() function (unless g_dbus_error_strip_remote_error() hasn't been used on the returned error).

This function is typically only used in object mappings to prepare #GError instances for applications. Regular applications should not use it.

The function takes the following parameters:

  • dbusErrorName d-Bus error name.
  • dbusErrorMessage d-Bus error message.

The function returns the following values:

  • err: allocated #GError. Free with g_error_free().

func NewDBusProxy 

func NewDBusProxy(ctx context.Context, connection *DBusConnection, flags DBusProxyFlags, info *DBusInterfaceInfo, name, objectPath, interfaceName string, callback AsyncReadyCallback)

NewDBusProxy creates a proxy for accessing interface_name on the remote object at object_path owned by name at connection and asynchronously loads D-Bus properties unless the G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used. Connect to the BusProxy::g-properties-changed signal to get notified about property changes.

If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the BusProxy::g-signal signal to handle signals from the remote object.

If both G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result.

See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.

BusProxy is used in this [example][gdbus-wellknown-proxy].

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connection: BusConnection.
  • flags flags used when constructing the proxy.
  • info (optional) specifying the minimal interface that proxy conforms to or NULL.
  • name (optional) bus name (well-known or unique) or NULL if connection is not a message bus connection.
  • objectPath: object path.
  • interfaceName d-Bus interface name.
  • callback (optional): callback function to invoke when the proxy is ready.

func NewDBusProxyForBus 

func NewDBusProxyForBus(ctx context.Context, busType BusType, flags DBusProxyFlags, info *DBusInterfaceInfo, name, objectPath, interfaceName string, callback AsyncReadyCallback)

NewDBusProxyForBus: like g_dbus_proxy_new() but takes a Type instead of a BusConnection.

BusProxy is used in this [example][gdbus-wellknown-proxy].

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busType: Type.
  • flags flags used when constructing the proxy.
  • info (optional) specifying the minimal interface that proxy conforms to or NULL.
  • name bus name (well-known or unique).
  • objectPath: object path.
  • interfaceName d-Bus interface name.
  • callback (optional): callback function to invoke when the proxy is ready.

func NewFileTmp 

func NewFileTmp(tmpl string) (*FileIOStream, *File, error)

NewFileTmp opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) and returns a #GFile and IOStream pointing to it.

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is NULL, a default template is used.

Unlike the other #GFile constructors, this will return NULL if a temporary file could not be created.

The function takes the following parameters:

  • tmpl (optional): template for the file name, as in g_file_open_tmp(), or NULL for a default template.

The function returns the following values:

  • iostream: on return, a IOStream for the created file.
  • file: new #GFile. Free the returned object with g_object_unref().

func NewFileTmpAsync added in v0.3.1 

func NewFileTmpAsync(ctx context.Context, tmpl string, ioPriority int, callback AsyncReadyCallback)

NewFileTmpAsync: asynchronously opens a file in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_file_new_tmp().

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is NULL, a default template is used.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • tmpl (optional): template for the file name, as in g_file_open_tmp(), or NULL for a default template.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is done.

func NewFileTmpDirAsync added in v0.3.1 

func NewFileTmpDirAsync(ctx context.Context, tmpl string, ioPriority int, callback AsyncReadyCallback)

NewFileTmpDirAsync: asynchronously creates a directory in the preferred directory for temporary files (as returned by g_get_tmp_dir()) as g_dir_make_tmp().

tmpl should be a string in the GLib file name encoding containing a sequence of six 'X' characters, and containing no directory components. If it is NULL, a default template is used.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • tmpl (optional): template for the file name, as in g_dir_make_tmp(), or NULL for a default template.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is done.

func NewFileTmpFinish added in v0.3.0 

func NewFileTmpFinish(result AsyncResulter) (*FileIOStream, *File, error)

NewFileTmpFinish finishes a temporary file creation started by g_file_new_tmp_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • iostream: on return, a IOStream for the created file.
  • file: new #GFile. Free the returned object with g_object_unref().

func NewPollableSource 

func NewPollableSource(pollableStream *coreglib.Object) *glib.Source

NewPollableSource: utility method for InputStream and OutputStream implementations. Creates a new #GSource that expects a callback of type SourceFunc. The new source does not actually do anything on its own; use g_source_add_child_source() to add other sources to it to cause it to trigger.

The function takes the following parameters:

  • pollableStream: stream associated with the new source.

The function returns the following values:

  • source: new #GSource.

func PollableSourceNewFull 

func PollableSourceNewFull(ctx context.Context, pollableStream *coreglib.Object, childSource *glib.Source) *glib.Source

PollableSourceNewFull: utility method for InputStream and OutputStream implementations. Creates a new #GSource, as with g_pollable_source_new(), but also attaching child_source (with a dummy callback), and cancellable, if they are non-NULL.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable to attach.
  • pollableStream: stream associated with the new source.
  • childSource (optional): optional child source to attach.

The function returns the following values:

  • source: new #GSource.

func PollableStreamRead 

func PollableStreamRead(ctx context.Context, stream InputStreamer, buffer []byte, blocking bool) (int, error)

PollableStreamRead tries to read from stream, as with g_input_stream_read() (if blocking is TRUE) or g_pollable_input_stream_read_nonblocking() (if blocking is FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is FALSE, then stream must be a InputStream for which g_pollable_input_stream_can_poll() returns TRUE, or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a InputStream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stream: Stream.
  • buffer to read data into.
  • blocking: whether to do blocking I/O.

The function returns the following values:

  • gssize: number of bytes read, or -1 on error.

func PollableStreamWrite 

func PollableStreamWrite(ctx context.Context, stream OutputStreamer, buffer []byte, blocking bool) (int, error)

PollableStreamWrite tries to write to stream, as with g_output_stream_write() (if blocking is TRUE) or g_pollable_output_stream_write_nonblocking() (if blocking is FALSE). This can be used to more easily share code between blocking and non-blocking implementations of a method.

If blocking is FALSE, then stream must be a OutputStream for which g_pollable_output_stream_can_poll() returns TRUE or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a OutputStream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stream: Stream.
  • buffer: buffer containing the data to write.
  • blocking: whether to do blocking I/O.

The function returns the following values:

  • gssize: number of bytes written, or -1 on error.

func PollableStreamWriteAll 

func PollableStreamWriteAll(ctx context.Context, stream OutputStreamer, buffer []byte, blocking bool) (uint, error)

PollableStreamWriteAll tries to write count bytes to stream, as with g_output_stream_write_all(), but using g_pollable_stream_write() rather than g_output_stream_write().

On a successful write of count bytes, TRUE is returned, and bytes_written is set to count.

If there is an error during the operation (including G_IO_ERROR_WOULD_BLOCK in the non-blocking case), FALSE is returned and error is set to indicate the error status, bytes_written is updated to contain the number of bytes written into the stream before the error occurred.

As with g_pollable_stream_write(), if blocking is FALSE, then stream must be a OutputStream for which g_pollable_output_stream_can_poll() returns TRUE or else the behavior is undefined. If blocking is TRUE, then stream does not need to be a OutputStream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stream: Stream.
  • buffer: buffer containing the data to write.
  • blocking: whether to do blocking I/O.

The function returns the following values:

  • bytesWritten: location to store the number of bytes that was written to the stream.

func ResolverErrorQuark 

func ResolverErrorQuark() glib.Quark

ResolverErrorQuark gets the #GResolver Error Quark.

The function returns the following values:

  • quark: #GQuark.

func ResourceErrorQuark 

func ResourceErrorQuark() glib.Quark

ResourceErrorQuark gets the #GResource Error Quark.

The function returns the following values:

  • quark: #GQuark.

func ResourcesEnumerateChildren 

func ResourcesEnumerateChildren(path string, lookupFlags ResourceLookupFlags) ([]string, error)

ResourcesEnumerateChildren returns all the names of children at the specified path in the set of globally registered resources. The return result is a NULL terminated list of strings which should be released with g_strfreev().

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • utf8s: array of constant strings.

func ResourcesGetInfo 

func ResourcesGetInfo(path string, lookupFlags ResourceLookupFlags) (uint, uint32, error)

ResourcesGetInfo looks for a file at the specified path in the set of globally registered resources and if found returns information about it.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • size (optional): location to place the length of the contents of the file, or NULL if the length is not needed.
  • flags (optional): location to place the Flags about the file, or NULL if the flags are not needed.

func ResourcesLookupData 

func ResourcesLookupData(path string, lookupFlags ResourceLookupFlags) (*glib.Bytes, error)

ResourcesLookupData looks for a file at the specified path in the set of globally registered resources and returns a #GBytes that lets you directly access the data in memory.

The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the GBytes.

For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some readonly data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • bytes or NULL on error. Free the returned object with g_bytes_unref().

func ResourcesRegister 

func ResourcesRegister(resource *Resource)

ResourcesRegister registers the resource with the process-global set of resources. Once a resource is registered the files in it can be accessed with the global resource lookup functions like g_resources_lookup_data().

The function takes the following parameters:

  • resource: #GResource.

func ResourcesUnregister 

func ResourcesUnregister(resource *Resource)

ResourcesUnregister unregisters the resource from the process-global set of resources.

The function takes the following parameters:

  • resource: #GResource.

func SettingsListRelocatableSchemas deprecated 

func SettingsListRelocatableSchemas() []string

SettingsListRelocatableSchemas: deprecated.

Deprecated: Use g_settings_schema_source_list_schemas() instead.

The function returns the following values:

  • utf8s: list of relocatable #GSettings schemas that are available, in no defined order. The list must not be modified or freed.

func SettingsListSchemas deprecated 

func SettingsListSchemas() []string

SettingsListSchemas: deprecated.

Deprecated: Use g_settings_schema_source_list_schemas() instead. If you used g_settings_list_schemas() to check for the presence of a particular schema, use g_settings_schema_source_lookup() instead of your whole loop.

The function returns the following values:

  • utf8s: list of #GSettings schemas that are available, in no defined order. The list must not be modified or freed.

func SettingsSync 

func SettingsSync()

SettingsSync ensures that all pending operations are complete for the default backend.

Writes made to a #GSettings are handled asynchronously. For this reason, it is very unlikely that the changes have it to disk by the time g_settings_set() returns.

This call will block until all of the writes have made it to the backend. Since the mainloop is not running, no change notifications will be dispatched during this call (but some may be queued by the time the call is done).

func SettingsUnbind 

func SettingsUnbind(object *coreglib.Object, property string)

SettingsUnbind removes an existing binding for property on object.

Note that bindings are automatically removed when the object is finalized, so it is rarely necessary to call this function.

The function takes the following parameters:

  • object: object.
  • property whose binding is removed.

func SimpleAsyncReportGErrorInIdle deprecated 

func SimpleAsyncReportGErrorInIdle(object *coreglib.Object, callback AsyncReadyCallback, err error)

SimpleAsyncReportGErrorInIdle reports an error in an idle function. Similar to g_simple_async_report_error_in_idle(), but takes a #GError rather than building a new one.

Deprecated: Use g_task_report_error().

The function takes the following parameters:

  • object (optional) or NULL.
  • callback (optional): ReadyCallback.
  • err to report.

func SimpleAsyncResultIsValid deprecated 

func SimpleAsyncResultIsValid(result AsyncResulter, source *coreglib.Object, sourceTag unsafe.Pointer) bool

SimpleAsyncResultIsValid ensures that the data passed to the _finish function of an async operation is consistent. Three checks are performed.

First, result is checked to ensure that it is really a AsyncResult. Second, source is checked to ensure that it matches the source object of result. Third, source_tag is checked to ensure that it is equal to the source_tag argument given to g_simple_async_result_new() (which, by convention, is a pointer to the _async function corresponding to the _finish function from which this function is called). (Alternatively, if either source_tag or result's source tag is NULL, then the source tag check is skipped.)

Deprecated: Use #GTask and g_task_is_valid() instead.

The function takes the following parameters:

  • result passed to the _finish function.
  • source (optional) passed to the _finish function.
  • sourceTag (optional) asynchronous function.

The function returns the following values:

  • ok if all checks passed or LSE if any failed.

func SocketConnectionFactoryLookupType 

func SocketConnectionFactoryLookupType(family SocketFamily, typ SocketType, protocolId int) coreglib.Type

SocketConnectionFactoryLookupType looks up the #GType to be used when creating socket connections on sockets with the specified family, type and protocol_id.

If no type is registered, the Connection base type is returned.

The function takes the following parameters:

  • family: Family.
  • typ: Type.
  • protocolId: protocol id.

The function returns the following values:

  • gType: #GType.

func SocketConnectionFactoryRegisterType 

func SocketConnectionFactoryRegisterType(gType coreglib.Type, family SocketFamily, typ SocketType, protocol int)

SocketConnectionFactoryRegisterType looks up the #GType to be used when creating socket connections on sockets with the specified family, type and protocol.

If no type is registered, the Connection base type is returned.

The function takes the following parameters:

  • gType inheriting from G_TYPE_SOCKET_CONNECTION.
  • family: Family.
  • typ: Type.
  • protocol id.

func TLSChannelBindingErrorQuark 

func TLSChannelBindingErrorQuark() glib.Quark

TLSChannelBindingErrorQuark gets the TLS channel binding error quark.

The function returns the following values:

  • quark: #GQuark.

func TLSErrorQuark 

func TLSErrorQuark() glib.Quark

TLSErrorQuark gets the TLS error quark.

The function returns the following values:

  • quark: #GQuark.

func TaskIsValid 

func TaskIsValid(result AsyncResulter, sourceObject *coreglib.Object) bool

TaskIsValid checks that result is a #GTask, and that source_object is its source object (or that source_object is NULL and result has no source object). This can be used in g_return_if_fail() checks.

The function takes the following parameters:

  • result: Result.
  • sourceObject (optional): source object expected to be associated with the task.

The function returns the following values:

  • ok: TRUE if result and source_object are valid, FALSE if not.

func TaskReportError 

func TaskReportError(sourceObject *coreglib.Object, callback AsyncReadyCallback, sourceTag unsafe.Pointer, err error)

TaskReportError creates a #GTask and then immediately calls g_task_return_error() on it. Use this in the wrapper function of an asynchronous method when you want to avoid even calling the virtual method. You can then use g_async_result_is_tagged() in the finish method wrapper to check if the result there is tagged as having been created by the wrapper method, and deal with it appropriately if so.

See also g_task_report_new_error().

The function takes the following parameters:

  • sourceObject (optional) that owns this task, or NULL.
  • callback (optional): ReadyCallback.
  • sourceTag (optional): opaque pointer indicating the source of this task.
  • err: error to report.

func TestDBusUnset 

func TestDBusUnset()

TestDBusUnset: unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test won't use user's session bus.

This is useful for unit tests that want to verify behaviour when no session bus is running. It is not necessary to call this if unit test already calls g_test_dbus_up() before acquiring the session bus.

Types

type Action 

type Action struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Action: GAction represents a single named action.

The main interface to an action is that it can be activated with gio.Action.Activate(). This results in the 'activate' signal being emitted. An activation has a GVariant parameter (which may be NULL). The correct type for the parameter is determined by a static parameter type (which is given at construction time).

An action may optionally have a state, in which case the state may be set with gio.Action.ChangeState(). This call takes a #GVariant. The correct type for the state is determined by a static state type (which is given at construction time).

The state may have a hint associated with it, specifying its valid range.

GAction is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including gio.SimpleAction.

In all cases, the implementing class is responsible for storing the name of the action, the parameter type, the enabled state, the optional state type and the state and emitting the appropriate signals when these change. The implementor is responsible for filtering calls to gio.Action.Activate() and gio.Action.ChangeState() for type safety and for the state being enabled.

Probably the only useful thing to do with a GAction is to put it inside of a gio.SimpleActionGroup.

Action wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Action) Activate 

func (action *Action) Activate(parameter *glib.Variant)

Activate activates the action.

parameter must be the correct type of parameter for the action (ie: the parameter type given at construction time). If the parameter type was NULL then parameter must also be NULL.

If the parameter GVariant is floating, it is consumed.

The function takes the following parameters:

  • parameter (optional) to the activation.

func (*Action) ChangeState 

func (action *Action) ChangeState(value *glib.Variant)

ChangeState: request for the state of action to be changed to value.

The action must be stateful and value must be of the correct type. See g_action_get_state_type().

This call merely requests a change. The action may refuse to change its state or may change its state to something other than value. See g_action_get_state_hint().

If the value GVariant is floating, it is consumed.

The function takes the following parameters:

  • value: new state.

func (*Action) Enabled 

func (action *Action) Enabled() bool

Enabled checks if action is currently enabled.

An action must be enabled in order to be activated or in order to have its state changed from outside callers.

The function returns the following values:

  • ok: whether the action is enabled.

func (*Action) Name 

func (action *Action) Name() string

Name queries the name of action.

The function returns the following values:

  • utf8: name of the action.

func (*Action) ParameterType 

func (action *Action) ParameterType() *glib.VariantType

ParameterType queries the type of the parameter that must be given when activating action.

When activating the action using g_action_activate(), the #GVariant given to that function must be of the type returned by this function.

In the case that this function returns NULL, you must not give any #GVariant, but NULL instead.

The function returns the following values:

  • variantType (optional): parameter type.

func (*Action) State 

func (action *Action) State() *glib.Variant

State queries the current state of action.

If the action is not stateful then NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_get_state_type().

The return value (if non-NULL) should be freed with g_variant_unref() when it is no longer required.

The function returns the following values:

  • variant (optional): current state of the action.

func (*Action) StateHint 

func (action *Action) StateHint() *glib.Variant

StateHint requests a hint about the valid range of values for the state of action.

If NULL is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action.

If a #GVariant array is returned then each item in the array is a possible value for the state. If a #GVariant pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state.

In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail.

The return value (if non-NULL) should be freed with g_variant_unref() when it is no longer required.

The function returns the following values:

  • variant (optional): state range hint.

func (*Action) StateType 

func (action *Action) StateType() *glib.VariantType

StateType queries the type of the state of action.

If the action is stateful (e.g. created with g_simple_action_new_stateful()) then this function returns the Type of the state. This is the type of the initial value given as the state. All calls to g_action_change_state() must give a #GVariant of this type and g_action_get_state() will return a #GVariant of the same type.

If the action is not stateful (e.g. created with g_simple_action_new()) then this function will return NULL. In that case, g_action_get_state() will return NULL and you must not call g_action_change_state().

The function returns the following values:

  • variantType (optional): state type, if the action is stateful.

type ActionEntry 

type ActionEntry struct {
	// contains filtered or unexported fields
}

ActionEntry: this struct defines a single action. It is for use with g_action_map_add_action_entries().

The order of the items in the structure are intended to reflect frequency of use. It is permissible to use an incomplete initialiser in order to leave some of the later values as NULL. All values after name are optional. Additional optional fields may be added in the future.

See g_action_map_add_action_entries() for an example.

An instance of this type is always passed by reference.

func (*ActionEntry) Name 

func (a *ActionEntry) Name() string

Name: name of the action.

func (*ActionEntry) ParameterType 

func (a *ActionEntry) ParameterType() string

ParameterType: type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or NULL for no parameter).

func (*ActionEntry) State 

func (a *ActionEntry) State() string

State: initial state for this action, given in [GVariant text format][gvariant-text]. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. Stateless actions should give NULL here.

type ActionGroup 

type ActionGroup struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

ActionGroup: GActionGroup represents a group of actions.

Actions can be used to expose functionality in a structured way, either from one part of a program to another, or to the outside world. Action groups are often used together with a GMenuModel that provides additional representation data for displaying the actions to the user, e.g. in a menu.

The main way to interact with the actions in a GActionGroup is to activate them with gio.ActionGroup.ActivateAction(). Activating an action may require a GVariant parameter. The required type of the parameter can be inquired with gio.ActionGroup.GetActionParameterType(). Actions may be disabled, see gio.ActionGroup.GetActionEnabled(). Activating a disabled action has no effect.

Actions may optionally have a state in the form of a #GVariant. The current state of an action can be inquired with gio.ActionGroup.GetActionState(). Activating a stateful action may change its state, but it is also possible to set the state by calling gio.ActionGroup.ChangeActionState().

As typical example, consider a text editing application which has an option to change the current font to 'bold'. A good way to represent this would be a stateful action, with a boolean state. Activating the action would toggle the state.

Each action in the group has a unique name (which is a string). All method calls, except gio.ActionGroup.ListActions() take the name of an action as an argument.

The GActionGroup API is meant to be the 'public' API to the action group. The calls here are exactly the interaction that 'external forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have with actions. 'Internal' APIs (ie: ones meant only to be accessed by the action group implementation) are found on subclasses. This is why you will find - for example - gio.ActionGroup.GetActionEnabled() but not an equivalent set() call.

Signals are emitted on the action group in response to state changes on individual actions.

Implementations of GActionGroup should provide implementations for the virtual functions gio.ActionGroup.ListActions() and gio.ActionGroup.QueryAction(). The other virtual functions should not be implemented - their "wrappers" are actually implemented with calls to gio.ActionGroup.QueryAction().

ActionGroup wraps an interface. This means the user can get the underlying type by calling Cast().

func (*ActionGroup) ActionAdded 

func (actionGroup *ActionGroup) ActionAdded(actionName string)

ActionAdded emits the Group::action-added signal on action_group.

This function should only be called by Group implementations.

The function takes the following parameters:

  • actionName: name of an action in the group.

func (*ActionGroup) ActionEnabled 

func (actionGroup *ActionGroup) ActionEnabled(actionName string) bool

ActionEnabled checks if the named action within action_group is currently enabled.

An action must be enabled in order to be activated or in order to have its state changed from outside callers.

The function takes the following parameters:

  • actionName: name of the action to query.

The function returns the following values:

  • ok: whether or not the action is currently enabled.

func (*ActionGroup) ActionEnabledChanged 

func (actionGroup *ActionGroup) ActionEnabledChanged(actionName string, enabled bool)

ActionEnabledChanged emits the Group::action-enabled-changed signal on action_group.

This function should only be called by Group implementations.

The function takes the following parameters:

  • actionName: name of an action in the group.
  • enabled: whether or not the action is now enabled.

func (*ActionGroup) ActionParameterType 

func (actionGroup *ActionGroup) ActionParameterType(actionName string) *glib.VariantType

ActionParameterType queries the type of the parameter that must be given when activating the named action within action_group.

When activating the action using g_action_group_activate_action(), the #GVariant given to that function must be of the type returned by this function.

In the case that this function returns NULL, you must not give any #GVariant, but NULL instead.

The parameter type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different parameter type.

The function takes the following parameters:

  • actionName: name of the action to query.

The function returns the following values:

  • variantType (optional): parameter type.

func (*ActionGroup) ActionRemoved 

func (actionGroup *ActionGroup) ActionRemoved(actionName string)

ActionRemoved emits the Group::action-removed signal on action_group.

This function should only be called by Group implementations.

The function takes the following parameters:

  • actionName: name of an action in the group.

func (*ActionGroup) ActionState 

func (actionGroup *ActionGroup) ActionState(actionName string) *glib.Variant

ActionState queries the current state of the named action within action_group.

If the action is not stateful then NULL will be returned. If the action is stateful then the type of the return value is the type given by g_action_group_get_action_state_type().

The return value (if non-NULL) should be freed with g_variant_unref() when it is no longer required.

The function takes the following parameters:

  • actionName: name of the action to query.

The function returns the following values:

  • variant (optional): current state of the action.

func (*ActionGroup) ActionStateChanged 

func (actionGroup *ActionGroup) ActionStateChanged(actionName string, state *glib.Variant)

ActionStateChanged emits the Group::action-state-changed signal on action_group.

This function should only be called by Group implementations.

The function takes the following parameters:

  • actionName: name of an action in the group.
  • state: new state of the named action.

func (*ActionGroup) ActionStateHint 

func (actionGroup *ActionGroup) ActionStateHint(actionName string) *glib.Variant

ActionStateHint requests a hint about the valid range of values for the state of the named action within action_group.

If NULL is returned it either means that the action is not stateful or that there is no hint about the valid range of values for the state of the action.

If a #GVariant array is returned then each item in the array is a possible value for the state. If a #GVariant pair (ie: two-tuple) is returned then the tuple specifies the inclusive lower and upper bound of valid values for the state.

In any case, the information is merely a hint. It may be possible to have a state value outside of the hinted range and setting a value within the range may fail.

The return value (if non-NULL) should be freed with g_variant_unref() when it is no longer required.

The function takes the following parameters:

  • actionName: name of the action to query.

The function returns the following values:

  • variant (optional): state range hint.

func (*ActionGroup) ActionStateType 

func (actionGroup *ActionGroup) ActionStateType(actionName string) *glib.VariantType

ActionStateType queries the type of the state of the named action within action_group.

If the action is stateful then this function returns the Type of the state. All calls to g_action_group_change_action_state() must give a #GVariant of this type and g_action_group_get_action_state() will return a #GVariant of the same type.

If the action is not stateful then this function will return NULL. In that case, g_action_group_get_action_state() will return NULL and you must not call g_action_group_change_action_state().

The state type of a particular action will never change but it is possible for an action to be removed and for a new action to be added with the same name but a different state type.

The function takes the following parameters:

  • actionName: name of the action to query.

The function returns the following values:

  • variantType (optional): state type, if the action is stateful.

func (*ActionGroup) ActivateAction 

func (actionGroup *ActionGroup) ActivateAction(actionName string, parameter *glib.Variant)

ActivateAction: activate the named action within action_group.

If the action is expecting a parameter, then the correct type of parameter must be given as parameter. If the action is expecting no parameters then parameter must be NULL. See g_action_group_get_action_parameter_type().

If the Group implementation supports asynchronous remote activation over D-Bus, this call may return before the relevant D-Bus traffic has been sent, or any replies have been received. In order to block on such asynchronous activation calls, g_dbus_connection_flush() should be called prior to the code, which depends on the result of the action activation. Without flushing the D-Bus connection, there is no guarantee that the action would have been activated.

The following code which runs in a remote app instance, shows an example of a "quit" action being activated on the primary app instance over D-Bus. Here g_dbus_connection_flush() is called before exit(). Without g_dbus_connection_flush(), the "quit" action may fail to be activated on the primary instance. 

// call "quit" action on primary instance
g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);

// make sure the action is activated now
g_dbus_connection_flush (...);

g_debug ("application has been terminated. exiting.");

exit (0);.

The function takes the following parameters:

  • actionName: name of the action to activate.
  • parameter (optional) parameters to the activation.

func (*ActionGroup) ChangeActionState 

func (actionGroup *ActionGroup) ChangeActionState(actionName string, value *glib.Variant)

ChangeActionState: request for the state of the named action within action_group to be changed to value.

The action must be stateful and value must be of the correct type. See g_action_group_get_action_state_type().

This call merely requests a change. The action may refuse to change its state or may change its state to something other than value. See g_action_group_get_action_state_hint().

If the value GVariant is floating, it is consumed.

The function takes the following parameters:

  • actionName: name of the action to request the change on.
  • value: new state.

func (*ActionGroup) ConnectActionAdded 

func (actionGroup *ActionGroup) ConnectActionAdded(f func(actionName string)) coreglib.SignalHandle

ConnectActionAdded signals that a new action was just added to the group. This signal is emitted after the action has been added and is now visible.

func (*ActionGroup) ConnectActionEnabledChanged 

func (actionGroup *ActionGroup) ConnectActionEnabledChanged(f func(actionName string, enabled bool)) coreglib.SignalHandle

ConnectActionEnabledChanged signals that the enabled status of the named action has changed.

func (*ActionGroup) ConnectActionRemoved 

func (actionGroup *ActionGroup) ConnectActionRemoved(f func(actionName string)) coreglib.SignalHandle

ConnectActionRemoved signals that an action is just about to be removed from the group. This signal is emitted before the action is removed, so the action is still visible and can be queried from the signal handler.

func (*ActionGroup) ConnectActionStateChanged 

func (actionGroup *ActionGroup) ConnectActionStateChanged(f func(actionName string, value *glib.Variant)) coreglib.SignalHandle

ConnectActionStateChanged signals that the state of the named action has changed.

func (*ActionGroup) HasAction 

func (actionGroup *ActionGroup) HasAction(actionName string) bool

HasAction checks if the named action exists within action_group.

The function takes the following parameters:

  • actionName: name of the action to check for.

The function returns the following values:

  • ok: whether the named action exists.

func (*ActionGroup) ListActions 

func (actionGroup *ActionGroup) ListActions() []string

ListActions lists the actions contained within action_group.

The caller is responsible for freeing the list with g_strfreev() when it is no longer required.

The function returns the following values:

  • utf8s: NULL-terminated array of the names of the actions in the group.

func (*ActionGroup) QueryAction 

func (actionGroup *ActionGroup) QueryAction(actionName string) (enabled bool, parameterType, stateType *glib.VariantType, stateHint, state *glib.Variant, ok bool)

QueryAction queries all aspects of the named action within an action_group.

This function acquires the information available from g_action_group_has_action(), g_action_group_get_action_enabled(), g_action_group_get_action_parameter_type(), g_action_group_get_action_state_type(), g_action_group_get_action_state_hint() and g_action_group_get_action_state() with a single function call.

This provides two main benefits.

The first is the improvement in efficiency that comes with not having to perform repeated lookups of the action in order to discover different things about it. The second is that implementing Group can now be done by only overriding this one virtual function.

The interface provides a default implementation of this function that calls the individual functions, as required, to fetch the information. The interface also provides default implementations of those functions that call this function. All implementations, therefore, must override either this function or all of the others.

If the action exists, TRUE is returned and any of the requested fields (as indicated by having a non-NULL reference passed in) are filled. If the action doesn't exist, FALSE is returned and the fields may or may not have been modified.

The function takes the following parameters:

  • actionName: name of an action in the group.

The function returns the following values:

  • enabled: if the action is presently enabled.
  • parameterType (optional): parameter type, or NULL if none needed.
  • stateType (optional): state type, or NULL if stateless.
  • stateHint (optional): state hint, or NULL if none.
  • state (optional): current state, or NULL if stateless.
  • ok: TRUE if the action exists, else FALSE.

type ActionGroupInterface added in v0.0.5 

type ActionGroupInterface struct {
	// contains filtered or unexported fields
}

ActionGroupInterface: virtual function table for Group.

An instance of this type is always passed by reference.

type ActionGrouper 

type ActionGrouper interface {
	coreglib.Objector

	// ActionAdded emits the Group::action-added signal on action_group.
	ActionAdded(actionName string)
	// ActionEnabledChanged emits the Group::action-enabled-changed signal on
	// action_group.
	ActionEnabledChanged(actionName string, enabled bool)
	// ActionRemoved emits the Group::action-removed signal on action_group.
	ActionRemoved(actionName string)
	// ActionStateChanged emits the Group::action-state-changed signal on
	// action_group.
	ActionStateChanged(actionName string, state *glib.Variant)
	// ActivateAction: activate the named action within action_group.
	ActivateAction(actionName string, parameter *glib.Variant)
	// ChangeActionState: request for the state of the named action within
	// action_group to be changed to value.
	ChangeActionState(actionName string, value *glib.Variant)
	// ActionEnabled checks if the named action within action_group is currently
	// enabled.
	ActionEnabled(actionName string) bool
	// ActionParameterType queries the type of the parameter that must be given
	// when activating the named action within action_group.
	ActionParameterType(actionName string) *glib.VariantType
	// ActionState queries the current state of the named action within
	// action_group.
	ActionState(actionName string) *glib.Variant
	// ActionStateHint requests a hint about the valid range of values for the
	// state of the named action within action_group.
	ActionStateHint(actionName string) *glib.Variant
	// ActionStateType queries the type of the state of the named action within
	// action_group.
	ActionStateType(actionName string) *glib.VariantType
	// HasAction checks if the named action exists within action_group.
	HasAction(actionName string) bool
	// ListActions lists the actions contained within action_group.
	ListActions() []string
	// QueryAction queries all aspects of the named action within an
	// action_group.
	QueryAction(actionName string) (enabled bool, parameterType, stateType *glib.VariantType, stateHint, state *glib.Variant, ok bool)

	// Action-added signals that a new action was just added to the group.
	ConnectActionAdded(func(actionName string)) coreglib.SignalHandle
	// Action-enabled-changed signals that the enabled status of the named
	// action has changed.
	ConnectActionEnabledChanged(func(actionName string, enabled bool)) coreglib.SignalHandle
	// Action-removed signals that an action is just about to be removed from
	// the group.
	ConnectActionRemoved(func(actionName string)) coreglib.SignalHandle
	// Action-state-changed signals that the state of the named action has
	// changed.
	ConnectActionStateChanged(func(actionName string, value *glib.Variant)) coreglib.SignalHandle
}

ActionGrouper describes ActionGroup's interface methods.

type ActionInterface added in v0.0.5 

type ActionInterface struct {
	// contains filtered or unexported fields
}

ActionInterface: virtual function table for gio.Action.

An instance of this type is always passed by reference.

type ActionMap 

type ActionMap struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

ActionMap: GActionMap is an interface for action containers.

The GActionMap interface is implemented by gio.ActionGroup implementations that operate by containing a number of named gio.Action instances, such as gio.SimpleActionGroup.

One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names (e.g. by prepending "app." or "win."). This is the motivation for the 'Map' part of the interface name.

ActionMap wraps an interface. This means the user can get the underlying type by calling Cast().

func (*ActionMap) AddAction 

func (actionMap *ActionMap) AddAction(action Actioner)

AddAction adds an action to the action_map.

If the action map already contains an action with the same name as action then the old action is dropped from the action map.

The action map takes its own reference on action.

The function takes the following parameters:

  • action: #GAction.

func (*ActionMap) AddActionEntries 

func (actionMap *ActionMap) AddActionEntries(entries []ActionEntry, userData unsafe.Pointer)

AddActionEntries: convenience function for creating multiple Action instances and adding them to a Map.

Each action is constructed as per one Entry. 

static void
activate_quit (GSimpleAction *simple,
               GVariant      *parameter,
               gpointer       user_data)
{
  exit (0);
}

static void
activate_print_string (GSimpleAction *simple,
                       GVariant      *parameter,
                       gpointer       user_data)
{
  g_print ("s\n", g_variant_get_string (parameter, NULL));
}

static GActionGroup *
create_action_group (void)
{
  const GActionEntry entries[] = {
    { "quit",         activate_quit              },
    { "print-string", activate_print_string, "s" }
  };
  GSimpleActionGroup *group;

  group = g_simple_action_group_new ();
  g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);

  return G_ACTION_GROUP (group);
}.

The function takes the following parameters:

  • entries: pointer to the first item in an array of Entry structs.
  • userData (optional): user data for signal connections.

func (*ActionMap) LookupAction 

func (actionMap *ActionMap) LookupAction(actionName string) *Action

LookupAction looks up the action with the name action_name in action_map.

If no such action exists, returns NULL.

The function takes the following parameters:

  • actionName: name of an action.

The function returns the following values:

  • action (optional) or NULL.

func (*ActionMap) RemoveAction 

func (actionMap *ActionMap) RemoveAction(actionName string)

RemoveAction removes the named action from the action map.

If no action of this name is in the map then nothing happens.

The function takes the following parameters:

  • actionName: name of the action.

func (*ActionMap) RemoveActionEntries added in v0.3.0 

func (actionMap *ActionMap) RemoveActionEntries(entries []ActionEntry)

RemoveActionEntries: remove actions from a Map. This is meant as the reverse of g_action_map_add_action_entries(). 

static const GActionEntry entries[] = {
    { "quit",         activate_quit              },
    { "print-string", activate_print_string, "s" }
};

void
add_actions (GActionMap *map)
{
  g_action_map_add_action_entries (map, entries, G_N_ELEMENTS (entries), NULL);
}

void
remove_actions (GActionMap *map)
{
  g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries));
}.

The function takes the following parameters:

  • entries: pointer to the first item in an array of Entry structs.

type ActionMapInterface added in v0.0.5 

type ActionMapInterface struct {
	// contains filtered or unexported fields
}

ActionMapInterface: virtual function table for Map.

An instance of this type is always passed by reference.

type ActionMapper 

type ActionMapper interface {
	coreglib.Objector

	// AddAction adds an action to the action_map.
	AddAction(action Actioner)
	// AddActionEntries: convenience function for creating multiple Action
	// instances and adding them to a Map.
	AddActionEntries(entries []ActionEntry, userData unsafe.Pointer)
	// LookupAction looks up the action with the name action_name in action_map.
	LookupAction(actionName string) *Action
	// RemoveAction removes the named action from the action map.
	RemoveAction(actionName string)
	// RemoveActionEntries: remove actions from a Map.
	RemoveActionEntries(entries []ActionEntry)
}

ActionMapper describes ActionMap's interface methods.

type Actioner 

type Actioner interface {
	coreglib.Objector

	// Activate activates the action.
	Activate(parameter *glib.Variant)
	// ChangeState: request for the state of action to be changed to value.
	ChangeState(value *glib.Variant)
	// Enabled checks if action is currently enabled.
	Enabled() bool
	// Name queries the name of action.
	Name() string
	// ParameterType queries the type of the parameter that must be given when
	// activating action.
	ParameterType() *glib.VariantType
	// State queries the current state of action.
	State() *glib.Variant
	// StateHint requests a hint about the valid range of values for the state
	// of action.
	StateHint() *glib.Variant
	// StateType queries the type of the state of action.
	StateType() *glib.VariantType
}

Actioner describes Action's interface methods.

type AppInfo 

type AppInfo struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

AppInfo: information about an installed application and methods to launch it (with file arguments).

GAppInfo and GAppLaunchContext are used for describing and launching applications installed on the system.

As of GLib 2.20, URIs will always be converted to POSIX paths (using gio.File.GetPath()) when using gio.AppInfo.Launch() even if the application requested an URI and not a POSIX path. For example for a desktop-file based application with Exec key totem U and a single URI, sftp://foo/file.avi, then /home/user/.gvfs/sftp on foo/file.avi will be passed. This will only work if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed unmodified to the application. Some URIs, such as mailto:, of course cannot be mapped to a POSIX path (in GVfs there's no FUSE mount for it); such URIs will be passed unmodified to the application.

Specifically for GVfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the gio.File constructors (since GVfs implements the GVfs extension point). As such, if the application needs to examine the URI, it needs to use gio.File.GetURI() or similar on gio.File. In other words, an application cannot assume that the URI passed to e.g. gio.File().NewForCommandlineArg is equal to the result of gio.File.GetURI(). The following snippet illustrates this: 

GFile *f;
char *uri;

file = g_file_new_for_commandline_arg (uri_from_commandline);

uri = g_file_get_uri (file);
strcmp (uri, uri_from_commandline) == 0;
g_free (uri);

if (g_file_has_uri_scheme (file, "cdda"))
  {
    // do something special with uri
  }
g_object_unref (file);

This code will work when both cdda://sr0/Track 1.wav and /home/user/.gvfs/cdda on sr0/Track 1.wav is passed to the application. It should be noted that it's generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means.

AppInfo wraps an interface. This means the user can get the underlying type by calling Cast().

func AppInfoCreateFromCommandline 

func AppInfoCreateFromCommandline(commandline, applicationName string, flags AppInfoCreateFlags) (*AppInfo, error)

AppInfoCreateFromCommandline creates a new Info from the given information.

Note that for commandline, the quoting rules of the Exec key of the freedesktop.org Desktop Entry Specification (http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from being swallowed by Exec key unquoting. See the specification for exact quoting rules.

The function takes the following parameters:

  • commandline to use.
  • applicationName (optional): application name, or NULL to use commandline.
  • flags that can specify details of the created Info.

The function returns the following values:

  • appInfo: new Info for given command.

func AppInfoGetAll 

func AppInfoGetAll() []*AppInfo

AppInfoGetAll gets a list of all of the applications currently registered on this system.

For desktop files, this includes applications that have NoDisplay=true set or are excluded from display by means of OnlyShowIn or NotShowIn. See g_app_info_should_show(). The returned list does not include applications which have the Hidden key set.

The function returns the following values:

  • list: newly allocated #GList of references to Infos.

func AppInfoGetAllForType 

func AppInfoGetAllForType(contentType string) []*AppInfo

AppInfoGetAllForType gets a list of all Infos for a given content type, including the recommended and fallback Infos. See g_app_info_get_recommended_for_type() and g_app_info_get_fallback_for_type().

The function takes the following parameters:

  • contentType: content type to find a Info for.

The function returns the following values:

  • list of Infos for given content_type or NULL on error.

func AppInfoGetDefaultForType 

func AppInfoGetDefaultForType(contentType string, mustSupportUris bool) *AppInfo

AppInfoGetDefaultForType gets the default Info for a given content type.

The function takes the following parameters:

  • contentType: content type to find a Info for.
  • mustSupportUris: if TRUE, the Info is expected to support URIs.

The function returns the following values:

  • appInfo (optional) for given content_type or NULL on error.

func AppInfoGetDefaultForTypeFinish added in v0.3.0 

func AppInfoGetDefaultForTypeFinish(result AsyncResulter) (*AppInfo, error)

AppInfoGetDefaultForTypeFinish finishes a default Info lookup started by g_app_info_get_default_for_type_async().

If no Info is found, then error will be set to G_IO_ERROR_NOT_FOUND.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • appInfo for given content_type or NULL on error.

func AppInfoGetDefaultForURIScheme 

func AppInfoGetDefaultForURIScheme(uriScheme string) *AppInfo

AppInfoGetDefaultForURIScheme gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', e.g. "http", "ftp" or "sip".

The function takes the following parameters:

  • uriScheme: string containing a URI scheme.

The function returns the following values:

  • appInfo (optional) for given uri_scheme or NULL on error.

func AppInfoGetDefaultForURISchemeFinish added in v0.3.0 

func AppInfoGetDefaultForURISchemeFinish(result AsyncResulter) (*AppInfo, error)

AppInfoGetDefaultForURISchemeFinish finishes a default Info lookup started by g_app_info_get_default_for_uri_scheme_async().

If no Info is found, then error will be set to G_IO_ERROR_NOT_FOUND.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • appInfo for given uri_scheme or NULL on error.

func AppInfoGetFallbackForType 

func AppInfoGetFallbackForType(contentType string) []*AppInfo

AppInfoGetFallbackForType gets a list of fallback Infos for a given content type, i.e. those applications which claim to support the given content type by MIME type subclassing and not directly.

The function takes the following parameters:

  • contentType: content type to find a Info for.

The function returns the following values:

  • list of Infos for given content_type or NULL on error.

func AppInfoGetRecommendedForType 

func AppInfoGetRecommendedForType(contentType string) []*AppInfo

AppInfoGetRecommendedForType gets a list of recommended Infos for a given content type, i.e. those applications which claim to support the given content type exactly, and not by MIME type subclassing. Note that the first application of the list is the last used one, i.e. the last one for which g_app_info_set_as_last_used_for_type() has been called.

The function takes the following parameters:

  • contentType: content type to find a Info for.

The function returns the following values:

  • list of Infos for given content_type or NULL on error.

func (*AppInfo) AddSupportsType 

func (appinfo *AppInfo) AddSupportsType(contentType string) error

AddSupportsType adds a content type to the application information to indicate the application is capable of opening files with the given content type.

The function takes the following parameters:

  • contentType: string.

func (*AppInfo) CanDelete 

func (appinfo *AppInfo) CanDelete() bool

CanDelete obtains the information whether the Info can be deleted. See g_app_info_delete().

The function returns the following values:

  • ok: TRUE if appinfo can be deleted.

func (*AppInfo) CanRemoveSupportsType 

func (appinfo *AppInfo) CanRemoveSupportsType() bool

CanRemoveSupportsType checks if a supported content type can be removed from an application.

The function returns the following values:

  • ok: TRUE if it is possible to remove supported content types from a given appinfo, FALSE if not.

func (*AppInfo) Commandline 

func (appinfo *AppInfo) Commandline() string

Commandline gets the commandline with which the application will be started.

The function returns the following values:

  • filename (optional): string containing the appinfo's commandline, or NULL if this information is not available.

func (*AppInfo) Delete 

func (appinfo *AppInfo) Delete() bool

Delete tries to delete a Info.

On some platforms, there may be a difference between user-defined Infos which can be deleted, and system-wide ones which cannot. See g_app_info_can_delete().

The function returns the following values:

  • ok: TRUE if appinfo has been deleted.

func (*AppInfo) Description 

func (appinfo *AppInfo) Description() string

Description gets a human-readable description of an installed application.

The function returns the following values:

  • utf8 (optional): string containing a description of the application appinfo, or NULL if none.

func (*AppInfo) DisplayName 

func (appinfo *AppInfo) DisplayName() string

DisplayName gets the display name of the application. The display name is often more descriptive to the user than the name itself.

The function returns the following values:

  • utf8: display name of the application for appinfo, or the name if no display name is available.

func (*AppInfo) Dup 

func (appinfo *AppInfo) Dup() *AppInfo

Dup creates a duplicate of a Info.

The function returns the following values:

  • appInfo: duplicate of appinfo.

func (*AppInfo) Equal 

func (appinfo1 *AppInfo) Equal(appinfo2 AppInfor) bool

Equal checks if two Infos are equal.

Note that the check *may not* compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields.

The function takes the following parameters:

  • appinfo2: second Info.

The function returns the following values:

  • ok: TRUE if appinfo1 is equal to appinfo2. FALSE otherwise.

func (*AppInfo) Executable 

func (appinfo *AppInfo) Executable() string

Executable gets the executable's name for the installed application.

This is intended to be used for debugging or labelling what program is going to be run. To launch the executable, use g_app_info_launch() and related functions, rather than spawning the return value from this function.

The function returns the following values:

  • filename: string containing the appinfo's application binaries name.

func (*AppInfo) ID 

func (appinfo *AppInfo) ID() string

ID gets the ID of an application. An id is a string that identifies the application. The exact format of the id is platform dependent. For instance, on Unix this is the desktop file id from the xdg menu specification.

Note that the returned ID may be NULL, depending on how the appinfo has been constructed.

The function returns the following values:

  • utf8 (optional): string containing the application's ID.

func (*AppInfo) Icon 

func (appinfo *AppInfo) Icon() *Icon

Icon gets the icon for the application.

The function returns the following values:

  • icon (optional): default #GIcon for appinfo or NULL if there is no default icon.

func (*AppInfo) Launch 

func (appinfo *AppInfo) Launch(files []Filer, context *AppLaunchContext) error

Launch launches the application. Passes files to the launched application as arguments, using the optional context to get information about the details of the launcher (like what screen it is on). On error, error will be set accordingly.

To launch the application without arguments pass a NULL files list.

Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this.

Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using g_app_info_launch_uris() instead.

The launched application inherits the environment of the launching process, but it can be modified with g_app_launch_context_setenv() and g_app_launch_context_unsetenv().

On UNIX, this function sets the GIO_LAUNCHED_DESKTOP_FILE environment variable with the path of the launched desktop file and GIO_LAUNCHED_DESKTOP_FILE_PID to the process id of the launched process. This can be used to ignore GIO_LAUNCHED_DESKTOP_FILE, should it be inherited by further processes. The DISPLAY, XDG_ACTIVATION_TOKEN and DESKTOP_STARTUP_ID environment variables are also set, based on information provided in context.

The function takes the following parameters:

  • files (optional) of #GFile objects.
  • context (optional) or NULL.

func (*AppInfo) LaunchURIs 

func (appinfo *AppInfo) LaunchURIs(uris []string, context *AppLaunchContext) error

LaunchURIs launches the application. This passes the uris to the launched application as arguments, using the optional context to get information about the details of the launcher (like what screen it is on). On error, error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned.

To launch the application without arguments pass a NULL uris list.

Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this.

The function takes the following parameters:

  • uris (optional) containing URIs to launch.
  • context (optional) or NULL.

func (*AppInfo) LaunchURIsAsync 

func (appinfo *AppInfo) LaunchURIsAsync(ctx context.Context, uris []string, context *AppLaunchContext, callback AsyncReadyCallback)

LaunchURIsAsync: async version of g_app_info_launch_uris().

The callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for g_app_info_launch_default_for_uri_async().

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • uris (optional) containing URIs to launch.
  • context (optional) or NULL.
  • callback (optional) to call when the request is done.

func (*AppInfo) LaunchURIsFinish 

func (appinfo *AppInfo) LaunchURIsFinish(result AsyncResulter) error

LaunchURIsFinish finishes a g_app_info_launch_uris_async() operation.

The function takes the following parameters:

  • result: Result.

func (*AppInfo) Name 

func (appinfo *AppInfo) Name() string

Name gets the installed name of the application.

The function returns the following values:

  • utf8: name of the application for appinfo.

func (*AppInfo) RemoveSupportsType 

func (appinfo *AppInfo) RemoveSupportsType(contentType string) error

RemoveSupportsType removes a supported type from an application, if possible.

The function takes the following parameters:

  • contentType: string.

func (*AppInfo) SetAsDefaultForExtension 

func (appinfo *AppInfo) SetAsDefaultForExtension(extension string) error

SetAsDefaultForExtension sets the application as the default handler for the given file extension.

The function takes the following parameters:

  • extension: string containing the file extension (without the dot).

func (*AppInfo) SetAsDefaultForType 

func (appinfo *AppInfo) SetAsDefaultForType(contentType string) error

SetAsDefaultForType sets the application as the default handler for a given type.

The function takes the following parameters:

  • contentType: content type.

func (*AppInfo) SetAsLastUsedForType 

func (appinfo *AppInfo) SetAsLastUsedForType(contentType string) error

SetAsLastUsedForType sets the application as the last used application for a given type. This will make the application appear as first in the list returned by g_app_info_get_recommended_for_type(), regardless of the default application for that content type.

The function takes the following parameters:

  • contentType: content type.

func (*AppInfo) ShouldShow 

func (appinfo *AppInfo) ShouldShow() bool

ShouldShow checks if the application info should be shown in menus that list available applications.

The function returns the following values:

  • ok: TRUE if the appinfo should be shown, FALSE otherwise.

func (*AppInfo) SupportedTypes 

func (appinfo *AppInfo) SupportedTypes() []string

SupportedTypes retrieves the list of content types that app_info claims to support. If this information is not provided by the environment, this function will return NULL. This function does not take in consideration associations added with g_app_info_add_supports_type(), but only those exported directly by the application.

The function returns the following values:

  • utf8s: a list of content types.

func (*AppInfo) SupportsFiles 

func (appinfo *AppInfo) SupportsFiles() bool

SupportsFiles checks if the application accepts files as arguments.

The function returns the following values:

  • ok: TRUE if the appinfo supports files.

func (*AppInfo) SupportsURIs 

func (appinfo *AppInfo) SupportsURIs() bool

SupportsURIs checks if the application supports reading files and directories from URIs.

The function returns the following values:

  • ok: TRUE if the appinfo supports URIs.

type AppInfoCreateFlags 

type AppInfoCreateFlags C.guint

AppInfoCreateFlags flags used when creating a Info. 

const (
	// AppInfoCreateNone: no flags.
	AppInfoCreateNone AppInfoCreateFlags = 0b0
	// AppInfoCreateNeedsTerminal: application opens in a terminal window.
	AppInfoCreateNeedsTerminal AppInfoCreateFlags = 0b1
	// AppInfoCreateSupportsURIs: application supports URI arguments.
	AppInfoCreateSupportsURIs AppInfoCreateFlags = 0b10
	// AppInfoCreateSupportsStartupNotification: application supports startup
	// notification. Since 2.26.
	AppInfoCreateSupportsStartupNotification AppInfoCreateFlags = 0b100
)

func (AppInfoCreateFlags) Has 

func (a AppInfoCreateFlags) Has(other AppInfoCreateFlags) bool

Has returns true if a contains other.

func (AppInfoCreateFlags) String 

func (a AppInfoCreateFlags) String() string

String returns the names in string for AppInfoCreateFlags.

type AppInfoIface added in v0.0.5 

type AppInfoIface struct {
	// contains filtered or unexported fields
}

AppInfoIface: application Information interface, for operating system portability.

An instance of this type is always passed by reference.

type AppInfoMonitor 

type AppInfoMonitor struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

AppInfoMonitor: GAppInfoMonitor monitors application information for changes.

GAppInfoMonitor is a very simple object used for monitoring the app info database for changes (newly installed or removed applications).

Call gio.AppInfoMonitor().Get to get a GAppInfoMonitor and connect to the gio.AppInfoMonitor::changed signal. The signal will be emitted once when the app info database changes, and will not be emitted again until after the next call to gio.AppInfo().GetAll or another g_app_info_*() function. This is because monitoring the app info database for changes is expensive.

The following functions will re-arm the gio.AppInfoMonitor::changed signal so it can be emitted again:

  • gio.AppInfo().GetAll
  • gio.AppInfo().GetAllForType
  • gio.AppInfo().GetDefaultForType
  • gio.AppInfo().GetFallbackForType
  • gio.AppInfo().GetRecommendedForType
  • g_desktop_app_info_get_implementations() (../gio-unix/type_func.DesktopAppInfo.get_implementation.html)
  • g_desktop_app_info_new() (../gio-unix/ctor.DesktopAppInfo.new.html)
  • g_desktop_app_info_new_from_filename() (../gio-unix/ctor.DesktopAppInfo.new_from_filename.html)
  • g_desktop_app_info_new_from_keyfile() (../gio-unix/ctor.DesktopAppInfo.new_from_keyfile.html)
  • g_desktop_app_info_search() (../gio-unix/type_func.DesktopAppInfo.search.html)

The latter functions are available if using GDesktopAppInfo (../gio-unix/class.DesktopAppInfo.html) from gio-unix-2.0.pc (GIR namespace GioUnix-2.0).

In the usual case, applications should try to make note of the change (doing things like invalidating caches) but not act on it. In particular, applications should avoid making calls to GAppInfo APIs in response to the change signal, deferring these until the time that the updated data is actually required. The exception to this case is when application information is actually being displayed on the screen (for example, during a search or when the list of all applications is shown). The reason for this is that changes to the list of installed applications often come in groups (like during system updates) and rescanning the list on every change is pointless and expensive.

func AppInfoMonitorGet 

func AppInfoMonitorGet() *AppInfoMonitor

AppInfoMonitorGet gets the InfoMonitor for the current thread-default main context.

The InfoMonitor will emit a "changed" signal in the thread-default main context whenever the list of installed applications (as reported by g_app_info_get_all()) may have changed.

The InfoMonitor::changed signal will only be emitted once until g_app_info_get_all() (or another g_app_info_*() function) is called. Doing so will re-arm the signal ready to notify about the next change.

You must only call g_object_unref() on the return value from under the same main context as you created it.

The function returns the following values:

  • appInfoMonitor: reference to a InfoMonitor.

func (*AppInfoMonitor) ConnectChanged 

func (v *AppInfoMonitor) ConnectChanged(f func()) coreglib.SignalHandle

ConnectChanged: signal emitted when the app info database changes, when applications are installed or removed.

type AppInfor 

type AppInfor interface {
	coreglib.Objector

	// AddSupportsType adds a content type to the application information to
	// indicate the application is capable of opening files with the given
	// content type.
	AddSupportsType(contentType string) error
	// CanDelete obtains the information whether the Info can be deleted.
	CanDelete() bool
	// CanRemoveSupportsType checks if a supported content type can be removed
	// from an application.
	CanRemoveSupportsType() bool
	// Delete tries to delete a Info.
	Delete() bool
	// Dup creates a duplicate of a Info.
	Dup() *AppInfo
	// Equal checks if two Infos are equal.
	Equal(appinfo2 AppInfor) bool
	// Commandline gets the commandline with which the application will be
	// started.
	Commandline() string
	// Description gets a human-readable description of an installed
	// application.
	Description() string
	// DisplayName gets the display name of the application.
	DisplayName() string
	// Executable gets the executable's name for the installed application.
	Executable() string
	// Icon gets the icon for the application.
	Icon() *Icon
	// ID gets the ID of an application.
	ID() string
	// Name gets the installed name of the application.
	Name() string
	// SupportedTypes retrieves the list of content types that app_info claims
	// to support.
	SupportedTypes() []string
	// Launch launches the application.
	Launch(files []Filer, context *AppLaunchContext) error
	// LaunchURIs launches the application.
	LaunchURIs(uris []string, context *AppLaunchContext) error
	// LaunchURIsAsync: async version of g_app_info_launch_uris().
	LaunchURIsAsync(ctx context.Context, uris []string, context *AppLaunchContext, callback AsyncReadyCallback)
	// LaunchURIsFinish finishes a g_app_info_launch_uris_async() operation.
	LaunchURIsFinish(result AsyncResulter) error
	// RemoveSupportsType removes a supported type from an application,
	// if possible.
	RemoveSupportsType(contentType string) error
	// SetAsDefaultForExtension sets the application as the default handler for
	// the given file extension.
	SetAsDefaultForExtension(extension string) error
	// SetAsDefaultForType sets the application as the default handler for a
	// given type.
	SetAsDefaultForType(contentType string) error
	// SetAsLastUsedForType sets the application as the last used application
	// for a given type.
	SetAsLastUsedForType(contentType string) error
	// ShouldShow checks if the application info should be shown in menus that
	// list available applications.
	ShouldShow() bool
	// SupportsFiles checks if the application accepts files as arguments.
	SupportsFiles() bool
	// SupportsURIs checks if the application supports reading files and
	// directories from URIs.
	SupportsURIs() bool
}

AppInfor describes AppInfo's interface methods.

type AppLaunchContext 

type AppLaunchContext struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

AppLaunchContext: integrating the launch with the launching application. This is used to handle for instance startup notification and launching the new application on the same screen as the launching window.

func NewAppLaunchContext 

func NewAppLaunchContext() *AppLaunchContext

NewAppLaunchContext creates a new application launch context. This is not normally used, instead you instantiate a subclass of this, such as AppLaunchContext.

The function returns the following values:

  • appLaunchContext: LaunchContext.

func (*AppLaunchContext) ConnectLaunchFailed 

func (context *AppLaunchContext) ConnectLaunchFailed(f func(startupNotifyId string)) coreglib.SignalHandle

ConnectLaunchFailed signal is emitted when a Info launch fails. The startup notification id is provided, so that the launcher can cancel the startup notification.

Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance.

func (*AppLaunchContext) ConnectLaunchStarted added in v0.3.0 

func (context *AppLaunchContext) ConnectLaunchStarted(f func(info AppInfor, platformData *glib.Variant)) coreglib.SignalHandle

ConnectLaunchStarted signal is emitted when a Info is about to be launched. If non-null the platform_data is an GVariant dictionary mapping strings to variants (ie a{sv}), which contains additional, platform-specific data about this launch. On UNIX, at least the startup-notification-id keys will be present.

The value of the startup-notification-id key (type s) is a startup notification ID corresponding to the format from the [startup-notification specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt). It allows tracking the progress of the launchee through startup.

It is guaranteed that this signal is followed by either a LaunchContext::launched or LaunchContext::launch-failed signal.

Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one for each spawned instance.

func (*AppLaunchContext) ConnectLaunched 

func (context *AppLaunchContext) ConnectLaunched(f func(info AppInfor, platformData *glib.Variant)) coreglib.SignalHandle

ConnectLaunched signal is emitted when a Info is successfully launched.

Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple times, one time for each spawned instance.

The platform_data is an GVariant dictionary mapping strings to variants (ie a{sv}), which contains additional, platform-specific data about this launch. On UNIX, at least the pid and startup-notification-id keys will be present.

Since 2.72 the pid may be 0 if the process id wasn't known (for example if the process was launched via D-Bus). The pid may not be set at all in subsequent releases.

On Windows, pid is guaranteed to be valid only for the duration of the LaunchContext::launched signal emission; after the signal is emitted, GLib will call g_spawn_close_pid(). If you need to keep the #GPid after the signal has been emitted, then you can duplicate pid using DuplicateHandle().

func (*AppLaunchContext) Display 

func (context *AppLaunchContext) Display(info AppInfor, files []Filer) string

Display gets the display string for the context. This is used to ensure new applications are started on the same display as the launching application, by setting the DISPLAY environment variable.

The function takes the following parameters:

  • info: Info.
  • files of #GFile objects.

The function returns the following values:

  • utf8 (optional): display string for the display.

func (*AppLaunchContext) Environment 

func (context *AppLaunchContext) Environment() []string

Environment gets the complete environment variable list to be passed to the child process when context is used to launch an application. This is a NULL-terminated array of strings, where each string has the form KEY=VALUE.

The function returns the following values:

  • filenames: the child's environment.

func (*AppLaunchContext) LaunchFailed 

func (context *AppLaunchContext) LaunchFailed(startupNotifyId string)

LaunchFailed: called when an application has failed to launch, so that it can cancel the application startup notification started in g_app_launch_context_get_startup_notify_id().

The function takes the following parameters:

  • startupNotifyId: startup notification id that was returned by g_app_launch_context_get_startup_notify_id().

func (*AppLaunchContext) Setenv 

func (context *AppLaunchContext) Setenv(variable, value string)

Setenv arranges for variable to be set to value in the child's environment when context is used to launch an application.

The function takes the following parameters:

  • variable: environment variable to set.
  • value for to set the variable to.

func (*AppLaunchContext) StartupNotifyID 

func (context *AppLaunchContext) StartupNotifyID(info AppInfor, files []Filer) string

StartupNotifyID initiates startup notification for the application and returns the XDG_ACTIVATION_TOKEN or DESKTOP_STARTUP_ID for the launched operation, if supported.

The returned token may be referred to equivalently as an ‘activation token’ (using Wayland terminology) or a ‘startup sequence ID’ (using X11 terminology). The two are interoperable (https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).

Activation tokens are defined in the XDG Activation Protocol (https://wayland.app/protocols/xdg-activation-v1), and startup notification IDs are defined in the freedesktop.org Startup Notification Protocol (http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).

Support for the XDG Activation Protocol was added in GLib 2.76.

The function takes the following parameters:

  • info: Info.
  • files of #GFile objects.

The function returns the following values:

  • utf8 (optional): startup notification ID for the application, or NULL if not supported.

func (*AppLaunchContext) Unsetenv 

func (context *AppLaunchContext) Unsetenv(variable string)

Unsetenv arranges for variable to be unset in the child's environment when context is used to launch an application.

The function takes the following parameters:

  • variable: environment variable to remove.

type AppLaunchContextClass added in v0.0.5 

type AppLaunchContextClass struct {
	// contains filtered or unexported fields
}

AppLaunchContextClass: instance of this type is always passed by reference.

type AppLaunchContextOverrides added in v0.0.5 

type AppLaunchContextOverrides struct {
	// Display gets the display string for the context. This is used to ensure
	// new applications are started on the same display as the launching
	// application, by setting the DISPLAY environment variable.
	//
	// The function takes the following parameters:
	//
	//   - info: Info.
	//   - files of #GFile objects.
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): display string for the display.
	Display func(info AppInfor, files []Filer) string
	// StartupNotifyID initiates startup notification for the application and
	// returns the XDG_ACTIVATION_TOKEN or DESKTOP_STARTUP_ID for the launched
	// operation, if supported.
	//
	// The returned token may be referred to equivalently as an
	// ‘activation token’ (using Wayland terminology) or a ‘startup
	// sequence ID’ (using X11 terminology). The two are interoperable
	// (https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/xdg-activation/x11-interoperation.rst).
	//
	// Activation tokens are defined in the XDG Activation
	// Protocol (https://wayland.app/protocols/xdg-activation-v1),
	// and startup notification IDs are defined in the
	// freedesktop.org Startup Notification Protocol
	// (http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt).
	//
	// Support for the XDG Activation Protocol was added in GLib 2.76.
	//
	// The function takes the following parameters:
	//
	//   - info: Info.
	//   - files of #GFile objects.
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): startup notification ID for the application, or NULL
	//     if not supported.
	StartupNotifyID func(info AppInfor, files []Filer) string
	// LaunchFailed: called when an application has failed to launch,
	// so that it can cancel the application startup notification started in
	// g_app_launch_context_get_startup_notify_id().
	//
	// The function takes the following parameters:
	//
	//   - startupNotifyId: startup notification id that was returned by
	//     g_app_launch_context_get_startup_notify_id().
	LaunchFailed func(startupNotifyId string)
	// The function takes the following parameters:
	//
	//   - info
	//   - platformData
	LaunchStarted func(info AppInfor, platformData *glib.Variant)
	// The function takes the following parameters:
	//
	//   - info
	//   - platformData
	Launched func(info AppInfor, platformData *glib.Variant)
}

AppLaunchContextOverrides contains methods that are overridable.

type Application 

type Application struct {
	*coreglib.Object

	ActionGroup
	ActionMap
	// contains filtered or unexported fields
}

Application: GApplication is the core class for application support.

A GApplication is the foundation of an application. It wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as GtkApplication or MxApplication. In general, you should not use this class outside of a higher level framework.

GApplication provides convenient life-cycle management by maintaining a "use count" for the primary application instance. The use count can be changed using gio.Application.Hold() and gio.Application.Release(). If it drops to zero, the application exits. Higher-level classes such as GtkApplication employ the use count to ensure that the application stays alive as long as it has any opened windows.

Another feature that GApplication (optionally) provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session concept is platform-dependent, but corresponds roughly to a graphical desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the "primary instance"; for non-unique applications this is always the current instance. On Linux, the D-Bus session bus is used for communication.

The use of GApplication differs from some other commonly-used uniqueness libraries (such as libunique) in important ways. The application is not expected to manually register itself and check if it is the primary instance. Instead, the main() function of a GApplication should do very little more than instantiating the application instance, possibly connecting signal handlers, then calling gio.Application.Run(). All checks for uniqueness are done internally. If the application is the primary instance then the startup signal is emitted and the mainloop runs. If the application is not the primary instance then a signal is sent to the primary instance and gio.Application.Run() promptly returns. See the code examples below.

If used, the expected form of an application identifier is the same as that of a D-Bus well-known bus name (https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). Examples include: com.example.MyApp, org.example.internal_apps.Calculator, org._7_zip.Archiver. For details on valid application identifiers, see gio.Application().IDIsValid.

On Linux, the application identifier is claimed as a well-known bus name on the user's session bus. This means that the uniqueness of your application is scoped to the current session. It also means that your application may provide additional services (through registration of other object paths) at that bus name. The registration of these object paths should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before #GApplication attempts to acquire the bus name of your application (which happens in gio.Application.Register()). Unfortunately, this means that you cannot use gio.Application:is-remote to decide if you want to register object paths.

GApplication also implements the gio.ActionGroup and gio.ActionMap interfaces and lets you easily export actions by adding them with gio.ActionMap.AddAction(). When invoking an action by calling gio.ActionGroup.ActivateAction() on the application, it is always invoked in the primary instance. The actions are also exported on the session bus, and GIO provides the gio.DBusActionGroup wrapper to conveniently access them remotely. GIO provides a gio.DBusMenuModel wrapper for remote access to exported gio.MenuModels.

Note: Due to the fact that actions are exported on the session bus, using maybe parameters is not supported, since D-Bus does not support maybe types.

There is a number of different entry points into a GApplication:

- via 'Activate' (i.e. just starting the application)

- via 'Open' (i.e. opening some files)

- by handling a command-line

- via activating an action

The gio.Application::startup signal lets you handle the application initialization for all of these in a single place.

Regardless of which of these entry points is used to start the application, GApplication passes some ‘platform data’ from the launching instance to the primary instance, in the form of a glib.Variant dictionary mapping strings to variants. To use platform data, override the gio.Application.BeforeEmit() or gio.Application.AfterEmit() virtual functions in your GApplication subclass. When dealing with gio.ApplicationCommandLine objects, the platform data is directly available via gio.ApplicationCommandLine.GetCwd(), gio.ApplicationCommandLine.GetEnviron() and gio.ApplicationCommandLine.GetPlatformData().

As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key cwd), and optionally the environment (ie the set of environment variables and their values) of the calling process (key environ). The environment is only added to the platform data if the G_APPLICATION_SEND_ENVIRONMENT flag is set. GApplication subclasses can add their own platform data by overriding the gio.Application.AddPlatformData() virtual function. For instance, GtkApplication adds startup notification data in this way.

To parse commandline arguments you may handle the gio.Application::command-line signal or override the gio.Application.LocalCommandLine() virtual funcion, to parse them in either the primary instance or the local instance, respectively.

For an example of opening files with a GApplication, see gapplication-example-open.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c).

For an example of using actions with GApplication, see gapplication-example-actions.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c).

For an example of using extra D-Bus hooks with GApplication, see gapplication-example-dbushooks.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c).

func ApplicationGetDefault 

func ApplicationGetDefault() *Application

ApplicationGetDefault returns the default #GApplication instance for this process.

Normally there is only one #GApplication per process and it becomes the default when it is created. You can exercise more control over this by using g_application_set_default().

If there is no default application then NULL is returned.

The function returns the following values:

  • application (optional): default application for this process, or NULL.

func NewApplication 

func NewApplication(applicationId string, flags ApplicationFlags) *Application

NewApplication creates a new #GApplication instance.

If non-NULL, the application id must be valid. See g_application_id_is_valid().

If no application ID is given then some features of #GApplication (most notably application uniqueness) will be disabled.

The function takes the following parameters:

  • applicationId (optional): application id.
  • flags: application flags.

The function returns the following values:

  • application: new #GApplication instance.

func (*Application) Activate 

func (application *Application) Activate()

Activate activates the application.

In essence, this results in the #GApplication::activate signal being emitted in the primary instance.

The application must be registered before calling this function.

func (*Application) AddMainOption 

func (application *Application) AddMainOption(longName string, shortName byte, flags glib.OptionFlags, arg glib.OptionArg, description, argDescription string)

AddMainOption: add an option to be handled by application.

Calling this function is the equivalent of calling g_application_add_main_option_entries() with a single Entry that has its arg_data member set to NULL.

The parsed arguments will be packed into a Dict which is passed to #GApplication::handle-local-options. If G_APPLICATION_HANDLES_COMMAND_LINE is set, then it will also be sent to the primary instance. See g_application_add_main_option_entries() for more details.

See Entry for more documentation of the arguments.

The function takes the following parameters:

  • longName: long name of an option used to specify it in a commandline.
  • shortName: short name of an option.
  • flags from Flags.
  • arg: type of the option, as a Arg.
  • description for the option in --help output.
  • argDescription (optional): placeholder to use for the extra argument parsed by the option in --help output.

func (*Application) AddMainOptionEntries 

func (application *Application) AddMainOptionEntries(entries []glib.OptionEntry)

AddMainOptionEntries adds main option entries to be handled by application.

This function is comparable to g_option_context_add_main_entries().

After the commandline arguments are parsed, the #GApplication::handle-local-options signal will be emitted. At this point, the application can inspect the values pointed to by arg_data in the given Entrys.

Unlike Context, #GApplication supports giving a NULL arg_data for a non-callback Entry. This results in the argument in question being packed into a Dict which is also passed to #GApplication::handle-local-options, where it can be inspected and modified. If G_APPLICATION_HANDLES_COMMAND_LINE is set, then the resulting dictionary is sent to the primary instance, where g_application_command_line_get_options_dict() will return it. As it has been passed outside the process at this point, the types of all values in the options dict must be checked before being used. This "packing" is done according to the type of the argument -- booleans for normal flags, strings for strings, bytestrings for filenames, etc. The packing only occurs if the flag is given (ie: we do not pack a "false" #GVariant in the case that a flag is missing).

In general, it is recommended that all commandline arguments are parsed locally. The options dictionary should then be used to transmit the result of the parsing to the primary instance, where g_variant_dict_lookup() can be used. For local options, it is possible to either use arg_data in the usual way, or to consult (and potentially remove) the option from the options dictionary.

This function is new in GLib 2.40. Before then, the only real choice was to send all of the commandline arguments (options and all) to the primary instance for handling. #GApplication ignored them completely on the local side. Calling this function "opts in" to the new behaviour, and in particular, means that unrecognised options will be treated as errors. Unrecognised options have never been ignored when G_APPLICATION_HANDLES_COMMAND_LINE is unset.

If #GApplication::handle-local-options needs to see the list of filenames, then the use of G_OPTION_REMAINING is recommended. If arg_data is NULL then G_OPTION_REMAINING can be used as a key into the options dictionary. If you do use G_OPTION_REMAINING then you need to handle these arguments for yourself because once they are consumed, they will no longer be visible to the default handling (which treats them as filenames to be opened).

It is important to use the proper GVariant format when retrieving the options with g_variant_dict_lookup():

- for G_OPTION_ARG_NONE, use b

- for G_OPTION_ARG_STRING, use &s

- for G_OPTION_ARG_INT, use i

- for G_OPTION_ARG_INT64, use x

- for G_OPTION_ARG_DOUBLE, use d

- for G_OPTION_ARG_FILENAME, use ^&ay

- for G_OPTION_ARG_STRING_ARRAY, use ^a&s

- for G_OPTION_ARG_FILENAME_ARRAY, use ^a&ay.

The function takes the following parameters:

  • entries: the main options for the application.

func (*Application) AddOptionGroup 

func (application *Application) AddOptionGroup(group *glib.OptionGroup)

AddOptionGroup adds a Group to the commandline handling of application.

This function is comparable to g_option_context_add_group().

Unlike g_application_add_main_option_entries(), this function does not deal with NULL arg_data and never transmits options to the primary instance.

The reason for that is because, by the time the options arrive at the primary instance, it is typically too late to do anything with them. Taking the GTK option group as an example: GTK will already have been initialised by the time the #GApplication::command-line handler runs. In the case that this is not the first-running instance of the application, the existing instance may already have been running for a very long time.

This means that the options from Group are only really usable in the case that the instance of the application being run is the first instance. Passing options like --display= or --gdk-debug= on future runs will have no effect on the existing primary instance.

Calling this function will cause the options in the supplied option group to be parsed, but it does not cause you to be "opted in" to the new functionality whereby unrecognised options are rejected even if G_APPLICATION_HANDLES_COMMAND_LINE was given.

The function takes the following parameters:

  • group: Group.

func (*Application) ApplicationID 

func (application *Application) ApplicationID() string

ApplicationID gets the unique identifier for application.

The function returns the following values:

  • utf8 (optional): identifier for application, owned by application.

func (*Application) BindBusyProperty 

func (application *Application) BindBusyProperty(object *coreglib.Object, property string)

BindBusyProperty marks application as busy (see g_application_mark_busy()) while property on object is TRUE.

The binding holds a reference to application while it is active, but not to object. Instead, the binding is destroyed when object is finalized.

The function takes the following parameters:

  • object: #GObject.
  • property: name of a boolean property of object.

func (*Application) ConnectActivate 

func (application *Application) ConnectActivate(f func()) coreglib.SignalHandle

ConnectActivate signal is emitted on the primary instance when an activation occurs. See g_application_activate().

func (*Application) ConnectCommandLine 

func (application *Application) ConnectCommandLine(f func(commandLine *ApplicationCommandLine) (gint int)) coreglib.SignalHandle

ConnectCommandLine signal is emitted on the primary instance when a commandline is not handled locally. See g_application_run() and the CommandLine documentation for more information.

func (*Application) ConnectHandleLocalOptions 

func (application *Application) ConnectHandleLocalOptions(f func(options *glib.VariantDict) (gint int)) coreglib.SignalHandle

ConnectHandleLocalOptions signal is emitted on the local instance after the parsing of the commandline options has occurred.

You can add options to be recognised during commandline option parsing using g_application_add_main_option_entries() and g_application_add_option_group().

Signal handlers can inspect options (along with values pointed to from the arg_data of an installed Entrys) in order to decide to perform certain actions, including direct local handling (which may be useful for options like --version).

In the event that the application is marked G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will send the options dictionary to the primary instance where it can be read with g_application_command_line_get_options_dict(). The signal handler can modify the dictionary before returning, and the modified dictionary will be sent.

In the event that G_APPLICATION_HANDLES_COMMAND_LINE is not set, "normal processing" will treat the remaining uncollected command line arguments as filenames or URIs. If there are no arguments, the application is activated by g_application_activate(). One or more arguments results in a call to g_application_open().

If you want to handle the local commandline arguments for yourself by converting them to calls to g_application_open() or g_action_group_activate_action() then you must be sure to register the application first. You should probably not call g_application_activate() for yourself, however: just return -1 and allow the default handler to do it for you. This will ensure that the --gapplication-service switch works properly (i.e. no activation in that case).

Note that this signal is emitted from the default implementation of local_command_line(). If you override that function and don't chain up then this signal will never be emitted.

You can override local_command_line() if you need more powerful capabilities than what is provided here, but this should not normally be required.

func (*Application) ConnectNameLost 

func (application *Application) ConnectNameLost(f func() (ok bool)) coreglib.SignalHandle

ConnectNameLost signal is emitted only on the registered primary instance when a new instance has taken over. This can only happen if the application is using the G_APPLICATION_ALLOW_REPLACEMENT flag.

The default handler for this signal calls g_application_quit().

func (*Application) ConnectOpen 

func (application *Application) ConnectOpen(f func(files []Filer, hint string)) coreglib.SignalHandle

ConnectOpen signal is emitted on the primary instance when there are files to open. See g_application_open() for more information.

func (*Application) ConnectShutdown 

func (application *Application) ConnectShutdown(f func()) coreglib.SignalHandle

ConnectShutdown signal is emitted only on the registered primary instance immediately after the main loop terminates.

func (*Application) ConnectStartup 

func (application *Application) ConnectStartup(f func()) coreglib.SignalHandle

ConnectStartup signal is emitted on the primary instance immediately after registration. See g_application_register().

func (*Application) DBusConnection 

func (application *Application) DBusConnection() *DBusConnection

DBusConnection gets the BusConnection being used by the application, or NULL.

If #GApplication is using its D-Bus backend then this function will return the BusConnection being used for uniqueness and communication with the desktop environment and other instances of the application.

If #GApplication is not using D-Bus then this function will return NULL. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus.

This function must not be called before the application has been registered. See g_application_get_is_registered().

The function returns the following values:

  • dBusConnection (optional) or NULL.

func (*Application) DBusObjectPath 

func (application *Application) DBusObjectPath() string

DBusObjectPath gets the D-Bus object path being used by the application, or NULL.

If #GApplication is using its D-Bus backend then this function will return the D-Bus object path that #GApplication is using. If the application is the primary instance then there is an object published at this path. If the application is not the primary instance then the result of this function is undefined.

If #GApplication is not using D-Bus then this function will return NULL. This includes the situation where the D-Bus backend would normally be in use but we were unable to connect to the bus.

This function must not be called before the application has been registered. See g_application_get_is_registered().

The function returns the following values:

  • utf8 (optional): object path, or NULL.

func (*Application) Flags 

func (application *Application) Flags() ApplicationFlags

Flags gets the flags for application.

See Flags.

The function returns the following values:

  • applicationFlags flags for application.

func (*Application) Hold 

func (application *Application) Hold()

Hold increases the use count of application.

Use this function to indicate that the application has a reason to continue to run. For example, g_application_hold() is called by GTK when a toplevel window is on the screen.

To cancel the hold, call g_application_release().

func (*Application) InactivityTimeout 

func (application *Application) InactivityTimeout() uint

InactivityTimeout gets the current inactivity timeout for the application.

This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running.

The function returns the following values:

  • guint: timeout, in milliseconds.

func (*Application) IsBusy 

func (application *Application) IsBusy() bool

IsBusy gets the application's current busy state, as set through g_application_mark_busy() or g_application_bind_busy_property().

The function returns the following values:

  • ok: TRUE if application is currently marked as busy.

func (*Application) IsRegistered 

func (application *Application) IsRegistered() bool

IsRegistered checks if application is registered.

An application is registered if g_application_register() has been successfully called.

The function returns the following values:

  • ok: TRUE if application is registered.

func (*Application) IsRemote 

func (application *Application) IsRemote() bool

IsRemote checks if application is remote.

If application is remote then it means that another instance of application already exists (the 'primary' instance). Calls to perform actions on application will result in the actions being performed by the primary instance.

The value of this property cannot be accessed before g_application_register() has been called. See g_application_get_is_registered().

The function returns the following values:

  • ok: TRUE if application is remote.

func (*Application) MarkBusy 

func (application *Application) MarkBusy()

MarkBusy increases the busy count of application.

Use this function to indicate that the application is busy, for instance while a long running operation is pending.

The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner).

To cancel the busy indication, use g_application_unmark_busy().

The application must be registered before calling this function.

func (*Application) Open 

func (application *Application) Open(files []Filer, hint string)

Open opens the given files.

In essence, this results in the #GApplication::open signal being emitted in the primary instance.

n_files must be greater than zero.

hint is simply passed through to the ::open signal. It is intended to be used by applications that have multiple modes for opening files (eg: "view" vs "edit", etc). Unless you have a need for this functionality, you should use "".

The application must be registered before calling this function and it must have the G_APPLICATION_HANDLES_OPEN flag set.

The function takes the following parameters:

  • files: array of #GFiles to open.
  • hint (or ""), but never NULL.

func (*Application) Quit 

func (application *Application) Quit()

Quit: immediately quits the application.

Upon return to the mainloop, g_application_run() will return, calling only the 'shutdown' function before doing so.

The hold count is ignored. Take care if your code has called g_application_hold() on the application and is therefore still expecting it to exist. (Note that you may have called g_application_hold() indirectly, for example through gtk_application_add_window().)

The result of calling g_application_run() again after it returns is unspecified.

func (*Application) Register 

func (application *Application) Register(ctx context.Context) error

Register attempts registration of the application.

This is the point at which the application discovers if it is the primary instance or merely acting as a remote for an already-existing primary instance. This is implemented by attempting to acquire the application identifier as a unique bus name on the session bus using GDBus.

If there is no application ID or if G_APPLICATION_NON_UNIQUE was given, then this process will always become the primary instance.

Due to the internal architecture of GDBus, method calls can be dispatched at any time (even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before calling this function.

If the application has already been registered then TRUE is returned with no work performed.

The #GApplication::startup signal is emitted if registration succeeds and application is the primary instance (including the non-unique case).

In the event of an error (such as cancellable being cancelled, or a failure to connect to the session bus), FALSE is returned and error is set appropriately.

Note: the return value of this function is not an indicator that this instance is or is not the primary instance of the application. See g_application_get_is_remote() for that.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*Application) Release 

func (application *Application) Release()

Release: decrease the use count of application.

When the use count reaches zero, the application will stop running.

Never call this function except to cancel the effect of a previous call to g_application_hold().

func (*Application) ResourceBasePath 

func (application *Application) ResourceBasePath() string

ResourceBasePath gets the resource base path of application.

See g_application_set_resource_base_path() for more information.

The function returns the following values:

  • utf8 (optional): base resource path, if one is set.

func (*Application) Run 

func (application *Application) Run(argv []string) int

Run runs the application.

This function is intended to be run from main() and its return value is intended to be returned by main(). Although you are expected to pass the argc, argv parameters from main() to this function, it is possible to pass NULL if argv is not available or commandline handling is not required. Note that on Windows, argc and argv are ignored, and g_win32_get_command_line() is called internally (for proper support of Unicode commandline arguments).

#GApplication will attempt to parse the commandline arguments. You can add commandline flags to the list of recognised options by way of g_application_add_main_option_entries(). After this, the #GApplication::handle-local-options signal is emitted, from which the application can inspect the values of its Entrys.

#GApplication::handle-local-options is a good place to handle options such as --version, where an immediate reply from the local process is desired (instead of communicating with an already-running instance). A #GApplication::handle-local-options handler can stop further processing by returning a non-negative value, which then becomes the exit status of the process.

What happens next depends on the flags: if G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining commandline arguments are sent to the primary instance, where a #GApplication::command-line signal is emitted. Otherwise, the remaining commandline arguments are assumed to be a list of files. If there are no files listed, the application is activated via the #GApplication::activate signal. If there are one or more files, and G_APPLICATION_HANDLES_OPEN was specified then the files are opened via the #GApplication::open signal.

If you are interested in doing more complicated local handling of the commandline then you should implement your own #GApplication subclass and override local_command_line(). In this case, you most likely want to return TRUE from your local_command_line() implementation to suppress the default handling. See [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] for an example.

If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the default main context is iterated until the use count falls to zero, at which point 0 is returned.

If the G_APPLICATION_IS_SERVICE flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that g_application_set_inactivity_timeout() is in use.

This function sets the prgname (g_set_prgname()), if not already set, to the basename of argv[0].

Much like g_main_loop_run(), this function will acquire the main context for the duration that the application is running.

Since 2.40, applications that are not explicitly flagged as services or launchers (ie: neither G_APPLICATION_IS_SERVICE or G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the default handler for local_command_line) if "--gapplication-service" was given in the command line. If this flag is present then normal commandline processing is interrupted and the G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" solution whereby running an application directly from the commandline will invoke it in the normal way (which can be useful for debugging) while still allowing applications to be D-Bus activated in service mode. The D-Bus service file should invoke the executable with "--gapplication-service" as the sole commandline argument. This approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the commandline will exit and what their exit status will be.

The function takes the following parameters:

  • argv (optional): the argv from main(), or NULL.

The function returns the following values:

  • gint: exit status.

func (*Application) SendNotification 

func (application *Application) SendNotification(id string, notification *Notification)

SendNotification sends a notification on behalf of application to the desktop shell. There is no guarantee that the notification is displayed immediately, or even at all.

Notifications may persist after the application exits. It will be D-Bus-activated when the notification or one of its actions is activated.

Modifying notification after this call has no effect. However, the object can be reused for a later call to this function.

id may be any string that uniquely identifies the event for the application. It does not need to be in any special format. For example, "new-message" might be appropriate for a notification about new messages.

If a previous notification was sent with the same id, it will be replaced with notification and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as id is the same string.

id may be NULL, but it is impossible to replace or withdraw notifications without an id.

If notification is no longer relevant, it can be withdrawn with g_application_withdraw_notification().

It is an error to call this function if application has no application ID.

The function takes the following parameters:

  • id (optional) of the notification, or NULL.
  • notification to send.

func (*Application) SetActionGroup deprecated 

func (application *Application) SetActionGroup(actionGroup ActionGrouper)

SetActionGroup: this used to be how actions were associated with a #GApplication. Now there is Map for that.

Deprecated: Use the Map interface instead. Never ever mix use of this API with use of Map on the same application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use Map instead.

The function takes the following parameters:

  • actionGroup (optional) or NULL.

func (*Application) SetApplicationID 

func (application *Application) SetApplicationID(applicationId string)

SetApplicationID sets the unique identifier for application.

The application id can only be modified if application has not yet been registered.

If non-NULL, the application id must be valid. See g_application_id_is_valid().

The function takes the following parameters:

  • applicationId (optional): identifier for application.

func (*Application) SetDefault 

func (application *Application) SetDefault()

SetDefault sets or unsets the default application for the process, as returned by g_application_get_default().

This function does not take its own reference on application. If application is destroyed then the default application will revert back to NULL.

func (*Application) SetFlags 

func (application *Application) SetFlags(flags ApplicationFlags)

SetFlags sets the flags for application.

The flags can only be modified if application has not yet been registered.

See Flags.

The function takes the following parameters:

  • flags for application.

func (*Application) SetInactivityTimeout 

func (application *Application) SetInactivityTimeout(inactivityTimeout uint)

SetInactivityTimeout sets the current inactivity timeout for the application.

This is the amount of time (in milliseconds) after the last call to g_application_release() before the application stops running.

This call has no side effects of its own. The value set here is only used for next time g_application_release() drops the use count to zero. Any timeouts currently in progress are not impacted.

The function takes the following parameters:

  • inactivityTimeout: timeout, in milliseconds.

func (*Application) SetOptionContextDescription 

func (application *Application) SetOptionContextDescription(description string)

SetOptionContextDescription adds a description to the application option context.

See g_option_context_set_description() for more information.

The function takes the following parameters:

  • description (optional): string to be shown in --help output after the list of options, or NULL.

func (*Application) SetOptionContextParameterString 

func (application *Application) SetOptionContextParameterString(parameterString string)

SetOptionContextParameterString sets the parameter string to be used by the commandline handling of application.

This function registers the argument to be passed to g_option_context_new() when the internal Context of application is created.

See g_option_context_new() for more information about parameter_string.

The function takes the following parameters:

  • parameterString (optional): string which is displayed in the first line of --help output, after the usage summary programname [OPTION...].

func (*Application) SetOptionContextSummary 

func (application *Application) SetOptionContextSummary(summary string)

SetOptionContextSummary adds a summary to the application option context.

See g_option_context_set_summary() for more information.

The function takes the following parameters:

  • summary (optional): string to be shown in --help output before the list of options, or NULL.

func (*Application) SetResourceBasePath 

func (application *Application) SetResourceBasePath(resourcePath string)

SetResourceBasePath sets (or unsets) the base resource path of application.

The path is used to automatically load various [application resources][gresource] such as menu layouts and action descriptions. The various types of resources will be found at fixed names relative to the given base path.

By default, the resource base path is determined from the application ID by prefixing '/' and replacing each '.' with '/'. This is done at the time that the #GApplication object is constructed. Changes to the application ID after that point will not have an impact on the resource base path.

As an example, if the application has an ID of "org.example.app" then the default resource base path will be "/org/example/app". If this is a Application (and you have not manually changed the path) then Gtk will then search for the menus of the application at "/org/example/app/gtk/menus.ui".

See #GResource for more information about adding resources to your application.

You can disable automatic resource loading functionality by setting the path to NULL.

Changing the resource base path once the application is running is not recommended. The point at which the resource path is consulted for forming paths for various purposes is unspecified. When writing a sub-class of #GApplication you should either set the #GApplication:resource-base-path property at construction time, or call this function during the instance initialization. Alternatively, you can call this function in the Class.startup virtual function, before chaining up to the parent implementation.

The function takes the following parameters:

  • resourcePath (optional): resource path to use.

func (*Application) SetVersion added in v0.3.0 

func (application *Application) SetVersion(version string)

SetVersion sets the version number of application. This will be used to implement a --version command line argument

The application version can only be modified if application has not yet been registered.

The function takes the following parameters:

  • version of application.

func (*Application) UnbindBusyProperty 

func (application *Application) UnbindBusyProperty(object *coreglib.Object, property string)

UnbindBusyProperty destroys a binding between property and the busy state of application that was previously created with g_application_bind_busy_property().

The function takes the following parameters:

  • object: #GObject.
  • property: name of a boolean property of object.

func (*Application) UnmarkBusy 

func (application *Application) UnmarkBusy()

UnmarkBusy decreases the busy count of application.

When the busy count reaches zero, the new state will be propagated to other processes.

This function must only be called to cancel the effect of a previous call to g_application_mark_busy().

func (*Application) Version added in v0.3.0 

func (application *Application) Version() string

Version gets the version of application.

The function returns the following values:

  • utf8 (optional): version of application.

func (*Application) WithdrawNotification 

func (application *Application) WithdrawNotification(id string)

WithdrawNotification withdraws a notification that was sent with g_application_send_notification().

This call does nothing if a notification with id doesn't exist or the notification was never sent.

This function works even for notifications sent in previous executions of this application, as long id is the same as it was for the sent notification.

Note that notifications are dismissed when the user clicks on one of the buttons in a notification or triggers its default action, so there is no need to explicitly withdraw the notification in that case.

The function takes the following parameters:

  • id of a previously sent notification.

type ApplicationClass added in v0.0.5 

type ApplicationClass struct {
	// contains filtered or unexported fields
}

ApplicationClass: virtual function table for #GApplication.

An instance of this type is always passed by reference.

type ApplicationCommandLine 

type ApplicationCommandLine struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

ApplicationCommandLine: GApplicationCommandLine represents a command-line invocation of an application.

It is created by gio.Application and emitted in the gio.Application::command-line signal and virtual function.

The class contains the list of arguments that the program was invoked with. It is also possible to query if the commandline invocation was local (ie: the current process is running in direct response to the invocation) or remote (ie: some other process forwarded the commandline to this process).

The GApplicationCommandLine object can provide the argc and argv parameters for use with the glib.OptionContext command-line parsing API, with the gio.ApplicationCommandLine.GetArguments() function. See [gapplication-example-cmdline3.c][gapplication-example-cmdline3] for an example.

The exit status of the originally-invoked process may be set and messages can be printed to stdout or stderr of that process.

For remote invocation, the originally-invoked process exits when gio.ApplicationCommandLine.Done() method is called. This method is also automatically called when the object is disposed.

The main use for GApplicationCommandLine (and the gio.Application::command-line signal) is 'Emacs server' like use cases: You can set the EDITOR environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen in the running instance, instead of opening a new one. An important aspect of this use case is that the process that gets started by git does not return until the editing is done.

Normally, the commandline is completely handled in the gio.Application::command-line handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. 

static int
command_line (GApplication            *application,
              GApplicationCommandLine *cmdline)
{
  gchar **argv;
  gint argc;
  gint i;

  argv = g_application_command_line_get_arguments (cmdline, &argc);

  g_application_command_line_print (cmdline,
                                    "This text is written back\n"
                                    "to stdout of the caller\n");

  for (i = 0; i < argc; i++)
    g_print ("argument d: s\n", i, argv[i]);

  g_strfreev (argv);

  return 0;
}

The complete example can be found here: gapplication-example-cmdline.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)

In more complicated cases, the handling of the commandline can be split between the launcher and the primary instance. 

static gboolean
 test_local_cmdline (GApplication   *application,
                     gchar        ***arguments,
                     gint           *exit_status)
{
  gint i, j;
  gchar **argv;

  argv = *arguments;

  if (argv[0] == NULL)
    {
      *exit_status = 0;
      return FALSE;
    }

  i = 1;
  while (argv[i])
    {
      if (g_str_has_prefix (argv[i], "--local-"))
        {
          g_print ("handling argument s locally\n", argv[i]);
          g_free (argv[i]);
          for (j = i; argv[j]; j++)
            argv[j] = argv[j + 1];
        }
      else
        {
          g_print ("not handling argument s locally\n", argv[i]);
          i++;
        }
    }

  *exit_status = 0;

  return FALSE;
}

static void
test_application_class_init (TestApplicationClass *class)
{
  G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;

  ...
}

In this example of split commandline handling, options that start with --local- are handled locally, all other options are passed to the gio.Application::command-line handler which runs in the primary instance.

The complete example can be found here: gapplication-example-cmdline2.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)

If handling the commandline requires a lot of work, it may be better to defer it. 

static gboolean
my_cmdline_handler (gpointer data)
{
  GApplicationCommandLine *cmdline = data;

  // do the heavy lifting in an idle

  g_application_command_line_set_exit_status (cmdline, 0);
  g_object_unref (cmdline); // this releases the application

  return G_SOURCE_REMOVE;
}

static int
command_line (GApplication            *application,
              GApplicationCommandLine *cmdline)
{
  // keep the application running until we are done with this commandline
  g_application_hold (application);

  g_object_set_data_full (G_OBJECT (cmdline),
                          "application", application,
                          (GDestroyNotify)g_application_release);

  g_object_ref (cmdline);
  g_idle_add (my_cmdline_handler, cmdline);

  return 0;
}

In this example the commandline is not completely handled before the gio.Application::command-line handler returns. Instead, we keep a reference to the GApplicationCommandLine object and handle it later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline.

The complete example can be found here: gapplication-example-cmdline3.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c).

func (*ApplicationCommandLine) Arguments 

func (cmdline *ApplicationCommandLine) Arguments() []string

Arguments gets the list of arguments that was passed on the command line.

The strings in the array may contain non-UTF-8 data on UNIX (such as filenames or arguments given in the system locale) but are always in UTF-8 on Windows.

If you wish to use the return value with Context, you must use g_option_context_parse_strv().

The return value is NULL-terminated and should be freed using g_strfreev().

The function returns the following values:

  • filenames: the string array containing the arguments (the argv).

func (*ApplicationCommandLine) CreateFileForArg 

func (cmdline *ApplicationCommandLine) CreateFileForArg(arg string) *File

CreateFileForArg creates a #GFile corresponding to a filename that was given as part of the invocation of cmdline.

This differs from g_file_new_for_commandline_arg() in that it resolves relative pathnames using the current working directory of the invoking process rather than the local process.

The function takes the following parameters:

  • arg: argument from cmdline.

The function returns the following values:

  • file: new #GFile.

func (*ApplicationCommandLine) Cwd 

func (cmdline *ApplicationCommandLine) Cwd() string

Cwd gets the working directory of the command line invocation. The string may contain non-utf8 data.

It is possible that the remote application did not send a working directory, so this may be NULL.

The return value should not be modified or freed and is valid for as long as cmdline exists.

The function returns the following values:

  • filename (optional): current directory, or NULL.

func (*ApplicationCommandLine) Done added in v0.3.0 

func (cmdline *ApplicationCommandLine) Done()

Done signals that command line processing is completed.

For remote invocation, it causes the invoking process to terminate.

For local invocation, it does nothing.

This method should be called in the gio.Application::command-line handler, after the exit status is set and all messages are printed.

After this call, g_application_command_line_set_exit_status() has no effect. Subsequent calls to this method are no-ops.

This method is automatically called when the CommandLine object is disposed — so you can omit the call in non-garbage collected languages.

func (*ApplicationCommandLine) Environ 

func (cmdline *ApplicationCommandLine) Environ() []string

Environ gets the contents of the 'environ' variable of the command line invocation, as would be returned by g_get_environ(), ie as a NULL-terminated list of strings in the form 'NAME=VALUE'. The strings may contain non-utf8 data.

The remote application usually does not send an environment. Use G_APPLICATION_SEND_ENVIRONMENT to affect that. Even with this flag set it is possible that the environment is still not available (due to invocation messages from other applications).

The return value should not be modified or freed and is valid for as long as cmdline exists.

See g_application_command_line_getenv() if you are only interested in the value of a single environment variable.

The function returns the following values:

  • filenames: the environment strings, or NULL if they were not sent.

func (*ApplicationCommandLine) ExitStatus 

func (cmdline *ApplicationCommandLine) ExitStatus() int

ExitStatus gets the exit status of cmdline. See g_application_command_line_set_exit_status() for more information.

The function returns the following values:

  • gint: exit status.

func (*ApplicationCommandLine) IsRemote 

func (cmdline *ApplicationCommandLine) IsRemote() bool

IsRemote determines if cmdline represents a remote invocation.

The function returns the following values:

  • ok: TRUE if the invocation was remote.

func (*ApplicationCommandLine) OptionsDict 

func (cmdline *ApplicationCommandLine) OptionsDict() *glib.VariantDict

OptionsDict gets the options that were passed to g_application_command_line().

If you did not override local_command_line() then these are the same options that were parsed according to the Entrys added to the application with g_application_add_main_option_entries() and possibly modified from your GApplication::handle-local-options handler.

If no options were sent then an empty dictionary is returned so that you don't need to check for NULL.

The data has been passed via an untrusted external process, so the types of all values must be checked before being used.

The function returns the following values:

  • variantDict with the options.

func (*ApplicationCommandLine) PlatformData 

func (cmdline *ApplicationCommandLine) PlatformData() *glib.Variant

PlatformData gets the platform data associated with the invocation of cmdline.

This is a #GVariant dictionary containing information about the context in which the invocation occurred. It typically contains information like the current working directory and the startup notification ID.

It comes from an untrusted external process and hence the types of all values must be validated before being used.

For local invocation, it will be NULL.

The function returns the following values:

  • variant (optional): platform data, or NULL.

func (*ApplicationCommandLine) PrintLiteral added in v0.3.0 

func (cmdline *ApplicationCommandLine) PrintLiteral(message string)

PrintLiteral prints a message using the stdout print handler in the invoking process.

Unlike g_application_command_line_print(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

The function takes the following parameters:

  • message: message.

func (*ApplicationCommandLine) PrinterrLiteral added in v0.3.0 

func (cmdline *ApplicationCommandLine) PrinterrLiteral(message string)

PrinterrLiteral prints a message using the stderr print handler in the invoking process.

Unlike g_application_command_line_printerr(), message is not a printf()-style format string. Use this function if message contains text you don't have control over, that could include printf() escape sequences.

The function takes the following parameters:

  • message: message.

func (*ApplicationCommandLine) SetExitStatus 

func (cmdline *ApplicationCommandLine) SetExitStatus(exitStatus int)

SetExitStatus sets the exit status that will be used when the invoking process exits.

The return value of the #GApplication::command-line signal is passed to this function when the handler returns. This is the usual way of setting the exit status.

In the event that you want the remote invocation to continue running and want to decide on the exit status in the future, you can use this call. For the case of a remote invocation, the remote process will typically exit when the last reference is dropped on cmdline. The exit status of the remote process will be equal to the last value that was set with this function.

In the case that the commandline invocation is local, the situation is slightly more complicated. If the commandline invocation results in the mainloop running (ie: because the use-count of the application increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit status of the local CommandLine is used.

This method is a no-op if g_application_command_line_done() has been called.

The function takes the following parameters:

  • exitStatus: exit status.

func (*ApplicationCommandLine) Stdin 

func (cmdline *ApplicationCommandLine) Stdin() InputStreamer

Stdin gets the stdin of the invoking process.

The Stream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available on UNIX when using a D-Bus daemon capable of passing file descriptors. If stdin is not available then NULL will be returned. In the future, support may be expanded to other platforms.

You must only call this function once per commandline invocation.

The function returns the following values:

  • inputStream (optional) for stdin.

type ApplicationCommandLineClass added in v0.0.5 

type ApplicationCommandLineClass struct {
	// contains filtered or unexported fields
}

ApplicationCommandLineClass private data only.

An instance of this type is always passed by reference.

type ApplicationCommandLineOverrides added in v0.0.5 

type ApplicationCommandLineOverrides struct {
	// Done signals that command line processing is completed.
	//
	// For remote invocation, it causes the invoking process to terminate.
	//
	// For local invocation, it does nothing.
	//
	// This method should be called in the gio.Application::command-line
	// handler, after the exit status is set and all messages are printed.
	//
	// After this call, g_application_command_line_set_exit_status() has no
	// effect. Subsequent calls to this method are no-ops.
	//
	// This method is automatically called when the CommandLine object is
	// disposed — so you can omit the call in non-garbage collected languages.
	Done func()
	// Stdin gets the stdin of the invoking process.
	//
	// The Stream can be used to read data passed to the standard input of
	// the invoking process. This doesn't work on all platforms. Presently,
	// it is only available on UNIX when using a D-Bus daemon capable of passing
	// file descriptors. If stdin is not available then NULL will be returned.
	// In the future, support may be expanded to other platforms.
	//
	// You must only call this function once per commandline invocation.
	//
	// The function returns the following values:
	//
	//   - inputStream (optional) for stdin.
	Stdin func() InputStreamer
	// PrintLiteral prints a message using the stdout print handler in the
	// invoking process.
	//
	// Unlike g_application_command_line_print(), message is not a
	// printf()-style format string. Use this function if message contains
	// text you don't have control over, that could include printf() escape
	// sequences.
	//
	// The function takes the following parameters:
	//
	//   - message: message.
	PrintLiteral func(message string)
	// PrinterrLiteral prints a message using the stderr print handler in the
	// invoking process.
	//
	// Unlike g_application_command_line_printerr(), message is not a
	// printf()-style format string. Use this function if message contains
	// text you don't have control over, that could include printf() escape
	// sequences.
	//
	// The function takes the following parameters:
	//
	//   - message: message.
	PrinterrLiteral func(message string)
}

ApplicationCommandLineOverrides contains methods that are overridable.

type ApplicationFlags 

type ApplicationFlags C.guint

ApplicationFlags flags used to define the behaviour of a #GApplication. 

const (
	// ApplicationFlagsNone: default. Deprecated in 2.74, use
	// G_APPLICATION_DEFAULT_FLAGS instead.
	ApplicationFlagsNone ApplicationFlags = 0b0
	// ApplicationDefaultFlags: default flags. Since: 2.74.
	ApplicationDefaultFlags ApplicationFlags = 0b0
	// ApplicationIsService: run as a service. In this mode, registration fails
	// if the service is already running, and the application will initially
	// wait up to 10 seconds for an initial activation message to arrive.
	ApplicationIsService ApplicationFlags = 0b1
	// ApplicationIsLauncher: don't try to become the primary instance.
	ApplicationIsLauncher ApplicationFlags = 0b10
	// ApplicationHandlesOpen: this application handles opening files
	// (in the primary instance). Note that this flag only affects the
	// default implementation of local_command_line(), and has no effect if
	// G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for
	// details.
	ApplicationHandlesOpen ApplicationFlags = 0b100
	// ApplicationHandlesCommandLine: this application handles command line
	// arguments (in the primary instance). Note that this flag only affect the
	// default implementation of local_command_line(). See g_application_run()
	// for details.
	ApplicationHandlesCommandLine ApplicationFlags = 0b1000
	// ApplicationSendEnvironment: send the environment of the launching process
	// to the primary instance. Set this flag if your application is expected
	// to behave differently depending on certain environment variables.
	// For instance, an editor might be expected to use the GIT_COMMITTER_NAME
	// environment variable when editing a git commit message. The environment
	// is available to the #GApplication::command-line signal handler,
	// via g_application_command_line_getenv().
	ApplicationSendEnvironment ApplicationFlags = 0b10000
	// ApplicationNonUnique: make no attempts to do any of the typical
	// single-instance application negotiation, even if the application ID
	// is given. The application neither attempts to become the owner of the
	// application ID nor does it check if an existing owner already exists.
	// Everything occurs in the local process. Since: 2.30.
	ApplicationNonUnique ApplicationFlags = 0b100000
	// ApplicationCanOverrideAppID: allow users to override the application ID
	// from the command line with --gapplication-app-id. Since: 2.48.
	ApplicationCanOverrideAppID ApplicationFlags = 0b1000000
	// ApplicationAllowReplacement: allow another instance to take over the bus
	// name. Since: 2.60.
	ApplicationAllowReplacement ApplicationFlags = 0b10000000
	// ApplicationReplace: take over from another instance. This flag is usually
	// set by passing --gapplication-replace on the commandline. Since: 2.60.
	ApplicationReplace ApplicationFlags = 0b100000000
)

func (ApplicationFlags) Has 

func (a ApplicationFlags) Has(other ApplicationFlags) bool

Has returns true if a contains other.

func (ApplicationFlags) String 

func (a ApplicationFlags) String() string

String returns the names in string for ApplicationFlags.

type ApplicationOverrides added in v0.0.5 

type ApplicationOverrides struct {
	// Activate activates the application.
	//
	// In essence, this results in the #GApplication::activate signal being
	// emitted in the primary instance.
	//
	// The application must be registered before calling this function.
	Activate func()
	// AddPlatformData: invoked (locally) to add 'platform data' to be sent to
	// the primary instance when activating, opening or invoking actions.
	AddPlatformData func(builder *glib.VariantBuilder)
	// AfterEmit: invoked on the primary instance after 'activate', 'open',
	// 'command-line' or any action invocation, gets the 'platform data' from
	// the calling instance.
	AfterEmit func(platformData *glib.Variant)
	// BeforeEmit: invoked on the primary instance before 'activate', 'open',
	// 'command-line' or any action invocation, gets the 'platform data' from
	// the calling instance.
	BeforeEmit func(platformData *glib.Variant)
	// CommandLine: invoked on the primary instance when a command-line is not
	// handled locally.
	CommandLine func(commandLine *ApplicationCommandLine) int
	// DBusRegister: invoked locally during registration, if the application
	// is using its D-Bus backend. You can use this to export extra objects
	// on the bus, that need to exist before the application tries to own the
	// bus name. The function is passed the BusConnection to to session bus,
	// and the object path that #GApplication will use to export its D-Bus API.
	// If this function returns TRUE, registration will proceed; otherwise
	// registration will abort. Since: 2.34.
	//
	// The function takes the following parameters:
	//
	//   - connection
	//   - objectPath
	DBusRegister func(connection *DBusConnection, objectPath string) error
	// DBusUnregister: invoked locally during unregistration, if the application
	// is using its D-Bus backend. Use this to undo anything done by the
	// dbus_register vfunc. Since: 2.34.
	//
	// The function takes the following parameters:
	//
	//   - connection
	//   - objectPath
	DBusUnregister func(connection *DBusConnection, objectPath string)
	// HandleLocalOptions: invoked locally after the parsing of the commandline
	// options has occurred. Since: 2.40.
	HandleLocalOptions func(options *glib.VariantDict) int
	// NameLost: invoked when another instance is taking over the name. Since:
	// 2.60.
	NameLost func() bool
	// Open opens the given files.
	//
	// In essence, this results in the #GApplication::open signal being emitted
	// in the primary instance.
	//
	// n_files must be greater than zero.
	//
	// hint is simply passed through to the ::open signal. It is intended to
	// be used by applications that have multiple modes for opening files (eg:
	// "view" vs "edit", etc). Unless you have a need for this functionality,
	// you should use "".
	//
	// The application must be registered before calling this function and it
	// must have the G_APPLICATION_HANDLES_OPEN flag set.
	//
	// The function takes the following parameters:
	//
	//   - files: array of #GFiles to open.
	//   - hint (or ""), but never NULL.
	Open func(files []Filer, hint string)
	// QuitMainloop: used to be invoked on the primary instance when the use
	// count of the application drops to zero (and after any inactivity timeout,
	// if requested). Not used anymore since 2.32.
	QuitMainloop func()
	// RunMainloop: used to be invoked on the primary instance from
	// g_application_run() if the use-count is non-zero. Since 2.32,
	// GApplication is iterating the main context directly and is not using
	// run_mainloop anymore.
	RunMainloop func()
	// Shutdown: invoked only on the registered primary instance immediately
	// after the main loop terminates.
	Shutdown func()
	// Startup: invoked on the primary instance immediately after registration.
	Startup func()
}

ApplicationOverrides contains methods that are overridable.

type AskPasswordFlags 

type AskPasswordFlags C.guint

AskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. 

const (
	// AskPasswordNeedPassword: operation requires a password.
	AskPasswordNeedPassword AskPasswordFlags = 0b1
	// AskPasswordNeedUsername: operation requires a username.
	AskPasswordNeedUsername AskPasswordFlags = 0b10
	// AskPasswordNeedDomain: operation requires a domain.
	AskPasswordNeedDomain AskPasswordFlags = 0b100
	// AskPasswordSavingSupported: operation supports saving settings.
	AskPasswordSavingSupported AskPasswordFlags = 0b1000
	// AskPasswordAnonymousSupported: operation supports anonymous users.
	AskPasswordAnonymousSupported AskPasswordFlags = 0b10000
	// AskPasswordTcrypt: operation takes TCRYPT parameters (Since: 2.58).
	AskPasswordTcrypt AskPasswordFlags = 0b100000
)

func (AskPasswordFlags) Has 

func (a AskPasswordFlags) Has(other AskPasswordFlags) bool

Has returns true if a contains other.

func (AskPasswordFlags) String 

func (a AskPasswordFlags) String() string

String returns the names in string for AskPasswordFlags.

type AsyncInitable 

type AsyncInitable struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

AsyncInitable: GAsyncInitable is an interface for asynchronously initializable objects.

This is the asynchronous version of gio.Initable; it behaves the same in all ways except that initialization is asynchronous. For more details see the descriptions on GInitable.

A class may implement both the GInitable and GAsyncInitable interfaces.

Users of objects implementing this are not intended to use the interface method directly; instead it will be used automatically in various ways. For C applications you generally just call gio.AsyncInitable().NewAsync directly, or indirectly via a foo_thing_new_async() wrapper. This will call gio.AsyncInitable.InitAsync() under the covers, calling back with NULL and a set GError on failure.

A typical implementation might look something like this: 

enum {
   NOT_INITIALIZED,
   INITIALIZING,
   INITIALIZED
};

static void
_foo_ready_cb (Foo *self)
{
  GList *l;

  self->priv->state = INITIALIZED;

  for (l = self->priv->init_results; l != NULL; l = l->next)
    {
      GTask *task = l->data;

      if (self->priv->success)
        g_task_return_boolean (task, TRUE);
      else
        g_task_return_new_error (task, ...);
      g_object_unref (task);
    }

  g_list_free (self->priv->init_results);
  self->priv->init_results = NULL;
}

static void
foo_init_async (GAsyncInitable       *initable,
                int                   io_priority,
                GCancellable         *cancellable,
                GAsyncReadyCallback   callback,
                gpointer              user_data)
{
  Foo *self = FOO (initable);
  GTask *task;

  task = g_task_new (initable, cancellable, callback, user_data);
  g_task_set_name (task, G_STRFUNC);

  switch (self->priv->state)
    {
      case NOT_INITIALIZED:
        _foo_get_ready (self);
        self->priv->init_results = g_list_append (self->priv->init_results,
                                                  task);
        self->priv->state = INITIALIZING;
        break;
      case INITIALIZING:
        self->priv->init_results = g_list_append (self->priv->init_results,
                                                  task);
        break;
      case INITIALIZED:
        if (!self->priv->success)
          g_task_return_new_error (task, ...);
        else
          g_task_return_boolean (task, TRUE);
        g_object_unref (task);
        break;
    }
}

static gboolean
foo_init_finish (GAsyncInitable       *initable,
                 GAsyncResult         *result,
                 GError              **error)
{
  g_return_val_if_fail (g_task_is_valid (result, initable), FALSE);

  return g_task_propagate_boolean (G_TASK (result), error);
}

static void
foo_async_initable_iface_init (gpointer g_iface,
                               gpointer data)
{
  GAsyncInitableIface *iface = g_iface;

  iface->init_async = foo_init_async;
  iface->init_finish = foo_init_finish;
}.

AsyncInitable wraps an interface. This means the user can get the underlying type by calling Cast().

func (*AsyncInitable) InitAsync 

func (initable *AsyncInitable) InitAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

InitAsync starts asynchronous initialization of the object implementing the interface. This must be done before any real use of the object after initial construction. If the object also implements #GInitable you can optionally call g_initable_init() instead.

This method is intended for language bindings. If writing in C, g_async_initable_new_async() should typically be used instead.

When the initialization is finished, callback will be called. You can then call g_async_initable_init_finish() to get the result of the initialization.

Implementations may also support cancellation. If cancellable is not NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If cancellable is not NULL, and the object doesn't support cancellable initialization, the error G_IO_ERROR_NOT_SUPPORTED will be returned.

As with #GInitable, if the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. They will often fail with g_critical() or g_warning(), but this must not be relied on.

Callers should not assume that a class which implements Initable can be initialized multiple times; for more information, see g_initable_init(). If a class explicitly supports being initialized multiple times, implementation requires yielding all subsequent calls to init_async() on the results of the first call.

For classes that also support the #GInitable interface, the default implementation of this method will run the g_initable_init() function in a thread, so if you want to support asynchronous initialization via threads, just implement the Initable interface without overriding any interface methods.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the operation.
  • callback (optional) to call when the request is satisfied.

func (*AsyncInitable) InitFinish 

func (initable *AsyncInitable) InitFinish(res AsyncResulter) error

InitFinish finishes asynchronous initialization and returns the result. See g_async_initable_init_async().

The function takes the following parameters:

  • res: Result.

func (*AsyncInitable) NewFinish 

func (initable *AsyncInitable) NewFinish(res AsyncResulter) (*coreglib.Object, error)

NewFinish finishes the async construction for the various g_async_initable_new calls, returning the created object or NULL on error.

The function takes the following parameters:

  • res from the callback.

The function returns the following values:

  • object: newly created #GObject, or NULL on error. Free with g_object_unref().

type AsyncInitableIface added in v0.0.5 

type AsyncInitableIface struct {
	// contains filtered or unexported fields
}

AsyncInitableIface provides an interface for asynchronous initializing object such that initialization may fail.

An instance of this type is always passed by reference.

type AsyncInitabler 

type AsyncInitabler interface {
	coreglib.Objector

	// InitAsync starts asynchronous initialization of the object implementing
	// the interface.
	InitAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// InitFinish finishes asynchronous initialization and returns the result.
	InitFinish(res AsyncResulter) error
	// NewFinish finishes the async construction for the various
	// g_async_initable_new calls, returning the created object or NULL on
	// error.
	NewFinish(res AsyncResulter) (*coreglib.Object, error)
}

AsyncInitabler describes AsyncInitable's interface methods.

type AsyncReadyCallback 

type AsyncReadyCallback func(res AsyncResulter)

AsyncReadyCallback: type definition for a function that will be called back when an asynchronous operation within GIO has been completed. ReadyCallback callbacks from #GTask are guaranteed to be invoked in a later iteration of the [thread-default main context][g-main-context-push-thread-default] where the #GTask was created. All other users of ReadyCallback must likewise call it asynchronously in a later iteration of the main context.

The asynchronous operation is guaranteed to have held a reference to source_object from the time when the *_async() function was called, until after this callback returns.

type AsyncResult 

type AsyncResult struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

AsyncResult: GAsyncResult provides a base class for implementing asynchronous function results.

Asynchronous operations are broken up into two separate operations which are chained together by a GAsyncReadyCallback. To begin an asynchronous operation, provide a GAsyncReadyCallback to the asynchronous function. This callback will be triggered when the operation has completed, and must be run in a later iteration of the thread-default main context (see glib.MainContext.PushThreadDefault()) from where the operation was initiated. It will be passed a GAsyncResult instance filled with the details of the operation's success or failure, the object the asynchronous function was started for and any error codes returned. The asynchronous callback function is then expected to call the corresponding _finish() function, passing the object the function was called for, the GAsyncResult instance, and (optionally) an error to grab any error conditions that may have occurred.

The _finish() function for an operation takes the generic result (of type GAsyncResult) and returns the specific result that the operation in question yields (e.g. a gio.FileEnumerator for a "enumerate children" operation). If the result or error status of the operation is not needed, there is no need to call the _finish() function; GIO will take care of cleaning up the result and error information after the GAsyncReadyCallback returns. You can pass NULL for the GAsyncReadyCallback if you don't need to take any action at all after the operation completes. Applications may also take a reference to the GAsyncResult and call _finish() later; however, the _finish() function may be called at most once.

Example of a typical asynchronous operation flow: 

void _theoretical_frobnitz_async (Theoretical         *t,
                                  GCancellable        *c,
                                  GAsyncReadyCallback  cb,
                                  gpointer             u);

gboolean _theoretical_frobnitz_finish (Theoretical   *t,
                                       GAsyncResult  *res,
                                       GError       **e);

static void
frobnitz_result_func (GObject      *source_object,
		 GAsyncResult *res,
		 gpointer      user_data)
{
  gboolean success = FALSE;

  success = _theoretical_frobnitz_finish (source_object, res, NULL);

  if (success)
    g_printf ("Hurray!\n");
  else
    g_printf ("Uh oh!\n");

  ...

}

int main (int argc, void *argv[])
{
   ...

   _theoretical_frobnitz_async (theoretical_data,
                                NULL,
                                frobnitz_result_func,
                                NULL);

   ...
}

The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation the result is a G_IO_ERROR_CANCELLED error.

I/O Priority

Many I/O-related asynchronous operations have a priority parameter, which is used in certain cases to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between G_PRIORITY_LOW and G_PRIORITY_HIGH, with G_PRIORITY_DEFAULT as a default.

AsyncResult wraps an interface. This means the user can get the underlying type by calling Cast().

func (*AsyncResult) IsTagged 

func (res *AsyncResult) IsTagged(sourceTag unsafe.Pointer) bool

IsTagged checks if res has the given source_tag (generally a function pointer indicating the function res was created by).

The function takes the following parameters:

  • sourceTag (optional): application-defined tag.

The function returns the following values:

  • ok: TRUE if res has the indicated source_tag, FALSE if not.

func (*AsyncResult) LegacyPropagateError 

func (res *AsyncResult) LegacyPropagateError() error

LegacyPropagateError: if res is a AsyncResult, this is equivalent to g_simple_async_result_propagate_error(). Otherwise it returns FALSE.

This can be used for legacy error handling in async *_finish() wrapper functions that traditionally handled AsyncResult error returns themselves rather than calling into the virtual method. This should not be used in new code; Result errors that are set by virtual methods should also be extracted by virtual methods, to enable subclasses to chain up correctly.

func (*AsyncResult) SourceObject 

func (res *AsyncResult) SourceObject() *coreglib.Object

SourceObject gets the source object from a Result.

The function returns the following values:

  • object (optional): new reference to the source object for the res, or NULL if there is none.

func (*AsyncResult) UserData 

func (res *AsyncResult) UserData() unsafe.Pointer

UserData gets the user data from a Result.

The function returns the following values:

  • gpointer (optional): user data for res.

type AsyncResultIface added in v0.0.5 

type AsyncResultIface struct {
	// contains filtered or unexported fields
}

AsyncResultIface: interface definition for Result.

An instance of this type is always passed by reference.

type AsyncResulter 

type AsyncResulter interface {
	coreglib.Objector

	// SourceObject gets the source object from a Result.
	SourceObject() *coreglib.Object
	// UserData gets the user data from a Result.
	UserData() unsafe.Pointer
	// IsTagged checks if res has the given source_tag (generally a function
	// pointer indicating the function res was created by).
	IsTagged(sourceTag unsafe.Pointer) bool
	// LegacyPropagateError: if res is a AsyncResult, this is equivalent to
	// g_simple_async_result_propagate_error().
	LegacyPropagateError() error
}

AsyncResulter describes AsyncResult's interface methods.

type BufferedInputStream 

type BufferedInputStream struct {
	FilterInputStream

	Seekable
	// contains filtered or unexported fields
}

BufferedInputStream: buffered input stream implements InputStream and provides for buffered reads.

By default, GBufferedInputStream's buffer size is set at 4 kilobytes.

To create a buffered input stream, use gio.BufferedInputStream.New, or gio.BufferedInputStream.NewSized to specify the buffer's size at construction.

To get the size of a buffer within a buffered input stream, use gio.BufferedInputStream.GetBufferSize(). To change the size of a buffered input stream's buffer, use gio.BufferedInputStream.SetBufferSize(). Note that the buffer's size cannot be reduced below the size of the data within the buffer.

func NewBufferedInputStream 

func NewBufferedInputStream(baseStream InputStreamer) *BufferedInputStream

NewBufferedInputStream creates a new Stream from the given base_stream, with a buffer set to the default size (4 kilobytes).

The function takes the following parameters:

  • baseStream: Stream.

The function returns the following values:

  • bufferedInputStream for the given base_stream.

func NewBufferedInputStreamSized 

func NewBufferedInputStreamSized(baseStream InputStreamer, size uint) *BufferedInputStream

NewBufferedInputStreamSized creates a new InputStream from the given base_stream, with a buffer set to size.

The function takes the following parameters:

  • baseStream: Stream.
  • size: #gsize.

The function returns the following values:

  • bufferedInputStream: Stream.

func (*BufferedInputStream) Available 

func (stream *BufferedInputStream) Available() uint

Available gets the size of the available data within the stream.

The function returns the following values:

  • gsize: size of the available stream.

func (*BufferedInputStream) BufferSize 

func (stream *BufferedInputStream) BufferSize() uint

BufferSize gets the size of the input buffer.

The function returns the following values:

  • gsize: current buffer size.

func (*BufferedInputStream) Fill 

func (stream *BufferedInputStream) Fill(ctx context.Context, count int) (int, error)

Fill tries to read count bytes from the stream into the buffer. Will block during this read.

If count is zero, returns zero and does nothing. A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if count is zero), but never otherwise.

If count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

On error -1 is returned and error is set accordingly.

For the asynchronous, non-blocking, version of this function, see g_buffered_input_stream_fill_async().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • count: number of bytes that will be read from the stream.

The function returns the following values:

  • gssize: number of bytes read into stream's buffer, up to count, or -1 on error.

func (*BufferedInputStream) FillAsync 

func (stream *BufferedInputStream) FillAsync(ctx context.Context, count, ioPriority int, callback AsyncReadyCallback)

FillAsync reads data into stream's buffer asynchronously, up to count size. io_priority can be used to prioritize reads. For the synchronous version of this function, see g_buffered_input_stream_fill().

If count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object.
  • count: number of bytes that will be read from the stream.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback.

func (*BufferedInputStream) FillFinish 

func (stream *BufferedInputStream) FillFinish(result AsyncResulter) (int, error)

FillFinish finishes an asynchronous read.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize of the read stream, or -1 on an error.

func (*BufferedInputStream) Peek 

func (stream *BufferedInputStream) Peek(buffer []byte, offset uint) uint

Peek peeks in the buffer, copying data of size count into buffer, offset offset bytes.

The function takes the following parameters:

  • buffer: pointer to an allocated chunk of memory.
  • offset: #gsize.

The function returns the following values:

  • gsize of the number of bytes peeked, or -1 on error.

func (*BufferedInputStream) PeekBuffer 

func (stream *BufferedInputStream) PeekBuffer() []byte

PeekBuffer returns the buffer with the currently available bytes. The returned buffer must not be modified and will become invalid when reading from the stream or filling the buffer.

The function returns the following values:

  • guint8s: read-only buffer.

func (*BufferedInputStream) ReadByte 

func (stream *BufferedInputStream) ReadByte(ctx context.Context) (int, error)

ReadByte tries to read a single byte from the stream or the buffer. Will block during this read.

On success, the byte read from the stream is returned. On end of stream -1 is returned but it's not an exceptional error and error is not set.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • gint: byte read from the stream, or -1 on end of stream or error.

func (*BufferedInputStream) SetBufferSize 

func (stream *BufferedInputStream) SetBufferSize(size uint)

SetBufferSize sets the size of the internal buffer of stream to size, or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents.

The function takes the following parameters:

  • size: #gsize.

type BufferedInputStreamClass added in v0.0.5 

type BufferedInputStreamClass struct {
	// contains filtered or unexported fields
}

BufferedInputStreamClass: instance of this type is always passed by reference.

func (*BufferedInputStreamClass) ParentClass added in v0.0.5 

func (b *BufferedInputStreamClass) ParentClass() *FilterInputStreamClass

type BufferedInputStreamOverrides added in v0.0.5 

type BufferedInputStreamOverrides struct {
	// Fill tries to read count bytes from the stream into the buffer. Will
	// block during this read.
	//
	// If count is zero, returns zero and does nothing. A value of count larger
	// than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.
	//
	// On success, the number of bytes read into the buffer is returned.
	// It is not an error if this is not the same as the requested size,
	// as it can happen e.g. near the end of a file. Zero is returned on end of
	// file (or if count is zero), but never otherwise.
	//
	// If count is -1 then the attempted read size is equal to the number of
	// bytes that are required to fill the buffer.
	//
	// If cancellable is not NULL, then the operation can be cancelled by
	// triggering the cancellable object from another thread. If the operation
	// was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
	// operation was partially finished when the operation was cancelled the
	// partial result will be returned, without an error.
	//
	// On error -1 is returned and error is set accordingly.
	//
	// For the asynchronous, non-blocking, version of this function, see
	// g_buffered_input_stream_fill_async().
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - count: number of bytes that will be read from the stream.
	//
	// The function returns the following values:
	//
	//   - gssize: number of bytes read into stream's buffer, up to count,
	//     or -1 on error.
	Fill func(ctx context.Context, count int) (int, error)
	// FillFinish finishes an asynchronous read.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - gssize of the read stream, or -1 on an error.
	FillFinish func(result AsyncResulter) (int, error)
}

BufferedInputStreamOverrides contains methods that are overridable.

type BufferedOutputStream 

type BufferedOutputStream struct {
	FilterOutputStream

	Seekable
	// contains filtered or unexported fields
}

BufferedOutputStream: buffered output stream implements gio.FilterOutputStream and provides for buffered writes.

By default, GBufferedOutputStream's buffer size is set at 4 kilobytes.

To create a buffered output stream, use gio.BufferedOutputStream.New, or gio.BufferedOutputStream.NewSized to specify the buffer's size at construction.

To get the size of a buffer within a buffered input stream, use gio.BufferedOutputStream.GetBufferSize(). To change the size of a buffered output stream's buffer, use gio.BufferedOutputStream.SetBufferSize(). Note that the buffer's size cannot be reduced below the size of the data within the buffer.

func NewBufferedOutputStream 

func NewBufferedOutputStream(baseStream OutputStreamer) *BufferedOutputStream

NewBufferedOutputStream creates a new buffered output stream for a base stream.

The function takes the following parameters:

  • baseStream: Stream.

The function returns the following values:

  • bufferedOutputStream for the given base_stream.

func NewBufferedOutputStreamSized 

func NewBufferedOutputStreamSized(baseStream OutputStreamer, size uint) *BufferedOutputStream

NewBufferedOutputStreamSized creates a new buffered output stream with a given buffer size.

The function takes the following parameters:

  • baseStream: Stream.
  • size: #gsize.

The function returns the following values:

  • bufferedOutputStream with an internal buffer set to size.

func (*BufferedOutputStream) AutoGrow 

func (stream *BufferedOutputStream) AutoGrow() bool

AutoGrow checks if the buffer automatically grows as data is added.

The function returns the following values:

  • ok: TRUE if the stream's buffer automatically grows, FALSE otherwise.

func (*BufferedOutputStream) BufferSize 

func (stream *BufferedOutputStream) BufferSize() uint

BufferSize gets the size of the buffer in the stream.

The function returns the following values:

  • gsize: current size of the buffer.

func (*BufferedOutputStream) SetAutoGrow 

func (stream *BufferedOutputStream) SetAutoGrow(autoGrow bool)

SetAutoGrow sets whether or not the stream's buffer should automatically grow. If auto_grow is true, then each write will just make the buffer larger, and you must manually flush the buffer to actually write out the data to the underlying stream.

The function takes the following parameters:

  • autoGrow: #gboolean.

func (*BufferedOutputStream) SetBufferSize 

func (stream *BufferedOutputStream) SetBufferSize(size uint)

SetBufferSize sets the size of the internal buffer to size.

The function takes the following parameters:

  • size: #gsize.

type BufferedOutputStreamClass added in v0.0.5 

type BufferedOutputStreamClass struct {
	// contains filtered or unexported fields
}

BufferedOutputStreamClass: instance of this type is always passed by reference.

func (*BufferedOutputStreamClass) ParentClass added in v0.0.5 

func (b *BufferedOutputStreamClass) ParentClass() *FilterOutputStreamClass

type BufferedOutputStreamOverrides added in v0.0.5 

type BufferedOutputStreamOverrides struct {
}

BufferedOutputStreamOverrides contains methods that are overridable.

type BusAcquiredCallback 

type BusAcquiredCallback func(connection *DBusConnection, name string)

BusAcquiredCallback: invoked when a connection to a message bus has been obtained.

type BusNameAcquiredCallback 

type BusNameAcquiredCallback func(connection *DBusConnection, name string)

BusNameAcquiredCallback: invoked when the name is acquired.

type BusNameAppearedCallback 

type BusNameAppearedCallback func(connection *DBusConnection, name, nameOwner string)

BusNameAppearedCallback: invoked when the name being watched is known to have to have an owner.

type BusNameLostCallback 

type BusNameLostCallback func(connection *DBusConnection, name string)

BusNameLostCallback: invoked when the name is lost or connection has been closed.

type BusNameOwnerFlags 

type BusNameOwnerFlags C.guint

BusNameOwnerFlags flags used in g_bus_own_name(). 

const (
	// BusNameOwnerFlagsNone: no flags set.
	BusNameOwnerFlagsNone BusNameOwnerFlags = 0b0
	// BusNameOwnerFlagsAllowReplacement: allow another message bus connection
	// to claim the name.
	BusNameOwnerFlagsAllowReplacement BusNameOwnerFlags = 0b1
	// BusNameOwnerFlagsReplace: if another message bus connection owns the name
	// and have specified G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take
	// the name from the other connection.
	BusNameOwnerFlagsReplace BusNameOwnerFlags = 0b10
	// BusNameOwnerFlagsDoNotQueue: if another message bus connection owns
	// the name, immediately return an error from g_bus_own_name() rather than
	// entering the waiting queue for that name. (Since 2.54).
	BusNameOwnerFlagsDoNotQueue BusNameOwnerFlags = 0b100
)

func (BusNameOwnerFlags) Has 

func (b BusNameOwnerFlags) Has(other BusNameOwnerFlags) bool

Has returns true if b contains other.

func (BusNameOwnerFlags) String 

func (b BusNameOwnerFlags) String() string

String returns the names in string for BusNameOwnerFlags.

type BusNameVanishedCallback 

type BusNameVanishedCallback func(connection *DBusConnection, name string)

BusNameVanishedCallback: invoked when the name being watched is known not to have to have an owner.

This is also invoked when the BusConnection on which the watch was established has been closed. In that case, connection will be NULL.

type BusNameWatcherFlags 

type BusNameWatcherFlags C.guint

BusNameWatcherFlags flags used in g_bus_watch_name(). 

const (
	// BusNameWatcherFlagsNone: no flags set.
	BusNameWatcherFlagsNone BusNameWatcherFlags = 0b0
	// BusNameWatcherFlagsAutoStart: if no-one owns the name when beginning to
	// watch the name, ask the bus to launch an owner for the name.
	BusNameWatcherFlagsAutoStart BusNameWatcherFlags = 0b1
)

func (BusNameWatcherFlags) Has 

func (b BusNameWatcherFlags) Has(other BusNameWatcherFlags) bool

Has returns true if b contains other.

func (BusNameWatcherFlags) String 

func (b BusNameWatcherFlags) String() string

String returns the names in string for BusNameWatcherFlags.

type BusType 

type BusType C.gint

BusType: enumeration for well-known message buses. 

const (
	// BusTypeStarter alias for the message bus that activated the process,
	// if any.
	BusTypeStarter BusType = -1
	// BusTypeNone: not a message bus.
	BusTypeNone BusType = 0
	// BusTypeSystem: system-wide message bus.
	BusTypeSystem BusType = 1
	// BusTypeSession: login session message bus.
	BusTypeSession BusType = 2
)

func (BusType) String 

func (b BusType) String() string

String returns the name in string for BusType.

type BytesIcon 

type BytesIcon struct {
	*coreglib.Object

	LoadableIcon
	// contains filtered or unexported fields
}

BytesIcon: GBytesIcon specifies an image held in memory in a common format (usually PNG) to be used as icon.

func NewBytesIcon 

func NewBytesIcon(bytes *glib.Bytes) *BytesIcon

NewBytesIcon creates a new icon for a bytes.

This cannot fail, but loading and interpreting the bytes may fail later on (for example, if g_loadable_icon_load() is called) if the image is invalid.

The function takes the following parameters:

  • bytes: #GBytes.

The function returns the following values:

  • bytesIcon for the given bytes.

func (*BytesIcon) Bytes 

func (icon *BytesIcon) Bytes() *glib.Bytes

Bytes gets the #GBytes associated with the given icon.

The function returns the following values:

  • bytes: #GBytes.

type Cancellable 

type Cancellable struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Cancellable: GCancellable allows operations to be cancelled.

GCancellable is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations.

func CancellableGetCurrent 

func CancellableGetCurrent() *Cancellable

CancellableGetCurrent gets the top cancellable from the stack.

The function returns the following values:

  • cancellable (optional) from the top of the stack, or NULL if the stack is empty.

func NewCancellable 

func NewCancellable() *Cancellable

NewCancellable creates a new #GCancellable object.

Applications that want to start one or more operations that should be cancellable should create a #GCancellable and pass it to the operations.

One #GCancellable can be used in multiple consecutive operations or in multiple concurrent operations.

The function returns the following values:

  • cancellable: #GCancellable.

func (*Cancellable) Cancel 

func (cancellable *Cancellable) Cancel()

Cancel will set cancellable to cancelled, and will emit the #GCancellable::cancelled signal. (However, see the warning about race conditions in the documentation for that signal if you are planning to connect to it.)

This function is thread-safe. In other words, you can safely call it from a thread other than the one running the operation that was passed the cancellable.

If cancellable is NULL, this function returns immediately for convenience.

The convention within GIO is that cancelling an asynchronous operation causes it to complete asynchronously. That is, if you cancel the operation from the same thread in which it is running, then the operation's ReadyCallback will not be invoked until the application returns to the main loop.

func (*Cancellable) ConnectCancelled 

func (cancellable *Cancellable) ConnectCancelled(f func()) coreglib.SignalHandle

ConnectCancelled is emitted when the operation has been cancelled.

Can be used by implementations of cancellable operations. If the operation is cancelled from another thread, the signal will be emitted in the thread that cancelled the operation, not the thread that is running the operation.

Note that disconnecting from this signal (or any signal) in a multi-threaded program is prone to race conditions. For instance it is possible that a signal handler may be invoked even after a call to g_signal_handler_disconnect() for that handler has already returned.

There is also a problem when cancellation happens right before connecting to the signal. If this happens the signal will unexpectedly not be emitted, and checking before connecting to the signal leaves a race condition where this is still happening.

In order to make it safe and easy to connect handlers there are two helper functions: g_cancellable_connect() and g_cancellable_disconnect() which protect against problems like this.

An example of how to us this: 

// Make sure we don't do unnecessary work if already cancelled
if (g_cancellable_set_error_if_cancelled (cancellable, error))
  return;

// Set up all the data needed to be able to handle cancellation
// of the operation
my_data = my_data_new (...);

id = 0;
if (cancellable)
  id = g_cancellable_connect (cancellable,
			      G_CALLBACK (cancelled_handler)
			      data, NULL);

// cancellable operation here...

g_cancellable_disconnect (cancellable, id);

// cancelled_handler is never called after this, it is now safe
// to free the data
my_data_free (my_data);

Note that the cancelled signal is emitted in the thread that the user cancelled from, which may be the main thread. So, the cancellable signal should not do something that can block.

func (*Cancellable) Disconnect 

func (cancellable *Cancellable) Disconnect(handlerId uint32)

Disconnect disconnects a handler from a cancellable instance similar to g_signal_handler_disconnect(). Additionally, in the event that a signal handler is currently running, this call will block until the handler has finished. Calling this function from a #GCancellable::cancelled signal handler will therefore result in a deadlock.

This avoids a race condition where a thread cancels at the same time as the cancellable operation is finished and the signal handler is removed. See #GCancellable::cancelled for details on how to use this.

If cancellable is NULL or handler_id is 0 this function does nothing.

The function takes the following parameters:

  • handlerId: handler id of the handler to be disconnected, or 0.

func (*Cancellable) Fd 

func (cancellable *Cancellable) Fd() int

Fd gets the file descriptor for a cancellable job. This can be used to implement cancellable operations on Unix systems. The returned fd will turn readable when cancellable is cancelled.

You are not supposed to read from the fd yourself, just check for readable status. Reading to unset the readable status is done with g_cancellable_reset().

After a successful return from this function, you should use g_cancellable_release_fd() to free up resources allocated for the returned file descriptor.

See also g_cancellable_make_pollfd().

The function returns the following values:

  • gint: valid file descriptor. -1 if the file descriptor is not supported, or on errors.

func (*Cancellable) IsCancelled 

func (cancellable *Cancellable) IsCancelled() bool

IsCancelled checks if a cancellable job has been cancelled.

The function returns the following values:

  • ok: TRUE if cancellable is cancelled, FALSE if called with NULL or if item is not cancelled.

func (*Cancellable) NewSource 

func (cancellable *Cancellable) NewSource() *glib.Source

NewSource creates a source that triggers if cancellable is cancelled and calls its callback of type SourceFunc. This is primarily useful for attaching to another (non-cancellable) source with g_source_add_child_source() to add cancellability to it.

For convenience, you can call this with a NULL #GCancellable, in which case the source will never trigger.

The new #GSource will hold a reference to the #GCancellable.

The function returns the following values:

  • source: new #GSource.

func (*Cancellable) PopCurrent 

func (cancellable *Cancellable) PopCurrent()

PopCurrent pops cancellable off the cancellable stack (verifying that cancellable is on the top of the stack).

func (*Cancellable) PushCurrent 

func (cancellable *Cancellable) PushCurrent()

PushCurrent pushes cancellable onto the cancellable stack. The current cancellable can then be received using g_cancellable_get_current().

This is useful when implementing cancellable operations in code that does not allow you to pass down the cancellable object.

This is typically called automatically by e.g. #GFile operations, so you rarely have to call this yourself.

func (*Cancellable) ReleaseFd 

func (cancellable *Cancellable) ReleaseFd()

ReleaseFd releases a resources previously allocated by g_cancellable_get_fd() or g_cancellable_make_pollfd().

For compatibility reasons with older releases, calling this function is not strictly required, the resources will be automatically freed when the cancellable is finalized. However, the cancellable will block scarce file descriptors until it is finalized if this function is not called. This can cause the application to run out of file descriptors when many #GCancellables are used at the same time.

func (*Cancellable) Reset 

func (cancellable *Cancellable) Reset()

Reset resets cancellable to its uncancelled state.

If cancellable is currently in use by any cancellable operation then the behavior of this function is undefined.

Note that it is generally not a good idea to reuse an existing cancellable for more operations after it has been cancelled once, as this function might tempt you to do. The recommended practice is to drop the reference to a cancellable after cancelling it, and let it die with the outstanding async operations. You should create a fresh cancellable for further async operations.

func (*Cancellable) SetErrorIfCancelled 

func (cancellable *Cancellable) SetErrorIfCancelled() error

SetErrorIfCancelled: if the cancellable is cancelled, sets the error to notify that the operation was cancelled.

type CancellableClass added in v0.0.5 

type CancellableClass struct {
	// contains filtered or unexported fields
}

CancellableClass: instance of this type is always passed by reference.

type CancellableOverrides added in v0.0.5 

type CancellableOverrides struct {
	Cancelled func()
}

CancellableOverrides contains methods that are overridable.

type CharsetConverter 

type CharsetConverter struct {
	*coreglib.Object

	Converter
	Initable
	// contains filtered or unexported fields
}

CharsetConverter: GCharsetConverter is an implementation of gio.Converter based on glib.IConv.

func NewCharsetConverter 

func NewCharsetConverter(toCharset, fromCharset string) (*CharsetConverter, error)

NewCharsetConverter creates a new Converter.

The function takes the following parameters:

  • toCharset: destination charset.
  • fromCharset: source charset.

The function returns the following values:

  • charsetConverter: new Converter or NULL on error.

func (*CharsetConverter) NumFallbacks 

func (converter *CharsetConverter) NumFallbacks() uint

NumFallbacks gets the number of fallbacks that converter has applied so far.

The function returns the following values:

  • guint: number of fallbacks that converter has applied.

func (*CharsetConverter) SetUseFallback 

func (converter *CharsetConverter) SetUseFallback(useFallback bool)

SetUseFallback sets the Converter:use-fallback property.

The function takes the following parameters:

  • useFallback: TRUE to use fallbacks.

func (*CharsetConverter) UseFallback 

func (converter *CharsetConverter) UseFallback() bool

UseFallback gets the Converter:use-fallback property.

The function returns the following values:

  • ok: TRUE if fallbacks are used by converter.

type CharsetConverterClass added in v0.0.5 

type CharsetConverterClass struct {
	// contains filtered or unexported fields
}

CharsetConverterClass: instance of this type is always passed by reference.

type CharsetConverterOverrides added in v0.0.5 

type CharsetConverterOverrides struct {
}

CharsetConverterOverrides contains methods that are overridable.

type Converter 

type Converter struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Converter: GConverter is an interface for streaming conversions.

GConverter is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place.

Some example conversions are: character set conversion, compression, decompression and regular expression replace.

Converter wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Converter) Convert 

func (converter *Converter) Convert(inbuf, outbuf []byte, flags ConverterFlags) (bytesRead, bytesWritten uint, converterResult ConverterResult, goerr error)

Convert: this is the main operation used when converting data. It is to be called multiple times in a loop, and each time it will do some work, i.e. producing some output (in outbuf) or consuming some input (from inbuf) or both. If its not possible to do any work an error is returned.

Note that a single call may not consume all input (or any input at all). Also a call may produce output even if given no input, due to state stored in the converter producing output.

If any data was either produced or consumed, and then an error happens, then only the successful conversion is reported and the error is returned on the next call.

A full conversion loop involves calling this method repeatedly, each time giving it new input and space output space. When there is no more input data after the data in inbuf, the flag G_CONVERTER_INPUT_AT_END must be set. The loop will be (unless some error happens) returning G_CONVERTER_CONVERTED each time until all data is consumed and all output is produced, then G_CONVERTER_FINISHED is returned instead. Note, that G_CONVERTER_FINISHED may be returned even if G_CONVERTER_INPUT_AT_END is not set, for instance in a decompression converter where the end of data is detectable from the data (and there might even be other data after the end of the compressed data).

When some data has successfully been converted bytes_read and is set to the number of bytes read from inbuf, and bytes_written is set to indicate how many bytes was written to outbuf. If there are more data to output or consume (i.e. unless the G_CONVERTER_INPUT_AT_END is specified) then G_CONVERTER_CONVERTED is returned, and if no more data is to be output then G_CONVERTER_FINISHED is returned.

On error G_CONVERTER_ERROR is returned and error is set accordingly. Some errors need special handling:

G_IO_ERROR_NO_SPACE is returned if there is not enough space to write the resulting converted data, the application should call the function again with a larger outbuf to continue.

G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough input to fully determine what the conversion should produce, and the G_CONVERTER_INPUT_AT_END flag is not set. This happens for example with an incomplete multibyte sequence when converting text, or when a regexp matches up to the end of the input (and may match further input). It may also happen when inbuf_size is zero and there is no more data to produce.

When this happens the application should read more input and then call the function again. If further input shows that there is no more data call the function again with the same data but with the G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion to finish as e.g. in the regexp match case (or, to fail again with G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the input is actually partial).

After g_converter_convert() has returned G_CONVERTER_FINISHED the converter object is in an invalid state where its not allowed to call g_converter_convert() anymore. At this time you can only free the object or call g_converter_reset() to reset it to the initial state.

If the flag G_CONVERTER_FLUSH is set then conversion is modified to try to write out all internal state to the output. The application has to call the function multiple times with the flag set, and when the available input has been consumed and all internal state has been produced then G_CONVERTER_FLUSHED (or G_CONVERTER_FINISHED if really at the end) is returned instead of G_CONVERTER_CONVERTED. This is somewhat similar to what happens at the end of the input stream, but done in the middle of the data.

This has different meanings for different conversions. For instance in a compression converter it would mean that we flush all the compression state into output such that if you uncompress the compressed data you get back all the input data. Doing this may make the final file larger due to padding though. Another example is a regexp conversion, where if you at the end of the flushed data have a match, but there is also a potential longer match. In the non-flushed case we would ask for more input, but when flushing we treat this as the end of input and do the match.

Flushing is not always possible (like if a charset converter flushes at a partial multibyte sequence). Converters are supposed to try to produce as much output as possible and then return an error (typically G_IO_ERROR_PARTIAL_INPUT).

The function takes the following parameters:

  • inbuf: buffer containing the data to convert.
  • outbuf: a buffer to write converted data in.
  • flags controlling the conversion details.

The function returns the following values:

  • bytesRead will be set to the number of bytes read from inbuf on success.
  • bytesWritten will be set to the number of bytes written to outbuf on success.
  • converterResult G_CONVERTER_ERROR on error.

func (*Converter) Reset 

func (converter *Converter) Reset()

Reset resets all internal state in the converter, making it behave as if it was just created. If the converter has any internal state that would produce output then that output is lost.

type ConverterFlags 

type ConverterFlags C.guint

ConverterFlags flags used when calling a g_converter_convert(). 

const (
	// ConverterNoFlags: no flags.
	ConverterNoFlags ConverterFlags = 0b0
	// ConverterInputAtEnd: at end of input data.
	ConverterInputAtEnd ConverterFlags = 0b1
	// ConverterFlush: flush data.
	ConverterFlush ConverterFlags = 0b10
)

func (ConverterFlags) Has 

func (c ConverterFlags) Has(other ConverterFlags) bool

Has returns true if c contains other.

func (ConverterFlags) String 

func (c ConverterFlags) String() string

String returns the names in string for ConverterFlags.

type ConverterIface added in v0.0.5 

type ConverterIface struct {
	// contains filtered or unexported fields
}

ConverterIface provides an interface for converting data from one type to another type. The conversion can be stateful and may fail at any place.

An instance of this type is always passed by reference.

type ConverterInputStream 

type ConverterInputStream struct {
	FilterInputStream

	*coreglib.Object
	InputStream
	PollableInputStream
	// contains filtered or unexported fields
}

ConverterInputStream: converter input stream implements gio.InputStream and allows conversion of data of various types during reading.

As of GLib 2.34, GConverterInputStream implements gio.PollableInputStream.

func NewConverterInputStream 

func NewConverterInputStream(baseStream InputStreamer, converter Converterer) *ConverterInputStream

NewConverterInputStream creates a new converter input stream for the base_stream.

The function takes the following parameters:

  • baseStream: Stream.
  • converter: #GConverter.

The function returns the following values:

  • converterInputStream: new Stream.

func (*ConverterInputStream) Converter 

func (converterStream *ConverterInputStream) Converter() *Converter

Converter gets the #GConverter that is used by converter_stream.

The function returns the following values:

  • converter of the converter input stream.

type ConverterInputStreamClass added in v0.0.5 

type ConverterInputStreamClass struct {
	// contains filtered or unexported fields
}

ConverterInputStreamClass: instance of this type is always passed by reference.

func (*ConverterInputStreamClass) ParentClass added in v0.0.5 

func (c *ConverterInputStreamClass) ParentClass() *FilterInputStreamClass

type ConverterInputStreamOverrides added in v0.0.5 

type ConverterInputStreamOverrides struct {
}

ConverterInputStreamOverrides contains methods that are overridable.

type ConverterOutputStream 

type ConverterOutputStream struct {
	FilterOutputStream

	*coreglib.Object
	OutputStream
	PollableOutputStream
	// contains filtered or unexported fields
}

ConverterOutputStream: converter output stream implements gio.OutputStream and allows conversion of data of various types during reading.

As of GLib 2.34, GConverterOutputStream implements gio.PollableOutputStream.

func NewConverterOutputStream 

func NewConverterOutputStream(baseStream OutputStreamer, converter Converterer) *ConverterOutputStream

NewConverterOutputStream creates a new converter output stream for the base_stream.

The function takes the following parameters:

  • baseStream: Stream.
  • converter: #GConverter.

The function returns the following values:

  • converterOutputStream: new Stream.

func (*ConverterOutputStream) Converter 

func (converterStream *ConverterOutputStream) Converter() *Converter

Converter gets the #GConverter that is used by converter_stream.

The function returns the following values:

  • converter of the converter output stream.

type ConverterOutputStreamClass added in v0.0.5 

type ConverterOutputStreamClass struct {
	// contains filtered or unexported fields
}

ConverterOutputStreamClass: instance of this type is always passed by reference.

func (*ConverterOutputStreamClass) ParentClass added in v0.0.5 

func (c *ConverterOutputStreamClass) ParentClass() *FilterOutputStreamClass

type ConverterOutputStreamOverrides added in v0.0.5 

type ConverterOutputStreamOverrides struct {
}

ConverterOutputStreamOverrides contains methods that are overridable.

type ConverterResult 

type ConverterResult C.gint

ConverterResult results returned from g_converter_convert(). 

const (
	// ConverterError: there was an error during conversion.
	ConverterError ConverterResult = iota
	// ConverterConverted: some data was consumed or produced.
	ConverterConverted
	// ConverterFinished: conversion is finished.
	ConverterFinished
	// ConverterFlushed: flushing is finished.
	ConverterFlushed
)

func (ConverterResult) String 

func (c ConverterResult) String() string

String returns the name in string for ConverterResult.

type Converterer 

type Converterer interface {
	coreglib.Objector

	// Convert: this is the main operation used when converting data.
	Convert(inbuf, outbuf []byte, flags ConverterFlags) (bytesRead, bytesWritten uint, converterResult ConverterResult, goerr error)
	// Reset resets all internal state in the converter, making it behave as if
	// it was just created.
	Reset()
}

Converterer describes Converter's interface methods.

type Credentials 

type Credentials struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Credentials: GCredentials type is a reference-counted wrapper for native credentials.

The information in GCredentials is typically used for identifying, authenticating and authorizing other processes.

Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. gio.Socket.GetCredentials().

Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see gio.UnixCredentialsMessage, gio.UnixConnection.SendCredentials() and gio.UnixConnection.ReceiveCredentials() for details.

On Linux, the native credential type is a struct ucred - see the unix(7) man page (man:unix(7)) for details. This corresponds to G_CREDENTIALS_TYPE_LINUX_UCRED.

On Apple operating systems (including iOS, tvOS, and macOS), the native credential type is a struct xucred. This corresponds to G_CREDENTIALS_TYPE_APPLE_XUCRED.

On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a struct cmsgcred. This corresponds to G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.

On NetBSD, the native credential type is a struct unpcbid. This corresponds to G_CREDENTIALS_TYPE_NETBSD_UNPCBID.

On OpenBSD, the native credential type is a struct sockpeercred. This corresponds to G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.

On Solaris (including OpenSolaris and its derivatives), the native credential type is a ucred_t. This corresponds to G_CREDENTIALS_TYPE_SOLARIS_UCRED.

Since GLib 2.72, on Windows, the native credentials may contain the PID of a process. This corresponds to G_CREDENTIALS_TYPE_WIN32_PID.

func NewCredentials 

func NewCredentials() *Credentials

NewCredentials creates a new #GCredentials object with credentials matching the the current process.

The function returns the following values:

  • credentials Free with g_object_unref().

func (*Credentials) IsSameUser 

func (credentials *Credentials) IsSameUser(otherCredentials *Credentials) error

IsSameUser checks if credentials and other_credentials is the same user.

This operation can fail if #GCredentials is not supported on the the OS.

The function takes the following parameters:

  • otherCredentials: #GCredentials.

func (*Credentials) SetNative 

func (credentials *Credentials) SetNative(nativeType CredentialsType, native unsafe.Pointer)

SetNative copies the native credentials of type native_type from native into credentials.

It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if native_type isn't supported by the OS.

The function takes the following parameters:

  • nativeType: type of native credentials to set.
  • native: pointer to native credentials.

func (*Credentials) String 

func (credentials *Credentials) String() string

String creates a human-readable textual representation of credentials that can be used in logging and debug messages. The format of the returned string may change in future GLib release.

The function returns the following values:

  • utf8: string that should be freed with g_free().

type CredentialsType 

type CredentialsType C.gint

CredentialsType: enumeration describing different kinds of native credential types. 

const (
	// CredentialsTypeInvalid indicates an invalid native credential type.
	CredentialsTypeInvalid CredentialsType = iota
	// CredentialsTypeLinuxUcred: native credentials type is a struct ucred.
	CredentialsTypeLinuxUcred
	// CredentialsTypeFreebsdCmsgcred: native credentials type is a struct
	// cmsgcred.
	CredentialsTypeFreebsdCmsgcred
	// CredentialsTypeOpenbsdSockpeercred: native credentials type is a struct
	// sockpeercred. Added in 2.30.
	CredentialsTypeOpenbsdSockpeercred
	// CredentialsTypeSolarisUcred: native credentials type is a ucred_t.
	// Added in 2.40.
	CredentialsTypeSolarisUcred
	// CredentialsTypeNetbsdUnpcbid: native credentials type is a struct
	// unpcbid. Added in 2.42.
	CredentialsTypeNetbsdUnpcbid
	// CredentialsTypeAppleXucred: native credentials type is a struct xucred.
	// Added in 2.66.
	CredentialsTypeAppleXucred
	// CredentialsTypeWin32Pid: native credentials type is a PID DWORD. Added in
	// 2.72.
	CredentialsTypeWin32Pid
)

func (CredentialsType) String 

func (c CredentialsType) String() string

String returns the name in string for CredentialsType.

type DBusActionGroup 

type DBusActionGroup struct {
	*coreglib.Object

	RemoteActionGroup
	// contains filtered or unexported fields
}

DBusActionGroup: GDBusActionGroup is an implementation of the gio.ActionGroup interface.

GDBusActionGroup can be used as a proxy for an action group that is exported over D-Bus with gio.DBusConnection.ExportActionGroup().

func DBusActionGroupGet 

func DBusActionGroupGet(connection *DBusConnection, busName, objectPath string) *DBusActionGroup

DBusActionGroupGet obtains a BusActionGroup for the action group which is exported at the given bus_name and object_path.

The thread default main context is taken at the time of this call. All signals on the menu model (and any linked models) are reported with respect to this context. All calls on the returned menu model (and linked models) must also originate from this same context, with the thread default main context unchanged.

This call is non-blocking. The returned action group may or may not already be filled in. The correct thing to do is connect the signals for the action group to monitor for changes and then to call g_action_group_list_actions() to get the initial list.

The function takes the following parameters:

  • connection: BusConnection.
  • busName (optional) bus name which exports the action group or NULL if connection is not a message bus connection.
  • objectPath: object path at which the action group is exported.

The function returns the following values:

  • dBusActionGroup: BusActionGroup.

type DBusAnnotationInfo 

type DBusAnnotationInfo struct {
	// contains filtered or unexported fields
}

DBusAnnotationInfo: information about an annotation.

An instance of this type is always passed by reference.

func (*DBusAnnotationInfo) Annotations 

func (d *DBusAnnotationInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusAnnotationInfo) Key 

func (d *DBusAnnotationInfo) Key() string

Key: name of the annotation, e.g. "org.freedesktop.DBus.Deprecated".

func (*DBusAnnotationInfo) RefCount 

func (d *DBusAnnotationInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusAnnotationInfo) SetRefCount 

func (d *DBusAnnotationInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

func (*DBusAnnotationInfo) Value 

func (d *DBusAnnotationInfo) Value() string

Value: value of the annotation.

type DBusArgInfo 

type DBusArgInfo struct {
	// contains filtered or unexported fields
}

DBusArgInfo: information about an argument for a method or a signal.

An instance of this type is always passed by reference.

func (*DBusArgInfo) Annotations 

func (d *DBusArgInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusArgInfo) Name 

func (d *DBusArgInfo) Name() string

Name of the argument, e.g. unix_user_id.

func (*DBusArgInfo) RefCount 

func (d *DBusArgInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusArgInfo) SetRefCount 

func (d *DBusArgInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

func (*DBusArgInfo) Signature 

func (d *DBusArgInfo) Signature() string

Signature d-Bus signature of the argument (a single complete type).

type DBusAuthObserver 

type DBusAuthObserver struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusAuthObserver: GDBusAuthObserver provides a mechanism for participating in how a gio.DBusServer (or a gio.DBusConnection) authenticates remote peers.

Simply instantiate a GDBusAuthObserver and connect to the signals you are interested in. Note that new signals may be added in the future.

Controlling Authentication Mechanisms

By default, a GDBusServer or server-side GDBusConnection will allow any authentication mechanism to be used. If you only want to allow D-Bus connections with the EXTERNAL mechanism, which makes use of credentials passing and is the recommended mechanism for modern Unix platforms such as Linux and the BSD family, you would use a signal handler like this: 

static gboolean
on_allow_mechanism (GDBusAuthObserver *observer,
                    const gchar       *mechanism,
                    gpointer           user_data)
{
  if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
    {
      return TRUE;
    }

  return FALSE;
}

Controlling Authorization

By default, a GDBusServer or server-side GDBusConnection will accept connections from any successfully authenticated user (but not from anonymous connections using the ANONYMOUS mechanism). If you only want to allow D-Bus connections from processes owned by the same uid as the server, since GLib 2.68, you should use the G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent to the following signal handler: 

static gboolean
on_authorize_authenticated_peer (GDBusAuthObserver *observer,
                                 GIOStream         *stream,
                                 GCredentials      *credentials,
                                 gpointer           user_data)
{
  gboolean authorized;

  authorized = FALSE;
  if (credentials != NULL)
    {
      GCredentials *own_credentials;
      own_credentials = g_credentials_new ();
      if (g_credentials_is_same_user (credentials, own_credentials, NULL))
        authorized = TRUE;
      g_object_unref (own_credentials);
    }

  return authorized;
}.

func NewDBusAuthObserver 

func NewDBusAuthObserver() *DBusAuthObserver

NewDBusAuthObserver creates a new BusAuthObserver object.

The function returns the following values:

  • dBusAuthObserver Free with g_object_unref().

func (*DBusAuthObserver) AllowMechanism 

func (observer *DBusAuthObserver) AllowMechanism(mechanism string) bool

AllowMechanism emits the BusAuthObserver::allow-mechanism signal on observer.

The function takes the following parameters:

  • mechanism: name of the mechanism, e.g. DBUS_COOKIE_SHA1.

The function returns the following values:

  • ok: TRUE if mechanism can be used to authenticate the other peer, FALSE if not.

func (*DBusAuthObserver) AuthorizeAuthenticatedPeer 

func (observer *DBusAuthObserver) AuthorizeAuthenticatedPeer(stream IOStreamer, credentials *Credentials) bool

AuthorizeAuthenticatedPeer emits the BusAuthObserver::authorize-authenticated-peer signal on observer.

The function takes the following parameters:

  • stream for the BusConnection.
  • credentials (optional) credentials received from the peer or NULL.

The function returns the following values:

  • ok: TRUE if the peer is authorized, FALSE if not.

func (*DBusAuthObserver) ConnectAllowMechanism 

func (observer *DBusAuthObserver) ConnectAllowMechanism(f func(mechanism string) (ok bool)) coreglib.SignalHandle

ConnectAllowMechanism is emitted to check if mechanism is allowed to be used.

func (*DBusAuthObserver) ConnectAuthorizeAuthenticatedPeer 

func (observer *DBusAuthObserver) ConnectAuthorizeAuthenticatedPeer(f func(stream IOStreamer, credentials *Credentials) (ok bool)) coreglib.SignalHandle

ConnectAuthorizeAuthenticatedPeer is emitted to check if a peer that is successfully authenticated is authorized.

type DBusCallFlags 

type DBusCallFlags C.guint

DBusCallFlags flags used in g_dbus_connection_call() and similar APIs. 

const (
	// DBusCallFlagsNone: no flags set.
	DBusCallFlagsNone DBusCallFlags = 0b0
	// DBusCallFlagsNoAutoStart bus must not launch an owner for the destination
	// name in response to this method invocation.
	DBusCallFlagsNoAutoStart DBusCallFlags = 0b1
	// DBusCallFlagsAllowInteractiveAuthorization: caller is prepared to wait
	// for interactive authorization. Since 2.46.
	DBusCallFlagsAllowInteractiveAuthorization DBusCallFlags = 0b10
)

func (DBusCallFlags) Has 

func (d DBusCallFlags) Has(other DBusCallFlags) bool

Has returns true if d contains other.

func (DBusCallFlags) String 

func (d DBusCallFlags) String() string

String returns the names in string for DBusCallFlags.

type DBusCapabilityFlags 

type DBusCapabilityFlags C.guint

DBusCapabilityFlags capabilities negotiated with the remote peer. 

const (
	// DBusCapabilityFlagsNone: no flags set.
	DBusCapabilityFlagsNone DBusCapabilityFlags = 0b0
	// DBusCapabilityFlagsUnixFdPassing connection supports exchanging UNIX file
	// descriptors with the remote peer.
	DBusCapabilityFlagsUnixFdPassing DBusCapabilityFlags = 0b1
)

func (DBusCapabilityFlags) Has 

func (d DBusCapabilityFlags) Has(other DBusCapabilityFlags) bool

Has returns true if d contains other.

func (DBusCapabilityFlags) String 

func (d DBusCapabilityFlags) String() string

String returns the names in string for DBusCapabilityFlags.

type DBusConnection 

type DBusConnection struct {
	*coreglib.Object

	AsyncInitable
	Initable
	// contains filtered or unexported fields
}

DBusConnection: GDBusConnection type is used for D-Bus connections to remote peers such as a message buses.

It is a low-level API that offers a lot of flexibility. For instance, it lets you establish a connection over any transport that can by represented as a gio.IOStream.

This class is rarely used directly in D-Bus clients. If you are writing a D-Bus client, it is often easier to use the gio.BusOwnName(), gio.BusWatchName() or gio.DBusProxy().NewForBus APIs.

As an exception to the usual GLib rule that a particular object must not be used by two threads at the same time, GDBusConnections methods may be called from any thread. This is so that gio.BusGet() and gio.BusGetSync() can safely return the same GDBusConnection when called from any thread.

Most of the ways to obtain a GDBusConnection automatically initialize it (i.e. connect to D-Bus): for instance, gio.DBusConnection().New and gio.BusGet(), and the synchronous versions of those methods, give you an initialized connection. Language bindings for GIO should use gio.Initable().New or gio.AsyncInitable().NewAsync, which also initialize the connection.

If you construct an uninitialized GDBusConnection, such as via gobject.Object.New, you must initialize it via gio.Initable.Init() or gio.AsyncInitable.InitAsync() before using its methods or properties. Calling methods or accessing properties on a GDBusConnection that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a GError, the only valid thing you can do with that GDBusConnection is to free it with gobject.Object.Unref().

An example D-Bus server

Here is an example for a D-Bus server: gdbus-example-server.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c)

An example for exporting a subtree

Here is an example for exporting a subtree: gdbus-example-subtree.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c)

An example for file descriptor passing

Here is an example for passing UNIX file descriptors: gdbus-unix-fd-client.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c)

An example for exporting a GObject

Here is an example for exporting a #GObject: gdbus-example-export.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c).

func BusGetFinish 

func BusGetFinish(res AsyncResulter) (*DBusConnection, error)

BusGetFinish finishes an operation started with g_bus_get().

The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for bus_type. In the event that you need a private message bus connection, use g_dbus_address_get_for_bus_sync() and g_dbus_connection_new_for_address() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags.

Note that the returned BusConnection object will (usually) have the BusConnection:exit-on-close property set to TRUE.

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_bus_get().

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func BusGetSync 

func BusGetSync(ctx context.Context, busType BusType) (*DBusConnection, error)

BusGetSync: synchronously connects to the message bus specified by bus_type. Note that the returned object may shared with other callers, e.g. if two separate parts of a process calls this function with the same bus_type, they will share the same object.

This is a synchronous failable function. See g_bus_get() and g_bus_get_finish() for the asynchronous version.

The returned object is a singleton, that is, shared with other callers of g_bus_get() and g_bus_get_sync() for bus_type. In the event that you need a private message bus connection, use g_dbus_address_get_for_bus_sync() and g_dbus_connection_new_for_address() with G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT and G_DBUS_CONNECTION_FLAGS_MESSAGE_BUS_CONNECTION flags.

Note that the returned BusConnection object will (usually) have the BusConnection:exit-on-close property set to TRUE.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busType: Type.

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func NewDBusConnectionFinish 

func NewDBusConnectionFinish(res AsyncResulter) (*DBusConnection, error)

NewDBusConnectionFinish finishes an operation started with g_dbus_connection_new().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_new().

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func NewDBusConnectionForAddressFinish 

func NewDBusConnectionForAddressFinish(res AsyncResulter) (*DBusConnection, error)

NewDBusConnectionForAddressFinish finishes an operation started with g_dbus_connection_new_for_address().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_new().

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func NewDBusConnectionForAddressSync 

func NewDBusConnectionForAddressSync(ctx context.Context, address string, flags DBusConnectionFlags, observer *DBusAuthObserver) (*DBusConnection, error)

NewDBusConnectionForAddressSync: synchronously connects and sets up a D-Bus client connection for exchanging D-Bus messages with an endpoint specified by address which must be in the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

This constructor can only be used to initiate client-side connections - use g_dbus_connection_new_sync() if you need to act as the server. In particular, flags cannot contain the G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags.

This is a synchronous failable constructor. See g_dbus_connection_new_for_address() for the asynchronous version.

If observer is not NULL it may be used to control the authentication process.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address d-Bus address.
  • flags describing how to make the connection.
  • observer (optional) or NULL.

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func NewDBusConnectionSync 

func NewDBusConnectionSync(ctx context.Context, stream IOStreamer, guid string, flags DBusConnectionFlags, observer *DBusAuthObserver) (*DBusConnection, error)

NewDBusConnectionSync: synchronously sets up a D-Bus connection for exchanging D-Bus messages with the end represented by stream.

If stream is a Connection, then the corresponding #GSocket will be put into non-blocking mode.

The D-Bus connection will interact with stream from a worker thread. As a result, the caller should not interact with stream after this method has been called, except by calling g_object_unref() on it.

If observer is not NULL it may be used to control the authentication process.

This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • stream: OStream.
  • guid (optional): GUID to use if authenticating as a server or NULL.
  • flags describing how to make the connection.
  • observer (optional) or NULL.

The function returns the following values:

  • dBusConnection or NULL if error is set. Free with g_object_unref().

func (*DBusConnection) AddFilter 

func (connection *DBusConnection) AddFilter(filterFunction DBusMessageFilterFunction) uint

AddFilter adds a message filter. Filters are handlers that are run on all incoming and outgoing messages, prior to standard dispatch. Filters are run in the order that they were added. The same handler can be added as a filter more than once, in which case it will be run more than once. Filters added during a filter callback won't be run on the message being processed. Filter functions are allowed to modify and even drop messages.

Note that filters are run in a dedicated message handling thread so they can't block and, generally, can't do anything but signal a worker thread. Also note that filters are rarely needed - use API such as g_dbus_connection_send_message_with_reply(), g_dbus_connection_signal_subscribe() or g_dbus_connection_call() instead.

If a filter consumes an incoming message the message is not dispatched anywhere else - not even the standard dispatch machinery (that API such as g_dbus_connection_signal_subscribe() and g_dbus_connection_send_message_with_reply() relies on) will see the message. Similarly, if a filter consumes an outgoing message, the message will not be sent to the other peer.

If user_data_free_func is non-NULL, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after user_data is no longer needed. (It is not guaranteed to be called synchronously when the filter is removed, and may be called after connection has been destroyed.).

The function takes the following parameters:

  • filterFunction: filter function.

The function returns the following values:

  • guint: filter identifier that can be used with g_dbus_connection_remove_filter().

func (*DBusConnection) Call 

func (connection *DBusConnection) Call(ctx context.Context, busName, objectPath, interfaceName, methodName string, parameters *glib.Variant, replyType *glib.VariantType, flags DBusCallFlags, timeoutMsec int, callback AsyncReadyCallback)

Call: asynchronously invokes the method_name method on the interface_name D-Bus interface on the remote object at object_path owned by bus_name.

If connection is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If reply_type is non-NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a reply_type then any non-NULL return value will be of this type. Unless it’s G_VARIANT_TYPE_UNIT, the reply_type will be a tuple containing one or more values.

If the parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: 

g_dbus_connection_call (connection,
                        "org.freedesktop.StringThings",
                        "/org/freedesktop/StringThings",
                        "org.freedesktop.StringThings",
                        "TwoStrings",
                        g_variant_new ("(ss)",
                                       "Thing One",
                                       "Thing Two"),
                        NULL,
                        G_DBUS_CALL_FLAGS_NONE,
                        -1,
                        NULL,
                        (GAsyncReadyCallback) two_strings_done,
                        NULL);

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_connection_call_finish() to get the result of the operation. See g_dbus_connection_call_sync() for the synchronous version of this function.

If callback is NULL then the D-Bus method call message will be sent with the G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busName (optional): unique or well-known bus name or NULL if connection is not a message bus connection.
  • objectPath: path of remote object.
  • interfaceName d-Bus interface to invoke method on.
  • methodName: name of the method to invoke.
  • parameters (optional) tuple with parameters for the method or NULL if not passing parameters.
  • replyType (optional): expected type of the reply (which will be a tuple), or NULL.
  • flags from the BusCallFlags enumeration.
  • timeoutMsec: timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout.
  • callback (optional) to call when the request is satisfied or NULL if you don't care about the result of the method invocation.

func (*DBusConnection) CallFinish 

func (connection *DBusConnection) CallFinish(res AsyncResulter) (*glib.Variant, error)

CallFinish finishes an operation started with g_dbus_connection_call().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_call().

The function returns the following values:

  • variant: NULL if error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref().

func (*DBusConnection) CallSync 

func (connection *DBusConnection) CallSync(ctx context.Context, busName, objectPath, interfaceName, methodName string, parameters *glib.Variant, replyType *glib.VariantType, flags DBusCallFlags, timeoutMsec int) (*glib.Variant, error)

CallSync: synchronously invokes the method_name method on the interface_name D-Bus interface on the remote object at object_path owned by bus_name.

If connection is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If reply_type is non-NULL then the reply will be checked for having this type and an error will be raised if it does not match. Said another way, if you give a reply_type then any non-NULL return value will be of this type.

If the parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: 

g_dbus_connection_call_sync (connection,
                             "org.freedesktop.StringThings",
                             "/org/freedesktop/StringThings",
                             "org.freedesktop.StringThings",
                             "TwoStrings",
                             g_variant_new ("(ss)",
                                            "Thing One",
                                            "Thing Two"),
                             NULL,
                             G_DBUS_CALL_FLAGS_NONE,
                             -1,
                             NULL,
                             &error);

The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busName (optional): unique or well-known bus name or NULL if connection is not a message bus connection.
  • objectPath: path of remote object.
  • interfaceName d-Bus interface to invoke method on.
  • methodName: name of the method to invoke.
  • parameters (optional) tuple with parameters for the method or NULL if not passing parameters.
  • replyType (optional): expected type of the reply, or NULL.
  • flags from the BusCallFlags enumeration.
  • timeoutMsec: timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout.

The function returns the following values:

  • variant: NULL if error is set. Otherwise a non-floating #GVariant tuple with return values. Free with g_variant_unref().

func (*DBusConnection) Capabilities 

func (connection *DBusConnection) Capabilities() DBusCapabilityFlags

Capabilities gets the capabilities negotiated with the remote peer.

The function returns the following values:

  • dBusCapabilityFlags: zero or more flags from the BusCapabilityFlags enumeration.

func (*DBusConnection) Close 

func (connection *DBusConnection) Close(ctx context.Context, callback AsyncReadyCallback)

Close closes connection. Note that this never causes the process to exit (this might only happen if the other end of a shared message bus connection disconnects, see BusConnection:exit-on-close).

Once the connection is closed, operations such as sending a message will return with the error G_IO_ERROR_CLOSED. Closing a connection will not automatically flush the connection so queued messages may be lost. Use g_dbus_connection_flush() if you need such guarantees.

If connection is already closed, this method fails with G_IO_ERROR_CLOSED.

When connection has been closed, the BusConnection::closed signal is emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that connection was constructed in.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_connection_close_finish() to get the result of the operation. See g_dbus_connection_close_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional) to call when the request is satisfied or NULL if you don't care about the result.

func (*DBusConnection) CloseFinish 

func (connection *DBusConnection) CloseFinish(res AsyncResulter) error

CloseFinish finishes an operation started with g_dbus_connection_close().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_close().

func (*DBusConnection) CloseSync 

func (connection *DBusConnection) CloseSync(ctx context.Context) error

CloseSync: synchronously closes connection. The calling thread is blocked until this is done. See g_dbus_connection_close() for the asynchronous version of this method and more details about what it does.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*DBusConnection) ConnectClosed 

func (connection *DBusConnection) ConnectClosed(f func(remotePeerVanished bool, err error)) coreglib.SignalHandle

ConnectClosed is emitted when the connection is closed.

The cause of this event can be

- If g_dbus_connection_close() is called. In this case remote_peer_vanished is set to FALSE and error is NULL.

- If the remote peer closes the connection. In this case remote_peer_vanished is set to TRUE and error is set.

- If the remote peer sends invalid or malformed data. In this case remote_peer_vanished is set to FALSE and error is set.

Upon receiving this signal, you should give up your reference to connection. You are guaranteed that this signal is emitted only once.

func (*DBusConnection) EmitSignal 

func (connection *DBusConnection) EmitSignal(destinationBusName, objectPath, interfaceName, signalName string, parameters *glib.Variant) error

EmitSignal emits a signal.

If the parameters GVariant is floating, it is consumed.

This can only fail if parameters is not compatible with the D-Bus protocol (G_IO_ERROR_INVALID_ARGUMENT), or if connection has been closed (G_IO_ERROR_CLOSED).

The function takes the following parameters:

  • destinationBusName (optional): unique bus name for the destination for the signal or NULL to emit to all listeners.
  • objectPath: path of remote object.
  • interfaceName d-Bus interface to emit a signal on.
  • signalName: name of the signal to emit.
  • parameters (optional) tuple with parameters for the signal or NULL if not passing parameters.

func (*DBusConnection) ExitOnClose 

func (connection *DBusConnection) ExitOnClose() bool

ExitOnClose gets whether the process is terminated when connection is closed by the remote peer. See BusConnection:exit-on-close for more details.

The function returns the following values:

  • ok: whether the process is terminated when connection is closed by the remote peer.

func (*DBusConnection) ExportActionGroup 

func (connection *DBusConnection) ExportActionGroup(objectPath string, actionGroup ActionGrouper) (uint, error)

ExportActionGroup exports action_group on connection at object_path.

The implemented D-Bus API should be considered private. It is subject to change in the future.

A given object path can only have one action group exported on it. If this constraint is violated, the export will fail and 0 will be returned (with error set accordingly).

You can unexport the action group using g_dbus_connection_unexport_action_group() with the return value of this function.

The thread default main context is taken at the time of this call. All incoming action activations and state change requests are reported from this context. Any changes on the action group that cause it to emit signals must also come from this same context. Since incoming action activations and state change requests are rather likely to cause changes on the action group, this effectively limits a given action group to being exported from only one main context.

The function takes the following parameters:

  • objectPath d-Bus object path.
  • actionGroup: Group.

The function returns the following values:

  • guint: ID of the export (never zero), or 0 in case of failure.

func (*DBusConnection) ExportMenuModel 

func (connection *DBusConnection) ExportMenuModel(objectPath string, menu MenuModeller) (uint, error)

ExportMenuModel exports menu on connection at object_path.

The implemented D-Bus API should be considered private. It is subject to change in the future.

An object path can only have one menu model exported on it. If this constraint is violated, the export will fail and 0 will be returned (with error set accordingly).

Exporting menus with sections containing more than G_MENU_EXPORTER_MAX_SECTION_SIZE items is not supported and results in undefined behavior.

You can unexport the menu model using g_dbus_connection_unexport_menu_model() with the return value of this function.

The function takes the following parameters:

  • objectPath d-Bus object path.
  • menu: Model.

The function returns the following values:

  • guint: ID of the export (never zero), or 0 in case of failure.

func (*DBusConnection) Flags 

func (connection *DBusConnection) Flags() DBusConnectionFlags

Flags gets the flags used to construct this connection.

The function returns the following values:

  • dBusConnectionFlags: zero or more flags from the BusConnectionFlags enumeration.

func (*DBusConnection) Flush 

func (connection *DBusConnection) Flush(ctx context.Context, callback AsyncReadyCallback)

Flush: asynchronously flushes connection, that is, writes all queued outgoing message to the transport and then flushes the transport (using g_output_stream_flush_async()). This is useful in programs that wants to emit a D-Bus signal and then exit immediately. Without flushing the connection, there is no guaranteed that the message has been sent to the networking buffers in the OS kernel.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_connection_flush_finish() to get the result of the operation. See g_dbus_connection_flush_sync() for the synchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional) to call when the request is satisfied or NULL if you don't care about the result.

func (*DBusConnection) FlushFinish 

func (connection *DBusConnection) FlushFinish(res AsyncResulter) error

FlushFinish finishes an operation started with g_dbus_connection_flush().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_flush().

func (*DBusConnection) FlushSync 

func (connection *DBusConnection) FlushSync(ctx context.Context) error

FlushSync: synchronously flushes connection. The calling thread is blocked until this is done. See g_dbus_connection_flush() for the asynchronous version of this method and more details about what it does.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*DBusConnection) GUID 

func (connection *DBusConnection) GUID() string

GUID of the peer performing the role of server when authenticating. See BusConnection:guid for more details.

The function returns the following values:

  • utf8: GUID. Do not free this string, it is owned by connection.

func (*DBusConnection) IsClosed 

func (connection *DBusConnection) IsClosed() bool

IsClosed gets whether connection is closed.

The function returns the following values:

  • ok: TRUE if the connection is closed, FALSE otherwise.

func (*DBusConnection) LastSerial 

func (connection *DBusConnection) LastSerial() uint32

LastSerial retrieves the last serial number assigned to a BusMessage on the current thread. This includes messages sent via both low-level API such as g_dbus_connection_send_message() as well as high-level API such as g_dbus_connection_emit_signal(), g_dbus_connection_call() or g_dbus_proxy_call().

The function returns the following values:

  • guint32: last used serial or zero when no message has been sent within the current thread.

func (*DBusConnection) PeerCredentials 

func (connection *DBusConnection) PeerCredentials() *Credentials

PeerCredentials gets the credentials of the authenticated peer. This will always return NULL unless connection acted as a server (e.g. G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER was passed) when set up and the client passed credentials as part of the authentication process.

In a message bus setup, the message bus is always the server and each application is a client. So this method will always return NULL for message bus clients.

The function returns the following values:

  • credentials (optional) or NULL if not available. Do not free this object, it is owned by connection.

func (*DBusConnection) RegisterObject 

func (connection *DBusConnection) RegisterObject(objectPath string, interfaceInfo *DBusInterfaceInfo, methodCallClosure, getPropertyClosure, setPropertyClosure coreglib.AnyClosure) (uint, error)

RegisterObject: version of g_dbus_connection_register_object() using closures instead of a BusInterfaceVTable for easier binding in other languages.

The function takes the following parameters:

  • objectPath: object path to register at.
  • interfaceInfo: introspection data for the interface.
  • methodCallClosure (optional) for handling incoming method calls.
  • getPropertyClosure (optional) for getting a property.
  • setPropertyClosure (optional) for setting a property.

The function returns the following values:

  • guint: 0 if error is set, otherwise a registration ID (never 0) that can be used with g_dbus_connection_unregister_object() .

func (*DBusConnection) RemoveFilter 

func (connection *DBusConnection) RemoveFilter(filterId uint)

RemoveFilter removes a filter.

Note that since filters run in a different thread, there is a race condition where it is possible that the filter will be running even after calling g_dbus_connection_remove_filter(), so you cannot just free data that the filter might be using. Instead, you should pass a Notify to g_dbus_connection_add_filter(), which will be called when it is guaranteed that the data is no longer needed.

The function takes the following parameters:

  • filterId: identifier obtained from g_dbus_connection_add_filter().

func (*DBusConnection) SendMessage 

func (connection *DBusConnection) SendMessage(message *DBusMessage, flags DBusSendMessageFlags) (uint32, error)

SendMessage: asynchronously sends message to the peer represented by connection.

Unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by connection and set on message via g_dbus_message_set_serial(). If out_serial is not NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

If connection is closed then the operation will fail with G_IO_ERROR_CLOSED. If message is not well-formed, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that message must be unlocked, unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.

The function takes the following parameters:

  • message: BusMessage.
  • flags affecting how the message is sent.

The function returns the following values:

  • outSerial (optional): return location for serial number assigned to message when sending it or NULL.

func (*DBusConnection) SendMessageWithReply 

func (connection *DBusConnection) SendMessageWithReply(ctx context.Context, message *DBusMessage, flags DBusSendMessageFlags, timeoutMsec int, callback AsyncReadyCallback) uint32

SendMessageWithReply: asynchronously sends message to the peer represented by connection.

Unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by connection and set on message via g_dbus_message_set_serial(). If out_serial is not NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

If connection is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If message is not well-formed, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.

Note that message must be unlocked, unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • message: BusMessage.
  • flags affecting how the message is sent.
  • timeoutMsec: timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout.
  • callback (optional) to call when the request is satisfied or NULL if you don't care about the result.

The function returns the following values:

  • outSerial (optional): return location for serial number assigned to message when sending it or NULL.

func (*DBusConnection) SendMessageWithReplyFinish 

func (connection *DBusConnection) SendMessageWithReplyFinish(res AsyncResulter) (*DBusMessage, error)

SendMessageWithReplyFinish finishes an operation started with g_dbus_connection_send_message_with_reply().

Note that error is only set if a local in-process error occurred. That is to say that the returned BusMessage object may be of type G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_connection_send_message_with_reply().

The function returns the following values:

  • dBusMessage: locked BusMessage or NULL if error is set.

func (*DBusConnection) SendMessageWithReplySync 

func (connection *DBusConnection) SendMessageWithReplySync(ctx context.Context, message *DBusMessage, flags DBusSendMessageFlags, timeoutMsec int) (uint32, *DBusMessage, error)

SendMessageWithReplySync: synchronously sends message to the peer represented by connection and blocks the calling thread until a reply is received or the timeout is reached. See g_dbus_connection_send_message_with_reply() for the asynchronous version of this method.

Unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag, the serial number will be assigned by connection and set on message via g_dbus_message_set_serial(). If out_serial is not NULL, then the serial number used will be written to this location prior to submitting the message to the underlying transport. While it has a volatile qualifier, this is a historical artifact and the argument passed to it should not be volatile.

If connection is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If message is not well-formed, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

Note that error is only set if a local in-process error occurred. That is to say that the returned BusMessage object may be of type G_DBUS_MESSAGE_TYPE_ERROR. Use g_dbus_message_to_gerror() to transcode this to a #GError.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

Note that message must be unlocked, unless flags contain the G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • message: BusMessage.
  • flags affecting how the message is sent.
  • timeoutMsec: timeout in milliseconds, -1 to use the default timeout or G_MAXINT for no timeout.

The function returns the following values:

  • outSerial (optional): return location for serial number assigned to message when sending it or NULL.
  • dBusMessage: locked BusMessage that is the reply to message or NULL if error is set.

func (*DBusConnection) SetExitOnClose 

func (connection *DBusConnection) SetExitOnClose(exitOnClose bool)

SetExitOnClose sets whether the process should be terminated when connection is closed by the remote peer. See BusConnection:exit-on-close for more details.

Note that this function should be used with care. Most modern UNIX desktops tie the notion of a user session with the session bus, and expect all of a user's applications to quit when their bus connection goes away. If you are setting exit_on_close to FALSE for the shared session bus connection, you should make sure that your application exits when the user session ends.

The function takes the following parameters:

  • exitOnClose: whether the process should be terminated when connection is closed by the remote peer.

func (*DBusConnection) SignalSubscribe 

func (connection *DBusConnection) SignalSubscribe(sender, interfaceName, member, objectPath, arg0 string, flags DBusSignalFlags, callback DBusSignalCallback) uint

SignalSubscribe subscribes to signals on connection and invokes callback whenever the signal is received. Note that callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from.

If connection is not a message bus connection, sender must be NULL.

If sender is a well-known name note that callback is invoked with the unique name for the owner of sender, not the well-known name as one would expect. This is because the message bus rewrites the name. As such, to avoid certain race conditions, users should be tracking the name owner of the well-known name and use that when processing the received signal.

If one of G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, arg0 is interpreted as part of a namespace or path. The first argument of a signal is matched against that part as specified by D-Bus.

If user_data_free_func is non-NULL, it will be called (in the thread-default main context of the thread you are calling this method from) at some point after user_data is no longer needed. (It is not guaranteed to be called synchronously when the signal is unsubscribed from, and may be called after connection has been destroyed.)

As callback is potentially invoked in a different thread from where it’s emitted, it’s possible for this to happen after g_dbus_connection_signal_unsubscribe() has been called in another thread. Due to this, user_data should have a strong reference which is freed with user_data_free_func, rather than pointing to data whose lifecycle is tied to the signal subscription. For example, if a #GObject is used to store the subscription ID from g_dbus_connection_signal_subscribe(), a strong reference to that #GObject must be passed to user_data, and g_object_unref() passed to user_data_free_func. You are responsible for breaking the resulting reference count cycle by explicitly unsubscribing from the signal when dropping the last external reference to the #GObject. Alternatively, a weak reference may be used.

It is guaranteed that if you unsubscribe from a signal using g_dbus_connection_signal_unsubscribe() from the same thread which made the corresponding g_dbus_connection_signal_subscribe() call, callback will not be invoked after g_dbus_connection_signal_unsubscribe() returns.

The returned subscription identifier is an opaque value which is guaranteed to never be zero.

This function can never fail.

The function takes the following parameters:

  • sender (optional) name to match on (unique or well-known name) or NULL to listen from all senders.
  • interfaceName (optional) d-Bus interface name to match on or NULL to match on all interfaces.
  • member (optional) d-Bus signal name to match on or NULL to match on all signals.
  • objectPath (optional): object path to match on or NULL to match on all object paths.
  • arg0 (optional) contents of first string argument to match on or NULL to match on all kinds of arguments.
  • flags describing how arg0 is used in subscribing to the signal.
  • callback to invoke when there is a signal matching the requested data.

The function returns the following values:

  • guint: subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().

func (*DBusConnection) SignalUnsubscribe 

func (connection *DBusConnection) SignalUnsubscribe(subscriptionId uint)

SignalUnsubscribe unsubscribes from signals.

Note that there may still be D-Bus traffic to process (relating to this signal subscription) in the current thread-default Context after this function has returned. You should continue to iterate the Context until the Notify function passed to g_dbus_connection_signal_subscribe() is called, in order to avoid memory leaks through callbacks queued on the Context after it’s stopped being iterated. Alternatively, any idle source with a priority lower than G_PRIORITY_DEFAULT that was scheduled after unsubscription, also indicates that all resources of this subscription are released.

The function takes the following parameters:

  • subscriptionId: subscription id obtained from g_dbus_connection_signal_subscribe().

func (*DBusConnection) StartMessageProcessing 

func (connection *DBusConnection) StartMessageProcessing()

StartMessageProcessing: if connection was created with G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method starts processing messages. Does nothing on if connection wasn't created with this flag or if the method has already been called.

func (*DBusConnection) Stream 

func (connection *DBusConnection) Stream() IOStreamer

Stream gets the underlying stream used for IO.

While the BusConnection is active, it will interact with this stream from a worker thread, so it is not safe to interact with the stream directly.

The function returns the following values:

  • ioStream: stream used for IO.

func (*DBusConnection) UnexportActionGroup 

func (connection *DBusConnection) UnexportActionGroup(exportId uint)

UnexportActionGroup reverses the effect of a previous call to g_dbus_connection_export_action_group().

It is an error to call this function with an ID that wasn't returned from g_dbus_connection_export_action_group() or to call it with the same ID more than once.

The function takes the following parameters:

  • exportId: ID from g_dbus_connection_export_action_group().

func (*DBusConnection) UnexportMenuModel 

func (connection *DBusConnection) UnexportMenuModel(exportId uint)

UnexportMenuModel reverses the effect of a previous call to g_dbus_connection_export_menu_model().

It is an error to call this function with an ID that wasn't returned from g_dbus_connection_export_menu_model() or to call it with the same ID more than once.

The function takes the following parameters:

  • exportId: ID from g_dbus_connection_export_menu_model().

func (*DBusConnection) UniqueName 

func (connection *DBusConnection) UniqueName() string

UniqueName gets the unique name of connection as assigned by the message bus. This can also be used to figure out if connection is a message bus connection.

The function returns the following values:

  • utf8 (optional): unique name or NULL if connection is not a message bus connection. Do not free this string, it is owned by connection.

func (*DBusConnection) UnregisterObject 

func (connection *DBusConnection) UnregisterObject(registrationId uint) bool

UnregisterObject unregisters an object.

The function takes the following parameters:

  • registrationId: registration id obtained from g_dbus_connection_register_object().

The function returns the following values:

  • ok: TRUE if the object was unregistered, FALSE otherwise.

func (*DBusConnection) UnregisterSubtree 

func (connection *DBusConnection) UnregisterSubtree(registrationId uint) bool

UnregisterSubtree unregisters a subtree.

The function takes the following parameters:

  • registrationId: subtree registration id obtained from g_dbus_connection_register_subtree().

The function returns the following values:

  • ok: TRUE if the subtree was unregistered, FALSE otherwise.

type DBusConnectionFlags 

type DBusConnectionFlags C.guint

DBusConnectionFlags flags used when creating a new BusConnection. 

const (
	// DBusConnectionFlagsNone: no flags set.
	DBusConnectionFlagsNone DBusConnectionFlags = 0b0
	// DBusConnectionFlagsAuthenticationClient: perform authentication against
	// server.
	DBusConnectionFlagsAuthenticationClient DBusConnectionFlags = 0b1
	// DBusConnectionFlagsAuthenticationServer: perform authentication against
	// client.
	DBusConnectionFlagsAuthenticationServer DBusConnectionFlags = 0b10
	// DBusConnectionFlagsAuthenticationAllowAnonymous: when authenticating as a
	// server, allow the anonymous authentication method.
	DBusConnectionFlagsAuthenticationAllowAnonymous DBusConnectionFlags = 0b100
	// DBusConnectionFlagsMessageBusConnection pass this flag if connecting to
	// a peer that is a message bus. This means that the Hello() method will be
	// invoked as part of the connection setup.
	DBusConnectionFlagsMessageBusConnection DBusConnectionFlags = 0b1000
	// DBusConnectionFlagsDelayMessageProcessing: if set, processing of D-Bus
	// messages is delayed until g_dbus_connection_start_message_processing() is
	// called.
	DBusConnectionFlagsDelayMessageProcessing DBusConnectionFlags = 0b10000
	// DBusConnectionFlagsAuthenticationRequireSameUser: when authenticating as
	// a server, require the UID of the peer to be the same as the UID of the
	// server. (Since: 2.68).
	DBusConnectionFlagsAuthenticationRequireSameUser DBusConnectionFlags = 0b100000
	// DBusConnectionFlagsCrossNamespace: when authenticating, try to use
	// protocols that work across a Linux user namespace boundary, even if this
	// reduces interoperability with older D-Bus implementations. This currently
	// affects client-side EXTERNAL authentication, for which this flag makes
	// connections to a server in another user namespace succeed, but causes
	// a deadlock when connecting to a GDBus server older than 2.73.3. Since:
	// 2.74.
	DBusConnectionFlagsCrossNamespace DBusConnectionFlags = 0b1000000
)

func (DBusConnectionFlags) Has 

func (d DBusConnectionFlags) Has(other DBusConnectionFlags) bool

Has returns true if d contains other.

func (DBusConnectionFlags) String 

func (d DBusConnectionFlags) String() string

String returns the names in string for DBusConnectionFlags.

type DBusError 

type DBusError C.gint

DBusError: error codes for the G_DBUS_ERROR error domain. 

const (
	// DBusErrorFailed: generic error; "something went wrong" - see the error
	// message for more.
	DBusErrorFailed DBusError = iota
	// DBusErrorNoMemory: there was not enough memory to complete an operation.
	DBusErrorNoMemory
	// DBusErrorServiceUnknown bus doesn't know how to launch a service to
	// supply the bus name you wanted.
	DBusErrorServiceUnknown
	// DBusErrorNameHasNoOwner bus name you referenced doesn't exist (i.e.
	// no application owns it).
	DBusErrorNameHasNoOwner
	// DBusErrorNoReply: no reply to a message expecting one, usually means a
	// timeout occurred.
	DBusErrorNoReply
	// DBusErrorIOError: something went wrong reading or writing to a socket,
	// for example.
	DBusErrorIOError
	// DBusErrorBadAddress d-Bus bus address was malformed.
	DBusErrorBadAddress
	// DBusErrorNotSupported: requested operation isn't supported (like ENOSYS
	// on UNIX).
	DBusErrorNotSupported
	// DBusErrorLimitsExceeded: some limited resource is exhausted.
	DBusErrorLimitsExceeded
	// DBusErrorAccessDenied: security restrictions don't allow doing what
	// you're trying to do.
	DBusErrorAccessDenied
	// DBusErrorAuthFailed: authentication didn't work.
	DBusErrorAuthFailed
	// DBusErrorNoServer: unable to connect to server (probably caused by
	// ECONNREFUSED on a socket).
	DBusErrorNoServer
	// DBusErrorTimeout: certain timeout errors, possibly ETIMEDOUT on a socket.
	// Note that G_DBUS_ERROR_NO_REPLY is used for message reply timeouts.
	// Warning: this is confusingly-named given that G_DBUS_ERROR_TIMED_OUT also
	// exists. We can't fix it for compatibility reasons so just be careful.
	DBusErrorTimeout
	// DBusErrorNoNetwork: no network access (probably ENETUNREACH on a socket).
	DBusErrorNoNetwork
	// DBusErrorAddressInUse: can't bind a socket since its address is in use
	// (i.e. EADDRINUSE).
	DBusErrorAddressInUse
	// DBusErrorDisconnected: connection is disconnected and you're trying to
	// use it.
	DBusErrorDisconnected
	// DBusErrorInvalidArgs: invalid arguments passed to a method call.
	DBusErrorInvalidArgs
	// DBusErrorFileNotFound: missing file.
	DBusErrorFileNotFound
	// DBusErrorFileExists: existing file and the operation you're using does
	// not silently overwrite.
	DBusErrorFileExists
	// DBusErrorUnknownMethod: method name you invoked isn't known by the object
	// you invoked it on.
	DBusErrorUnknownMethod
	// DBusErrorTimedOut: certain timeout errors, e.g. while starting a service.
	// Warning: this is confusingly-named given that G_DBUS_ERROR_TIMEOUT also
	// exists. We can't fix it for compatibility reasons so just be careful.
	DBusErrorTimedOut
	// DBusErrorMatchRuleNotFound: tried to remove or modify a match rule that
	// didn't exist.
	DBusErrorMatchRuleNotFound
	// DBusErrorMatchRuleInvalid: match rule isn't syntactically valid.
	DBusErrorMatchRuleInvalid
	// DBusErrorSpawnExecFailed: while starting a new process, the exec() call
	// failed.
	DBusErrorSpawnExecFailed
	// DBusErrorSpawnForkFailed: while starting a new process, the fork() call
	// failed.
	DBusErrorSpawnForkFailed
	// DBusErrorSpawnChildExited: while starting a new process, the child exited
	// with a status code.
	DBusErrorSpawnChildExited
	// DBusErrorSpawnChildSignaled: while starting a new process, the child
	// exited on a signal.
	DBusErrorSpawnChildSignaled
	// DBusErrorSpawnFailed: while starting a new process, something went wrong.
	DBusErrorSpawnFailed
	// DBusErrorSpawnSetupFailed: we failed to setup the environment correctly.
	DBusErrorSpawnSetupFailed
	// DBusErrorSpawnConfigInvalid: we failed to setup the config parser
	// correctly.
	DBusErrorSpawnConfigInvalid
	// DBusErrorSpawnServiceInvalid bus name was not valid.
	DBusErrorSpawnServiceInvalid
	// DBusErrorSpawnServiceNotFound: service file not found in system-services
	// directory.
	DBusErrorSpawnServiceNotFound
	// DBusErrorSpawnPermissionsInvalid permissions are incorrect on the setuid
	// helper.
	DBusErrorSpawnPermissionsInvalid
	// DBusErrorSpawnFileInvalid: service file invalid (Name, User or Exec
	// missing).
	DBusErrorSpawnFileInvalid
	// DBusErrorSpawnNoMemory: tried to get a UNIX process ID and it wasn't
	// available.
	DBusErrorSpawnNoMemory
	// DBusErrorUnixProcessIDUnknown: tried to get a UNIX process ID and it
	// wasn't available.
	DBusErrorUnixProcessIDUnknown
	// DBusErrorInvalidSignature: type signature is not valid.
	DBusErrorInvalidSignature
	// DBusErrorInvalidFileContent: file contains invalid syntax or is otherwise
	// broken.
	DBusErrorInvalidFileContent
	// DBusErrorSelinuxSecurityContextUnknown: asked for SELinux security
	// context and it wasn't available.
	DBusErrorSelinuxSecurityContextUnknown
	// DBusErrorAdtAuditDataUnknown: asked for ADT audit data and it wasn't
	// available.
	DBusErrorAdtAuditDataUnknown
	// DBusErrorObjectPathInUse there's already an object with the requested
	// object path.
	DBusErrorObjectPathInUse
	// DBusErrorUnknownObject: object you invoked a method on isn't known.
	// Since 2.42.
	DBusErrorUnknownObject
	// DBusErrorUnknownInterface: interface you invoked a method on isn't known
	// by the object. Since 2.42.
	DBusErrorUnknownInterface
	// DBusErrorUnknownProperty: property you tried to access isn't known by the
	// object. Since 2.42.
	DBusErrorUnknownProperty
	// DBusErrorPropertyReadOnly: property you tried to set is read-only.
	// Since 2.42.
	DBusErrorPropertyReadOnly
)

func (DBusError) String 

func (d DBusError) String() string

String returns the name in string for DBusError.

type DBusErrorEntry 

type DBusErrorEntry struct {
	// contains filtered or unexported fields
}

DBusErrorEntry: struct used in g_dbus_error_register_error_domain().

An instance of this type is always passed by reference.

func (*DBusErrorEntry) DBusErrorName 

func (d *DBusErrorEntry) DBusErrorName() string

DBusErrorName d-Bus error name to associate with error_code.

func (*DBusErrorEntry) ErrorCode 

func (d *DBusErrorEntry) ErrorCode() int

ErrorCode: error code.

func (*DBusErrorEntry) SetErrorCode 

func (d *DBusErrorEntry) SetErrorCode(errorCode int)

ErrorCode: error code.

type DBusInterface 

type DBusInterface struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusInterface: base type for D-Bus interfaces.

The GDBusInterface type is the base type for D-Bus interfaces both on the service side (see gio.DBusInterfaceSkeleton) and client side (see gio.DBusProxy).

DBusInterface wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DBusInterface) GetObject 

func (interface_ *DBusInterface) GetObject() *DBusObject

GetObject gets the BusObject that interface_ belongs to, if any.

The function returns the following values:

  • dBusObject (optional) or NULL. The returned reference should be freed with g_object_unref().

func (*DBusInterface) Info 

func (interface_ *DBusInterface) Info() *DBusInterfaceInfo

Info gets D-Bus introspection information for the D-Bus interface implemented by interface_.

The function returns the following values:

  • dBusInterfaceInfo Do not free.

func (*DBusInterface) SetObject 

func (interface_ *DBusInterface) SetObject(object DBusObjector)

SetObject sets the BusObject for interface_ to object.

Note that interface_ will hold a weak reference to object.

The function takes the following parameters:

  • object (optional) or NULL.

type DBusInterfaceGetPropertyFunc 

type DBusInterfaceGetPropertyFunc func(connection *DBusConnection, sender, objectPath, interfaceName, propertyName string) (err error, variant *glib.Variant)

DBusInterfaceGetPropertyFunc: type of the get_property function in BusInterfaceVTable.

type DBusInterfaceIface added in v0.0.5 

type DBusInterfaceIface struct {
	// contains filtered or unexported fields
}

DBusInterfaceIface: base type for D-Bus interfaces.

An instance of this type is always passed by reference.

type DBusInterfaceInfo 

type DBusInterfaceInfo struct {
	// contains filtered or unexported fields
}

DBusInterfaceInfo: information about a D-Bus interface.

An instance of this type is always passed by reference.

func (*DBusInterfaceInfo) Annotations 

func (d *DBusInterfaceInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusInterfaceInfo) CacheBuild 

func (info *DBusInterfaceInfo) CacheBuild()

CacheBuild builds a lookup-cache to speed up g_dbus_interface_info_lookup_method(), g_dbus_interface_info_lookup_signal() and g_dbus_interface_info_lookup_property().

If this has already been called with info, the existing cache is used and its use count is increased.

Note that info cannot be modified until g_dbus_interface_info_cache_release() is called.

func (*DBusInterfaceInfo) CacheRelease 

func (info *DBusInterfaceInfo) CacheRelease()

CacheRelease decrements the usage count for the cache for info built by g_dbus_interface_info_cache_build() (if any) and frees the resources used by the cache if the usage count drops to zero.

func (*DBusInterfaceInfo) LookupMethod 

func (info *DBusInterfaceInfo) LookupMethod(name string) *DBusMethodInfo

LookupMethod looks up information about a method.

The cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on info.

The function takes the following parameters:

  • name d-Bus method name (typically in CamelCase).

The function returns the following values:

  • dBusMethodInfo (optional) or NULL if not found. Do not free, it is owned by info.

func (*DBusInterfaceInfo) LookupProperty 

func (info *DBusInterfaceInfo) LookupProperty(name string) *DBusPropertyInfo

LookupProperty looks up information about a property.

The cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on info.

The function takes the following parameters:

  • name d-Bus property name (typically in CamelCase).

The function returns the following values:

  • dBusPropertyInfo (optional) or NULL if not found. Do not free, it is owned by info.

func (*DBusInterfaceInfo) LookupSignal 

func (info *DBusInterfaceInfo) LookupSignal(name string) *DBusSignalInfo

LookupSignal looks up information about a signal.

The cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on info.

The function takes the following parameters:

  • name d-Bus signal name (typically in CamelCase).

The function returns the following values:

  • dBusSignalInfo (optional) or NULL if not found. Do not free, it is owned by info.

func (*DBusInterfaceInfo) Methods 

func (d *DBusInterfaceInfo) Methods() []*DBusMethodInfo

Methods: pointer to a NULL-terminated array of pointers to BusMethodInfo structures or NULL if there are no methods.

func (*DBusInterfaceInfo) Name 

func (d *DBusInterfaceInfo) Name() string

Name: name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties".

func (*DBusInterfaceInfo) Properties 

func (d *DBusInterfaceInfo) Properties() []*DBusPropertyInfo

Properties: pointer to a NULL-terminated array of pointers to BusPropertyInfo structures or NULL if there are no properties.

func (*DBusInterfaceInfo) RefCount 

func (d *DBusInterfaceInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusInterfaceInfo) SetRefCount 

func (d *DBusInterfaceInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

func (*DBusInterfaceInfo) Signals 

func (d *DBusInterfaceInfo) Signals() []*DBusSignalInfo

Signals: pointer to a NULL-terminated array of pointers to BusSignalInfo structures or NULL if there are no signals.

type DBusInterfaceMethodCallFunc 

type DBusInterfaceMethodCallFunc func(connection *DBusConnection, sender, objectPath, interfaceName, methodName string, parameters *glib.Variant, invocation *DBusMethodInvocation)

DBusInterfaceMethodCallFunc: type of the method_call function in BusInterfaceVTable.

type DBusInterfaceSetPropertyFunc 

type DBusInterfaceSetPropertyFunc func(connection *DBusConnection, sender, objectPath, interfaceName, propertyName string, value *glib.Variant) (err error, ok bool)

DBusInterfaceSetPropertyFunc: type of the set_property function in BusInterfaceVTable.

type DBusInterfaceSkeleton 

type DBusInterfaceSkeleton struct {
	*coreglib.Object

	DBusInterface
	// contains filtered or unexported fields
}

DBusInterfaceSkeleton: abstract base class for D-Bus interfaces on the service side.

func BaseDBusInterfaceSkeleton 

func BaseDBusInterfaceSkeleton(obj DBusInterfaceSkeletonner) *DBusInterfaceSkeleton

BaseDBusInterfaceSkeleton returns the underlying base object.

func (*DBusInterfaceSkeleton) ConnectGAuthorizeMethod 

func (interface_ *DBusInterfaceSkeleton) ConnectGAuthorizeMethod(f func(invocation *DBusMethodInvocation) (ok bool)) coreglib.SignalHandle

ConnectGAuthorizeMethod is emitted when a method is invoked by a remote caller and used to determine if the method call is authorized.

Note that this signal is emitted in a thread dedicated to handling the method call so handlers are allowed to perform blocking IO. This means that it is appropriate to call e.g. polkit_authority_check_authorization_sync() (http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync) with the POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION (http://hal.freedesktop.org/docs/polkit/PolkitAuthority.htmlLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS) flag set.

If FALSE is returned then no further handlers are run and the signal handler must take a reference to invocation and finish handling the call (e.g. return an error via g_dbus_method_invocation_return_error()).

Otherwise, if TRUE is returned, signal emission continues. If no handlers return FALSE, then the method is dispatched. If interface has an enclosing BusObjectSkeleton, then the BusObjectSkeleton::authorize-method signal handlers run before the handlers for this signal.

The default class handler just returns TRUE.

Please note that the common case is optimized: if no signals handlers are connected and the default class handler isn't overridden (for both interface and the enclosing BusObjectSkeleton, if any) and BusInterfaceSkeleton:g-flags does not have the G_DBUS_INTERFACE_SKELETON_FLAGS_HANDLE_METHOD_INVOCATIONS_IN_THREAD flags set, no dedicated thread is ever used and the call will be handled in the same thread as the object that interface belongs to was exported in.

func (*DBusInterfaceSkeleton) Connection 

func (interface_ *DBusInterfaceSkeleton) Connection() *DBusConnection

Connection gets the first connection that interface_ is exported on, if any.

The function returns the following values:

  • dBusConnection (optional) or NULL if interface_ is not exported anywhere. Do not free, the object belongs to interface_.

func (*DBusInterfaceSkeleton) Connections 

func (interface_ *DBusInterfaceSkeleton) Connections() []*DBusConnection

Connections gets a list of the connections that interface_ is exported on.

The function returns the following values:

  • list of all the connections that interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

func (*DBusInterfaceSkeleton) Export 

func (interface_ *DBusInterfaceSkeleton) Export(connection *DBusConnection, objectPath string) error

Export exports interface_ at object_path on connection.

This can be called multiple times to export the same interface_ onto multiple connections however the object_path provided must be the same for all connections.

Use g_dbus_interface_skeleton_unexport() to unexport the object.

The function takes the following parameters:

  • connection to export interface_ on.
  • objectPath: path to export the interface at.

func (*DBusInterfaceSkeleton) Flags 

func (interface_ *DBusInterfaceSkeleton) Flags() DBusInterfaceSkeletonFlags

Flags gets the BusInterfaceSkeletonFlags that describes what the behavior of interface_.

The function returns the following values:

  • dBusInterfaceSkeletonFlags: one or more flags from the BusInterfaceSkeletonFlags enumeration.

func (*DBusInterfaceSkeleton) Flush 

func (interface_ *DBusInterfaceSkeleton) Flush()

Flush: if interface_ has outstanding changes, request for these changes to be emitted immediately.

For example, an exported D-Bus interface may queue up property changes and emit the org.freedesktop.DBus.Properties.PropertiesChanged signal later (e.g. in an idle handler). This technique is useful for collapsing multiple property changes into one.

func (*DBusInterfaceSkeleton) HasConnection 

func (interface_ *DBusInterfaceSkeleton) HasConnection(connection *DBusConnection) bool

HasConnection checks if interface_ is exported on connection.

The function takes the following parameters:

  • connection: BusConnection.

The function returns the following values:

  • ok: TRUE if interface_ is exported on connection, FALSE otherwise.

func (*DBusInterfaceSkeleton) Info 

func (interface_ *DBusInterfaceSkeleton) Info() *DBusInterfaceInfo

Info gets D-Bus introspection information for the D-Bus interface implemented by interface_.

The function returns the following values:

  • dBusInterfaceInfo (never NULL). Do not free.

func (*DBusInterfaceSkeleton) ObjectPath 

func (interface_ *DBusInterfaceSkeleton) ObjectPath() string

ObjectPath gets the object path that interface_ is exported on, if any.

The function returns the following values:

  • utf8 (optional): string owned by interface_ or NULL if interface_ is not exported anywhere. Do not free, the string belongs to interface_.

func (*DBusInterfaceSkeleton) Properties 

func (interface_ *DBusInterfaceSkeleton) Properties() *glib.Variant

Properties gets all D-Bus properties for interface_.

The function returns the following values:

  • variant of type ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. Free with g_variant_unref().

func (*DBusInterfaceSkeleton) SetFlags 

func (interface_ *DBusInterfaceSkeleton) SetFlags(flags DBusInterfaceSkeletonFlags)

SetFlags sets flags describing what the behavior of skeleton should be.

The function takes the following parameters:

  • flags flags from the BusInterfaceSkeletonFlags enumeration.

func (*DBusInterfaceSkeleton) Unexport 

func (interface_ *DBusInterfaceSkeleton) Unexport()

Unexport stops exporting interface_ on all connections it is exported on.

To unexport interface_ from only a single connection, use g_dbus_interface_skeleton_unexport_from_connection().

func (*DBusInterfaceSkeleton) UnexportFromConnection 

func (interface_ *DBusInterfaceSkeleton) UnexportFromConnection(connection *DBusConnection)

UnexportFromConnection stops exporting interface_ on connection.

To stop exporting on all connections the interface is exported on, use g_dbus_interface_skeleton_unexport().

The function takes the following parameters:

  • connection: BusConnection.

func (*DBusInterfaceSkeleton) Vtable added in v0.3.0 

func (interface_ *DBusInterfaceSkeleton) Vtable() *DBusInterfaceVTable

Vtable gets the interface vtable for the D-Bus interface implemented by interface_. The returned function pointers should expect interface_ itself to be passed as user_data.

The function returns the following values:

  • dBusInterfaceVTable: vtable of the D-Bus interface implemented by the skeleton.

type DBusInterfaceSkeletonClass added in v0.0.5 

type DBusInterfaceSkeletonClass struct {
	// contains filtered or unexported fields
}

DBusInterfaceSkeletonClass class structure for BusInterfaceSkeleton.

An instance of this type is always passed by reference.

type DBusInterfaceSkeletonFlags 

type DBusInterfaceSkeletonFlags C.guint

DBusInterfaceSkeletonFlags flags describing the behavior of a BusInterfaceSkeleton instance. 

const (
	// DBusInterfaceSkeletonFlagsNone: no flags set.
	DBusInterfaceSkeletonFlagsNone DBusInterfaceSkeletonFlags = 0b0
	// DBusInterfaceSkeletonFlagsHandleMethodInvocationsInThread: each method
	// invocation is handled in a thread dedicated to the invocation. This means
	// that the method implementation can use blocking IO without blocking any
	// other part of the process. It also means that the method implementation
	// must use locking to access data structures used by other threads.
	DBusInterfaceSkeletonFlagsHandleMethodInvocationsInThread DBusInterfaceSkeletonFlags = 0b1
)

func (DBusInterfaceSkeletonFlags) Has 

func (d DBusInterfaceSkeletonFlags) Has(other DBusInterfaceSkeletonFlags) bool

Has returns true if d contains other.

func (DBusInterfaceSkeletonFlags) String 

func (d DBusInterfaceSkeletonFlags) String() string

String returns the names in string for DBusInterfaceSkeletonFlags.

type DBusInterfaceSkeletonOverrides added in v0.0.5 

type DBusInterfaceSkeletonOverrides struct {
	// Flush: if interface_ has outstanding changes, request for these changes
	// to be emitted immediately.
	//
	// For example, an exported D-Bus interface may queue up property changes
	// and emit the org.freedesktop.DBus.Properties.PropertiesChanged signal
	// later (e.g. in an idle handler). This technique is useful for collapsing
	// multiple property changes into one.
	Flush func()
	// GAuthorizeMethod: signal class handler for the
	// BusInterfaceSkeleton::g-authorize-method signal.
	GAuthorizeMethod func(invocation *DBusMethodInvocation) bool
	// Info gets D-Bus introspection information for the D-Bus interface
	// implemented by interface_.
	//
	// The function returns the following values:
	//
	//   - dBusInterfaceInfo (never NULL). Do not free.
	Info func() *DBusInterfaceInfo
	// Properties gets all D-Bus properties for interface_.
	//
	// The function returns the following values:
	//
	//   - variant of type ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. Free with
	//     g_variant_unref().
	Properties func() *glib.Variant
	// Vtable gets the interface vtable for the D-Bus interface implemented
	// by interface_. The returned function pointers should expect interface_
	// itself to be passed as user_data.
	//
	// The function returns the following values:
	//
	//   - dBusInterfaceVTable: vtable of the D-Bus interface implemented by the
	//     skeleton.
	Vtable func() *DBusInterfaceVTable
}

DBusInterfaceSkeletonOverrides contains methods that are overridable.

type DBusInterfaceSkeletonner 

type DBusInterfaceSkeletonner interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

DBusInterfaceSkeletonner describes types inherited from class DBusInterfaceSkeleton.

To get the original type, the caller must assert this to an interface or another type.

type DBusInterfaceVTable 

type DBusInterfaceVTable struct {
	// contains filtered or unexported fields
}

DBusInterfaceVTable: virtual table for handling properties and method calls for a D-Bus interface.

Since 2.38, if you want to handle getting/setting D-Bus properties asynchronously, give NULL as your get_property() or set_property() function. The D-Bus call will be directed to your method_call function, with the provided interface_name set to "org.freedesktop.DBus.Properties".

Ownership of the BusMethodInvocation object passed to the method_call() function is transferred to your handler; you must call one of the methods of BusMethodInvocation to return a reply (possibly empty), or an error. These functions also take ownership of the passed-in invocation object, so unless the invocation object has otherwise been referenced, it will be then be freed. Calling one of these functions may be done within your method_call() implementation but it also can be done at a later point to handle the method asynchronously.

The usual checks on the validity of the calls is performed. For Get calls, an error is automatically returned if the property does not exist or the permissions do not allow access. The same checks are performed for Set calls, and the provided value is also checked for being the correct type.

For both Get and Set calls, the BusMethodInvocation passed to the method_call handler can be queried with g_dbus_method_invocation_get_property_info() to get a pointer to the BusPropertyInfo of the property.

If you have readable properties specified in your interface info, you must ensure that you either provide a non-NULL get_property() function or provide implementations of both the Get and GetAll methods on org.freedesktop.DBus.Properties interface in your method_call function. Note that the required return type of the Get call is (v), not the type of the property. GetAll expects a return value of type a{sv}.

If you have writable properties specified in your interface info, you must ensure that you either provide a non-NULL set_property() function or provide an implementation of the Set call. If implementing the call, you must return the value of type G_VARIANT_TYPE_UNIT.

An instance of this type is always passed by reference.

type DBusInterfacer 

type DBusInterfacer interface {
	coreglib.Objector

	// GetObject gets the BusObject that interface_ belongs to, if any.
	GetObject() *DBusObject
	// Info gets D-Bus introspection information for the D-Bus interface
	// implemented by interface_.
	Info() *DBusInterfaceInfo
	// SetObject sets the BusObject for interface_ to object.
	SetObject(object DBusObjector)
}

DBusInterfacer describes DBusInterface's interface methods.

type DBusMenuModel 

type DBusMenuModel struct {
	MenuModel
	// contains filtered or unexported fields
}

DBusMenuModel: GDBusMenuModel is an implementation of gio.MenuModel that can be used as a proxy for a menu model that is exported over D-Bus with gio.DBusConnection.ExportMenuModel().

func DBusMenuModelGet 

func DBusMenuModelGet(connection *DBusConnection, busName, objectPath string) *DBusMenuModel

DBusMenuModelGet obtains a BusMenuModel for the menu model which is exported at the given bus_name and object_path.

The thread default main context is taken at the time of this call. All signals on the menu model (and any linked models) are reported with respect to this context. All calls on the returned menu model (and linked models) must also originate from this same context, with the thread default main context unchanged.

The function takes the following parameters:

  • connection: BusConnection.
  • busName (optional) bus name which exports the menu model or NULL if connection is not a message bus connection.
  • objectPath: object path at which the menu model is exported.

The function returns the following values:

  • dBusMenuModel object. Free with g_object_unref().

type DBusMessage 

type DBusMessage struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusMessage: type for representing D-Bus messages that can be sent or received on a gio.DBusConnection.

func NewDBusMessage 

func NewDBusMessage() *DBusMessage

NewDBusMessage creates a new empty BusMessage.

The function returns the following values:

  • dBusMessage Free with g_object_unref().

func NewDBusMessageFromBlob 

func NewDBusMessageFromBlob(blob []byte, capabilities DBusCapabilityFlags) (*DBusMessage, error)

NewDBusMessageFromBlob creates a new BusMessage from the data stored at blob. The byte order that the message was in can be retrieved using g_dbus_message_get_byte_order().

If the blob cannot be parsed, contains invalid fields, or contains invalid headers, G_IO_ERROR_INVALID_ARGUMENT will be returned.

The function takes the following parameters:

  • blob representing a binary D-Bus message.
  • capabilities describing what protocol features are supported.

The function returns the following values:

  • dBusMessage: new BusMessage or NULL if error is set. Free with g_object_unref().

func NewDBusMessageMethodCall 

func NewDBusMessageMethodCall(name, path, interface_, method string) *DBusMessage

NewDBusMessageMethodCall creates a new BusMessage for a method call.

The function takes the following parameters:

  • name (optional): valid D-Bus name or NULL.
  • path: valid object path.
  • interface_ (optional): valid D-Bus interface name or NULL.
  • method: valid method name.

The function returns the following values:

  • dBusMessage Free with g_object_unref().

func NewDBusMessageSignal 

func NewDBusMessageSignal(path, interface_, signal string) *DBusMessage

NewDBusMessageSignal creates a new BusMessage for a signal emission.

The function takes the following parameters:

  • path: valid object path.
  • interface_: valid D-Bus interface name.
  • signal: valid signal name.

The function returns the following values:

  • dBusMessage Free with g_object_unref().

func (*DBusMessage) Arg0 

func (message *DBusMessage) Arg0() string

Arg0: convenience to get the first item in the body of message.

See gio.DBusMessage.GetArg0Path() for returning object-path-typed arg0 values.

The function returns the following values:

  • utf8 (optional): string item or NULL if the first item in the body of message is not a string.

func (*DBusMessage) Arg0Path added in v0.3.0 

func (message *DBusMessage) Arg0Path() string

Arg0Path: convenience to get the first item in the body of message.

See gio.DBusMessage.GetArg0() for returning string-typed arg0 values.

The function returns the following values:

  • utf8 (optional): object path item or NULL if the first item in the body of message is not an object path.

func (*DBusMessage) Body 

func (message *DBusMessage) Body() *glib.Variant

Body gets the body of a message.

The function returns the following values:

  • variant (optional) or NULL if the body is empty. Do not free, it is owned by message.

func (*DBusMessage) ByteOrder 

func (message *DBusMessage) ByteOrder() DBusMessageByteOrder

ByteOrder gets the byte order of message.

The function returns the following values:

  • dBusMessageByteOrder: byte order.

func (*DBusMessage) Copy 

func (message *DBusMessage) Copy() (*DBusMessage, error)

Copy copies message. The copy is a deep copy and the returned BusMessage is completely identical except that it is guaranteed to not be locked.

This operation can fail if e.g. message contains file descriptors and the per-process or system-wide open files limit is reached.

The function returns the following values:

  • dBusMessage: new BusMessage or NULL if error is set. Free with g_object_unref().

func (*DBusMessage) Destination 

func (message *DBusMessage) Destination() string

Destination: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) ErrorName 

func (message *DBusMessage) ErrorName() string

ErrorName: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) Flags 

func (message *DBusMessage) Flags() DBusMessageFlags

Flags gets the flags for message.

The function returns the following values:

  • dBusMessageFlags flags that are set (typically values from the BusMessageFlags enumeration bitwise ORed together).

func (*DBusMessage) Header 

func (message *DBusMessage) Header(headerField DBusMessageHeaderField) *glib.Variant

Header gets a header field on message.

The caller is responsible for checking the type of the returned #GVariant matches what is expected.

The function takes the following parameters:

  • headerField: 8-bit unsigned integer (typically a value from the BusMessageHeaderField enumeration).

The function returns the following values:

  • variant (optional) with the value if the header was found, NULL otherwise. Do not free, it is owned by message.

func (*DBusMessage) HeaderFields 

func (message *DBusMessage) HeaderFields() []byte

HeaderFields gets an array of all header fields on message that are set.

The function returns the following values:

  • guint8s: array of header fields terminated by G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free().

func (*DBusMessage) Interface 

func (message *DBusMessage) Interface() string

Interface: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) Lock 

func (message *DBusMessage) Lock()

Lock: if message is locked, does nothing. Otherwise locks the message.

func (*DBusMessage) Locked 

func (message *DBusMessage) Locked() bool

Locked checks whether message is locked. To monitor changes to this value, conncet to the #GObject::notify signal to listen for changes on the BusMessage:locked property.

The function returns the following values:

  • ok: TRUE if message is locked, FALSE otherwise.

func (*DBusMessage) Member 

func (message *DBusMessage) Member() string

Member: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) MessageType 

func (message *DBusMessage) MessageType() DBusMessageType

MessageType gets the type of message.

The function returns the following values:

  • dBusMessageType: 8-bit unsigned integer (typically a value from the BusMessageType enumeration).

func (*DBusMessage) NewMethodErrorLiteral 

func (methodCallMessage *DBusMessage) NewMethodErrorLiteral(errorName, errorMessage string) *DBusMessage

NewMethodErrorLiteral creates a new BusMessage that is an error reply to method_call_message.

The function takes the following parameters:

  • errorName: valid D-Bus error name.
  • errorMessage d-Bus error message.

The function returns the following values:

  • dBusMessage Free with g_object_unref().

func (*DBusMessage) NewMethodReply 

func (methodCallMessage *DBusMessage) NewMethodReply() *DBusMessage

NewMethodReply creates a new BusMessage that is a reply to method_call_message.

The function returns the following values:

  • dBusMessage Free with g_object_unref().

func (*DBusMessage) Path 

func (message *DBusMessage) Path() string

Path: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) Print 

func (message *DBusMessage) Print(indent uint) string

Print produces a human-readable multi-line description of message.

The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: 

Flags:   none
Version: 0
Serial:  4
Headers:
  path -> objectpath '/org/gtk/GDBus/TestObject'
  interface -> 'org.gtk.GDBus.TestInterface'
  member -> 'GimmeStdout'
  destination -> ':1.146'
Body: ()
UNIX File Descriptors:
  (none)

or 

Flags:   no-reply-expected
Version: 0
Serial:  477
Headers:
  reply-serial -> uint32 4
  destination -> ':1.159'
  sender -> ':1.146'
  num-unix-fds -> uint32 1
Body: ()
UNIX File Descriptors:
  fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635.

The function takes the following parameters:

  • indent: indentation level.

The function returns the following values:

  • utf8: string that should be freed with glib.Free().

func (*DBusMessage) ReplySerial 

func (message *DBusMessage) ReplySerial() uint32

ReplySerial: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

The function returns the following values:

  • guint32: value.

func (*DBusMessage) Sender 

func (message *DBusMessage) Sender() string

Sender: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

The function returns the following values:

  • utf8 (optional): value.

func (*DBusMessage) Serial 

func (message *DBusMessage) Serial() uint32

Serial gets the serial for message.

The function returns the following values:

  • guint32: #guint32.

func (*DBusMessage) SetBody 

func (message *DBusMessage) SetBody(body *glib.Variant)

SetBody sets the body message. As a side-effect the G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field is set to the type string of body (or cleared if body is NULL).

If body is floating, message assumes ownership of body.

The function takes the following parameters:

  • body: either NULL or a #GVariant that is a tuple.

func (*DBusMessage) SetByteOrder 

func (message *DBusMessage) SetByteOrder(byteOrder DBusMessageByteOrder)

SetByteOrder sets the byte order of message.

The function takes the following parameters:

  • byteOrder: byte order.

func (*DBusMessage) SetDestination 

func (message *DBusMessage) SetDestination(value string)

SetDestination: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) SetErrorName 

func (message *DBusMessage) SetErrorName(value string)

SetErrorName: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field.

The function takes the following parameters:

  • value to set.

func (*DBusMessage) SetFlags 

func (message *DBusMessage) SetFlags(flags DBusMessageFlags)

SetFlags sets the flags to set on message.

The function takes the following parameters:

  • flags flags for message that are set (typically values from the BusMessageFlags enumeration bitwise ORed together).

func (*DBusMessage) SetHeader 

func (message *DBusMessage) SetHeader(headerField DBusMessageHeaderField, value *glib.Variant)

SetHeader sets a header field on message.

If value is floating, message assumes ownership of value.

The function takes the following parameters:

  • headerField: 8-bit unsigned integer (typically a value from the BusMessageHeaderField enumeration).
  • value (optional) to set the header field or NULL to clear the header field.

func (*DBusMessage) SetInterface 

func (message *DBusMessage) SetInterface(value string)

SetInterface: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) SetMember 

func (message *DBusMessage) SetMember(value string)

SetMember: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) SetMessageType 

func (message *DBusMessage) SetMessageType(typ DBusMessageType)

SetMessageType sets message to be of type.

The function takes the following parameters:

  • typ: 8-bit unsigned integer (typically a value from the BusMessageType enumeration).

func (*DBusMessage) SetPath 

func (message *DBusMessage) SetPath(value string)

SetPath: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_PATH header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) SetReplySerial 

func (message *DBusMessage) SetReplySerial(value uint32)

SetReplySerial: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_REPLY_SERIAL header field.

The function takes the following parameters:

  • value to set.

func (*DBusMessage) SetSender 

func (message *DBusMessage) SetSender(value string)

SetSender: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) SetSerial 

func (message *DBusMessage) SetSerial(serial uint32)

SetSerial sets the serial for message.

The function takes the following parameters:

  • serial: #guint32.

func (*DBusMessage) SetSignature 

func (message *DBusMessage) SetSignature(value string)

SetSignature: convenience setter for the G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

The function takes the following parameters:

  • value (optional) to set.

func (*DBusMessage) Signature 

func (message *DBusMessage) Signature() string

Signature: convenience getter for the G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.

This will always be non-NULL, but may be an empty string.

The function returns the following values:

  • utf8: value.

func (*DBusMessage) ToBlob 

func (message *DBusMessage) ToBlob(capabilities DBusCapabilityFlags) ([]byte, error)

ToBlob serializes message to a blob. The byte order returned by g_dbus_message_get_byte_order() will be used.

The function takes the following parameters:

  • capabilities describing what protocol features are supported.

The function returns the following values:

  • guint8s: pointer to a valid binary D-Bus message of out_size bytes generated by message or NULL if error is set. Free with g_free().

func (*DBusMessage) ToGError 

func (message *DBusMessage) ToGError() error

ToGError: if message is not of type G_DBUS_MESSAGE_TYPE_ERROR does nothing and returns FALSE.

Otherwise this method encodes the error in message as a #GError using g_dbus_error_set_dbus_error() using the information in the G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field of message as well as the first string item in message's body.

type DBusMessageByteOrder 

type DBusMessageByteOrder C.gint

DBusMessageByteOrder: enumeration used to describe the byte order of a D-Bus message. 

const (
	// DBusMessageByteOrderBigEndian: byte order is big endian.
	DBusMessageByteOrderBigEndian DBusMessageByteOrder = 66
	// DBusMessageByteOrderLittleEndian: byte order is little endian.
	DBusMessageByteOrderLittleEndian DBusMessageByteOrder = 108
)

func (DBusMessageByteOrder) String 

func (d DBusMessageByteOrder) String() string

String returns the name in string for DBusMessageByteOrder.

type DBusMessageFilterFunction 

type DBusMessageFilterFunction func(connection *DBusConnection, message *DBusMessage, incoming bool) (dBusMessage *DBusMessage)

DBusMessageFilterFunction: signature for function used in g_dbus_connection_add_filter().

A filter function is passed a BusMessage and expected to return a BusMessage too. Passive filter functions that don't modify the message can simply return the message object: 

static GDBusMessage *
passive_filter (GDBusConnection *connection
                GDBusMessage    *message,
                gboolean         incoming,
                gpointer         user_data)
{
  // inspect message
  return message;
}

Filter functions that wants to drop a message can simply return NULL: 

static GDBusMessage *
drop_filter (GDBusConnection *connection
             GDBusMessage    *message,
             gboolean         incoming,
             gpointer         user_data)
{
  if (should_drop_message)
    {
      g_object_unref (message);
      message = NULL;
    }
  return message;
}

Finally, a filter function may modify a message by copying it: 

static GDBusMessage *
modifying_filter (GDBusConnection *connection
                  GDBusMessage    *message,
                  gboolean         incoming,
                  gpointer         user_data)
{
  GDBusMessage *copy;
  GError *error;

  error = NULL;
  copy = g_dbus_message_copy (message, &error);
  // handle error being set
  g_object_unref (message);

  // modify copy

  return copy;
}

If the returned BusMessage is different from message and cannot be sent on connection (it could use features, such as file descriptors, not compatible with connection), then a warning is logged to standard error. Applications can check this ahead of time using g_dbus_message_to_blob() passing a BusCapabilityFlags value obtained from connection.

type DBusMessageFlags 

type DBusMessageFlags C.guint

DBusMessageFlags: message flags used in BusMessage. 

const (
	// DBusMessageFlagsNone: no flags set.
	DBusMessageFlagsNone DBusMessageFlags = 0b0
	// DBusMessageFlagsNoReplyExpected: reply is not expected.
	DBusMessageFlagsNoReplyExpected DBusMessageFlags = 0b1
	// DBusMessageFlagsNoAutoStart bus must not launch an owner for the
	// destination name in response to this message.
	DBusMessageFlagsNoAutoStart DBusMessageFlags = 0b10
	// DBusMessageFlagsAllowInteractiveAuthorization: if set on a method call,
	// this flag means that the caller is prepared to wait for interactive
	// authorization. Since 2.46.
	DBusMessageFlagsAllowInteractiveAuthorization DBusMessageFlags = 0b100
)

func (DBusMessageFlags) Has 

func (d DBusMessageFlags) Has(other DBusMessageFlags) bool

Has returns true if d contains other.

func (DBusMessageFlags) String 

func (d DBusMessageFlags) String() string

String returns the names in string for DBusMessageFlags.

type DBusMessageHeaderField 

type DBusMessageHeaderField C.gint

DBusMessageHeaderField: header fields used in BusMessage. 

const (
	// DBusMessageHeaderFieldInvalid: not a valid header field.
	DBusMessageHeaderFieldInvalid DBusMessageHeaderField = iota
	// DBusMessageHeaderFieldPath: object path.
	DBusMessageHeaderFieldPath
	// DBusMessageHeaderFieldInterface: interface name.
	DBusMessageHeaderFieldInterface
	// DBusMessageHeaderFieldMember: method or signal name.
	DBusMessageHeaderFieldMember
	// DBusMessageHeaderFieldErrorName: name of the error that occurred.
	DBusMessageHeaderFieldErrorName
	// DBusMessageHeaderFieldReplySerial: serial number the message is a reply
	// to.
	DBusMessageHeaderFieldReplySerial
	// DBusMessageHeaderFieldDestination: name the message is intended for.
	DBusMessageHeaderFieldDestination
	// DBusMessageHeaderFieldSender: unique name of the sender of the message
	// (filled in by the bus).
	DBusMessageHeaderFieldSender
	// DBusMessageHeaderFieldSignature: signature of the message body.
	DBusMessageHeaderFieldSignature
	// DBusMessageHeaderFieldNumUnixFds: number of UNIX file descriptors that
	// accompany the message.
	DBusMessageHeaderFieldNumUnixFds
)

func (DBusMessageHeaderField) String 

func (d DBusMessageHeaderField) String() string

String returns the name in string for DBusMessageHeaderField.

type DBusMessageType 

type DBusMessageType C.gint

DBusMessageType: message types used in BusMessage. 

const (
	// DBusMessageTypeInvalid: message is of invalid type.
	DBusMessageTypeInvalid DBusMessageType = iota
	// DBusMessageTypeMethodCall: method call.
	DBusMessageTypeMethodCall
	// DBusMessageTypeMethodReturn: method reply.
	DBusMessageTypeMethodReturn
	// DBusMessageTypeError: error reply.
	DBusMessageTypeError
	// DBusMessageTypeSignal: signal emission.
	DBusMessageTypeSignal
)

func (DBusMessageType) String 

func (d DBusMessageType) String() string

String returns the name in string for DBusMessageType.

type DBusMethodInfo 

type DBusMethodInfo struct {
	// contains filtered or unexported fields
}

DBusMethodInfo: information about a method on an D-Bus interface.

An instance of this type is always passed by reference.

func (*DBusMethodInfo) Annotations 

func (d *DBusMethodInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusMethodInfo) InArgs 

func (d *DBusMethodInfo) InArgs() []*DBusArgInfo

InArgs: pointer to a NULL-terminated array of pointers to BusArgInfo structures or NULL if there are no in arguments.

func (*DBusMethodInfo) Name 

func (d *DBusMethodInfo) Name() string

Name: name of the D-Bus method, e.g. RequestName.

func (*DBusMethodInfo) OutArgs 

func (d *DBusMethodInfo) OutArgs() []*DBusArgInfo

OutArgs: pointer to a NULL-terminated array of pointers to BusArgInfo structures or NULL if there are no out arguments.

func (*DBusMethodInfo) RefCount 

func (d *DBusMethodInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusMethodInfo) SetRefCount 

func (d *DBusMethodInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

type DBusMethodInvocation 

type DBusMethodInvocation struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusMethodInvocation instances of the GDBusMethodInvocation class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors.

The normal way to obtain a GDBusMethodInvocation object is to receive it as an argument to the handle_method_call() function in a gio.DBusInterfaceVTable that was passed to gio.DBusConnection.RegisterObject().

func (*DBusMethodInvocation) Connection 

func (invocation *DBusMethodInvocation) Connection() *DBusConnection

Connection gets the BusConnection the method was invoked on.

The function returns the following values:

  • dBusConnection Do not free, it is owned by invocation.

func (*DBusMethodInvocation) InterfaceName 

func (invocation *DBusMethodInvocation) InterfaceName() string

InterfaceName gets the name of the D-Bus interface the method was invoked on.

If this method call is a property Get, Set or GetAll call that has been redirected to the method call handler then "org.freedesktop.DBus.Properties" will be returned. See BusInterfaceVTable for more information.

The function returns the following values:

  • utf8: string. Do not free, it is owned by invocation.

func (*DBusMethodInvocation) Message 

func (invocation *DBusMethodInvocation) Message() *DBusMessage

Message gets the BusMessage for the method invocation. This is useful if you need to use low-level protocol features, such as UNIX file descriptor passing, that cannot be properly expressed in the #GVariant API.

See this [server][gdbus-server] and [client][gdbus-unix-fd-client] for an example of how to use this low-level API to send and receive UNIX file descriptors.

The function returns the following values:

  • dBusMessage Do not free, it is owned by invocation.

func (*DBusMethodInvocation) MethodInfo 

func (invocation *DBusMethodInvocation) MethodInfo() *DBusMethodInfo

MethodInfo gets information about the method call, if any.

If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then NULL will be returned. See g_dbus_method_invocation_get_property_info() and BusInterfaceVTable for more information.

The function returns the following values:

  • dBusMethodInfo (optional) or NULL. Do not free, it is owned by invocation.

func (*DBusMethodInvocation) MethodName 

func (invocation *DBusMethodInvocation) MethodName() string

MethodName gets the name of the method that was invoked.

The function returns the following values:

  • utf8: string. Do not free, it is owned by invocation.

func (*DBusMethodInvocation) ObjectPath 

func (invocation *DBusMethodInvocation) ObjectPath() string

ObjectPath gets the object path the method was invoked on.

The function returns the following values:

  • utf8: string. Do not free, it is owned by invocation.

func (*DBusMethodInvocation) Parameters 

func (invocation *DBusMethodInvocation) Parameters() *glib.Variant

Parameters gets the parameters of the method invocation. If there are no input parameters then this will return a GVariant with 0 children rather than NULL.

The function returns the following values:

  • variant tuple. Do not unref this because it is owned by invocation.

func (*DBusMethodInvocation) PropertyInfo 

func (invocation *DBusMethodInvocation) PropertyInfo() *DBusPropertyInfo

PropertyInfo gets information about the property that this method call is for, if any.

This will only be set in the case of an invocation in response to a property Get or Set call that has been directed to the method call handler for an object on account of its property_get() or property_set() vtable pointers being unset.

See BusInterfaceVTable for more information.

If the call was GetAll, NULL will be returned.

The function returns the following values:

  • dBusPropertyInfo (optional) or NULL.

func (*DBusMethodInvocation) ReturnDBusError 

func (invocation *DBusMethodInvocation) ReturnDBusError(errorName, errorMessage string)

ReturnDBusError finishes handling a D-Bus method call by returning an error.

This method will take ownership of invocation. See BusInterfaceVTable for more information about the ownership of invocation.

The function takes the following parameters:

  • errorName: valid D-Bus error name.
  • errorMessage: valid D-Bus error message.

func (*DBusMethodInvocation) ReturnErrorLiteral 

func (invocation *DBusMethodInvocation) ReturnErrorLiteral(domain glib.Quark, code int, message string)

ReturnErrorLiteral: like g_dbus_method_invocation_return_error() but without printf()-style formatting.

This method will take ownership of invocation. See BusInterfaceVTable for more information about the ownership of invocation.

The function takes the following parameters:

  • domain for the #GError error domain.
  • code: error code.
  • message: error message.

func (*DBusMethodInvocation) ReturnGError 

func (invocation *DBusMethodInvocation) ReturnGError(err error)

ReturnGError: like g_dbus_method_invocation_return_error() but takes a #GError instead of the error domain, error code and message.

This method will take ownership of invocation. See BusInterfaceVTable for more information about the ownership of invocation.

The function takes the following parameters:

  • err: #GError.

func (*DBusMethodInvocation) ReturnValue 

func (invocation *DBusMethodInvocation) ReturnValue(parameters *glib.Variant)

ReturnValue finishes handling a D-Bus method call by returning parameters. If the parameters GVariant is floating, it is consumed.

It is an error if parameters is not of the right format: it must be a tuple containing the out-parameters of the D-Bus method. Even if the method has a single out-parameter, it must be contained in a tuple. If the method has no out-parameters, parameters may be NULL or an empty tuple. 

GDBusMethodInvocation *invocation = some_invocation;
g_autofree gchar *result_string = NULL;
g_autoptr (GError) error = NULL;

result_string = calculate_result (&error);

if (error != NULL)
  g_dbus_method_invocation_return_gerror (invocation, error);
else
  g_dbus_method_invocation_return_value (invocation,
                                         g_variant_new ("(s)", result_string));

// Do not free invocation here; returning a value does that

This method will take ownership of invocation. See BusInterfaceVTable for more information about the ownership of invocation.

Since 2.48, if the method call requested for a reply not to be sent then this call will sink parameters and free invocation, but otherwise do nothing (as per the recommendations of the D-Bus specification).

The function takes the following parameters:

  • parameters (optional) tuple with out parameters for the method or NULL if not passing any parameters.

func (*DBusMethodInvocation) Sender 

func (invocation *DBusMethodInvocation) Sender() string

Sender gets the bus name that invoked the method.

The function returns the following values:

  • utf8: string. Do not free, it is owned by invocation.

type DBusNodeInfo 

type DBusNodeInfo struct {
	// contains filtered or unexported fields
}

DBusNodeInfo: information about nodes in a remote object hierarchy.

An instance of this type is always passed by reference.

func NewDBusNodeInfoForXML 

func NewDBusNodeInfoForXML(xmlData string) (*DBusNodeInfo, error)

NewDBusNodeInfoForXML constructs a struct DBusNodeInfo.

func (*DBusNodeInfo) Annotations 

func (d *DBusNodeInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusNodeInfo) Interfaces 

func (d *DBusNodeInfo) Interfaces() []*DBusInterfaceInfo

Interfaces: pointer to a NULL-terminated array of pointers to BusInterfaceInfo structures or NULL if there are no interfaces.

func (*DBusNodeInfo) LookupInterface 

func (info *DBusNodeInfo) LookupInterface(name string) *DBusInterfaceInfo

LookupInterface looks up information about an interface.

The cost of this function is O(n) in number of interfaces.

The function takes the following parameters:

  • name d-Bus interface name.

The function returns the following values:

  • dBusInterfaceInfo (optional) or NULL if not found. Do not free, it is owned by info.

func (*DBusNodeInfo) Nodes 

func (d *DBusNodeInfo) Nodes() []*DBusNodeInfo

Nodes: pointer to a NULL-terminated array of pointers to BusNodeInfo structures or NULL if there are no nodes.

func (*DBusNodeInfo) Path 

func (d *DBusNodeInfo) Path() string

Path: path of the node or NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details.

func (*DBusNodeInfo) RefCount 

func (d *DBusNodeInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusNodeInfo) SetRefCount 

func (d *DBusNodeInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

type DBusObject 

type DBusObject struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusObject: GDBusObject type is the base type for D-Bus objects on both the service side (see gio.DBusObjectSkeleton) and the client side (see gio.DBusObjectProxy). It is essentially just a container of interfaces.

DBusObject wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DBusObject) ConnectInterfaceAdded 

func (object *DBusObject) ConnectInterfaceAdded(f func(iface DBusInterfacer)) coreglib.SignalHandle

ConnectInterfaceAdded is emitted when interface is added to object.

func (*DBusObject) ConnectInterfaceRemoved 

func (object *DBusObject) ConnectInterfaceRemoved(f func(iface DBusInterfacer)) coreglib.SignalHandle

ConnectInterfaceRemoved is emitted when interface is removed from object.

func (*DBusObject) Interface 

func (object *DBusObject) Interface(interfaceName string) *DBusInterface

Interface gets the D-Bus interface with name interface_name associated with object, if any.

The function takes the following parameters:

  • interfaceName d-Bus interface name.

The function returns the following values:

  • dBusInterface (optional): NULL if not found, otherwise a BusInterface that must be freed with g_object_unref().

func (*DBusObject) Interfaces 

func (object *DBusObject) Interfaces() []*DBusInterface

Interfaces gets the D-Bus interfaces associated with object.

The function returns the following values:

  • list of BusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref().

func (*DBusObject) ObjectPath 

func (object *DBusObject) ObjectPath() string

ObjectPath gets the object path for object.

The function returns the following values:

  • utf8: string owned by object. Do not free.

type DBusObjectIface added in v0.0.5 

type DBusObjectIface struct {
	// contains filtered or unexported fields
}

DBusObjectIface: base object type for D-Bus objects.

An instance of this type is always passed by reference.

type DBusObjectManager 

type DBusObjectManager struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DBusObjectManager: GDBusObjectManager type is the base type for service- and client-side implementations of the standardized org.freedesktop.DBus.ObjectManager (http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface.

See gio.DBusObjectManagerClient for the client-side implementation and gio.DBusObjectManagerServer for the service-side implementation.

DBusObjectManager wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DBusObjectManager) ConnectInterfaceAdded 

func (manager *DBusObjectManager) ConnectInterfaceAdded(f func(object DBusObjector, iface DBusInterfacer)) coreglib.SignalHandle

ConnectInterfaceAdded is emitted when interface is added to object.

This signal exists purely as a convenience to avoid having to connect signals to all objects managed by manager.

func (*DBusObjectManager) ConnectInterfaceRemoved 

func (manager *DBusObjectManager) ConnectInterfaceRemoved(f func(object DBusObjector, iface DBusInterfacer)) coreglib.SignalHandle

ConnectInterfaceRemoved is emitted when interface has been removed from object.

This signal exists purely as a convenience to avoid having to connect signals to all objects managed by manager.

func (*DBusObjectManager) ConnectObjectAdded 

func (manager *DBusObjectManager) ConnectObjectAdded(f func(object DBusObjector)) coreglib.SignalHandle

ConnectObjectAdded is emitted when object is added to manager.

func (*DBusObjectManager) ConnectObjectRemoved 

func (manager *DBusObjectManager) ConnectObjectRemoved(f func(object DBusObjector)) coreglib.SignalHandle

ConnectObjectRemoved is emitted when object is removed from manager.

func (*DBusObjectManager) GetObject 

func (manager *DBusObjectManager) GetObject(objectPath string) *DBusObject

GetObject gets the BusObject at object_path, if any.

The function takes the following parameters:

  • objectPath: object path to look up.

The function returns the following values:

  • dBusObject (optional) or NULL. Free with g_object_unref().

func (*DBusObjectManager) Interface 

func (manager *DBusObjectManager) Interface(objectPath, interfaceName string) *DBusInterface

Interface gets the interface proxy for interface_name at object_path, if any.

The function takes the following parameters:

  • objectPath: object path to look up.
  • interfaceName d-Bus interface name to look up.

The function returns the following values:

  • dBusInterface (optional) instance or NULL. Free with g_object_unref().

func (*DBusObjectManager) ObjectPath 

func (manager *DBusObjectManager) ObjectPath() string

ObjectPath gets the object path that manager is for.

The function returns the following values:

  • utf8: string owned by manager. Do not free.

func (*DBusObjectManager) Objects 

func (manager *DBusObjectManager) Objects() []*DBusObject

Objects gets all BusObject objects known to manager.

The function returns the following values:

  • list of BusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().

type DBusObjectManagerClient 

type DBusObjectManagerClient struct {
	*coreglib.Object

	AsyncInitable
	DBusObjectManager
	Initable
	// contains filtered or unexported fields
}

DBusObjectManagerClient: GDBusObjectManagerClient is used to create, monitor and delete object proxies for remote objects exported by a gio.DBusObjectManagerServer (or any code implementing the org.freedesktop.DBus.ObjectManager (http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface).

Once an instance of this type has been created, you can connect to the gio.DBusObjectManager::object-added and gio.DBusObjectManager::object-removed signals and inspect the gio.DBusObjectProxy objects returned by gio.DBusObjectManager.GetObjects().

If the name for a GDBusObjectManagerClient is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be disabled using the G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this case, GDBusObjectManagerClient object construction still succeeds but there will be no object proxies (e.g. gio.DBusObjectManager.GetObjects() returns the empty list) and the gio.DBusObjectManagerClient:name-owner property is NULL.

The owner of the requested name can come and go (for example consider a system service being restarted) – GDBusObjectManagerClient handles this case too; simply connect to the gobject.Object::notify signal to watch for changes on the gio.DBusObjectManagerClient:name-owner property. When the name owner vanishes, the behavior is that gio.DBusObjectManagerClient:name-owner is set to NULL (this includes emission of the gobject.Object::notify signal) and then gio.DBusObjectManager::object-removed signals are synthesized for all currently existing object proxies. Since gio.DBusObjectManagerClient:name-owner is NULL when this happens, you can use this information to disambiguate a synthesized signal from a genuine signal caused by object removal on the remote gio.DBusObjectManager. Similarly, when a new name owner appears, gio.DBusObjectManager::object-added signals are synthesized while gio.DBusObjectManagerClient:name-owner is still NULL. Only when all object proxies have been added, the gio.DBusObjectManagerClient:name-owner is set to the new name owner (this includes emission of the gobject.Object::notify signal). Furthermore, you are guaranteed that gio.DBusObjectManagerClient:name-owner will alternate between a name owner (e.g. :1.42) and NULL even in the case where the name of interest is atomically replaced

Ultimately, GDBusObjectManagerClient is used to obtain gio.DBusProxy instances. All signals (including the org.freedesktop.DBus.Properties::PropertiesChanged signal) delivered to gio.DBusProxy instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the “half the proxy is from the old owner and the other half is from the new owner” problem cannot happen.

To avoid having the application connect to signals on the returned gio.DBusObjectProxy and gio.DBusProxy objects, the gio.DBusObject::interface-added, gio.DBusObject::interface-removed, gio.DBusProxy::g-properties-changed and gio.DBusProxy::g-signal signals are also emitted on the GDBusObjectManagerClient instance managing these objects. The signals emitted are gio.DBusObjectManager::interface-added, gio.DBusObjectManager::interface-removed, gio.DBusObjectManagerClient::interface-proxy-properties-changed and gio.DBusObjectManagerClient::interface-proxy-signal.

Note that all callbacks and signals are emitted in the thread-default main context (see glib.MainContext.PushThreadDefault()) that the GDBusObjectManagerClient object was constructed in. Additionally, the gio.DBusObjectProxy and gio.DBusProxy objects originating from the GDBusObjectManagerClient object will be created in the same context and, consequently, will deliver signals in the same main loop.

func NewDBusObjectManagerClientFinish 

func NewDBusObjectManagerClientFinish(res AsyncResulter) (*DBusObjectManagerClient, error)

NewDBusObjectManagerClientFinish finishes an operation started with g_dbus_object_manager_client_new().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_object_manager_client_new().

The function returns the following values:

  • dBusObjectManagerClient: a BusObjectManagerClient object or NULL if error is set. Free with g_object_unref().

func NewDBusObjectManagerClientForBusFinish 

func NewDBusObjectManagerClientForBusFinish(res AsyncResulter) (*DBusObjectManagerClient, error)

NewDBusObjectManagerClientForBusFinish finishes an operation started with g_dbus_object_manager_client_new_for_bus().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_object_manager_client_new_for_bus().

The function returns the following values:

  • dBusObjectManagerClient: a BusObjectManagerClient object or NULL if error is set. Free with g_object_unref().

func (*DBusObjectManagerClient) ConnectInterfaceProxyPropertiesChanged 

func (manager *DBusObjectManagerClient) ConnectInterfaceProxyPropertiesChanged(f func(objectProxy *DBusObjectProxy, interfaceProxy *DBusProxy, changedProperties *glib.Variant, invalidatedProperties []string)) coreglib.SignalHandle

ConnectInterfaceProxyPropertiesChanged is emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changed_properties and invalidated_properties are guaranteed to never be NULL (either may be empty though).

This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

This signal is emitted in the [thread-default main context][g-main-context-push-thread-default] that manager was constructed in.

func (*DBusObjectManagerClient) ConnectInterfaceProxySignal 

func (manager *DBusObjectManagerClient) ConnectInterfaceProxySignal(f func(objectProxy *DBusObjectProxy, interfaceProxy *DBusProxy, senderName, signalName string, parameters *glib.Variant)) coreglib.SignalHandle

ConnectInterfaceProxySignal is emitted when a D-Bus signal is received on interface_proxy.

This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

This signal is emitted in the [thread-default main context][g-main-context-push-thread-default] that manager was constructed in.

func (*DBusObjectManagerClient) Connection 

func (manager *DBusObjectManagerClient) Connection() *DBusConnection

Connection gets the BusConnection used by manager.

The function returns the following values:

  • dBusConnection object. Do not free, the object belongs to manager.

func (*DBusObjectManagerClient) Flags 

func (manager *DBusObjectManagerClient) Flags() DBusObjectManagerClientFlags

Flags gets the flags that manager was constructed with.

The function returns the following values:

  • dBusObjectManagerClientFlags: zero of more flags from the BusObjectManagerClientFlags enumeration.

func (*DBusObjectManagerClient) Name 

func (manager *DBusObjectManagerClient) Name() string

Name gets the name that manager is for, or NULL if not a message bus connection.

The function returns the following values:

  • utf8: unique or well-known name. Do not free, the string belongs to manager.

func (*DBusObjectManagerClient) NameOwner 

func (manager *DBusObjectManagerClient) NameOwner() string

NameOwner: unique name that owns the name that manager is for or NULL if no-one currently owns that name. You can connect to the #GObject::notify signal to track changes to the BusObjectManagerClient:name-owner property.

The function returns the following values:

  • utf8 (optional): name owner or NULL if no name owner exists. Free with g_free().

type DBusObjectManagerClientClass added in v0.0.5 

type DBusObjectManagerClientClass struct {
	// contains filtered or unexported fields
}

DBusObjectManagerClientClass class structure for BusObjectManagerClient.

An instance of this type is always passed by reference.

type DBusObjectManagerClientFlags 

type DBusObjectManagerClientFlags C.guint

DBusObjectManagerClientFlags flags used when constructing a BusObjectManagerClient. 

const (
	// DBusObjectManagerClientFlagsNone: no flags set.
	DBusObjectManagerClientFlagsNone DBusObjectManagerClientFlags = 0b0
	// DBusObjectManagerClientFlagsDoNotAutoStart: if not set and the manager
	// is for a well-known name, then request the bus to launch an owner for the
	// name if no-one owns the name. This flag can only be used in managers for
	// well-known names.
	DBusObjectManagerClientFlagsDoNotAutoStart DBusObjectManagerClientFlags = 0b1
)

func (DBusObjectManagerClientFlags) Has 

func (d DBusObjectManagerClientFlags) Has(other DBusObjectManagerClientFlags) bool

Has returns true if d contains other.

func (DBusObjectManagerClientFlags) String 

func (d DBusObjectManagerClientFlags) String() string

String returns the names in string for DBusObjectManagerClientFlags.

type DBusObjectManagerClientOverrides added in v0.0.5 

type DBusObjectManagerClientOverrides struct {
	// InterfaceProxySignal: signal class handler for the
	// BusObjectManagerClient::interface-proxy-signal signal.
	//
	// The function takes the following parameters:
	//
	//   - objectProxy
	//   - interfaceProxy
	//   - senderName
	//   - signalName
	//   - parameters
	InterfaceProxySignal func(objectProxy *DBusObjectProxy, interfaceProxy *DBusProxy, senderName, signalName string, parameters *glib.Variant)
}

DBusObjectManagerClientOverrides contains methods that are overridable.

type DBusObjectManagerIface added in v0.0.5 

type DBusObjectManagerIface struct {
	// contains filtered or unexported fields
}

DBusObjectManagerIface: base type for D-Bus object managers.

An instance of this type is always passed by reference.

type DBusObjectManagerServer 

type DBusObjectManagerServer struct {
	*coreglib.Object

	DBusObjectManager
	// contains filtered or unexported fields
}

DBusObjectManagerServer: GDBusObjectManagerServer is used to export gio.DBusObject instances using the standardized org.freedesktop.DBus.ObjectManager (http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. For example, remote D-Bus clients can get all objects and properties in a single call. Additionally, any change in the object hierarchy is broadcast using signals. This means that D-Bus clients can keep caches up to date by only listening to D-Bus signals.

The recommended path to export an object manager at is the path form of the well-known name of a D-Bus service, or below. For example, if a D-Bus service is available at the well-known name net.example.ExampleService1, the object manager should typically be exported at /net/example/ExampleService1, or below (to allow for multiple object managers in a service).

It is supported, but not recommended, to export an object manager at the root path, /.

See gio.DBusObjectManagerClient for the client-side code that is intended to be used with GDBusObjectManagerServer or any D-Bus object implementing the org.freedesktop.DBus.ObjectManager interface.

func NewDBusObjectManagerServer 

func NewDBusObjectManagerServer(objectPath string) *DBusObjectManagerServer

NewDBusObjectManagerServer creates a new BusObjectManagerServer object.

The returned server isn't yet exported on any connection. To do so, use g_dbus_object_manager_server_set_connection(). Normally you want to export all of your objects before doing so to avoid InterfacesAdded (http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) signals being emitted.

The function takes the following parameters:

  • objectPath: object path to export the manager object at.

The function returns the following values:

  • dBusObjectManagerServer object. Free with g_object_unref().

func (*DBusObjectManagerServer) Connection 

func (manager *DBusObjectManagerServer) Connection() *DBusConnection

Connection gets the BusConnection used by manager.

The function returns the following values:

  • dBusConnection (optional) object or NULL if manager isn't exported on a connection. The returned object should be freed with g_object_unref().

func (*DBusObjectManagerServer) Export 

func (manager *DBusObjectManagerServer) Export(object *DBusObjectSkeleton)

Export exports object on manager.

If there is already a BusObject exported at the object path, then the old object is removed.

The object path for object must be in the hierarchy rooted by the object path for manager.

Note that manager will take a reference on object for as long as it is exported.

The function takes the following parameters:

  • object: BusObjectSkeleton.

func (*DBusObjectManagerServer) ExportUniquely 

func (manager *DBusObjectManagerServer) ExportUniquely(object *DBusObjectSkeleton)

ExportUniquely: like g_dbus_object_manager_server_export() but appends a string of the form _N (with N being a natural number) to object's object path if an object with the given path already exists. As such, the BusObjectProxy:g-object-path property of object may be modified.

The function takes the following parameters:

  • object: object.

func (*DBusObjectManagerServer) IsExported 

func (manager *DBusObjectManagerServer) IsExported(object *DBusObjectSkeleton) bool

IsExported returns whether object is currently exported on manager.

The function takes the following parameters:

  • object: object.

The function returns the following values:

  • ok: TRUE if object is exported.

func (*DBusObjectManagerServer) SetConnection 

func (manager *DBusObjectManagerServer) SetConnection(connection *DBusConnection)

SetConnection exports all objects managed by manager on connection. If connection is NULL, stops exporting objects.

The function takes the following parameters:

  • connection (optional) or NULL.

func (*DBusObjectManagerServer) Unexport 

func (manager *DBusObjectManagerServer) Unexport(objectPath string) bool

Unexport: if manager has an object at path, removes the object. Otherwise does nothing.

Note that object_path must be in the hierarchy rooted by the object path for manager.

The function takes the following parameters:

  • objectPath: object path.

The function returns the following values:

  • ok: TRUE if object at object_path was removed, FALSE otherwise.

type DBusObjectManagerServerClass added in v0.0.5 

type DBusObjectManagerServerClass struct {
	// contains filtered or unexported fields
}

DBusObjectManagerServerClass class structure for BusObjectManagerServer.

An instance of this type is always passed by reference.

type DBusObjectManagerServerOverrides added in v0.0.5 

type DBusObjectManagerServerOverrides struct {
}

DBusObjectManagerServerOverrides contains methods that are overridable.

type DBusObjectManagerer 

type DBusObjectManagerer interface {
	coreglib.Objector

	// Interface gets the interface proxy for interface_name at object_path,
	// if any.
	Interface(objectPath, interfaceName string) *DBusInterface
	// GetObject gets the BusObject at object_path, if any.
	GetObject(objectPath string) *DBusObject
	// ObjectPath gets the object path that manager is for.
	ObjectPath() string
	// Objects gets all BusObject objects known to manager.
	Objects() []*DBusObject

	// Interface-added is emitted when interface is added to object.
	ConnectInterfaceAdded(func(object DBusObjector, iface DBusInterfacer)) coreglib.SignalHandle
	// Interface-removed is emitted when interface has been removed from object.
	ConnectInterfaceRemoved(func(object DBusObjector, iface DBusInterfacer)) coreglib.SignalHandle
	// Object-added is emitted when object is added to manager.
	ConnectObjectAdded(func(object DBusObjector)) coreglib.SignalHandle
	// Object-removed is emitted when object is removed from manager.
	ConnectObjectRemoved(func(object DBusObjector)) coreglib.SignalHandle
}

DBusObjectManagerer describes DBusObjectManager's interface methods.

type DBusObjectProxy 

type DBusObjectProxy struct {
	*coreglib.Object

	DBusObject
	// contains filtered or unexported fields
}

DBusObjectProxy: GDBusObjectProxy is an object used to represent a remote object with one or more D-Bus interfaces. Normally, you don’t instantiate a GDBusObjectProxy yourself — typically gio.DBusObjectManagerClient is used to obtain it.

func NewDBusObjectProxy 

func NewDBusObjectProxy(connection *DBusConnection, objectPath string) *DBusObjectProxy

NewDBusObjectProxy creates a new BusObjectProxy for the given connection and object path.

The function takes the following parameters:

  • connection: BusConnection.
  • objectPath: object path.

The function returns the following values:

  • dBusObjectProxy: new BusObjectProxy.

func (*DBusObjectProxy) Connection 

func (proxy *DBusObjectProxy) Connection() *DBusConnection

Connection gets the connection that proxy is for.

The function returns the following values:

  • dBusConnection Do not free, the object is owned by proxy.

type DBusObjectProxyClass added in v0.0.5 

type DBusObjectProxyClass struct {
	// contains filtered or unexported fields
}

DBusObjectProxyClass class structure for BusObjectProxy.

An instance of this type is always passed by reference.

type DBusObjectProxyOverrides added in v0.0.5 

type DBusObjectProxyOverrides struct {
}

DBusObjectProxyOverrides contains methods that are overridable.

type DBusObjectSkeleton 

type DBusObjectSkeleton struct {
	*coreglib.Object

	DBusObject
	// contains filtered or unexported fields
}

DBusObjectSkeleton: GDBusObjectSkeleton instance is essentially a group of D-Bus interfaces. The set of exported interfaces on the object may be dynamic and change at runtime.

This type is intended to be used with gio.DBusObjectManager.

func NewDBusObjectSkeleton 

func NewDBusObjectSkeleton(objectPath string) *DBusObjectSkeleton

NewDBusObjectSkeleton creates a new BusObjectSkeleton.

The function takes the following parameters:

  • objectPath: object path.

The function returns the following values:

  • dBusObjectSkeleton Free with g_object_unref().

func (*DBusObjectSkeleton) AddInterface 

func (object *DBusObjectSkeleton) AddInterface(interface_ DBusInterfaceSkeletonner)

AddInterface adds interface_ to object.

If object already contains a BusInterfaceSkeleton with the same interface name, it is removed before interface_ is added.

Note that object takes its own reference on interface_ and holds it until removed.

The function takes the following parameters:

  • interface_: BusInterfaceSkeleton.

func (*DBusObjectSkeleton) ConnectAuthorizeMethod 

func (object *DBusObjectSkeleton) ConnectAuthorizeMethod(f func(iface DBusInterfaceSkeletonner, invocation *DBusMethodInvocation) (ok bool)) coreglib.SignalHandle

ConnectAuthorizeMethod is emitted when a method is invoked by a remote caller and used to determine if the method call is authorized.

This signal is like BusInterfaceSkeleton's BusInterfaceSkeleton::g-authorize-method signal, except that it is for the enclosing object.

The default class handler just returns TRUE.

func (*DBusObjectSkeleton) Flush 

func (object *DBusObjectSkeleton) Flush()

Flush: this method simply calls g_dbus_interface_skeleton_flush() on all interfaces belonging to object. See that method for when flushing is useful.

func (*DBusObjectSkeleton) RemoveInterface 

func (object *DBusObjectSkeleton) RemoveInterface(interface_ DBusInterfaceSkeletonner)

RemoveInterface removes interface_ from object.

The function takes the following parameters:

  • interface_: BusInterfaceSkeleton.

func (*DBusObjectSkeleton) RemoveInterfaceByName 

func (object *DBusObjectSkeleton) RemoveInterfaceByName(interfaceName string)

RemoveInterfaceByName removes the BusInterface with interface_name from object.

If no D-Bus interface of the given interface exists, this function does nothing.

The function takes the following parameters:

  • interfaceName d-Bus interface name.

func (*DBusObjectSkeleton) SetObjectPath 

func (object *DBusObjectSkeleton) SetObjectPath(objectPath string)

SetObjectPath sets the object path for object.

The function takes the following parameters:

  • objectPath: valid D-Bus object path.

type DBusObjectSkeletonClass added in v0.0.5 

type DBusObjectSkeletonClass struct {
	// contains filtered or unexported fields
}

DBusObjectSkeletonClass class structure for BusObjectSkeleton.

An instance of this type is always passed by reference.

type DBusObjectSkeletonOverrides added in v0.0.5 

type DBusObjectSkeletonOverrides struct {
	// AuthorizeMethod: signal class handler for the
	// BusObjectSkeleton::authorize-method signal.
	//
	// The function takes the following parameters:
	//
	//   - interface_
	//   - invocation
	AuthorizeMethod func(interface_ DBusInterfaceSkeletonner, invocation *DBusMethodInvocation) bool
}

DBusObjectSkeletonOverrides contains methods that are overridable.

type DBusObjector 

type DBusObjector interface {
	coreglib.Objector

	// Interface gets the D-Bus interface with name interface_name associated
	// with object, if any.
	Interface(interfaceName string) *DBusInterface
	// Interfaces gets the D-Bus interfaces associated with object.
	Interfaces() []*DBusInterface
	// ObjectPath gets the object path for object.
	ObjectPath() string

	// Interface-added is emitted when interface is added to object.
	ConnectInterfaceAdded(func(iface DBusInterfacer)) coreglib.SignalHandle
	// Interface-removed is emitted when interface is removed from object.
	ConnectInterfaceRemoved(func(iface DBusInterfacer)) coreglib.SignalHandle
}

DBusObjector describes DBusObject's interface methods.

type DBusPropertyInfo 

type DBusPropertyInfo struct {
	// contains filtered or unexported fields
}

DBusPropertyInfo: information about a D-Bus property on a D-Bus interface.

An instance of this type is always passed by reference.

func (*DBusPropertyInfo) Annotations 

func (d *DBusPropertyInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusPropertyInfo) Flags 

func (d *DBusPropertyInfo) Flags() DBusPropertyInfoFlags

Flags access control flags for the property.

func (*DBusPropertyInfo) Name 

func (d *DBusPropertyInfo) Name() string

Name: name of the D-Bus property, e.g. "SupportedFilesystems".

func (*DBusPropertyInfo) RefCount 

func (d *DBusPropertyInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusPropertyInfo) SetRefCount 

func (d *DBusPropertyInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

func (*DBusPropertyInfo) Signature 

func (d *DBusPropertyInfo) Signature() string

Signature d-Bus signature of the property (a single complete type).

type DBusPropertyInfoFlags 

type DBusPropertyInfoFlags C.guint

DBusPropertyInfoFlags flags describing the access control of a D-Bus property. 

const (
	// DBusPropertyInfoFlagsNone: no flags set.
	DBusPropertyInfoFlagsNone DBusPropertyInfoFlags = 0b0
	// DBusPropertyInfoFlagsReadable: property is readable.
	DBusPropertyInfoFlagsReadable DBusPropertyInfoFlags = 0b1
	// DBusPropertyInfoFlagsWritable: property is writable.
	DBusPropertyInfoFlagsWritable DBusPropertyInfoFlags = 0b10
)

func (DBusPropertyInfoFlags) Has 

func (d DBusPropertyInfoFlags) Has(other DBusPropertyInfoFlags) bool

Has returns true if d contains other.

func (DBusPropertyInfoFlags) String 

func (d DBusPropertyInfoFlags) String() string

String returns the names in string for DBusPropertyInfoFlags.

type DBusProxy 

type DBusProxy struct {
	*coreglib.Object

	AsyncInitable
	DBusInterface
	Initable
	// contains filtered or unexported fields
}

DBusProxy: GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A GDBusProxy can be constructed for both well-known and unique names.

By default, GDBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable gio.DBusProxyFlags when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

The unique name owner of the proxy’s name is tracked and can be read from gio.DBusProxy:g-name-owner. Connect to the gobject.Object::notify signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).

If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the gio.DBusProxy:g-name-owner tracking of GDBusProxy will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use GDBusProxy — use direct D-Bus method calls and signal connections.

The generic gio.DBusProxy::g-properties-changed and gio.DBusProxy::g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass GDBusProxy, and have more natural properties and signals in your derived class. This example (migrating-gdbus.html#using-gdbus-codegen) shows how this can easily be done using the gdbus-codegen (gdbus-codegen.html) tool.

A GDBusProxy instance can be used from multiple threads but note that all signals (e.g. gio.DBusProxy::g-signal, gio.DBusProxy::g-properties-changed and gobject.Object::notify) are emitted in the thread-default main context (see glib.MainContext.PushThreadDefault()) of the thread where the instance was constructed.

An example using a proxy for a well-known name can be found in gdbus-example-watch-proxy.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c).

func NewDBusProxyFinish 

func NewDBusProxyFinish(res AsyncResulter) (*DBusProxy, error)

NewDBusProxyFinish finishes creating a BusProxy.

The function takes the following parameters:

  • res obtained from the ReadyCallback function passed to g_dbus_proxy_new().

The function returns the following values:

  • dBusProxy or NULL if error is set. Free with g_object_unref().

func NewDBusProxyForBusFinish 

func NewDBusProxyForBusFinish(res AsyncResulter) (*DBusProxy, error)

NewDBusProxyForBusFinish finishes creating a BusProxy.

The function takes the following parameters:

  • res obtained from the ReadyCallback function passed to g_dbus_proxy_new_for_bus().

The function returns the following values:

  • dBusProxy or NULL if error is set. Free with g_object_unref().

func NewDBusProxyForBusSync 

func NewDBusProxyForBusSync(ctx context.Context, busType BusType, flags DBusProxyFlags, info *DBusInterfaceInfo, name, objectPath, interfaceName string) (*DBusProxy, error)

NewDBusProxyForBusSync: like g_dbus_proxy_new_sync() but takes a Type instead of a BusConnection.

BusProxy is used in this [example][gdbus-wellknown-proxy].

The function takes the following parameters:

  • ctx (optional) or NULL.
  • busType: Type.
  • flags flags used when constructing the proxy.
  • info (optional) specifying the minimal interface that proxy conforms to or NULL.
  • name bus name (well-known or unique).
  • objectPath: object path.
  • interfaceName d-Bus interface name.

The function returns the following values:

  • dBusProxy or NULL if error is set. Free with g_object_unref().

func NewDBusProxySync 

func NewDBusProxySync(ctx context.Context, connection *DBusConnection, flags DBusProxyFlags, info *DBusInterfaceInfo, name, objectPath, interfaceName string) (*DBusProxy, error)

NewDBusProxySync creates a proxy for accessing interface_name on the remote object at object_path owned by name at connection and synchronously loads D-Bus properties unless the G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES flag is used.

If the G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the BusProxy::g-signal signal to handle signals from the remote object.

If both G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version.

BusProxy is used in this [example][gdbus-wellknown-proxy].

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connection: BusConnection.
  • flags flags used when constructing the proxy.
  • info (optional) specifying the minimal interface that proxy conforms to or NULL.
  • name (optional) bus name (well-known or unique) or NULL if connection is not a message bus connection.
  • objectPath: object path.
  • interfaceName d-Bus interface name.

The function returns the following values:

  • dBusProxy or NULL if error is set. Free with g_object_unref().

func (*DBusProxy) CachedProperty 

func (proxy *DBusProxy) CachedProperty(propertyName string) *glib.Variant

CachedProperty looks up the value for a property from the cache. This call does no blocking IO.

If proxy has an expected interface (see BusProxy:g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

The function takes the following parameters:

  • propertyName: property name.

The function returns the following values:

  • variant (optional): reference to the #GVariant instance that holds the value for property_name or NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref().

func (*DBusProxy) CachedPropertyNames 

func (proxy *DBusProxy) CachedPropertyNames() []string

CachedPropertyNames gets the names of all cached properties on proxy.

The function returns the following values:

  • utf8s (optional): a NULL-terminated array of strings or NULL if proxy has no cached properties. Free the returned array with g_strfreev().

func (*DBusProxy) Call 

func (proxy *DBusProxy) Call(ctx context.Context, methodName string, parameters *glib.Variant, flags DBusCallFlags, timeoutMsec int, callback AsyncReadyCallback)

Call: asynchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the BusConnection associated with proxy is closed then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If the parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: 

g_dbus_proxy_call (proxy,
                   "TwoStrings",
                   g_variant_new ("(ss)",
                                  "Thing One",
                                  "Thing Two"),
                   G_DBUS_CALL_FLAGS_NONE,
                   -1,
                   NULL,
                   (GAsyncReadyCallback) two_strings_done,
                   &data);

If proxy has an expected interface (see BusProxy:g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method.

If callback is NULL then the D-Bus method call message will be sent with the G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • methodName: name of method to invoke.
  • parameters (optional) tuple with parameters for the signal or NULL if not passing parameters.
  • flags flags from the BusCallFlags enumeration.
  • timeoutMsec: timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
  • callback (optional) to call when the request is satisfied or NULL if you don't care about the result of the method invocation.

func (*DBusProxy) CallFinish 

func (proxy *DBusProxy) CallFinish(res AsyncResulter) (*glib.Variant, error)

CallFinish finishes an operation started with g_dbus_proxy_call().

The function takes the following parameters:

  • res obtained from the ReadyCallback passed to g_dbus_proxy_call().

The function returns the following values:

  • variant: NULL if error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().

func (*DBusProxy) CallSync 

func (proxy *DBusProxy) CallSync(ctx context.Context, methodName string, parameters *glib.Variant, flags DBusCallFlags, timeoutMsec int) (*glib.Variant, error)

CallSync: synchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the BusConnection associated with proxy is disconnected then the operation will fail with G_IO_ERROR_CLOSED. If cancellable is canceled, the operation will fail with G_IO_ERROR_CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with G_IO_ERROR_INVALID_ARGUMENT.

If the parameters #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.: 

g_dbus_proxy_call_sync (proxy,
                        "TwoStrings",
                        g_variant_new ("(ss)",
                                       "Thing One",
                                       "Thing Two"),
                        G_DBUS_CALL_FLAGS_NONE,
                        -1,
                        NULL,
                        &error);

The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method.

If proxy has an expected interface (see BusProxy:g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • methodName: name of method to invoke.
  • parameters (optional) tuple with parameters for the signal or NULL if not passing parameters.
  • flags flags from the BusCallFlags enumeration.
  • timeoutMsec: timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

The function returns the following values:

  • variant: NULL if error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().

func (*DBusProxy) ConnectGPropertiesChanged 

func (proxy *DBusProxy) ConnectGPropertiesChanged(f func(changedProperties *glib.Variant, invalidatedProperties []string)) coreglib.SignalHandle

ConnectGPropertiesChanged is emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changed_properties and invalidated_properties are guaranteed to never be NULL (either may be empty though).

If the proxy has the flag G_DBUS_PROXY_FLAGS_GET_INVALIDATED_PROPERTIES set, then invalidated_properties will always be empty.

This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.

func (*DBusProxy) ConnectGSignal 

func (proxy *DBusProxy) ConnectGSignal(f func(senderName, signalName string, parameters *glib.Variant)) coreglib.SignalHandle

ConnectGSignal is emitted when a signal from the remote object and interface that proxy is for, has been received.

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signal::x in order to receive callbacks only when signal x is received from the remote object.

func (*DBusProxy) Connection 

func (proxy *DBusProxy) Connection() *DBusConnection

Connection gets the connection proxy is for.

The function returns the following values:

  • dBusConnection owned by proxy. Do not free.

func (*DBusProxy) DefaultTimeout 

func (proxy *DBusProxy) DefaultTimeout() int

DefaultTimeout gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the BusProxy:g-default-timeout property for more details.

The function returns the following values:

  • gint: timeout to use for proxy.

func (*DBusProxy) Flags 

func (proxy *DBusProxy) Flags() DBusProxyFlags

Flags gets the flags that proxy was constructed with.

The function returns the following values:

  • dBusProxyFlags flags from the BusProxyFlags enumeration.

func (*DBusProxy) InterfaceInfo 

func (proxy *DBusProxy) InterfaceInfo() *DBusInterfaceInfo

InterfaceInfo returns the BusInterfaceInfo, if any, specifying the interface that proxy conforms to. See the BusProxy:g-interface-info property for more details.

The function returns the following values:

  • dBusInterfaceInfo (optional) or NULL. Do not unref the returned object, it is owned by proxy.

func (*DBusProxy) InterfaceName 

func (proxy *DBusProxy) InterfaceName() string

InterfaceName gets the D-Bus interface name proxy is for.

The function returns the following values:

  • utf8: string owned by proxy. Do not free.

func (*DBusProxy) Name 

func (proxy *DBusProxy) Name() string

Name gets the name that proxy was constructed for.

When connected to a message bus, this will usually be non-NULL. However, it may be NULL for a proxy that communicates using a peer-to-peer pattern.

The function returns the following values:

  • utf8 (optional): string owned by proxy. Do not free.

func (*DBusProxy) NameOwner 

func (proxy *DBusProxy) NameOwner() string

NameOwner: unique name that owns the name that proxy is for or NULL if no-one currently owns that name. You may connect to the #GObject::notify signal to track changes to the BusProxy:g-name-owner property.

The function returns the following values:

  • utf8 (optional): name owner or NULL if no name owner exists. Free with g_free().

func (*DBusProxy) ObjectPath 

func (proxy *DBusProxy) ObjectPath() string

ObjectPath gets the object path proxy is for.

The function returns the following values:

  • utf8: string owned by proxy. Do not free.

func (*DBusProxy) SetCachedProperty 

func (proxy *DBusProxy) SetCachedProperty(propertyName string, value *glib.Variant)

SetCachedProperty: if value is not NULL, sets the cached value for the property with name property_name to the value in value.

If value is NULL, then the cached value is removed from the property cache.

If proxy has an expected interface (see BusProxy:g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

If the value #GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g. 

g_dbus_proxy_set_cached_property (proxy,
                                  "SomeProperty",
                                  g_variant_new ("(si)",
                                                "A String",
                                                42));

Normally you will not need to use this method since proxy is tracking changes using the org.freedesktop.DBus.Properties.PropertiesChanged D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property ChatroomParticipants which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals ChatroomParticipantJoined(String name) and ChatroomParticipantParted(String name).

The function takes the following parameters:

  • propertyName: property name.
  • value (optional): value for the property or NULL to remove it from the cache.

func (*DBusProxy) SetDefaultTimeout 

func (proxy *DBusProxy) SetDefaultTimeout(timeoutMsec int)

SetDefaultTimeout sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the BusProxy:g-default-timeout property for more details.

The function takes the following parameters:

  • timeoutMsec: timeout in milliseconds.

func (*DBusProxy) SetInterfaceInfo 

func (proxy *DBusProxy) SetInterfaceInfo(info *DBusInterfaceInfo)

SetInterfaceInfo: ensure that interactions with proxy conform to the given interface. See the BusProxy:g-interface-info property for more details.

The function takes the following parameters:

  • info (optional): minimum interface this proxy conforms to or NULL to unset.

type DBusProxyClass added in v0.0.5 

type DBusProxyClass struct {
	// contains filtered or unexported fields
}

DBusProxyClass class structure for BusProxy.

An instance of this type is always passed by reference.

type DBusProxyFlags 

type DBusProxyFlags C.guint

DBusProxyFlags flags used when constructing an instance of a BusProxy derived class. 

const (
	// DBusProxyFlagsNone: no flags set.
	DBusProxyFlagsNone DBusProxyFlags = 0b0
	// DBusProxyFlagsDoNotLoadProperties: don't load properties.
	DBusProxyFlagsDoNotLoadProperties DBusProxyFlags = 0b1
	// DBusProxyFlagsDoNotConnectSignals: don't connect to signals on the remote
	// object.
	DBusProxyFlagsDoNotConnectSignals DBusProxyFlags = 0b10
	// DBusProxyFlagsDoNotAutoStart: if the proxy is for a well-known name,
	// do not ask the bus to launch an owner during proxy initialization or
	// a method call. This flag is only meaningful in proxies for well-known
	// names.
	DBusProxyFlagsDoNotAutoStart DBusProxyFlags = 0b100
	// DBusProxyFlagsGetInvalidatedProperties: if set,
	// the property value for any __invalidated property__ will be
	// (asynchronously) retrieved upon receiving the PropertiesChanged
	// (http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
	// D-Bus signal and the property will not cause emission of the
	// BusProxy::g-properties-changed signal. When the value is received the
	// BusProxy::g-properties-changed signal is emitted for the property along
	// with the retrieved value. Since 2.32.
	DBusProxyFlagsGetInvalidatedProperties DBusProxyFlags = 0b1000
	// DBusProxyFlagsDoNotAutoStartAtConstruction: if the proxy is for a
	// well-known name, do not ask the bus to launch an owner during proxy
	// initialization, but allow it to be autostarted by a method call.
	// This flag is only meaningful in proxies for well-known names, and only if
	// G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is not also specified.
	DBusProxyFlagsDoNotAutoStartAtConstruction DBusProxyFlags = 0b10000
	// DBusProxyFlagsNoMatchRule: don't actually send the AddMatch D-Bus call
	// for this signal subscription. This gives you more control over which
	// match rules you add (but you must add them manually). (Since: 2.72).
	DBusProxyFlagsNoMatchRule DBusProxyFlags = 0b100000
)

func (DBusProxyFlags) Has 

func (d DBusProxyFlags) Has(other DBusProxyFlags) bool

Has returns true if d contains other.

func (DBusProxyFlags) String 

func (d DBusProxyFlags) String() string

String returns the names in string for DBusProxyFlags.

type DBusProxyOverrides added in v0.0.5 

type DBusProxyOverrides struct {
	// GSignal: signal class handler for the BusProxy::g-signal signal.
	//
	// The function takes the following parameters:
	//
	//   - senderName
	//   - signalName
	//   - parameters
	GSignal func(senderName, signalName string, parameters *glib.Variant)
}

DBusProxyOverrides contains methods that are overridable.

type DBusSendMessageFlags 

type DBusSendMessageFlags C.guint

DBusSendMessageFlags flags used when sending BusMessages on a BusConnection. 

const (
	// DBusSendMessageFlagsNone: no flags set.
	DBusSendMessageFlagsNone DBusSendMessageFlags = 0b0
	// DBusSendMessageFlagsPreserveSerial: do not automatically assign a serial
	// number from the BusConnection object when sending a message.
	DBusSendMessageFlagsPreserveSerial DBusSendMessageFlags = 0b1
)

func (DBusSendMessageFlags) Has 

func (d DBusSendMessageFlags) Has(other DBusSendMessageFlags) bool

Has returns true if d contains other.

func (DBusSendMessageFlags) String 

func (d DBusSendMessageFlags) String() string

String returns the names in string for DBusSendMessageFlags.

type DBusServer 

type DBusServer struct {
	*coreglib.Object

	Initable
	// contains filtered or unexported fields
}

DBusServer: GDBusServer is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or implement the org.freedesktop.DBus interface (https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages).

To just export an object on a well-known name on a message bus, such as the session or system bus, you should instead use gio.BusOwnName().

An example of peer-to-peer communication with GDBus can be found in gdbus-example-peer.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).

Note that a minimal GDBusServer will accept connections from any peer. In many use-cases it will be necessary to add a gio.DBusAuthObserver that only accepts connections that have successfully authenticated as the same user that is running the GDBusServer. Since GLib 2.68 this can be achieved more simply by passing the G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.

func NewDBusServerSync 

func NewDBusServerSync(ctx context.Context, address string, flags DBusServerFlags, guid string, observer *DBusAuthObserver) (*DBusServer, error)

NewDBusServerSync creates a new D-Bus server that listens on the first address in address that works.

Once constructed, you can use g_dbus_server_get_client_address() to get a D-Bus address string that clients can use to connect.

To have control over the available authentication mechanisms and the users that are authorized to connect, it is strongly recommended to provide a non-NULL BusAuthObserver.

Connect to the BusServer::new-connection signal to handle incoming connections.

The returned BusServer isn't active - you have to start it with g_dbus_server_start().

BusServer is used in this [example][gdbus-peer-to-peer].

This is a synchronous failable constructor. There is currently no asynchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address d-Bus address.
  • flags flags from the BusServerFlags enumeration.
  • guid d-Bus GUID.
  • observer (optional) or NULL.

The function returns the following values:

  • dBusServer or NULL if error is set. Free with g_object_unref().

func (*DBusServer) ClientAddress 

func (server *DBusServer) ClientAddress() string

ClientAddress gets a D-Bus address (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) string that can be used by clients to connect to server.

This is valid and non-empty if initializing the BusServer succeeded.

The function returns the following values:

  • utf8 d-Bus address string. Do not free, the string is owned by server.

func (*DBusServer) ConnectNewConnection 

func (server *DBusServer) ConnectNewConnection(f func(connection *DBusConnection) (ok bool)) coreglib.SignalHandle

ConnectNewConnection is emitted when a new authenticated connection has been made. Use g_dbus_connection_get_peer_credentials() to figure out what identity (if any), was authenticated.

If you want to accept the connection, take a reference to the connection object and return TRUE. When you are done with the connection call g_dbus_connection_close() and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the BusConnection::closed signal.

If BusServer:flags contains G_DBUS_SERVER_FLAGS_RUN_IN_THREAD then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the [thread-default main context][g-main-context-push-thread-default] of the thread that server was constructed in.

You are guaranteed that signal handlers for this signal runs before incoming messages on connection are processed. This means that it's suitable to call g_dbus_connection_register_object() or similar from the signal handler.

func (*DBusServer) Flags 

func (server *DBusServer) Flags() DBusServerFlags

Flags gets the flags for server.

The function returns the following values:

  • dBusServerFlags: set of flags from the BusServerFlags enumeration.

func (*DBusServer) GUID 

func (server *DBusServer) GUID() string

GUID gets the GUID for server, as provided to g_dbus_server_new_sync().

The function returns the following values:

  • utf8 d-Bus GUID. Do not free this string, it is owned by server.

func (*DBusServer) IsActive 

func (server *DBusServer) IsActive() bool

IsActive gets whether server is active.

The function returns the following values:

  • ok: TRUE if server is active, FALSE otherwise.

func (*DBusServer) Start 

func (server *DBusServer) Start()

Start starts server.

func (*DBusServer) Stop 

func (server *DBusServer) Stop()

Stop stops server.

type DBusServerFlags 

type DBusServerFlags C.guint

DBusServerFlags flags used when creating a BusServer. 

const (
	// DBusServerFlagsNone: no flags set.
	DBusServerFlagsNone DBusServerFlags = 0b0
	// DBusServerFlagsRunInThread: all BusServer::new-connection signals will
	// run in separated dedicated threads (see signal for details).
	DBusServerFlagsRunInThread DBusServerFlags = 0b1
	// DBusServerFlagsAuthenticationAllowAnonymous: allow the anonymous
	// authentication method.
	DBusServerFlagsAuthenticationAllowAnonymous DBusServerFlags = 0b10
	// DBusServerFlagsAuthenticationRequireSameUser: require the UID of the
	// peer to be the same as the UID of the server when authenticating. (Since:
	// 2.68).
	DBusServerFlagsAuthenticationRequireSameUser DBusServerFlags = 0b100
)

func (DBusServerFlags) Has 

func (d DBusServerFlags) Has(other DBusServerFlags) bool

Has returns true if d contains other.

func (DBusServerFlags) String 

func (d DBusServerFlags) String() string

String returns the names in string for DBusServerFlags.

type DBusSignalCallback 

type DBusSignalCallback func(connection *DBusConnection, senderName, objectPath, interfaceName, signalName string, parameters *glib.Variant)

DBusSignalCallback: signature for callback function used in g_dbus_connection_signal_subscribe().

type DBusSignalFlags 

type DBusSignalFlags C.guint

DBusSignalFlags flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). 

const (
	// DBusSignalFlagsNone: no flags set.
	DBusSignalFlagsNone DBusSignalFlags = 0b0
	// DBusSignalFlagsNoMatchRule: don't actually send the AddMatch D-Bus call
	// for this signal subscription. This gives you more control over which
	// match rules you add (but you must add them manually).
	DBusSignalFlagsNoMatchRule DBusSignalFlags = 0b1
	// DBusSignalFlagsMatchArg0Namespace: match first arguments that contain a
	// bus or interface name with the given namespace.
	DBusSignalFlagsMatchArg0Namespace DBusSignalFlags = 0b10
	// DBusSignalFlagsMatchArg0Path: match first arguments that contain an
	// object path that is either equivalent to the given path, or one of the
	// paths is a subpath of the other.
	DBusSignalFlagsMatchArg0Path DBusSignalFlags = 0b100
)

func (DBusSignalFlags) Has 

func (d DBusSignalFlags) Has(other DBusSignalFlags) bool

Has returns true if d contains other.

func (DBusSignalFlags) String 

func (d DBusSignalFlags) String() string

String returns the names in string for DBusSignalFlags.

type DBusSignalInfo 

type DBusSignalInfo struct {
	// contains filtered or unexported fields
}

DBusSignalInfo: information about a signal on a D-Bus interface.

An instance of this type is always passed by reference.

func (*DBusSignalInfo) Annotations 

func (d *DBusSignalInfo) Annotations() []*DBusAnnotationInfo

Annotations: pointer to a NULL-terminated array of pointers to BusAnnotationInfo structures or NULL if there are no annotations.

func (*DBusSignalInfo) Args 

func (d *DBusSignalInfo) Args() []*DBusArgInfo

Args: pointer to a NULL-terminated array of pointers to BusArgInfo structures or NULL if there are no arguments.

func (*DBusSignalInfo) Name 

func (d *DBusSignalInfo) Name() string

Name: name of the D-Bus signal, e.g. "NameOwnerChanged".

func (*DBusSignalInfo) RefCount 

func (d *DBusSignalInfo) RefCount() int

RefCount: reference count or -1 if statically allocated.

func (*DBusSignalInfo) SetRefCount 

func (d *DBusSignalInfo) SetRefCount(refCount int)

RefCount: reference count or -1 if statically allocated.

type DBusSubtreeDispatchFunc 

type DBusSubtreeDispatchFunc func(connection *DBusConnection, sender, objectPath, interfaceName, node string) (outUserData unsafe.Pointer, dBusInterfaceVTable *DBusInterfaceVTable)

DBusSubtreeDispatchFunc: type of the dispatch function in BusSubtreeVTable.

Subtrees are flat. node, if non-NULL, is always exactly one segment of the object path (ie: it never contains a slash).

type DBusSubtreeEnumerateFunc 

type DBusSubtreeEnumerateFunc func(connection *DBusConnection, sender, objectPath string) (utf8s []string)

DBusSubtreeEnumerateFunc: type of the enumerate function in BusSubtreeVTable.

This function is called when generating introspection data and also when preparing to dispatch incoming messages in the event that the G_DBUS_SUBTREE_FLAGS_DISPATCH_TO_UNENUMERATED_NODES flag is not specified (ie: to verify that the object path is valid).

Hierarchies are not supported; the items that you return should not contain the / character.

The return value will be freed with g_strfreev().

type DBusSubtreeFlags 

type DBusSubtreeFlags C.guint

DBusSubtreeFlags flags passed to g_dbus_connection_register_subtree(). 

const (
	// DBusSubtreeFlagsNone: no flags set.
	DBusSubtreeFlagsNone DBusSubtreeFlags = 0b0
	// DBusSubtreeFlagsDispatchToUnenumeratedNodes: method calls to objects not
	// in the enumerated range will still be dispatched. This is useful if you
	// want to dynamically spawn objects in the subtree.
	DBusSubtreeFlagsDispatchToUnenumeratedNodes DBusSubtreeFlags = 0b1
)

func (DBusSubtreeFlags) Has 

func (d DBusSubtreeFlags) Has(other DBusSubtreeFlags) bool

Has returns true if d contains other.

func (DBusSubtreeFlags) String 

func (d DBusSubtreeFlags) String() string

String returns the names in string for DBusSubtreeFlags.

type DBusSubtreeIntrospectFunc 

type DBusSubtreeIntrospectFunc func(connection *DBusConnection, sender, objectPath, node string) (dBusInterfaceInfos []*DBusInterfaceInfo)

DBusSubtreeIntrospectFunc: type of the introspect function in BusSubtreeVTable.

Subtrees are flat. node, if non-NULL, is always exactly one segment of the object path (ie: it never contains a slash).

This function should return NULL to indicate that there is no object at this node.

If this function returns non-NULL, the return value is expected to be a NULL-terminated array of pointers to BusInterfaceInfo structures describing the interfaces implemented by node. This array will have g_dbus_interface_info_unref() called on each item before being freed with g_free().

The difference between returning NULL and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the NULL case.

type DBusSubtreeVTable 

type DBusSubtreeVTable struct {
	// contains filtered or unexported fields
}

DBusSubtreeVTable: virtual table for handling subtrees registered with g_dbus_connection_register_subtree().

An instance of this type is always passed by reference.

type DTLSClientConnection 

type DTLSClientConnection struct {
	DTLSConnection
	// contains filtered or unexported fields
}

DTLSClientConnection: GDtlsClientConnection is the client-side subclass of gio.DTLSConnection, representing a client-side DTLS connection.

DTLSClientConnection wraps an interface. This means the user can get the underlying type by calling Cast().

func NewDTLSClientConnection 

func NewDTLSClientConnection(baseSocket DatagramBasedder, serverIdentity SocketConnectabler) (*DTLSClientConnection, error)

NewDTLSClientConnection creates a new ClientConnection wrapping base_socket which is assumed to communicate with the server identified by server_identity.

The function takes the following parameters:

  • baseSocket to wrap.
  • serverIdentity (optional): expected identity of the server.

The function returns the following values:

  • dtlsClientConnection: new ClientConnection, or NULL on error.

func (*DTLSClientConnection) ServerIdentity 

func (conn *DTLSClientConnection) ServerIdentity() *SocketConnectable

ServerIdentity gets conn's expected server identity.

The function returns the following values:

  • socketConnectable describing the expected server identity, or NULL if the expected identity is not known.

func (*DTLSClientConnection) SetServerIdentity 

func (conn *DTLSClientConnection) SetServerIdentity(identity SocketConnectabler)

SetServerIdentity sets conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let conn know what name to look for in the certificate when performing G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.

The function takes the following parameters:

  • identity describing the expected server identity.

func (*DTLSClientConnection) SetValidationFlags deprecated 

func (conn *DTLSClientConnection) SetValidationFlags(flags TLSCertificateFlags)

SetValidationFlags sets conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, G_TLS_CERTIFICATE_VALIDATE_ALL is used.

This function does not work as originally designed and is impossible to use correctly. See ClientConnection:validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function takes the following parameters:

  • flags to use.

func (*DTLSClientConnection) ValidationFlags deprecated 

func (conn *DTLSClientConnection) ValidationFlags() TLSCertificateFlags

ValidationFlags gets conn's validation flags

This function does not work as originally designed and is impossible to use correctly. See ClientConnection:validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function returns the following values:

  • tlsCertificateFlags: validation flags.

type DTLSClientConnectionInterface added in v0.0.5 

type DTLSClientConnectionInterface struct {
	// contains filtered or unexported fields
}

DTLSClientConnectionInterface: vtable for a ClientConnection implementation.

An instance of this type is always passed by reference.

type DTLSClientConnectionOverrider 

type DTLSClientConnectionOverrider interface {
}

DTLSClientConnectionOverrider contains methods that are overridable.

type DTLSClientConnectioner 

type DTLSClientConnectioner interface {
	coreglib.Objector

	// ServerIdentity gets conn's expected server identity.
	ServerIdentity() *SocketConnectable
	// ValidationFlags gets conn's validation flags.
	ValidationFlags() TLSCertificateFlags
	// SetServerIdentity sets conn's expected server identity, which is used
	// both to tell servers on virtual hosts which certificate to present,
	// and also to let conn know what name to look for in the certificate when
	// performing G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
	SetServerIdentity(identity SocketConnectabler)
	// SetValidationFlags sets conn's validation flags, to override the default
	// set of checks performed when validating a server certificate.
	SetValidationFlags(flags TLSCertificateFlags)
}

DTLSClientConnectioner describes DTLSClientConnection's interface methods.

type DTLSConnection 

type DTLSConnection struct {
	DatagramBased
	// contains filtered or unexported fields
}

DTLSConnection: GDtlsConnection is the base DTLS connection class type, which wraps a gio.DatagramBased and provides DTLS encryption on top of it. Its subclasses, gio.DTLSClientConnection and gio.DTLSServerConnection, implement client-side and server-side DTLS, respectively.

For TLS support, see gio.TLSConnection.

As DTLS is datagram based, GDtlsConnection implements gio.DatagramBased, presenting a datagram-socket-like API for the encrypted connection. This operates over a base datagram connection, which is also a GDatagramBased (gio.DTLSConnection:base-socket).

To close a DTLS connection, use gio.DTLSConnection.Close().

Neither gio.DTLSServerConnection or gio.DTLSClientConnection set the peer address on their base gio.DatagramBased if it is a gio.Socket — it is up to the caller to do that if they wish. If they do not, and gio.Socket.Close() is called on the base socket, the GDtlsConnection will not raise a G_IO_ERROR_NOT_CONNECTED error on further I/O.

DTLSConnection wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DTLSConnection) Certificate 

func (conn *DTLSConnection) Certificate() TLSCertificater

Certificate gets conn's certificate, as set by g_dtls_connection_set_certificate().

The function returns the following values:

  • tlsCertificate (optional) conn's certificate, or NULL.

func (*DTLSConnection) ChannelBindingData 

func (conn *DTLSConnection) ChannelBindingData(typ TLSChannelBindingType) ([]byte, error)

ChannelBindingData: query the TLS backend for TLS channel binding data of type for conn.

This call retrieves TLS channel binding data as specified in RFC 5056 (https://tools.ietf.org/html/rfc5056), RFC 5929 (https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in data. The data is resized by the callee using Array buffer management and will be freed when the data is destroyed by g_byte_array_unref(). If data is NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support type or the binding data is not available yet due to additional negotiation or input required.

The function takes the following parameters:

  • typ type of data to fetch.

The function returns the following values:

  • data (optional) is filled with the binding data, or NULL.

func (*DTLSConnection) CiphersuiteName added in v0.3.0 

func (conn *DTLSConnection) CiphersuiteName() string

CiphersuiteName returns the name of the current DTLS ciphersuite, or NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended.

The function returns the following values:

  • utf8 (optional): name of the current DTLS ciphersuite, or NULL.

func (*DTLSConnection) Close 

func (conn *DTLSConnection) Close(ctx context.Context) error

Close the DTLS connection. This is equivalent to calling g_dtls_connection_shutdown() to shut down both sides of the connection.

Closing a Connection waits for all buffered but untransmitted data to be sent before it completes. It then sends a close_notify DTLS alert to the peer and may wait for a close_notify to be received from the peer. It does not close the underlying Connection:base-socket; that must be closed separately.

Once conn is closed, all other operations will return G_IO_ERROR_CLOSED. Closing a Connection multiple times will not return an error.

Connections will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

If cancellable is cancelled, the Connection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_close() again to complete closing the Connection.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*DTLSConnection) CloseAsync 

func (conn *DTLSConnection) CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

CloseAsync: asynchronously close the DTLS connection. See g_dtls_connection_close() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the close operation is complete.

func (*DTLSConnection) CloseFinish 

func (conn *DTLSConnection) CloseFinish(result AsyncResulter) error

CloseFinish: finish an asynchronous TLS close operation. See g_dtls_connection_close() for more information.

The function takes the following parameters:

  • result: Result.

func (*DTLSConnection) ConnectAcceptCertificate 

func (conn *DTLSConnection) ConnectAcceptCertificate(f func(peerCert TLSCertificater, errors TLSCertificateFlags) (ok bool)) coreglib.SignalHandle

ConnectAcceptCertificate is emitted during the TLS handshake after the peer certificate has been received. You can examine peer_cert's certification path by calling g_tls_certificate_get_issuer() on it.

For a client-side connection, peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to conn's ClientConnection:validation_flags. If you would like the certificate to be accepted despite errors, return TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with G_TLS_ERROR_BAD_CERTIFICATE.

GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate.

For a server-side connection, peer_cert is the certificate presented by the client, if this was requested via the server's ServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns TRUE.

Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return FALSE from the signal handler on the first attempt, and then after the connection attempt returns a G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return TRUE from the signal handler the next time.

If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer.

func (*DTLSConnection) Database 

func (conn *DTLSConnection) Database() TLSDatabaser

Database gets the certificate database that conn uses to verify peer certificates. See g_dtls_connection_set_database().

The function returns the following values:

  • tlsDatabase (optional): certificate database that conn uses or NULL.

func (*DTLSConnection) EmitAcceptCertificate 

func (conn *DTLSConnection) EmitAcceptCertificate(peerCert TLSCertificater, errors TLSCertificateFlags) bool

EmitAcceptCertificate: used by Connection implementations to emit the Connection::accept-certificate signal.

The function takes the following parameters:

  • peerCert peer's Certificate.
  • errors problems with peer_cert.

The function returns the following values:

  • ok: TRUE if one of the signal handlers has returned TRUE to accept peer_cert.

func (*DTLSConnection) Handshake 

func (conn *DTLSConnection) Handshake(ctx context.Context) error

Handshake attempts a TLS handshake on conn.

On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting, Connection will handle this for you automatically when you try to send or receive data on the connection. You can call g_dtls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable.

Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting.

Previously, calling g_dtls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything.

Connection::accept_certificate may be emitted during the handshake.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*DTLSConnection) HandshakeAsync 

func (conn *DTLSConnection) HandshakeAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

HandshakeAsync: asynchronously performs a TLS handshake on conn. See g_dtls_connection_handshake() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the handshake is complete.

func (*DTLSConnection) HandshakeFinish 

func (conn *DTLSConnection) HandshakeFinish(result AsyncResulter) error

HandshakeFinish: finish an asynchronous TLS handshake operation. See g_dtls_connection_handshake() for more information.

The function takes the following parameters:

  • result: Result.

func (*DTLSConnection) Interaction 

func (conn *DTLSConnection) Interaction() *TLSInteraction

Interaction: get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If NULL is returned, then no user interaction will occur for this connection.

The function returns the following values:

  • tlsInteraction (optional): interaction object.

func (*DTLSConnection) NegotiatedProtocol 

func (conn *DTLSConnection) NegotiatedProtocol() string

NegotiatedProtocol gets the name of the application-layer protocol negotiated during the handshake.

If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of conn's protocols, or the TLS backend does not support ALPN, then this will be NULL. See g_dtls_connection_set_advertised_protocols().

The function returns the following values:

  • utf8 (optional): negotiated protocol, or NULL.

func (*DTLSConnection) PeerCertificate 

func (conn *DTLSConnection) PeerCertificate() TLSCertificater

PeerCertificate gets conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of Connection::accept-certificate.).

The function returns the following values:

  • tlsCertificate (optional) conn's peer's certificate, or NULL.

func (*DTLSConnection) PeerCertificateErrors 

func (conn *DTLSConnection) PeerCertificateErrors() TLSCertificateFlags

PeerCertificateErrors gets the errors associated with validating conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of Connection::accept-certificate.).

The function returns the following values:

  • tlsCertificateFlags conn's peer's certificate errors.

func (*DTLSConnection) ProtocolVersion added in v0.3.0 

func (conn *DTLSConnection) ProtocolVersion() TLSProtocolVersion

ProtocolVersion returns the current DTLS protocol version, which may be G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized ProtocolVersion.

The function returns the following values:

  • tlsProtocolVersion: current DTLS protocol version.

func (*DTLSConnection) RehandshakeMode deprecated 

func (conn *DTLSConnection) RehandshakeMode() TLSRehandshakeMode

RehandshakeMode gets conn rehandshaking mode. See g_dtls_connection_set_rehandshake_mode() for details.

Deprecated: Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3.

The function returns the following values:

  • tlsRehandshakeMode: G_TLS_REHANDSHAKE_SAFELY.

func (*DTLSConnection) RequireCloseNotify 

func (conn *DTLSConnection) RequireCloseNotify() bool

RequireCloseNotify tests whether or not conn expects a proper TLS close notification when the connection is closed. See g_dtls_connection_set_require_close_notify() for details.

The function returns the following values:

  • ok: TRUE if conn requires a proper TLS close notification.

func (*DTLSConnection) SetAdvertisedProtocols 

func (conn *DTLSConnection) SetAdvertisedProtocols(protocols []string)

SetAdvertisedProtocols sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_dtls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying NULL for the the value of protocols will disable ALPN negotiation.

See IANA TLS ALPN Protocol IDs (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs.

The function takes the following parameters:

  • protocols (optional): NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or NULL.

func (*DTLSConnection) SetCertificate 

func (conn *DTLSConnection) SetCertificate(certificate TLSCertificater)

SetCertificate: this sets the certificate that conn will present to its peer during the TLS handshake. For a ServerConnection, it is mandatory to set this, and that will normally be done at construct time.

For a ClientConnection, this is optional. If a handshake fails with G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server requires a certificate, and if you try connecting again, you should call this method first. You can call g_dtls_client_connection_get_accepted_cas() on the failed connection to get a list of Certificate Authorities that the server will accept certificates from.

(It is also possible that a server will allow the connection with or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_dtls_client_connection_get_accepted_cas() will return non-NULL.).

The function takes the following parameters:

  • certificate to use for conn.

func (*DTLSConnection) SetDatabase 

func (conn *DTLSConnection) SetDatabase(database TLSDatabaser)

SetDatabase sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to NULL, then peer certificate validation will always set the G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning Connection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in ClientConnection:validation-flags).

There are nonintuitive security implications when using a non-default database. See Connection:database for details.

The function takes the following parameters:

  • database (optional): Database.

func (*DTLSConnection) SetInteraction 

func (conn *DTLSConnection) SetInteraction(interaction *TLSInteraction)

SetInteraction: set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords.

The interaction argument will normally be a derived subclass of Interaction. NULL can also be provided if no user interaction should occur for this connection.

The function takes the following parameters:

  • interaction (optional) object, or NULL.

func (*DTLSConnection) SetRehandshakeMode deprecated 

func (conn *DTLSConnection) SetRehandshakeMode(mode TLSRehandshakeMode)

SetRehandshakeMode: since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations.

Deprecated: Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3.

The function takes the following parameters:

  • mode: rehandshaking mode.

func (*DTLSConnection) SetRequireCloseNotify 

func (conn *DTLSConnection) SetRequireCloseNotify(requireCloseNotify bool)

SetRequireCloseNotify sets whether or not conn expects a proper TLS close notification before the connection is closed. If this is TRUE (the default), then conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a G_TLS_ERROR_EOF error if the connection is closed without proper notification (since this may indicate a network error, or man-in-the-middle attack).

In some protocols, the application will know whether or not the connection was closed cleanly based on application-level data (because the application-level data includes a length field, or is somehow self-delimiting); in this case, the close notify is redundant and may be omitted. You can use g_dtls_connection_set_require_close_notify() to tell conn to allow an "unannounced" connection close, in which case the close will show up as a 0-length read, as in a non-TLS Based, and it is up to the application to check that the data has been fully received.

Note that this only affects the behavior when the peer closes the connection; when the application calls g_dtls_connection_close_async() on conn itself, this will send a close notification regardless of the setting of this property. If you explicitly want to do an unclean close, you can close conn's Connection:base-socket rather than closing conn itself.

The function takes the following parameters:

  • requireCloseNotify: whether or not to require close notification.

func (*DTLSConnection) Shutdown 

func (conn *DTLSConnection) Shutdown(ctx context.Context, shutdownRead, shutdownWrite bool) error

Shutdown: shut down part or all of a DTLS connection.

If shutdown_read is TRUE then the receiving side of the connection is shut down, and further reading is disallowed. Subsequent calls to g_datagram_based_receive_messages() will return G_IO_ERROR_CLOSED.

If shutdown_write is TRUE then the sending side of the connection is shut down, and further writing is disallowed. Subsequent calls to g_datagram_based_send_messages() will return G_IO_ERROR_CLOSED.

It is allowed for both shutdown_read and shutdown_write to be TRUE — this is equivalent to calling g_dtls_connection_close().

If cancellable is cancelled, the Connection may be left partially-closed and any pending untransmitted data may be lost. Call g_dtls_connection_shutdown() again to complete closing the Connection.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • shutdownRead: TRUE to stop reception of incoming datagrams.
  • shutdownWrite: TRUE to stop sending outgoing datagrams.

func (*DTLSConnection) ShutdownAsync 

func (conn *DTLSConnection) ShutdownAsync(ctx context.Context, shutdownRead, shutdownWrite bool, ioPriority int, callback AsyncReadyCallback)

ShutdownAsync: asynchronously shut down part or all of the DTLS connection. See g_dtls_connection_shutdown() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • shutdownRead: TRUE to stop reception of incoming datagrams.
  • shutdownWrite: TRUE to stop sending outgoing datagrams.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the shutdown operation is complete.

func (*DTLSConnection) ShutdownFinish 

func (conn *DTLSConnection) ShutdownFinish(result AsyncResulter) error

ShutdownFinish: finish an asynchronous TLS shutdown operation. See g_dtls_connection_shutdown() for more information.

The function takes the following parameters:

  • result: Result.

type DTLSConnectionInterface added in v0.0.5 

type DTLSConnectionInterface struct {
	// contains filtered or unexported fields
}

DTLSConnectionInterface: virtual method table for a Connection implementation.

An instance of this type is always passed by reference.

type DTLSConnectioner 

type DTLSConnectioner interface {
	coreglib.Objector

	// Close the DTLS connection.
	Close(ctx context.Context) error
	// CloseAsync: asynchronously close the DTLS connection.
	CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// CloseFinish: finish an asynchronous TLS close operation.
	CloseFinish(result AsyncResulter) error
	// EmitAcceptCertificate: used by Connection implementations to emit the
	// Connection::accept-certificate signal.
	EmitAcceptCertificate(peerCert TLSCertificater, errors TLSCertificateFlags) bool
	// Certificate gets conn's certificate, as set by
	// g_dtls_connection_set_certificate().
	Certificate() TLSCertificater
	// ChannelBindingData: query the TLS backend for TLS channel binding data of
	// type for conn.
	ChannelBindingData(typ TLSChannelBindingType) ([]byte, error)
	// CiphersuiteName returns the name of the current DTLS ciphersuite,
	// or NULL if the connection has not handshaked or has been closed.
	CiphersuiteName() string
	// Database gets the certificate database that conn uses to verify peer
	// certificates.
	Database() TLSDatabaser
	// Interaction: get the object that will be used to interact with the user.
	Interaction() *TLSInteraction
	// NegotiatedProtocol gets the name of the application-layer protocol
	// negotiated during the handshake.
	NegotiatedProtocol() string
	// PeerCertificate gets conn's peer's certificate after the handshake has
	// completed or failed.
	PeerCertificate() TLSCertificater
	// PeerCertificateErrors gets the errors associated with validating conn's
	// peer's certificate, after the handshake has completed or failed.
	PeerCertificateErrors() TLSCertificateFlags
	// ProtocolVersion returns the current DTLS protocol version, which may be
	// G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked,
	// or has been closed, or if the TLS backend has implemented a protocol
	// version that is not a recognized ProtocolVersion.
	ProtocolVersion() TLSProtocolVersion
	// RehandshakeMode gets conn rehandshaking mode.
	RehandshakeMode() TLSRehandshakeMode
	// RequireCloseNotify tests whether or not conn expects a proper TLS close
	// notification when the connection is closed.
	RequireCloseNotify() bool
	// Handshake attempts a TLS handshake on conn.
	Handshake(ctx context.Context) error
	// HandshakeAsync: asynchronously performs a TLS handshake on conn.
	HandshakeAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// HandshakeFinish: finish an asynchronous TLS handshake operation.
	HandshakeFinish(result AsyncResulter) error
	// SetAdvertisedProtocols sets the list of application-layer protocols to
	// advertise that the caller is willing to speak on this connection.
	SetAdvertisedProtocols(protocols []string)
	// SetCertificate: this sets the certificate that conn will present to its
	// peer during the TLS handshake.
	SetCertificate(certificate TLSCertificater)
	// SetDatabase sets the certificate database that is used to verify peer
	// certificates.
	SetDatabase(database TLSDatabaser)
	// SetInteraction: set the object that will be used to interact with the
	// user.
	SetInteraction(interaction *TLSInteraction)
	// SetRehandshakeMode: since GLib 2.64, changing the rehandshake mode is no
	// longer supported and will have no effect.
	SetRehandshakeMode(mode TLSRehandshakeMode)
	// SetRequireCloseNotify sets whether or not conn expects a proper TLS close
	// notification before the connection is closed.
	SetRequireCloseNotify(requireCloseNotify bool)
	// Shutdown: shut down part or all of a DTLS connection.
	Shutdown(ctx context.Context, shutdownRead, shutdownWrite bool) error
	// ShutdownAsync: asynchronously shut down part or all of the DTLS
	// connection.
	ShutdownAsync(ctx context.Context, shutdownRead, shutdownWrite bool, ioPriority int, callback AsyncReadyCallback)
	// ShutdownFinish: finish an asynchronous TLS shutdown operation.
	ShutdownFinish(result AsyncResulter) error

	// Accept-certificate is emitted during the TLS handshake after the peer
	// certificate has been received.
	ConnectAcceptCertificate(func(peerCert TLSCertificater, errors TLSCertificateFlags) (ok bool)) coreglib.SignalHandle
}

DTLSConnectioner describes DTLSConnection's interface methods.

type DTLSServerConnection 

type DTLSServerConnection struct {
	DTLSConnection
	// contains filtered or unexported fields
}

DTLSServerConnection: GDtlsServerConnection is the server-side subclass of gio.DTLSConnection, representing a server-side DTLS connection.

DTLSServerConnection wraps an interface. This means the user can get the underlying type by calling Cast().

func BaseDTLSServerConnection 

func BaseDTLSServerConnection(obj DTLSServerConnectioner) *DTLSServerConnection

BaseDTLSServerConnection returns the underlying base object.

func NewDTLSServerConnection 

func NewDTLSServerConnection(baseSocket DatagramBasedder, certificate TLSCertificater) (*DTLSServerConnection, error)

NewDTLSServerConnection creates a new ServerConnection wrapping base_socket.

The function takes the following parameters:

  • baseSocket to wrap.
  • certificate (optional): default server certificate, or NULL.

The function returns the following values:

  • dtlsServerConnection: new ServerConnection, or NULL on error.

type DTLSServerConnectionInterface added in v0.0.5 

type DTLSServerConnectionInterface struct {
	// contains filtered or unexported fields
}

DTLSServerConnectionInterface: vtable for a ServerConnection implementation.

An instance of this type is always passed by reference.

type DTLSServerConnectionOverrider 

type DTLSServerConnectionOverrider interface {
}

DTLSServerConnectionOverrider contains methods that are overridable.

type DTLSServerConnectioner 

type DTLSServerConnectioner interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

DTLSServerConnectioner describes DTLSServerConnection's interface methods.

type DataInputStream 

type DataInputStream struct {
	BufferedInputStream
	// contains filtered or unexported fields
}

DataInputStream: data input stream implements gio.InputStream and includes functions for reading structured data directly from a binary input stream.

func NewDataInputStream 

func NewDataInputStream(baseStream InputStreamer) *DataInputStream

NewDataInputStream creates a new data input stream for the base_stream.

The function takes the following parameters:

  • baseStream: Stream.

The function returns the following values:

  • dataInputStream: new InputStream.

func (*DataInputStream) ByteOrder 

func (stream *DataInputStream) ByteOrder() DataStreamByteOrder

ByteOrder gets the byte order for the data input stream.

The function returns the following values:

  • dataStreamByteOrder stream's current StreamByteOrder.

func (*DataInputStream) NewlineType 

func (stream *DataInputStream) NewlineType() DataStreamNewlineType

NewlineType gets the current newline type for the stream.

The function returns the following values:

  • dataStreamNewlineType for the given stream.

func (*DataInputStream) ReadByte 

func (stream *DataInputStream) ReadByte(ctx context.Context) (byte, error)

ReadByte reads an unsigned 8-bit/1-byte value from stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • guint8: unsigned 8-bit/1-byte value read from the stream or 0 if an error occurred.

func (*DataInputStream) ReadInt16 

func (stream *DataInputStream) ReadInt16(ctx context.Context) (int16, error)

ReadInt16 reads a 16-bit/2-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • gint16: signed 16-bit/2-byte value read from stream or 0 if an error occurred.

func (*DataInputStream) ReadInt32 

func (stream *DataInputStream) ReadInt32(ctx context.Context) (int32, error)

ReadInt32 reads a signed 32-bit/4-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • gint32: signed 32-bit/4-byte value read from the stream or 0 if an error occurred.

func (*DataInputStream) ReadInt64 

func (stream *DataInputStream) ReadInt64(ctx context.Context) (int64, error)

ReadInt64 reads a 64-bit/8-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • gint64: signed 64-bit/8-byte value read from stream or 0 if an error occurred.

func (*DataInputStream) ReadLine 

func (stream *DataInputStream) ReadLine(ctx context.Context) (uint, []byte, error)

ReadLine reads a line from the data input stream. Note that no encoding checks or conversion is performed; the input is not guaranteed to be UTF-8, and may in fact have embedded NUL characters.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • guint8s (optional): a NUL terminated byte array with the line that was read in (without the newlines). Set length to a #gsize to get the length of the read line. On an error, it will return NULL and error will be set. If there's no content to read, it will still return NULL, but error won't be set.

func (*DataInputStream) ReadLineAsync 

func (stream *DataInputStream) ReadLineAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

ReadLineAsync asynchronous version of g_data_input_stream_read_line(). It is an error to have two outstanding calls to this function.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_line_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*DataInputStream) ReadLineFinish 

func (stream *DataInputStream) ReadLineFinish(result AsyncResulter) (uint, []byte, error)

ReadLineFinish: finish an asynchronous call started by g_data_input_stream_read_line_async(). Note the warning about string encoding in g_data_input_stream_read_line() applies here as well.

The function takes the following parameters:

  • result that was provided to the callback.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • guint8s (optional): a NUL-terminated byte array with the line that was read in (without the newlines). Set length to a #gsize to get the length of the read line. On an error, it will return NULL and error will be set. If there's no content to read, it will still return NULL, but error won't be set.

func (*DataInputStream) ReadLineFinishUTF8 

func (stream *DataInputStream) ReadLineFinishUTF8(result AsyncResulter) (uint, string, error)

ReadLineFinishUTF8: finish an asynchronous call started by g_data_input_stream_read_line_async().

The function takes the following parameters:

  • result that was provided to the callback.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8 (optional): string with the line that was read in (without the newlines). Set length to a #gsize to get the length of the read line. On an error, it will return NULL and error will be set. For UTF-8 conversion errors, the set error domain is G_CONVERT_ERROR. If there's no content to read, it will still return NULL, but error won't be set.

func (*DataInputStream) ReadLineUTF8 

func (stream *DataInputStream) ReadLineUTF8(ctx context.Context) (uint, string, error)

ReadLineUTF8 reads a UTF-8 encoded line from the data input stream.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8 (optional): NUL terminated UTF-8 string with the line that was read in (without the newlines). Set length to a #gsize to get the length of the read line. On an error, it will return NULL and error will be set. For UTF-8 conversion errors, the set error domain is G_CONVERT_ERROR. If there's no content to read, it will still return NULL, but error won't be set.

func (*DataInputStream) ReadUint16 

func (stream *DataInputStream) ReadUint16(ctx context.Context) (uint16, error)

ReadUint16 reads an unsigned 16-bit/2-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • guint16: unsigned 16-bit/2-byte value read from the stream or 0 if an error occurred.

func (*DataInputStream) ReadUint32 

func (stream *DataInputStream) ReadUint32(ctx context.Context) (uint32, error)

ReadUint32 reads an unsigned 32-bit/4-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • guint32: unsigned 32-bit/4-byte value read from the stream or 0 if an error occurred.

func (*DataInputStream) ReadUint64 

func (stream *DataInputStream) ReadUint64(ctx context.Context) (uint64, error)

ReadUint64 reads an unsigned 64-bit/8-byte value from stream.

In order to get the correct byte order for this read operation, see g_data_input_stream_get_byte_order().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • guint64: unsigned 64-bit/8-byte read from stream or 0 if an error occurred.

func (*DataInputStream) ReadUntil deprecated 

func (stream *DataInputStream) ReadUntil(ctx context.Context, stopChars string) (uint, string, error)

ReadUntil reads a string from the data input stream, up to the first occurrence of any of the stop characters.

Note that, in contrast to g_data_input_stream_read_until_async(), this function consumes the stop character that it finds.

Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until_async(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto() instead, but note that that function does not consume the stop character.

Deprecated: Use g_data_input_stream_read_upto() instead, which has more consistent behaviour regarding the stop character.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stopChars characters to terminate the read.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8: string with the data that was read before encountering any of the stop characters. Set length to a #gsize to get the length of the string. This function will return NULL on an error.

func (*DataInputStream) ReadUntilAsync deprecated 

func (stream *DataInputStream) ReadUntilAsync(ctx context.Context, stopChars string, ioPriority int, callback AsyncReadyCallback)

ReadUntilAsync asynchronous version of g_data_input_stream_read_until(). It is an error to have two outstanding calls to this function.

Note that, in contrast to g_data_input_stream_read_until(), this function does not consume the stop character that it finds. You must read it for yourself.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_until_finish() to get the result of the operation.

Don't use this function in new code. Its functionality is inconsistent with g_data_input_stream_read_until(). Both functions will be marked as deprecated in a future release. Use g_data_input_stream_read_upto_async() instead.

Deprecated: Use g_data_input_stream_read_upto_async() instead, which has more consistent behaviour regarding the stop character.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stopChars characters to terminate the read.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*DataInputStream) ReadUntilFinish deprecated 

func (stream *DataInputStream) ReadUntilFinish(result AsyncResulter) (uint, string, error)

ReadUntilFinish: finish an asynchronous call started by g_data_input_stream_read_until_async().

Deprecated: Use g_data_input_stream_read_upto_finish() instead, which has more consistent behaviour regarding the stop character.

The function takes the following parameters:

  • result that was provided to the callback.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8: string with the data that was read before encountering any of the stop characters. Set length to a #gsize to get the length of the string. This function will return NULL on an error.

func (*DataInputStream) ReadUpto 

func (stream *DataInputStream) ReadUpto(ctx context.Context, stopChars string) (uint, string, error)

ReadUpto reads a string from the data input stream, up to the first occurrence of any of the stop characters.

In contrast to g_data_input_stream_read_until(), this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again.

Note that stop_chars may contain '\0' if stop_chars_len is specified.

The returned string will always be nul-terminated on success.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stopChars characters to terminate the read.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8: string with the data that was read before encountering any of the stop characters. Set length to a #gsize to get the length of the string. This function will return NULL on an error.

func (*DataInputStream) ReadUptoAsync 

func (stream *DataInputStream) ReadUptoAsync(ctx context.Context, stopChars string, ioPriority int, callback AsyncReadyCallback)

ReadUptoAsync asynchronous version of g_data_input_stream_read_upto(). It is an error to have two outstanding calls to this function.

In contrast to g_data_input_stream_read_until(), this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto() again.

Note that stop_chars may contain '\0' if stop_chars_len is specified.

When the operation is finished, callback will be called. You can then call g_data_input_stream_read_upto_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stopChars characters to terminate the read.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*DataInputStream) ReadUptoFinish 

func (stream *DataInputStream) ReadUptoFinish(result AsyncResulter) (uint, string, error)

ReadUptoFinish: finish an asynchronous call started by g_data_input_stream_read_upto_async().

Note that this function does not consume the stop character. You have to use g_data_input_stream_read_byte() to get it before calling g_data_input_stream_read_upto_async() again.

The returned string will always be nul-terminated on success.

The function takes the following parameters:

  • result that was provided to the callback.

The function returns the following values:

  • length (optional) to get the length of the data read in.
  • utf8: string with the data that was read before encountering any of the stop characters. Set length to a #gsize to get the length of the string. This function will return NULL on an error.

func (*DataInputStream) SetByteOrder 

func (stream *DataInputStream) SetByteOrder(order DataStreamByteOrder)

SetByteOrder: this function sets the byte order for the given stream. All subsequent reads from the stream will be read in the given order.

The function takes the following parameters:

  • order to set.

func (*DataInputStream) SetNewlineType 

func (stream *DataInputStream) SetNewlineType(typ DataStreamNewlineType)

SetNewlineType sets the newline type for the stream.

Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read chunk ends in "CR" we must read an additional byte to know if this is "CR" or "CR LF", and this might block if there is no more data available.

The function takes the following parameters:

  • typ: type of new line return as StreamNewlineType.

type DataInputStreamClass added in v0.0.5 

type DataInputStreamClass struct {
	// contains filtered or unexported fields
}

DataInputStreamClass: instance of this type is always passed by reference.

func (*DataInputStreamClass) ParentClass added in v0.0.5 

func (d *DataInputStreamClass) ParentClass() *BufferedInputStreamClass

type DataInputStreamOverrides added in v0.0.5 

type DataInputStreamOverrides struct {
}

DataInputStreamOverrides contains methods that are overridable.

type DataOutputStream 

type DataOutputStream struct {
	FilterOutputStream

	Seekable
	// contains filtered or unexported fields
}

DataOutputStream: data output stream implements gio.OutputStream and includes functions for writing data directly to an output stream.

func NewDataOutputStream 

func NewDataOutputStream(baseStream OutputStreamer) *DataOutputStream

NewDataOutputStream creates a new data output stream for base_stream.

The function takes the following parameters:

  • baseStream: Stream.

The function returns the following values:

  • dataOutputStream: OutputStream.

func (*DataOutputStream) ByteOrder 

func (stream *DataOutputStream) ByteOrder() DataStreamByteOrder

ByteOrder gets the byte order for the stream.

The function returns the following values:

  • dataStreamByteOrder for the stream.

func (*DataOutputStream) PutByte 

func (stream *DataOutputStream) PutByte(ctx context.Context, data byte) error

PutByte puts a byte into the output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #guchar.

func (*DataOutputStream) PutInt16 

func (stream *DataOutputStream) PutInt16(ctx context.Context, data int16) error

PutInt16 puts a signed 16-bit integer into the output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #gint16.

func (*DataOutputStream) PutInt32 

func (stream *DataOutputStream) PutInt32(ctx context.Context, data int32) error

PutInt32 puts a signed 32-bit integer into the output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #gint32.

func (*DataOutputStream) PutInt64 

func (stream *DataOutputStream) PutInt64(ctx context.Context, data int64) error

PutInt64 puts a signed 64-bit integer into the stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #gint64.

func (*DataOutputStream) PutString 

func (stream *DataOutputStream) PutString(ctx context.Context, str string) error

PutString puts a string into the output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • str: string.

func (*DataOutputStream) PutUint16 

func (stream *DataOutputStream) PutUint16(ctx context.Context, data uint16) error

PutUint16 puts an unsigned 16-bit integer into the output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #guint16.

func (*DataOutputStream) PutUint32 

func (stream *DataOutputStream) PutUint32(ctx context.Context, data uint32) error

PutUint32 puts an unsigned 32-bit integer into the stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #guint32.

func (*DataOutputStream) PutUint64 

func (stream *DataOutputStream) PutUint64(ctx context.Context, data uint64) error

PutUint64 puts an unsigned 64-bit integer into the stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • data: #guint64.

func (*DataOutputStream) SetByteOrder 

func (stream *DataOutputStream) SetByteOrder(order DataStreamByteOrder)

SetByteOrder sets the byte order of the data output stream to order.

The function takes the following parameters:

  • order: GDataStreamByteOrder.

type DataOutputStreamClass added in v0.0.5 

type DataOutputStreamClass struct {
	// contains filtered or unexported fields
}

DataOutputStreamClass: instance of this type is always passed by reference.

func (*DataOutputStreamClass) ParentClass added in v0.0.5 

func (d *DataOutputStreamClass) ParentClass() *FilterOutputStreamClass

type DataOutputStreamOverrides added in v0.0.5 

type DataOutputStreamOverrides struct {
}

DataOutputStreamOverrides contains methods that are overridable.

type DataStreamByteOrder 

type DataStreamByteOrder C.gint

DataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures. 

const (
	// DataStreamByteOrderBigEndian selects Big Endian byte order.
	DataStreamByteOrderBigEndian DataStreamByteOrder = iota
	// DataStreamByteOrderLittleEndian selects Little Endian byte order.
	DataStreamByteOrderLittleEndian
	// DataStreamByteOrderHostEndian selects endianness based on host machine's
	// architecture.
	DataStreamByteOrderHostEndian
)

func (DataStreamByteOrder) String 

func (d DataStreamByteOrder) String() string

String returns the name in string for DataStreamByteOrder.

type DataStreamNewlineType 

type DataStreamNewlineType C.gint

DataStreamNewlineType is used when checking for or setting the line endings for a given file. 

const (
	// DataStreamNewlineTypeLf selects "LF" line endings, common on most modern
	// UNIX platforms.
	DataStreamNewlineTypeLf DataStreamNewlineType = iota
	// DataStreamNewlineTypeCr selects "CR" line endings.
	DataStreamNewlineTypeCr
	// DataStreamNewlineTypeCrLf selects "CR, LF" line ending, common on
	// Microsoft Windows.
	DataStreamNewlineTypeCrLf
	// DataStreamNewlineTypeAny: automatically try to handle any line ending
	// type.
	DataStreamNewlineTypeAny
)

func (DataStreamNewlineType) String 

func (d DataStreamNewlineType) String() string

String returns the name in string for DataStreamNewlineType.

type DatagramBased 

type DatagramBased struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

DatagramBased: interface for socket-like objects with datagram semantics.

A GDatagramBased is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by gio.Socket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.

GDatagramBased is entirely platform independent, and is intended to be used alongside higher-level networking APIs such as gio.IOStream.

It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing or system calls. For example, GSocket uses recvmmsg() and sendmmsg() where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message.

Each GDatagramBased operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would successfully run you can call gio.DatagramBased.ConditionCheck() or gio.DatagramBased.ConditionWait(). You can also use gio.DatagramBased.CreateSource() and attach it to a glib.MainContext to get callbacks when I/O is possible.

When running a non-blocking operation applications should always be able to handle getting a G_IO_ERROR_WOULD_BLOCK error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write returns G_IO_ERROR_WOULD_BLOCK.

As with GSocket, GDatagramBaseds can be either connection oriented (for example, SCTP) or connectionless (for example, UDP). GDatagramBaseds must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection before sending and receiving data through the GDatagramBased API. For connectionless socket types the target/source address is specified or received in each I/O operation.

Like most other APIs in GLib, GDatagramBased is not inherently thread safe. To use a GDatagramBased concurrently from multiple threads, you must implement your own locking.

DatagramBased wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DatagramBased) ConditionCheck 

func (datagramBased *DatagramBased) ConditionCheck(condition glib.IOCondition) glib.IOCondition

ConditionCheck checks on the readiness of datagram_based to perform operations. The operations specified in condition are checked for and masked against the currently-satisfied conditions on datagram_based. The result is returned.

G_IO_IN will be set in the return value if data is available to read with g_datagram_based_receive_messages(), or if the connection is closed remotely (EOS); and if the datagram_based has not been closed locally using some implementation-specific method (such as g_socket_close() or g_socket_shutdown() with shutdown_read set, if it’s a #GSocket).

If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return G_IO_ERROR_CLOSED.

G_IO_OUT will be set if it is expected that at least one byte can be sent using g_datagram_based_send_messages() without blocking. It will not be set if the datagram_based has been closed locally.

G_IO_HUP will be set if the connection has been closed locally.

G_IO_ERR will be set if there was an asynchronous error in transmitting data previously enqueued using g_datagram_based_send_messages().

Note that on Windows, it is possible for an operation to return G_IO_ERROR_WOULD_BLOCK even immediately after g_datagram_based_condition_check() has claimed that the Based is ready for writing. Rather than calling g_datagram_based_condition_check() and then writing to the Based if it succeeds, it is generally better to simply try writing right away, and try again later if the initial attempt returns G_IO_ERROR_WOULD_BLOCK.

It is meaningless to specify G_IO_ERR or G_IO_HUP in condition; these conditions will always be set in the output if they are true. Apart from these flags, the output is guaranteed to be masked by condition.

This call never blocks.

The function takes the following parameters:

  • condition mask to check.

The function returns the following values:

  • ioCondition mask of the current state.

func (*DatagramBased) ConditionWait 

func (datagramBased *DatagramBased) ConditionWait(ctx context.Context, condition glib.IOCondition, timeout int64) error

ConditionWait waits for up to timeout microseconds for condition to become true on datagram_based. If the condition is met, TRUE is returned.

If cancellable is cancelled before the condition is met, or if timeout is reached before the condition is met, then FALSE is returned and error is set appropriately (G_IO_ERROR_CANCELLED or G_IO_ERROR_TIMED_OUT).

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • condition mask to wait for.
  • timeout: maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely.

func (*DatagramBased) CreateSource 

func (datagramBased *DatagramBased) CreateSource(ctx context.Context, condition glib.IOCondition) *glib.Source

CreateSource creates a #GSource that can be attached to a Context to monitor for the availability of the specified condition on the Based. The #GSource keeps a reference to the datagram_based.

The callback on the source is of the BasedSourceFunc type.

It is meaningless to specify G_IO_ERR or G_IO_HUP in condition; these conditions will always be reported in the callback if they are true.

If non-NULL, cancellable can be used to cancel the source, which will cause the source to trigger, reporting the current condition (which is likely 0 unless cancellation happened at the same time as a condition change). You can check for this in the callback using g_cancellable_is_cancelled().

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • condition mask to monitor.

The function returns the following values:

  • source: newly allocated #GSource.

func (*DatagramBased) ReceiveMessages 

func (datagramBased *DatagramBased) ReceiveMessages(ctx context.Context, messages []InputMessage, flags int, timeout int64) (int, error)

ReceiveMessages: receive one or more data messages from datagram_based in one go.

messages must point to an array of Message structs and num_messages must be the length of this array. Each Message contains a pointer to an array of Vector structs describing the buffers that the data received in each message will be written to.

flags modify how all messages are received. The commonly available arguments for this are available in the MsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in Message.flags.

The other members of Message are treated as described in its documentation.

If timeout is negative the call will block until num_messages have been received, the connection is closed remotely (EOS), cancellable is cancelled, or an error occurs.

If timeout is 0 the call will return up to num_messages without blocking, or G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system to be received.

If timeout is positive the call will block on the same conditions as if timeout were negative. If the timeout is reached before any messages are received, G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages received before timing out. (Note: This is effectively the behaviour of MSG_WAITFORONE with recvmmsg().)

To be notified when messages are available, wait for the G_IO_IN condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_datagram_based_receive_messages() even if you were previously notified of a G_IO_IN condition.

If the remote peer closes the connection, any messages queued in the underlying receive buffer will be returned, and subsequent calls to g_datagram_based_receive_messages() will return 0 (with no error set).

If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with shutdown_read set, if it’s a #GSocket, for example), all calls to this function will return G_IO_ERROR_CLOSED.

On error -1 is returned and error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned. If cancellable is cancelled, G_IO_ERROR_CANCELLED is returned as with any other error.

The function takes the following parameters:

  • ctx (optional): GCancellable.
  • messages: array of Message structs.
  • flags: int containing MsgFlags flags for the overall operation.
  • timeout: maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely.

The function returns the following values:

  • gint: number of messages received, or -1 on error. Note that the number of messages received may be smaller than num_messages if timeout is zero or positive, if the peer closed the connection, or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to receive the remaining messages.

func (*DatagramBased) SendMessages 

func (datagramBased *DatagramBased) SendMessages(ctx context.Context, messages []OutputMessage, flags int, timeout int64) (int, error)

SendMessages: send one or more data messages from datagram_based in one go.

messages must point to an array of Message structs and num_messages must be the length of this array. Each Message contains an address to send the data to, and a pointer to an array of Vector structs to describe the buffers that the data to be sent for each message will be gathered from.

flags modify how the message is sent. The commonly available arguments for this are available in the MsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too.

The other members of Message are treated as described in its documentation.

If timeout is negative the call will block until num_messages have been sent, cancellable is cancelled, or an error occurs.

If timeout is 0 the call will send up to num_messages without blocking, or will return G_IO_ERROR_WOULD_BLOCK if there is no space to send messages.

If timeout is positive the call will block on the same conditions as if timeout were negative. If the timeout is reached before any messages are sent, G_IO_ERROR_TIMED_OUT is returned, otherwise it will return the number of messages sent before timing out.

To be notified when messages can be sent, wait for the G_IO_OUT condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_datagram_based_send_messages() even if you were previously notified of a G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

If the connection is shut down or closed (by calling g_socket_close() or g_socket_shutdown() with shutdown_write set, if it’s a #GSocket, for example), all calls to this function will return G_IO_ERROR_CLOSED.

On error -1 is returned and error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned. If cancellable is cancelled, G_IO_ERROR_CANCELLED is returned as with any other error.

The function takes the following parameters:

  • ctx (optional): GCancellable.
  • messages: array of Message structs.
  • flags: int containing MsgFlags flags.
  • timeout: maximum time (in microseconds) to wait, 0 to not block, or -1 to block indefinitely.

The function returns the following values:

  • gint: number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than num_messages if timeout is zero or positive, or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages.

type DatagramBasedInterface added in v0.0.5 

type DatagramBasedInterface struct {
	// contains filtered or unexported fields
}

DatagramBasedInterface provides an interface for socket-like objects which have datagram semantics, following the Berkeley sockets API. The interface methods are thin wrappers around the corresponding virtual methods, and no pre-processing of inputs is implemented — so implementations of this API must handle all functionality documented in the interface methods.

An instance of this type is always passed by reference.

type DatagramBasedder 

type DatagramBasedder interface {
	coreglib.Objector

	// ConditionCheck checks on the readiness of datagram_based to perform
	// operations.
	ConditionCheck(condition glib.IOCondition) glib.IOCondition
	// ConditionWait waits for up to timeout microseconds for condition to
	// become true on datagram_based.
	ConditionWait(ctx context.Context, condition glib.IOCondition, timeout int64) error
	// CreateSource creates a #GSource that can be attached to a Context to
	// monitor for the availability of the specified condition on the Based.
	CreateSource(ctx context.Context, condition glib.IOCondition) *glib.Source
	// ReceiveMessages: receive one or more data messages from datagram_based in
	// one go.
	ReceiveMessages(ctx context.Context, messages []InputMessage, flags int, timeout int64) (int, error)
	// SendMessages: send one or more data messages from datagram_based in one
	// go.
	SendMessages(ctx context.Context, messages []OutputMessage, flags int, timeout int64) (int, error)
}

DatagramBasedder describes DatagramBased's interface methods.

type DebugController added in v0.3.0 

type DebugController struct {
	Initable
	// contains filtered or unexported fields
}

DebugController: GDebugController is an interface to expose control of debugging features and debug output.

It is implemented on Linux using gio.DebugControllerDBus, which exposes a D-Bus interface to allow authenticated peers to control debug features in this process.

Whether debug output is enabled is exposed as gio.DebugController:debug-enabled. This controls glib.LogSetDebugEnabled() by default. Application code may connect to the gobject.Object::notify signal for it to control other parts of its debug infrastructure as necessary.

If your application or service is using the default GLib log writer function, creating one of the built-in implementations of GDebugController should be all that’s needed to dynamically enable or disable debug output.

DebugController wraps an interface. This means the user can get the underlying type by calling Cast().

func (*DebugController) DebugEnabled added in v0.3.0 

func (self *DebugController) DebugEnabled() bool

DebugEnabled: get the value of Controller:debug-enabled.

The function returns the following values:

  • ok: TRUE if debug output should be exposed, FALSE otherwise.

func (*DebugController) SetDebugEnabled added in v0.3.0 

func (self *DebugController) SetDebugEnabled(debugEnabled bool)

SetDebugEnabled: set the value of Controller:debug-enabled.

The function takes the following parameters:

  • debugEnabled: TRUE if debug output should be exposed, FALSE otherwise.

type DebugControllerDBus added in v0.3.0 

type DebugControllerDBus struct {
	*coreglib.Object

	DebugController
	// contains filtered or unexported fields
}

DebugControllerDBus: GDebugControllerDBus is an implementation of gio.DebugController which exposes debug settings as a D-Bus object.

It is a gio.Initable object, and will register an object at /org/gtk/Debugging on the bus given as gio.DebugControllerDBus:connection once it’s initialized. The object will be unregistered when the last reference to the GDebugControllerDBus is dropped.

This D-Bus object can be used by remote processes to enable or disable debug output in this process. Remote processes calling org.gtk.Debugging.SetDebugEnabled() will affect the value of gio.DebugController:debug-enabled and, by default, glib.LogGetDebugEnabled().

By default, no processes are allowed to call SetDebugEnabled() unless a gio.DebugControllerDBus::authorize signal handler is installed. This is because the process may be privileged, or might expose sensitive information in its debug output. You may want to restrict the ability to enable debug output to privileged users or processes.

One option is to install a D-Bus security policy which restricts access to SetDebugEnabled(), installing something like the following in $datadir/dbus-1/system.d/: 

<?xml version="1.0"?> <!--*-nxml-*-->
<!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
     "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
  <policy user="root">
    <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
  </policy>
  <policy context="default">
    <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
  </policy>
</busconfig>

This will prevent the SetDebugEnabled() method from being called by all except root. It will not prevent the DebugEnabled property from being read, as it’s accessed through the org.freedesktop.DBus.Properties interface.

Another option is to use polkit to allow or deny requests on a case-by-case basis, allowing for the possibility of dynamic authorisation. To do this, connect to the gio.DebugControllerDBus::authorize signal and query polkit in it: 

g_autoptr(GError) child_error = NULL;
g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
gulong debug_controller_authorize_id = 0;

// Set up the debug controller.
debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error));
if (debug_controller == NULL)
  {
    g_error ("Could not register debug controller on bus: s"),
             child_error->message);
  }

debug_controller_authorize_id = g_signal_connect (debug_controller,
                                                  "authorize",
                                                  G_CALLBACK (debug_controller_authorize_cb),
                                                  self);

static gboolean
debug_controller_authorize_cb (GDebugControllerDBus  *debug_controller,
                               GDBusMethodInvocation *invocation,
                               gpointer               user_data)
{
  g_autoptr(PolkitAuthority) authority = NULL;
  g_autoptr(PolkitSubject) subject = NULL;
  g_autoptr(PolkitAuthorizationResult) auth_result = NULL;
  g_autoptr(GError) local_error = NULL;
  GDBusMessage *message;
  GDBusMessageFlags message_flags;
  PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE;

  message = g_dbus_method_invocation_get_message (invocation);
  message_flags = g_dbus_message_get_flags (message);

  authority = polkit_authority_get_sync (NULL, &local_error);
  if (authority == NULL)
    {
      g_warning ("Failed to get polkit authority: s", local_error->message);
      return FALSE;
    }

  if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION)
    flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION;

  subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));

  auth_result = polkit_authority_check_authorization_sync (authority,
                                                           subject,
                                                           "com.example.MyService.set-debug-enabled",
                                                           NULL,
                                                           flags,
                                                           NULL,
                                                           &local_error);
  if (auth_result == NULL)
    {
      g_warning ("Failed to get check polkit authorization: s", local_error->message);
      return FALSE;
    }

  return polkit_authorization_result_get_is_authorized (auth_result);
}.

func NewDebugControllerDBus added in v0.3.0 

func NewDebugControllerDBus(ctx context.Context, connection *DBusConnection) (*DebugControllerDBus, error)

NewDebugControllerDBus: create a new ControllerDBus and synchronously initialize it.

Initializing the object will export the debug object on connection. The object will remain registered until the last reference to the ControllerDBus is dropped.

Initialization may fail if registering the object on connection fails.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connection to register the debug object on.

The function returns the following values:

  • debugControllerDBus (optional): new ControllerDBus, or NULL on failure.

func (*DebugControllerDBus) ConnectAuthorize added in v0.3.0 

func (self *DebugControllerDBus) ConnectAuthorize(f func(invocation *DBusMethodInvocation) (ok bool)) coreglib.SignalHandle

ConnectAuthorize is emitted when a D-Bus peer is trying to change the debug settings and used to determine if that is authorized.

This signal is emitted in a dedicated worker thread, so handlers are allowed to perform blocking I/O. This means that, for example, it is appropriate to call polkit_authority_check_authorization_sync() to check authorization using polkit.

If FALSE is returned then no further handlers are run and the request to change the debug settings is rejected.

Otherwise, if TRUE is returned, signal emission continues. If no handlers return FALSE, then the debug settings are allowed to be changed.

Signal handlers must not modify invocation, or cause it to return a value.

The default class handler just returns TRUE.

func (*DebugControllerDBus) Stop added in v0.3.0 

func (self *DebugControllerDBus) Stop()

Stop the debug controller, unregistering its object from the bus.

Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending ControllerDBus::authorize signals have been handled. This is expected to not take long, as it will just be waiting for threads to join. If any ControllerDBus::authorize signal handlers are still executing in other threads, this will block until after they have returned.

This method will be called automatically when the final reference to the ControllerDBus is dropped. You may want to call it explicitly to know when the controller has been fully removed from the bus, or to break reference count cycles.

Calling this method from within a ControllerDBus::authorize signal handler will cause a deadlock and must not be done.

type DebugControllerDBusClass added in v0.3.0 

type DebugControllerDBusClass struct {
	// contains filtered or unexported fields
}

DebugControllerDBusClass: virtual function table for ControllerDBus.

An instance of this type is always passed by reference.

func (*DebugControllerDBusClass) Padding added in v0.3.0 

func (d *DebugControllerDBusClass) Padding() [12]unsafe.Pointer

type DebugControllerDBusOverrides added in v0.3.0 

type DebugControllerDBusOverrides struct {
	// Authorize: default handler for the ControllerDBus::authorize signal.
	Authorize func(invocation *DBusMethodInvocation) bool
}

DebugControllerDBusOverrides contains methods that are overridable.

type DebugControllerInterface added in v0.3.0 

type DebugControllerInterface struct {
	// contains filtered or unexported fields
}

DebugControllerInterface: virtual function table for Controller.

An instance of this type is always passed by reference.

type DebugControllerOverrider added in v0.3.0 

type DebugControllerOverrider interface {
}

DebugControllerOverrider contains methods that are overridable.

type DebugControllerer added in v0.3.0 

type DebugControllerer interface {
	coreglib.Objector

	// DebugEnabled: get the value of Controller:debug-enabled.
	DebugEnabled() bool
	// SetDebugEnabled: set the value of Controller:debug-enabled.
	SetDebugEnabled(debugEnabled bool)
}

DebugControllerer describes DebugController's interface methods.

type Drive 

type Drive struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Drive: GDrive represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media.

GDrive is a container class for gio.Volume objects that stem from the same piece of media. As such, GDrive abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media.

If the GDrive reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise.

GDrive supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a GDrive may vary according to implementation. To choose the correct verbs in e.g. a file manager, use gio.Drive.GetStartStopType().

For porting from GnomeVFS (migrating-gnome-vfs.html) note that there is no equivalent of GDrive in that API.

Drive wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Drive) CanEject 

func (drive *Drive) CanEject() bool

CanEject checks if a drive can be ejected.

The function returns the following values:

  • ok: TRUE if the drive can be ejected, FALSE otherwise.

func (*Drive) CanPollForMedia 

func (drive *Drive) CanPollForMedia() bool

CanPollForMedia checks if a drive can be polled for media changes.

The function returns the following values:

  • ok: TRUE if the drive can be polled for media changes, FALSE otherwise.

func (*Drive) CanStart 

func (drive *Drive) CanStart() bool

CanStart checks if a drive can be started.

The function returns the following values:

  • ok: TRUE if the drive can be started, FALSE otherwise.

func (*Drive) CanStartDegraded 

func (drive *Drive) CanStartDegraded() bool

CanStartDegraded checks if a drive can be started degraded.

The function returns the following values:

  • ok: TRUE if the drive can be started degraded, FALSE otherwise.

func (*Drive) CanStop 

func (drive *Drive) CanStop() bool

CanStop checks if a drive can be stopped.

The function returns the following values:

  • ok: TRUE if the drive can be stopped, FALSE otherwise.

func (*Drive) ConnectChanged 

func (drive *Drive) ConnectChanged(f func()) coreglib.SignalHandle

ConnectChanged is emitted when the drive's state has changed.

func (*Drive) ConnectDisconnected 

func (drive *Drive) ConnectDisconnected(f func()) coreglib.SignalHandle

ConnectDisconnected: this signal is emitted when the #GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.

func (*Drive) ConnectEjectButton 

func (drive *Drive) ConnectEjectButton(f func()) coreglib.SignalHandle

ConnectEjectButton is emitted when the physical eject button (if any) of a drive has been pressed.

func (*Drive) ConnectStopButton 

func (drive *Drive) ConnectStopButton(f func()) coreglib.SignalHandle

ConnectStopButton is emitted when the physical stop button (if any) of a drive has been pressed.

func (*Drive) Eject deprecated 

func (drive *Drive) Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

Eject: asynchronously ejects a drive.

When the operation is finished, callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation.

Deprecated: Use g_drive_eject_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • callback (optional) or NULL.

func (*Drive) EjectFinish deprecated 

func (drive *Drive) EjectFinish(result AsyncResulter) error

EjectFinish finishes ejecting a drive.

Deprecated: Use g_drive_eject_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*Drive) EjectWithOperation 

func (drive *Drive) EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

EjectWithOperation ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the drive and Result data returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Drive) EjectWithOperationFinish 

func (drive *Drive) EjectWithOperationFinish(result AsyncResulter) error

EjectWithOperationFinish finishes ejecting a drive. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*Drive) EnumerateIdentifiers 

func (drive *Drive) EnumerateIdentifiers() []string

EnumerateIdentifiers gets the kinds of identifiers that drive has. Use g_drive_get_identifier() to obtain the identifiers themselves.

The function returns the following values:

  • utf8s: NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.

func (*Drive) HasMedia 

func (drive *Drive) HasMedia() bool

HasMedia checks if the drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details.

The function returns the following values:

  • ok: TRUE if drive has media, FALSE otherwise.

func (*Drive) HasVolumes 

func (drive *Drive) HasVolumes() bool

HasVolumes: check if drive has any mountable volumes.

The function returns the following values:

  • ok: TRUE if the drive contains volumes, FALSE otherwise.

func (*Drive) Icon 

func (drive *Drive) Icon() *Icon

Icon gets the icon for drive.

The function returns the following values:

  • icon for the drive. Free the returned object with g_object_unref().

func (*Drive) Identifier 

func (drive *Drive) Identifier(kind string) string

Identifier gets the identifier of the given kind for drive. The only identifier currently available is G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.

The function takes the following parameters:

  • kind of identifier to return.

The function returns the following values:

  • utf8 (optional): newly allocated string containing the requested identifier, or NULL if the #GDrive doesn't have this kind of identifier.

func (*Drive) IsMediaCheckAutomatic 

func (drive *Drive) IsMediaCheckAutomatic() bool

IsMediaCheckAutomatic checks if drive is capable of automatically detecting media changes.

The function returns the following values:

  • ok: TRUE if the drive is capable of automatically detecting media changes, FALSE otherwise.

func (*Drive) IsMediaRemovable 

func (drive *Drive) IsMediaRemovable() bool

IsMediaRemovable checks if the drive supports removable media.

The function returns the following values:

  • ok: TRUE if drive supports removable media, FALSE otherwise.

func (*Drive) IsRemovable 

func (drive *Drive) IsRemovable() bool

IsRemovable checks if the #GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable().

The function returns the following values:

  • ok: TRUE if drive and/or its media is considered removable, FALSE otherwise.

func (*Drive) Name 

func (drive *Drive) Name() string

Name gets the name of drive.

The function returns the following values:

  • utf8: string containing drive's name. The returned string should be freed when no longer needed.

func (*Drive) PollForMedia 

func (drive *Drive) PollForMedia(ctx context.Context, callback AsyncReadyCallback)

PollForMedia: asynchronously polls drive to see if media has been inserted or removed.

When the operation is finished, callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • callback (optional) or NULL.

func (*Drive) PollForMediaFinish 

func (drive *Drive) PollForMediaFinish(result AsyncResulter) error

PollForMediaFinish finishes an operation started with g_drive_poll_for_media() on a drive.

The function takes the following parameters:

  • result: Result.

func (*Drive) SortKey 

func (drive *Drive) SortKey() string

SortKey gets the sort key for drive, if any.

The function returns the following values:

  • utf8 (optional): sorting key for drive or NULL if no such key is available.

func (*Drive) Start 

func (drive *Drive) Start(ctx context.Context, flags DriveStartFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

Start: asynchronously starts a drive.

When the operation is finished, callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the start operation.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Drive) StartFinish 

func (drive *Drive) StartFinish(result AsyncResulter) error

StartFinish finishes starting a drive.

The function takes the following parameters:

  • result: Result.

func (*Drive) StartStopType 

func (drive *Drive) StartStopType() DriveStartStopType

StartStopType gets a hint about how a drive can be started/stopped.

The function returns the following values:

  • driveStartStopType: value from the StartStopType enumeration.

func (*Drive) Stop 

func (drive *Drive) Stop(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

Stop: asynchronously stops a drive.

When the operation is finished, callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for stopping.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Drive) StopFinish 

func (drive *Drive) StopFinish(result AsyncResulter) error

StopFinish finishes stopping a drive.

The function takes the following parameters:

  • result: Result.

func (*Drive) SymbolicIcon 

func (drive *Drive) SymbolicIcon() *Icon

SymbolicIcon gets the icon for drive.

The function returns the following values:

  • icon: symbolic #GIcon for the drive. Free the returned object with g_object_unref().

func (*Drive) Volumes 

func (drive *Drive) Volumes() []*Volume

Volumes: get a list of mountable volumes for drive.

The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

The function returns the following values:

  • list containing any #GVolume objects on the given drive.

type DriveIface added in v0.0.5 

type DriveIface struct {
	// contains filtered or unexported fields
}

DriveIface: interface for creating #GDrive implementations.

An instance of this type is always passed by reference.

type DriveStartFlags 

type DriveStartFlags C.guint

DriveStartFlags flags used when starting a drive. 

const (
	// DriveStartNone: no flags set.
	DriveStartNone DriveStartFlags = 0b0
)

func (DriveStartFlags) Has 

func (d DriveStartFlags) Has(other DriveStartFlags) bool

Has returns true if d contains other.

func (DriveStartFlags) String 

func (d DriveStartFlags) String() string

String returns the names in string for DriveStartFlags.

type DriveStartStopType 

type DriveStartStopType C.gint

DriveStartStopType: enumeration describing how a drive can be started/stopped. 

const (
	// DriveStartStopTypeUnknown: unknown or drive doesn't support start/stop.
	DriveStartStopTypeUnknown DriveStartStopType = iota
	// DriveStartStopTypeShutdown: stop method will physically shut down the
	// drive and e.g. power down the port the drive is attached to.
	DriveStartStopTypeShutdown
	// DriveStartStopTypeNetwork: start/stop methods are used for
	// connecting/disconnect to the drive over the network.
	DriveStartStopTypeNetwork
	// DriveStartStopTypeMultidisk: start/stop methods will assemble/disassemble
	// a virtual drive from several physical drives.
	DriveStartStopTypeMultidisk
	// DriveStartStopTypePassword: start/stop methods will unlock/lock the
	// disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote>
	// command).
	DriveStartStopTypePassword
)

func (DriveStartStopType) String 

func (d DriveStartStopType) String() string

String returns the name in string for DriveStartStopType.

type Driver 

type Driver interface {
	coreglib.Objector

	// CanEject checks if a drive can be ejected.
	CanEject() bool
	// CanPollForMedia checks if a drive can be polled for media changes.
	CanPollForMedia() bool
	// CanStart checks if a drive can be started.
	CanStart() bool
	// CanStartDegraded checks if a drive can be started degraded.
	CanStartDegraded() bool
	// CanStop checks if a drive can be stopped.
	CanStop() bool
	// Eject: asynchronously ejects a drive.
	Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// EjectFinish finishes ejecting a drive.
	EjectFinish(result AsyncResulter) error
	// EjectWithOperation ejects a drive.
	EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// EjectWithOperationFinish finishes ejecting a drive.
	EjectWithOperationFinish(result AsyncResulter) error
	// EnumerateIdentifiers gets the kinds of identifiers that drive has.
	EnumerateIdentifiers() []string
	// Icon gets the icon for drive.
	Icon() *Icon
	// Identifier gets the identifier of the given kind for drive.
	Identifier(kind string) string
	// Name gets the name of drive.
	Name() string
	// SortKey gets the sort key for drive, if any.
	SortKey() string
	// StartStopType gets a hint about how a drive can be started/stopped.
	StartStopType() DriveStartStopType
	// SymbolicIcon gets the icon for drive.
	SymbolicIcon() *Icon
	// Volumes: get a list of mountable volumes for drive.
	Volumes() []*Volume
	// HasMedia checks if the drive has media.
	HasMedia() bool
	// HasVolumes: check if drive has any mountable volumes.
	HasVolumes() bool
	// IsMediaCheckAutomatic checks if drive is capable of automatically
	// detecting media changes.
	IsMediaCheckAutomatic() bool
	// IsMediaRemovable checks if the drive supports removable media.
	IsMediaRemovable() bool
	// IsRemovable checks if the #GDrive and/or its media is considered
	// removable by the user.
	IsRemovable() bool
	// PollForMedia: asynchronously polls drive to see if media has been
	// inserted or removed.
	PollForMedia(ctx context.Context, callback AsyncReadyCallback)
	// PollForMediaFinish finishes an operation started with
	// g_drive_poll_for_media() on a drive.
	PollForMediaFinish(result AsyncResulter) error
	// Start: asynchronously starts a drive.
	Start(ctx context.Context, flags DriveStartFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// StartFinish finishes starting a drive.
	StartFinish(result AsyncResulter) error
	// Stop: asynchronously stops a drive.
	Stop(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// StopFinish finishes stopping a drive.
	StopFinish(result AsyncResulter) error

	// Changed is emitted when the drive's state has changed.
	ConnectChanged(func()) coreglib.SignalHandle
	// Disconnected: this signal is emitted when the #GDrive have been
	// disconnected.
	ConnectDisconnected(func()) coreglib.SignalHandle
	// Eject-button is emitted when the physical eject button (if any) of a
	// drive has been pressed.
	ConnectEjectButton(func()) coreglib.SignalHandle
	// Stop-button is emitted when the physical stop button (if any) of a drive
	// has been pressed.
	ConnectStopButton(func()) coreglib.SignalHandle
}

Driver describes Drive's interface methods.

type Emblem 

type Emblem struct {
	*coreglib.Object

	Icon
	// contains filtered or unexported fields
}

Emblem: GEmblem is an implementation of gio.Icon that supports having an emblem, which is an icon with additional properties. It can than be added to a gio.EmblemedIcon.

Currently, only metainformation about the emblem's origin is supported. More may be added in the future.

func NewEmblem 

func NewEmblem(icon Iconner) *Emblem

NewEmblem creates a new emblem for icon.

The function takes the following parameters:

  • icon: GIcon containing the icon.

The function returns the following values:

  • emblem: new #GEmblem.

func NewEmblemWithOrigin 

func NewEmblemWithOrigin(icon Iconner, origin EmblemOrigin) *Emblem

NewEmblemWithOrigin creates a new emblem for icon.

The function takes the following parameters:

  • icon: GIcon containing the icon.
  • origin: GEmblemOrigin enum defining the emblem's origin.

The function returns the following values:

  • emblem: new #GEmblem.

func (*Emblem) GetIcon 

func (emblem *Emblem) GetIcon() *Icon

GetIcon gives back the icon from emblem.

The function returns the following values:

  • icon The returned object belongs to the emblem and should not be modified or freed.

func (*Emblem) Origin 

func (emblem *Emblem) Origin() EmblemOrigin

Origin gets the origin of the emblem.

The function returns the following values:

  • emblemOrigin: origin of the emblem.

type EmblemOrigin 

type EmblemOrigin C.gint

EmblemOrigin is used to add information about the origin of the emblem to #GEmblem. 

const (
	// EmblemOriginUnknown: emblem of unknown origin.
	EmblemOriginUnknown EmblemOrigin = iota
	// EmblemOriginDevice: emblem adds device-specific information.
	EmblemOriginDevice
	// EmblemOriginLivemetadata: emblem depicts live metadata, such as
	// "readonly".
	EmblemOriginLivemetadata
	// EmblemOriginTag: emblem comes from a user-defined tag, e.g. set by
	// nautilus (in the future).
	EmblemOriginTag
)

func (EmblemOrigin) String 

func (e EmblemOrigin) String() string

String returns the name in string for EmblemOrigin.

type EmblemedIcon 

type EmblemedIcon struct {
	*coreglib.Object

	Icon
	// contains filtered or unexported fields
}

EmblemedIcon: GEmblemedIcon is an implementation of gio.Icon that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via gio.EmblemedIcon.AddEmblem().

Note that GEmblemedIcon allows no control over the position of the emblems. See also gio.Emblem for more information.

func NewEmblemedIcon 

func NewEmblemedIcon(icon Iconner, emblem *Emblem) *EmblemedIcon

NewEmblemedIcon creates a new emblemed icon for icon with the emblem emblem.

The function takes the following parameters:

  • icon: #GIcon.
  • emblem (optional) or NULL.

The function returns the following values:

  • emblemedIcon: new #GIcon.

func (*EmblemedIcon) AddEmblem 

func (emblemed *EmblemedIcon) AddEmblem(emblem *Emblem)

AddEmblem adds emblem to the #GList of #GEmblems.

The function takes the following parameters:

  • emblem: #GEmblem.

func (*EmblemedIcon) ClearEmblems 

func (emblemed *EmblemedIcon) ClearEmblems()

ClearEmblems removes all the emblems from icon.

func (*EmblemedIcon) Emblems 

func (emblemed *EmblemedIcon) Emblems() []*Emblem

Emblems gets the list of emblems for the icon.

The function returns the following values:

  • list of #GEmblems that is owned by emblemed.

func (*EmblemedIcon) GetIcon 

func (emblemed *EmblemedIcon) GetIcon() *Icon

GetIcon gets the main icon for emblemed.

The function returns the following values:

  • icon that is owned by emblemed.

type EmblemedIconClass added in v0.0.5 

type EmblemedIconClass struct {
	// contains filtered or unexported fields
}

EmblemedIconClass: instance of this type is always passed by reference.

type EmblemedIconOverrides added in v0.0.5 

type EmblemedIconOverrides struct {
}

EmblemedIconOverrides contains methods that are overridable.

type File 

type File struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

File: GFile is a high level abstraction for manipulating files on a virtual file system. GFiles are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that GFile objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see gio.InputStream and gio.OutputStream).

To construct a GFile, you can use:

- gio.File().NewForPath if you have a path.

- gio.File().NewForURI if you have a URI.

- gio.File().NewForCommandlineArg or gio.File().NewForCommandlineArgAndCwd for a command line argument.

- gio.File().NewTmp to create a temporary file from a template.

- gio.File().NewTmpAsync to asynchronously create a temporary file.

- gio.File().NewTmpDirAsync to asynchronously create a temporary directory.

- gio.File().ParseName from a UTF-8 string gotten from gio.File.GetParseName().

- gio.File().NewBuildFilename or gio.File().NewBuildFilenamev to create a file from path elements.

One way to think of a GFile is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as GFiles are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.

GFiles make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with GFile using gio.File.GetParent() to get an identifier for the parent directory, gio.File.GetChild() to get a child within a directory, and gio.File.ResolveRelativePath() to resolve a relative path between two GFiles. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call gio.File.GetParent() on two different files.

All GFiles have a basename (get with gio.File.GetBasename()). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with gio.File.QueryInfo(). This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the GFile to use to actually access the file, because there is no way to go from a display name to the actual name.

Using GFile as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different GFiles to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two GFiles point to the same file you can query for the G_FILE_ATTRIBUTE_ID_FILE attribute. Note that GFile does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, . or .. path segments, etc) does not create different GFiles.

Many GFile operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have _async() appended to their function names. The asynchronous I/O functions call a gio.AsyncReadyCallback which is then used to finalize the operation, producing a gio.AsyncResult which is then passed to the function’s matching _finish() operation.

It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the introduction to asynchronous programming section (overview.html#asynchronous-programming) for more.

Some GFile operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include:

- gio.File.MountMountable() to mount a mountable file.

- gio.File.UnmountMountableWithOperation() to unmount a mountable file.

- gio.File.EjectMountableWithOperation() to eject a mountable file.

Entity Tags

One notable feature of GFiles are entity tags, or ‘etags’ for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 specification (http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for HTTP ETag headers, which are a very similar concept.

File wraps an interface. This means the user can get the underlying type by calling Cast().

func FileParseName 

func FileParseName(parseName string) *File

FileParseName constructs a #GFile with the given parse_name (i.e. something given by g_file_get_parse_name()). This operation never fails, but the returned object might not support any I/O operation if the parse_name cannot be parsed.

The function takes the following parameters:

  • parseName: file name or path to be parsed.

The function returns the following values:

  • file: new #GFile.

func NewFileBuildFilenamev added in v0.3.0 

func NewFileBuildFilenamev(args []string) *File

NewFileBuildFilenamev constructs a #GFile from a vector of elements using the correct separator for filenames.

Using this function is equivalent to calling g_build_filenamev(), followed by g_file_new_for_path() on the result.

The function takes the following parameters:

  • args: NULL-terminated array of strings containing the path elements.

The function returns the following values:

  • file: new #GFile.

func NewFileForCommandlineArg 

func NewFileForCommandlineArg(arg string) *File

NewFileForCommandlineArg creates a #GFile with the given argument from the command line. The value of arg can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if arg points to a malformed path.

Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to main(). g_win32_get_command_line() will return a UTF-8 version of the commandline. #GApplication also uses UTF-8 but g_application_command_line_create_file_for_arg() may be more useful for you there. It is also always possible to use this function with Context arguments of type G_OPTION_ARG_FILENAME.

The function takes the following parameters:

  • arg: command line string.

The function returns the following values:

  • file: new #GFile. Free the returned object with g_object_unref().

func NewFileForCommandlineArgAndCwd 

func NewFileForCommandlineArgAndCwd(arg, cwd string) *File

NewFileForCommandlineArgAndCwd creates a #GFile with the given argument from the command line.

This function is similar to g_file_new_for_commandline_arg() except that it allows for passing the current working directory as an argument instead of using the current working directory of the process.

This is useful if the commandline argument was given in a context other than the invocation of the current process.

See also g_application_command_line_create_file_for_arg().

The function takes the following parameters:

  • arg: command line string.
  • cwd: current working directory of the commandline.

The function returns the following values:

  • file: new #GFile.

func NewFileForPath 

func NewFileForPath(path string) *File

NewFileForPath constructs a #GFile for a given path. This operation never fails, but the returned object might not support any I/O operation if path is malformed.

The function takes the following parameters:

  • path: string containing a relative or absolute path. The string must be encoded in the glib filename encoding.

The function returns the following values:

  • file: new #GFile for the given path. Free the returned object with g_object_unref().

func NewFileForURI 

func NewFileForURI(uri string) *File

NewFileForURI constructs a #GFile for a given URI. This operation never fails, but the returned object might not support any I/O operation if uri is malformed or if the uri type is not supported.

The function takes the following parameters:

  • uri: UTF-8 string containing a URI.

The function returns the following values:

  • file: new #GFile for the given uri. Free the returned object with g_object_unref().

func NewFileTmpDirFinish added in v0.3.0 

func NewFileTmpDirFinish(result AsyncResulter) (*File, error)

NewFileTmpDirFinish finishes a temporary directory creation started by g_file_new_tmp_dir_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • file: new #GFile. Free the returned object with g_object_unref().

func (*File) AppendTo 

func (file *File) AppendTo(ctx context.Context, flags FileCreateFlags) (*FileOutputStream, error)

AppendTo gets an output stream for appending data to the file. If the file doesn't already exist it is created.

By default files created are generally readable by everyone, but if you pass G_FILE_CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

Some file systems don't allow all file names, and may return an G_IO_ERROR_INVALID_FILENAME error. If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.

The function returns the following values:

  • fileOutputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) AppendToAsync 

func (file *File) AppendToAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)

AppendToAsync: asynchronously opens file for appending.

For more details, see g_file_append_to() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_append_to_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) AppendToFinish 

func (file *File) AppendToFinish(res AsyncResulter) (*FileOutputStream, error)

AppendToFinish finishes an asynchronous file append operation started with g_file_append_to_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileOutputStream: valid OutputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) Basename 

func (file *File) Basename() string

Basename gets the base name (the last component of the path) for a given #GFile.

If called for the top level of a system (such as the filesystem root or a uri like sftp://host/) it will return a single directory separator (and on Windows, possibly a drive letter).

The base name is a byte string (not UTF-8). It has no defined encoding or rules other than it may not contain zero bytes. If you want to use filenames in a user interface you should use the display name that you can get by requesting the G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info().

This call does no blocking I/O.

The function returns the following values:

  • filename (optional): string containing the #GFile's base name, or NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed.

func (*File) BuildAttributeListForCopy 

func (file *File) BuildAttributeListForCopy(ctx context.Context, flags FileCopyFlags) (string, error)

BuildAttributeListForCopy prepares the file attribute query string for copying to file.

This function prepares an attribute query string to be passed to g_file_query_info() to get a list of attributes normally copied with the file (see g_file_copy_attributes() for the detailed description). This function is used by the implementation of g_file_copy_attributes() and is useful when one needs to query and set the attributes in two stages (e.g., for recursive move of a directory).

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CopyFlags.

The function returns the following values:

  • utf8: attribute query string for g_file_query_info(), or NULL if an error occurs.

func (*File) Child 

func (file *File) Child(name string) *File

Child gets a child of file with basename equal to name.

Note that the file with that specific name might not exist, but you can still have a #GFile that points to it. You can use this for instance to create that file.

This call does no blocking I/O.

The function takes the following parameters:

  • name: string containing the child's basename.

The function returns the following values:

  • ret to a child specified by name. Free the returned object with g_object_unref().

func (*File) ChildForDisplayName 

func (file *File) ChildForDisplayName(displayName string) (*File, error)

ChildForDisplayName gets the child of file for a given display_name (i.e. a UTF-8 version of the name). If this function fails, it returns NULL and error will be set. This is very useful when constructing a #GFile for a new file and the user entered the filename in the user interface, for instance when you select a directory and type a filename in the file selector.

This call does no blocking I/O.

The function takes the following parameters:

  • displayName: string to a possible child.

The function returns the following values:

  • ret to the specified child, or NULL if the display name couldn't be converted. Free the returned object with g_object_unref().

func (*File) CopyAttributes 

func (source *File) CopyAttributes(ctx context.Context, destination Filer, flags FileCopyFlags) error

CopyAttributes copies the file attributes from source to destination.

Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation (which for instance does not include e.g. owner). However if G_FILE_COPY_ALL_METADATA is specified in flags, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • destination to copy attributes to.
  • flags: set of CopyFlags.

func (*File) CopyFinish 

func (file *File) CopyFinish(res AsyncResulter) error

CopyFinish finishes copying the file started with g_file_copy_async().

The function takes the following parameters:

  • res: Result.

func (*File) Create 

func (file *File) Create(ctx context.Context, flags FileCreateFlags) (*FileOutputStream, error)

Create creates a new file and returns an output stream for writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass G_FILE_CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If a file or directory with this name already exists the G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an G_IO_ERROR_INVALID_FILENAME error, and if the name is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.

The function returns the following values:

  • fileOutputStream for the newly created file, or NULL on error. Free the returned object with g_object_unref().

func (*File) CreateAsync 

func (file *File) CreateAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)

CreateAsync: asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.

For more details, see g_file_create() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_create_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) CreateFinish 

func (file *File) CreateFinish(res AsyncResulter) (*FileOutputStream, error)

CreateFinish finishes an asynchronous file create operation started with g_file_create_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileOutputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) CreateReadwrite 

func (file *File) CreateReadwrite(ctx context.Context, flags FileCreateFlags) (*FileIOStream, error)

CreateReadwrite creates a new file and returns a stream for reading and writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass G_FILE_CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If a file or directory with this name already exists, the G_IO_ERROR_EXISTS error will be returned. Some file systems don't allow all file names, and may return an G_IO_ERROR_INVALID_FILENAME error, and if the name is too long, G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.

The function returns the following values:

  • fileIOStream for the newly created file, or NULL on error. Free the returned object with g_object_unref().

func (*File) CreateReadwriteAsync 

func (file *File) CreateReadwriteAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)

CreateReadwriteAsync: asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.

For more details, see g_file_create_readwrite() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_create_readwrite_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of CreateFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) CreateReadwriteFinish 

func (file *File) CreateReadwriteFinish(res AsyncResulter) (*FileIOStream, error)

CreateReadwriteFinish finishes an asynchronous file create operation started with g_file_create_readwrite_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileIOStream or NULL on error. Free the returned object with g_object_unref().

func (*File) Delete 

func (file *File) Delete(ctx context.Context) error

Delete deletes a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink().

If file doesn’t exist, G_IO_ERROR_NOT_FOUND will be returned. This allows for deletion to be implemented avoiding time-of-check to time-of-use races (https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): 

g_autoptr(GError) local_error = NULL;
if (!g_file_delete (my_file, my_cancellable, &local_error) &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
  {
    // deletion failed for some reason other than the file not existing:
    // so report the error
    g_warning ("Failed to delete s: s",
               g_file_peek_path (my_file), local_error->message);
  }

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*File) DeleteAsync 

func (file *File) DeleteAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

DeleteAsync: asynchronously delete a file. If the file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*File) DeleteFinish 

func (file *File) DeleteFinish(result AsyncResulter) error

DeleteFinish finishes deleting a file started with g_file_delete_async().

The function takes the following parameters:

  • result: Result.

func (*File) Dup 

func (file *File) Dup() *File

Dup duplicates a #GFile handle. This operation does not duplicate the actual file or directory represented by the #GFile; see g_file_copy() if attempting to copy a file.

g_file_dup() is useful when a second handle is needed to the same underlying file, for use in a separate thread (#GFile is not thread-safe). For use within the same thread, use g_object_ref() to increment the existing object’s reference count.

This call does no blocking I/O.

The function returns the following values:

  • ret: new #GFile that is a duplicate of the given #GFile.

func (*File) EjectMountable deprecated 

func (file *File) EjectMountable(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

EjectMountable starts an asynchronous eject on a mountable. When this operation has completed, callback will be called with user_user data, and the operation can be finalized with g_file_eject_mountable_finish().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

Deprecated: Use g_file_eject_mountable_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) EjectMountableFinish deprecated 

func (file *File) EjectMountableFinish(result AsyncResulter) error

EjectMountableFinish finishes an asynchronous eject operation started by g_file_eject_mountable().

Deprecated: Use g_file_eject_mountable_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*File) EjectMountableWithOperation 

func (file *File) EjectMountableWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

EjectMountableWithOperation starts an asynchronous eject on a mountable. When this operation has completed, callback will be called with user_user data, and the operation can be finalized with g_file_eject_mountable_with_operation_finish().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional): Operation, or NULL to avoid user interaction.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) EjectMountableWithOperationFinish 

func (file *File) EjectMountableWithOperationFinish(result AsyncResulter) error

EjectMountableWithOperationFinish finishes an asynchronous eject operation started by g_file_eject_mountable_with_operation().

The function takes the following parameters:

  • result: Result.

func (*File) EnumerateChildren 

func (file *File) EnumerateChildren(ctx context.Context, attributes string, flags FileQueryInfoFlags) (*FileEnumerator, error)

EnumerateChildren gets the requested information about the files in a directory. The result is a Enumerator object that will give out Info objects for all the files in the directory.

The attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like G_FILE_ATTRIBUTE_STANDARD_NAME. G_FILE_ATTRIBUTE_STANDARD_NAME should always be specified if you plan to call g_file_enumerator_get_child() or g_file_enumerator_iterate() on the returned enumerator.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. If the file is not a directory, the G_IO_ERROR_NOT_DIRECTORY error will be returned. Other errors are possible too.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.
  • flags: set of QueryInfoFlags.

The function returns the following values:

  • fileEnumerator if successful, NULL on error. Free the returned object with g_object_unref().

func (*File) EnumerateChildrenAsync 

func (file *File) EnumerateChildrenAsync(ctx context.Context, attributes string, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)

EnumerateChildrenAsync: asynchronously gets the requested information about the files in a directory. The result is a Enumerator object that will give out Info objects for all the files in the directory.

For more details, see g_file_enumerate_children() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_enumerate_children_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.
  • flags: set of QueryInfoFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) EnumerateChildrenFinish 

func (file *File) EnumerateChildrenFinish(res AsyncResulter) (*FileEnumerator, error)

EnumerateChildrenFinish finishes an async enumerate children operation. See g_file_enumerate_children_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileEnumerator or NULL if an error occurred. Free the returned object with g_object_unref().

func (*File) Equal 

func (file1 *File) Equal(file2 Filer) bool

Equal checks if the two given #GFiles refer to the same file.

Note that two #GFiles that differ can still refer to the same file on the filesystem due to various forms of filename aliasing.

This call does no blocking I/O.

The function takes the following parameters:

  • file2: second #GFile.

The function returns the following values:

  • ok: TRUE if file1 and file2 are equal.

func (*File) FindEnclosingMount 

func (file *File) FindEnclosingMount(ctx context.Context) (*Mount, error)

FindEnclosingMount gets a #GMount for the #GFile.

#GMount is returned only for user interesting locations, see Monitor. If the Iface for file does not have a #mount, error will be set to G_IO_ERROR_NOT_FOUND and NULL #will be returned.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • mount where the file is located or NULL on error. Free the returned object with g_object_unref().

func (*File) FindEnclosingMountAsync 

func (file *File) FindEnclosingMountAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

FindEnclosingMountAsync: asynchronously gets the mount for the file.

For more details, see g_file_find_enclosing_mount() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_find_enclosing_mount_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) FindEnclosingMountFinish 

func (file *File) FindEnclosingMountFinish(res AsyncResulter) (*Mount, error)

FindEnclosingMountFinish finishes an asynchronous find mount request. See g_file_find_enclosing_mount_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • mount for given file or NULL on error. Free the returned object with g_object_unref().

func (*File) HasParent 

func (file *File) HasParent(parent Filer) bool

HasParent checks if file has a parent, and optionally, if it is parent.

If parent is NULL then this function returns TRUE if file has any parent at all. If parent is non-NULL then TRUE is only returned if file is an immediate child of parent.

The function takes the following parameters:

  • parent (optional) to check for, or NULL.

The function returns the following values:

  • ok: TRUE if file is an immediate child of parent (or any parent in the case that parent is NULL).

func (*File) HasPrefix 

func (file *File) HasPrefix(prefix Filer) bool

HasPrefix checks whether file has the prefix specified by prefix.

In other words, if the names of initial elements of file's pathname match prefix. Only full pathname elements are matched, so a path like /foo is not considered a prefix of /foobar, only of /foo/bar.

A #GFile is not a prefix of itself. If you want to check for equality, use g_file_equal().

This call does no I/O, as it works purely on names. As such it can sometimes return FALSE even if file is inside a prefix (from a filesystem point of view), because the prefix of file is an alias of prefix.

The function takes the following parameters:

  • prefix: input #GFile.

The function returns the following values:

  • ok: TRUE if the file's parent, grandparent, etc is prefix, FALSE otherwise.

func (*File) HasURIScheme 

func (file *File) HasURIScheme(uriScheme string) bool

HasURIScheme checks to see if a #GFile has a given URI scheme.

This call does no blocking I/O.

The function takes the following parameters:

  • uriScheme: string containing a URI scheme.

The function returns the following values:

  • ok: TRUE if #GFile's backend supports the given URI scheme, FALSE if URI scheme is NULL, not supported, or #GFile is invalid.

func (*File) Hash 

func (file *File) Hash() uint

Hash creates a hash value for a #GFile.

This call does no blocking I/O.

The function returns the following values:

  • guint: 0 if file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a Table or similar data structure.

func (*File) IsNative 

func (file *File) IsNative() bool

IsNative checks to see if a file is native to the platform.

A native file is one expressed in the platform-native filename format, e.g. "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it might be on a locally mounted remote filesystem.

On some systems non-native files may be available using the native filesystem via a userspace filesystem (FUSE), in these cases this call will return FALSE, but g_file_get_path() will still return a native path.

This call does no blocking I/O.

The function returns the following values:

  • ok: TRUE if file is native.

func (*File) LoadBytes 

func (file *File) LoadBytes(ctx context.Context) (string, *glib.Bytes, error)

LoadBytes loads the contents of file and returns it as #GBytes.

If file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling g_file_load_contents() and g_bytes_new_take().

For resources, etag_out will be set to NULL.

The data contained in the resulting #GBytes is always zero-terminated, but this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use.

The function takes the following parameters:

  • ctx (optional) or NULL.

The function returns the following values:

  • etagOut (optional): location to place the current entity tag for the file, or NULL if the entity tag is not needed.
  • bytes or NULL and error is set.

func (*File) LoadBytesAsync 

func (file *File) LoadBytesAsync(ctx context.Context, callback AsyncReadyCallback)

LoadBytesAsync: asynchronously loads the contents of file as #GBytes.

If file is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling g_file_load_contents_async() and g_bytes_new_take().

callback should call g_file_load_bytes_finish() to get the result of this asynchronous operation.

See g_file_load_bytes() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) LoadBytesFinish 

func (file *File) LoadBytesFinish(result AsyncResulter) (string, *glib.Bytes, error)

LoadBytesFinish completes an asynchronous request to g_file_load_bytes_async().

For resources, etag_out will be set to NULL.

The data contained in the resulting #GBytes is always zero-terminated, but this is not included in the #GBytes length. The resulting #GBytes should be freed with g_bytes_unref() when no longer in use.

See g_file_load_bytes() for more information.

The function takes the following parameters:

  • result provided to the callback.

The function returns the following values:

  • etagOut (optional): location to place the current entity tag for the file, or NULL if the entity tag is not needed.
  • bytes or NULL and error is set.

func (*File) LoadContents 

func (file *File) LoadContents(ctx context.Context) ([]byte, string, error)

LoadContents loads the content of the file into memory. The data is always zero-terminated, but this is not included in the resultant length. The returned contents should be freed with g_free() when no longer needed.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • contents: location to place the contents of the file.
  • etagOut (optional): location to place the current entity tag for the file, or NULL if the entity tag is not needed.

func (*File) LoadContentsAsync 

func (file *File) LoadContentsAsync(ctx context.Context, callback AsyncReadyCallback)

LoadContentsAsync starts an asynchronous load of the file's contents.

For more details, see g_file_load_contents() which is the synchronous version of this call.

When the load operation has completed, callback will be called with user data. To finish the operation, call g_file_load_contents_finish() with the Result returned by the callback.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • callback (optional) to call when the request is satisfied.

func (*File) LoadContentsFinish 

func (file *File) LoadContentsFinish(res AsyncResulter) ([]byte, string, error)

LoadContentsFinish finishes an asynchronous load of the file's contents. The contents are placed in contents, and length is set to the size of the contents string. The contents should be freed with g_free() when no longer needed. If etag_out is present, it will be set to the new entity tag for the file.

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • contents: location to place the contents of the file.
  • etagOut (optional): location to place the current entity tag for the file, or NULL if the entity tag is not needed.

func (*File) LoadPartialContentsFinish 

func (file *File) LoadPartialContentsFinish(res AsyncResulter) ([]byte, string, error)

LoadPartialContentsFinish finishes an asynchronous partial load operation that was started with g_file_load_partial_contents_async(). The data is always zero-terminated, but this is not included in the resultant length. The returned contents should be freed with g_free() when no longer needed.

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • contents: location to place the contents of the file.
  • etagOut (optional): location to place the current entity tag for the file, or NULL if the entity tag is not needed.

func (*File) MakeDirectory 

func (file *File) MakeDirectory(ctx context.Context) error

MakeDirectory creates a directory. Note that this will only create a child directory of the immediate parent directory of the path or URI given by the #GFile. To recursively create directories, see g_file_make_directory_with_parents(). This function will fail if the parent directory does not exist, setting error to G_IO_ERROR_NOT_FOUND. If the file system doesn't support creating directories, this function will fail, setting error to G_IO_ERROR_NOT_SUPPORTED.

For a local #GFile the newly created directory will have the default (current) ownership and permissions of the current process.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*File) MakeDirectoryAsync 

func (file *File) MakeDirectoryAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

MakeDirectoryAsync: asynchronously creates a directory.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*File) MakeDirectoryFinish 

func (file *File) MakeDirectoryFinish(result AsyncResulter) error

MakeDirectoryFinish finishes an asynchronous directory creation, started with g_file_make_directory_async().

The function takes the following parameters:

  • result: Result.

func (*File) MakeDirectoryWithParents 

func (file *File) MakeDirectoryWithParents(ctx context.Context) error

MakeDirectoryWithParents creates a directory and any parent directories that may not exist similar to 'mkdir -p'. If the file system does not support creating directories, this function will fail, setting error to G_IO_ERROR_NOT_SUPPORTED. If the directory itself already exists, this function will fail setting error to G_IO_ERROR_EXISTS, unlike the similar g_mkdir_with_parents().

For a local #GFile the newly created directories will have the default (current) ownership and permissions of the current process.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
func (file *File) MakeSymbolicLink(ctx context.Context, symlinkValue string) error

MakeSymbolicLink creates a symbolic link named file which contains the string symlink_value.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • symlinkValue: string with the path for the target of the new symlink.

func (*File) MakeSymbolicLinkAsync added in v0.3.1 

func (file *File) MakeSymbolicLinkAsync(ctx context.Context, symlinkValue string, ioPriority int, callback AsyncReadyCallback)

MakeSymbolicLinkAsync: asynchronously creates a symbolic link named file which contains the string symlink_value.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • symlinkValue: string with the path for the target of the new symlink.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*File) MakeSymbolicLinkFinish added in v0.3.0 

func (file *File) MakeSymbolicLinkFinish(result AsyncResulter) error

MakeSymbolicLinkFinish finishes an asynchronous symbolic link creation, started with g_file_make_symbolic_link_async().

The function takes the following parameters:

  • result: Result.

func (*File) MeasureDiskUsageFinish 

func (file *File) MeasureDiskUsageFinish(result AsyncResulter) (diskUsage, numDirs, numFiles uint64, goerr error)

MeasureDiskUsageFinish collects the results from an earlier call to g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for more information.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • diskUsage (optional): number of bytes of disk space used.
  • numDirs (optional): number of directories encountered.
  • numFiles (optional): number of non-directories encountered.

func (*File) Monitor 

func (file *File) Monitor(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)

Monitor obtains a file or directory monitor for the given file, depending on the type of the file.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of MonitorFlags.

The function returns the following values:

  • fileMonitor for the given file, or NULL on error. Free the returned object with g_object_unref().

func (*File) MonitorDirectory 

func (file *File) MonitorDirectory(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)

MonitorDirectory obtains a directory monitor for the given file. This may fail if directory monitoring is not supported.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

It does not make sense for flags to contain G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to directories. It is not possible to monitor all the files in a directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of MonitorFlags.

The function returns the following values:

  • fileMonitor for the given file, or NULL on error. Free the returned object with g_object_unref().

func (*File) MonitorFile 

func (file *File) MonitorFile(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)

MonitorFile obtains a file monitor for the given file. If no file notification mechanism exists, then regular polling of the file is used.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If flags contains G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor will also attempt to report changes made to the file via another filename (ie, a hard link). Without this flag, you can only rely on changes made through the filename contained in file to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the Monitor backend and/or filesystem type.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of MonitorFlags.

The function returns the following values:

  • fileMonitor for the given file, or NULL on error. Free the returned object with g_object_unref().

func (*File) MountEnclosingVolume 

func (location *File) MountEnclosingVolume(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

MountEnclosingVolume starts a mount_operation, mounting the volume that contains the file location.

When this operation has completed, callback will be called with user_user data, and the operation can be finalized with g_file_mount_enclosing_volume_finish().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional): Operation or NULL to avoid user interaction.
  • callback (optional) to call when the request is satisfied, or NULL.

func (*File) MountEnclosingVolumeFinish 

func (location *File) MountEnclosingVolumeFinish(result AsyncResulter) error

MountEnclosingVolumeFinish finishes a mount operation started by g_file_mount_enclosing_volume().

The function takes the following parameters:

  • result: Result.

func (*File) MountMountable 

func (file *File) MountMountable(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

MountMountable mounts a file of type G_FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when, for instance, passwords are needed during authentication.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional): Operation, or NULL to avoid user interaction.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) MountMountableFinish 

func (file *File) MountMountableFinish(result AsyncResulter) (*File, error)

MountMountableFinish finishes a mount operation. See g_file_mount_mountable() for details.

Finish an asynchronous mount operation that was started with g_file_mount_mountable().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • ret or NULL on error. Free the returned object with g_object_unref().

func (*File) MoveFinish added in v0.3.0 

func (file *File) MoveFinish(result AsyncResulter) error

MoveFinish finishes an asynchronous file movement, started with g_file_move_async().

The function takes the following parameters:

  • result: Result.

func (*File) OpenReadwrite 

func (file *File) OpenReadwrite(ctx context.Context) (*FileIOStream, error)

OpenReadwrite opens an existing file for reading and writing. The result is a IOStream that can be used to read and write the contents of the file.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

The function takes the following parameters:

  • ctx (optional): #GCancellable.

The function returns the following values:

  • fileIOStream or NULL on error. Free the returned object with g_object_unref().

func (*File) OpenReadwriteAsync 

func (file *File) OpenReadwriteAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

OpenReadwriteAsync: asynchronously opens file for reading and writing.

For more details, see g_file_open_readwrite() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_open_readwrite_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) OpenReadwriteFinish 

func (file *File) OpenReadwriteFinish(res AsyncResulter) (*FileIOStream, error)

OpenReadwriteFinish finishes an asynchronous file read operation started with g_file_open_readwrite_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileIOStream or NULL on error. Free the returned object with g_object_unref().

func (*File) Parent 

func (file *File) Parent() *File

Parent gets the parent directory for the file. If the file represents the root directory of the file system, then NULL will be returned.

This call does no blocking I/O.

The function returns the following values:

  • ret (optional) structure to the parent of the given #GFile or NULL if there is no parent. Free the returned object with g_object_unref().

func (*File) ParseName 

func (file *File) ParseName() string

ParseName gets the parse name of the file. A parse name is a UTF-8 string that describes the file such that one can get the #GFile back using g_file_parse_name().

This is generally used to show the #GFile as a nice full-pathname kind of string in a user interface, like in a location entry.

For local files with names that can safely be converted to UTF-8 the pathname is used, otherwise the IRI is used (a form of URI that allows UTF-8 characters unescaped).

This call does no blocking I/O.

The function returns the following values:

  • utf8: string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed.

func (*File) Path 

func (file *File) Path() string

Path gets the local pathname for #GFile, if one exists. If non-NULL, this is guaranteed to be an absolute, canonical path. It might contain symlinks.

This call does no blocking I/O.

The function returns the following values:

  • filename (optional): string containing the #GFile's path, or NULL if no such path exists. The returned string should be freed with g_free() when no longer needed.

func (*File) PeekPath 

func (file *File) PeekPath() string

PeekPath: exactly like g_file_get_path(), but caches the result via g_object_set_qdata_full(). This is useful for example in C applications which mix g_file_* APIs with native ones. It also avoids an extra duplicated string when possible, so will be generally more efficient.

This call does no blocking I/O.

The function returns the following values:

  • filename (optional): string containing the #GFile's path, or NULL if no such path exists. The returned string is owned by file.

func (*File) PollMountable 

func (file *File) PollMountable(ctx context.Context, callback AsyncReadyCallback)

PollMountable polls a file of type G_FILE_TYPE_MOUNTABLE.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • callback (optional) to call when the request is satisfied, or NULL.

func (*File) PollMountableFinish 

func (file *File) PollMountableFinish(result AsyncResulter) error

PollMountableFinish finishes a poll operation. See g_file_poll_mountable() for details.

Finish an asynchronous poll operation that was polled with g_file_poll_mountable().

The function takes the following parameters:

  • result: Result.

func (*File) QueryDefaultHandler 

func (file *File) QueryDefaultHandler(ctx context.Context) (*AppInfo, error)

QueryDefaultHandler returns the Info that is registered as the default application to handle the file specified by file.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • appInfo if the handle was found, NULL if there were errors. When you are done with it, release it with g_object_unref().

func (*File) QueryDefaultHandlerAsync 

func (file *File) QueryDefaultHandlerAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

QueryDefaultHandlerAsync: async version of g_file_query_default_handler().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is done.

func (*File) QueryDefaultHandlerFinish 

func (file *File) QueryDefaultHandlerFinish(result AsyncResulter) (*AppInfo, error)

QueryDefaultHandlerFinish finishes a g_file_query_default_handler_async() operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • appInfo if the handle was found, NULL if there were errors. When you are done with it, release it with g_object_unref().

func (*File) QueryExists 

func (file *File) QueryExists(ctx context.Context) bool

QueryExists: utility function to check if a particular file exists. This is implemented using g_file_query_info() and as such does blocking I/O.

Note that in many cases it is racy to first check for file existence (https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the file might have been created or removed in between the operations. The general approach to handling that is to not check, but just do the operation and handle the errors as they come.

As an example of race-free checking, take the case of reading a file, and if it doesn't exist, creating it. There are two racy versions: read it, and on error create it; and: check if it exists, if not create it. These can both result in two processes creating the file (with perhaps a partially written file as the result). The correct approach is to always try to create the file with g_file_create() which will either atomically create the file or fail with a G_IO_ERROR_EXISTS error.

However, in many cases an existence check is useful in a user interface, for instance to make a menu item sensitive/insensitive, so that you don't have to fool users that something is possible and then just show an error dialog. If you do this, you should make sure to also handle the errors that can happen due to races when you execute the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • ok: TRUE if the file exists (and can be detected without error), FALSE otherwise (or if cancelled).

func (*File) QueryFileType 

func (file *File) QueryFileType(ctx context.Context, flags FileQueryInfoFlags) FileType

QueryFileType: utility function to inspect the Type of a file. This is implemented using g_file_query_info() and as such does blocking I/O.

The primary use case of this method is to check if a file is a regular file, directory, or symlink.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags: set of QueryInfoFlags passed to g_file_query_info().

The function returns the following values:

  • fileType of the file and G_FILE_TYPE_UNKNOWN if the file does not exist.

func (*File) QueryFilesystemInfo 

func (file *File) QueryFilesystemInfo(ctx context.Context, attributes string) (*FileInfo, error)

QueryFilesystemInfo: similar to g_file_query_info(), but obtains information about the filesystem the file is on, rather than the file itself. For instance the amount of space available and the type of the filesystem.

The attributes value is a string that specifies the attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "filesystem::*" means all attributes in the filesystem namespace. The standard namespace for filesystem attributes is "filesystem". Common attributes of interest are G_FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), G_FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and G_FILE_ATTRIBUTE_FILESYSTEM_TYPE (type of the filesystem).

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.

The function returns the following values:

  • fileInfo or NULL if there was an error. Free the returned object with g_object_unref().

func (*File) QueryFilesystemInfoAsync 

func (file *File) QueryFilesystemInfoAsync(ctx context.Context, attributes string, ioPriority int, callback AsyncReadyCallback)

QueryFilesystemInfoAsync: asynchronously gets the requested information about the filesystem that the specified file is on. The result is a Info object that contains key-value attributes (such as type or size for the file).

For more details, see g_file_query_filesystem_info() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_query_info_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) QueryFilesystemInfoFinish 

func (file *File) QueryFilesystemInfoFinish(res AsyncResulter) (*FileInfo, error)

QueryFilesystemInfoFinish finishes an asynchronous filesystem info query. See g_file_query_filesystem_info_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileInfo for given file or NULL on error. Free the returned object with g_object_unref().

func (*File) QueryInfo 

func (file *File) QueryInfo(ctx context.Context, attributes string, flags FileQueryInfoFlags) (*FileInfo, error)

QueryInfo gets the requested information about specified file. The result is a Info object that contains key-value attributes (such as the type or size of the file).

The attributes value is a string that specifies the file attributes that should be gathered. It is not an error if it's not possible to read a particular requested attribute from a file - it just won't be set. attributes should be a comma-separated list of attributes or attribute wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all attributes in the standard namespace. An example attribute query be "standard::*,owner::user". The standard attributes are available as defines, like G_FILE_ATTRIBUTE_STANDARD_NAME.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

For symlinks, normally the information about the target of the symlink is returned, rather than information about the symlink itself. However if you pass G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in flags the information about the symlink itself will be returned. Also, for symlinks that point to non-existing files the information about the symlink itself will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.
  • flags: set of QueryInfoFlags.

The function returns the following values:

  • fileInfo for the given file, or NULL on error. Free the returned object with g_object_unref().

func (*File) QueryInfoAsync 

func (file *File) QueryInfoAsync(ctx context.Context, attributes string, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)

QueryInfoAsync: asynchronously gets the requested information about specified file. The result is a Info object that contains key-value attributes (such as type or size for the file).

For more details, see g_file_query_info() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_query_info_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: attribute query string.
  • flags: set of QueryInfoFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) QueryInfoFinish 

func (file *File) QueryInfoFinish(res AsyncResulter) (*FileInfo, error)

QueryInfoFinish finishes an asynchronous file info query. See g_file_query_info_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileInfo for given file or NULL on error. Free the returned object with g_object_unref().

func (*File) QuerySettableAttributes 

func (file *File) QuerySettableAttributes(ctx context.Context) (*FileAttributeInfoList, error)

QuerySettableAttributes: obtain the list of settable attributes for the file.

Returns the type and full attribute name of all the attributes that can be set on this file. This doesn't mean setting it will always succeed though, you might get an access failure, or some specific file may not support a specific attribute.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • fileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref().

func (*File) QueryWritableNamespaces 

func (file *File) QueryWritableNamespaces(ctx context.Context) (*FileAttributeInfoList, error)

QueryWritableNamespaces: obtain the list of attribute namespaces where new attributes can be created by a user. An example of this is extended attributes (in the "xattr" namespace).

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • fileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref().

func (*File) Read 

func (file *File) Read(ctx context.Context) (*FileInputStream, error)

Read opens a file for reading. The result is a InputStream that can be used to read the contents of the file.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): #GCancellable.

The function returns the following values:

  • fileInputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) ReadAsync 

func (file *File) ReadAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

ReadAsync: asynchronously opens file for reading.

For more details, see g_file_read() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_read_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) ReadFinish 

func (file *File) ReadFinish(res AsyncResulter) (*FileInputStream, error)

ReadFinish finishes an asynchronous file read operation started with g_file_read_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileInputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) RelativePath 

func (parent *File) RelativePath(descendant Filer) string

RelativePath gets the path for descendant relative to parent.

This call does no blocking I/O.

The function takes the following parameters:

  • descendant: input #GFile.

The function returns the following values:

  • filename (optional): string with the relative path from descendant to parent, or NULL if descendant doesn't have parent as prefix. The returned string should be freed with g_free() when no longer needed.

func (*File) Replace 

func (file *File) Replace(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags) (*FileOutputStream, error)

Replace returns an output stream for overwriting the file, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

This will try to replace the file in the safest way possible so that any errors during the writing will not affect an already existing copy of the file. For instance, for local files it may write to a temporary file and then atomically rename over the destination when the stream is closed.

By default files created are generally readable by everyone, but if you pass G_FILE_CREATE_PRIVATE in flags the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If you pass in a non-NULL etag value and file already exists, then this value is compared to the current entity tag of the file, and if they differ an G_IO_ERROR_WRONG_ETAG error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from g_file_output_stream_get_etag() after you've finished writing and closed the OutputStream. When you load a new file you can use g_file_input_stream_query_info() to get the etag of the file.

If make_backup is TRUE, this function will attempt to make a backup of the current file before overwriting it. If this fails a G_IO_ERROR_CANT_CREATE_BACKUP error will be returned. If you want to replace anyway, try again with make_backup set to FALSE.

If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned, and if the file is some other form of non-regular file then a G_IO_ERROR_NOT_REGULAR_FILE error will be returned. Some file systems don't allow all file names, and may return an G_IO_ERROR_INVALID_FILENAME error, and if the name is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • etag (optional): optional entity tag (#entity-tags) for the current #GFile, or LL to ignore.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.

The function returns the following values:

  • fileOutputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) ReplaceAsync 

func (file *File) ReplaceAsync(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)

ReplaceAsync: asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first.

For more details, see g_file_replace() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_replace_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • etag (optional): entity tag (#entity-tags) for the current #GFile, or NULL to ignore.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) ReplaceContents 

func (file *File) ReplaceContents(ctx context.Context, contents, etag string, makeBackup bool, flags FileCreateFlags) (string, error)

ReplaceContents replaces the contents of file with contents of length bytes.

If etag is specified (not NULL), any existing file must have that etag, or the error G_IO_ERROR_WRONG_ETAG will be returned.

If make_backup is TRUE, this function will attempt to make a backup of file. Internally, it uses g_file_replace(), so will try to replace the file contents in the safest way possible. For example, atomic renames are used when replacing local files’ contents.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The returned new_etag can be used to verify that the file hasn't changed the next time it is saved over.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • contents: string containing the new contents for file.
  • etag (optional): old entity-tag (#entity-tags) for the document, or NULL.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.

The function returns the following values:

  • newEtag (optional): location to a new entity tag (#entity-tags) for the document. This should be freed with g_free() when no longer needed, or NULL.

func (*File) ReplaceContentsAsync 

func (file *File) ReplaceContentsAsync(ctx context.Context, contents, etag string, makeBackup bool, flags FileCreateFlags, callback AsyncReadyCallback)

ReplaceContentsAsync starts an asynchronous replacement of file with the given contents of length bytes. etag will replace the document's current entity tag.

When this operation has completed, callback will be called with user_user data, and the operation can be finalized with g_file_replace_contents_finish().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

If make_backup is TRUE, this function will attempt to make a backup of file.

Note that no copy of contents will be made, so it must stay valid until callback is called. See g_file_replace_contents_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • contents: string of contents to replace the file with.
  • etag (optional): new entity tag (#entity-tags) for the file, or NULL.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.
  • callback (optional) to call when the request is satisfied.

func (*File) ReplaceContentsBytesAsync 

func (file *File) ReplaceContentsBytesAsync(ctx context.Context, contents *glib.Bytes, etag string, makeBackup bool, flags FileCreateFlags, callback AsyncReadyCallback)

ReplaceContentsBytesAsync: same as g_file_replace_contents_async() but takes a #GBytes input instead. This function will keep a ref on contents until the operation is done. Unlike g_file_replace_contents_async() this allows forgetting about the content without waiting for the callback.

When this operation has completed, callback will be called with user_user data, and the operation can be finalized with g_file_replace_contents_finish().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • contents: #GBytes.
  • etag (optional): new entity tag (#entity-tags) for the file, or NULL.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.
  • callback (optional) to call when the request is satisfied.

func (*File) ReplaceContentsFinish 

func (file *File) ReplaceContentsFinish(res AsyncResulter) (string, error)

ReplaceContentsFinish finishes an asynchronous replace of the given file. See g_file_replace_contents_async(). Sets new_etag to the new entity tag for the document, if present.

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • newEtag (optional): location of a new entity tag (#entity-tags) for the document. This should be freed with g_free() when it is no longer needed, or NULL.

func (*File) ReplaceFinish 

func (file *File) ReplaceFinish(res AsyncResulter) (*FileOutputStream, error)

ReplaceFinish finishes an asynchronous file replace operation started with g_file_replace_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileOutputStream or NULL on error. Free the returned object with g_object_unref().

func (*File) ReplaceReadwrite 

func (file *File) ReplaceReadwrite(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags) (*FileIOStream, error)

ReplaceReadwrite returns an output stream for overwriting the file in readwrite mode, possibly creating a backup copy of the file first. If the file doesn't exist, it will be created.

For details about the behaviour, see g_file_replace() which does the same thing but returns an output stream only.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • etag (optional): optional entity tag (#entity-tags) for the current #GFile, or LL to ignore.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.

The function returns the following values:

  • fileIOStream or NULL on error. Free the returned object with g_object_unref().

func (*File) ReplaceReadwriteAsync 

func (file *File) ReplaceReadwriteAsync(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)

ReplaceReadwriteAsync: asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first.

For more details, see g_file_replace_readwrite() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_replace_readwrite_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • etag (optional): entity tag (#entity-tags) for the current #GFile, or NULL to ignore.
  • makeBackup: TRUE if a backup should be created.
  • flags: set of CreateFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) ReplaceReadwriteFinish 

func (file *File) ReplaceReadwriteFinish(res AsyncResulter) (*FileIOStream, error)

ReplaceReadwriteFinish finishes an asynchronous file replace operation started with g_file_replace_readwrite_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • fileIOStream or NULL on error. Free the returned object with g_object_unref().

func (*File) ResolveRelativePath 

func (file *File) ResolveRelativePath(relativePath string) *File

ResolveRelativePath resolves a relative path for file to an absolute path.

This call does no blocking I/O.

If the relative_path is an absolute path name, the resolution is done absolutely (without taking file path as base).

The function takes the following parameters:

  • relativePath: given relative path string.

The function returns the following values:

  • ret for the resolved path.

func (*File) SetAttribute 

func (file *File) SetAttribute(ctx context.Context, attribute string, typ FileAttributeType, valueP unsafe.Pointer, flags FileQueryInfoFlags) error

SetAttribute sets an attribute in the file with attribute name attribute to value_p.

Some attributes can be unset by setting type to G_FILE_ATTRIBUTE_TYPE_INVALID and value_p to NULL.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • typ: type of the attribute.
  • valueP (optional): pointer to the value (or the pointer itself if the type is a pointer type).
  • flags: set of QueryInfoFlags.

func (*File) SetAttributeByteString 

func (file *File) SetAttributeByteString(ctx context.Context, attribute, value string, flags FileQueryInfoFlags) error

SetAttributeByteString sets attribute of type G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to value. If attribute is of a different type, this operation will fail, returning FALSE.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value: string containing the attribute's new value.
  • flags: QueryInfoFlags.

func (*File) SetAttributeInt32 

func (file *File) SetAttributeInt32(ctx context.Context, attribute string, value int32, flags FileQueryInfoFlags) error

SetAttributeInt32 sets attribute of type G_FILE_ATTRIBUTE_TYPE_INT32 to value. If attribute is of a different type, this operation will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value containing the attribute's new value.
  • flags: QueryInfoFlags.

func (*File) SetAttributeInt64 

func (file *File) SetAttributeInt64(ctx context.Context, attribute string, value int64, flags FileQueryInfoFlags) error

SetAttributeInt64 sets attribute of type G_FILE_ATTRIBUTE_TYPE_INT64 to value. If attribute is of a different type, this operation will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value containing the attribute's new value.
  • flags: QueryInfoFlags.

func (*File) SetAttributeString 

func (file *File) SetAttributeString(ctx context.Context, attribute, value string, flags FileQueryInfoFlags) error

SetAttributeString sets attribute of type G_FILE_ATTRIBUTE_TYPE_STRING to value. If attribute is of a different type, this operation will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value: string containing the attribute's value.
  • flags: QueryInfoFlags.

func (*File) SetAttributeUint32 

func (file *File) SetAttributeUint32(ctx context.Context, attribute string, value uint32, flags FileQueryInfoFlags) error

SetAttributeUint32 sets attribute of type G_FILE_ATTRIBUTE_TYPE_UINT32 to value. If attribute is of a different type, this operation will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value containing the attribute's new value.
  • flags: QueryInfoFlags.

func (*File) SetAttributeUint64 

func (file *File) SetAttributeUint64(ctx context.Context, attribute string, value uint64, flags FileQueryInfoFlags) error

SetAttributeUint64 sets attribute of type G_FILE_ATTRIBUTE_TYPE_UINT64 to value. If attribute is of a different type, this operation will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attribute: string containing the attribute's name.
  • value containing the attribute's new value.
  • flags: QueryInfoFlags.

func (*File) SetAttributesAsync 

func (file *File) SetAttributesAsync(ctx context.Context, info *FileInfo, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)

SetAttributesAsync: asynchronously sets the attributes of file with info.

For more details, see g_file_set_attributes_from_info(), which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_set_attributes_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • info: Info.
  • flags: QueryInfoFlags.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) SetAttributesFinish 

func (file *File) SetAttributesFinish(result AsyncResulter) (*FileInfo, error)

SetAttributesFinish finishes setting an attribute started in g_file_set_attributes_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • info: Info.

func (*File) SetAttributesFromInfo 

func (file *File) SetAttributesFromInfo(ctx context.Context, info *FileInfo, flags FileQueryInfoFlags) error

SetAttributesFromInfo tries to set all attributes in the Info on the target values, not stopping on the first error.

If there is any error during this operation then error will be set to the first error. Error on particular fields are flagged by setting the "status" field in the attribute value to G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect further errors.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • info: Info.
  • flags: QueryInfoFlags.

func (*File) SetDisplayName 

func (file *File) SetDisplayName(ctx context.Context, displayName string) (*File, error)

SetDisplayName renames file to the specified display name.

The display name is converted from UTF-8 to the correct encoding for the target filesystem if possible and the file is renamed to this.

If you want to implement a rename operation in the user interface the edit name (G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the initial value in the rename widget, and then the result after editing should be passed to g_file_set_display_name().

On success the resulting converted filename is returned.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • displayName: string.

The function returns the following values:

  • ret specifying what file was renamed to, or NULL if there was an error. Free the returned object with g_object_unref().

func (*File) SetDisplayNameAsync 

func (file *File) SetDisplayNameAsync(ctx context.Context, displayName string, ioPriority int, callback AsyncReadyCallback)

SetDisplayNameAsync: asynchronously sets the display name for a given #GFile.

For more details, see g_file_set_display_name() which is the synchronous version of this call.

When the operation is finished, callback will be called. You can then call g_file_set_display_name_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • displayName: string.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) SetDisplayNameFinish 

func (file *File) SetDisplayNameFinish(res AsyncResulter) (*File, error)

SetDisplayNameFinish finishes setting a display name started with g_file_set_display_name_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • ret or NULL on error. Free the returned object with g_object_unref().

func (*File) StartMountable 

func (file *File) StartMountable(ctx context.Context, flags DriveStartFlags, startOperation *MountOperation, callback AsyncReadyCallback)

StartMountable starts a file of type G_FILE_TYPE_MOUNTABLE. Using start_operation, you can request callbacks when, for instance, passwords are needed during authentication.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_mount_mountable_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • startOperation (optional) or NULL to avoid user interaction.
  • callback (optional) to call when the request is satisfied, or NULL.

func (*File) StartMountableFinish 

func (file *File) StartMountableFinish(result AsyncResulter) error

StartMountableFinish finishes a start operation. See g_file_start_mountable() for details.

Finish an asynchronous start operation that was started with g_file_start_mountable().

The function takes the following parameters:

  • result: Result.

func (*File) StopMountable 

func (file *File) StopMountable(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

StopMountable stops a file of type G_FILE_TYPE_MOUNTABLE.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_stop_mountable_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional): Operation, or NULL to avoid user interaction.
  • callback (optional) to call when the request is satisfied, or NULL.

func (*File) StopMountableFinish 

func (file *File) StopMountableFinish(result AsyncResulter) error

StopMountableFinish finishes a stop operation, see g_file_stop_mountable() for details.

Finish an asynchronous stop operation that was started with g_file_stop_mountable().

The function takes the following parameters:

  • result: Result.

func (*File) SupportsThreadContexts 

func (file *File) SupportsThreadContexts() bool

SupportsThreadContexts checks if file supports [thread-default contexts][g-main-context-push-thread-default-context]. If this returns FALSE, you cannot perform asynchronous operations on file in a thread that has a thread-default context.

The function returns the following values:

  • ok: whether or not file supports thread-default contexts.

func (*File) Trash 

func (file *File) Trash(ctx context.Context) error

Trash sends file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Not all file systems support trashing, so this call can return the G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the x-gvfs-notrash unix mount option can be used to disable g_file_trash() support for certain mounts, the G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*File) TrashAsync 

func (file *File) TrashAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

TrashAsync: asynchronously sends file to the Trash location, if possible.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the request is satisfied.

func (*File) TrashFinish 

func (file *File) TrashFinish(result AsyncResulter) error

TrashFinish finishes an asynchronous file trashing operation, started with g_file_trash_async().

The function takes the following parameters:

  • result: Result.

func (*File) URI 

func (file *File) URI() string

URI gets the URI for the file.

This call does no blocking I/O.

The function returns the following values:

  • utf8: string containing the #GFile's URI. If the #GFile was constructed with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed.

func (*File) URIScheme 

func (file *File) URIScheme() string

URIScheme gets the URI scheme for a #GFile. RFC 3986 decodes the scheme as: 

URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

Common schemes include "file", "http", "ftp", etc.

The scheme can be different from the one used to construct the #GFile, in that it might be replaced with one that is logically equivalent to the #GFile.

This call does no blocking I/O.

The function returns the following values:

  • utf8 (optional): string containing the URI scheme for the given #GFile or NULL if the #GFile was constructed with an invalid URI. The returned string should be freed with g_free() when no longer needed.

func (*File) UnmountMountable deprecated 

func (file *File) UnmountMountable(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

UnmountMountable unmounts a file of type G_FILE_TYPE_MOUNTABLE.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation.

Deprecated: Use g_file_unmount_mountable_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) UnmountMountableFinish deprecated 

func (file *File) UnmountMountableFinish(result AsyncResulter) error

UnmountMountableFinish finishes an unmount operation, see g_file_unmount_mountable() for details.

Finish an asynchronous unmount operation that was started with g_file_unmount_mountable().

Deprecated: Use g_file_unmount_mountable_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*File) UnmountMountableWithOperation 

func (file *File) UnmountMountableWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

UnmountMountableWithOperation unmounts a file of type G_FILE_TYPE_MOUNTABLE.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

When the operation is finished, callback will be called. You can then call g_file_unmount_mountable_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional): Operation, or NULL to avoid user interaction.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*File) UnmountMountableWithOperationFinish 

func (file *File) UnmountMountableWithOperationFinish(result AsyncResulter) error

UnmountMountableWithOperationFinish finishes an unmount operation, see g_file_unmount_mountable_with_operation() for details.

Finish an asynchronous unmount operation that was started with g_file_unmount_mountable_with_operation().

The function takes the following parameters:

  • result: Result.

type FileAttributeInfo 

type FileAttributeInfo struct {
	// contains filtered or unexported fields
}

FileAttributeInfo: information about a specific attribute.

An instance of this type is always passed by reference.

func (*FileAttributeInfo) Flags 

func (f *FileAttributeInfo) Flags() FileAttributeInfoFlags

Flags: set of AttributeInfoFlags.

func (*FileAttributeInfo) Name 

func (f *FileAttributeInfo) Name() string

Name: name of the attribute.

func (*FileAttributeInfo) Type 

func (f *FileAttributeInfo) Type() FileAttributeType

Type type of the attribute.

type FileAttributeInfoFlags 

type FileAttributeInfoFlags C.guint

FileAttributeInfoFlags flags specifying the behaviour of an attribute. 

const (
	// FileAttributeInfoNone: no flags set.
	FileAttributeInfoNone FileAttributeInfoFlags = 0b0
	// FileAttributeInfoCopyWithFile: copy the attribute values when the file is
	// copied.
	FileAttributeInfoCopyWithFile FileAttributeInfoFlags = 0b1
	// FileAttributeInfoCopyWhenMoved: copy the attribute values when the file
	// is moved.
	FileAttributeInfoCopyWhenMoved FileAttributeInfoFlags = 0b10
)

func (FileAttributeInfoFlags) Has 

func (f FileAttributeInfoFlags) Has(other FileAttributeInfoFlags) bool

Has returns true if f contains other.

func (FileAttributeInfoFlags) String 

func (f FileAttributeInfoFlags) String() string

String returns the names in string for FileAttributeInfoFlags.

type FileAttributeInfoList 

type FileAttributeInfoList struct {
	// contains filtered or unexported fields
}

FileAttributeInfoList acts as a lightweight registry for possible valid file attributes. The registry stores Key-Value pair formats as AttributeInfos.

An instance of this type is always passed by reference.

func NewFileAttributeInfoList 

func NewFileAttributeInfoList() *FileAttributeInfoList

NewFileAttributeInfoList constructs a struct FileAttributeInfoList.

func (*FileAttributeInfoList) Add 

func (list *FileAttributeInfoList) Add(name string, typ FileAttributeType, flags FileAttributeInfoFlags)

Add adds a new attribute with name to the list, setting its type and flags.

The function takes the following parameters:

  • name of the attribute to add.
  • typ for the attribute.
  • flags for the attribute.

func (*FileAttributeInfoList) Dup 

func (list *FileAttributeInfoList) Dup() *FileAttributeInfoList

Dup makes a duplicate of a file attribute info list.

The function returns the following values:

  • fileAttributeInfoList: copy of the given list.

func (*FileAttributeInfoList) Infos 

func (f *FileAttributeInfoList) Infos() *FileAttributeInfo

Infos: array of AttributeInfos.

func (*FileAttributeInfoList) Lookup 

func (list *FileAttributeInfoList) Lookup(name string) *FileAttributeInfo

Lookup gets the file attribute with the name name from list.

The function takes the following parameters:

  • name of the attribute to look up.

The function returns the following values:

  • fileAttributeInfo for the name, or NULL if an attribute isn't found.

func (*FileAttributeInfoList) NInfos 

func (f *FileAttributeInfoList) NInfos() int

NInfos: number of values in the array.

func (*FileAttributeInfoList) SetNInfos 

func (f *FileAttributeInfoList) SetNInfos(nInfos int)

NInfos: number of values in the array.

type FileAttributeMatcher 

type FileAttributeMatcher struct {
	// contains filtered or unexported fields
}

FileAttributeMatcher determines if a string matches a file attribute.

An instance of this type is always passed by reference.

func NewFileAttributeMatcher 

func NewFileAttributeMatcher(attributes string) *FileAttributeMatcher

NewFileAttributeMatcher constructs a struct FileAttributeMatcher.

func (*FileAttributeMatcher) EnumerateNamespace 

func (matcher *FileAttributeMatcher) EnumerateNamespace(ns string) bool

EnumerateNamespace checks if the matcher will match all of the keys in a given namespace. This will always return TRUE if a wildcard character is in use (e.g. if matcher was created with "standard::*" and ns is "standard", or if matcher was created using "*" and namespace is anything.)

TODO: this is awkwardly worded.

The function takes the following parameters:

  • ns: string containing a file attribute namespace.

The function returns the following values:

  • ok: TRUE if the matcher matches all of the entries in the given ns, FALSE otherwise.

func (*FileAttributeMatcher) EnumerateNext 

func (matcher *FileAttributeMatcher) EnumerateNext() string

EnumerateNext gets the next matched attribute from a AttributeMatcher.

The function returns the following values:

  • utf8 (optional): string containing the next attribute or, NULL if no more attribute exist.

func (*FileAttributeMatcher) Matches 

func (matcher *FileAttributeMatcher) Matches(attribute string) bool

Matches checks if an attribute will be matched by an attribute matcher. If the matcher was created with the "*" matching string, this function will always return TRUE.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • ok: TRUE if attribute matches matcher. FALSE otherwise.

func (*FileAttributeMatcher) MatchesOnly 

func (matcher *FileAttributeMatcher) MatchesOnly(attribute string) bool

MatchesOnly checks if an attribute matcher only matches a given attribute. Always returns FALSE if "*" was used when creating the matcher.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • ok: TRUE if the matcher only matches attribute. FALSE otherwise.

func (*FileAttributeMatcher) String 

func (matcher *FileAttributeMatcher) String() string

String prints what the matcher is matching against. The format will be equal to the format passed to g_file_attribute_matcher_new(). The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts.

The function returns the following values:

  • utf8: string describing the attributes the matcher matches against or NULL if matcher was NULL.

func (*FileAttributeMatcher) Subtract 

func (matcher *FileAttributeMatcher) Subtract(subtract *FileAttributeMatcher) *FileAttributeMatcher

Subtract subtracts all attributes of subtract from matcher and returns a matcher that supports those attributes.

Note that currently it is not possible to remove a single attribute when the matcher matches the whole namespace - or remove a namespace or attribute when the matcher matches everything. This is a limitation of the current implementation, but may be fixed in the future.

The function takes the following parameters:

  • subtract (optional): matcher to subtract.

The function returns the following values:

  • fileAttributeMatcher (optional): file attribute matcher matching all attributes of matcher that are not matched by subtract.

type FileAttributeStatus 

type FileAttributeStatus C.gint

FileAttributeStatus: used by g_file_set_attributes_from_info() when setting file attributes. 

const (
	// FileAttributeStatusUnset: attribute value is unset (empty).
	FileAttributeStatusUnset FileAttributeStatus = iota
	// FileAttributeStatusSet: attribute value is set.
	FileAttributeStatusSet
	// FileAttributeStatusErrorSetting indicates an error in setting the value.
	FileAttributeStatusErrorSetting
)

func (FileAttributeStatus) String 

func (f FileAttributeStatus) String() string

String returns the name in string for FileAttributeStatus.

type FileAttributeType 

type FileAttributeType C.gint

FileAttributeType: data types for file attributes. 

const (
	// FileAttributeTypeInvalid indicates an invalid or uninitialized type.
	FileAttributeTypeInvalid FileAttributeType = iota
	// FileAttributeTypeString: null terminated UTF8 string.
	FileAttributeTypeString
	// FileAttributeTypeByteString: zero terminated string of non-zero bytes.
	FileAttributeTypeByteString
	// FileAttributeTypeBoolean: boolean value.
	FileAttributeTypeBoolean
	// FileAttributeTypeUint32: unsigned 4-byte/32-bit integer.
	FileAttributeTypeUint32
	// FileAttributeTypeInt32: signed 4-byte/32-bit integer.
	FileAttributeTypeInt32
	// FileAttributeTypeUint64: unsigned 8-byte/64-bit integer.
	FileAttributeTypeUint64
	// FileAttributeTypeInt64: signed 8-byte/64-bit integer.
	FileAttributeTypeInt64
	// FileAttributeTypeObject: #GObject.
	FileAttributeTypeObject
	// FileAttributeTypeStringv: NULL terminated char **. Since 2.22.
	FileAttributeTypeStringv
)

func (FileAttributeType) String 

func (f FileAttributeType) String() string

String returns the name in string for FileAttributeType.

type FileCopyFlags 

type FileCopyFlags C.guint

FileCopyFlags flags used when copying or moving files. 

const (
	// FileCopyNone: no flags set.
	FileCopyNone FileCopyFlags = 0b0
	// FileCopyOverwrite: overwrite any existing files.
	FileCopyOverwrite FileCopyFlags = 0b1
	// FileCopyBackup: make a backup of any existing files.
	FileCopyBackup FileCopyFlags = 0b10
	// FileCopyNofollowSymlinks: don't follow symlinks.
	FileCopyNofollowSymlinks FileCopyFlags = 0b100
	// FileCopyAllMetadata: copy all file metadata instead of just default set
	// used for copy (see Info).
	FileCopyAllMetadata FileCopyFlags = 0b1000
	// FileCopyNoFallbackForMove: don't use copy and delete fallback if native
	// move not supported.
	FileCopyNoFallbackForMove FileCopyFlags = 0b10000
	// FileCopyTargetDefaultPerms leaves target file with default perms, instead
	// of setting the source file perms.
	FileCopyTargetDefaultPerms FileCopyFlags = 0b100000
	// FileCopyTargetDefaultModifiedTime: use default modification timestamps
	// instead of copying them from the source file. Since 2.80.
	FileCopyTargetDefaultModifiedTime FileCopyFlags = 0b1000000
)

func (FileCopyFlags) Has 

func (f FileCopyFlags) Has(other FileCopyFlags) bool

Has returns true if f contains other.

func (FileCopyFlags) String 

func (f FileCopyFlags) String() string

String returns the names in string for FileCopyFlags.

type FileCreateFlags 

type FileCreateFlags C.guint

FileCreateFlags flags used when an operation may create a file. 

const (
	// FileCreateNone: no flags set.
	FileCreateNone FileCreateFlags = 0b0
	// FileCreatePrivate: create a file that can only be accessed by the current
	// user.
	FileCreatePrivate FileCreateFlags = 0b1
	// FileCreateReplaceDestination: replace the destination as if it
	// didn't exist before. Don't try to keep any old permissions, replace
	// instead of following links. This is generally useful if you're doing
	// a "copy over" rather than a "save new version of" replace operation.
	// You can think of it as "unlink destination" before writing to it,
	// although the implementation may not be exactly like that. This flag
	// can only be used with g_file_replace() and its variants, including
	// g_file_replace_contents(). Since 2.20.
	FileCreateReplaceDestination FileCreateFlags = 0b10
)

func (FileCreateFlags) Has 

func (f FileCreateFlags) Has(other FileCreateFlags) bool

Has returns true if f contains other.

func (FileCreateFlags) String 

func (f FileCreateFlags) String() string

String returns the names in string for FileCreateFlags.

type FileEnumerator 

type FileEnumerator struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

FileEnumerator: GFileEnumerator allows you to operate on a set of gio.File objects, returning a gio.FileInfo structure for each file enumerated (e.g. gio.File.EnumerateChildren() will return a GFileEnumerator for each of the children within a directory).

To get the next file's information from a GFileEnumerator, use gio.FileEnumerator.NextFile() or its asynchronous version, gio.FileEnumerator.NextFilesAsync(). Note that the asynchronous version will return a list of gio.FileInfo objects, whereas the synchronous will only return the next file in the enumerator.

The ordering of returned files is unspecified for non-Unix platforms; for more information, see glib.Dir.ReadName(). On Unix, when operating on local files, returned files will be sorted by inode number. Effectively you can assume that the ordering of returned files will be stable between successive calls (and applications) assuming the directory is unchanged.

If your application needs a specific ordering, such as by name or modification time, you will have to implement that in your application code.

To close a GFileEnumerator, use gio.FileEnumerator.Close(), or its asynchronous version, gio.FileEnumerator.CloseAsync(). Once a GFileEnumerator is closed, no further actions may be performed on it, and it should be freed with gobject.Object.Unref().

func (*FileEnumerator) Child 

func (enumerator *FileEnumerator) Child(info *FileInfo) *File

Child: return a new #GFile which refers to the file named by info in the source directory of enumerator. This function is primarily intended to be used inside loops with g_file_enumerator_next_file().

To use this, G_FILE_ATTRIBUTE_STANDARD_NAME must have been listed in the attributes list used when creating the Enumerator.

This is a convenience method that's equivalent to: 

gchar *name = g_file_info_get_name (info);
GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
                                 name);.

The function takes the following parameters:

  • info gotten from g_file_enumerator_next_file() or the async equivalents.

The function returns the following values:

  • file for the Info passed it.

func (*FileEnumerator) Close 

func (enumerator *FileEnumerator) Close(ctx context.Context) error

Close releases all resources used by this enumerator, making the enumerator return G_IO_ERROR_CLOSED on all calls.

This will be automatically called when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*FileEnumerator) CloseAsync 

func (enumerator *FileEnumerator) CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

CloseAsync: asynchronously closes the file enumerator.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned in g_file_enumerator_close_finish().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*FileEnumerator) CloseFinish 

func (enumerator *FileEnumerator) CloseFinish(result AsyncResulter) error

CloseFinish finishes closing a file enumerator, started from g_file_enumerator_close_async().

If the file enumerator was already closed when g_file_enumerator_close_async() was called, then this function will report G_IO_ERROR_CLOSED in error, and return FALSE. If the file enumerator had pending operation when the close operation was started, then this function will report G_IO_ERROR_PENDING, and return FALSE. If cancellable was not NULL, then the operation may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be set, and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*FileEnumerator) Container 

func (enumerator *FileEnumerator) Container() *File

Container: get the #GFile container which is being enumerated.

The function returns the following values:

  • file which is being enumerated.

func (*FileEnumerator) HasPending 

func (enumerator *FileEnumerator) HasPending() bool

HasPending checks if the file enumerator has pending operations.

The function returns the following values:

  • ok: TRUE if the enumerator has pending operations.

func (*FileEnumerator) IsClosed 

func (enumerator *FileEnumerator) IsClosed() bool

IsClosed checks if the file enumerator has been closed.

The function returns the following values:

  • ok: TRUE if the enumerator is closed.

func (*FileEnumerator) Iterate 

func (direnum *FileEnumerator) Iterate(ctx context.Context) (*FileInfo, *File, error)

Iterate: this is a version of g_file_enumerator_next_file() that's easier to use correctly from C programs. With g_file_enumerator_next_file(), the gboolean return value signifies "end of iteration or error", which requires allocation of a temporary #GError.

In contrast, with this function, a FALSE return from g_file_enumerator_iterate() *always* means "error". End of iteration is signaled by out_info or out_child being NULL.

Another crucial difference is that the references for out_info and out_child are owned by direnum (they are cached as hidden properties). You must not unref them in your own code. This makes memory management significantly easier for C code in combination with loops.

Finally, this function optionally allows retrieving a #GFile as well.

You must specify at least one of out_info or out_child.

The code pattern for correctly using g_file_enumerator_iterate() from C is: 

direnum = g_file_enumerate_children (file, ...);
while (TRUE)
  {
    GFileInfo *info;
    if (!g_file_enumerator_iterate (direnum, &info, NULL, cancellable, error))
      goto out;
    if (!info)
      break;
    ... do stuff with "info"; do not unref it! ...
  }

out:
  g_object_unref (direnum); // Note: frees the last info.

The function takes the following parameters:

  • ctx (optional): #GCancellable.

The function returns the following values:

  • outInfo (optional): output location for the next Info, or NULL.
  • outChild (optional): output location for the next #GFile, or NULL.

func (*FileEnumerator) NextFile 

func (enumerator *FileEnumerator) NextFile(ctx context.Context) (*FileInfo, error)

NextFile returns information for the next file in the enumerated object. Will block until the information is available. The Info returned from this function will contain attributes that match the attribute string that was passed when the Enumerator was created.

See the documentation of Enumerator for information about the order of returned files.

On error, returns NULL and sets error to the error. If the enumerator is at the end, NULL will be returned and error will be unset.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • fileInfo (optional) or NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed.

func (*FileEnumerator) NextFilesAsync 

func (enumerator *FileEnumerator) NextFilesAsync(ctx context.Context, numFiles, ioPriority int, callback AsyncReadyCallback)

NextFilesAsync: request information for a number of files from the enumerator asynchronously. When all I/O for the operation is finished the callback will be called with the requested information.

See the documentation of Enumerator for information about the order of returned files.

Once the end of the enumerator is reached, or if an error occurs, the callback will be called with an empty list. In this case, the previous call to g_file_enumerator_next_files_async() will typically have returned fewer than num_files items.

If a request is cancelled the callback will be called with G_IO_ERROR_CANCELLED.

This leads to the following pseudo-code usage: 

g_autoptr(GFile) dir = get_directory ();
g_autoptr(GFileEnumerator) enumerator = NULL;
g_autolist(GFileInfo) files = NULL;
g_autoptr(GError) local_error = NULL;

enumerator = yield g_file_enumerate_children_async (dir,
                                                    G_FILE_ATTRIBUTE_STANDARD_NAME ","
                                                    G_FILE_ATTRIBUTE_STANDARD_TYPE,
                                                    G_FILE_QUERY_INFO_NONE,
                                                    G_PRIORITY_DEFAULT,
                                                    cancellable,
                                                    …,
                                                    &local_error);
if (enumerator == NULL)
  g_error ("Error enumerating: s", local_error->message);

// Loop until no files are returned, either because the end of the enumerator
// has been reached, or an error was returned.
do
  {
    files = yield g_file_enumerator_next_files_async (enumerator,
                                                      5,  // number of files to request
                                                      G_PRIORITY_DEFAULT,
                                                      cancellable,
                                                      …,
                                                      &local_error);

    // Process the returned files, but don’t assume that exactly 5 were returned.
    for (GList *l = files; l != NULL; l = l->next)
      {
        GFileInfo *info = l->data;
        handle_file_info (info);
      }
  }
while (files != NULL);

if (local_error != NULL &&
    !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_CANCELLED))
  g_error ("Error while enumerating: s", local_error->message);

During an async request no other sync and async calls are allowed, and will result in G_IO_ERROR_PENDING errors.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • numFiles: number of file info objects to request.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*FileEnumerator) NextFilesFinish 

func (enumerator *FileEnumerator) NextFilesFinish(result AsyncResulter) ([]*FileInfo, error)

NextFilesFinish finishes the asynchronous operation started with g_file_enumerator_next_files_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • list of Infos. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them.

func (*FileEnumerator) SetPending 

func (enumerator *FileEnumerator) SetPending(pending bool)

SetPending sets the file enumerator as having pending operations.

The function takes the following parameters:

  • pending: boolean value.

type FileEnumeratorClass added in v0.0.5 

type FileEnumeratorClass struct {
	// contains filtered or unexported fields
}

FileEnumeratorClass: instance of this type is always passed by reference.

type FileEnumeratorOverrides added in v0.0.5 

type FileEnumeratorOverrides struct {
	// CloseFinish finishes closing a file enumerator, started from
	// g_file_enumerator_close_async().
	//
	// If the file enumerator was already closed when
	// g_file_enumerator_close_async() was called, then this function will
	// report G_IO_ERROR_CLOSED in error, and return FALSE. If the file
	// enumerator had pending operation when the close operation was started,
	// then this function will report G_IO_ERROR_PENDING, and return FALSE.
	// If cancellable was not NULL, then the operation may have been cancelled
	// by triggering the cancellable object from another thread. If the
	// operation was cancelled, the error G_IO_ERROR_CANCELLED will be set,
	// and FALSE will be returned.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	CloseFinish func(result AsyncResulter) error
	CloseFn     func(ctx context.Context) error
	// NextFile returns information for the next file in the enumerated object.
	// Will block until the information is available. The Info returned from
	// this function will contain attributes that match the attribute string
	// that was passed when the Enumerator was created.
	//
	// See the documentation of Enumerator for information about the order of
	// returned files.
	//
	// On error, returns NULL and sets error to the error. If the enumerator is
	// at the end, NULL will be returned and error will be unset.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//
	// The function returns the following values:
	//
	//   - fileInfo (optional) or NULL on error or end of enumerator. Free the
	//     returned object with g_object_unref() when no longer needed.
	NextFile func(ctx context.Context) (*FileInfo, error)
	// NextFilesFinish finishes the asynchronous operation started with
	// g_file_enumerator_next_files_async().
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - list of Infos. You must free the list with g_list_free() and unref
	//     the infos with g_object_unref() when you're done with them.
	NextFilesFinish func(result AsyncResulter) ([]*FileInfo, error)
}

FileEnumeratorOverrides contains methods that are overridable.

type FileIOStream 

type FileIOStream struct {
	IOStream

	*coreglib.Object
	Seekable
	// contains filtered or unexported fields
}

FileIOStream: GFileIOStream provides I/O streams that both read and write to the same file handle.

GFileIOStream implements gio.Seekable, which allows the I/O stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations.

To find the position of a file I/O stream, use gio.Seekable.Tell().

To find out if a file I/O stream supports seeking, use gio.Seekable.CanSeek(). To position a file I/O stream, use gio.Seekable.Seek(). To find out if a file I/O stream supports truncating, use gio.Seekable.CanTruncate(). To truncate a file I/O stream, use gio.Seekable.Truncate().

The default implementation of all the GFileIOStream operations and the implementation of gio.Seekable just call into the same operations on the output stream.

func (*FileIOStream) ETag 

func (stream *FileIOStream) ETag() string

ETag gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing.

The function returns the following values:

  • utf8 (optional): entity tag for the stream.

func (*FileIOStream) QueryInfo 

func (stream *FileIOStream) QueryInfo(ctx context.Context, attributes string) (*FileInfo, error)

QueryInfo queries a file io stream for the given attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_io_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with G_IO_ERROR_PENDING.

Can fail if the stream was already closed (with error being set to G_IO_ERROR_CLOSED), the stream has pending operations (with error being set to G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with error being set to G_IO_ERROR_NOT_SUPPORTED). I all cases of failure, NULL will be returned.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be set, and NULL will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.

The function returns the following values:

  • fileInfo for the stream, or NULL on error.

func (*FileIOStream) QueryInfoAsync 

func (stream *FileIOStream) QueryInfoAsync(ctx context.Context, attributes string, ioPriority int, callback AsyncReadyCallback)

QueryInfoAsync: asynchronously queries the stream for a Info. When completed, callback will be called with a Result which can be used to finish the operation with g_file_io_stream_query_info_finish().

For the synchronous version of this function, see g_file_io_stream_query_info().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.
  • ioPriority: I/O priority (iface.AsyncResult.html#io-priority) of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*FileIOStream) QueryInfoFinish 

func (stream *FileIOStream) QueryInfoFinish(result AsyncResulter) (*FileInfo, error)

QueryInfoFinish finalizes the asynchronous query started by g_file_io_stream_query_info_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • fileInfo for the finished query.

type FileIOStreamClass added in v0.0.5 

type FileIOStreamClass struct {
	// contains filtered or unexported fields
}

FileIOStreamClass: instance of this type is always passed by reference.

func (*FileIOStreamClass) ParentClass added in v0.0.5 

func (f *FileIOStreamClass) ParentClass() *IOStreamClass

type FileIOStreamOverrides added in v0.0.5 

type FileIOStreamOverrides struct {
	CanSeek     func() bool
	CanTruncate func() bool
	// ETag gets the entity tag for the file when it has been written. This must
	// be called after the stream has been written and closed, as the etag can
	// change while writing.
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): entity tag for the stream.
	ETag func() string
	// QueryInfo queries a file io stream for the given attributes. This
	// function blocks while querying the stream. For the asynchronous version
	// of this function, see g_file_io_stream_query_info_async(). While the
	// stream is blocked, the stream will set the pending flag internally,
	// and any other operations on the stream will fail with G_IO_ERROR_PENDING.
	//
	// Can fail if the stream was already closed (with error being set to
	// G_IO_ERROR_CLOSED), the stream has pending operations (with error being
	// set to G_IO_ERROR_PENDING), or if querying info is not supported for the
	// stream's interface (with error being set to G_IO_ERROR_NOT_SUPPORTED).
	// I all cases of failure, NULL will be returned.
	//
	// If cancellable is not NULL, then the operation can be cancelled by
	// triggering the cancellable object from another thread. If the operation
	// was cancelled, the error G_IO_ERROR_CANCELLED will be set, and NULL will
	// be returned.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - attributes: file attribute query string.
	//
	// The function returns the following values:
	//
	//   - fileInfo for the stream, or NULL on error.
	QueryInfo func(ctx context.Context, attributes string) (*FileInfo, error)
	// QueryInfoFinish finalizes the asynchronous query started by
	// g_file_io_stream_query_info_async().
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - fileInfo for the finished query.
	QueryInfoFinish func(result AsyncResulter) (*FileInfo, error)
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - offset
	//   - typ
	Seek func(ctx context.Context, offset int64, typ glib.SeekType) error
	Tell func() int64
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - size
	TruncateFn func(ctx context.Context, size int64) error
}

FileIOStreamOverrides contains methods that are overridable.

type FileIcon 

type FileIcon struct {
	*coreglib.Object

	LoadableIcon
	// contains filtered or unexported fields
}

FileIcon: GFileIcon specifies an icon by pointing to an image file to be used as icon.

It implements gio.LoadableIcon.

func NewFileIcon 

func NewFileIcon(file Filer) *FileIcon

NewFileIcon creates a new icon for a file.

The function takes the following parameters:

  • file: #GFile.

The function returns the following values:

  • fileIcon for the given file, or NULL on error.

func (*FileIcon) File 

func (icon *FileIcon) File() *File

File gets the #GFile associated with the given icon.

The function returns the following values:

  • file: #GFile.

type FileIface added in v0.0.5 

type FileIface struct {
	// contains filtered or unexported fields
}

FileIface: interface for writing VFS file handles.

An instance of this type is always passed by reference.

func (*FileIface) SupportsThreadContexts added in v0.0.5 

func (f *FileIface) SupportsThreadContexts() bool

SupportsThreadContexts: boolean that indicates whether the #GFile implementation supports thread-default contexts. Since 2.22.

type FileInfo 

type FileInfo struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

FileInfo stores information about a file system object referenced by a gio.File.

Functionality for manipulating basic metadata for files. GFileInfo implements methods for getting information that all files should contain, and allows for manipulation of extended attributes.

See file-attributes.html (file attributes) for more information on how GIO handles file attributes.

To obtain a GFileInfo for a gio.File, use gio.File.QueryInfo() (or its async variant). To obtain a GFileInfo for a file input or output stream, use gio.FileInputStream.QueryInfo() or gio.FileOutputStream.QueryInfo() (or their async variants).

To change the actual attributes of a file, you should then set the attribute in the GFileInfo and call gio.File.SetAttributesFromInfo() or gio.File.SetAttributesAsync() on a GFile.

However, not all attributes can be changed in the file. For instance, the actual size of a file cannot be changed via gio.FileInfo.SetSize(). You may call gio.File.QuerySettableAttributes() and gio.File.QueryWritableNamespaces() to discover the settable attributes of a particular file at runtime.

The direct accessors, such as gio.FileInfo.GetName(), are slightly more optimized than the generic attribute accessors, such as gio.FileInfo.GetAttributeByteString().This optimization will matter only if calling the API in a tight loop.

It is an error to call these accessors without specifying their required file attributes when creating the GFileInfo. Use gio.FileInfo.HasAttribute() or gio.FileInfo.ListAttributes() to check what attributes are specified for a GFileInfo.

gio.FileAttributeMatcher allows for searching through a GFileInfo for attributes.

func NewFileInfo 

func NewFileInfo() *FileInfo

NewFileInfo creates a new file info structure.

The function returns the following values:

  • fileInfo: Info.

func (*FileInfo) AccessDateTime added in v0.3.0 

func (info *FileInfo) AccessDateTime() *glib.DateTime

AccessDateTime gets the access time of the current info and returns it as a Time.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_TIME_ACCESS. If G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting Time will additionally have microsecond precision.

If nanosecond precision is needed, G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC must be queried separately using g_file_info_get_attribute_uint32().

The function returns the following values:

  • dateTime (optional) access time, or NULL if unknown.

func (*FileInfo) AttributeAsString 

func (info *FileInfo) AttributeAsString(attribute string) string

AttributeAsString gets the value of an attribute, formatted as a string. This escapes things as needed to make the string valid UTF-8.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • utf8 (optional): UTF-8 string associated with the given attribute, or NULL if the attribute wasn’t set. When you're done with the string it must be freed with g_free().

func (*FileInfo) AttributeBoolean 

func (info *FileInfo) AttributeBoolean(attribute string) bool

AttributeBoolean gets the value of a boolean attribute. If the attribute does not contain a boolean value, FALSE will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • ok: boolean value contained within the attribute.

func (*FileInfo) AttributeByteString 

func (info *FileInfo) AttributeByteString(attribute string) string

AttributeByteString gets the value of a byte string attribute. If the attribute does not contain a byte string, NULL will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • utf8 (optional) contents of the attribute value as a byte string, or NULL otherwise.

func (*FileInfo) AttributeData 

func (info *FileInfo) AttributeData(attribute string) (FileAttributeType, unsafe.Pointer, FileAttributeStatus, bool)

AttributeData gets the attribute type, value and status for an attribute key.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • typ (optional): return location for the attribute type, or NULL.
  • valuePp (optional): return location for the attribute value, or NULL; the attribute value will not be NULL.
  • status (optional): return location for the attribute status, or NULL.
  • ok: TRUE if info has an attribute named attribute, FALSE otherwise.

func (*FileInfo) AttributeFilePath added in v0.3.0 

func (info *FileInfo) AttributeFilePath(attribute string) string

AttributeFilePath gets the value of a byte string attribute as a file path.

If the attribute does not contain a byte string, NULL will be returned.

This function is meant to be used by language bindings that have specific handling for Unix paths.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • filename (optional) contents of the attribute value as a file path, or NULL otherwise.

func (*FileInfo) AttributeInt32 

func (info *FileInfo) AttributeInt32(attribute string) int32

AttributeInt32 gets a signed 32-bit integer contained within the attribute. If the attribute does not contain a signed 32-bit integer, or is invalid, 0 will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • gint32: signed 32-bit integer from the attribute.

func (*FileInfo) AttributeInt64 

func (info *FileInfo) AttributeInt64(attribute string) int64

AttributeInt64 gets a signed 64-bit integer contained within the attribute. If the attribute does not contain a signed 64-bit integer, or is invalid, 0 will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • gint64: signed 64-bit integer from the attribute.

func (*FileInfo) AttributeObject 

func (info *FileInfo) AttributeObject(attribute string) *coreglib.Object

AttributeObject gets the value of a #GObject attribute. If the attribute does not contain a #GObject, NULL will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • object (optional) associated with the given attribute, or NULL otherwise.

func (*FileInfo) AttributeStatus 

func (info *FileInfo) AttributeStatus(attribute string) FileAttributeStatus

AttributeStatus gets the attribute status for an attribute key.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • fileAttributeStatus for the given attribute, or G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.

func (*FileInfo) AttributeString 

func (info *FileInfo) AttributeString(attribute string) string

AttributeString gets the value of a string attribute. If the attribute does not contain a string, NULL will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • utf8 (optional) contents of the attribute value as a UTF-8 string, or NULL otherwise.

func (*FileInfo) AttributeStringv 

func (info *FileInfo) AttributeStringv(attribute string) []string

AttributeStringv gets the value of a stringv attribute. If the attribute does not contain a stringv, NULL will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • utf8s (optional) contents of the attribute value as a stringv, or NULL otherwise. Do not free. These returned strings are UTF-8.

func (*FileInfo) AttributeType 

func (info *FileInfo) AttributeType(attribute string) FileAttributeType

AttributeType gets the attribute type for an attribute key.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • fileAttributeType for the given attribute, or G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.

func (*FileInfo) AttributeUint32 

func (info *FileInfo) AttributeUint32(attribute string) uint32

AttributeUint32 gets an unsigned 32-bit integer contained within the attribute. If the attribute does not contain an unsigned 32-bit integer, or is invalid, 0 will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • guint32: unsigned 32-bit integer from the attribute.

func (*FileInfo) AttributeUint64 

func (info *FileInfo) AttributeUint64(attribute string) uint64

AttributeUint64 gets a unsigned 64-bit integer contained within the attribute. If the attribute does not contain an unsigned 64-bit integer, or is invalid, 0 will be returned.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • guint64: unsigned 64-bit integer from the attribute.

func (*FileInfo) ClearStatus 

func (info *FileInfo) ClearStatus()

ClearStatus clears the status information from info.

func (*FileInfo) ContentType 

func (info *FileInfo) ContentType() string

ContentType gets the file's content type.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.

The function returns the following values:

  • utf8 (optional): string containing the file's content type, or NULL if unknown.

func (*FileInfo) CopyInto 

func (srcInfo *FileInfo) CopyInto(destInfo *FileInfo)

CopyInto: first clears all of the [GFileAttribute][gio-GFileAttribute] of dest_info, and then copies all of the file attributes from src_info to dest_info.

The function takes the following parameters:

  • destInfo: destination to copy attributes to.

func (*FileInfo) CreationDateTime added in v0.3.0 

func (info *FileInfo) CreationDateTime() *glib.DateTime

CreationDateTime gets the creation time of the current info and returns it as a Time.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_TIME_CREATED. If G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting Time will additionally have microsecond precision.

If nanosecond precision is needed, G_FILE_ATTRIBUTE_TIME_CREATED_NSEC must be queried separately using g_file_info_get_attribute_uint32().

The function returns the following values:

  • dateTime (optional): creation time, or NULL if unknown.

func (*FileInfo) DeletionDate 

func (info *FileInfo) DeletionDate() *glib.DateTime

DeletionDate returns the Time representing the deletion date of the file, as available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, NULL is returned.

The function returns the following values:

  • dateTime (optional) or NULL.

func (*FileInfo) DisplayName 

func (info *FileInfo) DisplayName() string

DisplayName gets a display name for a file. This is guaranteed to always be set.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.

The function returns the following values:

  • utf8: string containing the display name.

func (*FileInfo) Dup 

func (other *FileInfo) Dup() *FileInfo

Dup duplicates a file info structure.

The function returns the following values:

  • fileInfo: duplicate Info of other.

func (*FileInfo) ETag 

func (info *FileInfo) ETag() string

ETag gets the entity tag (iface.File.html#entity-tags) for a given Info. See G_FILE_ATTRIBUTE_ETAG_VALUE.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_ETAG_VALUE.

The function returns the following values:

  • utf8 (optional): string containing the value of the "etag:value" attribute.

func (*FileInfo) EditName 

func (info *FileInfo) EditName() string

EditName gets the edit name for a file.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.

The function returns the following values:

  • utf8: string containing the edit name.

func (*FileInfo) FileType 

func (info *FileInfo) FileType() FileType

FileType gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see g_file_info_get_content_type().

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_TYPE.

The function returns the following values:

  • fileType for the given file.

func (*FileInfo) HasAttribute 

func (info *FileInfo) HasAttribute(attribute string) bool

HasAttribute checks if a file info structure has an attribute named attribute.

The function takes the following parameters:

  • attribute: file attribute key.

The function returns the following values:

  • ok: TRUE if info has an attribute named attribute, FALSE otherwise.

func (*FileInfo) HasNamespace 

func (info *FileInfo) HasNamespace(nameSpace string) bool

HasNamespace checks if a file info structure has an attribute in the specified name_space.

The function takes the following parameters:

  • nameSpace: file attribute namespace.

The function returns the following values:

  • ok: TRUE if info has an attribute in name_space, FALSE otherwise.

func (*FileInfo) Icon 

func (info *FileInfo) Icon() *Icon

Icon gets the icon for a file.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_ICON.

The function returns the following values:

  • icon (optional) for the given info.

func (*FileInfo) IsBackup 

func (info *FileInfo) IsBackup() bool

IsBackup checks if a file is a backup file.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP.

The function returns the following values:

  • ok: TRUE if file is a backup file, FALSE otherwise.

func (*FileInfo) IsHidden 

func (info *FileInfo) IsHidden() bool

IsHidden checks if a file is hidden.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.

The function returns the following values:

  • ok: TRUE if the file is a hidden file, FALSE otherwise.
func (info *FileInfo) IsSymlink() bool

IsSymlink checks if a file is a symlink.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.

The function returns the following values:

  • ok: TRUE if the given info is a symlink.

func (*FileInfo) ListAttributes 

func (info *FileInfo) ListAttributes(nameSpace string) []string

ListAttributes lists the file info structure's attributes.

The function takes the following parameters:

  • nameSpace (optional): file attribute key's namespace, or NULL to list all attributes.

The function returns the following values:

  • utf8s (optional): a null-terminated array of strings of all of the possible attribute types for the given name_space, or NULL on error.

func (*FileInfo) ModificationDateTime 

func (info *FileInfo) ModificationDateTime() *glib.DateTime

ModificationDateTime gets the modification time of the current info and returns it as a Time.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_TIME_MODIFIED. If G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided, the resulting Time will additionally have microsecond precision.

If nanosecond precision is needed, G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC must be queried separately using g_file_info_get_attribute_uint32().

The function returns the following values:

  • dateTime (optional): modification time, or NULL if unknown.

func (*FileInfo) ModificationTime deprecated 

func (info *FileInfo) ModificationTime() *glib.TimeVal

ModificationTime gets the modification time of the current info and sets it in result.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_TIME_MODIFIED. If G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC is provided it will be used too.

Deprecated: Use g_file_info_get_modification_date_time() instead, as Val is deprecated due to the year 2038 problem.

The function returns the following values:

  • result: Val.

func (*FileInfo) Name 

func (info *FileInfo) Name() string

Name gets the name for a file. This is guaranteed to always be set.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_NAME.

The function returns the following values:

  • filename: string containing the file name.

func (*FileInfo) RemoveAttribute 

func (info *FileInfo) RemoveAttribute(attribute string)

RemoveAttribute removes all cases of attribute from info if it exists.

The function takes the following parameters:

  • attribute: file attribute key.

func (*FileInfo) SetAccessDateTime added in v0.3.0 

func (info *FileInfo) SetAccessDateTime(atime *glib.DateTime)

SetAccessDateTime sets the G_FILE_ATTRIBUTE_TIME_ACCESS and G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the given date/time value.

G_FILE_ATTRIBUTE_TIME_ACCESS_NSEC will be cleared.

The function takes the following parameters:

  • atime: Time.

func (*FileInfo) SetAttribute 

func (info *FileInfo) SetAttribute(attribute string, typ FileAttributeType, valueP unsafe.Pointer)

SetAttribute sets the attribute to contain the given value, if possible. To unset the attribute, use G_FILE_ATTRIBUTE_TYPE_INVALID for type.

The function takes the following parameters:

  • attribute: file attribute key.
  • typ: AttributeType.
  • valueP: pointer to the value.

func (*FileInfo) SetAttributeBoolean 

func (info *FileInfo) SetAttributeBoolean(attribute string, attrValue bool)

SetAttributeBoolean sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: boolean value.

func (*FileInfo) SetAttributeByteString 

func (info *FileInfo) SetAttributeByteString(attribute, attrValue string)

SetAttributeByteString sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: byte string.

func (*FileInfo) SetAttributeFilePath added in v0.3.0 

func (info *FileInfo) SetAttributeFilePath(attribute, attrValue string)

SetAttributeFilePath sets the attribute to contain the given attr_value, if possible.

This function is meant to be used by language bindings that have specific handling for Unix paths.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: file path.

func (*FileInfo) SetAttributeInt32 

func (info *FileInfo) SetAttributeInt32(attribute string, attrValue int32)

SetAttributeInt32 sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: signed 32-bit integer.

func (*FileInfo) SetAttributeInt64 

func (info *FileInfo) SetAttributeInt64(attribute string, attrValue int64)

SetAttributeInt64 sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute name to set.
  • attrValue: int64 value to set attribute to.

func (*FileInfo) SetAttributeMask 

func (info *FileInfo) SetAttributeMask(mask *FileAttributeMatcher)

SetAttributeMask sets mask on info to match specific attribute types.

The function takes the following parameters:

  • mask: AttributeMatcher.

func (*FileInfo) SetAttributeObject 

func (info *FileInfo) SetAttributeObject(attribute string, attrValue *coreglib.Object)

SetAttributeObject sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: #GObject.

func (*FileInfo) SetAttributeStatus 

func (info *FileInfo) SetAttributeStatus(attribute string, status FileAttributeStatus) bool

SetAttributeStatus sets the attribute status for an attribute key. This is only needed by external code that implement g_file_set_attributes_from_info() or similar functions.

The attribute must exist in info for this to work. Otherwise FALSE is returned and info is unchanged.

The function takes the following parameters:

  • attribute: file attribute key.
  • status: AttributeStatus.

The function returns the following values:

  • ok: TRUE if the status was changed, FALSE if the key was not set.

func (*FileInfo) SetAttributeString 

func (info *FileInfo) SetAttributeString(attribute, attrValue string)

SetAttributeString sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: UTF-8 string.

func (*FileInfo) SetAttributeStringv 

func (info *FileInfo) SetAttributeStringv(attribute string, attrValue []string)

SetAttributeStringv sets the attribute to contain the given attr_value, if possible.

Sinze: 2.22.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: NULL terminated array of UTF-8 strings.

func (*FileInfo) SetAttributeUint32 

func (info *FileInfo) SetAttributeUint32(attribute string, attrValue uint32)

SetAttributeUint32 sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: unsigned 32-bit integer.

func (*FileInfo) SetAttributeUint64 

func (info *FileInfo) SetAttributeUint64(attribute string, attrValue uint64)

SetAttributeUint64 sets the attribute to contain the given attr_value, if possible.

The function takes the following parameters:

  • attribute: file attribute key.
  • attrValue: unsigned 64-bit integer.

func (*FileInfo) SetContentType 

func (info *FileInfo) SetContentType(contentType string)

SetContentType sets the content type attribute for a given Info. See G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.

The function takes the following parameters:

  • contentType: content type. See [GContentType][gio-GContentType].

func (*FileInfo) SetCreationDateTime added in v0.3.0 

func (info *FileInfo) SetCreationDateTime(creationTime *glib.DateTime)

SetCreationDateTime sets the G_FILE_ATTRIBUTE_TIME_CREATED and G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the given date/time value.

G_FILE_ATTRIBUTE_TIME_CREATED_NSEC will be cleared.

The function takes the following parameters:

  • creationTime: Time.

func (*FileInfo) SetDisplayName 

func (info *FileInfo) SetDisplayName(displayName string)

SetDisplayName sets the display name for the current Info. See G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME.

The function takes the following parameters:

  • displayName: string containing a display name.

func (*FileInfo) SetEditName 

func (info *FileInfo) SetEditName(editName string)

SetEditName sets the edit name for the current file. See G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME.

The function takes the following parameters:

  • editName: string containing an edit name.

func (*FileInfo) SetFileType 

func (info *FileInfo) SetFileType(typ FileType)

SetFileType sets the file type in a Info to type. See G_FILE_ATTRIBUTE_STANDARD_TYPE.

The function takes the following parameters:

  • typ: Type.

func (*FileInfo) SetIcon 

func (info *FileInfo) SetIcon(icon Iconner)

SetIcon sets the icon for a given Info. See G_FILE_ATTRIBUTE_STANDARD_ICON.

The function takes the following parameters:

  • icon: #GIcon.

func (*FileInfo) SetIsHidden 

func (info *FileInfo) SetIsHidden(isHidden bool)

SetIsHidden sets the "is_hidden" attribute in a Info according to is_hidden. See G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN.

The function takes the following parameters:

  • isHidden: #gboolean.
func (info *FileInfo) SetIsSymlink(isSymlink bool)

SetIsSymlink sets the "is_symlink" attribute in a Info according to is_symlink. See G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK.

The function takes the following parameters:

  • isSymlink: #gboolean.

func (*FileInfo) SetModificationDateTime 

func (info *FileInfo) SetModificationDateTime(mtime *glib.DateTime)

SetModificationDateTime sets the G_FILE_ATTRIBUTE_TIME_MODIFIED and G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given date/time value.

G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.

The function takes the following parameters:

  • mtime: Time.

func (*FileInfo) SetModificationTime deprecated 

func (info *FileInfo) SetModificationTime(mtime *glib.TimeVal)

SetModificationTime sets the G_FILE_ATTRIBUTE_TIME_MODIFIED and G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC attributes in the file info to the given time value.

G_FILE_ATTRIBUTE_TIME_MODIFIED_NSEC will be cleared.

Deprecated: Use g_file_info_set_modification_date_time() instead, as Val is deprecated due to the year 2038 problem.

The function takes the following parameters:

  • mtime: Val.

func (*FileInfo) SetName 

func (info *FileInfo) SetName(name string)

SetName sets the name attribute for the current Info. See G_FILE_ATTRIBUTE_STANDARD_NAME.

The function takes the following parameters:

  • name: string containing a name.

func (*FileInfo) SetSize 

func (info *FileInfo) SetSize(size int64)

SetSize sets the G_FILE_ATTRIBUTE_STANDARD_SIZE attribute in the file info to the given size.

The function takes the following parameters:

  • size containing the file's size.

func (*FileInfo) SetSortOrder 

func (info *FileInfo) SetSortOrder(sortOrder int32)

SetSortOrder sets the sort order attribute in the file info structure. See G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

The function takes the following parameters:

  • sortOrder: sort order integer.

func (*FileInfo) SetSymbolicIcon 

func (info *FileInfo) SetSymbolicIcon(icon Iconner)

SetSymbolicIcon sets the symbolic icon for a given Info. See G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.

The function takes the following parameters:

  • icon: #GIcon.

func (*FileInfo) SetSymlinkTarget 

func (info *FileInfo) SetSymlinkTarget(symlinkTarget string)

SetSymlinkTarget sets the G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET attribute in the file info to the given symlink target.

The function takes the following parameters:

  • symlinkTarget: static string containing a path to a symlink target.

func (*FileInfo) Size 

func (info *FileInfo) Size() int64

Size gets the file's size (in bytes). The size is retrieved through the value of the G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted from #guint64 to #goffset before returning the result.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_SIZE.

The function returns the following values:

  • gint64 containing the file's size (in bytes).

func (*FileInfo) SortOrder 

func (info *FileInfo) SortOrder() int32

SortOrder gets the value of the sort_order attribute from the Info. See G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER.

The function returns the following values:

  • gint32 containing the value of the "standard::sort_order" attribute.

func (*FileInfo) SymbolicIcon 

func (info *FileInfo) SymbolicIcon() *Icon

SymbolicIcon gets the symbolic icon for a file.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON.

The function returns the following values:

  • icon (optional) for the given info.

func (*FileInfo) SymlinkTarget 

func (info *FileInfo) SymlinkTarget() string

SymlinkTarget gets the symlink target for a given Info.

It is an error to call this if the Info does not contain G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET.

The function returns the following values:

  • filename (optional): string containing the symlink target.

func (*FileInfo) UnsetAttributeMask 

func (info *FileInfo) UnsetAttributeMask()

UnsetAttributeMask unsets a mask set by g_file_info_set_attribute_mask(), if one is set.

type FileInputStream 

type FileInputStream struct {
	InputStream

	*coreglib.Object
	Seekable
	// contains filtered or unexported fields
}

FileInputStream: GFileInputStream provides input streams that take their content from a file.

GFileInputStream implements gio.Seekable, which allows the input stream to jump to arbitrary positions in the file, provided the filesystem of the file allows it. To find the position of a file input stream, use gio.Seekable.Tell(). To find out if a file input stream supports seeking, use gio.Seekable.CanSeek(). To position a file input stream, use gio.Seekable.Seek().

func (*FileInputStream) QueryInfo 

func (stream *FileInputStream) QueryInfo(ctx context.Context, attributes string) (*FileInfo, error)

QueryInfo queries a file input stream the given attributes. This function blocks while querying the stream. For the asynchronous (non-blocking) version of this function, see g_file_input_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with G_IO_ERROR_PENDING.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.

The function returns the following values:

  • fileInfo or NULL on error.

func (*FileInputStream) QueryInfoAsync 

func (stream *FileInputStream) QueryInfoAsync(ctx context.Context, attributes string, ioPriority int, callback AsyncReadyCallback)

QueryInfoAsync queries the stream information asynchronously. When the operation is finished callback will be called. You can then call g_file_input_stream_query_info_finish() to get the result of the operation.

For the synchronous version of this function, see g_file_input_stream_query_info().

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be set.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*FileInputStream) QueryInfoFinish 

func (stream *FileInputStream) QueryInfoFinish(result AsyncResulter) (*FileInfo, error)

QueryInfoFinish finishes an asynchronous info query operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • fileInfo: Info.

type FileInputStreamClass added in v0.0.5 

type FileInputStreamClass struct {
	// contains filtered or unexported fields
}

FileInputStreamClass: instance of this type is always passed by reference.

func (*FileInputStreamClass) ParentClass added in v0.0.5 

func (f *FileInputStreamClass) ParentClass() *InputStreamClass

type FileInputStreamOverrides added in v0.0.5 

type FileInputStreamOverrides struct {
	CanSeek func() bool
	// QueryInfo queries a file input stream the given attributes. This function
	// blocks while querying the stream. For the asynchronous (non-blocking)
	// version of this function, see g_file_input_stream_query_info_async().
	// While the stream is blocked, the stream will set the pending flag
	// internally, and any other operations on the stream will fail with
	// G_IO_ERROR_PENDING.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - attributes: file attribute query string.
	//
	// The function returns the following values:
	//
	//   - fileInfo or NULL on error.
	QueryInfo func(ctx context.Context, attributes string) (*FileInfo, error)
	// QueryInfoFinish finishes an asynchronous info query operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - fileInfo: Info.
	QueryInfoFinish func(result AsyncResulter) (*FileInfo, error)
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - offset
	//   - typ
	Seek func(ctx context.Context, offset int64, typ glib.SeekType) error
	Tell func() int64
}

FileInputStreamOverrides contains methods that are overridable.

type FileMeasureFlags 

type FileMeasureFlags C.guint

FileMeasureFlags flags that can be used with g_file_measure_disk_usage(). 

const (
	// FileMeasureNone: no flags set.
	FileMeasureNone FileMeasureFlags = 0b0
	// FileMeasureReportAnyError: report any error encountered while traversing
	// the directory tree. Normally errors are only reported for the toplevel
	// file.
	FileMeasureReportAnyError FileMeasureFlags = 0b10
	// FileMeasureApparentSize: tally usage based on apparent file sizes.
	// Normally, the block-size is used, if available, as this is a
	// more accurate representation of disk space used. Compare with du
	// --apparent-size. Since GLib 2.78. and similarly to du since GNU Coreutils
	// 9.2, this will ignore the sizes of file types other than regular files
	// and links, as the sizes of other file types are not specified in a
	// standard way.
	FileMeasureApparentSize FileMeasureFlags = 0b100
	// FileMeasureNoXdev: do not cross mount point boundaries. Compare with du
	// -x.
	FileMeasureNoXdev FileMeasureFlags = 0b1000
)

func (FileMeasureFlags) Has 

func (f FileMeasureFlags) Has(other FileMeasureFlags) bool

Has returns true if f contains other.

func (FileMeasureFlags) String 

func (f FileMeasureFlags) String() string

String returns the names in string for FileMeasureFlags.

type FileMonitor 

type FileMonitor struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

FileMonitor monitors a file or directory for changes.

To obtain a GFileMonitor for a file or directory, use gio.File.Monitor(), gio.File.MonitorFile(), or gio.File.MonitorDirectory().

To get informed about changes to the file or directory you are monitoring, connect to the gio.FileMonitor::changed signal. The signal will be emitted in the thread-default main context (see glib.MainContext.PushThreadDefault()) of the thread that the monitor was created in (though if the global default main context is blocked, this may cause notifications to be blocked even if the thread-default context is still running).

func BaseFileMonitor 

func BaseFileMonitor(obj FileMonitorrer) *FileMonitor

BaseFileMonitor returns the underlying base object.

func (*FileMonitor) Cancel 

func (monitor *FileMonitor) Cancel() bool

Cancel cancels a file monitor.

The function returns the following values:

  • ok always TRUE.

func (*FileMonitor) ConnectChanged 

func (monitor *FileMonitor) ConnectChanged(f func(file, otherFile Filer, eventType FileMonitorEvent)) coreglib.SignalHandle

ConnectChanged is emitted when file has been changed.

If using G_FILE_MONITOR_WATCH_MOVES on a directory monitor, and the information is available (and if supported by the backend), event_type may be G_FILE_MONITOR_EVENT_RENAMED, G_FILE_MONITOR_EVENT_MOVED_IN or G_FILE_MONITOR_EVENT_MOVED_OUT.

In all cases file will be a child of the monitored directory. For renames, file will be the old name and other_file is the new name. For "moved in" events, file is the name of the file that appeared and other_file is the old name that it was moved from (in another directory). For "moved out" events, file is the name of the file that used to be in this directory and other_file is the name of the file at its new location.

It makes sense to treat G_FILE_MONITOR_EVENT_MOVED_IN as equivalent to G_FILE_MONITOR_EVENT_CREATED and G_FILE_MONITOR_EVENT_MOVED_OUT as equivalent to G_FILE_MONITOR_EVENT_DELETED, with extra information. G_FILE_MONITOR_EVENT_RENAMED is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the G_FILE_MONITOR_WATCH_MOVES flag is not in use.

If using the deprecated flag G_FILE_MONITOR_SEND_MOVED flag and event_type is G_FILE_MONITOR_EVENT_MOVED, file will be set to a #GFile containing the old path, and other_file will be set to a #GFile containing the new path.

In all the other cases, other_file will be set to LL.

func (*FileMonitor) EmitEvent 

func (monitor *FileMonitor) EmitEvent(child, otherFile Filer, eventType FileMonitorEvent)

EmitEvent emits the Monitor::changed signal if a change has taken place. Should be called from file monitor implementations only.

Implementations are responsible to call this method from the [thread-default main context][g-main-context-push-thread-default] of the thread that the monitor was created in.

The function takes the following parameters:

  • child: #GFile.
  • otherFile: #GFile.
  • eventType: set of MonitorEvent flags.

func (*FileMonitor) IsCancelled 

func (monitor *FileMonitor) IsCancelled() bool

IsCancelled returns whether the monitor is canceled.

The function returns the following values:

  • ok: TRUE if monitor is canceled. FALSE otherwise.

func (*FileMonitor) SetRateLimit 

func (monitor *FileMonitor) SetRateLimit(limitMsecs int)

SetRateLimit sets the rate limit to which the monitor will report consecutive change events to the same file.

The function takes the following parameters:

  • limitMsecs: non-negative integer with the limit in milliseconds to poll for changes.

type FileMonitorClass added in v0.0.5 

type FileMonitorClass struct {
	// contains filtered or unexported fields
}

FileMonitorClass: instance of this type is always passed by reference.

type FileMonitorEvent 

type FileMonitorEvent C.gint

FileMonitorEvent specifies what type of event a monitor event is. 

const (
	// FileMonitorEventChanged: file changed.
	FileMonitorEventChanged FileMonitorEvent = iota
	// FileMonitorEventChangesDoneHint: hint that this was probably the last
	// change in a set of changes.
	FileMonitorEventChangesDoneHint
	// FileMonitorEventDeleted: file was deleted.
	FileMonitorEventDeleted
	// FileMonitorEventCreated: file was created.
	FileMonitorEventCreated
	// FileMonitorEventAttributeChanged: file attribute was changed.
	FileMonitorEventAttributeChanged
	// FileMonitorEventPreUnmount: file location will soon be unmounted.
	FileMonitorEventPreUnmount
	// FileMonitorEventUnmounted: file location was unmounted.
	FileMonitorEventUnmounted
	// FileMonitorEventMoved: file was moved -- only sent if the (deprecated)
	// G_FILE_MONITOR_SEND_MOVED flag is set.
	FileMonitorEventMoved
	// FileMonitorEventRenamed: file was renamed within the current directory --
	// only sent if the G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46.
	FileMonitorEventRenamed
	// FileMonitorEventMovedIn: file was moved into the monitored directory from
	// another location -- only sent if the G_FILE_MONITOR_WATCH_MOVES flag is
	// set. Since: 2.46.
	FileMonitorEventMovedIn
	// FileMonitorEventMovedOut: file was moved out of the monitored directory
	// to another location -- only sent if the G_FILE_MONITOR_WATCH_MOVES flag
	// is set. Since: 2.46.
	FileMonitorEventMovedOut
)

func (FileMonitorEvent) String 

func (f FileMonitorEvent) String() string

String returns the name in string for FileMonitorEvent.

type FileMonitorFlags 

type FileMonitorFlags C.guint

FileMonitorFlags flags used to set what a Monitor will watch for. 

const (
	// FileMonitorNone: no flags set.
	FileMonitorNone FileMonitorFlags = 0b0
	// FileMonitorWatchMounts: watch for mount events.
	FileMonitorWatchMounts FileMonitorFlags = 0b1
	// FileMonitorSendMoved: pair DELETED and CREATED events caused by file
	// renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event
	// instead (NB: not supported on all backends; the default behaviour
	// -without specifying this flag- is to send single DELETED and CREATED
	// events). Deprecated since 2.46: use G_FILE_MONITOR_WATCH_MOVES instead.
	FileMonitorSendMoved FileMonitorFlags = 0b10
	// FileMonitorWatchHardLinks: watch for changes to the file made via another
	// hard link. Since 2.36.
	FileMonitorWatchHardLinks FileMonitorFlags = 0b100
	// FileMonitorWatchMoves: watch for rename operations on a
	// monitored directory. This causes G_FILE_MONITOR_EVENT_RENAMED,
	// G_FILE_MONITOR_EVENT_MOVED_IN and G_FILE_MONITOR_EVENT_MOVED_OUT events
	// to be emitted when possible. Since: 2.46.
	FileMonitorWatchMoves FileMonitorFlags = 0b1000
)

func (FileMonitorFlags) Has 

func (f FileMonitorFlags) Has(other FileMonitorFlags) bool

Has returns true if f contains other.

func (FileMonitorFlags) String 

func (f FileMonitorFlags) String() string

String returns the names in string for FileMonitorFlags.

type FileMonitorOverrides added in v0.0.5 

type FileMonitorOverrides struct {
	// Cancel cancels a file monitor.
	//
	// The function returns the following values:
	//
	//   - ok always TRUE.
	Cancel func() bool
	// The function takes the following parameters:
	//
	//   - file
	//   - otherFile
	//   - eventType
	Changed func(file, otherFile Filer, eventType FileMonitorEvent)
}

FileMonitorOverrides contains methods that are overridable.

type FileMonitorrer 

type FileMonitorrer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

FileMonitorrer describes types inherited from class FileMonitor.

To get the original type, the caller must assert this to an interface or another type.

type FileOutputStream 

type FileOutputStream struct {
	OutputStream

	*coreglib.Object
	Seekable
	// contains filtered or unexported fields
}

FileOutputStream: GFileOutputStream provides output streams that write their content to a file.

GFileOutputStream implements gio.Seekable, which allows the output stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations.

To find the position of a file output stream, use gio.Seekable.Tell(). To find out if a file output stream supports seeking, use gio.Seekable.CanSeek().To position a file output stream, use gio.Seekable.Seek(). To find out if a file output stream supports truncating, use gio.Seekable.CanTruncate(). To truncate a file output stream, use gio.Seekable.Truncate().

func (*FileOutputStream) ETag 

func (stream *FileOutputStream) ETag() string

ETag gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing.

The function returns the following values:

  • utf8 (optional): entity tag for the stream.

func (*FileOutputStream) QueryInfo 

func (stream *FileOutputStream) QueryInfo(ctx context.Context, attributes string) (*FileInfo, error)

QueryInfo queries a file output stream for the given attributes. This function blocks while querying the stream. For the asynchronous version of this function, see g_file_output_stream_query_info_async(). While the stream is blocked, the stream will set the pending flag internally, and any other operations on the stream will fail with G_IO_ERROR_PENDING.

Can fail if the stream was already closed (with error being set to G_IO_ERROR_CLOSED), the stream has pending operations (with error being set to G_IO_ERROR_PENDING), or if querying info is not supported for the stream's interface (with error being set to G_IO_ERROR_NOT_SUPPORTED). In all cases of failure, NULL will be returned.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be set, and NULL will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.

The function returns the following values:

  • fileInfo for the stream, or NULL on error.

func (*FileOutputStream) QueryInfoAsync 

func (stream *FileOutputStream) QueryInfoAsync(ctx context.Context, attributes string, ioPriority int, callback AsyncReadyCallback)

QueryInfoAsync: asynchronously queries the stream for a Info. When completed, callback will be called with a Result which can be used to finish the operation with g_file_output_stream_query_info_finish().

For the synchronous version of this function, see g_file_output_stream_query_info().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • attributes: file attribute query string.
  • ioPriority: I/O priority (iface.AsyncResult.html#io-priority) of the request.
  • callback (optional) to call when the request is satisfied.

func (*FileOutputStream) QueryInfoFinish 

func (stream *FileOutputStream) QueryInfoFinish(result AsyncResulter) (*FileInfo, error)

QueryInfoFinish finalizes the asynchronous query started by g_file_output_stream_query_info_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • fileInfo for the finished query.

type FileOutputStreamClass added in v0.0.5 

type FileOutputStreamClass struct {
	// contains filtered or unexported fields
}

FileOutputStreamClass: instance of this type is always passed by reference.

func (*FileOutputStreamClass) ParentClass added in v0.0.5 

func (f *FileOutputStreamClass) ParentClass() *OutputStreamClass

type FileOutputStreamOverrides added in v0.0.5 

type FileOutputStreamOverrides struct {
	CanSeek     func() bool
	CanTruncate func() bool
	// ETag gets the entity tag for the file when it has been written. This must
	// be called after the stream has been written and closed, as the etag can
	// change while writing.
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): entity tag for the stream.
	ETag func() string
	// QueryInfo queries a file output stream for the given attributes. This
	// function blocks while querying the stream. For the asynchronous version
	// of this function, see g_file_output_stream_query_info_async(). While
	// the stream is blocked, the stream will set the pending flag internally,
	// and any other operations on the stream will fail with G_IO_ERROR_PENDING.
	//
	// Can fail if the stream was already closed (with error being set to
	// G_IO_ERROR_CLOSED), the stream has pending operations (with error being
	// set to G_IO_ERROR_PENDING), or if querying info is not supported for the
	// stream's interface (with error being set to G_IO_ERROR_NOT_SUPPORTED).
	// In all cases of failure, NULL will be returned.
	//
	// If cancellable is not NULL, then the operation can be cancelled by
	// triggering the cancellable object from another thread. If the operation
	// was cancelled, the error G_IO_ERROR_CANCELLED will be set, and NULL will
	// be returned.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - attributes: file attribute query string.
	//
	// The function returns the following values:
	//
	//   - fileInfo for the stream, or NULL on error.
	QueryInfo func(ctx context.Context, attributes string) (*FileInfo, error)
	// QueryInfoFinish finalizes the asynchronous query started by
	// g_file_output_stream_query_info_async().
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - fileInfo for the finished query.
	QueryInfoFinish func(result AsyncResulter) (*FileInfo, error)
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - offset
	//   - typ
	Seek func(ctx context.Context, offset int64, typ glib.SeekType) error
	Tell func() int64
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - size
	TruncateFn func(ctx context.Context, size int64) error
}

FileOutputStreamOverrides contains methods that are overridable.

type FileQueryInfoFlags 

type FileQueryInfoFlags C.guint

FileQueryInfoFlags flags used when querying a Info. 

const (
	// FileQueryInfoNone: no flags set.
	FileQueryInfoNone FileQueryInfoFlags = 0b0
	// FileQueryInfoNofollowSymlinks: don't follow symlinks.
	FileQueryInfoNofollowSymlinks FileQueryInfoFlags = 0b1
)

func (FileQueryInfoFlags) Has 

func (f FileQueryInfoFlags) Has(other FileQueryInfoFlags) bool

Has returns true if f contains other.

func (FileQueryInfoFlags) String 

func (f FileQueryInfoFlags) String() string

String returns the names in string for FileQueryInfoFlags.

type FileType 

type FileType C.gint

FileType indicates the file's on-disk type.

On Windows systems a file will never have G_FILE_TYPE_SYMBOLIC_LINK type; use Info and G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK to determine whether a file is a symlink or not. This is due to the fact that NTFS does not have a single filesystem object type for symbolic links - it has files that symlink to files, and directories that symlink to directories. Type enumeration cannot precisely represent this important distinction, which is why all Windows symlinks will continue to be reported as G_FILE_TYPE_REGULAR or G_FILE_TYPE_DIRECTORY. 

const (
	// FileTypeUnknown file's type is unknown.
	FileTypeUnknown FileType = iota
	// FileTypeRegular: file handle represents a regular file.
	FileTypeRegular
	// FileTypeDirectory: file handle represents a directory.
	FileTypeDirectory
	// FileTypeSymbolicLink: file handle represents a symbolic link (Unix
	// systems).
	FileTypeSymbolicLink
	// FileTypeSpecial: file is a "special" file, such as a socket, fifo,
	// block device, or character device.
	FileTypeSpecial
	// FileTypeShortcut: file is a shortcut (Windows systems).
	FileTypeShortcut
	// FileTypeMountable: file is a mountable location.
	FileTypeMountable
)

func (FileType) String 

func (f FileType) String() string

String returns the name in string for FileType.

type FilenameCompleter 

type FilenameCompleter struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

FilenameCompleter completes partial file and directory names given a partial string by looking in the file system for clues. Can return a list of possible completion strings for widget implementations.

func NewFilenameCompleter 

func NewFilenameCompleter() *FilenameCompleter

NewFilenameCompleter creates a new filename completer.

The function returns the following values:

  • filenameCompleter: Completer.

func (*FilenameCompleter) CompletionSuffix 

func (completer *FilenameCompleter) CompletionSuffix(initialText string) string

CompletionSuffix obtains a completion for initial_text from completer.

The function takes the following parameters:

  • initialText: text to be completed.

The function returns the following values:

  • utf8 (optional): completed string, or NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished.

func (*FilenameCompleter) Completions 

func (completer *FilenameCompleter) Completions(initialText string) []string

Completions gets an array of completion strings for a given initial text.

The function takes the following parameters:

  • initialText: text to be completed.

The function returns the following values:

  • utf8s: array of strings with possible completions for initial_text. This array must be freed by g_strfreev() when finished.

func (*FilenameCompleter) ConnectGotCompletionData 

func (completer *FilenameCompleter) ConnectGotCompletionData(f func()) coreglib.SignalHandle

ConnectGotCompletionData is emitted when the file name completion information comes available.

func (*FilenameCompleter) SetDirsOnly 

func (completer *FilenameCompleter) SetDirsOnly(dirsOnly bool)

SetDirsOnly: if dirs_only is TRUE, completer will only complete directory names, and not file names.

The function takes the following parameters:

  • dirsOnly: #gboolean.

type FilenameCompleterClass added in v0.0.5 

type FilenameCompleterClass struct {
	// contains filtered or unexported fields
}

FilenameCompleterClass: instance of this type is always passed by reference.

type FilenameCompleterOverrides added in v0.0.5 

type FilenameCompleterOverrides struct {
	GotCompletionData func()
}

FilenameCompleterOverrides contains methods that are overridable.

type Filer 

type Filer interface {
	coreglib.Objector

	// AppendTo gets an output stream for appending data to the file.
	AppendTo(ctx context.Context, flags FileCreateFlags) (*FileOutputStream, error)
	// AppendToAsync: asynchronously opens file for appending.
	AppendToAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)
	// AppendToFinish finishes an asynchronous file append operation started
	// with g_file_append_to_async().
	AppendToFinish(res AsyncResulter) (*FileOutputStream, error)
	// BuildAttributeListForCopy prepares the file attribute query string for
	// copying to file.
	BuildAttributeListForCopy(ctx context.Context, flags FileCopyFlags) (string, error)
	// CopyAttributes copies the file attributes from source to destination.
	CopyAttributes(ctx context.Context, destination Filer, flags FileCopyFlags) error
	// CopyFinish finishes copying the file started with g_file_copy_async().
	CopyFinish(res AsyncResulter) error
	// Create creates a new file and returns an output stream for writing to it.
	Create(ctx context.Context, flags FileCreateFlags) (*FileOutputStream, error)
	// CreateAsync: asynchronously creates a new file and returns an output
	// stream for writing to it.
	CreateAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)
	// CreateFinish finishes an asynchronous file create operation started with
	// g_file_create_async().
	CreateFinish(res AsyncResulter) (*FileOutputStream, error)
	// CreateReadwrite creates a new file and returns a stream for reading and
	// writing to it.
	CreateReadwrite(ctx context.Context, flags FileCreateFlags) (*FileIOStream, error)
	// CreateReadwriteAsync: asynchronously creates a new file and returns a
	// stream for reading and writing to it.
	CreateReadwriteAsync(ctx context.Context, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)
	// CreateReadwriteFinish finishes an asynchronous file create operation
	// started with g_file_create_readwrite_async().
	CreateReadwriteFinish(res AsyncResulter) (*FileIOStream, error)
	// Delete deletes a file.
	Delete(ctx context.Context) error
	// DeleteAsync: asynchronously delete a file.
	DeleteAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// DeleteFinish finishes deleting a file started with g_file_delete_async().
	DeleteFinish(result AsyncResulter) error
	// Dup duplicates a #GFile handle.
	Dup() *File
	// EjectMountable starts an asynchronous eject on a mountable.
	EjectMountable(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// EjectMountableFinish finishes an asynchronous eject operation started by
	// g_file_eject_mountable().
	EjectMountableFinish(result AsyncResulter) error
	// EjectMountableWithOperation starts an asynchronous eject on a mountable.
	EjectMountableWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// EjectMountableWithOperationFinish finishes an asynchronous eject
	// operation started by g_file_eject_mountable_with_operation().
	EjectMountableWithOperationFinish(result AsyncResulter) error
	// EnumerateChildren gets the requested information about the files in a
	// directory.
	EnumerateChildren(ctx context.Context, attributes string, flags FileQueryInfoFlags) (*FileEnumerator, error)
	// EnumerateChildrenAsync: asynchronously gets the requested information
	// about the files in a directory.
	EnumerateChildrenAsync(ctx context.Context, attributes string, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)
	// EnumerateChildrenFinish finishes an async enumerate children operation.
	EnumerateChildrenFinish(res AsyncResulter) (*FileEnumerator, error)
	// Equal checks if the two given #GFiles refer to the same file.
	Equal(file2 Filer) bool
	// FindEnclosingMount gets a #GMount for the #GFile.
	FindEnclosingMount(ctx context.Context) (*Mount, error)
	// FindEnclosingMountAsync: asynchronously gets the mount for the file.
	FindEnclosingMountAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// FindEnclosingMountFinish finishes an asynchronous find mount request.
	FindEnclosingMountFinish(res AsyncResulter) (*Mount, error)
	// Basename gets the base name (the last component of the path) for a given
	// #GFile.
	Basename() string
	// Child gets a child of file with basename equal to name.
	Child(name string) *File
	// ChildForDisplayName gets the child of file for a given display_name (i.e.
	ChildForDisplayName(displayName string) (*File, error)
	// Parent gets the parent directory for the file.
	Parent() *File
	// ParseName gets the parse name of the file.
	ParseName() string
	// Path gets the local pathname for #GFile, if one exists.
	Path() string
	// RelativePath gets the path for descendant relative to parent.
	RelativePath(descendant Filer) string
	// URI gets the URI for the file.
	URI() string
	// URIScheme gets the URI scheme for a #GFile.
	URIScheme() string
	// HasParent checks if file has a parent, and optionally, if it is parent.
	HasParent(parent Filer) bool
	// HasPrefix checks whether file has the prefix specified by prefix.
	HasPrefix(prefix Filer) bool
	// HasURIScheme checks to see if a #GFile has a given URI scheme.
	HasURIScheme(uriScheme string) bool
	// Hash creates a hash value for a #GFile.
	Hash() uint
	// IsNative checks to see if a file is native to the platform.
	IsNative() bool
	// LoadBytes loads the contents of file and returns it as #GBytes.
	LoadBytes(ctx context.Context) (string, *glib.Bytes, error)
	// LoadBytesAsync: asynchronously loads the contents of file as #GBytes.
	LoadBytesAsync(ctx context.Context, callback AsyncReadyCallback)
	// LoadBytesFinish completes an asynchronous request to
	// g_file_load_bytes_async().
	LoadBytesFinish(result AsyncResulter) (string, *glib.Bytes, error)
	// LoadContents loads the content of the file into memory.
	LoadContents(ctx context.Context) ([]byte, string, error)
	// LoadContentsAsync starts an asynchronous load of the file's contents.
	LoadContentsAsync(ctx context.Context, callback AsyncReadyCallback)
	// LoadContentsFinish finishes an asynchronous load of the file's contents.
	LoadContentsFinish(res AsyncResulter) ([]byte, string, error)
	// LoadPartialContentsFinish finishes an asynchronous partial load operation
	// that was started with g_file_load_partial_contents_async().
	LoadPartialContentsFinish(res AsyncResulter) ([]byte, string, error)
	// MakeDirectory creates a directory.
	MakeDirectory(ctx context.Context) error
	// MakeDirectoryAsync: asynchronously creates a directory.
	MakeDirectoryAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// MakeDirectoryFinish finishes an asynchronous directory creation, started
	// with g_file_make_directory_async().
	MakeDirectoryFinish(result AsyncResulter) error
	// MakeDirectoryWithParents creates a directory and any parent directories
	// that may not exist similar to 'mkdir -p'.
	MakeDirectoryWithParents(ctx context.Context) error
	// MakeSymbolicLink creates a symbolic link named file which contains the
	// string symlink_value.
	MakeSymbolicLink(ctx context.Context, symlinkValue string) error
	// MakeSymbolicLinkAsync: asynchronously creates a symbolic link named file
	// which contains the string symlink_value.
	MakeSymbolicLinkAsync(ctx context.Context, symlinkValue string, ioPriority int, callback AsyncReadyCallback)
	// MakeSymbolicLinkFinish finishes an asynchronous symbolic link creation,
	// started with g_file_make_symbolic_link_async().
	MakeSymbolicLinkFinish(result AsyncResulter) error
	// MeasureDiskUsageFinish collects the results from an earlier call to
	// g_file_measure_disk_usage_async().
	MeasureDiskUsageFinish(result AsyncResulter) (diskUsage, numDirs, numFiles uint64, goerr error)
	// Monitor obtains a file or directory monitor for the given file, depending
	// on the type of the file.
	Monitor(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)
	// MonitorDirectory obtains a directory monitor for the given file.
	MonitorDirectory(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)
	// MonitorFile obtains a file monitor for the given file.
	MonitorFile(ctx context.Context, flags FileMonitorFlags) (FileMonitorrer, error)
	// MountEnclosingVolume starts a mount_operation, mounting the volume that
	// contains the file location.
	MountEnclosingVolume(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// MountEnclosingVolumeFinish finishes a mount operation started by
	// g_file_mount_enclosing_volume().
	MountEnclosingVolumeFinish(result AsyncResulter) error
	// MountMountable mounts a file of type G_FILE_TYPE_MOUNTABLE.
	MountMountable(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// MountMountableFinish finishes a mount operation.
	MountMountableFinish(result AsyncResulter) (*File, error)
	// MoveFinish finishes an asynchronous file movement, started with
	// g_file_move_async().
	MoveFinish(result AsyncResulter) error
	// OpenReadwrite opens an existing file for reading and writing.
	OpenReadwrite(ctx context.Context) (*FileIOStream, error)
	// OpenReadwriteAsync: asynchronously opens file for reading and writing.
	OpenReadwriteAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// OpenReadwriteFinish finishes an asynchronous file read operation started
	// with g_file_open_readwrite_async().
	OpenReadwriteFinish(res AsyncResulter) (*FileIOStream, error)
	// PeekPath: exactly like g_file_get_path(), but caches the result via
	// g_object_set_qdata_full().
	PeekPath() string
	// PollMountable polls a file of type G_FILE_TYPE_MOUNTABLE.
	PollMountable(ctx context.Context, callback AsyncReadyCallback)
	// PollMountableFinish finishes a poll operation.
	PollMountableFinish(result AsyncResulter) error
	// QueryDefaultHandler returns the Info that is registered as the default
	// application to handle the file specified by file.
	QueryDefaultHandler(ctx context.Context) (*AppInfo, error)
	// QueryDefaultHandlerAsync: async version of
	// g_file_query_default_handler().
	QueryDefaultHandlerAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// QueryDefaultHandlerFinish finishes a g_file_query_default_handler_async()
	// operation.
	QueryDefaultHandlerFinish(result AsyncResulter) (*AppInfo, error)
	// QueryExists: utility function to check if a particular file exists.
	QueryExists(ctx context.Context) bool
	// QueryFileType: utility function to inspect the Type of a file.
	QueryFileType(ctx context.Context, flags FileQueryInfoFlags) FileType
	// QueryFilesystemInfo: similar to g_file_query_info(), but obtains
	// information about the filesystem the file is on, rather than the file
	// itself.
	QueryFilesystemInfo(ctx context.Context, attributes string) (*FileInfo, error)
	// QueryFilesystemInfoAsync: asynchronously gets the requested information
	// about the filesystem that the specified file is on.
	QueryFilesystemInfoAsync(ctx context.Context, attributes string, ioPriority int, callback AsyncReadyCallback)
	// QueryFilesystemInfoFinish finishes an asynchronous filesystem info query.
	QueryFilesystemInfoFinish(res AsyncResulter) (*FileInfo, error)
	// QueryInfo gets the requested information about specified file.
	QueryInfo(ctx context.Context, attributes string, flags FileQueryInfoFlags) (*FileInfo, error)
	// QueryInfoAsync: asynchronously gets the requested information about
	// specified file.
	QueryInfoAsync(ctx context.Context, attributes string, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)
	// QueryInfoFinish finishes an asynchronous file info query.
	QueryInfoFinish(res AsyncResulter) (*FileInfo, error)
	// QuerySettableAttributes: obtain the list of settable attributes for the
	// file.
	QuerySettableAttributes(ctx context.Context) (*FileAttributeInfoList, error)
	// QueryWritableNamespaces: obtain the list of attribute namespaces where
	// new attributes can be created by a user.
	QueryWritableNamespaces(ctx context.Context) (*FileAttributeInfoList, error)
	// Read opens a file for reading.
	Read(ctx context.Context) (*FileInputStream, error)
	// ReadAsync: asynchronously opens file for reading.
	ReadAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// ReadFinish finishes an asynchronous file read operation started with
	// g_file_read_async().
	ReadFinish(res AsyncResulter) (*FileInputStream, error)
	// Replace returns an output stream for overwriting the file, possibly
	// creating a backup copy of the file first.
	Replace(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags) (*FileOutputStream, error)
	// ReplaceAsync: asynchronously overwrites the file, replacing the contents,
	// possibly creating a backup copy of the file first.
	ReplaceAsync(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)
	// ReplaceContents replaces the contents of file with contents of length
	// bytes.
	ReplaceContents(ctx context.Context, contents, etag string, makeBackup bool, flags FileCreateFlags) (string, error)
	// ReplaceContentsAsync starts an asynchronous replacement of file with the
	// given contents of length bytes.
	ReplaceContentsAsync(ctx context.Context, contents, etag string, makeBackup bool, flags FileCreateFlags, callback AsyncReadyCallback)
	// ReplaceContentsBytesAsync: same as g_file_replace_contents_async() but
	// takes a #GBytes input instead.
	ReplaceContentsBytesAsync(ctx context.Context, contents *glib.Bytes, etag string, makeBackup bool, flags FileCreateFlags, callback AsyncReadyCallback)
	// ReplaceContentsFinish finishes an asynchronous replace of the given file.
	ReplaceContentsFinish(res AsyncResulter) (string, error)
	// ReplaceFinish finishes an asynchronous file replace operation started
	// with g_file_replace_async().
	ReplaceFinish(res AsyncResulter) (*FileOutputStream, error)
	// ReplaceReadwrite returns an output stream for overwriting the file in
	// readwrite mode, possibly creating a backup copy of the file first.
	ReplaceReadwrite(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags) (*FileIOStream, error)
	// ReplaceReadwriteAsync: asynchronously overwrites the file in read-write
	// mode, replacing the contents, possibly creating a backup copy of the file
	// first.
	ReplaceReadwriteAsync(ctx context.Context, etag string, makeBackup bool, flags FileCreateFlags, ioPriority int, callback AsyncReadyCallback)
	// ReplaceReadwriteFinish finishes an asynchronous file replace operation
	// started with g_file_replace_readwrite_async().
	ReplaceReadwriteFinish(res AsyncResulter) (*FileIOStream, error)
	// ResolveRelativePath resolves a relative path for file to an absolute
	// path.
	ResolveRelativePath(relativePath string) *File
	// SetAttribute sets an attribute in the file with attribute name attribute
	// to value_p.
	SetAttribute(ctx context.Context, attribute string, typ FileAttributeType, valueP unsafe.Pointer, flags FileQueryInfoFlags) error
	// SetAttributeByteString sets attribute of type
	// G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to value.
	SetAttributeByteString(ctx context.Context, attribute, value string, flags FileQueryInfoFlags) error
	// SetAttributeInt32 sets attribute of type G_FILE_ATTRIBUTE_TYPE_INT32 to
	// value.
	SetAttributeInt32(ctx context.Context, attribute string, value int32, flags FileQueryInfoFlags) error
	// SetAttributeInt64 sets attribute of type G_FILE_ATTRIBUTE_TYPE_INT64 to
	// value.
	SetAttributeInt64(ctx context.Context, attribute string, value int64, flags FileQueryInfoFlags) error
	// SetAttributeString sets attribute of type G_FILE_ATTRIBUTE_TYPE_STRING to
	// value.
	SetAttributeString(ctx context.Context, attribute, value string, flags FileQueryInfoFlags) error
	// SetAttributeUint32 sets attribute of type G_FILE_ATTRIBUTE_TYPE_UINT32 to
	// value.
	SetAttributeUint32(ctx context.Context, attribute string, value uint32, flags FileQueryInfoFlags) error
	// SetAttributeUint64 sets attribute of type G_FILE_ATTRIBUTE_TYPE_UINT64 to
	// value.
	SetAttributeUint64(ctx context.Context, attribute string, value uint64, flags FileQueryInfoFlags) error
	// SetAttributesAsync: asynchronously sets the attributes of file with info.
	SetAttributesAsync(ctx context.Context, info *FileInfo, flags FileQueryInfoFlags, ioPriority int, callback AsyncReadyCallback)
	// SetAttributesFinish finishes setting an attribute started in
	// g_file_set_attributes_async().
	SetAttributesFinish(result AsyncResulter) (*FileInfo, error)
	// SetAttributesFromInfo tries to set all attributes in the Info on the
	// target values, not stopping on the first error.
	SetAttributesFromInfo(ctx context.Context, info *FileInfo, flags FileQueryInfoFlags) error
	// SetDisplayName renames file to the specified display name.
	SetDisplayName(ctx context.Context, displayName string) (*File, error)
	// SetDisplayNameAsync: asynchronously sets the display name for a given
	// #GFile.
	SetDisplayNameAsync(ctx context.Context, displayName string, ioPriority int, callback AsyncReadyCallback)
	// SetDisplayNameFinish finishes setting a display name started with
	// g_file_set_display_name_async().
	SetDisplayNameFinish(res AsyncResulter) (*File, error)
	// StartMountable starts a file of type G_FILE_TYPE_MOUNTABLE.
	StartMountable(ctx context.Context, flags DriveStartFlags, startOperation *MountOperation, callback AsyncReadyCallback)
	// StartMountableFinish finishes a start operation.
	StartMountableFinish(result AsyncResulter) error
	// StopMountable stops a file of type G_FILE_TYPE_MOUNTABLE.
	StopMountable(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// StopMountableFinish finishes a stop operation, see
	// g_file_stop_mountable() for details.
	StopMountableFinish(result AsyncResulter) error
	// SupportsThreadContexts checks if file supports [thread-default
	// contexts][g-main-context-push-thread-default-context].
	SupportsThreadContexts() bool
	// Trash sends file to the "Trashcan", if possible.
	Trash(ctx context.Context) error
	// TrashAsync: asynchronously sends file to the Trash location, if possible.
	TrashAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)
	// TrashFinish finishes an asynchronous file trashing operation, started
	// with g_file_trash_async().
	TrashFinish(result AsyncResulter) error
	// UnmountMountable unmounts a file of type G_FILE_TYPE_MOUNTABLE.
	UnmountMountable(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// UnmountMountableFinish finishes an unmount operation, see
	// g_file_unmount_mountable() for details.
	UnmountMountableFinish(result AsyncResulter) error
	// UnmountMountableWithOperation unmounts a file of type
	// G_FILE_TYPE_MOUNTABLE.
	UnmountMountableWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// UnmountMountableWithOperationFinish finishes an unmount operation,
	// see g_file_unmount_mountable_with_operation() for details.
	UnmountMountableWithOperationFinish(result AsyncResulter) error
}

Filer describes File's interface methods.

type FilesystemPreviewType 

type FilesystemPreviewType C.gint

FilesystemPreviewType indicates a hint from the file system whether files should be previewed in a file manager. Returned as the value of the key G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. 

const (
	// FilesystemPreviewTypeIfAlways: only preview files if user has explicitly
	// requested it.
	FilesystemPreviewTypeIfAlways FilesystemPreviewType = iota
	// FilesystemPreviewTypeIfLocal: preview files if user has requested preview
	// of "local" files.
	FilesystemPreviewTypeIfLocal
	// FilesystemPreviewTypeNever: never preview files.
	FilesystemPreviewTypeNever
)

func (FilesystemPreviewType) String 

func (f FilesystemPreviewType) String() string

String returns the name in string for FilesystemPreviewType.

type FilterInputStream 

type FilterInputStream struct {
	InputStream
	// contains filtered or unexported fields
}

FilterInputStream: base class for input stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping.

func BaseFilterInputStream 

func BaseFilterInputStream(obj FilterInputStreamer) *FilterInputStream

BaseFilterInputStream returns the underlying base object.

func (*FilterInputStream) BaseStream 

func (stream *FilterInputStream) BaseStream() InputStreamer

BaseStream gets the base stream for the filter stream.

The function returns the following values:

  • inputStream: Stream.

func (*FilterInputStream) CloseBaseStream 

func (stream *FilterInputStream) CloseBaseStream() bool

CloseBaseStream returns whether the base stream will be closed when stream is closed.

The function returns the following values:

  • ok: TRUE if the base stream will be closed.

func (*FilterInputStream) SetCloseBaseStream 

func (stream *FilterInputStream) SetCloseBaseStream(closeBase bool)

SetCloseBaseStream sets whether the base stream will be closed when stream is closed.

The function takes the following parameters:

  • closeBase: TRUE to close the base stream.

type FilterInputStreamClass added in v0.0.5 

type FilterInputStreamClass struct {
	// contains filtered or unexported fields
}

FilterInputStreamClass: instance of this type is always passed by reference.

func (*FilterInputStreamClass) ParentClass added in v0.0.5 

func (f *FilterInputStreamClass) ParentClass() *InputStreamClass

type FilterInputStreamOverrides added in v0.0.5 

type FilterInputStreamOverrides struct {
}

FilterInputStreamOverrides contains methods that are overridable.

type FilterInputStreamer 

type FilterInputStreamer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

FilterInputStreamer describes types inherited from class FilterInputStream.

To get the original type, the caller must assert this to an interface or another type.

type FilterOutputStream 

type FilterOutputStream struct {
	OutputStream
	// contains filtered or unexported fields
}

FilterOutputStream: base class for output stream implementations that perform some kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping.

func BaseFilterOutputStream 

func BaseFilterOutputStream(obj FilterOutputStreamer) *FilterOutputStream

BaseFilterOutputStream returns the underlying base object.

func (*FilterOutputStream) BaseStream 

func (stream *FilterOutputStream) BaseStream() OutputStreamer

BaseStream gets the base stream for the filter stream.

The function returns the following values:

  • outputStream: Stream.

func (*FilterOutputStream) CloseBaseStream 

func (stream *FilterOutputStream) CloseBaseStream() bool

CloseBaseStream returns whether the base stream will be closed when stream is closed.

The function returns the following values:

  • ok: TRUE if the base stream will be closed.

func (*FilterOutputStream) SetCloseBaseStream 

func (stream *FilterOutputStream) SetCloseBaseStream(closeBase bool)

SetCloseBaseStream sets whether the base stream will be closed when stream is closed.

The function takes the following parameters:

  • closeBase: TRUE to close the base stream.

type FilterOutputStreamClass added in v0.0.5 

type FilterOutputStreamClass struct {
	// contains filtered or unexported fields
}

FilterOutputStreamClass: instance of this type is always passed by reference.

func (*FilterOutputStreamClass) ParentClass added in v0.0.5 

func (f *FilterOutputStreamClass) ParentClass() *OutputStreamClass

type FilterOutputStreamOverrides added in v0.0.5 

type FilterOutputStreamOverrides struct {
}

FilterOutputStreamOverrides contains methods that are overridable.

type FilterOutputStreamer 

type FilterOutputStreamer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

FilterOutputStreamer describes types inherited from class FilterOutputStream.

To get the original type, the caller must assert this to an interface or another type.

type IOErrorEnum 

type IOErrorEnum C.gint

IOErrorEnum: error codes returned by GIO functions.

Note that this domain may be extended in future GLib releases. In general, new error codes either only apply to new APIs, or else replace G_IO_ERROR_FAILED in cases that were not explicitly distinguished before. You should therefore avoid writing code like 

if (g_error_matches (error, G_IO_ERROR, G_IO_ERROR_FAILED))
  {
    // Assume that this is EPRINTERONFIRE
    ...
  }

but should instead treat all unrecognized error codes the same as G_IO_ERROR_FAILED.

See also Return for a cheaper way of returning G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError. 

const (
	// IOErrorFailed: generic error condition for when an operation fails and no
	// more specific OErrorEnum value is defined.
	IOErrorFailed IOErrorEnum = 0
	// IOErrorNotFound: file not found.
	IOErrorNotFound IOErrorEnum = 1
	// IOErrorExists: file already exists.
	IOErrorExists IOErrorEnum = 2
	// IOErrorIsDirectory: file is a directory.
	IOErrorIsDirectory IOErrorEnum = 3
	// IOErrorNotDirectory: file is not a directory.
	IOErrorNotDirectory IOErrorEnum = 4
	// IOErrorNotEmpty: file is a directory that isn't empty.
	IOErrorNotEmpty IOErrorEnum = 5
	// IOErrorNotRegularFile: file is not a regular file.
	IOErrorNotRegularFile IOErrorEnum = 6
	// IOErrorNotSymbolicLink: file is not a symbolic link.
	IOErrorNotSymbolicLink IOErrorEnum = 7
	// IOErrorNotMountableFile: file cannot be mounted.
	IOErrorNotMountableFile IOErrorEnum = 8
	// IOErrorFilenameTooLong: filename is too many characters.
	IOErrorFilenameTooLong IOErrorEnum = 9
	// IOErrorInvalidFilename: filename is invalid or contains invalid
	// characters.
	IOErrorInvalidFilename IOErrorEnum = 10
	// IOErrorTooManyLinks: file contains too many symbolic links.
	IOErrorTooManyLinks IOErrorEnum = 11
	// IOErrorNoSpace: no space left on drive.
	IOErrorNoSpace IOErrorEnum = 12
	// IOErrorInvalidArgument: invalid argument.
	IOErrorInvalidArgument IOErrorEnum = 13
	// IOErrorPermissionDenied: permission denied.
	IOErrorPermissionDenied IOErrorEnum = 14
	// IOErrorNotSupported: operation (or one of its parameters) not supported.
	IOErrorNotSupported IOErrorEnum = 15
	// IOErrorNotMounted: file isn't mounted.
	IOErrorNotMounted IOErrorEnum = 16
	// IOErrorAlreadyMounted: file is already mounted.
	IOErrorAlreadyMounted IOErrorEnum = 17
	// IOErrorClosed: file was closed.
	IOErrorClosed IOErrorEnum = 18
	// IOErrorCancelled: operation was cancelled. See #GCancellable.
	IOErrorCancelled IOErrorEnum = 19
	// IOErrorPending operations are still pending.
	IOErrorPending IOErrorEnum = 20
	// IOErrorReadOnly: file is read only.
	IOErrorReadOnly IOErrorEnum = 21
	// IOErrorCantCreateBackup: backup couldn't be created.
	IOErrorCantCreateBackup IOErrorEnum = 22
	// IOErrorWrongETag file's Entity Tag was incorrect.
	IOErrorWrongETag IOErrorEnum = 23
	// IOErrorTimedOut: operation timed out.
	IOErrorTimedOut IOErrorEnum = 24
	// IOErrorWouldRecurse: operation would be recursive.
	IOErrorWouldRecurse IOErrorEnum = 25
	// IOErrorBusy: file is busy.
	IOErrorBusy IOErrorEnum = 26
	// IOErrorWouldBlock: operation would block.
	IOErrorWouldBlock IOErrorEnum = 27
	// IOErrorHostNotFound: host couldn't be found (remote operations).
	IOErrorHostNotFound IOErrorEnum = 28
	// IOErrorWouldMerge: operation would merge files.
	IOErrorWouldMerge IOErrorEnum = 29
	// IOErrorFailedHandled: operation failed and a helper program has already
	// interacted with the user. Do not display any error dialog.
	IOErrorFailedHandled IOErrorEnum = 30
	// IOErrorTooManyOpenFiles: current process has too many files open and
	// can't open any more. Duplicate descriptors do count toward this limit.
	// Since 2.20.
	IOErrorTooManyOpenFiles IOErrorEnum = 31
	// IOErrorNotInitialized: object has not been initialized. Since 2.22.
	IOErrorNotInitialized IOErrorEnum = 32
	// IOErrorAddressInUse: requested address is already in use. Since 2.22.
	IOErrorAddressInUse IOErrorEnum = 33
	// IOErrorPartialInput: need more input to finish operation. Since 2.24.
	IOErrorPartialInput IOErrorEnum = 34
	// IOErrorInvalidData: input data was invalid. Since 2.24.
	IOErrorInvalidData IOErrorEnum = 35
	// IOErrorDBusError: remote object generated an error that doesn't
	// correspond to a locally registered #GError error domain. Use
	// g_dbus_error_get_remote_error() to extract the D-Bus error name and
	// g_dbus_error_strip_remote_error() to fix up the message so it matches
	// what was received on the wire. Since 2.26.
	IOErrorDBusError IOErrorEnum = 36
	// IOErrorHostUnreachable: host unreachable. Since 2.26.
	IOErrorHostUnreachable IOErrorEnum = 37
	// IOErrorNetworkUnreachable: network unreachable. Since 2.26.
	IOErrorNetworkUnreachable IOErrorEnum = 38
	// IOErrorConnectionRefused: connection refused. Since 2.26.
	IOErrorConnectionRefused IOErrorEnum = 39
	// IOErrorProxyFailed: connection to proxy server failed. Since 2.26.
	IOErrorProxyFailed IOErrorEnum = 40
	// IOErrorProxyAuthFailed: proxy authentication failed. Since 2.26.
	IOErrorProxyAuthFailed IOErrorEnum = 41
	// IOErrorProxyNeedAuth: proxy server needs authentication. Since 2.26.
	IOErrorProxyNeedAuth IOErrorEnum = 42
	// IOErrorProxyNotAllowed: proxy connection is not allowed by ruleset.
	// Since 2.26.
	IOErrorProxyNotAllowed IOErrorEnum = 43
	// IOErrorBrokenPipe: broken pipe. Since 2.36.
	IOErrorBrokenPipe IOErrorEnum = 44
	// IOErrorConnectionClosed: connection closed by peer. Note that this is
	// the same code as G_IO_ERROR_BROKEN_PIPE; before 2.44 some "connection
	// closed" errors returned G_IO_ERROR_BROKEN_PIPE, but others returned
	// G_IO_ERROR_FAILED. Now they should all return the same value, which has
	// this more logical name. Since 2.44.
	IOErrorConnectionClosed IOErrorEnum = 44
	// IOErrorNotConnected: transport endpoint is not connected. Since 2.44.
	IOErrorNotConnected IOErrorEnum = 45
	// IOErrorMessageTooLarge: message too large. Since 2.48.
	IOErrorMessageTooLarge IOErrorEnum = 46
	// IOErrorNoSuchDevice: no such device found. Since 2.74.
	IOErrorNoSuchDevice IOErrorEnum = 47
	// IOErrorDestinationUnset: destination address unset. Since 2.80.
	IOErrorDestinationUnset IOErrorEnum = 48
)

func IOErrorFromErrno 

func IOErrorFromErrno(errNo int) IOErrorEnum

IOErrorFromErrno converts errno.h error codes into GIO error codes.

The fallback value G_IO_ERROR_FAILED is returned for error codes not currently handled (but note that future GLib releases may return a more specific value instead).

As errno is global and may be modified by intermediate function calls, you should save its value immediately after the call returns, and use the saved value instead of errno: 

int saved_errno;

ret = read (blah);
saved_errno = errno;

g_io_error_from_errno (saved_errno);.

The function takes the following parameters:

  • errNo: error number as defined in errno.h.

The function returns the following values:

  • ioErrorEnum value for the given errno.h error number.

func IOErrorFromFileError added in v0.3.0 

func IOErrorFromFileError(fileError glib.FileError) IOErrorEnum

IOErrorFromFileError converts Error error codes into GIO error codes.

The function takes the following parameters:

  • fileError: Error.

The function returns the following values:

  • ioErrorEnum value for the given Error error value.

func (IOErrorEnum) String 

func (i IOErrorEnum) String() string

String returns the name in string for IOErrorEnum.

type IOModuleScopeFlags 

type IOModuleScopeFlags C.gint

IOModuleScopeFlags flags for use with g_io_module_scope_new(). 

const (
	// IOModuleScopeNone: no module scan flags.
	IOModuleScopeNone IOModuleScopeFlags = iota
	// IOModuleScopeBlockDuplicates: when using this scope to load or scan
	// modules, automatically block a modules which has the same base basename
	// as previously loaded module.
	IOModuleScopeBlockDuplicates
)

func (IOModuleScopeFlags) String 

func (i IOModuleScopeFlags) String() string

String returns the name in string for IOModuleScopeFlags.

type IOStream 

type IOStream struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

IOStream: GIOStream represents an object that has both read and write streams. Generally the two streams act as separate input and output streams, but they share some common resources and state. For instance, for seekable streams, both streams may use the same position.

Examples of GIOStream objects are gio.SocketConnection, which represents a two-way network connection; and gio.FileIOStream, which represents a file handle opened in read-write mode.

To do the actual reading and writing you need to get the substreams with gio.IOStream.GetInputStream() and gio.IOStream.GetOutputStream().

The GIOStream object owns the input and the output streams, not the other way around, so keeping the substreams alive will not keep the GIOStream object alive. If the GIOStream object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will always return G_IO_ERROR_CLOSED for all operations.

To close a stream use gio.IOStream.Close() which will close the common stream object and also the individual substreams. You can also close the substreams themselves. In most cases this only marks the substream as closed, so further I/O on it fails but common state in the GIOStream may still be open. However, some streams may support ‘half-closed’ states where one direction of the stream is actually shut down.

Operations on GIOStreams cannot be started while another operation on the GIOStream or its substreams is in progress. Specifically, an application can read from the gio.InputStream and write to the gio.OutputStream simultaneously (either in separate threads, or as asynchronous operations in the same thread), but an application cannot start any GIOStream operation while there is a GIOStream, GInputStream or GOutputStream operation in progress, and an application can’t start any GInputStream or GOutputStream operation while there is a GIOStream operation in progress.

This is a product of individual stream operations being associated with a given glib.MainContext (the thread-default context at the time the operation was started), rather than entire streams being associated with a single GMainContext.

GIO may run operations on GIOStreams from other (worker) threads, and this may be exposed to application code in the behaviour of wrapper streams, such as gio.BufferedInputStream or gio.TLSConnection. With such wrapper APIs, application code may only run operations on the base (wrapped) stream when the wrapper stream is idle. Note that the semantics of such operations may not be well-defined due to the state the wrapper stream leaves the base stream in (though they are guaranteed not to crash).

func BaseIOStream 

func BaseIOStream(obj IOStreamer) *IOStream

BaseIOStream returns the underlying base object.

func (*IOStream) ClearPending 

func (stream *IOStream) ClearPending()

ClearPending clears the pending flag on stream.

func (*IOStream) Close 

func (stream *IOStream) Close(ctx context.Context) error

Close closes the stream, releasing resources related to it. This will also close the individual input and output streams, if they are not already closed.

Once the stream is closed, all other operations will return G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error.

Closing a stream will automatically flush any outstanding buffers in the stream.

Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details.

On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors.

The default implementation of this method just calls close on the individual input/output streams.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*IOStream) CloseAsync 

func (stream *IOStream) CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

CloseAsync requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished callback will be called. You can then call g_io_stream_close_finish() to get the result of the operation.

For behaviour details see g_io_stream_close().

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*IOStream) CloseFinish 

func (stream *IOStream) CloseFinish(result AsyncResulter) error

CloseFinish closes a stream.

The function takes the following parameters:

  • result: Result.

func (*IOStream) HasPending 

func (stream *IOStream) HasPending() bool

HasPending checks if a stream has pending actions.

The function returns the following values:

  • ok: TRUE if stream has pending actions.

func (*IOStream) InputStream 

func (stream *IOStream) InputStream() InputStreamer

InputStream gets the input stream for this object. This is used for reading.

The function returns the following values:

  • inputStream owned by the OStream. Do not free.

func (*IOStream) IsClosed 

func (stream *IOStream) IsClosed() bool

IsClosed checks if a stream is closed.

The function returns the following values:

  • ok: TRUE if the stream is closed.

func (*IOStream) OutputStream 

func (stream *IOStream) OutputStream() OutputStreamer

OutputStream gets the output stream for this object. This is used for writing.

The function returns the following values:

  • outputStream owned by the OStream. Do not free.

func (*IOStream) SetPending 

func (stream *IOStream) SetPending() error

SetPending sets stream to have actions pending. If the pending flag is already set or stream is closed, it will return FALSE and set error.

func (*IOStream) SpliceAsync 

func (stream1 *IOStream) SpliceAsync(ctx context.Context, stream2 IOStreamer, flags IOStreamSpliceFlags, ioPriority int, callback AsyncReadyCallback)

SpliceAsync: asynchronously splice the output stream of stream1 to the input stream of stream2, and splice the output stream of stream2 to the input stream of stream1.

When the operation is finished callback will be called. You can then call g_io_stream_splice_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • stream2: OStream.
  • flags: set of OStreamSpliceFlags.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

type IOStreamClass added in v0.0.5 

type IOStreamClass struct {
	// contains filtered or unexported fields
}

IOStreamClass: instance of this type is always passed by reference.

type IOStreamOverrides added in v0.0.5 

type IOStreamOverrides struct {
	// CloseFinish closes a stream.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	CloseFinish func(result AsyncResulter) error
	CloseFn     func(ctx context.Context) error
	// InputStream gets the input stream for this object. This is used for
	// reading.
	//
	// The function returns the following values:
	//
	//   - inputStream owned by the OStream. Do not free.
	InputStream func() InputStreamer
	// OutputStream gets the output stream for this object. This is used for
	// writing.
	//
	// The function returns the following values:
	//
	//   - outputStream owned by the OStream. Do not free.
	OutputStream func() OutputStreamer
}

IOStreamOverrides contains methods that are overridable.

type IOStreamSpliceFlags 

type IOStreamSpliceFlags C.guint

IOStreamSpliceFlags determine how streams should be spliced. 

const (
	// IOStreamSpliceNone: do not close either stream.
	IOStreamSpliceNone IOStreamSpliceFlags = 0b0
	// IOStreamSpliceCloseStream1: close the first stream after the splice.
	IOStreamSpliceCloseStream1 IOStreamSpliceFlags = 0b1
	// IOStreamSpliceCloseStream2: close the second stream after the splice.
	IOStreamSpliceCloseStream2 IOStreamSpliceFlags = 0b10
	// IOStreamSpliceWaitForBoth: wait for both splice operations to finish
	// before calling the callback.
	IOStreamSpliceWaitForBoth IOStreamSpliceFlags = 0b100
)

func (IOStreamSpliceFlags) Has 

func (i IOStreamSpliceFlags) Has(other IOStreamSpliceFlags) bool

Has returns true if i contains other.

func (IOStreamSpliceFlags) String 

func (i IOStreamSpliceFlags) String() string

String returns the names in string for IOStreamSpliceFlags.

type IOStreamer 

type IOStreamer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

IOStreamer describes types inherited from class IOStream.

To get the original type, the caller must assert this to an interface or another type.

func DBusAddressGetStreamFinish 

func DBusAddressGetStreamFinish(res AsyncResulter) (string, IOStreamer, error)

DBusAddressGetStreamFinish finishes an operation started with g_dbus_address_get_stream().

A server is not required to set a GUID, so out_guid may be set to NULL even on success.

The function takes the following parameters:

  • res obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().

The function returns the following values:

  • outGuid (optional): NULL or return location to store the GUID extracted from address, if any.
  • ioStream or NULL if error is set.

func DBusAddressGetStreamSync 

func DBusAddressGetStreamSync(ctx context.Context, address string) (string, IOStreamer, error)

DBusAddressGetStreamSync: synchronously connects to an endpoint specified by address and sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. address must be in the D-Bus address format (https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).

A server is not required to set a GUID, so out_guid may be set to NULL even on success.

This is a synchronous failable function. See g_dbus_address_get_stream() for the asynchronous version.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address: valid D-Bus address.

The function returns the following values:

  • outGuid (optional): NULL or return location to store the GUID extracted from address, if any.
  • ioStream or NULL if error is set.

type Icon 

type Icon struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Icon: GIcon is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings.

GIcon does not provide the actual pixmap for the icon as this is out of GIO's scope, however implementations of GIcon may contain the name of an icon (see gio.ThemedIcon), or the path to an icon (see gio.LoadableIcon).

To obtain a hash of a GIcon, see gio.Icon.Hash().

To check if two GIcons are equal, see gio.Icon.Equal().

For serializing a GIcon, use gio.Icon.Serialize() and gio.Icon().Deserialize.

If you want to consume GIcon (for example, in a toolkit) you must be prepared to handle at least the three following cases: gio.LoadableIcon, gio.ThemedIcon and gio.EmblemedIcon. It may also make sense to have fast-paths for other cases (like handling GdkPixbuf (https://docs.gtk.org/gdk-pixbuf/class.Pixbuf.html) directly, for example) but all compliant GIcon implementations outside of GIO must implement gio.LoadableIcon.

If your application or library provides one or more GIcon implementations you need to ensure that your new implementation also implements gio.LoadableIcon. Additionally, you must provide an implementation of gio.Icon.Serialize() that gives a result that is understood by gio.Icon().Deserialize, yielding one of the built-in icon types.

Icon wraps an interface. This means the user can get the underlying type by calling Cast().

func ContentTypeGetIcon 

func ContentTypeGetIcon(typ string) *Icon

ContentTypeGetIcon gets the icon for a content type.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • icon corresponding to the content type. Free the returned object with g_object_unref().

func ContentTypeGetSymbolicIcon 

func ContentTypeGetSymbolicIcon(typ string) *Icon

ContentTypeGetSymbolicIcon gets the symbolic icon for a content type.

The function takes the following parameters:

  • typ: content type string.

The function returns the following values:

  • icon: symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref().

func IconDeserialize 

func IconDeserialize(value *glib.Variant) *Icon

IconDeserialize deserializes a #GIcon previously serialized using g_icon_serialize().

The function takes the following parameters:

  • value created with g_icon_serialize().

The function returns the following values:

  • icon (optional) or NULL when deserialization fails.

func NewIconForString 

func NewIconForString(str string) (*Icon, error)

NewIconForString: generate a #GIcon instance from str. This function can fail if str is not valid - see g_icon_to_string() for discussion.

If your application or library provides one or more #GIcon implementations you need to ensure that each #GType is registered with the type system prior to calling g_icon_new_for_string().

The function takes the following parameters:

  • str: string obtained via g_icon_to_string().

The function returns the following values:

  • icon: object implementing the #GIcon interface or NULL if error is set.

func (*Icon) Equal 

func (icon1 *Icon) Equal(icon2 Iconner) bool

Equal checks if two icons are equal.

The function takes the following parameters:

  • icon2 (optional): pointer to the second #GIcon.

The function returns the following values:

  • ok: TRUE if icon1 is equal to icon2. FALSE otherwise.

func (*Icon) Hash added in v0.3.0 

func (icon *Icon) Hash() uint

Hash gets a hash for an icon.

The function returns the following values:

  • guint containing a hash for the icon, suitable for use in a Table or similar data structure.

func (*Icon) Serialize 

func (icon *Icon) Serialize() *glib.Variant

Serialize serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace.

The function returns the following values:

  • variant (optional) or NULL when serialization fails. The #GVariant will not be floating.

func (*Icon) String 

func (icon *Icon) String() string

String generates a textual representation of icon that can be used for serialization such as when passing icon to a different process or saving it to persistent storage. Use g_icon_new_for_string() to get icon back from the returned string.

The encoding of the returned string is proprietary to #GIcon except in the following two cases

- If icon is a Icon, the returned string is a native path (such as /path/to/my icon.png) without escaping if the #GFile for icon is a native file. If the file is not native, the returned string is the result of g_file_get_uri() (such as sftp://path/to/my20icon.png).

- If icon is a Icon with exactly one name and no fallbacks, the encoding is simply the name (such as network-server).

The function returns the following values:

  • utf8 (optional): allocated NUL-terminated UTF8 string or NULL if icon can't be serialized. Use g_free() to free.

type IconIface added in v0.0.5 

type IconIface struct {
	// contains filtered or unexported fields
}

IconIface is used to implement GIcon types for various different systems. See Icon and Icon for examples of how to implement this interface.

An instance of this type is always passed by reference.

type Iconner 

type Iconner interface {
	coreglib.Objector

	// Equal checks if two icons are equal.
	Equal(icon2 Iconner) bool
	// Hash gets a hash for an icon.
	Hash() uint
	// Serialize serializes a #GIcon into a #GVariant.
	Serialize() *glib.Variant
	// String generates a textual representation of icon that can be used for
	// serialization such as when passing icon to a different process or saving
	// it to persistent storage.
	String() string
}

Iconner describes Icon's interface methods.

type InetAddress 

type InetAddress struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

InetAddress: GInetAddress represents an IPv4 or IPv6 internet address. Use gio.Resolver.LookupByName() or gio.Resolver.LookupByNameAsync() to look up the GInetAddress for a hostname. Use gio.Resolver.LookupByAddress() or gio.Resolver.LookupByAddressAsync() to look up the hostname for a GInetAddress.

To actually connect to a remote host, you will need a gio.InetSocketAddress (which includes a GInetAddress as well as a port number).

func NewInetAddressAny 

func NewInetAddressAny(family SocketFamily) *InetAddress

NewInetAddressAny creates a Address for the "any" address (unassigned/"don't care") for family.

The function takes the following parameters:

  • family address family.

The function returns the following values:

  • inetAddress: new Address corresponding to the "any" address for family. Free the returned object with g_object_unref().

func NewInetAddressFromString 

func NewInetAddressFromString(str string) *InetAddress

NewInetAddressFromString parses string as an IP address and creates a new Address.

The function takes the following parameters:

  • str: string representation of an IP address.

The function returns the following values:

  • inetAddress (optional): new Address corresponding to string, or NULL if string could not be parsed. Free the returned object with g_object_unref().

func NewInetAddressLoopback 

func NewInetAddressLoopback(family SocketFamily) *InetAddress

NewInetAddressLoopback creates a Address for the loopback address for family.

The function takes the following parameters:

  • family address family.

The function returns the following values:

  • inetAddress: new Address corresponding to the loopback address for family. Free the returned object with g_object_unref().

func (*InetAddress) Equal 

func (address *InetAddress) Equal(otherAddress *InetAddress) bool

Equal checks if two Address instances are equal, e.g. the same address.

The function takes the following parameters:

  • otherAddress: another Address.

The function returns the following values:

  • ok: TRUE if address and other_address are equal, FALSE otherwise.

func (*InetAddress) Family 

func (address *InetAddress) Family() SocketFamily

Family gets address's family.

The function returns the following values:

  • socketFamily address's family.

func (*InetAddress) IsAny 

func (address *InetAddress) IsAny() bool

IsAny tests whether address is the "any" address for its family.

The function returns the following values:

  • ok: TRUE if address is the "any" address for its family.

func (*InetAddress) IsLinkLocal 

func (address *InetAddress) IsLinkLocal() bool

IsLinkLocal tests whether address is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet).

The function returns the following values:

  • ok: TRUE if address is a link-local address.

func (*InetAddress) IsLoopback 

func (address *InetAddress) IsLoopback() bool

IsLoopback tests whether address is the loopback address for its family.

The function returns the following values:

  • ok: TRUE if address is the loopback address for its family.

func (*InetAddress) IsMcGlobal 

func (address *InetAddress) IsMcGlobal() bool

IsMcGlobal tests whether address is a global multicast address.

The function returns the following values:

  • ok: TRUE if address is a global multicast address.

func (*InetAddress) IsMcLinkLocal 

func (address *InetAddress) IsMcLinkLocal() bool

IsMcLinkLocal tests whether address is a link-local multicast address.

The function returns the following values:

  • ok: TRUE if address is a link-local multicast address.

func (*InetAddress) IsMcNodeLocal 

func (address *InetAddress) IsMcNodeLocal() bool

IsMcNodeLocal tests whether address is a node-local multicast address.

The function returns the following values:

  • ok: TRUE if address is a node-local multicast address.

func (*InetAddress) IsMcOrgLocal 

func (address *InetAddress) IsMcOrgLocal() bool

IsMcOrgLocal tests whether address is an organization-local multicast address.

The function returns the following values:

  • ok: TRUE if address is an organization-local multicast address.

func (*InetAddress) IsMcSiteLocal 

func (address *InetAddress) IsMcSiteLocal() bool

IsMcSiteLocal tests whether address is a site-local multicast address.

The function returns the following values:

  • ok: TRUE if address is a site-local multicast address.

func (*InetAddress) IsMulticast 

func (address *InetAddress) IsMulticast() bool

IsMulticast tests whether address is a multicast address.

The function returns the following values:

  • ok: TRUE if address is a multicast address.

func (*InetAddress) IsSiteLocal 

func (address *InetAddress) IsSiteLocal() bool

IsSiteLocal tests whether address is a site-local address such as 10.0.0.1 (that is, the address identifies a host on a local network that can not be reached directly from the Internet, but which may have outgoing Internet connectivity via a NAT or firewall).

The function returns the following values:

  • ok: TRUE if address is a site-local address.

func (*InetAddress) NativeSize 

func (address *InetAddress) NativeSize() uint

NativeSize gets the size of the native raw binary address for address. This is the size of the data that you get from g_inet_address_to_bytes().

The function returns the following values:

  • gsize: number of bytes used for the native version of address.

func (*InetAddress) String 

func (address *InetAddress) String() string

String converts address to string form.

The function returns the following values:

  • utf8: representation of address as a string, which should be freed after use.

type InetAddressClass added in v0.0.5 

type InetAddressClass struct {
	// contains filtered or unexported fields
}

InetAddressClass: instance of this type is always passed by reference.

type InetAddressMask 

type InetAddressMask struct {
	*coreglib.Object

	Initable
	// contains filtered or unexported fields
}

InetAddressMask: GInetAddressMask represents a range of IPv4 or IPv6 addresses described by a base address and a length indicating how many bits of the base address are relevant for matching purposes. These are often given in string form. For example, 10.0.0.0/8, or fe80::/10.

func NewInetAddressMask 

func NewInetAddressMask(addr *InetAddress, length uint) (*InetAddressMask, error)

NewInetAddressMask creates a new AddressMask representing all addresses whose first length bits match addr.

The function takes the following parameters:

  • addr: Address.
  • length: number of bits of addr to use.

The function returns the following values:

  • inetAddressMask: new AddressMask, or NULL on error.

func NewInetAddressMaskFromString 

func NewInetAddressMaskFromString(maskString string) (*InetAddressMask, error)

NewInetAddressMaskFromString parses mask_string as an IP address and (optional) length, and creates a new AddressMask. The length, if present, is delimited by a "/". If it is not present, then the length is assumed to be the full length of the address.

The function takes the following parameters:

  • maskString: IP address or address/length string.

The function returns the following values:

  • inetAddressMask: new AddressMask corresponding to string, or NULL on error.

func (*InetAddressMask) Address 

func (mask *InetAddressMask) Address() *InetAddress

Address gets mask's base address.

The function returns the following values:

  • inetAddress mask's base address.

func (*InetAddressMask) Equal 

func (mask *InetAddressMask) Equal(mask2 *InetAddressMask) bool

Equal tests if mask and mask2 are the same mask.

The function takes the following parameters:

  • mask2: another AddressMask.

The function returns the following values:

  • ok: whether mask and mask2 are the same mask.

func (*InetAddressMask) Family 

func (mask *InetAddressMask) Family() SocketFamily

Family gets the Family of mask's address.

The function returns the following values:

  • socketFamily of mask's address.

func (*InetAddressMask) Length 

func (mask *InetAddressMask) Length() uint

Length gets mask's length.

The function returns the following values:

  • guint mask's length.

func (*InetAddressMask) Matches 

func (mask *InetAddressMask) Matches(address *InetAddress) bool

Matches tests if address falls within the range described by mask.

The function takes the following parameters:

  • address: Address.

The function returns the following values:

  • ok: whether address falls within the range described by mask.

func (*InetAddressMask) String 

func (mask *InetAddressMask) String() string

String converts mask back to its corresponding string form.

The function returns the following values:

  • utf8: string corresponding to mask.

type InetAddressMaskClass added in v0.0.5 

type InetAddressMaskClass struct {
	// contains filtered or unexported fields
}

InetAddressMaskClass: instance of this type is always passed by reference.

type InetAddressMaskOverrides added in v0.0.5 

type InetAddressMaskOverrides struct {
}

InetAddressMaskOverrides contains methods that are overridable.

type InetAddressOverrides added in v0.0.5 

type InetAddressOverrides struct {
	// String converts address to string form.
	//
	// The function returns the following values:
	//
	//   - utf8: representation of address as a string, which should be freed
	//     after use.
	String func() string
}

InetAddressOverrides contains methods that are overridable.

type InetSocketAddress 

type InetSocketAddress struct {
	SocketAddress
	// contains filtered or unexported fields
}

InetSocketAddress: IPv4 or IPv6 socket address. That is, the combination of a gio.InetAddress and a port number.

In UNIX terms, GInetSocketAddress corresponds to a struct sockaddr_in or struct sockaddr_in6 (man:sockaddr(3type)).

func NewInetSocketAddress 

func NewInetSocketAddress(address *InetAddress, port uint16) *InetSocketAddress

NewInetSocketAddress creates a new SocketAddress for address and port.

The function takes the following parameters:

  • address: Address.
  • port number.

The function returns the following values:

  • inetSocketAddress: new SocketAddress.

func NewInetSocketAddressFromString 

func NewInetSocketAddressFromString(address string, port uint) *InetSocketAddress

NewInetSocketAddressFromString creates a new SocketAddress for address and port.

If address is an IPv6 address, it can also contain a scope ID (separated from the address by a %).

The function takes the following parameters:

  • address: string form of an IP address.
  • port number.

The function returns the following values:

  • inetSocketAddress (optional): new SocketAddress, or NULL if address cannot be parsed.

func (*InetSocketAddress) Address 

func (address *InetSocketAddress) Address() *InetAddress

Address gets address's Address.

The function returns the following values:

  • inetAddress for address, which must be g_object_ref()'d if it will be stored.

func (*InetSocketAddress) Flowinfo 

func (address *InetSocketAddress) Flowinfo() uint32

Flowinfo gets the sin6_flowinfo field from address, which must be an IPv6 address.

The function returns the following values:

  • guint32: flowinfo field.

func (*InetSocketAddress) Port 

func (address *InetSocketAddress) Port() uint16

Port gets address's port.

The function returns the following values:

  • guint16: port for address.

func (*InetSocketAddress) ScopeID 

func (address *InetSocketAddress) ScopeID() uint32

ScopeID gets the sin6_scope_id field from address, which must be an IPv6 address.

The function returns the following values:

  • guint32: scope id field.

type InetSocketAddressClass added in v0.0.5 

type InetSocketAddressClass struct {
	// contains filtered or unexported fields
}

InetSocketAddressClass: instance of this type is always passed by reference.

func (*InetSocketAddressClass) ParentClass added in v0.0.5 

func (i *InetSocketAddressClass) ParentClass() *SocketAddressClass

type InetSocketAddressOverrides added in v0.0.5 

type InetSocketAddressOverrides struct {
}

InetSocketAddressOverrides contains methods that are overridable.

type Initable 

type Initable struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Initable: 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 via gio.Initable.Init() or gio.AsyncInitable.InitAsync() (the latter is only available if it also implements gio.AsyncInitable).

If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. They will often fail with glib.Critical() or glib.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 gio.Initable().New directly, or indirectly via a foo_thing_new() wrapper. This will call gio.Initable.Init() under the cover, returning NULL and setting a GError 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 implementing GInitable during normal construction and automatically initialize them, throwing an exception on failure.

Initable wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Initable) Init 

func (initable *Initable) Init(ctx context.Context) error

Init initializes the object implementing the interface.

This method is intended for language bindings. If writing in C, g_initable_new() should typically be used instead.

The object must be initialized before any real use after initial construction, either with this function or g_async_initable_init_async().

Implementations may also support cancellation. If cancellable is not NULL, then initialization can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If cancellable is not NULL and the object doesn't support cancellable initialization the error G_IO_ERROR_NOT_SUPPORTED will be returned.

If the object is not initialized, or initialization returns with an error, then all operations on the object except g_object_ref() and g_object_unref() are considered to be invalid, and have undefined behaviour. See the [introduction][ginitable] for more details.

Callers should not assume that a class which implements #GInitable can be initialized multiple times, unless the class explicitly documents itself as supporting this. Generally, a class’ implementation of init() can assume (and assert) that it will only be called once. Previously, this documentation recommended all #GInitable implementations should be idempotent; that recommendation was relaxed in GLib 2.54.

If a class explicitly supports being initialized multiple times, it is recommended that the method is idempotent: multiple calls with the same arguments should return the same results. Only the first call initializes the object; further calls return the result of the first call.

One reason why a class might need to support idempotent initialization is if it is designed to be used via the singleton pattern, with a Class.constructor that sometimes returns an existing instance. In this pattern, a caller would expect to be able to call g_initable_init() on the result of g_object_new(), regardless of whether it is in fact a new instance.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

type InitableIface added in v0.0.5 

type InitableIface struct {
	// contains filtered or unexported fields
}

InitableIface provides an interface for initializing object such that initialization may fail.

An instance of this type is always passed by reference.

type Initabler 

type Initabler interface {
	coreglib.Objector

	// Init initializes the object implementing the interface.
	Init(ctx context.Context) error
}

Initabler describes Initable's interface methods.

type InputMessage 

type InputMessage struct {
	// contains filtered or unexported fields
}

InputMessage: structure used for scatter/gather data input when receiving multiple messages or packets in one go. You generally pass in an array of empty Vectors and the operation will use all the buffers as if they were one buffer, and will set bytes_received to the total number of bytes received across all Vectors.

This structure closely mirrors struct mmsghdr and struct msghdr from the POSIX sockets API (see man 2 recvmmsg).

If address is non-NULL then it is set to the source address the message was received from, and the caller must free it afterwards.

If control_messages is non-NULL then it is set to an array of control messages received with the message (if any), and the caller must free it afterwards. num_control_messages is set to the number of elements in this array, which may be zero.

Flags relevant to this message will be returned in flags. For example, MSG_EOR or MSG_TRUNC.

An instance of this type is always passed by reference.

type InputStream 

type InputStream struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

InputStream: GInputStream is a base class for implementing streaming input.

It has functions to read from a stream (gio.InputStream.Read()), to close a stream (gio.InputStream.Close()) and to skip some content (gio.InputStream.Skip()).

To copy the content of an input stream to an output stream without manually handling the reads and writes, use gio.OutputStream.Splice().

See the documentation for gio.IOStream for details of thread safety of streaming APIs.

All of these functions have async variants too.

func BaseInputStream 

func BaseInputStream(obj InputStreamer) *InputStream

BaseInputStream returns the underlying base object.

func (*InputStream) ClearPending 

func (stream *InputStream) ClearPending()

ClearPending clears the pending flag on stream.

func (*InputStream) Close 

func (stream *InputStream) Close(ctx context.Context) error

Close closes the stream, releasing resources related to it.

Once the stream is closed, all other operations will return G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error.

Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details.

On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but some streams can use a faster close that doesn't block to e.g. check errors.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

func (*InputStream) CloseAsync 

func (stream *InputStream) CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

CloseAsync requests an asynchronous closes of the stream, releasing resources related to it. When the operation is finished callback will be called. You can then call g_input_stream_close_finish() to get the result of the operation.

For behaviour details see g_input_stream_close().

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*InputStream) CloseFinish 

func (stream *InputStream) CloseFinish(result AsyncResulter) error

CloseFinish finishes closing a stream asynchronously, started from g_input_stream_close_async().

The function takes the following parameters:

  • result: Result.

func (*InputStream) HasPending 

func (stream *InputStream) HasPending() bool

HasPending checks if an input stream has pending actions.

The function returns the following values:

  • ok: TRUE if stream has pending actions.

func (*InputStream) IsClosed 

func (stream *InputStream) IsClosed() bool

IsClosed checks if an input stream is closed.

The function returns the following values:

  • ok: TRUE if the stream is closed.

func (*InputStream) Read 

func (stream *InputStream) Read(ctx context.Context, buffer []byte) (int, error)

Read tries to read count bytes from the stream into the buffer starting at buffer. Will block during this read.

If count is zero returns zero and does nothing. A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file. Zero is returned on end of file (or if count is zero), but never otherwise.

The returned buffer is not a nul-terminated string, it can contain nul bytes at any position, and this function doesn't nul-terminate the buffer.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer: a buffer to read data into (which should be at least count bytes long).

The function returns the following values:

  • gssize: number of bytes read, or -1 on error, or 0 on end of file.

func (*InputStream) ReadAll 

func (stream *InputStream) ReadAll(ctx context.Context, buffer []byte) (uint, error)

ReadAll tries to read count bytes from the stream into the buffer starting at buffer. Will block during this read.

This function is similar to g_input_stream_read(), except it tries to read as many bytes as requested, only stopping on an error or end of stream.

On a successful read of count bytes, or if we reached the end of the stream, TRUE is returned, and bytes_read is set to the number of bytes read into buffer.

If there is an error during the operation FALSE is returned and error is set to indicate the error status.

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_read will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer: a buffer to read data into (which should be at least count bytes long).

The function returns the following values:

  • bytesRead: location to store the number of bytes that was read from the stream.

func (*InputStream) ReadAllAsync 

func (stream *InputStream) ReadAllAsync(ctx context.Context, buffer []byte, ioPriority int, callback AsyncReadyCallback)

ReadAllAsync: request an asynchronous read of count bytes from the stream into the buffer starting at buffer.

This is the asynchronous equivalent of g_input_stream_read_all().

Call g_input_stream_read_all_finish() to collect the result.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer: a buffer to read data into (which should be at least count bytes long).
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*InputStream) ReadAllFinish 

func (stream *InputStream) ReadAllFinish(result AsyncResulter) (uint, error)

ReadAllFinish finishes an asynchronous stream read operation started with g_input_stream_read_all_async().

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_read will be set to the number of bytes that were successfully read before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_input_stream_read_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • bytesRead: location to store the number of bytes that was read from the stream.

func (*InputStream) ReadAsync 

func (stream *InputStream) ReadAsync(ctx context.Context, buffer []byte, ioPriority int, callback AsyncReadyCallback)

ReadAsync: request an asynchronous read of count bytes from the stream into the buffer starting at buffer. When the operation is finished callback will be called. You can then call g_input_stream_read_finish() to get the result of the operation.

During an async request no other sync and async calls are allowed on stream, and will result in G_IO_ERROR_PENDING errors.

A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes read into the buffer will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if count is zero), but never otherwise.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer: a buffer to read data into (which should be at least count bytes long).
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*InputStream) ReadBytes 

func (stream *InputStream) ReadBytes(ctx context.Context, count uint) (*glib.Bytes, error)

ReadBytes: like g_input_stream_read(), this tries to read count bytes from the stream in a blocking fashion. However, rather than reading into a user-supplied buffer, this will create a new #GBytes containing the data that was read. This may be easier to use from language bindings.

If count is zero, returns a zero-length #GBytes and does nothing. A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, a new #GBytes is returned. It is not an error if the size of this object is not the same as the requested size, as it can happen e.g. near the end of a file. A zero-length #GBytes is returned on end of file (or if count is zero), but never otherwise.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

On error NULL is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • count: maximum number of bytes that will be read from the stream. Common values include 4096 and 8192.

The function returns the following values:

  • bytes: new #GBytes, or NULL on error.

func (*InputStream) ReadBytesAsync 

func (stream *InputStream) ReadBytesAsync(ctx context.Context, count uint, ioPriority int, callback AsyncReadyCallback)

ReadBytesAsync: request an asynchronous read of count bytes from the stream into a new #GBytes. When the operation is finished callback will be called. You can then call g_input_stream_read_bytes_finish() to get the result of the operation.

During an async request no other sync and async calls are allowed on stream, and will result in G_IO_ERROR_PENDING errors.

A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the new #GBytes will be passed to the callback. It is not an error if this is smaller than the requested size, as it can happen e.g. near the end of a file, but generally we try to read as many bytes as requested. Zero is returned on end of file (or if count is zero), but never otherwise.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • count: number of bytes that will be read from the stream.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*InputStream) ReadBytesFinish 

func (stream *InputStream) ReadBytesFinish(result AsyncResulter) (*glib.Bytes, error)

ReadBytesFinish finishes an asynchronous stream read-into-#GBytes operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • bytes: newly-allocated #GBytes, or NULL on error.

func (*InputStream) ReadFinish 

func (stream *InputStream) ReadFinish(result AsyncResulter) (int, error)

ReadFinish finishes an asynchronous stream read operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize: number of bytes read in, or -1 on error, or 0 on end of file.

func (*InputStream) SetPending 

func (stream *InputStream) SetPending() error

SetPending sets stream to have actions pending. If the pending flag is already set or stream is closed, it will return FALSE and set error.

func (*InputStream) Skip 

func (stream *InputStream) Skip(ctx context.Context, count uint) (int, error)

Skip tries to skip count bytes from the stream. Will block during the operation.

This is identical to g_input_stream_read(), from a behaviour standpoint, but the bytes that are skipped are not returned to the user. Some streams have an implementation that is more efficient than reading the data.

This function is optional for inherited classes, as the default implementation emulates it using read.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • count: number of bytes that will be skipped from the stream.

The function returns the following values:

  • gssize: number of bytes skipped, or -1 on error.

func (*InputStream) SkipAsync 

func (stream *InputStream) SkipAsync(ctx context.Context, count uint, ioPriority int, callback AsyncReadyCallback)

SkipAsync: request an asynchronous skip of count bytes from the stream. When the operation is finished callback will be called. You can then call g_input_stream_skip_finish() to get the result of the operation.

During an async request no other sync and async calls are allowed, and will result in G_IO_ERROR_PENDING errors.

A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes skipped will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. near the end of a file, but generally we try to skip as many bytes as requested. Zero is returned on end of file (or if count is zero), but never otherwise.

Any outstanding i/o request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one, you must override all.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • count: number of bytes that will be skipped from the stream.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*InputStream) SkipFinish 

func (stream *InputStream) SkipFinish(result AsyncResulter) (int, error)

SkipFinish finishes a stream skip operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize: size of the bytes skipped, or -1 on error.

type InputStreamClass added in v0.0.5 

type InputStreamClass struct {
	// contains filtered or unexported fields
}

InputStreamClass: instance of this type is always passed by reference.

type InputStreamOverrides added in v0.0.5 

type InputStreamOverrides struct {
	// CloseFinish finishes closing a stream asynchronously, started from
	// g_input_stream_close_async().
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	CloseFinish func(result AsyncResulter) error
	CloseFn     func(ctx context.Context) error
	// ReadFinish finishes an asynchronous stream read operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - gssize: number of bytes read in, or -1 on error, or 0 on end of file.
	ReadFinish func(result AsyncResulter) (int, error)
	// Skip tries to skip count bytes from the stream. Will block during the
	// operation.
	//
	// This is identical to g_input_stream_read(), from a behaviour standpoint,
	// but the bytes that are skipped are not returned to the user. Some streams
	// have an implementation that is more efficient than reading the data.
	//
	// This function is optional for inherited classes, as the default
	// implementation emulates it using read.
	//
	// If cancellable is not NULL, then the operation can be cancelled by
	// triggering the cancellable object from another thread. If the operation
	// was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an
	// operation was partially finished when the operation was cancelled the
	// partial result will be returned, without an error.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - count: number of bytes that will be skipped from the stream.
	//
	// The function returns the following values:
	//
	//   - gssize: number of bytes skipped, or -1 on error.
	Skip func(ctx context.Context, count uint) (int, error)
	// SkipFinish finishes a stream skip operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - gssize: size of the bytes skipped, or -1 on error.
	SkipFinish func(result AsyncResulter) (int, error)
}

InputStreamOverrides contains methods that are overridable.

type InputStreamer 

type InputStreamer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

InputStreamer describes types inherited from class InputStream.

To get the original type, the caller must assert this to an interface or another type.

func ResourcesOpenStream 

func ResourcesOpenStream(path string, lookupFlags ResourceLookupFlags) (InputStreamer, error)

ResourcesOpenStream looks for a file at the specified path in the set of globally registered resources and returns a Stream that lets you read the data.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • inputStream or NULL on error. Free the returned object with g_object_unref().

type InputVector 

type InputVector struct {
	// contains filtered or unexported fields
}

InputVector: structure used for scatter/gather data input. You generally pass in an array of Vectors and the operation will store the read data starting in the first buffer, switching to the next as needed.

An instance of this type is always passed by reference.

func (*InputVector) Buffer 

func (i *InputVector) Buffer() unsafe.Pointer

Buffer: pointer to a buffer where data will be written.

func (*InputVector) SetSize 

func (i *InputVector) SetSize(size uint)

Size: available size in buffer.

func (*InputVector) Size 

func (i *InputVector) Size() uint

Size: available size in buffer.

type ListModel 

type ListModel struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

ListModel: GListModel is an interface that represents a mutable list of gobject.Object. 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.Object::notify signal). Taken together with the gio.ListModel::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. gio.ListModel.GetItemType() 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: gio.ListModel.GetNItems() returns the number of items in the list and gio.ListModel.GetItem() 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 call gio.ListModel.GetItem() until it returns NULL.

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 facilitate 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 (see glib.MainContext.PushThreadDefault()) in effect at the time that the model was created.

Over time, it has established itself as good practice for list model implementations to provide properties item-type and n-items to ease working with them. While it is not required, it is recommended that implementations provide these two properties. They should return the values of gio.ListModel.GetItemType() and gio.ListModel.GetNItems() respectively and be defined as such: 

properties[PROP_ITEM_TYPE] =
  g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT,
                      G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
properties[PROP_N_ITEMS] =
  g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0,
                     G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);.

ListModel wraps an interface. This means the user can get the underlying type by calling Cast().

func (*ListModel) ConnectItemsChanged 

func (list *ListModel) ConnectItemsChanged(f func(position, removed, added uint)) coreglib.SignalHandle

ConnectItemsChanged: this signal is emitted whenever items were added to or removed from list. At position, removed items were removed and added items were added in their place.

Note: If removed != added, the positions of all later items in the model change.

func (*ListModel) Item 

func (list *ListModel) Item(position uint) *coreglib.Object

Item: get the item at position.

If position is greater than the number of items in list, NULL is returned.

NULL is never returned for an index that is smaller than the length of the list.

This function is meant to be used by language bindings in place of g_list_model_get_item().

See also: g_list_model_get_n_items().

The function takes the following parameters:

  • position of the item to fetch.

The function returns the following values:

  • object (optional) at position.

func (*ListModel) ItemType 

func (list *ListModel) ItemType() coreglib.Type

ItemType gets the type of the items in list.

All items returned from g_list_model_get_item() are of the type returned by this function, or a subtype, or if the type is an interface, they are an implementation of that interface.

The item type of a Model can not change during the life of the model.

The function returns the following values:

  • gType of the items contained in list.

func (*ListModel) ItemsChanged 

func (list *ListModel) ItemsChanged(position, removed, added uint)

ItemsChanged emits the Model::items-changed signal on list.

This function should only be called by classes implementing Model. It has to be called after the internal representation of list has been updated, because handlers connected to this signal might query the new state of the list.

Implementations must only make changes to the model (as visible to its consumer) in places that will not cause problems for that consumer. For models that are driven directly by a write API (such as Store), changes can be reported in response to uses of that API. For models that represent remote data, changes should only be made from a fresh mainloop dispatch. It is particularly not permitted to make changes in response to a call to the Model consumer API.

Stated another way: in general, it is assumed that code making a series of accesses to the model via the API, without returning to the mainloop, and without calling other code, will continue to view the same contents of the model.

The function takes the following parameters:

  • position at which list changed.
  • removed: number of items removed.
  • added: number of items added.

func (*ListModel) NItems 

func (list *ListModel) NItems() uint

NItems gets the number of items in list.

Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for position until g_list_model_get_item() returns NULL.

The function returns the following values:

  • guint: number of items in list.

type ListModelInterface added in v0.0.5 

type ListModelInterface struct {
	// contains filtered or unexported fields
}

ListModelInterface: virtual function table for Model.

An instance of this type is always passed by reference.

type ListModeller 

type ListModeller interface {
	coreglib.Objector

	// ItemType gets the type of the items in list.
	ItemType() coreglib.Type
	// NItems gets the number of items in list.
	NItems() uint
	// Item: get the item at position.
	Item(position uint) *coreglib.Object
	// ItemsChanged emits the Model::items-changed signal on list.
	ItemsChanged(position, removed, added uint)

	// Items-changed: this signal is emitted whenever items were added to or
	// removed from list.
	ConnectItemsChanged(func(position, removed, added uint)) coreglib.SignalHandle
}

ListModeller describes ListModel's interface methods.

type ListStore 

type ListStore struct {
	*coreglib.Object

	ListModel
	// contains filtered or unexported fields
}

ListStore: GListStore is a simple implementation of gio.ListModel 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.

func NewListStore 

func NewListStore(itemType coreglib.Type) *ListStore

NewListStore creates a new Store with items of type item_type. item_type must be a subclass of #GObject.

The function takes the following parameters:

  • itemType of items in the list.

The function returns the following values:

  • listStore: new Store.

func (*ListStore) Append 

func (store *ListStore) Append(item *coreglib.Object)

Append appends item to store. item must be of type Store:item-type.

This function takes a ref on item.

Use g_list_store_splice() to append multiple items at the same time efficiently.

The function takes the following parameters:

  • item: new item.

func (*ListStore) Find 

func (store *ListStore) Find(item *coreglib.Object) (uint, bool)

Find looks up the given item in the list store by looping over the items until the first occurrence of item. If item was not found, then position will not be set, and this method will return FALSE.

If you need to compare the two items with a custom comparison function, use g_list_store_find_with_equal_func() with a custom Func instead.

The function takes the following parameters:

  • item: item.

The function returns the following values:

  • position (optional): first position of item, if it was found.
  • ok: whether store contains item. If it was found, position will be set to the position where item occurred for the first time.

func (*ListStore) FindWithEqualFuncFull added in v0.3.0 

func (store *ListStore) FindWithEqualFuncFull(item *coreglib.Object, equalFunc glib.EqualFuncFull) (uint, bool)

FindWithEqualFuncFull: like g_list_store_find_with_equal_func() but with an additional user_data that is passed to equal_func.

item is always passed as second parameter to equal_func.

Since GLib 2.76 it is possible to pass NULL for item.

The function takes the following parameters:

  • item (optional): item.
  • equalFunc: custom equality check function.

The function returns the following values:

  • position (optional): first position of item, if it was found.
  • ok: whether store contains item. If it was found, position will be set to the position where item occurred for the first time.

func (*ListStore) Insert 

func (store *ListStore) Insert(position uint, item *coreglib.Object)

Insert inserts item into store at position. item must be of type Store:item-type or derived from it. position must be smaller than the length of the list, or equal to it to append.

This function takes a ref on item.

Use g_list_store_splice() to insert multiple items at the same time efficiently.

The function takes the following parameters:

  • position at which to insert the new item.
  • item: new item.

func (*ListStore) InsertSorted 

func (store *ListStore) InsertSorted(item *coreglib.Object, compareFunc glib.CompareDataFunc) uint

InsertSorted inserts item into store at a position to be determined by the compare_func.

The list must already be sorted before calling this function or the result is undefined. Usually you would approach this by only ever inserting items by way of this function.

This function takes a ref on item.

The function takes the following parameters:

  • item: new item.
  • compareFunc: pairwise comparison function for sorting.

The function returns the following values:

  • guint: position at which item was inserted.

func (*ListStore) Remove 

func (store *ListStore) Remove(position uint)

Remove removes the item from store that is at position. position must be smaller than the current length of the list.

Use g_list_store_splice() to remove multiple items at the same time efficiently.

The function takes the following parameters:

  • position of the item that is to be removed.

func (*ListStore) RemoveAll 

func (store *ListStore) RemoveAll()

RemoveAll removes all items from store.

func (*ListStore) Sort 

func (store *ListStore) Sort(compareFunc glib.CompareDataFunc)

Sort the items in store according to compare_func.

The function takes the following parameters:

  • compareFunc: pairwise comparison function for sorting.

func (*ListStore) Splice 

func (store *ListStore) Splice(position, nRemovals uint, additions []*coreglib.Object)

Splice changes store by removing n_removals items and adding n_additions items to it. additions must contain n_additions items of type Store:item-type. NULL is not permitted.

This function is more efficient than g_list_store_insert() and g_list_store_remove(), because it only emits Model::items-changed once for the change.

This function takes a ref on each item in additions.

The parameters position and n_removals must be correct (ie: position + n_removals must be less than or equal to the length of the list at the time this function is called).

The function takes the following parameters:

  • position at which to make the change.
  • nRemovals: number of items to remove.
  • additions items to add.

type ListStoreClass added in v0.0.5 

type ListStoreClass struct {
	// contains filtered or unexported fields
}

ListStoreClass: instance of this type is always passed by reference.

type ListStoreOverrides added in v0.0.5 

type ListStoreOverrides struct {
}

ListStoreOverrides contains methods that are overridable.

type LoadableIcon 

type LoadableIcon struct {
	Icon
	// contains filtered or unexported fields
}

LoadableIcon: GLoadableIcon extends the gio.Icon interface and adds the ability to load icons from streams.

LoadableIcon wraps an interface. This means the user can get the underlying type by calling Cast().

func (*LoadableIcon) Load 

func (icon *LoadableIcon) Load(ctx context.Context, size int) (string, InputStreamer, error)

Load loads a loadable icon. For the asynchronous version of this function, see g_loadable_icon_load_async().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • size: integer.

The function returns the following values:

  • typ (optional): location to store the type of the loaded icon, NULL to ignore.
  • inputStream to read the icon from.

func (*LoadableIcon) LoadAsync 

func (icon *LoadableIcon) LoadAsync(ctx context.Context, size int, callback AsyncReadyCallback)

LoadAsync loads an icon asynchronously. To finish this function, see g_loadable_icon_load_finish(). For the synchronous, blocking version of this function, see g_loadable_icon_load().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • size: integer.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*LoadableIcon) LoadFinish 

func (icon *LoadableIcon) LoadFinish(res AsyncResulter) (string, InputStreamer, error)

LoadFinish finishes an asynchronous icon load started in g_loadable_icon_load_async().

The function takes the following parameters:

  • res: Result.

The function returns the following values:

  • typ (optional): location to store the type of the loaded icon, NULL to ignore.
  • inputStream to read the icon from.

type LoadableIconIface added in v0.0.5 

type LoadableIconIface struct {
	// contains filtered or unexported fields
}

LoadableIconIface: interface for icons that can be loaded as a stream.

An instance of this type is always passed by reference.

type LoadableIconner 

type LoadableIconner interface {
	coreglib.Objector

	// Load loads a loadable icon.
	Load(ctx context.Context, size int) (string, InputStreamer, error)
	// LoadAsync loads an icon asynchronously.
	LoadAsync(ctx context.Context, size int, callback AsyncReadyCallback)
	// LoadFinish finishes an asynchronous icon load started in
	// g_loadable_icon_load_async().
	LoadFinish(res AsyncResulter) (string, InputStreamer, error)
}

LoadableIconner describes LoadableIcon's interface methods.

type MemoryInputStream 

type MemoryInputStream struct {
	InputStream

	*coreglib.Object
	PollableInputStream
	Seekable
	// contains filtered or unexported fields
}

MemoryInputStream: GMemoryInputStream is a class for using arbitrary memory chunks as input for GIO streaming input operations.

As of GLib 2.34, GMemoryInputStream implements gio.PollableInputStream.

func NewMemoryInputStream 

func NewMemoryInputStream() *MemoryInputStream

NewMemoryInputStream creates a new empty InputStream.

The function returns the following values:

  • memoryInputStream: new Stream.

func NewMemoryInputStreamFromBytes 

func NewMemoryInputStreamFromBytes(bytes *glib.Bytes) *MemoryInputStream

NewMemoryInputStreamFromBytes creates a new InputStream with data from the given bytes.

The function takes the following parameters:

  • bytes: #GBytes.

The function returns the following values:

  • memoryInputStream: new Stream read from bytes.

func (*MemoryInputStream) AddBytes 

func (stream *MemoryInputStream) AddBytes(bytes *glib.Bytes)

AddBytes appends bytes to data that can be read from the input stream.

The function takes the following parameters:

  • bytes: input data.

type MemoryInputStreamClass added in v0.0.5 

type MemoryInputStreamClass struct {
	// contains filtered or unexported fields
}

MemoryInputStreamClass: instance of this type is always passed by reference.

func (*MemoryInputStreamClass) ParentClass added in v0.0.5 

func (m *MemoryInputStreamClass) ParentClass() *InputStreamClass

type MemoryInputStreamOverrides added in v0.0.5 

type MemoryInputStreamOverrides struct {
}

MemoryInputStreamOverrides contains methods that are overridable.

type MemoryMonitor 

type MemoryMonitor struct {
	Initable
	// contains filtered or unexported fields
}

MemoryMonitor: 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 (https://gitlab.freedesktop.org/hadess/low-memory-monitor/) (API documentation (https://hadess.pages.freedesktop.org/low-memory-monitor/)).

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
  • Call malloc_trim(3) (man:malloc_trim(3)) to return cached heap pages to the kernel (if supported by your libc)

Note that some actions may not always improve system performance, and so should be profiled for your application. malloc_trim(), for example, may make future heap allocations slower (due to releasing cached heap pages back to the kernel).

See gio.MemoryMonitorWarningLevel for details on the various warning levels. 

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 gio.MemoryMonitor::low-memory-warning signal, and unref the GMemoryMonitor itself when exiting.

MemoryMonitor wraps an interface. This means the user can get the underlying type by calling Cast().

func BaseMemoryMonitor 

func BaseMemoryMonitor(obj MemoryMonitorrer) *MemoryMonitor

BaseMemoryMonitor returns the underlying base object.

func MemoryMonitorDupDefault 

func MemoryMonitorDupDefault() *MemoryMonitor

MemoryMonitorDupDefault gets a reference to the default Monitor for the system.

The function returns the following values:

  • memoryMonitor: new reference to the default Monitor.

func (*MemoryMonitor) ConnectLowMemoryWarning 

func (v *MemoryMonitor) ConnectLowMemoryWarning(f func(level MemoryMonitorWarningLevel)) coreglib.SignalHandle

ConnectLowMemoryWarning is emitted when the system is running low on free memory. The signal handler should then take the appropriate action depending on the warning level. See the MonitorWarningLevel documentation for details.

type MemoryMonitorInterface added in v0.0.5 

type MemoryMonitorInterface struct {
	// contains filtered or unexported fields
}

MemoryMonitorInterface: virtual function table for Monitor.

An instance of this type is always passed by reference.

type MemoryMonitorWarningLevel 

type MemoryMonitorWarningLevel C.gint

MemoryMonitorWarningLevel: memory availability warning levels.

Note that because new values might be added, it is recommended that applications check MonitorWarningLevel as ranges, for example: 

if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW)
  drop_caches ();.

const (
	// MemoryMonitorWarningLevelLow: memory on the device is low, processes
	// should free up unneeded resources (for example, in-memory caches) so they
	// can be used elsewhere.
	MemoryMonitorWarningLevelLow MemoryMonitorWarningLevel = 50
	// MemoryMonitorWarningLevelMedium: same as
	// G_MEMORY_MONITOR_WARNING_LEVEL_LOW but the device has even less free
	// memory, so processes should try harder to free up unneeded resources.
	// If your process does not need to stay running, it is a good time for it
	// to quit.
	MemoryMonitorWarningLevelMedium MemoryMonitorWarningLevel = 100
	// MemoryMonitorWarningLevelCritical: system will soon start terminating
	// processes to reclaim memory, including background processes.
	MemoryMonitorWarningLevelCritical MemoryMonitorWarningLevel = 255
)

func (MemoryMonitorWarningLevel) String 

func (m MemoryMonitorWarningLevel) String() string

String returns the name in string for MemoryMonitorWarningLevel.

type MemoryMonitorrer 

type MemoryMonitorrer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

MemoryMonitorrer describes MemoryMonitor's interface methods.

type MemoryOutputStream 

type MemoryOutputStream struct {
	OutputStream

	*coreglib.Object
	PollableOutputStream
	Seekable
	// contains filtered or unexported fields
}

MemoryOutputStream: GMemoryOutputStream is a class for using arbitrary memory chunks as output for GIO streaming output operations.

As of GLib 2.34, GMemoryOutputStream trivially implements gio.PollableOutputStream: it always polls as ready.

func NewMemoryOutputStreamResizable 

func NewMemoryOutputStreamResizable() *MemoryOutputStream

NewMemoryOutputStreamResizable creates a new OutputStream, using g_realloc() and g_free() for memory allocation.

func (*MemoryOutputStream) Data 

func (ostream *MemoryOutputStream) Data() unsafe.Pointer

Data gets any loaded data from the ostream.

Note that the returned pointer may become invalid on the next write or truncate operation on the stream.

The function returns the following values:

  • gpointer (optional): pointer to the stream's data, or NULL if the data has been stolen.

func (*MemoryOutputStream) DataSize 

func (ostream *MemoryOutputStream) DataSize() uint

DataSize returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away.

The function returns the following values:

  • gsize: number of bytes written to the stream.

func (*MemoryOutputStream) Size 

func (ostream *MemoryOutputStream) Size() uint

Size gets the size of the currently allocated data area (available from g_memory_output_stream_get_data()).

You probably don't want to use this function on resizable streams. See g_memory_output_stream_get_data_size() instead. For resizable streams the size returned by this function is an implementation detail and may be change at any time in response to operations on the stream.

If the stream is fixed-sized (ie: no realloc was passed to g_memory_output_stream_new()) then this is the maximum size of the stream and further writes will return G_IO_ERROR_NO_SPACE.

In any case, if you want the number of bytes currently written to the stream, use g_memory_output_stream_get_data_size().

The function returns the following values:

  • gsize: number of bytes allocated for the data buffer.

func (*MemoryOutputStream) StealAsBytes 

func (ostream *MemoryOutputStream) StealAsBytes() *glib.Bytes

StealAsBytes returns data from the ostream as a #GBytes. ostream must be closed before calling this function.

The function returns the following values:

  • bytes stream's data.

func (*MemoryOutputStream) StealData 

func (ostream *MemoryOutputStream) StealData() unsafe.Pointer

StealData gets any loaded data from the ostream. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in ostream's OutputStream:destroy-function property.

ostream must be closed before calling this function.

The function returns the following values:

  • gpointer (optional) stream's data, or NULL if it has previously been stolen.

type MemoryOutputStreamClass added in v0.0.5 

type MemoryOutputStreamClass struct {
	// contains filtered or unexported fields
}

MemoryOutputStreamClass: instance of this type is always passed by reference.

func (*MemoryOutputStreamClass) ParentClass added in v0.0.5 

func (m *MemoryOutputStreamClass) ParentClass() *OutputStreamClass

type MemoryOutputStreamOverrides added in v0.0.5 

type MemoryOutputStreamOverrides struct {
}

MemoryOutputStreamOverrides contains methods that are overridable. 

type Menu struct {
	MenuModel
	// contains filtered or unexported fields
}

Menu: GMenu is a simple implementation of gio.MenuModel. You populate a GMenu by adding gio.MenuItem instances to it.

There are some convenience functions to allow you to directly add items (avoiding gio.MenuItem) for the common cases. To add a regular item, use gio.Menu.Insert(). To add a section, use gio.Menu.InsertSection(). To add a submenu, use gio.Menu.InsertSubmenu().

func NewMenu 

func NewMenu() *Menu

NewMenu creates a new #GMenu.

The new menu has no items.

The function returns the following values:

  • menu: new #GMenu.
func (menu *Menu) Append(label, detailedAction string)

Append: convenience function for appending a normal menu item to the end of menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • detailedAction (optional): detailed action string, or NULL.
func (menu *Menu) AppendItem(item *MenuItem)

AppendItem appends item to the end of menu.

See g_menu_insert_item() for more information.

The function takes the following parameters:

  • item to append.
func (menu *Menu) AppendSection(label string, section MenuModeller)

AppendSection: convenience function for appending a section menu item to the end of menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • section with the items of the section.
func (menu *Menu) AppendSubmenu(label string, submenu MenuModeller)

AppendSubmenu: convenience function for appending a submenu menu item to the end of menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • submenu with the items of the submenu.
func (menu *Menu) Freeze()

Freeze marks menu as frozen.

After the menu is frozen, it is an error to attempt to make any changes to it. In effect this means that the #GMenu API must no longer be used.

This function causes g_menu_model_is_mutable() to begin returning FALSE, which has some positive performance implications. 

func (menu *Menu) Insert(position int, label, detailedAction string)

Insert: convenience function for inserting a normal menu item into menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • position at which to insert the item.
  • label (optional): section label, or NULL.
  • detailedAction (optional): detailed action string, or NULL.
func (menu *Menu) InsertItem(position int, item *MenuItem)

InsertItem inserts item into menu.

The "insertion" is actually done by copying all of the attribute and link values of item and using them to form a new item within menu. As such, item itself is not really inserted, but rather, a menu item that is exactly the same as the one presently described by item.

This means that item is essentially useless after the insertion occurs. Any changes you make to it are ignored unless it is inserted again (at which point its updated values will be copied).

You should probably just free item once you're done.

There are many convenience functions to take care of common cases. See g_menu_insert(), g_menu_insert_section() and g_menu_insert_submenu() as well as "prepend" and "append" variants of each of these functions.

The function takes the following parameters:

  • position at which to insert the item.
  • item to insert.
func (menu *Menu) InsertSection(position int, label string, section MenuModeller)

InsertSection: convenience function for inserting a section menu item into menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • position at which to insert the item.
  • label (optional): section label, or NULL.
  • section with the items of the section.
func (menu *Menu) InsertSubmenu(position int, label string, submenu MenuModeller)

InsertSubmenu: convenience function for inserting a submenu menu item into menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • position at which to insert the item.
  • label (optional): section label, or NULL.
  • submenu with the items of the submenu.
func (menu *Menu) Prepend(label, detailedAction string)

Prepend: convenience function for prepending a normal menu item to the start of menu. Combine g_menu_item_new() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • detailedAction (optional): detailed action string, or NULL.
func (menu *Menu) PrependItem(item *MenuItem)

PrependItem prepends item to the start of menu.

See g_menu_insert_item() for more information.

The function takes the following parameters:

  • item to prepend.
func (menu *Menu) PrependSection(label string, section MenuModeller)

PrependSection: convenience function for prepending a section menu item to the start of menu. Combine g_menu_item_new_section() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • section with the items of the section.
func (menu *Menu) PrependSubmenu(label string, submenu MenuModeller)

PrependSubmenu: convenience function for prepending a submenu menu item to the start of menu. Combine g_menu_item_new_submenu() and g_menu_insert_item() for a more flexible alternative.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • submenu with the items of the submenu.
func (menu *Menu) Remove(position int)

Remove removes an item from the menu.

position gives the index of the item to remove.

It is an error if position is not in range the range from 0 to one less than the number of items in the menu.

It is not possible to remove items by identity since items are added to the menu simply by copying their links and attributes (ie: identity of the item itself is not preserved).

The function takes the following parameters:

  • position of the item to remove.
func (menu *Menu) RemoveAll()

RemoveAll removes all items in the menu. 

type MenuAttributeIter struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

MenuAttributeIter is an opaque structure type. You must access it using the functions below.

func BaseMenuAttributeIter 

func BaseMenuAttributeIter(obj MenuAttributeIterer) *MenuAttributeIter

BaseMenuAttributeIter returns the underlying base object. 

func (iter *MenuAttributeIter) GetNext() (string, *glib.Variant, bool)

GetNext: this function combines g_menu_attribute_iter_next() with g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().

First the iterator is advanced to the next (possibly first) attribute. If that fails, then FALSE is returned and there are no other effects.

If successful, name and value are set to the name and value of the attribute that has just been advanced to. At this point, g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value() will return the same values again.

The value returned in name remains valid for as long as the iterator remains at the current position. The value returned in value must be unreffed using g_variant_unref() when it is no longer in use.

The function returns the following values:

  • outName (optional): type of the attribute.
  • value (optional): attribute value.
  • ok: TRUE on success, or FALSE if there is no additional attribute.
func (iter *MenuAttributeIter) Name() string

Name gets the name of the attribute at the current iterator position, as a string.

The iterator is not advanced.

The function returns the following values:

  • utf8: name of the attribute.
func (iter *MenuAttributeIter) Next() bool

Next attempts to advance the iterator to the next (possibly first) attribute.

TRUE is returned on success, or FALSE if there are no more attributes.

You must call this function when you first acquire the iterator to advance it to the first attribute (and determine if the first attribute exists at all).

The function returns the following values:

  • ok: TRUE on success, or FALSE when there are no more attributes.
func (iter *MenuAttributeIter) Value() *glib.Variant

Value gets the value of the attribute at the current iterator position.

The iterator is not advanced.

The function returns the following values:

  • variant: value of the current attribute.
type MenuAttributeIterClass struct {
	// contains filtered or unexported fields
}

MenuAttributeIterClass: instance of this type is always passed by reference. 

type MenuAttributeIterOverrides struct {
	// Next: this function combines g_menu_attribute_iter_next() with
	// g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
	//
	// First the iterator is advanced to the next (possibly first) attribute.
	// If that fails, then FALSE is returned and there are no other effects.
	//
	// If successful, name and value are set to the name and value of
	// the attribute that has just been advanced to. At this point,
	// g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value()
	// will return the same values again.
	//
	// The value returned in name remains valid for as long as the iterator
	// remains at the current position. The value returned in value must be
	// unreffed using g_variant_unref() when it is no longer in use.
	//
	// The function returns the following values:
	//
	//   - outName (optional): type of the attribute.
	//   - value (optional): attribute value.
	//   - ok: TRUE on success, or FALSE if there is no additional attribute.
	Next func() (string, *glib.Variant, bool)
}

MenuAttributeIterOverrides contains methods that are overridable. 

type MenuAttributeIterer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

MenuAttributeIterer describes types inherited from class MenuAttributeIter.

To get the original type, the caller must assert this to an interface or another type. 

type MenuItem struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

MenuItem is an opaque structure type. You must access it using the functions below.

func NewMenuItem 

func NewMenuItem(label, detailedAction string) *MenuItem

NewMenuItem creates a new Item.

If label is non-NULL it is used to set the "label" attribute of the new item.

If detailed_action is non-NULL it is used to set the "action" and possibly the "target" attribute of the new item. See g_menu_item_set_detailed_action() for more information.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • detailedAction (optional): detailed action string, or NULL.

The function returns the following values:

  • menuItem: new Item.

func NewMenuItemFromModel 

func NewMenuItemFromModel(model MenuModeller, itemIndex int) *MenuItem

NewMenuItemFromModel creates a Item as an exact copy of an existing menu item in a Model.

item_index must be valid (ie: be sure to call g_menu_model_get_n_items() first).

The function takes the following parameters:

  • model: Model.
  • itemIndex: index of an item in model.

The function returns the following values:

  • menuItem: new Item.

func NewMenuItemSection 

func NewMenuItemSection(label string, section MenuModeller) *MenuItem

NewMenuItemSection creates a new Item representing a section.

This is a convenience API around g_menu_item_new() and g_menu_item_set_section().

The effect of having one menu appear as a section of another is exactly as it sounds: the items from section become a direct part of the menu that menu_item is added to.

Visual separation is typically displayed between two non-empty sections. If label is non-NULL then it will be encorporated into this visual indication. This allows for labeled subsections of a menu.

As a simple example, consider a typical "Edit" menu from a simple program. It probably contains an "Undo" and "Redo" item, followed by a separator, followed by "Cut", "Copy" and "Paste".

This would be accomplished by creating three #GMenu instances. The first would be populated with the "Undo" and "Redo" items, and the second with the "Cut", "Copy" and "Paste" items. The first and second menus would then be added as submenus of the third. In XML format, this would look something like the following: 

<menu id='edit-menu'>
  <section>
    <item label='Undo'/>
    <item label='Redo'/>
  </section>
  <section>
    <item label='Cut'/>
    <item label='Copy'/>
    <item label='Paste'/>
  </section>
</menu>

The following example is exactly equivalent. It is more illustrative of the exact relationship between the menus and items (keeping in mind that the 'link' element defines a new menu that is linked to the containing one). The style of the second example is more verbose and difficult to read (and therefore not recommended except for the purpose of understanding what is really going on). 

<menu id='edit-menu'>
  <item>
    <link name='section'>
      <item label='Undo'/>
      <item label='Redo'/>
    </link>
  </item>
  <item>
    <link name='section'>
      <item label='Cut'/>
      <item label='Copy'/>
      <item label='Paste'/>
    </link>
  </item>
</menu>.

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • section with the items of the section.

The function returns the following values:

  • menuItem: new Item.

func NewMenuItemSubmenu 

func NewMenuItemSubmenu(label string, submenu MenuModeller) *MenuItem

NewMenuItemSubmenu creates a new Item representing a submenu.

This is a convenience API around g_menu_item_new() and g_menu_item_set_submenu().

The function takes the following parameters:

  • label (optional): section label, or NULL.
  • submenu with the items of the submenu.

The function returns the following values:

  • menuItem: new Item.
func (menuItem *MenuItem) AttributeValue(attribute string, expectedType *glib.VariantType) *glib.Variant

AttributeValue queries the named attribute on menu_item.

If expected_type is specified and the attribute does not have this type, NULL is returned. NULL is also returned if the attribute simply does not exist.

The function takes the following parameters:

  • attribute name to query.
  • expectedType (optional): expected type of the attribute.

The function returns the following values:

  • variant (optional): attribute value, or NULL.
func (menuItem *MenuItem) Link(link string) MenuModeller

Link queries the named link on menu_item.

The function takes the following parameters:

  • link name to query.

The function returns the following values:

  • menuModel (optional): link, or NULL.
func (menuItem *MenuItem) SetActionAndTargetValue(action string, targetValue *glib.Variant)

SetActionAndTargetValue sets or unsets the "action" and "target" attributes of menu_item.

If action is NULL then both the "action" and "target" attributes are unset (and target_value is ignored).

If action is non-NULL then the "action" attribute is set. The "target" attribute is then set to the value of target_value if it is non-NULL or unset otherwise.

Normal menu items (ie: not submenu, section or other custom item types) are expected to have the "action" attribute set to identify the action that they are associated with. The state type of the action help to determine the disposition of the menu item. See #GAction and Group for an overview of actions.

In general, clicking on the menu item will result in activation of the named action with the "target" attribute given as the parameter to the action invocation. If the "target" attribute is not set then the action is invoked with no parameter.

If the action has no state then the menu item is usually drawn as a plain menu item (ie: with no additional decoration).

If the action has a boolean state then the menu item is usually drawn as a toggle menu item (ie: with a checkmark or equivalent indication). The item should be marked as 'toggled' or 'checked' when the boolean state is TRUE.

If the action has a string state then the menu item is usually drawn as a radio menu item (ie: with a radio bullet or equivalent indication). The item should be marked as 'selected' when the string state is equal to the value of the target property.

See g_menu_item_set_action_and_target() or g_menu_item_set_detailed_action() for two equivalent calls that are probably more convenient for most uses.

The function takes the following parameters:

  • action (optional): name of the action for this item.
  • targetValue (optional) to use as the action target.
func (menuItem *MenuItem) SetAttributeValue(attribute string, value *glib.Variant)

SetAttributeValue sets or unsets an attribute on menu_item.

The attribute to set or unset is specified by attribute. This can be one of the standard attribute names G_MENU_ATTRIBUTE_LABEL, G_MENU_ATTRIBUTE_ACTION, G_MENU_ATTRIBUTE_TARGET, or a custom attribute name. Attribute 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.

must consist only of lowercase ASCII characters, digits and '-'.

If value is non-NULL then it is used as the new value for the attribute. If value is NULL then the attribute is unset. If the value #GVariant is floating, it is consumed.

See also g_menu_item_set_attribute() for a more convenient way to do the same.

The function takes the following parameters:

  • attribute to set.
  • value (optional) to use as the value, or NULL.
func (menuItem *MenuItem) SetDetailedAction(detailedAction string)

SetDetailedAction sets the "action" and possibly the "target" attribute of menu_item.

The format of detailed_action is the same format parsed by g_action_parse_detailed_name().

See g_menu_item_set_action_and_target() or g_menu_item_set_action_and_target_value() for more flexible (but slightly less convenient) alternatives.

See also g_menu_item_set_action_and_target_value() for a description of the semantics of the action and target attributes.

The function takes the following parameters:

  • detailedAction: "detailed" action string.
func (menuItem *MenuItem) SetIcon(icon Iconner)

SetIcon sets (or unsets) the icon on menu_item.

This call is the same as calling g_icon_serialize() and using the result as the value to g_menu_item_set_attribute_value() for G_MENU_ATTRIBUTE_ICON.

This API is only intended for use with "noun" menu items; things like bookmarks or applications in an "Open With" menu. Don't use it on menu items corresponding to verbs (eg: stock icons for 'Save' or 'Quit').

If icon is NULL then the icon is unset.

The function takes the following parameters:

  • icon or NULL.
func (menuItem *MenuItem) SetLabel(label string)

SetLabel sets or unsets the "label" attribute of menu_item.

If label is non-NULL it is used as the label for the menu item. If it is NULL then the label attribute is unset.

The function takes the following parameters:

  • label (optional) to set, or NULL to unset.
func (menuItem *MenuItem) SetLink(link string, model MenuModeller)

SetLink creates a link from menu_item to model if non-NULL, or unsets it.

Links are used to establish a relationship between a particular menu item and another menu. For example, G_MENU_LINK_SUBMENU is used to associate a submenu with a particular menu item, and G_MENU_LINK_SECTION is used to create a section. Other types of link can be used, but there is no guarantee that clients will be able to make sense of them. Link types 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.

The function takes the following parameters:

  • link: type of link to establish or unset.
  • model (optional) to link to (or NULL to unset).
func (menuItem *MenuItem) SetSection(section MenuModeller)

SetSection sets or unsets the "section" link of menu_item to section.

The effect of having one menu appear as a section of another is exactly as it sounds: the items from section become a direct part of the menu that menu_item is added to. See g_menu_item_new_section() for more information about what it means for a menu item to be a section.

The function takes the following parameters:

  • section (optional) or NULL.
func (menuItem *MenuItem) SetSubmenu(submenu MenuModeller)

SetSubmenu sets or unsets the "submenu" link of menu_item to submenu.

If submenu is non-NULL, it is linked to. If it is NULL then the link is unset.

The effect of having one menu appear as a submenu of another is exactly as it sounds.

The function takes the following parameters:

  • submenu (optional) or NULL.
type MenuLinkIter struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

MenuLinkIter is an opaque structure type. You must access it using the functions below.

func BaseMenuLinkIter 

func BaseMenuLinkIter(obj MenuLinkIterer) *MenuLinkIter

BaseMenuLinkIter returns the underlying base object. 

func (iter *MenuLinkIter) GetNext() (string, MenuModeller, bool)

GetNext: this function combines g_menu_link_iter_next() with g_menu_link_iter_get_name() and g_menu_link_iter_get_value().

First the iterator is advanced to the next (possibly first) link. If that fails, then FALSE is returned and there are no other effects.

If successful, out_link and value are set to the name and Model of the link that has just been advanced to. At this point, g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return the same values again.

The value returned in out_link remains valid for as long as the iterator remains at the current position. The value returned in value must be unreffed using g_object_unref() when it is no longer in use.

The function returns the following values:

  • outLink (optional): name of the link.
  • value (optional): linked Model.
  • ok: TRUE on success, or FALSE if there is no additional link.
func (iter *MenuLinkIter) Name() string

Name gets the name of the link at the current iterator position.

The iterator is not advanced.

The function returns the following values:

  • utf8: type of the link.
func (iter *MenuLinkIter) Next() bool

Next attempts to advance the iterator to the next (possibly first) link.

TRUE is returned on success, or FALSE if there are no more links.

You must call this function when you first acquire the iterator to advance it to the first link (and determine if the first link exists at all).

The function returns the following values:

  • ok: TRUE on success, or FALSE when there are no more links.
func (iter *MenuLinkIter) Value() MenuModeller

Value gets the linked Model at the current iterator position.

The iterator is not advanced.

The function returns the following values:

  • menuModel that is linked to.
type MenuLinkIterClass struct {
	// contains filtered or unexported fields
}

MenuLinkIterClass: instance of this type is always passed by reference. 

type MenuLinkIterOverrides struct {
	// Next: this function combines g_menu_link_iter_next() with
	// g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
	//
	// First the iterator is advanced to the next (possibly first) link.
	// If that fails, then FALSE is returned and there are no other effects.
	//
	// If successful, out_link and value are set to the name and Model
	// of the link that has just been advanced to. At this point,
	// g_menu_link_iter_get_name() and g_menu_link_iter_get_value() will return
	// the same values again.
	//
	// The value returned in out_link remains valid for as long as the iterator
	// remains at the current position. The value returned in value must be
	// unreffed using g_object_unref() when it is no longer in use.
	//
	// The function returns the following values:
	//
	//   - outLink (optional): name of the link.
	//   - value (optional): linked Model.
	//   - ok: TRUE on success, or FALSE if there is no additional link.
	Next func() (string, MenuModeller, bool)
}

MenuLinkIterOverrides contains methods that are overridable. 

type MenuLinkIterer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

MenuLinkIterer describes types inherited from class MenuLinkIter.

To get the original type, the caller must assert this to an interface or another type. 

type MenuModel struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

MenuModel: 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 by GMenuModels. Menus themselves do not define their own roles. Rather, the role of a particular GMenuModel 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

! (menu-example.png)

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 (#a-menu-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

! (menu-model.png)

Notice that the separators visible in the example (#an-example-menu) appear nowhere in the menu model (#a-menu-example). 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 action group exporter and the menu model exporter do for gio.ActionGroup and gio.MenuModel. The client-side counterparts to make use of the exported information are gio.DBusActionGroup and gio.DBusMenuModel.

The API of GMenuModel is very generic, with iterators for the attributes and links of an item, see gio.MenuModel.IterateItemAttributes() and gio.MenuModel.IterateItemLinks(). 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 and G_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 the G_MENU_ATTRIBUTE_ACTION attribute. An action ID uniquely identifies an action in an action group. Which action group(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 a GtkApplication (https://docs.gtk.org/gtk4/class.Application.html), 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.

func BaseMenuModel 

func BaseMenuModel(obj MenuModeller) *MenuModel

BaseMenuModel returns the underlying base object. 

func (model *MenuModel) ConnectItemsChanged(f func(position, removed, added int)) coreglib.SignalHandle

ConnectItemsChanged is emitted when a change has occurred to the menu.

The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added back in the same location). This signal is capable of describing both of those changes (at the same time).

The signal means that starting at the index position, removed items were removed and added items were added in their place. If removed is zero then only items were added. If added is zero then only items were removed.

As an example, if the menu contains items a, b, c, d (in that order) and the signal (2, 1, 3) occurs then the new composition of the menu will be a, b, _, _, _, d (with each _ representing some new item).

Signal handlers may query the model (particularly the added items) and expect to see the results of the modification that is being reported. The signal is emitted after the modification. 

func (model *MenuModel) IsMutable() bool

IsMutable queries if model is mutable.

An immutable Model will never emit the Model::items-changed signal. Consumers of the model may make optimisations accordingly.

The function returns the following values:

  • ok: TRUE if the model is mutable (ie: "items-changed" may be emitted).
func (model *MenuModel) ItemAttributeValue(itemIndex int, attribute string, expectedType *glib.VariantType) *glib.Variant

ItemAttributeValue queries the item at position item_index in model for the attribute specified by attribute.

If expected_type is non-NULL then it specifies the expected type of the attribute. If it is NULL then any type will be accepted.

If the attribute exists and matches expected_type (or if the expected type is unspecified) then the value is returned.

If the attribute does not exist, or does not match the expected type then NULL is returned.

The function takes the following parameters:

  • itemIndex: index of the item.
  • attribute to query.
  • expectedType (optional): expected type of the attribute, or NULL.

The function returns the following values:

  • variant (optional): value of the attribute.
func (model *MenuModel) ItemLink(itemIndex int, link string) MenuModeller

ItemLink queries the item at position item_index in model for the link specified by link.

If the link exists, the linked Model is returned. If the link does not exist, NULL is returned.

The function takes the following parameters:

  • itemIndex: index of the item.
  • link to query.

The function returns the following values:

  • menuModel (optional): linked Model, or NULL.
func (model *MenuModel) ItemsChanged(position, removed, added int)

ItemsChanged requests emission of the Model::items-changed signal on model.

This function should never be called except by Model subclasses. Any other calls to this function will very likely lead to a violation of the interface of the model.

The implementation should update its internal representation of the menu before emitting the signal. The implementation should further expect to receive queries about the new state of the menu (and particularly added menu items) while signal handlers are running.

The implementation must dispatch this call directly from a mainloop entry and not in response to calls -- particularly those from the Model API. Said another way: the menu must not change while user code is running without returning to the mainloop.

The function takes the following parameters:

  • position of the change.
  • removed: number of items removed.
  • added: number of items added.
func (model *MenuModel) IterateItemAttributes(itemIndex int) MenuAttributeIterer

IterateItemAttributes creates a AttributeIter to iterate over the attributes of the item at position item_index in model.

You must free the iterator with g_object_unref() when you are done.

The function takes the following parameters:

  • itemIndex: index of the item.

The function returns the following values:

  • menuAttributeIter: new AttributeIter.
func (model *MenuModel) IterateItemLinks(itemIndex int) MenuLinkIterer

IterateItemLinks creates a LinkIter to iterate over the links of the item at position item_index in model.

You must free the iterator with g_object_unref() when you are done.

The function takes the following parameters:

  • itemIndex: index of the item.

The function returns the following values:

  • menuLinkIter: new LinkIter.
func (model *MenuModel) NItems() int

NItems: query the number of items in model.

The function returns the following values:

  • gint: number of items.
type MenuModelClass struct {
	// contains filtered or unexported fields
}

MenuModelClass: instance of this type is always passed by reference. 

type MenuModelOverrides struct {
	// ItemAttributeValue queries the item at position item_index in model for
	// the attribute specified by attribute.
	//
	// If expected_type is non-NULL then it specifies the expected type of the
	// attribute. If it is NULL then any type will be accepted.
	//
	// If the attribute exists and matches expected_type (or if the expected
	// type is unspecified) then the value is returned.
	//
	// If the attribute does not exist, or does not match the expected type then
	// NULL is returned.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex: index of the item.
	//   - attribute to query.
	//   - expectedType (optional): expected type of the attribute, or NULL.
	//
	// The function returns the following values:
	//
	//   - variant (optional): value of the attribute.
	ItemAttributeValue func(itemIndex int, attribute string, expectedType *glib.VariantType) *glib.Variant
	// ItemAttributes gets all the attributes associated with the item in the
	// menu model.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex to query.
	//
	// The function returns the following values:
	//
	//   - attributes attributes on the item.
	ItemAttributes func(itemIndex int) map[string]*glib.Variant
	// ItemLink queries the item at position item_index in model for the link
	// specified by link.
	//
	// If the link exists, the linked Model is returned. If the link does not
	// exist, NULL is returned.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex: index of the item.
	//   - link to query.
	//
	// The function returns the following values:
	//
	//   - menuModel (optional): linked Model, or NULL.
	ItemLink func(itemIndex int, link string) MenuModeller
	// ItemLinks gets all the links associated with the item in the menu model.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex to query.
	//
	// The function returns the following values:
	//
	//   - links links from the item.
	ItemLinks func(itemIndex int) map[string]MenuModeller
	// NItems: query the number of items in model.
	//
	// The function returns the following values:
	//
	//   - gint: number of items.
	NItems func() int
	// IsMutable queries if model is mutable.
	//
	// An immutable Model will never emit the Model::items-changed signal.
	// Consumers of the model may make optimisations accordingly.
	//
	// The function returns the following values:
	//
	//   - ok: TRUE if the model is mutable (ie: "items-changed" may be
	//     emitted).
	IsMutable func() bool
	// IterateItemAttributes creates a AttributeIter to iterate over the
	// attributes of the item at position item_index in model.
	//
	// You must free the iterator with g_object_unref() when you are done.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex: index of the item.
	//
	// The function returns the following values:
	//
	//   - menuAttributeIter: new AttributeIter.
	IterateItemAttributes func(itemIndex int) MenuAttributeIterer
	// IterateItemLinks creates a LinkIter to iterate over the links of the item
	// at position item_index in model.
	//
	// You must free the iterator with g_object_unref() when you are done.
	//
	// The function takes the following parameters:
	//
	//   - itemIndex: index of the item.
	//
	// The function returns the following values:
	//
	//   - menuLinkIter: new LinkIter.
	IterateItemLinks func(itemIndex int) MenuLinkIterer
}

MenuModelOverrides contains methods that are overridable. 

type MenuModeller interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

MenuModeller describes types inherited from class MenuModel.

To get the original type, the caller must assert this to an interface or another type.

type Mount 

type Mount struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Mount: GMount interface represents user-visible mounts. Note, when porting from GnomeVFS (migrating-gnome-vfs.html), GMount is the moral equivalent of GnomeVFSVolume.

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 GMount instance is an asynchronous operation. For more information about asynchronous operations, see gio.AsyncResult and gio.Task. To unmount a GMount instance, first call gio.Mount.UnmountWithOperation() with (at least) the GMount instance and a gio.AsyncReadyCallback. The callback will be fired when the operation has resolved (either with success or failure), and a gio.AsyncResult structure will be passed to the callback. That callback should then call gio.Mount.UnmountWithOperationFinish() with the GMount and the gio.AsyncResult data to see if the operation was completed successfully. If an error is present when gio.Mount.UnmountWithOperationFinish() is called, then it will be filled with any error information.

Mount wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Mount) CanEject 

func (mount *Mount) CanEject() bool

CanEject checks if mount can be ejected.

The function returns the following values:

  • ok: TRUE if the mount can be ejected.

func (*Mount) CanUnmount 

func (mount *Mount) CanUnmount() bool

CanUnmount checks if mount can be unmounted.

The function returns the following values:

  • ok: TRUE if the mount can be unmounted.

func (*Mount) ConnectChanged 

func (mount *Mount) ConnectChanged(f func()) coreglib.SignalHandle

ConnectChanged is emitted when the mount has been changed.

func (*Mount) ConnectPreUnmount 

func (mount *Mount) ConnectPreUnmount(f func()) coreglib.SignalHandle

ConnectPreUnmount: this signal may be emitted when the #GMount is about to be unmounted.

This signal depends on the backend and is only emitted if GIO was used to unmount.

func (*Mount) ConnectUnmounted 

func (mount *Mount) ConnectUnmounted(f func()) coreglib.SignalHandle

ConnectUnmounted: this signal is emitted when the #GMount have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized.

func (*Mount) DefaultLocation 

func (mount *Mount) DefaultLocation() *File

DefaultLocation gets the default location of mount. The default location of the given mount is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume).

The function returns the following values:

  • file: #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Mount) Drive 

func (mount *Mount) Drive() *Drive

Drive gets the drive for the mount.

This is a convenience method for getting the #GVolume and then using that object to get the #GDrive.

The function returns the following values:

  • drive (optional) or NULL if mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Mount) Eject deprecated 

func (mount *Mount) Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

Eject ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_finish() with the mount and Result data returned in the callback.

Deprecated: Use g_mount_eject_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • callback (optional) or NULL.

func (*Mount) EjectFinish deprecated 

func (mount *Mount) EjectFinish(result AsyncResulter) error

EjectFinish finishes ejecting a mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

Deprecated: Use g_mount_eject_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*Mount) EjectWithOperation 

func (mount *Mount) EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

EjectWithOperation ejects a mount. This is an asynchronous operation, and is finished by calling g_mount_eject_with_operation_finish() with the mount and Result data returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Mount) EjectWithOperationFinish 

func (mount *Mount) EjectWithOperationFinish(result AsyncResulter) error

EjectWithOperationFinish finishes ejecting a mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*Mount) GuessContentType 

func (mount *Mount) GuessContentType(ctx context.Context, forceRescan bool, callback AsyncReadyCallback)

GuessContentType tries to guess the type of content stored on mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the shared-mime-info (http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types.

This is an asynchronous operation (see g_mount_guess_content_type_sync() for the synchronous version), and is finished by calling g_mount_guess_content_type_finish() with the mount and Result data returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • forceRescan: whether to force a rescan of the content. Otherwise a cached result will be used if available.
  • callback (optional): ReadyCallback.

func (*Mount) GuessContentTypeFinish 

func (mount *Mount) GuessContentTypeFinish(result AsyncResulter) ([]string, error)

GuessContentTypeFinish finishes guessing content types of mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned. In particular, you may get an G_IO_ERROR_NOT_SUPPORTED if the mount does not support content guessing.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • utf8s: NULL-terminated array of content types or NULL on error. Caller should free this array with g_strfreev() when done with it.

func (*Mount) GuessContentTypeSync 

func (mount *Mount) GuessContentTypeSync(ctx context.Context, forceRescan bool) ([]string, error)

GuessContentTypeSync tries to guess the type of content stored on mount. Returns one or more textual identifiers of well-known content types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory cards. See the shared-mime-info (http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec) specification for more on x-content types.

This is a synchronous operation and as such may block doing IO; see g_mount_guess_content_type() for the asynchronous version.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • forceRescan: whether to force a rescan of the content. Otherwise a cached result will be used if available.

The function returns the following values:

  • utf8s: NULL-terminated array of content types or NULL on error. Caller should free this array with g_strfreev() when done with it.

func (*Mount) Icon 

func (mount *Mount) Icon() *Icon

Icon gets the icon for mount.

The function returns the following values:

  • icon: #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Mount) IsShadowed 

func (mount *Mount) IsShadowed() bool

IsShadowed determines if mount is shadowed. Applications or libraries should avoid displaying mount in the user interface if it is shadowed.

A mount is said to be shadowed if there exists one or more user visible objects (currently #GMount objects) with a root that is inside the root of mount.

One application of shadow mounts is when exposing a single file system that is used to address several logical volumes. In this situation, a Monitor implementation would create two #GVolume objects (for example, one for the camera functionality of the device and one for a SD card reader on the device) with activation URIs gphoto2://[usb:001,002]/store1/ and gphoto2://[usb:001,002]/store2/. When the underlying mount (with root gphoto2://[usb:001,002]/) is mounted, said Monitor implementation would create two #GMount objects (each with their root matching the corresponding volume activation root) that would shadow the original mount.

The proxy monitor in GVfs 2.26 and later, automatically creates and manage shadow mounts (and shadows the underlying mount) if the activation root on a #GVolume is set.

The function returns the following values:

  • ok: TRUE if mount is shadowed.

func (*Mount) Name 

func (mount *Mount) Name() string

Name gets the name of mount.

The function returns the following values:

  • utf8: name for the given mount. The returned string should be freed with g_free() when no longer needed.

func (*Mount) Remount 

func (mount *Mount) Remount(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

Remount remounts a mount. This is an asynchronous operation, and is finished by calling g_mount_remount_finish() with the mount and Results data returned in the callback.

Remounting is useful when some setting affecting the operation of the volume has been changed, as these may need a remount to take affect. While this is semantically equivalent with unmounting and then remounting not all backends might need to actually be unmounted.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Mount) RemountFinish 

func (mount *Mount) RemountFinish(result AsyncResulter) error

RemountFinish finishes remounting a mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*Mount) Root 

func (mount *Mount) Root() *File

Root gets the root directory on mount.

The function returns the following values:

  • file: #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Mount) Shadow 

func (mount *Mount) Shadow()

Shadow increments the shadow count on mount. Usually used by Monitor implementations when creating a shadow mount for mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on mount manually.

func (*Mount) SortKey 

func (mount *Mount) SortKey() string

SortKey gets the sort key for mount, if any.

The function returns the following values:

  • utf8 (optional): sorting key for mount or NULL if no such key is available.

func (*Mount) SymbolicIcon 

func (mount *Mount) SymbolicIcon() *Icon

SymbolicIcon gets the symbolic icon for mount.

The function returns the following values:

  • icon: #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Mount) UUID 

func (mount *Mount) UUID() string

UUID gets the UUID for the mount. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns NULL if there is no UUID available.

The function returns the following values:

  • utf8 (optional): UUID for mount or NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.

func (*Mount) Unmount deprecated 

func (mount *Mount) Unmount(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

Unmount unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_finish() with the mount and Result data returned in the callback.

Deprecated: Use g_mount_unmount_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • callback (optional) or NULL.

func (*Mount) UnmountFinish deprecated 

func (mount *Mount) UnmountFinish(result AsyncResulter) error

UnmountFinish finishes unmounting a mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

Deprecated: Use g_mount_unmount_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*Mount) UnmountWithOperation 

func (mount *Mount) UnmountWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

UnmountWithOperation unmounts a mount. This is an asynchronous operation, and is finished by calling g_mount_unmount_with_operation_finish() with the mount and Result data returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Mount) UnmountWithOperationFinish 

func (mount *Mount) UnmountWithOperationFinish(result AsyncResulter) error

UnmountWithOperationFinish finishes unmounting a mount. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*Mount) Unshadow 

func (mount *Mount) Unshadow()

Unshadow decrements the shadow count on mount. Usually used by Monitor implementations when destroying a shadow mount for mount, see g_mount_is_shadowed() for more information. The caller will need to emit the #GMount::changed signal on mount manually.

func (*Mount) Volume 

func (mount *Mount) Volume() *Volume

Volume gets the volume for the mount.

The function returns the following values:

  • volume (optional) or NULL if mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed.

type MountIface added in v0.0.5 

type MountIface struct {
	// contains filtered or unexported fields
}

MountIface: interface for implementing operations for mounts.

An instance of this type is always passed by reference.

type MountMountFlags 

type MountMountFlags C.guint

MountMountFlags flags used when mounting a mount. 

const (
	// MountMountNone: no flags set.
	MountMountNone MountMountFlags = 0b0
)

func (MountMountFlags) Has 

func (m MountMountFlags) Has(other MountMountFlags) bool

Has returns true if m contains other.

func (MountMountFlags) String 

func (m MountMountFlags) String() string

String returns the names in string for MountMountFlags.

type MountOperation 

type MountOperation struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

MountOperation: 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 just gio.Mount objects – for example it is also used in gio.Drive.Start() and gio.Drive.Stop().

Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as GtkMountOperation (https://docs.gtk.org/gtk4/class.MountOperation.html). If no user interaction is desired (for example when automounting filesystems at login time), usually NULL can be passed, see each method taking a GMountOperation for details.

Throughout the API, the term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. TrueCrypt (https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. VeraCrypt (https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various improvements and auditing fixes.

func NewMountOperation 

func NewMountOperation() *MountOperation

NewMountOperation creates a new mount operation.

The function returns the following values:

  • mountOperation: Operation.

func (*MountOperation) Anonymous 

func (op *MountOperation) Anonymous() bool

Anonymous: check to see whether the mount operation is being used for an anonymous user.

The function returns the following values:

  • ok: TRUE if mount operation is anonymous.

func (*MountOperation) Choice 

func (op *MountOperation) Choice() int

Choice gets a choice from the mount operation.

The function returns the following values:

  • gint: integer containing an index of the user's choice from the choice's list, or 0.

func (*MountOperation) ConnectAborted 

func (op *MountOperation) ConnectAborted(f func()) coreglib.SignalHandle

ConnectAborted is emitted by the backend when e.g. a device becomes unavailable while a mount operation is in progress.

Implementations of GMountOperation should handle this signal by dismissing open password dialogs.

func (*MountOperation) ConnectAskPassword 

func (op *MountOperation) ConnectAskPassword(f func(message, defaultUser, defaultDomain string, flags AskPasswordFlags)) coreglib.SignalHandle

ConnectAskPassword is emitted when a mount operation asks the user for a password.

If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a MessageDialog.

func (*MountOperation) ConnectAskQuestion 

func (op *MountOperation) ConnectAskQuestion(f func(message string, choices []string)) coreglib.SignalHandle

ConnectAskQuestion is emitted when asking the user a question and gives a list of choices for the user to choose from.

If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a MessageDialog.

func (*MountOperation) ConnectReply 

func (op *MountOperation) ConnectReply(f func(result MountOperationResult)) coreglib.SignalHandle

ConnectReply is emitted when the user has replied to the mount operation.

func (*MountOperation) ConnectShowUnmountProgress 

func (op *MountOperation) ConnectShowUnmountProgress(f func(message string, timeLeft, bytesLeft int64)) coreglib.SignalHandle

ConnectShowUnmountProgress is emitted when an unmount operation has been busy for more than some time (typically 1.5 seconds).

When unmounting or ejecting a volume, the kernel might need to flush pending data in its buffers to the volume stable storage, and this operation can take a considerable amount of time. This signal may be emitted several times as long as the unmount operation is outstanding, and then one last time when the operation is completed, with bytes_left set to zero.

Implementations of GMountOperation should handle this signal by showing an UI notification, and then dismiss it, or show another notification of completion, when bytes_left reaches zero.

If the message contains a line break, the first line should be presented as a heading. For example, it may be used as the primary text in a MessageDialog.

func (*MountOperation) Domain 

func (op *MountOperation) Domain() string

Domain gets the domain of the mount operation.

The function returns the following values:

  • utf8 (optional): string set to the domain.

func (*MountOperation) IsTcryptHiddenVolume 

func (op *MountOperation) IsTcryptHiddenVolume() bool

IsTcryptHiddenVolume: check to see whether the mount operation is being used for a TCRYPT hidden volume.

The function returns the following values:

  • ok: TRUE if mount operation is for hidden volume.

func (*MountOperation) IsTcryptSystemVolume 

func (op *MountOperation) IsTcryptSystemVolume() bool

IsTcryptSystemVolume: check to see whether the mount operation is being used for a TCRYPT system volume.

The function returns the following values:

  • ok: TRUE if mount operation is for system volume.

func (*MountOperation) Password 

func (op *MountOperation) Password() string

Password gets a password from the mount operation.

The function returns the following values:

  • utf8 (optional): string containing the password within op.

func (*MountOperation) PasswordSave 

func (op *MountOperation) PasswordSave() PasswordSave

PasswordSave gets the state of saving passwords for the mount operation.

The function returns the following values:

  • passwordSave: Save flag.

func (*MountOperation) Pim 

func (op *MountOperation) Pim() uint

Pim gets a PIM from the mount operation.

The function returns the following values:

  • guint: veraCrypt PIM within op.

func (*MountOperation) Reply 

func (op *MountOperation) Reply(result MountOperationResult)

Reply emits the Operation::reply signal.

The function takes the following parameters:

  • result: OperationResult.

func (*MountOperation) SetAnonymous 

func (op *MountOperation) SetAnonymous(anonymous bool)

SetAnonymous sets the mount operation to use an anonymous user if anonymous is TRUE.

The function takes the following parameters:

  • anonymous: boolean value.

func (*MountOperation) SetChoice 

func (op *MountOperation) SetChoice(choice int)

SetChoice sets a default choice for the mount operation.

The function takes the following parameters:

  • choice: integer.

func (*MountOperation) SetDomain 

func (op *MountOperation) SetDomain(domain string)

SetDomain sets the mount operation's domain.

The function takes the following parameters:

  • domain (optional) to set.

func (*MountOperation) SetIsTcryptHiddenVolume 

func (op *MountOperation) SetIsTcryptHiddenVolume(hiddenVolume bool)

SetIsTcryptHiddenVolume sets the mount operation to use a hidden volume if hidden_volume is TRUE.

The function takes the following parameters:

  • hiddenVolume: boolean value.

func (*MountOperation) SetIsTcryptSystemVolume 

func (op *MountOperation) SetIsTcryptSystemVolume(systemVolume bool)

SetIsTcryptSystemVolume sets the mount operation to use a system volume if system_volume is TRUE.

The function takes the following parameters:

  • systemVolume: boolean value.

func (*MountOperation) SetPassword 

func (op *MountOperation) SetPassword(password string)

SetPassword sets the mount operation's password to password.

The function takes the following parameters:

  • password (optional) to set.

func (*MountOperation) SetPasswordSave 

func (op *MountOperation) SetPasswordSave(save PasswordSave)

SetPasswordSave sets the state of saving passwords for the mount operation.

The function takes the following parameters:

  • save: set of Save flags.

func (*MountOperation) SetPim 

func (op *MountOperation) SetPim(pim uint)

SetPim sets the mount operation's PIM to pim.

The function takes the following parameters:

  • pim: unsigned integer.

func (*MountOperation) SetUsername 

func (op *MountOperation) SetUsername(username string)

SetUsername sets the user name within op to username.

The function takes the following parameters:

  • username (optional): input username.

func (*MountOperation) Username 

func (op *MountOperation) Username() string

Username: get the user name from the mount operation.

The function returns the following values:

  • utf8 (optional): string containing the user name.

type MountOperationClass added in v0.0.5 

type MountOperationClass struct {
	// contains filtered or unexported fields
}

MountOperationClass: instance of this type is always passed by reference.

type MountOperationOverrides added in v0.0.5 

type MountOperationOverrides struct {
	Aborted func()
	// The function takes the following parameters:
	//
	//   - message
	//   - defaultUser
	//   - defaultDomain
	//   - flags
	AskPassword func(message, defaultUser, defaultDomain string, flags AskPasswordFlags)
	// AskQuestion: virtual implementation of Operation::ask-question.
	//
	// The function takes the following parameters:
	//
	//   - message: string containing a message to display to the user.
	//   - choices: array of strings for each possible choice.
	AskQuestion func(message string, choices []string)
	// Reply emits the Operation::reply signal.
	//
	// The function takes the following parameters:
	//
	//   - result: OperationResult.
	Reply func(result MountOperationResult)
	// The function takes the following parameters:
	//
	//   - message
	//   - timeLeft
	//   - bytesLeft
	ShowUnmountProgress func(message string, timeLeft, bytesLeft int64)
}

MountOperationOverrides contains methods that are overridable.

type MountOperationResult 

type MountOperationResult C.gint

MountOperationResult is returned as a result when a request for information is send by the mounting operation. 

const (
	// MountOperationHandled: request was fulfilled and the user specified data
	// is now available.
	MountOperationHandled MountOperationResult = iota
	// MountOperationAborted: user requested the mount operation to be aborted.
	MountOperationAborted
	// MountOperationUnhandled: request was unhandled (i.e. not implemented).
	MountOperationUnhandled
)

func (MountOperationResult) String 

func (m MountOperationResult) String() string

String returns the name in string for MountOperationResult.

type MountUnmountFlags 

type MountUnmountFlags C.guint

MountUnmountFlags flags used when an unmounting a mount. 

const (
	// MountUnmountNone: no flags set.
	MountUnmountNone MountUnmountFlags = 0b0
	// MountUnmountForce: unmount even if there are outstanding file operations
	// on the mount.
	MountUnmountForce MountUnmountFlags = 0b1
)

func (MountUnmountFlags) Has 

func (m MountUnmountFlags) Has(other MountUnmountFlags) bool

Has returns true if m contains other.

func (MountUnmountFlags) String 

func (m MountUnmountFlags) String() string

String returns the names in string for MountUnmountFlags.

type Mounter 

type Mounter interface {
	coreglib.Objector

	// CanEject checks if mount can be ejected.
	CanEject() bool
	// CanUnmount checks if mount can be unmounted.
	CanUnmount() bool
	// Eject ejects a mount.
	Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// EjectFinish finishes ejecting a mount.
	EjectFinish(result AsyncResulter) error
	// EjectWithOperation ejects a mount.
	EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// EjectWithOperationFinish finishes ejecting a mount.
	EjectWithOperationFinish(result AsyncResulter) error
	// DefaultLocation gets the default location of mount.
	DefaultLocation() *File
	// Drive gets the drive for the mount.
	Drive() *Drive
	// Icon gets the icon for mount.
	Icon() *Icon
	// Name gets the name of mount.
	Name() string
	// Root gets the root directory on mount.
	Root() *File
	// SortKey gets the sort key for mount, if any.
	SortKey() string
	// SymbolicIcon gets the symbolic icon for mount.
	SymbolicIcon() *Icon
	// UUID gets the UUID for the mount.
	UUID() string
	// Volume gets the volume for the mount.
	Volume() *Volume
	// GuessContentType tries to guess the type of content stored on mount.
	GuessContentType(ctx context.Context, forceRescan bool, callback AsyncReadyCallback)
	// GuessContentTypeFinish finishes guessing content types of mount.
	GuessContentTypeFinish(result AsyncResulter) ([]string, error)
	// GuessContentTypeSync tries to guess the type of content stored on mount.
	GuessContentTypeSync(ctx context.Context, forceRescan bool) ([]string, error)
	// IsShadowed determines if mount is shadowed.
	IsShadowed() bool
	// Remount remounts a mount.
	Remount(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// RemountFinish finishes remounting a mount.
	RemountFinish(result AsyncResulter) error
	// Shadow increments the shadow count on mount.
	Shadow()
	// Unmount unmounts a mount.
	Unmount(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// UnmountFinish finishes unmounting a mount.
	UnmountFinish(result AsyncResulter) error
	// UnmountWithOperation unmounts a mount.
	UnmountWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// UnmountWithOperationFinish finishes unmounting a mount.
	UnmountWithOperationFinish(result AsyncResulter) error
	// Unshadow decrements the shadow count on mount.
	Unshadow()

	// Changed is emitted when the mount has been changed.
	ConnectChanged(func()) coreglib.SignalHandle
	// Pre-unmount: this signal may be emitted when the #GMount is about to be
	// unmounted.
	ConnectPreUnmount(func()) coreglib.SignalHandle
	// Unmounted: this signal is emitted when the #GMount have been unmounted.
	ConnectUnmounted(func()) coreglib.SignalHandle
}

Mounter describes Mount's interface methods.

type NativeSocketAddress 

type NativeSocketAddress struct {
	SocketAddress
	// contains filtered or unexported fields
}

NativeSocketAddress: socket address of some unknown native type.

This corresponds to a general struct sockaddr of a type not otherwise handled by GLib.

func NewNativeSocketAddress 

func NewNativeSocketAddress(native unsafe.Pointer, len uint) *NativeSocketAddress

NewNativeSocketAddress creates a new SocketAddress for native and len.

The function takes the following parameters:

  • native (optional) address object.
  • len: length of native, in bytes.

The function returns the following values:

  • nativeSocketAddress: new SocketAddress.

type NativeSocketAddressClass added in v0.0.5 

type NativeSocketAddressClass struct {
	// contains filtered or unexported fields
}

NativeSocketAddressClass: instance of this type is always passed by reference.

func (*NativeSocketAddressClass) ParentClass added in v0.0.5 

func (n *NativeSocketAddressClass) ParentClass() *SocketAddressClass

type NativeSocketAddressOverrides added in v0.0.5 

type NativeSocketAddressOverrides struct {
}

NativeSocketAddressOverrides contains methods that are overridable.

type NativeVolumeMonitor 

type NativeVolumeMonitor struct {
	VolumeMonitor
	// contains filtered or unexported fields
}

func BaseNativeVolumeMonitor 

func BaseNativeVolumeMonitor(obj NativeVolumeMonitorrer) *NativeVolumeMonitor

BaseNativeVolumeMonitor returns the underlying base object.

type NativeVolumeMonitorClass added in v0.0.5 

type NativeVolumeMonitorClass struct {
	// contains filtered or unexported fields
}

NativeVolumeMonitorClass: instance of this type is always passed by reference.

func (*NativeVolumeMonitorClass) ParentClass added in v0.0.5 

func (n *NativeVolumeMonitorClass) ParentClass() *VolumeMonitorClass

type NativeVolumeMonitorOverrides added in v0.0.5 

type NativeVolumeMonitorOverrides struct {
}

NativeVolumeMonitorOverrides contains methods that are overridable.

type NativeVolumeMonitorrer 

type NativeVolumeMonitorrer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

NativeVolumeMonitorrer describes types inherited from class NativeVolumeMonitor.

To get the original type, the caller must assert this to an interface or another type.

type NetworkAddress 

type NetworkAddress struct {
	*coreglib.Object

	SocketConnectable
	// contains filtered or unexported fields
}

NetworkAddress: 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 gio.SocketConnectable for an example of using the connectable interface.

func NetworkAddressParse 

func NetworkAddressParse(hostAndPort string, defaultPort uint16) (*NetworkAddress, error)

NetworkAddressParse creates a new Connectable for connecting to the given hostname and port. May fail and return NULL in case parsing host_and_port fails.

host_and_port may be in any of a number of recognised formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon.

If no port is specified in host_and_port then default_port will be used as the port number to connect to.

In general, host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and default_port is expected to be provided by the application.

(The port component of host_and_port can also be specified as a service name rather than as a numeric port, but this functionality is deprecated, because it depends on the contents of /etc/services, which is generally quite sparse on platforms other than Linux.).

The function takes the following parameters:

  • hostAndPort: hostname and optionally a port.
  • defaultPort: default port if not in host_and_port.

The function returns the following values:

  • networkAddress: new Address, or NULL on error.

func NetworkAddressParseURI 

func NetworkAddressParseURI(uri string, defaultPort uint16) (*NetworkAddress, error)

NetworkAddressParseURI creates a new Connectable for connecting to the given uri. May fail and return NULL in case parsing uri fails.

Using this rather than g_network_address_new() or g_network_address_parse() allows Client to determine when to use application-specific proxy protocols.

The function takes the following parameters:

  • uri: hostname and optionally a port.
  • defaultPort: default port if none is found in the URI.

The function returns the following values:

  • networkAddress: new Address, or NULL on error.

func NewNetworkAddress 

func NewNetworkAddress(hostname string, port uint16) *NetworkAddress

NewNetworkAddress creates a new Connectable for connecting to the given hostname and port.

Note that depending on the configuration of the machine, a hostname of localhost may refer to the IPv4 loopback address only, or to both IPv4 and IPv6; use g_network_address_new_loopback() to create a Address that is guaranteed to resolve to both addresses.

The function takes the following parameters:

  • hostname: hostname.
  • port: port.

The function returns the following values:

  • networkAddress: new Address.

func NewNetworkAddressLoopback 

func NewNetworkAddressLoopback(port uint16) *NetworkAddress

NewNetworkAddressLoopback creates a new Connectable for connecting to the local host over a loopback connection to the given port. This is intended for use in connecting to local services which may be running on IPv4 or IPv6.

The connectable will return IPv4 and IPv6 loopback addresses, regardless of how the host resolves localhost. By contrast, g_network_address_new() will often only return an IPv4 address when resolving localhost, and an IPv6 address for localhost6.

g_network_address_get_hostname() will always return localhost for a Address created with this constructor.

The function takes the following parameters:

  • port: port.

The function returns the following values:

  • networkAddress: new Address.

func (*NetworkAddress) Hostname 

func (addr *NetworkAddress) Hostname() string

Hostname gets addr's hostname. This might be either UTF-8 or ASCII-encoded, depending on what addr was created with.

The function returns the following values:

  • utf8 addr's hostname.

func (*NetworkAddress) Port 

func (addr *NetworkAddress) Port() uint16

Port gets addr's port number.

The function returns the following values:

  • guint16 addr's port (which may be 0).

func (*NetworkAddress) Scheme 

func (addr *NetworkAddress) Scheme() string

Scheme gets addr's scheme.

The function returns the following values:

  • utf8 (optional) addr's scheme (NULL if not built from URI).

type NetworkAddressClass added in v0.0.5 

type NetworkAddressClass struct {
	// contains filtered or unexported fields
}

NetworkAddressClass: instance of this type is always passed by reference.

type NetworkAddressOverrides added in v0.0.5 

type NetworkAddressOverrides struct {
}

NetworkAddressOverrides contains methods that are overridable.

type NetworkConnectivity 

type NetworkConnectivity C.gint

NetworkConnectivity host's network connectivity state, as reported by Monitor. 

const (
	// NetworkConnectivityLocal: host is not configured with a route to the
	// Internet; it may or may not be connected to a local network.
	NetworkConnectivityLocal NetworkConnectivity = 1
	// NetworkConnectivityLimited: host is connected to a network, but does not
	// appear to be able to reach the full Internet, perhaps due to upstream
	// network problems.
	NetworkConnectivityLimited NetworkConnectivity = 2
	// NetworkConnectivityPortal: host is behind a captive portal and cannot
	// reach the full Internet.
	NetworkConnectivityPortal NetworkConnectivity = 3
	// NetworkConnectivityFull: host is connected to a network, and appears to
	// be able to reach the full Internet.
	NetworkConnectivityFull NetworkConnectivity = 4
)

func (NetworkConnectivity) String 

func (n NetworkConnectivity) String() string

String returns the name in string for NetworkConnectivity.

type NetworkMonitor 

type NetworkMonitor struct {
	Initable
	// contains filtered or unexported fields
}

NetworkMonitor: 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.

NetworkMonitor wraps an interface. This means the user can get the underlying type by calling Cast().

func NetworkMonitorGetDefault 

func NetworkMonitorGetDefault() *NetworkMonitor

NetworkMonitorGetDefault gets the default Monitor for the system.

The function returns the following values:

  • networkMonitor which will be a dummy object if no network monitor is available.

func (*NetworkMonitor) CanReach 

func (monitor *NetworkMonitor) CanReach(ctx context.Context, connectable SocketConnectabler) error

CanReach attempts to determine whether or not the host pointed to by connectable can be reached, without actually trying to connect to it.

This may return TRUE even when Monitor:network-available is FALSE, if, for example, monitor can determine that connectable refers to a host on a local network.

If monitor believes that an attempt to connect to connectable will succeed, it will return TRUE. Otherwise, it will return FALSE and set error to an appropriate error (such as G_IO_ERROR_HOST_UNREACHABLE).

Note that although this does not attempt to connect to connectable, it may still block for a brief period of time (eg, trying to do multicast DNS on the local network), so if you do not want to block, you should use g_network_monitor_can_reach_async().

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connectable: Connectable.

func (*NetworkMonitor) CanReachAsync 

func (monitor *NetworkMonitor) CanReachAsync(ctx context.Context, connectable SocketConnectabler, callback AsyncReadyCallback)

CanReachAsync: asynchronously attempts to determine whether or not the host pointed to by connectable can be reached, without actually trying to connect to it.

For more details, see g_network_monitor_can_reach().

When the operation is finished, callback will be called. You can then call g_network_monitor_can_reach_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connectable: Connectable.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*NetworkMonitor) CanReachFinish 

func (monitor *NetworkMonitor) CanReachFinish(result AsyncResulter) error

CanReachFinish finishes an async network connectivity test. See g_network_monitor_can_reach_async().

The function takes the following parameters:

  • result: Result.

func (*NetworkMonitor) ConnectNetworkChanged 

func (monitor *NetworkMonitor) ConnectNetworkChanged(f func(networkAvailable bool)) coreglib.SignalHandle

ConnectNetworkChanged is emitted when the network configuration changes.

func (*NetworkMonitor) Connectivity 

func (monitor *NetworkMonitor) Connectivity() NetworkConnectivity

Connectivity gets a more detailed networking state than g_network_monitor_get_network_available().

If Monitor:network-available is FALSE, then the connectivity state will be G_NETWORK_CONNECTIVITY_LOCAL.

If Monitor:network-available is TRUE, then the connectivity state will be G_NETWORK_CONNECTIVITY_FULL (if there is full Internet connectivity), G_NETWORK_CONNECTIVITY_LIMITED (if the host has a default route, but appears to be unable to actually reach the full Internet), or G_NETWORK_CONNECTIVITY_PORTAL (if the host is trapped behind a "captive portal" that requires some sort of login or acknowledgement before allowing full Internet access).

Note that in the case of G_NETWORK_CONNECTIVITY_LIMITED and G_NETWORK_CONNECTIVITY_PORTAL, it is possible that some sites are reachable but others are not. In this case, applications can attempt to connect to remote servers, but should gracefully fall back to their "offline" behavior if the connection attempt fails.

The function returns the following values:

  • networkConnectivity: network connectivity state.

func (*NetworkMonitor) NetworkAvailable 

func (monitor *NetworkMonitor) NetworkAvailable() bool

NetworkAvailable checks if the network is available. "Available" here means that the system has a default route available for at least one of IPv4 or IPv6. It does not necessarily imply that the public Internet is reachable. See Monitor:network-available for more details.

The function returns the following values:

  • ok: whether the network is available.

func (*NetworkMonitor) NetworkMetered 

func (monitor *NetworkMonitor) NetworkMetered() bool

NetworkMetered checks if the network is metered. See Monitor:network-metered for more details.

The function returns the following values:

  • ok: whether the connection is metered.

type NetworkMonitorInterface added in v0.0.5 

type NetworkMonitorInterface struct {
	// contains filtered or unexported fields
}

NetworkMonitorInterface: virtual function table for Monitor.

An instance of this type is always passed by reference.

type NetworkMonitorrer 

type NetworkMonitorrer interface {
	coreglib.Objector

	// CanReach attempts to determine whether or not the host pointed to by
	// connectable can be reached, without actually trying to connect to it.
	CanReach(ctx context.Context, connectable SocketConnectabler) error
	// CanReachAsync: asynchronously attempts to determine whether or not the
	// host pointed to by connectable can be reached, without actually trying to
	// connect to it.
	CanReachAsync(ctx context.Context, connectable SocketConnectabler, callback AsyncReadyCallback)
	// CanReachFinish finishes an async network connectivity test.
	CanReachFinish(result AsyncResulter) error
	// Connectivity gets a more detailed networking state than
	// g_network_monitor_get_network_available().
	Connectivity() NetworkConnectivity
	// NetworkAvailable checks if the network is available.
	NetworkAvailable() bool
	// NetworkMetered checks if the network is metered.
	NetworkMetered() bool

	// Network-changed is emitted when the network configuration changes.
	ConnectNetworkChanged(func(networkAvailable bool)) coreglib.SignalHandle
}

NetworkMonitorrer describes NetworkMonitor's interface methods.

type NetworkService 

type NetworkService struct {
	*coreglib.Object

	SocketConnectable
	// contains filtered or unexported fields
}

NetworkService: like gio.NetworkAddress 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 gio.SrvTarget for more information about SRV records, and see gio.SocketConnectable for an example of using the connectable interface.

func NewNetworkService 

func NewNetworkService(service, protocol, domain string) *NetworkService

NewNetworkService creates a new Service representing the given service, protocol, and domain. This will initially be unresolved; use the Connectable interface to resolve it.

The function takes the following parameters:

  • service type to look up (eg, "ldap").
  • protocol: networking protocol to use for service (eg, "tcp").
  • domain: DNS domain to look up the service in.

The function returns the following values:

  • networkService: new Service.

func (*NetworkService) Domain 

func (srv *NetworkService) Domain() string

Domain gets the domain that srv serves. This might be either UTF-8 or ASCII-encoded, depending on what srv was created with.

The function returns the following values:

  • utf8 srv's domain name.

func (*NetworkService) Protocol 

func (srv *NetworkService) Protocol() string

Protocol gets srv's protocol name (eg, "tcp").

The function returns the following values:

  • utf8 srv's protocol name.

func (*NetworkService) Scheme 

func (srv *NetworkService) Scheme() string

Scheme gets the URI scheme used to resolve proxies. By default, the service name is used as scheme.

The function returns the following values:

  • utf8 srv's scheme name.

func (*NetworkService) Service 

func (srv *NetworkService) Service() string

Service gets srv's service name (eg, "ldap").

The function returns the following values:

  • utf8 srv's service name.

func (*NetworkService) SetScheme 

func (srv *NetworkService) SetScheme(scheme string)

SetScheme set's the URI scheme used to resolve proxies. By default, the service name is used as scheme.

The function takes the following parameters:

  • scheme: URI scheme.

type NetworkServiceClass added in v0.0.5 

type NetworkServiceClass struct {
	// contains filtered or unexported fields
}

NetworkServiceClass: instance of this type is always passed by reference.

type NetworkServiceOverrides added in v0.0.5 

type NetworkServiceOverrides struct {
}

NetworkServiceOverrides contains methods that are overridable.

type Notification 

type Notification struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Notification: 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 with GNotification 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, using gio.Application.

In order for GNotification to work, the application must have installed a .desktop file. For example: 

[Desktop Entry]
Name=Test Application
Comment=Description of what Test Application does
Exec=gnome-test-application
Icon=org.gnome.TestApplication
Terminal=false
Type=Application
Categories=GNOME;GTK;TestApplication Category;
StartupNotify=true
DBusActivatable=true
X-GNOME-UsesNotifications=true

The X-GNOME-UsesNotifications key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel.

The .desktop file must be named as org.gnome.TestApplication.desktop, where org.gnome.TestApplication is the ID passed to gio.Application.New.

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 gio.Application.SendNotification().

func NewNotification 

func NewNotification(title string) *Notification

NewNotification creates a new #GNotification with title as its title.

After populating notification with more details, it can be sent to the desktop shell with g_application_send_notification(). Changing any properties after this call will not have any effect until resending notification.

The function takes the following parameters:

  • title of the notification.

The function returns the following values:

  • notification: new #GNotification instance.

func (*Notification) AddButton 

func (notification *Notification) AddButton(label, detailedAction string)

AddButton adds a button to notification that activates the action in detailed_action when clicked. That action must be an application-wide action (starting with "app."). If detailed_action contains a target, the action will be activated with that target as its parameter.

See g_action_parse_detailed_name() for a description of the format for detailed_action.

The function takes the following parameters:

  • label of the button.
  • detailedAction: detailed action name.

func (*Notification) AddButtonWithTarget 

func (notification *Notification) AddButtonWithTarget(label, action string, target *glib.Variant)

AddButtonWithTarget adds a button to notification that activates action when clicked. action must be an application-wide action (it must start with "app.").

If target is non-NULL, action will be activated with target as its parameter.

The function takes the following parameters:

  • label of the button.
  • action name.
  • target (optional) to use as action's parameter, or NULL.

func (*Notification) SetBody 

func (notification *Notification) SetBody(body string)

SetBody sets the body of notification to body.

The function takes the following parameters:

  • body (optional): new body for notification, or NULL.

func (*Notification) SetCategory added in v0.3.0 

func (notification *Notification) SetCategory(category string)

SetCategory sets the type of notification to category. Categories have a main type like email, im or device and can have a detail separated by a ., e.g. im.received or email.arrived. Setting the category helps the notification server to select proper feedback to the user.

Standard categories are listed in the specification (https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).

The function takes the following parameters:

  • category (optional) for notification, or NULL for no category.

func (*Notification) SetDefaultAction 

func (notification *Notification) SetDefaultAction(detailedAction string)

SetDefaultAction sets the default action of notification to detailed_action. This action is activated when the notification is clicked on.

The action in detailed_action must be an application-wide action (it must start with "app."). If detailed_action contains a target, the given action will be activated with that target as its parameter. See g_action_parse_detailed_name() for a description of the format for detailed_action.

When no default action is set, the application that the notification was sent on is activated.

The function takes the following parameters:

  • detailedAction: detailed action name.

func (*Notification) SetDefaultActionAndTarget 

func (notification *Notification) SetDefaultActionAndTarget(action string, target *glib.Variant)

SetDefaultActionAndTarget sets the default action of notification to action. This action is activated when the notification is clicked on. It must be an application-wide action (start with "app.").

If target is non-NULL, action will be activated with target as its parameter. If target is floating, it will be consumed.

When no default action is set, the application that the notification was sent on is activated.

The function takes the following parameters:

  • action name.
  • target (optional) to use as action's parameter, or NULL.

func (*Notification) SetIcon 

func (notification *Notification) SetIcon(icon Iconner)

SetIcon sets the icon of notification to icon.

The function takes the following parameters:

  • icon to be shown in notification, as a #GIcon.

func (*Notification) SetPriority 

func (notification *Notification) SetPriority(priority NotificationPriority)

SetPriority sets the priority of notification to priority. See Priority for possible values.

The function takes the following parameters:

  • priority: Priority.

func (*Notification) SetTitle 

func (notification *Notification) SetTitle(title string)

SetTitle sets the title of notification to title.

The function takes the following parameters:

  • title: new title for notification.

func (*Notification) SetUrgent deprecated 

func (notification *Notification) SetUrgent(urgent bool)

SetUrgent: deprecated in favor of g_notification_set_priority().

Deprecated: Since 2.42, this has been deprecated in favour of g_notification_set_priority().

The function takes the following parameters:

  • urgent: TRUE if notification is urgent.

type NotificationPriority 

type NotificationPriority C.gint

NotificationPriority: priority levels for #GNotifications. 

const (
	// NotificationPriorityNormal: default priority, to be used for the majority
	// of notifications (for example email messages, software updates, completed
	// download/sync operations).
	NotificationPriorityNormal NotificationPriority = iota
	// NotificationPriorityLow: for notifications that do not require immediate
	// attention - typically used for contextual background information, such as
	// contact birthdays or local weather.
	NotificationPriorityLow
	// NotificationPriorityHigh: for events that require more attention, usually
	// because responses are time-sensitive (for example chat and SMS messages
	// or alarms).
	NotificationPriorityHigh
	// NotificationPriorityUrgent: for urgent notifications, or notifications
	// that require a response in a short space of time (for example phone calls
	// or emergency warnings).
	NotificationPriorityUrgent
)

func (NotificationPriority) String 

func (n NotificationPriority) String() string

String returns the name in string for NotificationPriority.

type OutputMessage 

type OutputMessage struct {
	// contains filtered or unexported fields
}

OutputMessage: structure used for scatter/gather data output when sending multiple messages or packets in one go. You generally pass in an array of Vectors and the operation will use all the buffers as if they were one buffer.

If address is NULL then the message is sent to the default receiver (as previously set by g_socket_connect()).

An instance of this type is always passed by reference.

type OutputStream 

type OutputStream struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

OutputStream: GOutputStream is a base class for implementing streaming output.

It has functions to write to a stream (gio.OutputStream.Write()), to close a stream (gio.OutputStream.Close()) and to flush pending writes (gio.OutputStream.Flush()).

To copy the content of an input stream to an output stream without manually handling the reads and writes, use gio.OutputStream.Splice().

See the documentation for gio.IOStream for details of thread safety of streaming APIs.

All of these functions have async variants too.

All classes derived from GOutputStream *should* implement synchronous writing, splicing, flushing and closing streams, but *may* implement asynchronous versions.

func BaseOutputStream 

func BaseOutputStream(obj OutputStreamer) *OutputStream

BaseOutputStream returns the underlying base object.

func (*OutputStream) ClearPending 

func (stream *OutputStream) ClearPending()

ClearPending clears the pending flag on stream.

func (*OutputStream) Close 

func (stream *OutputStream) Close(ctx context.Context) error

Close closes the stream, releasing resources related to it.

Once the stream is closed, all other operations will return G_IO_ERROR_CLOSED. Closing a stream multiple times will not return an error.

Closing a stream will automatically flush any outstanding buffers in the stream.

Streams will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

Some streams might keep the backing store of the stream (e.g. a file descriptor) open after the stream is closed. See the documentation for the individual stream for details.

On failure the first error that happened will be reported, but the close operation will finish as much as possible. A stream that failed to close will still return G_IO_ERROR_CLOSED for all operations. Still, it is important to check and report the error to the user, otherwise there might be a loss of data as all data might not be written.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. Cancelling a close will still leave the stream closed, but there some streams can use a faster close that doesn't block to e.g. check errors. On cancellation (as with any error) there is no guarantee that all written data will reach the target.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.

func (*OutputStream) CloseAsync 

func (stream *OutputStream) CloseAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

CloseAsync requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished callback will be called. You can then call g_output_stream_close_finish() to get the result of the operation.

For behaviour details see g_output_stream_close().

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) CloseFinish 

func (stream *OutputStream) CloseFinish(result AsyncResulter) error

CloseFinish closes an output stream.

The function takes the following parameters:

  • result: Result.

func (*OutputStream) Flush 

func (stream *OutputStream) Flush(ctx context.Context) error

Flush forces a write of all user-space buffered data for the given stream. Will block during the operation. Closing the stream will implicitly cause a flush.

This function is optional for inherited classes.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.

func (*OutputStream) FlushAsync 

func (stream *OutputStream) FlushAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

FlushAsync forces an asynchronous write of all user-space buffered data for the given stream. For behaviour details see g_output_stream_flush().

When the operation is finished callback will be called. You can then call g_output_stream_flush_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) FlushFinish 

func (stream *OutputStream) FlushFinish(result AsyncResulter) error

FlushFinish finishes flushing an output stream.

The function takes the following parameters:

  • result: GAsyncResult.

func (*OutputStream) HasPending 

func (stream *OutputStream) HasPending() bool

HasPending checks if an output stream has pending actions.

The function returns the following values:

  • ok: TRUE if stream has pending actions.

func (*OutputStream) IsClosed 

func (stream *OutputStream) IsClosed() bool

IsClosed checks if an output stream has already been closed.

The function returns the following values:

  • ok: TRUE if stream is closed. FALSE otherwise.

func (*OutputStream) IsClosing 

func (stream *OutputStream) IsClosing() bool

IsClosing checks if an output stream is being closed. This can be used inside e.g. a flush implementation to see if the flush (or other i/o operation) is called from within the closing operation.

The function returns the following values:

  • ok: TRUE if stream is being closed. FALSE otherwise.

func (*OutputStream) SetPending 

func (stream *OutputStream) SetPending() error

SetPending sets stream to have actions pending. If the pending flag is already set or stream is closed, it will return FALSE and set error.

func (*OutputStream) Splice 

func (stream *OutputStream) Splice(ctx context.Context, source InputStreamer, flags OutputStreamSpliceFlags) (int, error)

Splice splices an input stream into an output stream.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • source: Stream.
  • flags: set of StreamSpliceFlags.

The function returns the following values:

  • gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.

func (*OutputStream) SpliceAsync 

func (stream *OutputStream) SpliceAsync(ctx context.Context, source InputStreamer, flags OutputStreamSpliceFlags, ioPriority int, callback AsyncReadyCallback)

SpliceAsync splices a stream asynchronously. When the operation is finished callback will be called. You can then call g_output_stream_splice_finish() to get the result of the operation.

For the synchronous, blocking version of this function, see g_output_stream_splice().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • source: Stream.
  • flags: set of StreamSpliceFlags.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) SpliceFinish 

func (stream *OutputStream) SpliceFinish(result AsyncResulter) (int, error)

SpliceFinish finishes an asynchronous stream splice operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.

func (*OutputStream) Write 

func (stream *OutputStream) Write(ctx context.Context, buffer []byte) (int, error)

Write tries to write count bytes from buffer into the stream. Will block during the operation.

If count is 0, returns 0 and does nothing. A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless count is 0).

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • buffer containing the data to write.

The function returns the following values:

  • gssize: number of bytes written, or -1 on error.

func (*OutputStream) WriteAll 

func (stream *OutputStream) WriteAll(ctx context.Context, buffer []byte) (uint, error)

WriteAll tries to write count bytes from buffer into the stream. Will block during the operation.

This function is similar to g_output_stream_write(), except it tries to write as many bytes as requested, only stopping on an error.

On a successful write of count bytes, TRUE is returned, and bytes_written is set to count.

If there is an error during the operation FALSE is returned and error is set to indicate the error status.

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer containing the data to write.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that was written to the stream.

func (*OutputStream) WriteAllAsync 

func (stream *OutputStream) WriteAllAsync(ctx context.Context, buffer []byte, ioPriority int, callback AsyncReadyCallback)

WriteAllAsync: request an asynchronous write of count bytes from buffer into the stream. When the operation is finished callback will be called. You can then call g_output_stream_write_all_finish() to get the result of the operation.

This is the asynchronous version of g_output_stream_write_all().

Call g_output_stream_write_all_finish() to collect the result.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

Note that no copy of buffer will be made, so it must stay valid until callback is called.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer containing the data to write.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) WriteAllFinish 

func (stream *OutputStream) WriteAllFinish(result AsyncResulter) (uint, error)

WriteAllFinish finishes an asynchronous stream write operation started with g_output_stream_write_all_async().

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that was written to the stream.

func (*OutputStream) WriteAsync 

func (stream *OutputStream) WriteAsync(ctx context.Context, buffer []byte, ioPriority int, callback AsyncReadyCallback)

WriteAsync: request an asynchronous write of count bytes from buffer into the stream. When the operation is finished callback will be called. You can then call g_output_stream_write_finish() to get the result of the operation.

During an async request no other sync and async calls are allowed, and will result in G_IO_ERROR_PENDING errors.

A value of count larger than G_MAXSSIZE will cause a G_IO_ERROR_INVALID_ARGUMENT error.

On success, the number of bytes written will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested.

You are guaranteed that this method will never fail with G_IO_ERROR_WOULD_BLOCK - if stream can't accept more data, the method will just wait until this changes.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

For the synchronous, blocking version of this function, see g_output_stream_write().

Note that no copy of buffer will be made, so it must stay valid until callback is called. See g_output_stream_write_bytes_async() for a #GBytes version that will automatically hold a reference to the contents (without copying) for the duration of the call.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • buffer containing the data to write.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) WriteBytes 

func (stream *OutputStream) WriteBytes(ctx context.Context, bytes *glib.Bytes) (int, error)

WriteBytes: wrapper function for g_output_stream_write() which takes a #GBytes as input. This can be more convenient for use by language bindings or in other cases where the refcounted nature of #GBytes is helpful over a bare pointer interface.

However, note that this function may still perform partial writes, just like g_output_stream_write(). If that occurs, to continue writing, you will need to create a new #GBytes containing just the remaining bytes, using g_bytes_new_from_bytes(). Passing the same #GBytes instance multiple times potentially can result in duplicated data in the output stream.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • bytes to write.

The function returns the following values:

  • gssize: number of bytes written, or -1 on error.

func (*OutputStream) WriteBytesAsync 

func (stream *OutputStream) WriteBytesAsync(ctx context.Context, bytes *glib.Bytes, ioPriority int, callback AsyncReadyCallback)

WriteBytesAsync: this function is similar to g_output_stream_write_async(), but takes a #GBytes as input. Due to the refcounted nature of #GBytes, this allows the stream to avoid taking a copy of the data.

However, note that this function may still perform partial writes, just like g_output_stream_write_async(). If that occurs, to continue writing, you will need to create a new #GBytes containing just the remaining bytes, using g_bytes_new_from_bytes(). Passing the same #GBytes instance multiple times potentially can result in duplicated data in the output stream.

For the synchronous, blocking version of this function, see g_output_stream_write_bytes().

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • bytes to write.
  • ioPriority: io priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) WriteBytesFinish 

func (stream *OutputStream) WriteBytesFinish(result AsyncResulter) (int, error)

WriteBytesFinish finishes a stream write-from-#GBytes operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize containing the number of bytes written to the stream.

func (*OutputStream) WriteFinish 

func (stream *OutputStream) WriteFinish(result AsyncResulter) (int, error)

WriteFinish finishes a stream write operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • gssize containing the number of bytes written to the stream.

func (*OutputStream) Writev 

func (stream *OutputStream) Writev(ctx context.Context, vectors []OutputVector) (uint, error)

Writev tries to write the bytes contained in the n_vectors vectors into the stream. Will block during the operation.

If n_vectors is 0 or the sum of all bytes in vectors is 0, returns 0 and does nothing.

On success, the number of bytes written to the stream is returned. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, or if there is not enough storage in the stream. All writes block until at least one byte is written or an error occurs; 0 is never returned (unless n_vectors is 0 or the sum of all bytes in vectors is 0).

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

Some implementations of g_output_stream_writev() may have limitations on the aggregate buffer size, and will return G_IO_ERROR_INVALID_ARGUMENT if these are exceeded. For example, when writing to a local file on UNIX platforms, the aggregate buffer size must not exceed G_MAXSSIZE bytes.

The function takes the following parameters:

  • ctx (optional): optional cancellable object.
  • vectors: buffer containing the Vectors to write.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the stream.

func (*OutputStream) WritevAll 

func (stream *OutputStream) WritevAll(ctx context.Context, vectors []OutputVector) (uint, error)

WritevAll tries to write the bytes contained in the n_vectors vectors into the stream. Will block during the operation.

This function is similar to g_output_stream_writev(), except it tries to write as many bytes as requested, only stopping on an error.

On a successful write of all n_vectors vectors, TRUE is returned, and bytes_written is set to the sum of all the sizes of vectors.

If there is an error during the operation FALSE is returned and error is set to indicate the error status.

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_write().

The content of the individual elements of vectors might be changed by this function.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • vectors: buffer containing the Vectors to write.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the stream.

func (*OutputStream) WritevAllAsync 

func (stream *OutputStream) WritevAllAsync(ctx context.Context, vectors []OutputVector, ioPriority int, callback AsyncReadyCallback)

WritevAllAsync: request an asynchronous write of the bytes contained in the n_vectors vectors into the stream. When the operation is finished callback will be called. You can then call g_output_stream_writev_all_finish() to get the result of the operation.

This is the asynchronous version of g_output_stream_writev_all().

Call g_output_stream_writev_all_finish() to collect the result.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

Note that no copy of vectors will be made, so it must stay valid until callback is called. The content of the individual elements of vectors might be changed by this function.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • vectors: buffer containing the Vectors to write.
  • ioPriority: i/O priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) WritevAllFinish 

func (stream *OutputStream) WritevAllFinish(result AsyncResulter) (uint, error)

WritevAllFinish finishes an asynchronous stream write operation started with g_output_stream_writev_all_async().

As a special exception to the normal conventions for functions that use #GError, if this function returns FALSE (and sets error) then bytes_written will be set to the number of bytes that were successfully written before the error was encountered. This functionality is only available from C. If you need it from another language then you must write your own loop around g_output_stream_writev_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the stream.

func (*OutputStream) WritevAsync 

func (stream *OutputStream) WritevAsync(ctx context.Context, vectors []OutputVector, ioPriority int, callback AsyncReadyCallback)

WritevAsync: request an asynchronous write of the bytes contained in n_vectors vectors into the stream. When the operation is finished callback will be called. You can then call g_output_stream_writev_finish() to get the result of the operation.

During an async request no other sync and async calls are allowed, and will result in G_IO_ERROR_PENDING errors.

On success, the number of bytes written will be passed to the callback. It is not an error if this is not the same as the requested size, as it can happen e.g. on a partial I/O error, but generally we try to write as many bytes as requested.

You are guaranteed that this method will never fail with G_IO_ERROR_WOULD_BLOCK — if stream can't accept more data, the method will just wait until this changes.

Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower priority. Default priority is G_PRIORITY_DEFAULT.

The asynchronous methods have a default fallback that uses threads to implement asynchronicity, so they are optional for inheriting classes. However, if you override one you must override all.

For the synchronous, blocking version of this function, see g_output_stream_writev().

Note that no copy of vectors will be made, so it must stay valid until callback is called.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • vectors: buffer containing the Vectors to write.
  • ioPriority: i/O priority of the request.
  • callback (optional): ReadyCallback to call when the request is satisfied.

func (*OutputStream) WritevFinish 

func (stream *OutputStream) WritevFinish(result AsyncResulter) (uint, error)

WritevFinish finishes a stream writev operation.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the stream.

type OutputStreamClass added in v0.0.5 

type OutputStreamClass struct {
	// contains filtered or unexported fields
}

OutputStreamClass: instance of this type is always passed by reference.

type OutputStreamOverrides added in v0.0.5 

type OutputStreamOverrides struct {
	// CloseFinish closes an output stream.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	CloseFinish func(result AsyncResulter) error
	CloseFn     func(ctx context.Context) error
	// Flush forces a write of all user-space buffered data for the given
	// stream. Will block during the operation. Closing the stream will
	// implicitly cause a flush.
	//
	// This function is optional for inherited classes.
	//
	// If cancellable is not NULL, then the operation can be cancelled by
	// triggering the cancellable object from another thread. If the operation
	// was cancelled, the error G_IO_ERROR_CANCELLED will be returned.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional cancellable object.
	Flush func(ctx context.Context) error
	// FlushFinish finishes flushing an output stream.
	//
	// The function takes the following parameters:
	//
	//   - result: GAsyncResult.
	FlushFinish func(result AsyncResulter) error
	// Splice splices an input stream into an output stream.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//   - source: Stream.
	//   - flags: set of StreamSpliceFlags.
	//
	// The function returns the following values:
	//
	//   - gssize containing the size of the data spliced, or -1 if an error
	//     occurred. Note that if the number of bytes spliced is greater than
	//     G_MAXSSIZE, then that will be returned, and there is no way to
	//     determine the actual number of bytes spliced.
	Splice func(ctx context.Context, source InputStreamer, flags OutputStreamSpliceFlags) (int, error)
	// SpliceFinish finishes an asynchronous stream splice operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - gssize of the number of bytes spliced. Note that if the number of
	//     bytes spliced is greater than G_MAXSSIZE, then that will be returned,
	//     and there is no way to determine the actual number of bytes spliced.
	SpliceFinish func(result AsyncResulter) (int, error)
	// WriteFinish finishes a stream write operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - gssize containing the number of bytes written to the stream.
	WriteFinish func(result AsyncResulter) (int, error)
	// WritevFinish finishes a stream writev operation.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - bytesWritten (optional): location to store the number of bytes that
	//     were written to the stream.
	WritevFinish func(result AsyncResulter) (uint, error)
}

OutputStreamOverrides contains methods that are overridable.

type OutputStreamSpliceFlags 

type OutputStreamSpliceFlags C.guint

OutputStreamSpliceFlags determine how streams should be spliced. 

const (
	// OutputStreamSpliceNone: do not close either stream.
	OutputStreamSpliceNone OutputStreamSpliceFlags = 0b0
	// OutputStreamSpliceCloseSource: close the source stream after the splice.
	OutputStreamSpliceCloseSource OutputStreamSpliceFlags = 0b1
	// OutputStreamSpliceCloseTarget: close the target stream after the splice.
	OutputStreamSpliceCloseTarget OutputStreamSpliceFlags = 0b10
)

func (OutputStreamSpliceFlags) Has 

func (o OutputStreamSpliceFlags) Has(other OutputStreamSpliceFlags) bool

Has returns true if o contains other.

func (OutputStreamSpliceFlags) String 

func (o OutputStreamSpliceFlags) String() string

String returns the names in string for OutputStreamSpliceFlags.

type OutputStreamer 

type OutputStreamer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

OutputStreamer describes types inherited from class OutputStream.

To get the original type, the caller must assert this to an interface or another type.

type OutputVector 

type OutputVector struct {
	// contains filtered or unexported fields
}

OutputVector: structure used for scatter/gather data output. You generally pass in an array of Vectors and the operation will use all the buffers as if they were one buffer.

An instance of this type is always passed by reference.

func (*OutputVector) Buffer 

func (o *OutputVector) Buffer() unsafe.Pointer

Buffer: pointer to a buffer of data to read.

func (*OutputVector) SetSize 

func (o *OutputVector) SetSize(size uint)

Size: size of buffer.

func (*OutputVector) Size 

func (o *OutputVector) Size() uint

Size: size of buffer.

type PasswordSave 

type PasswordSave C.gint

PasswordSave is used to indicate the lifespan of a saved password.

#Gvfs stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. 

const (
	// PasswordSaveNever: never save a password.
	PasswordSaveNever PasswordSave = iota
	// PasswordSaveForSession: save a password for the session.
	PasswordSaveForSession
	// PasswordSavePermanently: save a password permanently.
	PasswordSavePermanently
)

func (PasswordSave) String 

func (p PasswordSave) String() string

String returns the name in string for PasswordSave.

type Permission 

type Permission struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Permission: 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 GPermission might represent the ability for the user to write to a gio.Settings object. This GPermission 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.

func BasePermission 

func BasePermission(obj Permissioner) *Permission

BasePermission returns the underlying base object.

func (*Permission) Acquire 

func (permission *Permission) Acquire(ctx context.Context) error

Acquire attempts to acquire the permission represented by permission.

The precise method by which this happens depends on the permission and the underlying authentication mechanism. A simple example is that a dialog may appear asking the user to enter their password.

You should check with g_permission_get_can_acquire() before calling this function.

If the permission is acquired then TRUE is returned. Otherwise, FALSE is returned and error is set appropriately.

This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_acquire_async() for the non-blocking version.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*Permission) AcquireAsync 

func (permission *Permission) AcquireAsync(ctx context.Context, callback AsyncReadyCallback)

AcquireAsync attempts to acquire the permission represented by permission.

This is the first half of the asynchronous version of g_permission_acquire().

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional) to call when done.

func (*Permission) AcquireFinish 

func (permission *Permission) AcquireFinish(result AsyncResulter) error

AcquireFinish collects the result of attempting to acquire the permission represented by permission.

This is the second half of the asynchronous version of g_permission_acquire().

The function takes the following parameters:

  • result given to the ReadyCallback.

func (*Permission) Allowed 

func (permission *Permission) Allowed() bool

Allowed gets the value of the 'allowed' property. This property is TRUE if the caller currently has permission to perform the action that permission represents the permission to perform.

The function returns the following values:

  • ok: value of the 'allowed' property.

func (*Permission) CanAcquire 

func (permission *Permission) CanAcquire() bool

CanAcquire gets the value of the 'can-acquire' property. This property is TRUE if it is generally possible to acquire the permission by calling g_permission_acquire().

The function returns the following values:

  • ok: value of the 'can-acquire' property.

func (*Permission) CanRelease 

func (permission *Permission) CanRelease() bool

CanRelease gets the value of the 'can-release' property. This property is TRUE if it is generally possible to release the permission by calling g_permission_release().

The function returns the following values:

  • ok: value of the 'can-release' property.

func (*Permission) ImplUpdate 

func (permission *Permission) ImplUpdate(allowed, canAcquire, canRelease bool)

ImplUpdate: this function is called by the #GPermission implementation to update the properties of the permission. You should never call this function except from a #GPermission implementation.

GObject notify signals are generated, as appropriate.

The function takes the following parameters:

  • allowed: new value for the 'allowed' property.
  • canAcquire: new value for the 'can-acquire' property.
  • canRelease: new value for the 'can-release' property.

func (*Permission) Release 

func (permission *Permission) Release(ctx context.Context) error

Release attempts to release the permission represented by permission.

The precise method by which this happens depends on the permission and the underlying authentication mechanism. In most cases the permission will be dropped immediately without further action.

You should check with g_permission_get_can_release() before calling this function.

If the permission is released then TRUE is returned. Otherwise, FALSE is returned and error is set appropriately.

This call is blocking, likely for a very long time (in the case that user interaction is required). See g_permission_release_async() for the non-blocking version.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*Permission) ReleaseAsync 

func (permission *Permission) ReleaseAsync(ctx context.Context, callback AsyncReadyCallback)

ReleaseAsync attempts to release the permission represented by permission.

This is the first half of the asynchronous version of g_permission_release().

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional) to call when done.

func (*Permission) ReleaseFinish 

func (permission *Permission) ReleaseFinish(result AsyncResulter) error

ReleaseFinish collects the result of attempting to release the permission represented by permission.

This is the second half of the asynchronous version of g_permission_release().

The function takes the following parameters:

  • result given to the ReadyCallback.

type PermissionClass added in v0.0.5 

type PermissionClass struct {
	// contains filtered or unexported fields
}

PermissionClass: instance of this type is always passed by reference.

func (*PermissionClass) Reserved added in v0.0.5 

func (p *PermissionClass) Reserved() [16]unsafe.Pointer

type PermissionOverrides added in v0.0.5 

type PermissionOverrides struct {
	// Acquire attempts to acquire the permission represented by permission.
	//
	// The precise method by which this happens depends on the permission and
	// the underlying authentication mechanism. A simple example is that a
	// dialog may appear asking the user to enter their password.
	//
	// You should check with g_permission_get_can_acquire() before calling this
	// function.
	//
	// If the permission is acquired then TRUE is returned. Otherwise, FALSE is
	// returned and error is set appropriately.
	//
	// This call is blocking, likely for a very long time (in the case that
	// user interaction is required). See g_permission_acquire_async() for the
	// non-blocking version.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	Acquire func(ctx context.Context) error
	// AcquireFinish collects the result of attempting to acquire the permission
	// represented by permission.
	//
	// This is the second half of the asynchronous version of
	// g_permission_acquire().
	//
	// The function takes the following parameters:
	//
	//   - result given to the ReadyCallback.
	AcquireFinish func(result AsyncResulter) error
	// Release attempts to release the permission represented by permission.
	//
	// The precise method by which this happens depends on the permission and
	// the underlying authentication mechanism. In most cases the permission
	// will be dropped immediately without further action.
	//
	// You should check with g_permission_get_can_release() before calling this
	// function.
	//
	// If the permission is released then TRUE is returned. Otherwise, FALSE is
	// returned and error is set appropriately.
	//
	// This call is blocking, likely for a very long time (in the case that
	// user interaction is required). See g_permission_release_async() for the
	// non-blocking version.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	Release func(ctx context.Context) error
	// ReleaseFinish collects the result of attempting to release the permission
	// represented by permission.
	//
	// This is the second half of the asynchronous version of
	// g_permission_release().
	//
	// The function takes the following parameters:
	//
	//   - result given to the ReadyCallback.
	ReleaseFinish func(result AsyncResulter) error
}

PermissionOverrides contains methods that are overridable.

type Permissioner 

type Permissioner interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

Permissioner describes types inherited from class Permission.

To get the original type, the caller must assert this to an interface or another type.

type PollableInputStream 

type PollableInputStream struct {
	InputStream
	// contains filtered or unexported fields
}

PollableInputStream: GPollableInputStream is implemented by gio.InputStreams 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.

Some classes may implement GPollableInputStream but have only certain instances of that class be pollable. If gio.PollableInputStream.CanPoll() returns false, then the behavior of other GPollableInputStream methods is undefined.

PollableInputStream wraps an interface. This means the user can get the underlying type by calling Cast().

func (*PollableInputStream) CanPoll 

func (stream *PollableInputStream) CanPoll() bool

CanPoll checks if stream is actually pollable. Some classes may implement InputStream but have only certain instances of that class be pollable. If this method returns FALSE, then the behavior of other InputStream methods is undefined.

For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa.

The function returns the following values:

  • ok: TRUE if stream is pollable, FALSE if not.

func (*PollableInputStream) CreateSource 

func (stream *PollableInputStream) CreateSource(ctx context.Context) *glib.Source

CreateSource creates a #GSource that triggers when stream can be read, or cancellable is triggered or an error occurs. The callback on the source is of the SourceFunc type.

As with g_pollable_input_stream_is_readable(), it is possible that the stream may not actually be readable even after the source triggers, so you should use g_pollable_input_stream_read_nonblocking() rather than g_input_stream_read() from the callback.

The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns FALSE for stream.

The function takes the following parameters:

  • ctx (optional) or NULL.

The function returns the following values:

  • source: new #GSource.

func (*PollableInputStream) IsReadable 

func (stream *PollableInputStream) IsReadable() bool

IsReadable checks if stream can be read.

Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_input_stream_read() after this returns TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_input_stream_read_nonblocking(), which will return a G_IO_ERROR_WOULD_BLOCK error rather than blocking.

The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns FALSE for stream.

The function returns the following values:

  • ok: TRUE if stream is readable, FALSE if not. If an error has occurred on stream, this will result in g_pollable_input_stream_is_readable() returning TRUE, and the next attempt to read will return the error.

func (*PollableInputStream) ReadNonblocking 

func (stream *PollableInputStream) ReadNonblocking(ctx context.Context, buffer []byte) (int, error)

ReadNonblocking attempts to read up to count bytes from stream into buffer, as with g_input_stream_read(). If stream is not currently readable, this will immediately return G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_input_stream_create_source() to create a #GSource that will be triggered when stream is readable.

Note that since this method never blocks, you cannot actually use cancellable to cancel it. However, it will return an error if cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled.

The behaviour of this method is undefined if g_pollable_input_stream_can_poll() returns FALSE for stream.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • buffer: a buffer to read data into (which should be at least count bytes long).

The function returns the following values:

  • gssize: number of bytes read, or -1 on error (including G_IO_ERROR_WOULD_BLOCK).

type PollableInputStreamInterface added in v0.0.5 

type PollableInputStreamInterface struct {
	// contains filtered or unexported fields
}

PollableInputStreamInterface: interface for pollable input streams.

The default implementation of can_poll always returns TRUE.

The default implementation of read_nonblocking calls g_pollable_input_stream_is_readable(), and then calls g_input_stream_read() if it returns TRUE. This means you only need to override it if it is possible that your is_readable implementation may return TRUE when the stream is not actually readable.

An instance of this type is always passed by reference.

type PollableInputStreamer 

type PollableInputStreamer interface {
	coreglib.Objector

	// CanPoll checks if stream is actually pollable.
	CanPoll() bool
	// CreateSource creates a #GSource that triggers when stream can be read,
	// or cancellable is triggered or an error occurs.
	CreateSource(ctx context.Context) *glib.Source
	// IsReadable checks if stream can be read.
	IsReadable() bool
	// ReadNonblocking attempts to read up to count bytes from stream into
	// buffer, as with g_input_stream_read().
	ReadNonblocking(ctx context.Context, buffer []byte) (int, error)
}

PollableInputStreamer describes PollableInputStream's interface methods.

type PollableOutputStream 

type PollableOutputStream struct {
	OutputStream
	// contains filtered or unexported fields
}

PollableOutputStream: GPollableOutputStream is implemented by gio.OutputStreams 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.

Some classes may implement GPollableOutputStream but have only certain instances of that class be pollable. If gio.PollableOutputStream.CanPoll() returns false, then the behavior of other GPollableOutputStream methods is undefined.

PollableOutputStream wraps an interface. This means the user can get the underlying type by calling Cast().

func (*PollableOutputStream) CanPoll 

func (stream *PollableOutputStream) CanPoll() bool

CanPoll checks if stream is actually pollable. Some classes may implement OutputStream but have only certain instances of that class be pollable. If this method returns FALSE, then the behavior of other OutputStream methods is undefined.

For any given stream, the value returned by this method is constant; a stream cannot switch from pollable to non-pollable or vice versa.

The function returns the following values:

  • ok: TRUE if stream is pollable, FALSE if not.

func (*PollableOutputStream) CreateSource 

func (stream *PollableOutputStream) CreateSource(ctx context.Context) *glib.Source

CreateSource creates a #GSource that triggers when stream can be written, or cancellable is triggered or an error occurs. The callback on the source is of the SourceFunc type.

As with g_pollable_output_stream_is_writable(), it is possible that the stream may not actually be writable even after the source triggers, so you should use g_pollable_output_stream_write_nonblocking() rather than g_output_stream_write() from the callback.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns FALSE for stream.

The function takes the following parameters:

  • ctx (optional) or NULL.

The function returns the following values:

  • source: new #GSource.

func (*PollableOutputStream) IsWritable 

func (stream *PollableOutputStream) IsWritable() bool

IsWritable checks if stream can be written.

Note that some stream types may not be able to implement this 100% reliably, and it is possible that a call to g_output_stream_write() after this returns TRUE would still block. To guarantee non-blocking behavior, you should always use g_pollable_output_stream_write_nonblocking(), which will return a G_IO_ERROR_WOULD_BLOCK error rather than blocking.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns FALSE for stream.

The function returns the following values:

  • ok: TRUE if stream is writable, FALSE if not. If an error has occurred on stream, this will result in g_pollable_output_stream_is_writable() returning TRUE, and the next attempt to write will return the error.

func (*PollableOutputStream) WriteNonblocking 

func (stream *PollableOutputStream) WriteNonblocking(ctx context.Context, buffer []byte) (int, error)

WriteNonblocking attempts to write up to count bytes from buffer to stream, as with g_output_stream_write(). If stream is not currently writable, this will immediately return G_IO_ERROR_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when stream is writable.

Note that since this method never blocks, you cannot actually use cancellable to cancel it. However, it will return an error if cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled.

Also note that if G_IO_ERROR_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same buffer and count in the next write call.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns FALSE for stream.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • buffer to write data from.

The function returns the following values:

  • gssize: number of bytes written, or -1 on error (including G_IO_ERROR_WOULD_BLOCK).

func (*PollableOutputStream) WritevNonblocking 

func (stream *PollableOutputStream) WritevNonblocking(ctx context.Context, vectors []OutputVector) (uint, PollableReturn, error)

WritevNonblocking attempts to write the bytes contained in the n_vectors vectors to stream, as with g_output_stream_writev(). If stream is not currently writable, this will immediately return G_POLLABLE_RETURN_WOULD_BLOCK, and you can use g_pollable_output_stream_create_source() to create a #GSource that will be triggered when stream is writable. error will *not* be set in that case.

Note that since this method never blocks, you cannot actually use cancellable to cancel it. However, it will return an error if cancellable has already been cancelled when you call, which may happen if you call this method after a source triggers due to having been cancelled.

Also note that if G_POLLABLE_RETURN_WOULD_BLOCK is returned some underlying transports like D/TLS require that you re-send the same vectors and n_vectors in the next write call.

The behaviour of this method is undefined if g_pollable_output_stream_can_poll() returns FALSE for stream.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • vectors: buffer containing the Vectors to write.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the stream.
  • pollableReturn: G_POLLABLE_RETURN_OK on success, G_POLLABLE_RETURN_WOULD_BLOCK if the stream is not currently writable (and error is *not* set), or G_POLLABLE_RETURN_FAILED if there was an error in which case error will be set.

type PollableOutputStreamInterface added in v0.0.5 

type PollableOutputStreamInterface struct {
	// contains filtered or unexported fields
}

PollableOutputStreamInterface: interface for pollable output streams.

The default implementation of can_poll always returns TRUE.

The default implementation of write_nonblocking calls g_pollable_output_stream_is_writable(), and then calls g_output_stream_write() if it returns TRUE. This means you only need to override it if it is possible that your is_writable implementation may return TRUE when the stream is not actually writable.

The default implementation of writev_nonblocking calls g_pollable_output_stream_write_nonblocking() for each vector, and converts its return value and error (if set) to a Return. You should override this where possible to avoid having to allocate a #GError to return G_IO_ERROR_WOULD_BLOCK.

An instance of this type is always passed by reference.

type PollableOutputStreamer 

type PollableOutputStreamer interface {
	coreglib.Objector

	// CanPoll checks if stream is actually pollable.
	CanPoll() bool
	// CreateSource creates a #GSource that triggers when stream can be written,
	// or cancellable is triggered or an error occurs.
	CreateSource(ctx context.Context) *glib.Source
	// IsWritable checks if stream can be written.
	IsWritable() bool
	// WriteNonblocking attempts to write up to count bytes from buffer to
	// stream, as with g_output_stream_write().
	WriteNonblocking(ctx context.Context, buffer []byte) (int, error)
	// WritevNonblocking attempts to write the bytes contained in the n_vectors
	// vectors to stream, as with g_output_stream_writev().
	WritevNonblocking(ctx context.Context, vectors []OutputVector) (uint, PollableReturn, error)
}

PollableOutputStreamer describes PollableOutputStream's interface methods.

type PollableReturn 

type PollableReturn C.gint

PollableReturn: return value for various IO operations that signal errors via the return value and not necessarily via a #GError.

This enum exists to be able to return errors to callers without having to allocate a #GError. Allocating #GErrors can be quite expensive for regularly happening errors like G_IO_ERROR_WOULD_BLOCK.

In case of G_POLLABLE_RETURN_FAILED a #GError should be set for the operation to give details about the error that happened. 

const (
	// PollableReturnFailed: generic error condition for when an operation
	// fails.
	PollableReturnFailed PollableReturn = 0
	// PollableReturnOK: operation was successfully finished.
	PollableReturnOK PollableReturn = 1
	// PollableReturnWouldBlock: operation would block.
	PollableReturnWouldBlock PollableReturn = -27
)

func (PollableReturn) String 

func (p PollableReturn) String() string

String returns the name in string for PollableReturn.

type PowerProfileMonitor added in v0.3.0 

type PowerProfileMonitor struct {
	Initable
	// contains filtered or unexported fields
}

PowerProfileMonitor: GPowerProfileMonitor makes it possible for applications as well as OS components to monitor system power profiles and act upon them. It currently only exports whether the system is in “Power Saver” mode (known as “Low Power” mode on some systems).

When in “Low Power” mode, it is recommended that applications:

- disable automatic downloads;

- reduce the rate of refresh from online sources such as calendar or email synchronisation;

- reduce the use of expensive visual effects.

It is also likely that OS components providing services to applications will lower their own background activity, for the sake of the system.

There are a variety of tools that exist for power consumption analysis, but those usually depend on the OS and hardware used. On Linux, one could use upower to monitor the battery discharge rate, powertop to check on the background activity or activity at all), sysprof to inspect CPU usage, and intel_gpu_time to profile GPU usage.

Don’t forget to disconnect the gobject.Object::notify signal for gio.PowerProfileMonitor:power-saver-enabled, and unref the GPowerProfileMonitor itself when exiting.

PowerProfileMonitor wraps an interface. This means the user can get the underlying type by calling Cast().

func PowerProfileMonitorDupDefault added in v0.3.0 

func PowerProfileMonitorDupDefault() *PowerProfileMonitor

PowerProfileMonitorDupDefault gets a reference to the default ProfileMonitor for the system.

The function returns the following values:

  • powerProfileMonitor: new reference to the default ProfileMonitor.

func (*PowerProfileMonitor) PowerSaverEnabled added in v0.3.0 

func (monitor *PowerProfileMonitor) PowerSaverEnabled() bool

PowerSaverEnabled gets whether the system is in “Power Saver” mode.

You are expected to listen to the ProfileMonitor::notify::power-saver-enabled signal to know when the profile has changed.

The function returns the following values:

  • ok: whether the system is in “Power Saver” mode.

type PowerProfileMonitorInterface added in v0.3.0 

type PowerProfileMonitorInterface struct {
	// contains filtered or unexported fields
}

PowerProfileMonitorInterface: virtual function table for ProfileMonitor.

An instance of this type is always passed by reference.

type PowerProfileMonitorOverrider added in v0.3.0 

type PowerProfileMonitorOverrider interface {
}

PowerProfileMonitorOverrider contains methods that are overridable.

type PowerProfileMonitorrer added in v0.3.0 

type PowerProfileMonitorrer interface {
	coreglib.Objector

	// PowerSaverEnabled gets whether the system is in “Power Saver” mode.
	PowerSaverEnabled() bool
}

PowerProfileMonitorrer describes PowerProfileMonitor's interface methods.

type PropertyAction 

type PropertyAction struct {
	*coreglib.Object

	Action
	// contains filtered or unexported fields
}

PropertyAction: GPropertyAction is a way to get a gio.Action with a state value reflecting and controlling the value of a gobject.Object 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 gobject.ParamSpec).

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 gobject.EnumValue 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 glib.Variant 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 gio.Action corresponding to the visible-child-name property of a GtkStack (https://docs.gtk.org/gtk4/class.Stack.html) 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 the GtkStack.

An anti-example would be binding the active-id property on a GtkComboBox (https://docs.gtk.org/gtk4/class.ComboBox.html). This is because the state of the combo box 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 GtkStack (https://docs.gtk.org/gtk4/class.Stack.html) if this value is actually stored in gio.Settings. In that case, the real source of the value is* gio.Settings. If you want a gio.Action to control a setting stored in gio.Settings, see gio.Settings.CreateAction() instead, and possibly combine its use with gio.Settings.Bind().

func NewPropertyAction 

func NewPropertyAction(name string, object *coreglib.Object, propertyName string) *PropertyAction

NewPropertyAction creates a #GAction corresponding to the value of property property_name on object.

The property must be existent and readable and writable (and not construct-only).

This function takes a reference on object and doesn't release it until the action is destroyed.

The function takes the following parameters:

  • name of the action to create.
  • object that has the property to wrap.
  • propertyName: name of the property.

The function returns the following values:

  • propertyAction: new Action.

type Proxier 

type Proxier interface {
	coreglib.Objector

	// ConnectProxy: given connection to communicate with a proxy (eg,
	// a Connection that is connected to the proxy server), this does the
	// necessary handshake to connect to proxy_address, and if required,
	// wraps the OStream to handle proxy payload.
	ConnectProxy(ctx context.Context, connection IOStreamer, proxyAddress *ProxyAddress) (IOStreamer, error)
	// ConnectAsync asynchronous version of g_proxy_connect().
	ConnectAsync(ctx context.Context, connection IOStreamer, proxyAddress *ProxyAddress, callback AsyncReadyCallback)
	// ConnectFinish: see g_proxy_connect().
	ConnectFinish(result AsyncResulter) (IOStreamer, error)
	// SupportsHostname: some proxy protocols expect to be passed a hostname,
	// which they will resolve to an IP address themselves.
	SupportsHostname() bool
}

Proxier describes Proxy's interface methods.

type Proxy 

type Proxy struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Proxy: GProxy 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 function gio.IOExtensionPoint.GetExtensionByName().

Proxy wraps an interface. This means the user can get the underlying type by calling Cast().

func ProxyGetDefaultForProtocol 

func ProxyGetDefaultForProtocol(protocol string) *Proxy

ProxyGetDefaultForProtocol: find the gio-proxy extension point for a proxy implementation that supports the specified protocol.

The function takes the following parameters:

  • protocol: proxy protocol name (e.g. http, socks, etc).

The function returns the following values:

  • proxy (optional): return a #GProxy or NULL if protocol is not supported.

func (*Proxy) ConnectAsync 

func (proxy *Proxy) ConnectAsync(ctx context.Context, connection IOStreamer, proxyAddress *ProxyAddress, callback AsyncReadyCallback)

ConnectAsync asynchronous version of g_proxy_connect().

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • connection: OStream.
  • proxyAddress: Address.
  • callback (optional): ReadyCallback.

func (*Proxy) ConnectFinish 

func (proxy *Proxy) ConnectFinish(result AsyncResulter) (IOStreamer, error)

ConnectFinish: see g_proxy_connect().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • ioStream: OStream.

func (*Proxy) ConnectProxy 

func (proxy *Proxy) ConnectProxy(ctx context.Context, connection IOStreamer, proxyAddress *ProxyAddress) (IOStreamer, error)

ConnectProxy: given connection to communicate with a proxy (eg, a Connection that is connected to the proxy server), this does the necessary handshake to connect to proxy_address, and if required, wraps the OStream to handle proxy payload.

The function takes the following parameters:

  • ctx (optional): #GCancellable.
  • connection: OStream.
  • proxyAddress: Address.

The function returns the following values:

  • ioStream that will replace connection. This might be the same as connection, in which case a reference will be added.

func (*Proxy) SupportsHostname 

func (proxy *Proxy) SupportsHostname() bool

SupportsHostname: some proxy protocols expect to be passed a hostname, which they will resolve to an IP address themselves. Others, like SOCKS4, do not allow this. This function will return FALSE if proxy is implementing such a protocol. When FALSE is returned, the caller should resolve the destination hostname first, and then pass a Address containing the stringified IP address to g_proxy_connect() or g_proxy_connect_async().

The function returns the following values:

  • ok: TRUE if hostname resolution is supported.

type ProxyAddress 

type ProxyAddress struct {
	InetSocketAddress
	// contains filtered or unexported fields
}

ProxyAddress: gio.InetSocketAddress representing a connection via a proxy server.

func NewProxyAddress 

func NewProxyAddress(inetaddr *InetAddress, port uint16, protocol, destHostname string, destPort uint16, username, password string) *ProxyAddress

NewProxyAddress creates a new Address for inetaddr with protocol that should tunnel through dest_hostname and dest_port.

(Note that this method doesn't set the Address:uri or Address:destination-protocol fields; use g_object_new() directly if you want to set those.).

The function takes the following parameters:

  • inetaddr: proxy server Address.
  • port: proxy server port.
  • protocol: proxy protocol to support, in lower case (e.g. socks, http).
  • destHostname: destination hostname the proxy should tunnel to.
  • destPort: destination port to tunnel to.
  • username (optional) to authenticate to the proxy server (or NULL).
  • password (optional) to authenticate to the proxy server (or NULL).

The function returns the following values:

  • proxyAddress: new Address.

func (*ProxyAddress) DestinationHostname 

func (proxy *ProxyAddress) DestinationHostname() string

DestinationHostname gets proxy's destination hostname; that is, the name of the host that will be connected to via the proxy, not the name of the proxy itself.

The function returns the following values:

  • utf8 proxy's destination hostname.

func (*ProxyAddress) DestinationPort 

func (proxy *ProxyAddress) DestinationPort() uint16

DestinationPort gets proxy's destination port; that is, the port on the destination host that will be connected to via the proxy, not the port number of the proxy itself.

The function returns the following values:

  • guint16 proxy's destination port.

func (*ProxyAddress) DestinationProtocol 

func (proxy *ProxyAddress) DestinationProtocol() string

DestinationProtocol gets the protocol that is being spoken to the destination server; eg, "http" or "ftp".

The function returns the following values:

  • utf8 proxy's destination protocol.

func (*ProxyAddress) Password 

func (proxy *ProxyAddress) Password() string

Password gets proxy's password.

The function returns the following values:

  • utf8 (optional) proxy's password.

func (*ProxyAddress) Protocol 

func (proxy *ProxyAddress) Protocol() string

Protocol gets proxy's protocol. eg, "socks" or "http".

The function returns the following values:

  • utf8 proxy's protocol.

func (*ProxyAddress) URI 

func (proxy *ProxyAddress) URI() string

URI gets the proxy URI that proxy was constructed from.

The function returns the following values:

  • utf8 (optional) proxy's URI, or NULL if unknown.

func (*ProxyAddress) Username 

func (proxy *ProxyAddress) Username() string

Username gets proxy's username.

The function returns the following values:

  • utf8 (optional) proxy's username.

type ProxyAddressClass added in v0.0.5 

type ProxyAddressClass struct {
	// contains filtered or unexported fields
}

ProxyAddressClass class structure for Address.

An instance of this type is always passed by reference.

func (*ProxyAddressClass) ParentClass added in v0.0.5 

func (p *ProxyAddressClass) ParentClass() *InetSocketAddressClass

type ProxyAddressEnumerator 

type ProxyAddressEnumerator struct {
	SocketAddressEnumerator
	// contains filtered or unexported fields
}

ProxyAddressEnumerator: GProxyAddressEnumerator is a wrapper around gio.SocketAddressEnumerator which takes the gio.SocketAddress instances returned by the gio.SocketAddressEnumerator and wraps them in gio.ProxyAddress instances, using the given gio.ProxyAddressEnumerator:proxy-resolver.

This enumerator will be returned (for example, by gio.SocketConnectable.Enumerate()) as appropriate when a proxy is configured; there should be no need to manually wrap a gio.SocketAddressEnumerator instance with one.

type ProxyAddressEnumeratorClass added in v0.0.5 

type ProxyAddressEnumeratorClass struct {
	// contains filtered or unexported fields
}

ProxyAddressEnumeratorClass class structure for AddressEnumerator.

An instance of this type is always passed by reference.

type ProxyAddressEnumeratorOverrides added in v0.0.5 

type ProxyAddressEnumeratorOverrides struct {
}

ProxyAddressEnumeratorOverrides contains methods that are overridable.

type ProxyAddressOverrides added in v0.0.5 

type ProxyAddressOverrides struct {
}

ProxyAddressOverrides contains methods that are overridable.

type ProxyInterface added in v0.0.5 

type ProxyInterface struct {
	// contains filtered or unexported fields
}

ProxyInterface provides an interface for handling proxy connection and payload.

An instance of this type is always passed by reference.

type ProxyResolver 

type ProxyResolver struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

ProxyResolver: GProxyResolver provides synchronous and asynchronous network proxy resolution. GProxyResolver is used within gio.SocketClient through the method gio.SocketConnectable.ProxyEnumerate().

Implementations of GProxyResolver based on libproxy (https://github.com/libproxy/libproxy) and GNOME settings can be found in glib-networking (https://gitlab.gnome.org/GNOME/glib-networking). GIO comes with an implementation for use inside Flatpak portals.

ProxyResolver wraps an interface. This means the user can get the underlying type by calling Cast().

func NewSimpleProxyResolver added in v0.3.0 

func NewSimpleProxyResolver(defaultProxy string, ignoreHosts []string) *ProxyResolver

NewSimpleProxyResolver creates a new ProxyResolver. See ProxyResolver:default-proxy and ProxyResolver:ignore-hosts for more details on how the arguments are interpreted.

The function takes the following parameters:

  • defaultProxy (optional): default proxy to use, eg "socks://192.168.1.1".
  • ignoreHosts (optional): optional list of hosts/IP addresses to not use a proxy for.

The function returns the following values:

  • proxyResolver: new ProxyResolver.

func ProxyResolverGetDefault 

func ProxyResolverGetDefault() *ProxyResolver

ProxyResolverGetDefault gets the default Resolver for the system.

The function returns the following values:

  • proxyResolver: default Resolver, which will be a dummy object if no proxy resolver is available.

func (*ProxyResolver) IsSupported 

func (resolver *ProxyResolver) IsSupported() bool

IsSupported checks if resolver can be used on this system. (This is used internally; g_proxy_resolver_get_default() will only return a proxy resolver that returns TRUE for this method.).

The function returns the following values:

  • ok: TRUE if resolver is supported.

func (*ProxyResolver) Lookup 

func (resolver *ProxyResolver) Lookup(ctx context.Context, uri string) ([]string, error)

Lookup looks into the system proxy configuration to determine what proxy, if any, to use to connect to uri. The returned proxy URIs are of the form <protocol>://[user[:password]@]host[:port] or direct://, where <protocol> could be http, rtsp, socks or other proxying protocol.

If you don't know what network protocol is being used on the socket, you should use none as the URI protocol. In this case, the resolver might still return a generic proxy type (such as SOCKS), but would not return protocol-specific proxy types (such as http).

direct:// is used when no proxy is needed. Direct connection should not be attempted unless it is part of the returned array of proxies.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • uri: URI representing the destination to connect to.

The function returns the following values:

  • utf8s: a NULL-terminated array of proxy URIs. Must be freed with g_strfreev().

func (*ProxyResolver) LookupAsync 

func (resolver *ProxyResolver) LookupAsync(ctx context.Context, uri string, callback AsyncReadyCallback)

LookupAsync asynchronous lookup of proxy. See g_proxy_resolver_lookup() for more details.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • uri: URI representing the destination to connect to.
  • callback (optional) to call after resolution completes.

func (*ProxyResolver) LookupFinish 

func (resolver *ProxyResolver) LookupFinish(result AsyncResulter) ([]string, error)

LookupFinish: call this function to obtain the array of proxy URIs when g_proxy_resolver_lookup_async() is complete. See g_proxy_resolver_lookup() for more details.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • utf8s: a NULL-terminated array of proxy URIs. Must be freed with g_strfreev().

type ProxyResolverInterface added in v0.0.5 

type ProxyResolverInterface struct {
	// contains filtered or unexported fields
}

ProxyResolverInterface: virtual function table for Resolver.

An instance of this type is always passed by reference.

type ProxyResolverer 

type ProxyResolverer interface {
	coreglib.Objector

	// IsSupported checks if resolver can be used on this system.
	IsSupported() bool
	// Lookup looks into the system proxy configuration to determine what proxy,
	// if any, to use to connect to uri.
	Lookup(ctx context.Context, uri string) ([]string, error)
	// LookupAsync asynchronous lookup of proxy.
	LookupAsync(ctx context.Context, uri string, callback AsyncReadyCallback)
	// LookupFinish: call this function to obtain the array of proxy URIs when
	// g_proxy_resolver_lookup_async() is complete.
	LookupFinish(result AsyncResulter) ([]string, error)
}

ProxyResolverer describes ProxyResolver's interface methods.

type RemoteActionGroup 

type RemoteActionGroup struct {
	ActionGroup
	// contains filtered or unexported fields
}

RemoteActionGroup: GRemoteActionGroup interface is implemented by gio.ActionGroup instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes.

The interface has _full variants of the two methods on gio.ActionGroup used to activate actions: gio.ActionGroup.ActivateAction() and gio.ActionGroup.ChangeActionState(). These variants allow a ‘platform data’ glib.Variant to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc).

gio.DBusActionGroup implements GRemoteActionGroup. This provides a mechanism to send platform data for action invocations over D-Bus.

Additionally, gio.DBusConnection.ExportActionGroup() will check if the exported gio.ActionGroup implements GRemoteActionGroup and use the _full variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus.

RemoteActionGroup wraps an interface. This means the user can get the underlying type by calling Cast().

func (*RemoteActionGroup) ActivateActionFull 

func (remote *RemoteActionGroup) ActivateActionFull(actionName string, parameter, platformData *glib.Variant)

ActivateActionFull activates the remote action.

This is the same as g_action_group_activate_action() except that it allows for provision of "platform data" to be sent along with the activation request. This typically contains details such as the user interaction timestamp or startup notification information.

platform_data must be non-NULL and must have the type G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.

The function takes the following parameters:

  • actionName: name of the action to activate.
  • parameter (optional): optional parameter to the activation.
  • platformData: platform data to send.

func (*RemoteActionGroup) ChangeActionStateFull 

func (remote *RemoteActionGroup) ChangeActionStateFull(actionName string, value, platformData *glib.Variant)

ChangeActionStateFull changes the state of a remote action.

This is the same as g_action_group_change_action_state() except that it allows for provision of "platform data" to be sent along with the state change request. This typically contains details such as the user interaction timestamp or startup notification information.

platform_data must be non-NULL and must have the type G_VARIANT_TYPE_VARDICT. If it is floating, it will be consumed.

The function takes the following parameters:

  • actionName: name of the action to change the state of.
  • value: new requested value for the state.
  • platformData: platform data to send.

type RemoteActionGroupInterface added in v0.0.5 

type RemoteActionGroupInterface struct {
	// contains filtered or unexported fields
}

RemoteActionGroupInterface: virtual function table for ActionGroup.

An instance of this type is always passed by reference.

type RemoteActionGrouper 

type RemoteActionGrouper interface {
	coreglib.Objector

	// ActivateActionFull activates the remote action.
	ActivateActionFull(actionName string, parameter, platformData *glib.Variant)
	// ChangeActionStateFull changes the state of a remote action.
	ChangeActionStateFull(actionName string, value, platformData *glib.Variant)
}

RemoteActionGrouper describes RemoteActionGroup's interface methods.

type Resolver 

type Resolver struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Resolver: object that handles DNS resolution. Use gio.Resolver().GetDefault to get the default resolver.

GResolver provides cancellable synchronous and asynchronous DNS resolution, for hostnames (gio.Resolver.LookupByAddress(), gio.Resolver.LookupByName() and their async variants) and SRV (service) records (gio.Resolver.LookupService()).

gio.NetworkAddress and gio.NetworkService provide wrappers around GResolver functionality that also implement gio.SocketConnectable, making it easy to connect to a remote host/service.

The default resolver (see gio.Resolver().GetDefault) has a timeout of 30s set on it since GLib 2.78. Earlier versions of GLib did not support resolver timeouts.

This is an abstract type; subclasses of it implement different resolvers for different platforms and situations.

func BaseResolver 

func BaseResolver(obj Resolverer) *Resolver

BaseResolver returns the underlying base object.

func (*Resolver) ConnectReload 

func (resolver *Resolver) ConnectReload(f func()) coreglib.SignalHandle

ConnectReload is emitted when the resolver notices that the system resolver configuration has changed.

func (*Resolver) LookupByAddress 

func (resolver *Resolver) LookupByAddress(ctx context.Context, address *InetAddress) (string, error)

LookupByAddress: synchronously reverse-resolves address to determine its associated hostname.

If the DNS resolution fails, error (if non-NULL) will be set to a value from Error.

If cancellable is non-NULL, it can be used to cancel the operation, in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address to reverse-resolve.

The function returns the following values:

  • utf8: hostname (either ASCII-only, or in ASCII-encoded form), or NULL on error.

func (*Resolver) LookupByAddressAsync 

func (resolver *Resolver) LookupByAddressAsync(ctx context.Context, address *InetAddress, callback AsyncReadyCallback)

LookupByAddressAsync begins asynchronously reverse-resolving address to determine its associated hostname, and eventually calls callback, which must call g_resolver_lookup_by_address_finish() to get the final result.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • address to reverse-resolve.
  • callback (optional) to call after resolution completes.

func (*Resolver) LookupByAddressFinish 

func (resolver *Resolver) LookupByAddressFinish(result AsyncResulter) (string, error)

LookupByAddressFinish retrieves the result of a previous call to g_resolver_lookup_by_address_async().

If the DNS resolution failed, error (if non-NULL) will be set to a value from Error. If the operation was cancelled, error will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • utf8: hostname (either ASCII-only, or in ASCII-encoded form), or NULL on error.

func (*Resolver) LookupByName 

func (resolver *Resolver) LookupByName(ctx context.Context, hostname string) ([]*InetAddress, error)

LookupByName: synchronously resolves hostname to determine its associated IP address(es). hostname may be an ASCII-only or UTF-8 hostname, or the textual form of an IP address (in which case this just becomes a wrapper around g_inet_address_new_from_string()).

On success, g_resolver_lookup_by_name() will return a non-empty #GList of Address, sorted in order of preference and guaranteed to not contain duplicates. That is, if using the result to connect to hostname, you should attempt to connect to the first address first, then the second if the first fails, etc. If you are using the result to listen on a socket, it is appropriate to add each result using e.g. g_socket_listener_add_address().

If the DNS resolution fails, error (if non-NULL) will be set to a value from Error and NULL will be returned.

If cancellable is non-NULL, it can be used to cancel the operation, in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.

If you are planning to connect to a socket on the resolved IP address, it may be easier to create a Address and use its Connectable interface.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostname to look up.

The function returns the following values:

  • list: non-empty #GList of Address, or NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.).

func (*Resolver) LookupByNameAsync 

func (resolver *Resolver) LookupByNameAsync(ctx context.Context, hostname string, callback AsyncReadyCallback)

LookupByNameAsync begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls callback, which must call g_resolver_lookup_by_name_finish() to get the result. See g_resolver_lookup_by_name() for more details.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostname to look up the address of.
  • callback (optional) to call after resolution completes.

func (*Resolver) LookupByNameFinish 

func (resolver *Resolver) LookupByNameFinish(result AsyncResulter) ([]*InetAddress, error)

LookupByNameFinish retrieves the result of a call to g_resolver_lookup_by_name_async().

If the DNS resolution failed, error (if non-NULL) will be set to a value from Error. If the operation was cancelled, error will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • list Address, or NULL on error. See g_resolver_lookup_by_name() for more details.

func (*Resolver) LookupByNameWithFlags 

func (resolver *Resolver) LookupByNameWithFlags(ctx context.Context, hostname string, flags ResolverNameLookupFlags) ([]*InetAddress, error)

LookupByNameWithFlags: this differs from g_resolver_lookup_by_name() in that you can modify the lookup behavior with flags. For example this can be used to limit results with G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostname to look up.
  • flags: extra NameLookupFlags for the lookup.

The function returns the following values:

  • list: non-empty #GList of Address, or NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.).

func (*Resolver) LookupByNameWithFlagsAsync 

func (resolver *Resolver) LookupByNameWithFlagsAsync(ctx context.Context, hostname string, flags ResolverNameLookupFlags, callback AsyncReadyCallback)

LookupByNameWithFlagsAsync begins asynchronously resolving hostname to determine its associated IP address(es), and eventually calls callback, which must call g_resolver_lookup_by_name_with_flags_finish() to get the result. See g_resolver_lookup_by_name() for more details.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostname to look up the address of.
  • flags: extra NameLookupFlags for the lookup.
  • callback (optional) to call after resolution completes.

func (*Resolver) LookupByNameWithFlagsFinish 

func (resolver *Resolver) LookupByNameWithFlagsFinish(result AsyncResulter) ([]*InetAddress, error)

LookupByNameWithFlagsFinish retrieves the result of a call to g_resolver_lookup_by_name_with_flags_async().

If the DNS resolution failed, error (if non-NULL) will be set to a value from Error. If the operation was cancelled, error will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • list Address, or NULL on error. See g_resolver_lookup_by_name() for more details.

func (*Resolver) LookupRecords 

func (resolver *Resolver) LookupRecords(ctx context.Context, rrname string, recordType ResolverRecordType) ([]*glib.Variant, error)

LookupRecords: synchronously performs a DNS record lookup for the given rrname and returns a list of records as #GVariant tuples. See RecordType for information on what the records contain for each record_type.

If the DNS resolution fails, error (if non-NULL) will be set to a value from Error and NULL will be returned.

If cancellable is non-NULL, it can be used to cancel the operation, in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • rrname: DNS name to look up the record for.
  • recordType: type of DNS record to look up.

The function returns the following values:

  • list: non-empty #GList of #GVariant, or NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.).

func (*Resolver) LookupRecordsAsync 

func (resolver *Resolver) LookupRecordsAsync(ctx context.Context, rrname string, recordType ResolverRecordType, callback AsyncReadyCallback)

LookupRecordsAsync begins asynchronously performing a DNS lookup for the given rrname, and eventually calls callback, which must call g_resolver_lookup_records_finish() to get the final result. See g_resolver_lookup_records() for more details.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • rrname: DNS name to look up the record for.
  • recordType: type of DNS record to look up.
  • callback (optional) to call after resolution completes.

func (*Resolver) LookupRecordsFinish 

func (resolver *Resolver) LookupRecordsFinish(result AsyncResulter) ([]*glib.Variant, error)

LookupRecordsFinish retrieves the result of a previous call to g_resolver_lookup_records_async(). Returns a non-empty list of records as #GVariant tuples. See RecordType for information on what the records contain.

If the DNS resolution failed, error (if non-NULL) will be set to a value from Error. If the operation was cancelled, error will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • list: non-empty #GList of #GVariant, or NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.).

func (*Resolver) LookupService 

func (resolver *Resolver) LookupService(ctx context.Context, service, protocol, domain string) ([]*SrvTarget, error)

LookupService: synchronously performs a DNS SRV lookup for the given service and protocol in the given domain and returns an array of Target. domain may be an ASCII-only or UTF-8 hostname. Note also that the service and protocol arguments do not include the leading underscore that appears in the actual DNS entry.

On success, g_resolver_lookup_service() will return a non-empty #GList of Target, sorted in order of preference. (That is, you should attempt to connect to the first target first, then the second if the first fails, etc.)

If the DNS resolution fails, error (if non-NULL) will be set to a value from Error and NULL will be returned.

If cancellable is non-NULL, it can be used to cancel the operation, in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.

If you are planning to connect to the service, it is usually easier to create a Service and use its Connectable interface.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • service type to look up (eg, "ldap").
  • protocol: networking protocol to use for service (eg, "tcp").
  • domain: DNS domain to look up the service in.

The function returns the following values:

  • list: non-empty #GList of Target, or NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.).

func (*Resolver) LookupServiceAsync 

func (resolver *Resolver) LookupServiceAsync(ctx context.Context, service, protocol, domain string, callback AsyncReadyCallback)

LookupServiceAsync begins asynchronously performing a DNS SRV lookup for the given service and protocol in the given domain, and eventually calls callback, which must call g_resolver_lookup_service_finish() to get the final result. See g_resolver_lookup_service() for more details.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • service type to look up (eg, "ldap").
  • protocol: networking protocol to use for service (eg, "tcp").
  • domain: DNS domain to look up the service in.
  • callback (optional) to call after resolution completes.

func (*Resolver) LookupServiceFinish 

func (resolver *Resolver) LookupServiceFinish(result AsyncResulter) ([]*SrvTarget, error)

LookupServiceFinish retrieves the result of a previous call to g_resolver_lookup_service_async().

If the DNS resolution failed, error (if non-NULL) will be set to a value from Error. If the operation was cancelled, error will be set to G_IO_ERROR_CANCELLED.

The function takes the following parameters:

  • result passed to your ReadyCallback.

The function returns the following values:

  • list: non-empty #GList of Target, or NULL on error. See g_resolver_lookup_service() for more details.

func (*Resolver) SetDefault 

func (resolver *Resolver) SetDefault()

SetDefault sets resolver to be the application's default resolver (reffing resolver, and unreffing the previous default resolver, if any). Future calls to g_resolver_get_default() will return this resolver.

This can be used if an application wants to perform any sort of DNS caching or "pinning"; it can implement its own #GResolver that calls the original default resolver for DNS operations, and implements its own cache policies on top of that, and then set itself as the default resolver for all later code to use.

func (*Resolver) SetTimeout added in v0.3.0 

func (resolver *Resolver) SetTimeout(timeoutMs uint)

SetTimeout: set the timeout applied to all resolver lookups. See #GResolver:timeout.

The function takes the following parameters:

  • timeoutMs: timeout in milliseconds, or 0 for no timeouts.

func (*Resolver) Timeout added in v0.3.0 

func (resolver *Resolver) Timeout() uint

Timeout: get the timeout applied to all resolver lookups. See #GResolver:timeout.

The function returns the following values:

  • guint: resolver timeout, in milliseconds, or 0 for no timeout.

type ResolverClass added in v0.0.5 

type ResolverClass struct {
	// contains filtered or unexported fields
}

ResolverClass: instance of this type is always passed by reference.

type ResolverError 

type ResolverError C.gint

ResolverError: error code used with G_RESOLVER_ERROR in a #GError returned from a #GResolver routine. 

const (
	// ResolverErrorNotFound: requested name/address/service was not found.
	ResolverErrorNotFound ResolverError = iota
	// ResolverErrorTemporaryFailure: requested information could not be looked
	// up due to a network error or similar problem.
	ResolverErrorTemporaryFailure
	// ResolverErrorInternal: unknown error.
	ResolverErrorInternal
)

func (ResolverError) String 

func (r ResolverError) String() string

String returns the name in string for ResolverError.

type ResolverNameLookupFlags 

type ResolverNameLookupFlags C.guint

ResolverNameLookupFlags flags to modify lookup behavior. 

const (
	// ResolverNameLookupFlagsDefault: default behavior (same as
	// g_resolver_lookup_by_name()).
	ResolverNameLookupFlagsDefault ResolverNameLookupFlags = 0b0
	// ResolverNameLookupFlagsIPv4Only: only resolve ipv4 addresses.
	ResolverNameLookupFlagsIPv4Only ResolverNameLookupFlags = 0b1
	// ResolverNameLookupFlagsIPv6Only: only resolve ipv6 addresses.
	ResolverNameLookupFlagsIPv6Only ResolverNameLookupFlags = 0b10
)

func (ResolverNameLookupFlags) Has 

func (r ResolverNameLookupFlags) Has(other ResolverNameLookupFlags) bool

Has returns true if r contains other.

func (ResolverNameLookupFlags) String 

func (r ResolverNameLookupFlags) String() string

String returns the names in string for ResolverNameLookupFlags.

type ResolverOverrides added in v0.0.5 

type ResolverOverrides struct {
	// LookupByAddress: synchronously reverse-resolves address to determine its
	// associated hostname.
	//
	// If the DNS resolution fails, error (if non-NULL) will be set to a value
	// from Error.
	//
	// If cancellable is non-NULL, it can be used to cancel the operation,
	// in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - address to reverse-resolve.
	//
	// The function returns the following values:
	//
	//   - utf8: hostname (either ASCII-only, or in ASCII-encoded form), or NULL
	//     on error.
	LookupByAddress func(ctx context.Context, address *InetAddress) (string, error)
	// LookupByAddressFinish retrieves the result of a previous call to
	// g_resolver_lookup_by_address_async().
	//
	// If the DNS resolution failed, error (if non-NULL) will be set to a
	// value from Error. If the operation was cancelled, error will be set to
	// G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - result passed to your ReadyCallback.
	//
	// The function returns the following values:
	//
	//   - utf8: hostname (either ASCII-only, or in ASCII-encoded form), or NULL
	//     on error.
	LookupByAddressFinish func(result AsyncResulter) (string, error)
	// LookupByName: synchronously resolves hostname to determine its associated
	// IP address(es). hostname may be an ASCII-only or UTF-8 hostname, or the
	// textual form of an IP address (in which case this just becomes a wrapper
	// around g_inet_address_new_from_string()).
	//
	// On success, g_resolver_lookup_by_name() will return a non-empty
	// #GList of Address, sorted in order of preference and guaranteed to
	// not contain duplicates. That is, if using the result to connect to
	// hostname, you should attempt to connect to the first address first,
	// then the second if the first fails, etc. If you are using the result
	// to listen on a socket, it is appropriate to add each result using e.g.
	// g_socket_listener_add_address().
	//
	// If the DNS resolution fails, error (if non-NULL) will be set to a value
	// from Error and NULL will be returned.
	//
	// If cancellable is non-NULL, it can be used to cancel the operation,
	// in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.
	//
	// If you are planning to connect to a socket on the resolved IP address,
	// it may be easier to create a Address and use its Connectable interface.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - hostname to look up.
	//
	// The function returns the following values:
	//
	//   - list: non-empty #GList of Address, or NULL on error. You must unref
	//     each of the addresses and free the list when you are done with it.
	//     (You can use g_resolver_free_addresses() to do this.).
	LookupByName func(ctx context.Context, hostname string) ([]*InetAddress, error)
	// LookupByNameFinish retrieves the result of a call to
	// g_resolver_lookup_by_name_async().
	//
	// If the DNS resolution failed, error (if non-NULL) will be set to a
	// value from Error. If the operation was cancelled, error will be set to
	// G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - result passed to your ReadyCallback.
	//
	// The function returns the following values:
	//
	//   - list Address, or NULL on error. See g_resolver_lookup_by_name() for
	//     more details.
	LookupByNameFinish func(result AsyncResulter) ([]*InetAddress, error)
	// LookupByNameWithFlags: this differs from g_resolver_lookup_by_name() in
	// that you can modify the lookup behavior with flags. For example this can
	// be used to limit results with G_RESOLVER_NAME_LOOKUP_FLAGS_IPV4_ONLY.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - hostname to look up.
	//   - flags: extra NameLookupFlags for the lookup.
	//
	// The function returns the following values:
	//
	//   - list: non-empty #GList of Address, or NULL on error. You must unref
	//     each of the addresses and free the list when you are done with it.
	//     (You can use g_resolver_free_addresses() to do this.).
	LookupByNameWithFlags func(ctx context.Context, hostname string, flags ResolverNameLookupFlags) ([]*InetAddress, error)
	// LookupByNameWithFlagsFinish retrieves the result of a call to
	// g_resolver_lookup_by_name_with_flags_async().
	//
	// If the DNS resolution failed, error (if non-NULL) will be set to a
	// value from Error. If the operation was cancelled, error will be set to
	// G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - result passed to your ReadyCallback.
	//
	// The function returns the following values:
	//
	//   - list Address, or NULL on error. See g_resolver_lookup_by_name() for
	//     more details.
	LookupByNameWithFlagsFinish func(result AsyncResulter) ([]*InetAddress, error)
	// LookupRecords: synchronously performs a DNS record lookup for the given
	// rrname and returns a list of records as #GVariant tuples. See RecordType
	// for information on what the records contain for each record_type.
	//
	// If the DNS resolution fails, error (if non-NULL) will be set to a value
	// from Error and NULL will be returned.
	//
	// If cancellable is non-NULL, it can be used to cancel the operation,
	// in which case error (if non-NULL) will be set to G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - rrname: DNS name to look up the record for.
	//   - recordType: type of DNS record to look up.
	//
	// The function returns the following values:
	//
	//   - list: non-empty #GList of #GVariant, or NULL on error. You must
	//     free each of the records and the list when you are done with it.
	//     (You can use g_list_free_full() with g_variant_unref() to do this.).
	LookupRecords func(ctx context.Context, rrname string, recordType ResolverRecordType) ([]*glib.Variant, error)
	// LookupRecordsFinish retrieves the result of a previous call to
	// g_resolver_lookup_records_async(). Returns a non-empty list of records
	// as #GVariant tuples. See RecordType for information on what the records
	// contain.
	//
	// If the DNS resolution failed, error (if non-NULL) will be set to a
	// value from Error. If the operation was cancelled, error will be set to
	// G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - result passed to your ReadyCallback.
	//
	// The function returns the following values:
	//
	//   - list: non-empty #GList of #GVariant, or NULL on error. You must
	//     free each of the records and the list when you are done with it.
	//     (You can use g_list_free_full() with g_variant_unref() to do this.).
	LookupRecordsFinish func(result AsyncResulter) ([]*glib.Variant, error)
	// LookupServiceFinish retrieves the result of a previous call to
	// g_resolver_lookup_service_async().
	//
	// If the DNS resolution failed, error (if non-NULL) will be set to a
	// value from Error. If the operation was cancelled, error will be set to
	// G_IO_ERROR_CANCELLED.
	//
	// The function takes the following parameters:
	//
	//   - result passed to your ReadyCallback.
	//
	// The function returns the following values:
	//
	//   - list: non-empty #GList of Target, or NULL on error. See
	//     g_resolver_lookup_service() for more details.
	LookupServiceFinish func(result AsyncResulter) ([]*SrvTarget, error)
	Reload              func()
}

ResolverOverrides contains methods that are overridable.

type ResolverRecordType 

type ResolverRecordType C.gint

ResolverRecordType: type of record that g_resolver_lookup_records() or g_resolver_lookup_records_async() should retrieve. The records are returned as lists of #GVariant tuples. Each record type has different values in the variant tuples returned.

G_RESOLVER_RECORD_SRV records are returned as variants with the signature (qqqs), containing a guint16 with the priority, a guint16 with the weight, a guint16 with the port, and a string of the hostname.

G_RESOLVER_RECORD_MX records are returned as variants with the signature (qs), representing a guint16 with the preference, and a string containing the mail exchanger hostname.

G_RESOLVER_RECORD_TXT records are returned as variants with the signature (as), representing an array of the strings in the text record. Note: Most TXT records only contain a single string, but RFC 1035 (https://tools.ietf.org/html/rfc1035#section-3.3.14) does allow a record to contain multiple strings. The RFC which defines the interpretation of a specific TXT record will likely require concatenation of multiple strings if they are present, as with RFC 7208 (https://tools.ietf.org/html/rfc7208#section-3.3).

G_RESOLVER_RECORD_SOA records are returned as variants with the signature (ssuuuuu), representing a string containing the primary name server, a string containing the administrator, the serial as a guint32, the refresh interval as a guint32, the retry interval as a guint32, the expire timeout as a guint32, and the TTL as a guint32.

G_RESOLVER_RECORD_NS records are returned as variants with the signature (s), representing a string of the hostname of the name server. 

const (
	// ResolverRecordSrv: look up DNS SRV records for a domain.
	ResolverRecordSrv ResolverRecordType = 1
	// ResolverRecordMx: look up DNS MX records for a domain.
	ResolverRecordMx ResolverRecordType = 2
	// ResolverRecordTxt: look up DNS TXT records for a name.
	ResolverRecordTxt ResolverRecordType = 3
	// ResolverRecordSoa: look up DNS SOA records for a zone.
	ResolverRecordSoa ResolverRecordType = 4
	// ResolverRecordNs: look up DNS NS records for a domain.
	ResolverRecordNs ResolverRecordType = 5
)

func (ResolverRecordType) String 

func (r ResolverRecordType) String() string

String returns the name in string for ResolverRecordType.

type Resolverer 

type Resolverer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

Resolverer describes types inherited from class Resolver.

To get the original type, the caller must assert this to an interface or another type.

func ResolverGetDefault 

func ResolverGetDefault() Resolverer

ResolverGetDefault gets the default #GResolver. You should unref it when you are done with it. #GResolver may use its reference count as a hint about how many threads it should allocate for concurrent DNS resolutions.

The function returns the following values:

  • resolver: default #GResolver.

type Resource 

type Resource struct {
	// contains filtered or unexported fields
}

Resource applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance GtkBuilder (https://docs.gtk.org/gtk4/class.Builder.html) .ui files, splashscreen images, gio.Menu 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 (glib-compile-resources.html) program provide a convenient and efficient alternative to this which has some nice properties. You maintain the files as normal files, so it’s 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 (man:xmllint(1)) command to strip ignorable whitespace from the XML file. For this to work, the XMLLINT environment variable must be set to the full path to the xmllint executable, or xmllint must be in the PATH; otherwise the preprocessing step is skipped.

  • to-pixdata (deprecated since gdk-pixbuf 2.32) which will use the gdk-pixbuf-pixdata command to convert images to the GdkPixdata (https://docs.gtk.org/gdk-pixbuf/class.Pixdata.html) 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 the GDK_PIXBUF_PIXDATA environment variable must be set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will abort. to-pixdata has been deprecated since gdk-pixbuf 2.32, as GResource supports embedding modern image formats just as well. Instead of using it, embed a PNG or SVG file in your GResource.

  • json-stripblanks which will use the json-glib-format (man:json-glib-format(1)) command to strip ignorable whitespace from the JSON file. For this to work, the JSON_GLIB_FORMAT environment variable must be set to the full path to the json-glib-format executable, or it must be in the PATH; otherwise the preprocessing step is skipped. In addition, at least version 1.6 of json-glib-format is required.

Resource files will be exported in the GResource namespace using the combination of the given prefix and the filename from the file element. The alias attribute can be used to alter the filename to expose them at a 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 (glib-compile-resources.html) 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 (glib-compile-resources.html) to compile the XML to a binary bundle that you can load with gio.Resource().Load. However, it’s more common to use the --generate-source and --generate-header arguments to create a source file and header to link directly into your application. This will generate get_resource(), register_resource() and unregister_resource() functions, prefixed by the --c-name argument passed to glib-compile-resources (glib-compile-resources.html). get_resource() returns the generated GResource object. The register and unregister functions register the resource so its files can be accessed using gio.ResourcesLookupData().

Once a GResource has been created and registered all the data in it can be accessed globally in the process by using API calls like gio.ResourcesOpenStream() to stream the data or gio.ResourcesLookupData() to get a direct pointer to the data. You can also use URIs like resource:///org/gtk/Example/data/splashscreen.png with gio.File to access the resource data.

Some higher-level APIs, such as GtkApplication (https://docs.gtk.org/gtk4/class.Application.html), 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.

Overlays

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 a G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform during resource lookups. It is ignored when running in a setuid process.

A substitution has the form 

/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.

An instance of this type is always passed by reference.

func NewResourceFromData 

func NewResourceFromData(data *glib.Bytes) (*Resource, error)

NewResourceFromData constructs a struct Resource.

func ResourceLoad 

func ResourceLoad(filename string) (*Resource, error)

ResourceLoad loads a binary resource bundle and creates a #GResource representation of it, allowing you to query it for data.

If you want to use this resource in the global resource namespace you need to register it with g_resources_register().

If filename is empty or the data in it is corrupt, G_RESOURCE_ERROR_INTERNAL will be returned. If filename doesn’t exist, or there is an error in reading it, an error from g_mapped_file_new() will be returned.

The function takes the following parameters:

  • filename: path of a filename to load, in the GLib filename encoding.

The function returns the following values:

  • resource: new #GResource, or NULL on error.

func (*Resource) EnumerateChildren 

func (resource *Resource) EnumerateChildren(path string, lookupFlags ResourceLookupFlags) ([]string, error)

EnumerateChildren returns all the names of children at the specified path in the resource. The return result is a NULL terminated list of strings which should be released with g_strfreev().

If path is invalid or does not exist in the #GResource, G_RESOURCE_ERROR_NOT_FOUND will be returned.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • utf8s: array of constant strings.

func (*Resource) Info 

func (resource *Resource) Info(path string, lookupFlags ResourceLookupFlags) (uint, uint32, error)

Info looks for a file at the specified path in the resource and if found returns information about it.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • size (optional): location to place the length of the contents of the file, or NULL if the length is not needed.
  • flags (optional): location to place the flags about the file, or NULL if the length is not needed.

func (*Resource) LookupData 

func (resource *Resource) LookupData(path string, lookupFlags ResourceLookupFlags) (*glib.Bytes, error)

LookupData looks for a file at the specified path in the resource and returns a #GBytes that lets you directly access the data in memory.

The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte is not included in the size of the GBytes.

For uncompressed resource files this is a pointer directly into the resource bundle, which is typically in some readonly data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • bytes or NULL on error. Free the returned object with g_bytes_unref().

func (*Resource) OpenStream 

func (resource *Resource) OpenStream(path string, lookupFlags ResourceLookupFlags) (InputStreamer, error)

OpenStream looks for a file at the specified path in the resource and returns a Stream that lets you read the data.

lookup_flags controls the behaviour of the lookup.

The function takes the following parameters:

  • path: pathname inside the resource.
  • lookupFlags: LookupFlags.

The function returns the following values:

  • inputStream or NULL on error. Free the returned object with g_object_unref().

type ResourceError 

type ResourceError C.gint

ResourceError: error code used with G_RESOURCE_ERROR in a #GError returned from a #GResource routine. 

const (
	// ResourceErrorNotFound: no file was found at the requested path.
	ResourceErrorNotFound ResourceError = iota
	// ResourceErrorInternal: unknown error.
	ResourceErrorInternal
)

func (ResourceError) String 

func (r ResourceError) String() string

String returns the name in string for ResourceError.

type ResourceFlags 

type ResourceFlags C.guint

ResourceFlags give information about a particular file inside a resource bundle. 

const (
	// ResourceFlagsNone: no flags set.
	ResourceFlagsNone ResourceFlags = 0b0
	// ResourceFlagsCompressed: file is compressed.
	ResourceFlagsCompressed ResourceFlags = 0b1
)

func (ResourceFlags) Has 

func (r ResourceFlags) Has(other ResourceFlags) bool

Has returns true if r contains other.

func (ResourceFlags) String 

func (r ResourceFlags) String() string

String returns the names in string for ResourceFlags.

type ResourceLookupFlags 

type ResourceLookupFlags C.guint

ResourceLookupFlags determine how resource path lookups are handled. 

const (
	// ResourceLookupFlagsNone: no flags set.
	ResourceLookupFlagsNone ResourceLookupFlags = 0b0
)

func (ResourceLookupFlags) Has 

func (r ResourceLookupFlags) Has(other ResourceLookupFlags) bool

Has returns true if r contains other.

func (ResourceLookupFlags) String 

func (r ResourceLookupFlags) String() string

String returns the names in string for ResourceLookupFlags.

type Seekable 

type Seekable struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Seekable: GSeekable is implemented by streams (implementations of gio.InputStream or gio.OutputStream) that support seeking.

Seekable streams largely fall into two categories: resizable and fixed-size.

GSeekable on fixed-sized streams is approximately the same as POSIX lseek() (man:lseek(2)) on a block device (for example: attempting to seek past the end of the device is an error). Fixed streams typically cannot be truncated.

GSeekable on resizable streams is approximately the same as POSIX lseek() (man:lseek(2)) on a normal file. Seeking past the end and writing data will usually cause the stream to resize by introducing zero bytes.

Seekable wraps an interface. This means the user can get the underlying type by calling Cast().

func (*Seekable) CanSeek 

func (seekable *Seekable) CanSeek() bool

CanSeek tests if the stream supports the Iface.

The function returns the following values:

  • ok: TRUE if seekable can be seeked. FALSE otherwise.

func (*Seekable) CanTruncate 

func (seekable *Seekable) CanTruncate() bool

CanTruncate tests if the length of the stream can be adjusted with g_seekable_truncate().

The function returns the following values:

  • ok: TRUE if the stream can be truncated, FALSE otherwise.

func (*Seekable) Seek 

func (seekable *Seekable) Seek(ctx context.Context, offset int64, typ glib.SeekType) error

Seek seeks in the stream by the given offset, modified by type.

Attempting to seek past the end of the stream will have different results depending on if the stream is fixed-sized or resizable. If the stream is resizable then seeking past the end and then writing will result in zeros filling the empty space. Seeking past the end of a resizable stream and reading will result in EOF. Seeking past the end of a fixed-sized stream will fail.

Any operation that would result in a negative offset will fail.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • offset: #goffset.
  • typ: Type.

func (*Seekable) Tell 

func (seekable *Seekable) Tell() int64

Tell tells the current position within the stream.

The function returns the following values:

  • gint64: (positive or zero) offset from the beginning of the buffer, zero if the target is not seekable.

func (*Seekable) Truncate 

func (seekable *Seekable) Truncate(ctx context.Context, offset int64) error

Truncate sets the length of the stream to offset. If the stream was previously larger than offset, the extra data is discarded. If the stream was previously shorter than offset, it is extended with NUL ('\0') bytes.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • offset: new length for seekable, in bytes.

type SeekableIface added in v0.0.5 

type SeekableIface struct {
	// contains filtered or unexported fields
}

SeekableIface provides an interface for implementing seekable functionality on I/O Streams.

An instance of this type is always passed by reference.

type Seekabler 

type Seekabler interface {
	coreglib.Objector

	// CanSeek tests if the stream supports the Iface.
	CanSeek() bool
	// CanTruncate tests if the length of the stream can be adjusted with
	// g_seekable_truncate().
	CanTruncate() bool
	// Seek seeks in the stream by the given offset, modified by type.
	Seek(ctx context.Context, offset int64, typ glib.SeekType) error
	// Tell tells the current position within the stream.
	Tell() int64
	// Truncate sets the length of the stream to offset.
	Truncate(ctx context.Context, offset int64) error
}

Seekabler describes Seekable's interface methods.

type Settings 

type Settings struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Settings: 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) a glib.HashTable lookup. Writing settings is also extremely fast in terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings a lot of work can be avoided. For dconf, the D-Bus service doesn’t even need to be started in this case. For this reason, you should only ever modify GSettings keys in response to explicit user action. Particular care should be paid to ensure that modifications are not made during startup — for example, when setting the initial value of preferences widgets. The built-in gio.Settings.Bind() functionality is careful not to write settings in response to notify signals as a result of modifications that it makes to widgets.

When creating a GSettings instance, you have to specify a schema 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 (#relocatable-schemas)’, i.e. not equipped with a fixed path. This is useful e.g. when the schema describes an ‘account’, and you want to be 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 glib.Variant, and allows any glib.VariantType for keys. Key names are restricted to lowercase characters, numbers and -. Furthermore, the names must begin with a lowercase character, must not end with a -, and must not contain consecutive dashes.

Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the gettext-domain attribute of the <schemalist> or <schema> elements and the category that is specified in the l10n attribute of the <default> element. The string which is translated includes all text in the <default> element, including any surrounding quotation marks.

The l10n attribute must be set to messages or time, and sets the [locale category for translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). The messages category should be used by default; use time for translatable date or time formats. A translation comment can be added as an XML comment immediately above the <default> element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation context attribute can be set on the <default> element to disambiguate multiple defaults which use the same string.

For example: 

<!-- Translators: A list of words which are not allowed to be typed, in
     GVariant serialization syntax.
     See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
<default l10n='messages' context='Banned words'>['bad', 'words']</default>

Translations of default values must remain syntactically valid serialized glib.Variants (e.g. retaining any surrounding quotation marks) or runtime errors will occur.

GSettings uses schemas in a compact binary form that is created by the glib-compile-schemas (glib-compile-schemas.html) utility. The input is a schema description in an XML format.

A DTD for the gschema XML format can be found here: gschema.dtd (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)

The glib-compile-schemas (glib-compile-schemas.html) tool expects schema files to have the extension .gschema.xml.

At runtime, schemas are identified by their ID (as specified in the id attribute of the <schema> element). The convention for schema IDs is to use a dotted name, similar in style to a D-Bus bus name, e.g. org.gnome.SessionManager. In particular, if the settings are 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 glib.Variant types, keys can have types that have enumerated types. These can be described by a <choice>, <enum> or <flags> element, as seen in the second example below. The underlying type of such a key is string, but you can use gio.Settings.GetEnum(), gio.Settings.SetEnum(), gio.Settings.GetFlags(), gio.Settings.SetFlags() 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 (glib-compile-schemas.html) reads so-called ‘vendor override’ files. These are keyfiles in the same directory as the XML schema sources which can override default values. The schema ID serves as the group name in the key file, and the values are expected in serialized glib.Variant form, as in the following example: 

[org.gtk.Example]
key1='string'
key2=1.5

glib-compile-schemas expects schema files to have the extension .gschema.override.

Binding

A very convenient feature of GSettings lets you bind gobject.Object properties directly to settings, using gio.Settings.Bind(). Once a gobject.Object property has been bound to a setting, changes on either side are automatically propagated to the other side. GSettings handles details like mapping between gobject.Object and glib.Variant types, and preventing infinite cycles.

This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings looks for a boolean property with the name sensitivity and 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 its <schema> element. By using gio.Settings.NewWithPath, a GSettings object can be instantiated for a relocatable schema, assigning a path to the instance. Paths passed to gio.Settings.NewWithPath 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 as <child> elements 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 to POTFILES.in, assuming gettext 0.19 is in use (the preferred method for translation): 

data/org.foo.MyApp.gschema.xml

Alternatively, if intltool 0.50.1 is in use: 

[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml

GSettings will use gettext to look up translations for the <summary> and <description> elements, and also any <default> elements which have a l10n attribute set. Translations must not be included in the .gschema.xml file by the build system, for example by using intltool XML rules with a .gschema.xml.in template.

If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an <enum> element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant Makefile.am: 

gsettings_ENUM_NAMESPACE = org.foo.MyApp
gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h

gsettings_ENUM_NAMESPACE specifies the schema namespace for the enum files, which are specified in gsettings_ENUM_FILES. This will generate a org.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 in EXTRA_DIST.

func NewSettings 

func NewSettings(schemaId string) *Settings

NewSettings creates a new #GSettings object with the schema specified by schema_id.

It is an error for the schema to not exist: schemas are an essential part of a program, as they provide type information. If schemas need to be dynamically loaded (for example, from an optional runtime dependency), g_settings_schema_source_lookup() can be used to test for their existence before loading them.

Signals on the newly created #GSettings object will be dispatched via the thread-default Context in effect at the time of the call to g_settings_new(). The new #GSettings will hold a reference on the context. See g_main_context_push_thread_default().

The function takes the following parameters:

  • schemaId: id of the schema.

The function returns the following values:

  • settings: new #GSettings object.

func NewSettingsWithPath 

func NewSettingsWithPath(schemaId, path string) *Settings

NewSettingsWithPath creates a new #GSettings object with the relocatable schema specified by schema_id and a given path.

You only need to do this if you want to directly create a settings object with a schema that doesn't have a specified path of its own. That's quite rare.

It is a programmer error to call this function for a schema that has an explicitly specified path.

It is a programmer error if path is not a valid path. A valid path begins and ends with '/' and does not contain two consecutive '/' characters.

The function takes the following parameters:

  • schemaId: id of the schema.
  • path to use.

The function returns the following values:

  • settings: new #GSettings object.

func (*Settings) Apply 

func (settings *Settings) Apply()

Apply applies any changes that have been made to the settings. This function does nothing unless settings is in 'delay-apply' mode; see g_settings_delay(). In the normal case settings are always applied immediately.

func (*Settings) Bind 

func (settings *Settings) Bind(key string, object *coreglib.Object, property string, flags SettingsBindFlags)

Bind: create a binding between the key in the settings object and the property property of object.

The binding uses the default GIO mapping functions to map between the settings and property values. These functions handle booleans, numeric types and string types in a straightforward way. Use g_settings_bind_with_mapping() if you need a custom mapping, or map between types that are not supported by the default mapping functions.

Unless the flags include G_SETTINGS_BIND_NO_SENSITIVITY, this function also establishes a binding between the writability of key and the "sensitive" property of object (if object has a boolean property by that name). See g_settings_bind_writable() for more details about writable bindings.

Note that the lifecycle of the binding is tied to object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one.

The function takes the following parameters:

  • key to bind.
  • object: #GObject.
  • property: name of the property to bind.
  • flags for the binding.

func (*Settings) BindWritable 

func (settings *Settings) BindWritable(key string, object *coreglib.Object, property string, inverted bool)

BindWritable: create a binding between the writability of key in the settings object and the property property of object. The property must be boolean; "sensitive" or "visible" properties of widgets are the most likely candidates.

Writable bindings are always uni-directional; changes of the writability of the setting will be propagated to the object property, not the other way.

When the inverted argument is TRUE, the binding inverts the value as it passes from the setting to the object, i.e. property will be set to TRUE if the key is not writable.

Note that the lifecycle of the binding is tied to object, and that you can have only one binding per object property. If you bind the same property twice on the same object, the second binding overrides the first one.

The function takes the following parameters:

  • key to bind.
  • object: #GObject.
  • property: name of a boolean property to bind.
  • inverted: whether to 'invert' the value.

func (*Settings) Boolean 

func (settings *Settings) Boolean(key string) bool

Boolean gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for booleans.

It is a programmer error to give a key that isn't specified as having a boolean type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • ok: boolean.

func (*Settings) Child 

func (settings *Settings) Child(name string) *Settings

Child creates a child settings object which has a base path of base-path/name, where base-path is the base path of settings.

The schema for the child settings object must have been declared in the schema of settings using a <child> element.

The created child settings object will inherit the #GSettings:delay-apply mode from settings.

The function takes the following parameters:

  • name of the child schema.

The function returns the following values:

  • ret: 'child' settings object.

func (*Settings) ConnectChangeEvent 

func (settings *Settings) ConnectChangeEvent(f func(keys []glib.Quark) (ok bool)) coreglib.SignalHandle

ConnectChangeEvent: "change-event" signal is emitted once per change event that affects this settings object. You should connect to this signal only if you are interested in viewing groups of changes before they are split out into multiple emissions of the "changed" signal. For most use cases it is more appropriate to use the "changed" signal.

In the event that the change event applies to one or more specified keys, keys will be an array of #GQuark of length n_keys. In the event that the change event applies to the #GSettings object as a whole (ie: potentially every key has been changed) then keys will be NULL and n_keys will be 0.

The default handler for this signal invokes the "changed" signal for each affected key. If any other connected handler returns TRUE then this default functionality will be suppressed.

func (*Settings) ConnectChanged 

func (settings *Settings) ConnectChanged(f func(key string)) coreglib.SignalHandle

ConnectChanged: "changed" signal is emitted when a key has potentially changed. You should call one of the g_settings_get() calls to check the new value.

This signal supports detailed connections. You can connect to the detailed signal "changed::x" in order to only receive callbacks when key "x" changes.

Note that settings only emits this signal if you have read key at least once while a signal handler was already connected for key.

func (*Settings) ConnectWritableChangeEvent 

func (settings *Settings) ConnectWritableChangeEvent(f func(key uint) (ok bool)) coreglib.SignalHandle

ConnectWritableChangeEvent: "writable-change-event" signal is emitted once per writability change event that affects this settings object. You should connect to this signal if you are interested in viewing groups of changes before they are split out into multiple emissions of the "writable-changed" signal. For most use cases it is more appropriate to use the "writable-changed" signal.

In the event that the writability change applies only to a single key, key will be set to the #GQuark for that key. In the event that the writability change affects the entire settings object, key will be 0.

The default handler for this signal invokes the "writable-changed" and "changed" signals for each affected key. This is done because changes in writability might also imply changes in value (if for example, a new mandatory setting is introduced). If any other connected handler returns TRUE then this default functionality will be suppressed.

func (*Settings) ConnectWritableChanged 

func (settings *Settings) ConnectWritableChanged(f func(key string)) coreglib.SignalHandle

ConnectWritableChanged: "writable-changed" signal is emitted when the writability of a key has potentially changed. You should call g_settings_is_writable() in order to determine the new status.

This signal supports detailed connections. You can connect to the detailed signal "writable-changed::x" in order to only receive callbacks when the writability of "x" changes.

func (*Settings) CreateAction 

func (settings *Settings) CreateAction(key string) *Action

CreateAction creates a #GAction corresponding to a given #GSettings key.

The action has the same name as the key.

The value of the key becomes the state of the action and the action is enabled when the key is writable. Changing the state of the action results in the key being written to. Changes to the value or writability of the key cause appropriate change notifications to be emitted for the action.

For boolean-valued keys, action activations take no parameter and result in the toggling of the value. For all other types, activations take the new value for the key (which must have the correct type).

The function takes the following parameters:

  • key: name of a key in settings.

The function returns the following values:

  • action: new #GAction.

func (*Settings) DefaultValue 

func (settings *Settings) DefaultValue(key string) *glib.Variant

DefaultValue gets the "default value" of a key.

This is the value that would be read if g_settings_reset() were to be called on the key.

Note that this may be a different value than returned by g_settings_schema_key_get_default_value() if the system administrator has provided a default value.

Comparing the return values of g_settings_get_default_value() and g_settings_get_value() is not sufficient for determining if a value has been set because the user may have explicitly set the value to something that happens to be equal to the default. The difference here is that if the default changes in the future, the user's key will still be set.

This function may be useful for adding an indication to a UI of what the default value was before the user set it.

It is a programmer error to give a key that isn't contained in the schema for settings.

The function takes the following parameters:

  • key to get the default value for.

The function returns the following values:

  • variant (optional): default value.

func (*Settings) Delay 

func (settings *Settings) Delay()

Delay changes the #GSettings object into 'delay-apply' mode. In this mode, changes to settings are not immediately propagated to the backend, but kept locally until g_settings_apply() is called.

func (*Settings) Double 

func (settings *Settings) Double(key string) float64

Double gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for doubles.

It is a programmer error to give a key that isn't specified as having a 'double' type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • gdouble: double.

func (*Settings) Enum 

func (settings *Settings) Enum(key string) int

Enum gets the value that is stored in settings for key and converts it to the enum value that it represents.

In order to use this function the type of the value must be a string and it must be marked in the schema file as an enumerated type.

It is a programmer error to give a key that isn't contained in the schema for settings or is not marked as an enumerated type.

If the value stored in the configuration database is not a valid value for the enumerated type then this function will return the default value.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • gint: enum value.

func (*Settings) Flags 

func (settings *Settings) Flags(key string) uint

Flags gets the value that is stored in settings for key and converts it to the flags value that it represents.

In order to use this function the type of the value must be an array of strings and it must be marked in the schema file as a flags type.

It is a programmer error to give a key that isn't contained in the schema for settings or is not marked as a flags type.

If the value stored in the configuration database is not a valid value for the flags type then this function will return the default value.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • guint flags value.

func (*Settings) HasUnapplied 

func (settings *Settings) HasUnapplied() bool

HasUnapplied returns whether the #GSettings object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode.

The function returns the following values:

  • ok: TRUE if settings has unapplied changes.

func (*Settings) Int 

func (settings *Settings) Int(key string) int

Int gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for 32-bit integers.

It is a programmer error to give a key that isn't specified as having a int32 type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • gint: integer.

func (*Settings) Int64 

func (settings *Settings) Int64(key string) int64

Int64 gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for 64-bit integers.

It is a programmer error to give a key that isn't specified as having a int64 type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • gint64: 64-bit integer.

func (*Settings) IsWritable 

func (settings *Settings) IsWritable(name string) bool

IsWritable finds out if a key can be written or not.

The function takes the following parameters:

  • name of a key.

The function returns the following values:

  • ok: TRUE if the key name is writable.

func (*Settings) ListChildren 

func (settings *Settings) ListChildren() []string

ListChildren gets the list of children on settings.

The list is exactly the list of strings for which it is not an error to call g_settings_get_child().

There is little reason to call this function from "normal" code, since you should already know what children are in your schema. This function may still be useful there for introspection reasons, however.

You should free the return value with g_strfreev() when you are done with it.

The function returns the following values:

  • utf8s: list of the children on settings, in no defined order.

func (*Settings) ListKeys deprecated 

func (settings *Settings) ListKeys() []string

ListKeys introspects the list of keys on settings.

You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons.

You should free the return value with g_strfreev() when you are done with it.

Deprecated: Use g_settings_schema_list_keys() instead.

The function returns the following values:

  • utf8s: list of the keys on settings, in no defined order.

func (*Settings) Mapped 

func (settings *Settings) Mapped(key string, mapping SettingsGetMapping) unsafe.Pointer

Mapped gets the value that is stored at key in settings, subject to application-level validation/mapping.

You should use this function when the application needs to perform some processing on the value of the key (for example, parsing). The mapping function performs that processing. If the function indicates that the processing was unsuccessful (due to a parse error, for example) then the mapping is tried again with another value.

This allows a robust 'fall back to defaults' behaviour to be implemented somewhat automatically.

The first value that is tried is the user's setting for the key. If the mapping function fails to map this value, other values may be tried in an unspecified order (system or site defaults, translated schema default values, untranslated schema default values, etc).

If the mapping function fails for all possible values, one additional attempt is made: the mapping function is called with a NULL value. If the mapping function still indicates failure at this point then the application will be aborted.

The result parameter for the mapping function is pointed to a #gpointer which is initially set to NULL. The same pointer is given to each invocation of mapping. The final value of that #gpointer is what is returned by this function. NULL is valid; it is returned just as any other value would be.

The function takes the following parameters:

  • key to get the value for.
  • mapping: function to map the value in the settings database to the value used by the application.

The function returns the following values:

  • gpointer (optional): result, which may be NULL.

func (*Settings) Range deprecated 

func (settings *Settings) Range(key string) *glib.Variant

Range queries the range of a key.

Deprecated: Use g_settings_schema_key_get_range() instead.

The function takes the following parameters:

  • key to query the range of.

func (*Settings) RangeCheck deprecated 

func (settings *Settings) RangeCheck(key string, value *glib.Variant) bool

RangeCheck checks if the given value is of the correct type and within the permitted range for key.

Deprecated: Use g_settings_schema_key_range_check() instead.

The function takes the following parameters:

  • key to check.
  • value to check.

The function returns the following values:

  • ok: TRUE if value is valid for key.

func (*Settings) Reset 

func (settings *Settings) Reset(key string)

Reset resets key to its default value.

This call resets the key, as much as possible, to its default value. That might be the value specified in the schema or the one set by the administrator.

The function takes the following parameters:

  • key: name of a key.

func (*Settings) Revert 

func (settings *Settings) Revert()

Revert reverts all non-applied changes to the settings. This function does nothing unless settings is in 'delay-apply' mode; see g_settings_delay(). In the normal case settings are always applied immediately.

Change notifications will be emitted for affected keys.

func (*Settings) SetBoolean 

func (settings *Settings) SetBoolean(key string, value bool) bool

SetBoolean sets key in settings to value.

A convenience variant of g_settings_set() for booleans.

It is a programmer error to give a key that isn't specified as having a boolean type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetDouble 

func (settings *Settings) SetDouble(key string, value float64) bool

SetDouble sets key in settings to value.

A convenience variant of g_settings_set() for doubles.

It is a programmer error to give a key that isn't specified as having a 'double' type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetEnum 

func (settings *Settings) SetEnum(key string, value int) bool

SetEnum looks up the enumerated type nick for value and writes it to key, within settings.

It is a programmer error to give a key that isn't contained in the schema for settings or is not marked as an enumerated type, or for value not to be a valid value for the named type.

After performing the write, accessing key directly with g_settings_get_string() will return the 'nick' associated with value.

The function takes the following parameters:

  • key: key, within settings.
  • value: enumerated value.

The function returns the following values:

  • ok: TRUE, if the set succeeds.

func (*Settings) SetFlags 

func (settings *Settings) SetFlags(key string, value uint) bool

SetFlags looks up the flags type nicks for the bits specified by value, puts them in an array of strings and writes the array to key, within settings.

It is a programmer error to give a key that isn't contained in the schema for settings or is not marked as a flags type, or for value to contain any bits that are not value for the named type.

After performing the write, accessing key directly with g_settings_get_strv() will return an array of 'nicks'; one for each bit in value.

The function takes the following parameters:

  • key: key, within settings.
  • value flags value.

The function returns the following values:

  • ok: TRUE, if the set succeeds.

func (*Settings) SetInt 

func (settings *Settings) SetInt(key string, value int) bool

SetInt sets key in settings to value.

A convenience variant of g_settings_set() for 32-bit integers.

It is a programmer error to give a key that isn't specified as having a int32 type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetInt64 

func (settings *Settings) SetInt64(key string, value int64) bool

SetInt64 sets key in settings to value.

A convenience variant of g_settings_set() for 64-bit integers.

It is a programmer error to give a key that isn't specified as having a int64 type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetString 

func (settings *Settings) SetString(key, value string) bool

SetString sets key in settings to value.

A convenience variant of g_settings_set() for strings.

It is a programmer error to give a key that isn't specified as having a string type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetStrv 

func (settings *Settings) SetStrv(key string, value []string) bool

SetStrv sets key in settings to value.

A convenience variant of g_settings_set() for string arrays. If value is NULL, then key is set to be the empty array.

It is a programmer error to give a key that isn't specified as having an array of strings type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value (optional) to set it to, or NULL.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetUint 

func (settings *Settings) SetUint(key string, value uint) bool

SetUint sets key in settings to value.

A convenience variant of g_settings_set() for 32-bit unsigned integers.

It is a programmer error to give a key that isn't specified as having a uint32 type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetUint64 

func (settings *Settings) SetUint64(key string, value uint64) bool

SetUint64 sets key in settings to value.

A convenience variant of g_settings_set() for 64-bit unsigned integers.

It is a programmer error to give a key that isn't specified as having a uint64 type in the schema for settings.

The function takes the following parameters:

  • key: name of the key to set.
  • value to set it to.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) SetValue 

func (settings *Settings) SetValue(key string, value *glib.Variant) bool

SetValue sets key in settings to value.

It is a programmer error to give a key that isn't contained in the schema for settings or for value to have the incorrect type, per the schema.

If value is floating then this function consumes the reference.

The function takes the following parameters:

  • key: name of the key to set.
  • value of the correct type.

The function returns the following values:

  • ok: TRUE if setting the key succeeded, FALSE if the key was not writable.

func (*Settings) String 

func (settings *Settings) String(key string) string

String gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for strings.

It is a programmer error to give a key that isn't specified as having a string type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • utf8: newly-allocated string.

func (*Settings) Strv 

func (settings *Settings) Strv(key string) []string

Strv: convenience variant of g_settings_get() for string arrays.

It is a programmer error to give a key that isn't specified as having an array of strings type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • utf8s: a newly-allocated, NULL-terminated array of strings, the value that is stored at key in settings.

func (*Settings) Uint 

func (settings *Settings) Uint(key string) uint

Uint gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for 32-bit unsigned integers.

It is a programmer error to give a key that isn't specified as having a uint32 type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • guint: unsigned integer.

func (*Settings) Uint64 

func (settings *Settings) Uint64(key string) uint64

Uint64 gets the value that is stored at key in settings.

A convenience variant of g_settings_get() for 64-bit unsigned integers.

It is a programmer error to give a key that isn't specified as having a uint64 type in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • guint64: 64-bit unsigned integer.

func (*Settings) UserValue 

func (settings *Settings) UserValue(key string) *glib.Variant

UserValue checks the "user value" of a key, if there is one.

The user value of a key is the last value that was set by the user.

After calling g_settings_reset() this function should always return NULL (assuming something is not wrong with the system configuration).

It is possible that g_settings_get_value() will return a different value than this function. This can happen in the case that the user set a value for a key that was subsequently locked down by the system administrator -- this function will return the user's old value.

This function may be useful for adding a "reset" option to a UI or for providing indication that a particular value has been changed.

It is a programmer error to give a key that isn't contained in the schema for settings.

The function takes the following parameters:

  • key to get the user value for.

The function returns the following values:

  • variant (optional) user's value, if set.

func (*Settings) Value 

func (settings *Settings) Value(key string) *glib.Variant

Value gets the value that is stored in settings for key.

It is a programmer error to give a key that isn't contained in the schema for settings.

The function takes the following parameters:

  • key to get the value for.

The function returns the following values:

  • variant: new #GVariant.

type SettingsBindFlags 

type SettingsBindFlags C.guint

SettingsBindFlags flags used when creating a binding. These flags determine in which direction the binding works. The default is to synchronize in both directions. 

const (
	// SettingsBindDefault: equivalent to
	// G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET.
	SettingsBindDefault SettingsBindFlags = 0b0
	// SettingsBindGet: update the #GObject property when the setting changes.
	// It is an error to use this flag if the property is not writable.
	SettingsBindGet SettingsBindFlags = 0b1
	// SettingsBindSet: update the setting when the #GObject property changes.
	// It is an error to use this flag if the property is not readable.
	SettingsBindSet SettingsBindFlags = 0b10
	// SettingsBindNoSensitivity: do not try to bind a "sensitivity" property to
	// the writability of the setting.
	SettingsBindNoSensitivity SettingsBindFlags = 0b100
	// SettingsBindGetNoChanges: when set in addition to G_SETTINGS_BIND_GET,
	// set the #GObject property value initially from the setting, but do not
	// listen for changes of the setting.
	SettingsBindGetNoChanges SettingsBindFlags = 0b1000
	// SettingsBindInvertBoolean: when passed to g_settings_bind(), uses a pair
	// of mapping functions that invert the boolean value when mapping between
	// the setting and the property. The setting and property must both be
	// booleans. You cannot pass this flag to g_settings_bind_with_mapping().
	SettingsBindInvertBoolean SettingsBindFlags = 0b10000
)

func (SettingsBindFlags) Has 

func (s SettingsBindFlags) Has(other SettingsBindFlags) bool

Has returns true if s contains other.

func (SettingsBindFlags) String 

func (s SettingsBindFlags) String() string

String returns the names in string for SettingsBindFlags.

type SettingsBindGetMapping 

type SettingsBindGetMapping func(value *coreglib.Value, variant *glib.Variant) (ok bool)

SettingsBindGetMapping: type for the function that is used to convert from #GSettings to an object property. The value is already initialized to hold values of the appropriate type.

type SettingsBindSetMapping 

type SettingsBindSetMapping func(value *coreglib.Value, expectedType *glib.VariantType) (variant *glib.Variant)

SettingsBindSetMapping: type for the function that is used to convert an object property value to a #GVariant for storing it in #GSettings.

type SettingsClass added in v0.0.5 

type SettingsClass struct {
	// contains filtered or unexported fields
}

SettingsClass: instance of this type is always passed by reference.

func (*SettingsClass) Padding added in v0.0.5 

func (s *SettingsClass) Padding() [20]unsafe.Pointer

type SettingsGetMapping 

type SettingsGetMapping func(value *glib.Variant) (result unsafe.Pointer, ok bool)

SettingsGetMapping: type of the function that is used to convert from a value stored in a #GSettings to a value that is useful to the application.

If the value is successfully mapped, the result should be stored at result and TRUE returned. If mapping fails (for example, if value is not in the right format) then FALSE should be returned.

If value is NULL then it means that the mapping function is being given a "last chance" to successfully return a valid value. TRUE must be returned in this case.

type SettingsOverrides added in v0.0.5 

type SettingsOverrides struct {
	// The function takes the following parameters:
	//
	//   - keys
	//   - nKeys
	ChangeEvent         func(keys *glib.Quark, nKeys int) bool
	Changed             func(key string)
	WritableChangeEvent func(key glib.Quark) bool
	WritableChanged     func(key string)
}

SettingsOverrides contains methods that are overridable.

type SettingsSchema 

type SettingsSchema struct {
	// contains filtered or unexported fields
}

SettingsSchema: gio.SettingsSchemaSource and GSettingsSchema 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.

gio.SettingsSchemaSource provides a mechanism for dealing with this by allowing the creation of a new ‘schema source’ from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings.

Consider the following example: 

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: 

{
  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.

An instance of this type is always passed by reference.

func (*SettingsSchema) HasKey 

func (schema *SettingsSchema) HasKey(name string) bool

HasKey checks if schema has a key named name.

The function takes the following parameters:

  • name of a key.

The function returns the following values:

  • ok: TRUE if such a key exists.

func (*SettingsSchema) ID 

func (schema *SettingsSchema) ID() string

ID: get the ID of schema.

The function returns the following values:

  • utf8: ID.

func (*SettingsSchema) Key 

func (schema *SettingsSchema) Key(name string) *SettingsSchemaKey

Key gets the key named name from schema.

It is a programmer error to request a key that does not exist. See g_settings_schema_list_keys().

The function takes the following parameters:

  • name of a key.

The function returns the following values:

  • settingsSchemaKey for name.

func (*SettingsSchema) ListChildren 

func (schema *SettingsSchema) ListChildren() []string

ListChildren gets the list of children in schema.

You should free the return value with g_strfreev() when you are done with it.

The function returns the following values:

  • utf8s: list of the children on settings, in no defined order.

func (*SettingsSchema) ListKeys 

func (schema *SettingsSchema) ListKeys() []string

ListKeys introspects the list of keys on schema.

You should probably not be calling this function from "normal" code (since you should already know what keys are in your schema). This function is intended for introspection reasons.

The function returns the following values:

  • utf8s: list of the keys on schema, in no defined order.

func (*SettingsSchema) Path 

func (schema *SettingsSchema) Path() string

Path gets the path associated with schema, or NULL.

Schemas may be single-instance or relocatable. Single-instance schemas correspond to exactly one set of keys in the backend database: those located at the path returned by this function.

Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return NULL.

The function returns the following values:

  • utf8 (optional): path of the schema, or NULL.

type SettingsSchemaKey 

type SettingsSchemaKey struct {
	// contains filtered or unexported fields
}

SettingsSchemaKey is an opaque data structure and can only be accessed using the following functions.

An instance of this type is always passed by reference.

func (*SettingsSchemaKey) DefaultValue 

func (key *SettingsSchemaKey) DefaultValue() *glib.Variant

DefaultValue gets the default value for key.

Note that this is the default value according to the schema. System administrator defaults and lockdown are not visible via this API.

The function returns the following values:

  • variant: default value for the key.

func (*SettingsSchemaKey) Description 

func (key *SettingsSchemaKey) Description() string

Description gets the description for key.

If no description has been provided in the schema for key, returns NULL.

The description can be one sentence to several paragraphs in length. Paragraphs are delimited with a double newline. Descriptions can be translated and the value returned from this function is is the current locale.

This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory.

The function returns the following values:

  • utf8 (optional): description for key, or NULL.

func (*SettingsSchemaKey) Name 

func (key *SettingsSchemaKey) Name() string

Name gets the name of key.

The function returns the following values:

  • utf8: name of key.

func (*SettingsSchemaKey) Range 

func (key *SettingsSchemaKey) Range() *glib.Variant

Range queries the range of a key.

This function will return a #GVariant that fully describes the range of values that are valid for key.

The type of #GVariant returned is (sv). The string describes the type of range restriction in effect. The type and meaning of the value contained in the variant depends on the string.

If the string is 'type' then the variant contains an empty array. The element type of that empty array is the expected type of value and all values of that type are valid.

If the string is 'enum' then the variant contains an array enumerating the possible values. Each item in the array is a possible valid value and no other values are valid.

If the string is 'flags' then the variant contains an array. Each item in the array is a value that may appear zero or one times in an array to be used as the value for this key. For example, if the variant contained the array ['x', 'y'] then the valid values for the key would be [], ['x'], ['y'], ['x', 'y'] and ['y', 'x'].

Finally, if the string is 'range' then the variant contains a pair of like-typed values -- the minimum and maximum permissible values for this key.

This information should not be used by normal programs. It is considered to be a hint for introspection purposes. Normal programs should already know what is permitted by their own schema. The format may change in any way in the future -- but particularly, new forms may be added to the possibilities described above.

You should free the returned value with g_variant_unref() when it is no longer needed.

The function returns the following values:

  • variant describing the range.

func (*SettingsSchemaKey) RangeCheck 

func (key *SettingsSchemaKey) RangeCheck(value *glib.Variant) bool

RangeCheck checks if the given value is within the permitted range for key.

It is a programmer error if value is not of the correct type — you must check for this first.

The function takes the following parameters:

  • value to check.

The function returns the following values:

  • ok: TRUE if value is valid for key.

func (*SettingsSchemaKey) Summary 

func (key *SettingsSchemaKey) Summary() string

Summary gets the summary for key.

If no summary has been provided in the schema for key, returns NULL.

The summary is a short description of the purpose of the key; usually one short sentence. Summaries can be translated and the value returned from this function is is the current locale.

This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory.

The function returns the following values:

  • utf8 (optional): summary for key, or NULL.

func (*SettingsSchemaKey) ValueType 

func (key *SettingsSchemaKey) ValueType() *glib.VariantType

ValueType gets the Type of key.

The function returns the following values:

  • variantType: type of key.

type SettingsSchemaSource 

type SettingsSchemaSource struct {
	// contains filtered or unexported fields
}

SettingsSchemaSource: this is an opaque structure type. You may not access it directly.

An instance of this type is always passed by reference.

func NewSettingsSchemaSourceFromDirectory 

func NewSettingsSchemaSourceFromDirectory(directory string, parent *SettingsSchemaSource, trusted bool) (*SettingsSchemaSource, error)

NewSettingsSchemaSourceFromDirectory constructs a struct SettingsSchemaSource.

func SettingsSchemaSourceGetDefault 

func SettingsSchemaSourceGetDefault() *SettingsSchemaSource

SettingsSchemaSourceGetDefault gets the default system schema source.

This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas.

If no schemas are installed, NULL will be returned.

The returned source may actually consist of multiple schema sources from different directories, depending on which directories were given in XDG_DATA_DIRS and GSETTINGS_SCHEMA_DIR. For this reason, all lookups performed against the default source should probably be done recursively.

The function returns the following values:

  • settingsSchemaSource (optional): default schema source.

func (*SettingsSchemaSource) ListSchemas 

func (source *SettingsSchemaSource) ListSchemas(recursive bool) (nonRelocatable []string, relocatable []string)

ListSchemas lists the schemas in a given source.

If recursive is TRUE then include parent sources. If FALSE then only include the schemas from one source (ie: one directory). You probably want TRUE.

Non-relocatable schemas are those for which you can call g_settings_new(). Relocatable schemas are those for which you must use g_settings_new_with_path().

Do not call this function from normal programs. This is designed for use by database editors, commandline tools, etc.

The function takes the following parameters:

  • recursive: if we should recurse.

The function returns the following values:

  • nonRelocatable: the list of non-relocatable schemas, in no defined order.
  • relocatable: list of relocatable schemas, in no defined order.

func (*SettingsSchemaSource) Lookup 

func (source *SettingsSchemaSource) Lookup(schemaId string, recursive bool) *SettingsSchema

Lookup looks up a schema with the identifier schema_id in source.

This function is not required for normal uses of #GSettings but it may be useful to authors of plugin management systems or to those who want to introspect the content of schemas.

If the schema isn't found directly in source and recursive is TRUE then the parent sources will also be checked.

If the schema isn't found, NULL is returned.

The function takes the following parameters:

  • schemaId: schema ID.
  • recursive: TRUE if the lookup should be recursive.

The function returns the following values:

  • settingsSchema (optional): new Schema.

type SimpleAction 

type SimpleAction struct {
	*coreglib.Object

	Action
	// contains filtered or unexported fields
}

SimpleAction: GSimpleAction is the obvious simple implementation of the gio.Action interface. This is the easiest way to create an action for purposes of adding it to a gio.SimpleActionGroup.

func NewSimpleAction 

func NewSimpleAction(name string, parameterType *glib.VariantType) *SimpleAction

NewSimpleAction creates a new action.

The created action is stateless. See g_simple_action_new_stateful() to create an action that has state.

The function takes the following parameters:

  • name of the action.
  • parameterType (optional): type of parameter that will be passed to handlers for the Action::activate signal, or NULL for no parameter.

The function returns the following values:

  • simpleAction: new Action.

func NewSimpleActionStateful 

func NewSimpleActionStateful(name string, parameterType *glib.VariantType, state *glib.Variant) *SimpleAction

NewSimpleActionStateful creates a new stateful action.

All future state values must have the same Type as the initial state.

If the state #GVariant is floating, it is consumed.

The function takes the following parameters:

  • name of the action.
  • parameterType (optional): type of the parameter that will be passed to handlers for the Action::activate signal, or NULL for no parameter.
  • state: initial state of the action.

The function returns the following values:

  • simpleAction: new Action.

func (*SimpleAction) ConnectActivate 

func (simple *SimpleAction) ConnectActivate(f func(parameter *glib.Variant)) coreglib.SignalHandle

ConnectActivate indicates that the action was just activated.

parameter will always be of the expected type, i.e. the parameter type specified when the action was created. If an incorrect type is given when activating the action, this signal is not emitted.

Since GLib 2.40, if no handler is connected to this signal then the default behaviour for boolean-stated actions with a NULL parameter type is to toggle them via the Action::change-state signal. For stateful actions where the state type is equal to the parameter type, the default is to forward them directly to Action::change-state. This should allow almost all users of Action to connect only one handler or the other.

func (*SimpleAction) ConnectChangeState 

func (simple *SimpleAction) ConnectChangeState(f func(value *glib.Variant)) coreglib.SignalHandle

ConnectChangeState indicates that the action just received a request to change its state.

value will always be of the correct state type, i.e. the type of the initial state passed to g_simple_action_new_stateful(). If an incorrect type is given when requesting to change the state, this signal is not emitted.

If no handler is connected to this signal then the default behaviour is to call g_simple_action_set_state() to set the state to the requested value. If you connect a signal handler then no default action is taken. If the state should change then you must call g_simple_action_set_state() from the handler.

An example of a 'change-state' handler: 

static void
change_volume_state (GSimpleAction *action,
                     GVariant      *value,
                     gpointer       user_data)
{
  gint requested;

  requested = g_variant_get_int32 (value);

  // Volume only goes from 0 to 10
  if (0 <= requested && requested <= 10)
    g_simple_action_set_state (action, value);
}

The handler need not set the state to the requested value. It could set it to any value at all, or take some other action.

func (*SimpleAction) SetEnabled 

func (simple *SimpleAction) SetEnabled(enabled bool)

SetEnabled sets the action as enabled or not.

An action must be enabled in order to be activated or in order to have its state changed from outside callers.

This should only be called by the implementor of the action. Users of the action should not attempt to modify its enabled flag.

The function takes the following parameters:

  • enabled: whether the action is enabled.

func (*SimpleAction) SetState 

func (simple *SimpleAction) SetState(value *glib.Variant)

SetState sets the state of the action.

This directly updates the 'state' property to the given value.

This should only be called by the implementor of the action. Users of the action should not attempt to directly modify the 'state' property. Instead, they should call g_action_change_state() to request the change.

If the value GVariant is floating, it is consumed.

The function takes the following parameters:

  • value: new #GVariant for the state.

func (*SimpleAction) SetStateHint 

func (simple *SimpleAction) SetStateHint(stateHint *glib.Variant)

SetStateHint sets the state hint for the action.

See g_action_get_state_hint() for more information about action state hints.

The function takes the following parameters:

  • stateHint (optional) representing the state hint.

type SimpleActionGroup 

type SimpleActionGroup struct {
	*coreglib.Object

	ActionGroup
	ActionMap
	// contains filtered or unexported fields
}

SimpleActionGroup: GSimpleActionGroup is a hash table filled with gio.Action objects, implementing the gio.ActionGroup and gio.ActionMap interfaces.

func NewSimpleActionGroup 

func NewSimpleActionGroup() *SimpleActionGroup

NewSimpleActionGroup creates a new, empty, ActionGroup.

The function returns the following values:

  • simpleActionGroup: new ActionGroup.

func (*SimpleActionGroup) AddEntries deprecated 

func (simple *SimpleActionGroup) AddEntries(entries []ActionEntry, userData unsafe.Pointer)

AddEntries: convenience function for creating multiple Action instances and adding them to the action group.

Deprecated: Use g_action_map_add_action_entries().

The function takes the following parameters:

  • entries: pointer to the first item in an array of Entry structs.
  • userData (optional): user data for signal connections.

func (*SimpleActionGroup) Insert deprecated 

func (simple *SimpleActionGroup) Insert(action Actioner)

Insert adds an action to the action group.

If the action group already contains an action with the same name as action then the old action is dropped from the group.

The action group takes its own reference on action.

Deprecated: Use g_action_map_add_action().

The function takes the following parameters:

  • action: #GAction.

func (*SimpleActionGroup) Lookup deprecated 

func (simple *SimpleActionGroup) Lookup(actionName string) *Action

Lookup looks up the action with the name action_name in the group.

If no such action exists, returns NULL.

Deprecated: Use g_action_map_lookup_action().

The function takes the following parameters:

  • actionName: name of an action.

The function returns the following values:

  • action or NULL.

func (*SimpleActionGroup) Remove deprecated 

func (simple *SimpleActionGroup) Remove(actionName string)

Remove removes the named action from the action group.

If no action of this name is in the group then nothing happens.

Deprecated: Use g_action_map_remove_action().

The function takes the following parameters:

  • actionName: name of the action.

type SimpleActionGroupClass added in v0.0.5 

type SimpleActionGroupClass struct {
	// contains filtered or unexported fields
}

SimpleActionGroupClass: instance of this type is always passed by reference.

type SimpleActionGroupOverrides added in v0.0.5 

type SimpleActionGroupOverrides struct {
}

SimpleActionGroupOverrides contains methods that are overridable.

type SimpleAsyncResult 

type SimpleAsyncResult struct {
	*coreglib.Object

	AsyncResult
	// contains filtered or unexported fields
}

SimpleAsyncResult as of GLib 2.46, GSimpleAsyncResult is deprecated in favor of gio.Task, which provides a simpler API.

GSimpleAsyncResult implements gio.AsyncResult.

GSimpleAsyncResult handles gio.AsyncReadyCallbacks, 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 a gssize 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 gio.AsyncResult’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, call gio.SimpleAsyncResult.New. If the result needs to be created for a GError, use gio.SimpleAsyncResult.NewFromError or gio.SimpleAsyncResult.NewTakeError. If a GError is not available (e.g. the asynchronous operation doesn’t take a GError argument), but the result still needs to be created for an error condition, use gio.SimpleAsyncResult.NewError (or gio.SimpleAsyncResult.SetErrorVa() if your application or binding requires passing a variable argument list directly), and the error can then be propagated through the use of gio.SimpleAsyncResult.PropagateError().

An asynchronous operation can be made to ignore a cancellation event by calling gio.SimpleAsyncResult.SetHandleCancellation() with a GSimpleAsyncResult for the operation and FALSE. 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, glib.MainLoop, or it can use glib.Threads. gio.SimpleAsyncResult.Complete() will finish an I/O task directly from the point where it is called. gio.SimpleAsyncResult.CompleteInIdle() will finish it from an idle handler in the thread-default main context (see glib.MainContext.PushThreadDefault()) where the GSimpleAsyncResult was created. gio.SimpleAsyncResult.RunInThread() will run the job in a separate thread and then use gio.SimpleAsyncResult.CompleteInIdle() to deliver the result.

To set the results of an asynchronous function, gio.SimpleAsyncResult.SetOpResGpointer(), gio.SimpleAsyncResult.SetOpResGboolean(), and gio.SimpleAsyncResult.SetOpResGssize() are provided, setting the operation's result to a gpointer, gboolean, or gssize, respectively.

Likewise, to get the result of an asynchronous function, gio.SimpleAsyncResult.GetOpResGpointer(), gio.SimpleAsyncResult.GetOpResGboolean(), and gio.SimpleAsyncResult.GetOpResGssize() are provided, getting the operation’s result as a gpointer, gboolean, and gssize, respectively.

For the details of the requirements implementations must respect, see gio.AsyncResult. A typical implementation of an asynchronous operation using GSimpleAsyncResult looks something like this: 

static 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);
}.

func NewSimpleAsyncResult deprecated 

func NewSimpleAsyncResult(sourceObject *coreglib.Object, callback AsyncReadyCallback, sourceTag unsafe.Pointer) *SimpleAsyncResult

NewSimpleAsyncResult creates a AsyncResult.

The common convention is to create the AsyncResult in the function that starts the asynchronous operation and use that same function as the source_tag.

If your operation supports cancellation with #GCancellable (which it probably should) then you should provide the user's cancellable to g_simple_async_result_set_check_cancellable() immediately after this function returns.

Deprecated: Use g_task_new() instead.

The function takes the following parameters:

  • sourceObject (optional) or NULL.
  • callback (optional): ReadyCallback.
  • sourceTag (optional) asynchronous function.

The function returns the following values:

  • simpleAsyncResult: AsyncResult.

func NewSimpleAsyncResultFromError deprecated 

func NewSimpleAsyncResultFromError(sourceObject *coreglib.Object, callback AsyncReadyCallback, err error) *SimpleAsyncResult

NewSimpleAsyncResultFromError creates a AsyncResult from an error condition.

Deprecated: Use g_task_new() and g_task_return_error() instead.

The function takes the following parameters:

  • sourceObject (optional) or NULL.
  • callback (optional): ReadyCallback.
  • err: #GError.

The function returns the following values:

  • simpleAsyncResult: AsyncResult.

func (*SimpleAsyncResult) Complete deprecated 

func (simple *SimpleAsyncResult) Complete()

Complete completes an asynchronous I/O job immediately. Must be called in the thread where the asynchronous result was to be delivered, as it invokes the callback directly. If you are in a different thread use g_simple_async_result_complete_in_idle().

Calling this function takes a reference to simple for as long as is needed to complete the call.

Deprecated: Use #GTask instead.

func (*SimpleAsyncResult) CompleteInIdle deprecated 

func (simple *SimpleAsyncResult) CompleteInIdle()

CompleteInIdle completes an asynchronous function in an idle handler in the [thread-default main context][g-main-context-push-thread-default] of the thread that simple was initially created in (and re-pushes that context around the invocation of the callback).

Calling this function takes a reference to simple for as long as is needed to complete the call.

Deprecated: Use #GTask instead.

func (*SimpleAsyncResult) OpResGboolean deprecated 

func (simple *SimpleAsyncResult) OpResGboolean() bool

OpResGboolean gets the operation result boolean from within the asynchronous result.

Deprecated: Use #GTask and g_task_propagate_boolean() instead.

The function returns the following values:

  • ok: TRUE if the operation's result was TRUE, FALSE if the operation's result was FALSE.

func (*SimpleAsyncResult) OpResGssize deprecated 

func (simple *SimpleAsyncResult) OpResGssize() int

OpResGssize gets a gssize from the asynchronous result.

Deprecated: Use #GTask and g_task_propagate_int() instead.

The function returns the following values:

  • gssize returned from the asynchronous function.

func (*SimpleAsyncResult) PropagateError deprecated 

func (simple *SimpleAsyncResult) PropagateError() error

PropagateError propagates an error from within the simple asynchronous result to a given destination.

If the #GCancellable given to a prior call to g_simple_async_result_set_check_cancellable() is cancelled then this function will return TRUE with dest set appropriately.

Deprecated: Use #GTask instead.

func (*SimpleAsyncResult) SetCheckCancellable deprecated 

func (simple *SimpleAsyncResult) SetCheckCancellable(ctx context.Context)

SetCheckCancellable sets a #GCancellable to check before dispatching results.

This function has one very specific purpose: the provided cancellable is checked at the time of g_simple_async_result_propagate_error() If it is cancelled, these functions will return an "Operation was cancelled" error (G_IO_ERROR_CANCELLED).

Implementors of cancellable asynchronous functions should use this in order to provide a guarantee to their callers that cancelling an async operation will reliably result in an error being returned for that operation (even if a positive result for the operation has already been sent as an idle to the main context to be dispatched).

The checking described above is done regardless of any call to the unrelated g_simple_async_result_set_handle_cancellation() function.

Deprecated: Use #GTask instead.

The function takes the following parameters:

  • ctx (optional) to check, or NULL to unset.

func (*SimpleAsyncResult) SetFromError deprecated 

func (simple *SimpleAsyncResult) SetFromError(err error)

SetFromError sets the result from a #GError.

Deprecated: Use #GTask and g_task_return_error() instead.

The function takes the following parameters:

  • err: #GError.

func (*SimpleAsyncResult) SetHandleCancellation deprecated 

func (simple *SimpleAsyncResult) SetHandleCancellation(handleCancellation bool)

SetHandleCancellation sets whether to handle cancellation within the asynchronous operation.

This function has nothing to do with g_simple_async_result_set_check_cancellable(). It only refers to the #GCancellable passed to g_simple_async_result_run_in_thread().

Deprecated: since version 2.46.

The function takes the following parameters:

  • handleCancellation: #gboolean.

func (*SimpleAsyncResult) SetOpResGboolean deprecated 

func (simple *SimpleAsyncResult) SetOpResGboolean(opRes bool)

SetOpResGboolean sets the operation result to a boolean within the asynchronous result.

Deprecated: Use #GTask and g_task_return_boolean() instead.

The function takes the following parameters:

  • opRes: #gboolean.

func (*SimpleAsyncResult) SetOpResGssize deprecated 

func (simple *SimpleAsyncResult) SetOpResGssize(opRes int)

SetOpResGssize sets the operation result within the asynchronous result to the given op_res.

Deprecated: Use #GTask and g_task_return_int() instead.

The function takes the following parameters:

  • opRes: #gssize.

type SimpleIOStream 

type SimpleIOStream struct {
	IOStream
	// contains filtered or unexported fields
}

SimpleIOStream: GSimpleIOStream creates a gio.IOStream from an arbitrary gio.InputStream and gio.OutputStream. This allows any pair of input and output streams to be used with gio.IOStream methods.

This is useful when you obtained a gio.InputStream and a gio.OutputStream by other means, for instance creating them with platform specific methods as g_unix_input_stream_new() (../gio-unix/ctor.UnixInputStream.new.html) (from gio-unix-2.0.pc / GioUnix-2.0), and you want to take advantage of the methods provided by gio.IOStream.

func NewSimpleIOStream 

func NewSimpleIOStream(inputStream InputStreamer, outputStream OutputStreamer) *SimpleIOStream

NewSimpleIOStream creates a new IOStream wrapping input_stream and output_stream. See also OStream.

The function takes the following parameters:

  • inputStream: Stream.
  • outputStream: Stream.

The function returns the following values:

  • simpleIOStream: new IOStream instance.

type SimplePermission 

type SimplePermission struct {
	Permission
	// contains filtered or unexported fields
}

SimplePermission: GSimplePermission is a trivial implementation of gio.Permission that represents a permission that is either always or never allowed. The value is given at construction and doesn’t change.

Calling gio.Permission.Acquire() or gio.Permission.Release() on a GSimplePermission will result in errors.

func NewSimplePermission 

func NewSimplePermission(allowed bool) *SimplePermission

NewSimplePermission creates a new #GPermission instance that represents an action that is either always or never allowed.

The function takes the following parameters:

  • allowed: TRUE if the action is allowed.

The function returns the following values:

  • simplePermission as a #GPermission.

type SimpleProxyResolver 

type SimpleProxyResolver struct {
	*coreglib.Object

	ProxyResolver
	// contains filtered or unexported fields
}

SimpleProxyResolver: GSimpleProxyResolver is a simple gio.ProxyResolver implementation that handles a single default proxy, multiple URI-scheme-specific proxies, and a list of hosts that proxies should not be used for.

GSimpleProxyResolver is never the default proxy resolver, but it can be used as the base class for another proxy resolver implementation, or it can be created and used manually, such as with gio.SocketClient.SetProxyResolver().

func (*SimpleProxyResolver) SetDefaultProxy 

func (resolver *SimpleProxyResolver) SetDefaultProxy(defaultProxy string)

SetDefaultProxy sets the default proxy on resolver, to be used for any URIs that don't match ProxyResolver:ignore-hosts or a proxy set via g_simple_proxy_resolver_set_uri_proxy().

If default_proxy starts with "socks://", ProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types.

The function takes the following parameters:

  • defaultProxy (optional): default proxy to use.

func (*SimpleProxyResolver) SetURIProxy 

func (resolver *SimpleProxyResolver) SetURIProxy(uriScheme, proxy string)

SetURIProxy adds a URI-scheme-specific proxy to resolver; URIs whose scheme matches uri_scheme (and which don't match ProxyResolver:ignore-hosts) will be proxied via proxy.

As with ProxyResolver:default-proxy, if proxy starts with "socks://", ProxyResolver will treat it as referring to all three of the socks5, socks4a, and socks4 proxy types.

The function takes the following parameters:

  • uriScheme: URI scheme to add a proxy for.
  • proxy to use for uri_scheme.

type SimpleProxyResolverClass added in v0.0.5 

type SimpleProxyResolverClass struct {
	// contains filtered or unexported fields
}

SimpleProxyResolverClass: instance of this type is always passed by reference.

type SimpleProxyResolverOverrides added in v0.0.5 

type SimpleProxyResolverOverrides struct {
}

SimpleProxyResolverOverrides contains methods that are overridable.

type Socket 

type Socket struct {
	*coreglib.Object

	DatagramBased
	Initable
	// contains filtered or unexported fields
}

Socket: 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 like gio.SocketClient, gio.SocketService and gio.SocketConnection. However there may be cases where direct use of GSocket is useful.

GSocket implements the gio.Initable interface, so if it is manually constructed by e.g. gobject.Object.New you must call gio.Initable.Init() and check the results before using the object. This is done automatically in gio.Socket.New and gio.Socket.NewFromFd, so these functions can return NULL.

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 call gio.Socket.ConditionCheck(), or gio.Socket.ConditionWait(). You can also use gio.Socket.CreateSource() and attach it to a glib.MainContext 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 returns G_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 signal SIGPIPE to be ignored for the remainder of the program. If you are writing a command-line utility that uses GSocket, you may need to take into account the fact that your program will not automatically be killed if it tries to write to stdout after it has been closed.

Like most other APIs in GLib, GSocket is not inherently thread safe. To use a GSocket concurrently from multiple threads, you must implement your own locking.

Nagle’s algorithm

Since GLib 2.80, GSocket will automatically set the TCP_NODELAY option on all G_SOCKET_TYPE_STREAM sockets. This disables Nagle’s algorithm (https://en.wikipedia.org/wiki/Nagle27s_algorithm) as it typically does more harm than good on modern networks.

If your application needs Nagle’s algorithm enabled, call gio.Socket.SetOption() after constructing a GSocket to enable it: 

socket = g_socket_new (…, G_SOCKET_TYPE_STREAM, …);
if (socket != NULL)
  {
    g_socket_set_option (socket, IPPROTO_TCP, TCP_NODELAY, FALSE, &local_error);
    // handle error if needed
  }.

func NewSocket 

func NewSocket(family SocketFamily, typ SocketType, protocol SocketProtocol) (*Socket, error)

NewSocket creates a new #GSocket with the defined family, type and protocol. If protocol is 0 (G_SOCKET_PROTOCOL_DEFAULT) the default protocol type for the family and type is used.

The protocol is a family and type specific int that specifies what kind of protocol to use. Protocol lists several common ones. Many families only support one protocol, and use 0 for this, others support several and using 0 means to use the default protocol for the family and type.

The protocol id is passed directly to the operating system, so you can use protocols not listed in Protocol if you know the protocol number used for it.

The function takes the following parameters:

  • family: socket family to use, e.g. G_SOCKET_FAMILY_IPV4.
  • typ: socket type to use.
  • protocol: id of the protocol to use, or 0 for default.

The function returns the following values:

  • socket or NULL on error. Free the returned object with g_object_unref().

func NewSocketFromFd 

func NewSocketFromFd(fd int) (*Socket, error)

NewSocketFromFd creates a new #GSocket from a native file descriptor or winsock SOCKET handle.

This reads all the settings from the file descriptor so that all properties should work. Note that the file descriptor will be set to non-blocking mode, independent on the blocking mode of the #GSocket.

On success, the returned #GSocket takes ownership of fd. On failure, the caller must close fd themselves.

Since GLib 2.46, it is no longer a fatal error to call this on a non-socket descriptor. Instead, a GError will be set with code G_IO_ERROR_FAILED.

The function takes the following parameters:

  • fd: native socket file descriptor.

The function returns the following values:

  • socket or NULL on error. Free the returned object with g_object_unref().

func (*Socket) Accept 

func (socket *Socket) Accept(ctx context.Context) (*Socket, error)

Accept incoming connections on a connection-based socket. This removes the first outstanding connection request from the listening socket and creates a #GSocket object for it.

The socket must be bound to a local address with g_socket_bind() and must be listening for incoming connections (g_socket_listen()).

If there are no outstanding connections then the operation will block or return G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. To be notified of an incoming connection, wait for the G_IO_IN condition.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.

The function returns the following values:

  • ret: new #GSocket, or NULL on error. Free the returned object with g_object_unref().

func (*Socket) AvailableBytes 

func (socket *Socket) AvailableBytes() int

AvailableBytes: get the amount of data pending in the OS input buffer, without blocking.

If socket is a UDP or SCTP socket, this will return the size of just the next packet, even if additional packets are buffered after that one.

Note that on Windows, this function is rather inefficient in the UDP case, and so if you know any plausible upper bound on the size of the incoming packet, it is better to just do a g_socket_receive() with a buffer of that size, rather than calling g_socket_get_available_bytes() first and then doing a receive of exactly the right size.

The function returns the following values:

  • gssize: number of bytes that can be read from the socket without blocking or truncating, or -1 on error.

func (*Socket) Bind 

func (socket *Socket) Bind(address SocketAddresser, allowReuse bool) error

Bind: when a socket is created it is attached to an address family, but it doesn't have an address in this family. g_socket_bind() assigns the address (sometimes called name) of the socket.

It is generally required to bind to a local address before you can receive connections. (See g_socket_listen() and g_socket_accept() ). In certain situations, you may also want to bind a socket that will be used to initiate connections, though this is not normally required.

If socket is a TCP socket, then allow_reuse controls the setting of the SO_REUSEADDR socket option; normally it should be TRUE for server sockets (sockets that you will eventually call g_socket_accept() on), and FALSE for client sockets. (Failing to set this flag on a server socket may cause g_socket_bind() to return G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then immediately restarted.)

If socket is a UDP socket, then allow_reuse determines whether or not other UDP sockets can be bound to the same address at the same time. In particular, you can have several UDP sockets bound to the same address, and they will all receive all of the multicast and broadcast packets sent to that address. (The behavior of unicast UDP packets to an address with multiple listeners is not defined.).

The function takes the following parameters:

  • address specifying the local address.
  • allowReuse: whether to allow reusing this address.

func (*Socket) Blocking 

func (socket *Socket) Blocking() bool

Blocking gets the blocking mode of the socket. For details on blocking I/O, see g_socket_set_blocking().

The function returns the following values:

  • ok: TRUE if blocking I/O is used, FALSE otherwise.

func (*Socket) Broadcast 

func (socket *Socket) Broadcast() bool

Broadcast gets the broadcast setting on socket; if TRUE, it is possible to send packets to broadcast addresses.

The function returns the following values:

  • ok: broadcast setting on socket.

func (*Socket) CheckConnectResult 

func (socket *Socket) CheckConnectResult() error

CheckConnectResult checks and resets the pending connect error for the socket. This is used to check for errors when g_socket_connect() is used in non-blocking mode.

func (*Socket) Close 

func (socket *Socket) Close() error

Close closes the socket, shutting down any active connection.

Closing a socket does not wait for all outstanding I/O operations to finish, so the caller should not rely on them to be guaranteed to complete even if the close returns with no error.

Once the socket is closed, all other operations will return G_IO_ERROR_CLOSED. Closing a socket multiple times will not return an error.

Sockets will be automatically closed when the last reference is dropped, but you might want to call this function to make sure resources are released as early as possible.

Beware that due to the way that TCP works, it is possible for recently-sent data to be lost if either you close a socket while the G_IO_IN condition is set, or else if the remote connection tries to send something to you after you close the socket but before it has finished reading all of the data you sent. There is no easy generic way to avoid this problem; the easiest fix is to design the network protocol such that the client will never send data "out of turn". Another solution is for the server to half-close the connection by calling g_socket_shutdown() with only the shutdown_write flag set, and then wait for the client to notice this and close its side of the connection, after which the server can safely call g_socket_close(). (This is what Connection does if you call g_tcp_connection_set_graceful_disconnect(). But of course, this only works if the client will close its connection after the server does.).

func (*Socket) ConditionCheck 

func (socket *Socket) ConditionCheck(condition glib.IOCondition) glib.IOCondition

ConditionCheck checks on the readiness of socket to perform operations. The operations specified in condition are checked for and masked against the currently-satisfied conditions on socket. The result is returned.

Note that on Windows, it is possible for an operation to return G_IO_ERROR_WOULD_BLOCK even immediately after g_socket_condition_check() has claimed that the socket is ready for writing. Rather than calling g_socket_condition_check() and then writing to the socket if it succeeds, it is generally better to simply try writing to the socket right away, and try again later if the initial attempt returns G_IO_ERROR_WOULD_BLOCK.

It is meaningless to specify G_IO_ERR or G_IO_HUP in condition; these conditions will always be set in the output if they are true.

This call never blocks.

The function takes the following parameters:

  • condition mask to check.

The function returns the following values:

  • ioCondition: GIOCondition mask of the current state.

func (*Socket) ConditionTimedWait 

func (socket *Socket) ConditionTimedWait(ctx context.Context, condition glib.IOCondition, timeoutUs int64) error

ConditionTimedWait waits for up to timeout_us microseconds for condition to become true on socket. If the condition is met, TRUE is returned.

If cancellable is cancelled before the condition is met, or if timeout_us (or the socket's #GSocket:timeout) is reached before the condition is met, then FALSE is returned and error, if non-NULL, is set to the appropriate value (G_IO_ERROR_CANCELLED or G_IO_ERROR_TIMED_OUT).

If you don't want a timeout, use g_socket_condition_wait(). (Alternatively, you can pass -1 for timeout_us.)

Note that although timeout_us is in microseconds for consistency with other GLib APIs, this function actually only has millisecond resolution, and the behavior is undefined if timeout_us is not an exact number of milliseconds.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • condition mask to wait for.
  • timeoutUs: maximum time (in microseconds) to wait, or -1.

func (*Socket) ConditionWait 

func (socket *Socket) ConditionWait(ctx context.Context, condition glib.IOCondition) error

ConditionWait waits for condition to become true on socket. When the condition is met, TRUE is returned.

If cancellable is cancelled before the condition is met, or if the socket has a timeout set and it is reached before the condition is met, then FALSE is returned and error, if non-NULL, is set to the appropriate value (G_IO_ERROR_CANCELLED or G_IO_ERROR_TIMED_OUT).

See also g_socket_condition_timed_wait().

The function takes the following parameters:

  • ctx (optional) or NULL.
  • condition mask to wait for.

func (*Socket) ConnectSocket 

func (socket *Socket) ConnectSocket(ctx context.Context, address SocketAddresser) error

ConnectSocket: connect the socket to the specified remote address.

For connection oriented socket this generally means we attempt to make a connection to the address. For a connection-less socket it sets the default address for g_socket_send() and discards all incoming datagrams from other sources.

Generally connection oriented sockets can only connect once, but connection-less sockets can connect multiple times to change the default address.

If the connect call needs to do network I/O it will block, unless non-blocking I/O is enabled. Then G_IO_ERROR_PENDING is returned and the user can be notified of the connection finishing by waiting for the G_IO_OUT condition. The result of the connection must then be checked with g_socket_check_connect_result().

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address specifying the remote address.

func (*Socket) ConnectionFactoryCreateConnection 

func (socket *Socket) ConnectionFactoryCreateConnection() *SocketConnection

ConnectionFactoryCreateConnection creates a Connection subclass of the right type for socket.

The function returns the following values:

  • socketConnection: Connection.

func (*Socket) Credentials 

func (socket *Socket) Credentials() (*Credentials, error)

Credentials returns the credentials of the foreign process connected to this socket, if any (e.g. it is only supported for G_SOCKET_FAMILY_UNIX sockets).

If this operation isn't supported on the OS, the method fails with the G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented by reading the SO_PEERCRED option on the underlying socket.

This method can be expected to be available on the following platforms:

- Linux since GLib 2.26

- OpenBSD since GLib 2.30

- Solaris, Illumos and OpenSolaris since GLib 2.40

- NetBSD since GLib 2.42

- macOS, tvOS, iOS since GLib 2.66

Other ways to obtain credentials from a foreign peer includes the CredentialsMessage type and g_unix_connection_send_credentials() / g_unix_connection_receive_credentials() functions.

The function returns the following values:

  • credentials: NULL if error is set, otherwise a #GCredentials object that must be freed with g_object_unref().

func (*Socket) Family 

func (socket *Socket) Family() SocketFamily

Family gets the socket family of the socket.

The function returns the following values:

  • socketFamily: Family.

func (*Socket) Fd 

func (socket *Socket) Fd() int

Fd returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for doing platform specific or otherwise unusual operations on the socket.

The function returns the following values:

  • gint: file descriptor of the socket.

func (*Socket) IsClosed 

func (socket *Socket) IsClosed() bool

IsClosed checks whether a socket is closed.

The function returns the following values:

  • ok: TRUE if socket is closed, FALSE otherwise.

func (*Socket) IsConnected 

func (socket *Socket) IsConnected() bool

IsConnected: check whether the socket is connected. This is only useful for connection-oriented sockets.

If using g_socket_shutdown(), this function will return TRUE until the socket has been shut down for reading and writing. If you do a non-blocking connect, this function will not return TRUE until after you call g_socket_check_connect_result().

The function returns the following values:

  • ok: TRUE if socket is connected, FALSE otherwise.

func (*Socket) JoinMulticastGroup 

func (socket *Socket) JoinMulticastGroup(group *InetAddress, sourceSpecific bool, iface string) error

JoinMulticastGroup registers socket to receive multicast messages sent to group. socket must be a G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind().

If iface is NULL, the system will automatically pick an interface to bind to based on group.

If source_specific is TRUE, source-specific multicast as defined in RFC 4604 is used. Note that on older platforms this may fail with a G_IO_ERROR_NOT_SUPPORTED error.

To bind to a given source-specific multicast address, use g_socket_join_multicast_group_ssm() instead.

The function takes the following parameters:

  • group specifying the group address to join.
  • sourceSpecific: TRUE if source-specific multicast should be used.
  • iface (optional): name of the interface to use, or NULL.

func (*Socket) JoinMulticastGroupSSM 

func (socket *Socket) JoinMulticastGroupSSM(group, sourceSpecific *InetAddress, iface string) error

JoinMulticastGroupSSM registers socket to receive multicast messages sent to group. socket must be a G_SOCKET_TYPE_DATAGRAM socket, and must have been bound to an appropriate interface and port with g_socket_bind().

If iface is NULL, the system will automatically pick an interface to bind to based on group.

If source_specific is not NULL, use source-specific multicast as defined in RFC 4604. Note that on older platforms this may fail with a G_IO_ERROR_NOT_SUPPORTED error.

Note that this function can be called multiple times for the same group with different source_specific in order to receive multicast packets from more than one source.

The function takes the following parameters:

  • group specifying the group address to join.
  • sourceSpecific (optional) specifying the source-specific multicast address or NULL to ignore.
  • iface (optional): name of the interface to use, or NULL.

func (*Socket) Keepalive 

func (socket *Socket) Keepalive() bool

Keepalive gets the keepalive mode of the socket. For details on this, see g_socket_set_keepalive().

The function returns the following values:

  • ok: TRUE if keepalive is active, FALSE otherwise.

func (*Socket) LeaveMulticastGroup 

func (socket *Socket) LeaveMulticastGroup(group *InetAddress, sourceSpecific bool, iface string) error

LeaveMulticastGroup removes socket from the multicast group defined by group, iface, and source_specific (which must all have the same values they had when you joined the group).

socket remains bound to its address and port, and can still receive unicast messages after calling this.

To unbind to a given source-specific multicast address, use g_socket_leave_multicast_group_ssm() instead.

The function takes the following parameters:

  • group specifying the group address to leave.
  • sourceSpecific: TRUE if source-specific multicast was used.
  • iface (optional): interface used.

func (*Socket) LeaveMulticastGroupSSM 

func (socket *Socket) LeaveMulticastGroupSSM(group, sourceSpecific *InetAddress, iface string) error

LeaveMulticastGroupSSM removes socket from the multicast group defined by group, iface, and source_specific (which must all have the same values they had when you joined the group).

socket remains bound to its address and port, and can still receive unicast messages after calling this.

The function takes the following parameters:

  • group specifying the group address to leave.
  • sourceSpecific (optional) specifying the source-specific multicast address or NULL to ignore.
  • iface (optional): name of the interface to use, or NULL.

func (*Socket) Listen 

func (socket *Socket) Listen() error

Listen marks the socket as a server socket, i.e. a socket that is used to accept incoming requests using g_socket_accept().

Before calling this the socket must be bound to a local address using g_socket_bind().

To set the maximum amount of outstanding clients, use g_socket_set_listen_backlog().

func (*Socket) ListenBacklog 

func (socket *Socket) ListenBacklog() int

ListenBacklog gets the listen backlog setting of the socket. For details on this, see g_socket_set_listen_backlog().

The function returns the following values:

  • gint: maximum number of pending connections.

func (*Socket) LocalAddress 

func (socket *Socket) LocalAddress() (SocketAddresser, error)

LocalAddress: try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting.

The function returns the following values:

  • socketAddress or NULL on error. Free the returned object with g_object_unref().

func (*Socket) MulticastLoopback 

func (socket *Socket) MulticastLoopback() bool

MulticastLoopback gets the multicast loopback setting on socket; if TRUE (the default), outgoing multicast packets will be looped back to multicast listeners on the same host.

The function returns the following values:

  • ok: multicast loopback setting on socket.

func (*Socket) MulticastTTL 

func (socket *Socket) MulticastTTL() uint

MulticastTTL gets the multicast time-to-live setting on socket; see g_socket_set_multicast_ttl() for more details.

The function returns the following values:

  • guint: multicast time-to-live setting on socket.

func (*Socket) Option 

func (socket *Socket) Option(level, optname int) (int, error)

Option gets the value of an integer-valued option on socket, as with getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers.

Note that even for socket options that are a single byte in size, value is still a pointer to a #gint variable, not a #guchar; g_socket_get_option() will handle the conversion internally.

The function takes the following parameters:

  • level: "API level" of the option (eg, SOL_SOCKET).
  • optname: "name" of the option (eg, SO_BROADCAST).

The function returns the following values:

  • value: return location for the option value.

func (*Socket) Protocol 

func (socket *Socket) Protocol() SocketProtocol

Protocol gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned.

The function returns the following values:

  • socketProtocol: protocol id, or -1 if unknown.

func (*Socket) Receive 

func (socket *Socket) Receive(ctx context.Context, buffer []byte) (int, error)

Receive data (up to size bytes) from a socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_receive_from() with address set to NULL.

For G_SOCKET_TYPE_DATAGRAM and G_SOCKET_TYPE_SEQPACKET sockets, g_socket_receive() will always read either 0 or 1 complete messages from the socket. If the received message is too large to fit in buffer, then the data beyond size bytes will be discarded, without any explicit indication that this has occurred.

For G_SOCKET_TYPE_STREAM sockets, g_socket_receive() can return any number of bytes, up to size. If more than size bytes have been received, the additional data will be returned in future calls to g_socket_receive().

If the socket is in blocking mode the call will block until there is some data to receive, the connection is closed, or there is an error. If there is no data available and the socket is in non-blocking mode, a G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when data is available, wait for the G_IO_IN condition.

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • buffer: a buffer to read data into (which should be at least size bytes long).

The function returns the following values:

  • gssize: number of bytes read, or 0 if the connection was closed by the peer, or -1 on error.

func (*Socket) ReceiveBytes added in v0.3.0 

func (socket *Socket) ReceiveBytes(ctx context.Context, size uint, timeoutUs int64) (*glib.Bytes, error)

ReceiveBytes receives data (up to size bytes) from a socket.

This function is a variant of gio.Socket.Receive() which returns a glib.Bytes rather than a plain buffer.

Pass -1 to timeout_us to block indefinitely until data is received (or the connection is closed, or there is an error). Pass 0 to use the default timeout from gio.Socket:timeout, or pass a positive number to wait for that many microseconds for data before returning G_IO_ERROR_TIMED_OUT.

The function takes the following parameters:

  • ctx (optional): GCancellable, or NULL.
  • size: number of bytes you want to read from the socket.
  • timeoutUs: timeout to wait for, in microseconds, or -1 to block indefinitely.

The function returns the following values:

  • bytes buffer containing the received bytes, or NULL on error.

func (*Socket) ReceiveBytesFrom added in v0.3.0 

func (socket *Socket) ReceiveBytesFrom(ctx context.Context, size uint, timeoutUs int64) (SocketAddresser, *glib.Bytes, error)

ReceiveBytesFrom: receive data (up to size bytes) from a socket.

This function is a variant of gio.Socket.ReceiveFrom() which returns a glib.Bytes rather than a plain buffer.

If address is non-NULL then address will be set equal to the source address of the received packet.

The address is owned by the caller.

Pass -1 to timeout_us to block indefinitely until data is received (or the connection is closed, or there is an error). Pass 0 to use the default timeout from gio.Socket:timeout, or pass a positive number to wait for that many microseconds for data before returning G_IO_ERROR_TIMED_OUT.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • size: number of bytes you want to read from the socket.
  • timeoutUs: timeout to wait for, in microseconds, or -1 to block indefinitely.

The function returns the following values:

  • address (optional): return location for a Address.
  • bytes buffer containing the received bytes, or NULL on error.

func (*Socket) ReceiveFrom 

func (socket *Socket) ReceiveFrom(ctx context.Context, buffer []byte) (SocketAddresser, int, error)

ReceiveFrom: receive data (up to size bytes) from a socket.

If address is non-NULL then address will be set equal to the source address of the received packet. address is owned by the caller.

See g_socket_receive() for additional information.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • buffer: a buffer to read data into (which should be at least size bytes long).

The function returns the following values:

  • address (optional): pointer to a Address pointer, or NULL.
  • gssize: number of bytes read, or 0 if the connection was closed by the peer, or -1 on error.

func (*Socket) ReceiveMessages 

func (socket *Socket) ReceiveMessages(ctx context.Context, messages []InputMessage, flags int) (int, error)

ReceiveMessages: receive multiple data messages from socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_receive(), g_socket_receive_from(), and g_socket_receive_message().

messages must point to an array of Message structs and num_messages must be the length of this array. Each Message contains a pointer to an array of Vector structs describing the buffers that the data received in each message will be written to. Using multiple Vectors is more memory-efficient than manually copying data out of a single buffer to multiple sources, and more system-call-efficient than making multiple calls to g_socket_receive(), such as in scenarios where a lot of data packets need to be received (e.g. high-bandwidth video streaming over RTP/UDP).

flags modify how all messages are received. The commonly available arguments for this are available in the MsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too. These flags affect the overall receive operation. Flags affecting individual messages are returned in Message.flags.

The other members of Message are treated as described in its documentation.

If #GSocket:blocking is TRUE the call will block until num_messages have been received, or the end of the stream is reached.

If #GSocket:blocking is FALSE the call will return up to num_messages without blocking, or G_IO_ERROR_WOULD_BLOCK if no messages are queued in the operating system to be received.

In blocking mode, if #GSocket:timeout is positive and is reached before any messages are received, G_IO_ERROR_TIMED_OUT is returned, otherwise up to num_messages are returned. (Note: This is effectively the behaviour of MSG_WAITFORONE with recvmmsg().)

To be notified when messages are available, wait for the G_IO_IN condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_socket_receive_messages() even if you were previously notified of a G_IO_IN condition.

If the remote peer closes the connection, any messages queued in the operating system will be returned, and subsequent calls to g_socket_receive_messages() will return 0 (with no error set).

On error -1 is returned and error is set accordingly. An error will only be returned if zero messages could be received; otherwise the number of messages successfully received before the error will be returned.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • messages: array of Message structs.
  • flags: int containing MsgFlags flags for the overall operation, which may additionally contain other platform specific flags (http://man7.org/linux/man-pages/man2/recv.2.html).

The function returns the following values:

  • gint: number of messages received, or -1 on error. Note that the number of messages received may be smaller than num_messages if in non-blocking mode, if the peer closed the connection, or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to receive the remaining messages.

func (*Socket) ReceiveWithBlocking 

func (socket *Socket) ReceiveWithBlocking(ctx context.Context, buffer []byte, blocking bool) (int, error)

ReceiveWithBlocking: this behaves exactly the same as g_socket_receive(), except that the choice of blocking or non-blocking behavior is determined by the blocking argument rather than by socket's properties.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • buffer: a buffer to read data into (which should be at least size bytes long).
  • blocking: whether to do blocking or non-blocking I/O.

The function returns the following values:

  • gssize: number of bytes read, or 0 if the connection was closed by the peer, or -1 on error.

func (*Socket) RemoteAddress 

func (socket *Socket) RemoteAddress() (SocketAddresser, error)

RemoteAddress: try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected.

The function returns the following values:

  • socketAddress or NULL on error. Free the returned object with g_object_unref().

func (*Socket) Send 

func (socket *Socket) Send(ctx context.Context, buffer string) (int, error)

Send tries to send size bytes from buffer on the socket. This is mainly used by connection-oriented sockets; it is identical to g_socket_send_to() with address set to NULL.

If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when space is available, wait for the G_IO_OUT condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • buffer: buffer containing the data to send.

The function returns the following values:

  • gssize: number of bytes written (which may be less than size), or -1 on error.

func (*Socket) SendMessage 

func (socket *Socket) SendMessage(ctx context.Context, address SocketAddresser, vectors []OutputVector, messages []SocketControlMessager, flags int) (int, error)

SendMessage: send data to address on socket. For sending multiple messages see g_socket_send_messages(); for easier use, see g_socket_send() and g_socket_send_to().

If address is NULL then the message is sent to the default receiver (set by g_socket_connect()).

vectors must point to an array of Vector structs and num_vectors must be the length of this array. (If num_vectors is -1, then vectors is assumed to be terminated by a Vector with a NULL buffer pointer.) The Vector structs describe the buffers that the sent data will be gathered from. Using multiple Vectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send().

messages, if non-NULL, is taken to point to an array of num_messages ControlMessage instances. These correspond to the control messages to be sent on the socket. If num_messages is -1 then messages is treated as a NULL-terminated array.

flags modify how the message is sent. The commonly available arguments for this are available in the MsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too.

If the socket is in blocking mode the call will block until there is space for the data in the socket queue. If there is no space available and the socket is in non-blocking mode a G_IO_ERROR_WOULD_BLOCK error will be returned. To be notified when space is available, wait for the G_IO_OUT condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

The sum of the sizes of each Vector in vectors must not be greater than G_MAXSSIZE. If the message can be larger than this, then it is mandatory to use the g_socket_send_message_with_timeout() function.

On error -1 is returned and error is set accordingly.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address (optional) or NULL.
  • vectors: array of Vector structs.
  • messages (optional): pointer to an array of ControlMessages, or NULL.
  • flags: int containing MsgFlags flags, which may additionally contain other platform specific flags (http://man7.org/linux/man-pages/man2/recv.2.html).

The function returns the following values:

  • gssize: number of bytes written (which may be less than size), or -1 on error.

func (*Socket) SendMessageWithTimeout 

func (socket *Socket) SendMessageWithTimeout(ctx context.Context, address SocketAddresser, vectors []OutputVector, messages []SocketControlMessager, flags int, timeoutUs int64) (uint, PollableReturn, error)

SendMessageWithTimeout: this behaves exactly the same as g_socket_send_message(), except that the choice of timeout behavior is determined by the timeout_us argument rather than by socket's properties.

On error G_POLLABLE_RETURN_FAILED is returned and error is set accordingly, or if the socket is currently not writable G_POLLABLE_RETURN_WOULD_BLOCK is returned. bytes_written will contain 0 in both cases.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address (optional) or NULL.
  • vectors: array of Vector structs.
  • messages (optional): pointer to an array of ControlMessages, or NULL.
  • flags: int containing MsgFlags flags, which may additionally contain other platform specific flags (http://man7.org/linux/man-pages/man2/recv.2.html).
  • timeoutUs: maximum time (in microseconds) to wait, or -1.

The function returns the following values:

  • bytesWritten (optional): location to store the number of bytes that were written to the socket.
  • pollableReturn: G_POLLABLE_RETURN_OK if all data was successfully written, G_POLLABLE_RETURN_WOULD_BLOCK if the socket is currently not writable, or G_POLLABLE_RETURN_FAILED if an error happened and error is set.

func (*Socket) SendMessages 

func (socket *Socket) SendMessages(ctx context.Context, messages []OutputMessage, flags int) (int, error)

SendMessages: send multiple data messages from socket in one go. This is the most complicated and fully-featured version of this call. For easier use, see g_socket_send(), g_socket_send_to(), and g_socket_send_message().

messages must point to an array of Message structs and num_messages must be the length of this array. Each Message contains an address to send the data to, and a pointer to an array of Vector structs to describe the buffers that the data to be sent for each message will be gathered from. Using multiple Vectors is more memory-efficient than manually copying data from multiple sources into a single buffer, and more network-efficient than making multiple calls to g_socket_send(). Sending multiple messages in one go avoids the overhead of making a lot of syscalls in scenarios where a lot of data packets need to be sent (e.g. high-bandwidth video streaming over RTP/UDP), or where the same data needs to be sent to multiple recipients.

flags modify how the message is sent. The commonly available arguments for this are available in the MsgFlags enum, but the values there are the same as the system values, and the flags are passed in as-is, so you can pass in system-specific flags too.

If the socket is in blocking mode the call will block until there is space for all the data in the socket queue. If there is no space available and the socket is in non-blocking mode a G_IO_ERROR_WOULD_BLOCK error will be returned if no data was written at all, otherwise the number of messages sent will be returned. To be notified when space is available, wait for the G_IO_OUT condition. Note though that you may still receive G_IO_ERROR_WOULD_BLOCK from g_socket_send() even if you were previously notified of a G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.)

On error -1 is returned and error is set accordingly. An error will only be returned if zero messages could be sent; otherwise the number of messages successfully sent before the error will be returned.

The function takes the following parameters:

The function returns the following values:

  • gint: number of messages sent, or -1 on error. Note that the number of messages sent may be smaller than num_messages if the socket is non-blocking or if num_messages was larger than UIO_MAXIOV (1024), in which case the caller may re-try to send the remaining messages.

func (*Socket) SendTo 

func (socket *Socket) SendTo(ctx context.Context, address SocketAddresser, buffer string) (int, error)

SendTo tries to send size bytes from buffer to address. If address is NULL then the message is sent to the default receiver (set by g_socket_connect()).

See g_socket_send() for additional information.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address (optional) or NULL.
  • buffer: buffer containing the data to send.

The function returns the following values:

  • gssize: number of bytes written (which may be less than size), or -1 on error.

func (*Socket) SendWithBlocking 

func (socket *Socket) SendWithBlocking(ctx context.Context, buffer string, blocking bool) (int, error)

SendWithBlocking: this behaves exactly the same as g_socket_send(), except that the choice of blocking or non-blocking behavior is determined by the blocking argument rather than by socket's properties.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • buffer: buffer containing the data to send.
  • blocking: whether to do blocking or non-blocking I/O.

The function returns the following values:

  • gssize: number of bytes written (which may be less than size), or -1 on error.

func (*Socket) SetBlocking 

func (socket *Socket) SetBlocking(blocking bool)

SetBlocking sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In non-blocking mode all functions return results immediately or with a G_IO_ERROR_WOULD_BLOCK error.

All sockets are created in blocking mode. However, note that the platform level socket is always non-blocking, and blocking mode is a GSocket level feature.

The function takes the following parameters:

  • blocking: whether to use blocking I/O or not.

func (*Socket) SetBroadcast 

func (socket *Socket) SetBroadcast(broadcast bool)

SetBroadcast sets whether socket should allow sending to broadcast addresses. This is FALSE by default.

The function takes the following parameters:

  • broadcast: whether socket should allow sending to broadcast addresses.

func (*Socket) SetKeepalive 

func (socket *Socket) SetKeepalive(keepalive bool)

SetKeepalive sets or unsets the SO_KEEPALIVE flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of time passes with no data being exchanged. If the system is unable to verify the presence of the remote endpoint, it will automatically close the connection.

This option is only functional on certain kinds of sockets. (Notably, G_SOCKET_PROTOCOL_TCP sockets.)

The exact time between pings is system- and protocol-dependent, but will normally be at least two hours. Most commonly, you would set this flag on a server socket if you want to allow clients to remain idle for long periods of time, but also want to ensure that connections are eventually garbage-collected if clients crash or become unreachable.

The function takes the following parameters:

  • keepalive: value for the keepalive flag.

func (*Socket) SetListenBacklog 

func (socket *Socket) SetListenBacklog(backlog int)

SetListenBacklog sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them on time then the new connections will be refused.

Note that this must be called before g_socket_listen() and has no effect if called after that.

The function takes the following parameters:

  • backlog: maximum number of pending connections.

func (*Socket) SetMulticastLoopback 

func (socket *Socket) SetMulticastLoopback(loopback bool)

SetMulticastLoopback sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is TRUE by default.

The function takes the following parameters:

  • loopback: whether socket should receive messages sent to its multicast groups from the local host.

func (*Socket) SetMulticastTTL 

func (socket *Socket) SetMulticastTTL(ttl uint)

SetMulticastTTL sets the time-to-live for outgoing multicast datagrams on socket. By default, this is 1, meaning that multicast packets will not leave the local network.

The function takes the following parameters:

  • ttl: time-to-live value for all multicast datagrams on socket.

func (*Socket) SetOption 

func (socket *Socket) SetOption(level, optname, value int) error

SetOption sets the value of an integer-valued option on socket, as with setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.)

The [<gio/gnetworking.h>][gio-gnetworking.h] header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional headers.

The function takes the following parameters:

  • level: "API level" of the option (eg, SOL_SOCKET).
  • optname: "name" of the option (eg, SO_BROADCAST).
  • value to set the option to.

func (*Socket) SetTTL 

func (socket *Socket) SetTTL(ttl uint)

SetTTL sets the time-to-live for outgoing unicast packets on socket. By default the platform-specific default value is used.

The function takes the following parameters:

  • ttl: time-to-live value for all unicast packets on socket.

func (*Socket) SetTimeout 

func (socket *Socket) SetTimeout(timeout uint)

SetTimeout sets the time in seconds after which I/O operations on socket will time out if they have not yet completed.

On a blocking socket, this means that any blocking #GSocket operation will time out after timeout seconds of inactivity, returning G_IO_ERROR_TIMED_OUT.

On a non-blocking socket, calls to g_socket_condition_wait() will also fail with G_IO_ERROR_TIMED_OUT after the given time. Sources created with g_socket_create_source() will trigger after timeout seconds of inactivity, with the requested condition set, at which point calling g_socket_receive(), g_socket_send(), g_socket_check_connect_result(), etc, will fail with G_IO_ERROR_TIMED_OUT.

If timeout is 0 (the default), operations will never time out on their own.

Note that if an I/O operation is interrupted by a signal, this may cause the timeout to be reset.

The function takes the following parameters:

  • timeout for socket, in seconds, or 0 for none.

func (*Socket) Shutdown 

func (socket *Socket) Shutdown(shutdownRead, shutdownWrite bool) error

Shutdown: shut down part or all of a full-duplex connection.

If shutdown_read is TRUE then the receiving side of the connection is shut down, and further reading is disallowed.

If shutdown_write is TRUE then the sending side of the connection is shut down, and further writing is disallowed.

It is allowed for both shutdown_read and shutdown_write to be TRUE.

One example where it is useful to shut down only one side of a connection is graceful disconnect for TCP connections where you close the sending side, then wait for the other side to close the connection, thus ensuring that the other side saw all sent data.

The function takes the following parameters:

  • shutdownRead: whether to shut down the read side.
  • shutdownWrite: whether to shut down the write side.

func (*Socket) SocketType 

func (socket *Socket) SocketType() SocketType

SocketType gets the socket type of the socket.

The function returns the following values:

  • socketType: Type.

func (*Socket) SpeaksIPv4 

func (socket *Socket) SpeaksIPv4() bool

SpeaksIPv4 checks if a socket is capable of speaking IPv4.

IPv4 sockets are capable of speaking IPv4. On some operating systems and under some combinations of circumstances IPv6 sockets are also capable of speaking IPv4. See RFC 3493 section 3.7 for more information.

No other types of sockets are currently considered as being capable of speaking IPv4.

The function returns the following values:

  • ok: TRUE if this socket can be used with IPv4.

func (*Socket) TTL 

func (socket *Socket) TTL() uint

TTL gets the unicast time-to-live setting on socket; see g_socket_set_ttl() for more details.

The function returns the following values:

  • guint: time-to-live setting on socket.

func (*Socket) Timeout 

func (socket *Socket) Timeout() uint

Timeout gets the timeout setting of the socket. For details on this, see g_socket_set_timeout().

The function returns the following values:

  • guint: timeout in seconds.

type SocketAddress 

type SocketAddress struct {
	*coreglib.Object

	SocketConnectable
	// contains filtered or unexported fields
}

SocketAddress: GSocketAddress is the equivalent of struct sockaddr (man:sockaddr(3type)) and its subtypes in the BSD sockets API. This is an abstract class; use gio.InetSocketAddress for internet sockets, or gio.UnixSocketAddress for UNIX domain sockets.

func BaseSocketAddress 

func BaseSocketAddress(obj SocketAddresser) *SocketAddress

BaseSocketAddress returns the underlying base object.

func NewSocketAddressFromNative 

func NewSocketAddressFromNative(native unsafe.Pointer, len uint) *SocketAddress

NewSocketAddressFromNative creates a Address subclass corresponding to the native struct sockaddr native.

The function takes the following parameters:

  • native: pointer to a struct sockaddr.
  • len: size of the memory location pointed to by native.

The function returns the following values:

  • socketAddress: new Address if native could successfully be converted, otherwise NULL.

func (*SocketAddress) Family 

func (address *SocketAddress) Family() SocketFamily

Family gets the socket family type of address.

The function returns the following values:

  • socketFamily: socket family type of address.

func (*SocketAddress) NativeSize 

func (address *SocketAddress) NativeSize() int

NativeSize gets the size of address's native struct sockaddr. You can use this to allocate memory to pass to g_socket_address_to_native().

The function returns the following values:

  • gssize: size of the native struct sockaddr that address represents.

func (*SocketAddress) ToNative 

func (address *SocketAddress) ToNative(dest unsafe.Pointer, destlen uint) error

ToNative converts a Address to a native struct sockaddr, which can be passed to low-level functions like connect() or bind().

If not enough space is available, a G_IO_ERROR_NO_SPACE error is returned. If the address type is not known on the system then a G_IO_ERROR_NOT_SUPPORTED error is returned.

The function takes the following parameters:

  • dest (optional): pointer to a memory location that will contain the native struct sockaddr.
  • destlen: size of dest. Must be at least as large as g_socket_address_get_native_size().

type SocketAddressClass added in v0.0.5 

type SocketAddressClass struct {
	// contains filtered or unexported fields
}

SocketAddressClass: instance of this type is always passed by reference.

type SocketAddressEnumerator 

type SocketAddressEnumerator struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

SocketAddressEnumerator: GSocketAddressEnumerator is an enumerator type for gio.SocketAddress instances. It is returned by enumeration functions such as gio.SocketConnectable.Enumerate(), which returns a GSocketAddressEnumerator to list each gio.SocketAddress which could be used to connect to that gio.SocketConnectable.

Enumeration is typically a blocking operation, so the asynchronous methods gio.SocketAddressEnumerator.NextAsync() and gio.SocketAddressEnumerator.NextFinish() should be used where possible.

Each GSocketAddressEnumerator can only be enumerated once. Once gio.SocketAddressEnumerator.Next() has returned NULL, further enumeration with that GSocketAddressEnumerator is not possible, and it can be unreffed.

func BaseSocketAddressEnumerator 

func BaseSocketAddressEnumerator(obj SocketAddressEnumeratorrer) *SocketAddressEnumerator

BaseSocketAddressEnumerator returns the underlying base object.

func (*SocketAddressEnumerator) Next 

func (enumerator *SocketAddressEnumerator) Next(ctx context.Context) (SocketAddresser, error)

Next retrieves the next Address from enumerator. Note that this may block for some amount of time. (Eg, a Address may need to do a DNS lookup before it can return an address.) Use g_socket_address_enumerator_next_async() if you need to avoid blocking.

If enumerator is expected to yield addresses, but for some reason is unable to (eg, because of a DNS error), then the first call to g_socket_address_enumerator_next() will return an appropriate error in *error. However, if the first call to g_socket_address_enumerator_next() succeeds, then any further internal errors (other than cancellable being triggered) will be ignored.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • socketAddress (optional) (owned by the caller), or NULL on error (in which case *error will be set) or if there are no more addresses.

func (*SocketAddressEnumerator) NextAsync 

func (enumerator *SocketAddressEnumerator) NextAsync(ctx context.Context, callback AsyncReadyCallback)

NextAsync: asynchronously retrieves the next Address from enumerator and then calls callback, which must call g_socket_address_enumerator_next_finish() to get the result.

It is an error to call this multiple times before the previous callback has finished.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • callback (optional) to call when the request is satisfied.

func (*SocketAddressEnumerator) NextFinish 

func (enumerator *SocketAddressEnumerator) NextFinish(result AsyncResulter) (SocketAddresser, error)

NextFinish retrieves the result of a completed call to g_socket_address_enumerator_next_async(). See g_socket_address_enumerator_next() for more information about error handling.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • socketAddress (optional) (owned by the caller), or NULL on error (in which case *error will be set) or if there are no more addresses.

type SocketAddressEnumeratorClass added in v0.0.5 

type SocketAddressEnumeratorClass struct {
	// contains filtered or unexported fields
}

SocketAddressEnumeratorClass class structure for AddressEnumerator.

An instance of this type is always passed by reference.

type SocketAddressEnumeratorOverrides added in v0.0.5 

type SocketAddressEnumeratorOverrides struct {
	// Next retrieves the next Address from enumerator. Note that
	// this may block for some amount of time. (Eg, a Address may
	// need to do a DNS lookup before it can return an address.) Use
	// g_socket_address_enumerator_next_async() if you need to avoid blocking.
	//
	// If enumerator is expected to yield addresses, but for some reason
	// is unable to (eg, because of a DNS error), then the first call to
	// g_socket_address_enumerator_next() will return an appropriate error in
	// *error. However, if the first call to g_socket_address_enumerator_next()
	// succeeds, then any further internal errors (other than cancellable being
	// triggered) will be ignored.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable object, NULL to ignore.
	//
	// The function returns the following values:
	//
	//   - socketAddress (optional) (owned by the caller), or NULL on error (in
	//     which case *error will be set) or if there are no more addresses.
	Next func(ctx context.Context) (SocketAddresser, error)
	// NextFinish retrieves the result of a completed call
	// to g_socket_address_enumerator_next_async(). See
	// g_socket_address_enumerator_next() for more information about error
	// handling.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - socketAddress (optional) (owned by the caller), or NULL on error (in
	//     which case *error will be set) or if there are no more addresses.
	NextFinish func(result AsyncResulter) (SocketAddresser, error)
}

SocketAddressEnumeratorOverrides contains methods that are overridable.

type SocketAddressEnumeratorrer 

type SocketAddressEnumeratorrer interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

SocketAddressEnumeratorrer describes types inherited from class SocketAddressEnumerator.

To get the original type, the caller must assert this to an interface or another type.

type SocketAddressOverrides added in v0.0.5 

type SocketAddressOverrides struct {
	// Family gets the socket family type of address.
	//
	// The function returns the following values:
	//
	//   - socketFamily: socket family type of address.
	Family func() SocketFamily
	// NativeSize gets the size of address's native struct sockaddr. You can use
	// this to allocate memory to pass to g_socket_address_to_native().
	//
	// The function returns the following values:
	//
	//   - gssize: size of the native struct sockaddr that address represents.
	NativeSize func() int
	// ToNative converts a Address to a native struct sockaddr, which can be
	// passed to low-level functions like connect() or bind().
	//
	// If not enough space is available, a G_IO_ERROR_NO_SPACE error is
	// returned. If the address type is not known on the system then a
	// G_IO_ERROR_NOT_SUPPORTED error is returned.
	//
	// The function takes the following parameters:
	//
	//   - dest (optional): pointer to a memory location that will contain the
	//     native struct sockaddr.
	//   - destlen: size of dest. Must be at least as large as
	//     g_socket_address_get_native_size().
	ToNative func(dest unsafe.Pointer, destlen uint) error
}

SocketAddressOverrides contains methods that are overridable.

type SocketAddresser 

type SocketAddresser interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

SocketAddresser describes types inherited from class SocketAddress.

To get the original type, the caller must assert this to an interface or another type.

type SocketClass added in v0.0.5 

type SocketClass struct {
	// contains filtered or unexported fields
}

SocketClass: instance of this type is always passed by reference.

type SocketClient 

type SocketClient struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

SocketClient: 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 a gio.SocketConnection subclass on success.

The type of the gio.SocketConnection object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a gio.TCPConnection.

As GSocketClient is a lightweight object, you don't need to cache it. You can just create a new one any time you need one.

func NewSocketClient 

func NewSocketClient() *SocketClient

NewSocketClient creates a new Client with the default options.

The function returns the following values:

  • socketClient: Client. Free the returned object with g_object_unref().

func (*SocketClient) AddApplicationProxy 

func (client *SocketClient) AddApplicationProxy(protocol string)

AddApplicationProxy: enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the Resolver, Client will consider this protocol as supported but will not try to find a #GProxy instance to handle handshaking. The application must check for this case by calling g_socket_connection_get_remote_address() on the returned Connection, and seeing if it's a Address of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself.

This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method.

When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake.

The function takes the following parameters:

  • protocol: proxy protocol.

func (*SocketClient) ConnectAsync 

func (client *SocketClient) ConnectAsync(ctx context.Context, connectable SocketConnectabler, callback AsyncReadyCallback)

ConnectAsync: this is the asynchronous version of g_socket_client_connect().

You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements RFC 8305 (https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.)

When the operation is finished callback will be called. You can then call g_socket_client_connect_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • connectable specifying the remote address.
  • callback (optional): ReadyCallback.

func (*SocketClient) ConnectEvent 

func (client *SocketClient) ConnectEvent(f func(event SocketClientEvent, connectable SocketConnectabler, connection IOStreamer)) coreglib.SignalHandle

ConnectEvent is emitted when client's activity on connectable changes state. Among other things, this can be used to provide progress information about a network connection in the UI. The meanings of the different event values are as follows:

- G_SOCKET_CLIENT_RESOLVING: client is about to look up connectable in DNS. connection will be NULL.

- G_SOCKET_CLIENT_RESOLVED: client has successfully resolved connectable in DNS. connection will be NULL.

- G_SOCKET_CLIENT_CONNECTING: client is about to make a connection to a remote host; either a proxy server or the destination server itself. connection is the Connection, which is not yet connected. Since GLib 2.40, you can access the remote address via g_socket_connection_get_remote_address().

- G_SOCKET_CLIENT_CONNECTED: client has successfully connected to a remote host. connection is the connected Connection.

- G_SOCKET_CLIENT_PROXY_NEGOTIATING: client is about to negotiate with a proxy to get it to connect to connectable. connection is the Connection to the proxy server.

- G_SOCKET_CLIENT_PROXY_NEGOTIATED: client has negotiated a connection to connectable through a proxy server. connection is the stream returned from g_proxy_connect(), which may or may not be a Connection.

- G_SOCKET_CLIENT_TLS_HANDSHAKING: client is about to begin a TLS handshake. connection is a ClientConnection.

- G_SOCKET_CLIENT_TLS_HANDSHAKED: client has successfully completed the TLS handshake. connection is a ClientConnection.

- G_SOCKET_CLIENT_COMPLETE: client has either successfully connected to connectable (in which case connection is the Connection that it will be returning to the caller) or has failed (in which case connection is NULL and the client is about to return an error).

Each event except G_SOCKET_CLIENT_COMPLETE may be emitted multiple times (or not at all) for a given connectable (in particular, if client ends up attempting to connect to more than one address). However, if client emits the Client::event signal at all for a given connectable, then it will always emit it with G_SOCKET_CLIENT_COMPLETE when it is done.

Note that there may be additional ClientEvent values in the future; unrecognized event values should be ignored.

func (*SocketClient) ConnectFinish 

func (client *SocketClient) ConnectFinish(result AsyncResulter) (*SocketConnection, error)

ConnectFinish finishes an async connect operation. See g_socket_client_connect_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectSocketClient 

func (client *SocketClient) ConnectSocketClient(ctx context.Context, connectable SocketConnectabler) (*SocketConnection, error)

ConnectSocketClient tries to resolve the connectable and make a network connection to it.

Upon a successful connection, a new Connection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

The type of the Connection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a Connection.

The socket created will be the same family as the address that the connectable resolves to, unless family is set with g_socket_client_set_family() or indirectly via g_socket_client_set_local_address(). The socket type defaults to G_SOCKET_TYPE_STREAM but can be set with g_socket_client_set_socket_type().

If a local address is specified with g_socket_client_set_local_address() the socket will be bound to this address before connecting.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • connectable specifying the remote address.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectToHost 

func (client *SocketClient) ConnectToHost(ctx context.Context, hostAndPort string, defaultPort uint16) (*SocketConnection, error)

ConnectToHost: this is a helper function for g_socket_client_connect().

Attempts to create a TCP connection to the named host.

host_and_port may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).

If no port override is given in host_and_port then default_port will be used as the port number to connect to.

In general, host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and default_port is expected to be provided by the application.

In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.

Upon a successful connection, a new Connection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) NULL is returned and error (if non-NULL) is set accordingly.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostAndPort: name and optionally port of the host to connect to.
  • defaultPort: default port to connect to.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectToHostAsync 

func (client *SocketClient) ConnectToHostAsync(ctx context.Context, hostAndPort string, defaultPort uint16, callback AsyncReadyCallback)

ConnectToHostAsync: this is the asynchronous version of g_socket_client_connect_to_host().

When the operation is finished callback will be called. You can then call g_socket_client_connect_to_host_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • hostAndPort: name and optionally the port of the host to connect to.
  • defaultPort: default port to connect to.
  • callback (optional): ReadyCallback.

func (*SocketClient) ConnectToHostFinish 

func (client *SocketClient) ConnectToHostFinish(result AsyncResulter) (*SocketConnection, error)

ConnectToHostFinish finishes an async connect operation. See g_socket_client_connect_to_host_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectToService 

func (client *SocketClient) ConnectToService(ctx context.Context, domain, service string) (*SocketConnection, error)

ConnectToService attempts to create a TCP connection to a service.

This call looks up the SRV record for service at domain for the "tcp" protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining.

Upon a successful connection, a new Connection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) NULL is returned and error (if non-NULL) is set accordingly.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • domain name.
  • service: name of the service to connect to.

The function returns the following values:

  • socketConnection if successful, or NULL on error.

func (*SocketClient) ConnectToServiceAsync 

func (client *SocketClient) ConnectToServiceAsync(ctx context.Context, domain, service string, callback AsyncReadyCallback)

ConnectToServiceAsync: this is the asynchronous version of g_socket_client_connect_to_service().

The function takes the following parameters:

  • ctx (optional) or NULL.
  • domain name.
  • service: name of the service to connect to.
  • callback (optional): ReadyCallback.

func (*SocketClient) ConnectToServiceFinish 

func (client *SocketClient) ConnectToServiceFinish(result AsyncResulter) (*SocketConnection, error)

ConnectToServiceFinish finishes an async connect operation. See g_socket_client_connect_to_service_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectToURI 

func (client *SocketClient) ConnectToURI(ctx context.Context, uri string, defaultPort uint16) (*SocketConnection, error)

ConnectToURI: this is a helper function for g_socket_client_connect().

Attempts to create a TCP connection with a network URI.

uri may be any valid URI containing an "authority" (hostname/port) component. If a port is not specified in the URI, default_port will be used. TLS will be negotiated if Client:tls is TRUE. (Client does not know to automatically assume TLS for certain URI schemes.)

Using this rather than g_socket_client_connect() or g_socket_client_connect_to_host() allows Client to determine when to use application-specific proxy protocols.

Upon a successful connection, a new Connection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) NULL is returned and error (if non-NULL) is set accordingly.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • uri: network URI.
  • defaultPort: default port to connect to.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) ConnectToURIAsync 

func (client *SocketClient) ConnectToURIAsync(ctx context.Context, uri string, defaultPort uint16, callback AsyncReadyCallback)

ConnectToURIAsync: this is the asynchronous version of g_socket_client_connect_to_uri().

When the operation is finished callback will be called. You can then call g_socket_client_connect_to_uri_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • uri: network uri.
  • defaultPort: default port to connect to.
  • callback (optional): ReadyCallback.

func (*SocketClient) ConnectToURIFinish 

func (client *SocketClient) ConnectToURIFinish(result AsyncResulter) (*SocketConnection, error)

ConnectToURIFinish finishes an async connect operation. See g_socket_client_connect_to_uri_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • socketConnection on success, NULL on error.

func (*SocketClient) EnableProxy 

func (client *SocketClient) EnableProxy() bool

EnableProxy gets the proxy enable state; see g_socket_client_set_enable_proxy().

The function returns the following values:

  • ok: whether proxying is enabled.

func (*SocketClient) Family 

func (client *SocketClient) Family() SocketFamily

Family gets the socket family of the socket client.

See g_socket_client_set_family() for details.

The function returns the following values:

  • socketFamily: Family.

func (*SocketClient) LocalAddress 

func (client *SocketClient) LocalAddress() SocketAddresser

LocalAddress gets the local address of the socket client.

See g_socket_client_set_local_address() for details.

The function returns the following values:

  • socketAddress (optional) or NULL. Do not free.

func (*SocketClient) Protocol 

func (client *SocketClient) Protocol() SocketProtocol

Protocol gets the protocol name type of the socket client.

See g_socket_client_set_protocol() for details.

The function returns the following values:

  • socketProtocol: Protocol.

func (*SocketClient) ProxyResolver 

func (client *SocketClient) ProxyResolver() *ProxyResolver

ProxyResolver gets the Resolver being used by client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver().

The function returns the following values:

  • proxyResolver being used by client.

func (*SocketClient) SetEnableProxy 

func (client *SocketClient) SetEnableProxy(enable bool)

SetEnableProxy sets whether or not client attempts to make connections via a proxy server. When enabled (the default), Client will use a Resolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation.

See also g_socket_client_set_proxy_resolver().

The function takes the following parameters:

  • enable: whether to enable proxies.

func (*SocketClient) SetFamily 

func (client *SocketClient) SetFamily(family SocketFamily)

SetFamily sets the socket family of the socket client. If this is set to something other than G_SOCKET_FAMILY_INVALID then the sockets created by this object will be of the specified family.

This might be useful for instance if you want to force the local connection to be an ipv4 socket, even though the address might be an ipv6 mapped to ipv4 address.

The function takes the following parameters:

  • family: Family.

func (*SocketClient) SetLocalAddress 

func (client *SocketClient) SetLocalAddress(address SocketAddresser)

SetLocalAddress sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not NULL) before connecting.

This is useful if you want to ensure that the local side of the connection is on a specific port, or on a specific interface.

The function takes the following parameters:

  • address (optional) or NULL.

func (*SocketClient) SetProtocol 

func (client *SocketClient) SetProtocol(protocol SocketProtocol)

SetProtocol sets the protocol of the socket client. The sockets created by this object will use of the specified protocol.

If protocol is G_SOCKET_PROTOCOL_DEFAULT that means to use the default protocol for the socket family and type.

The function takes the following parameters:

  • protocol: Protocol.

func (*SocketClient) SetProxyResolver 

func (client *SocketClient) SetProxyResolver(proxyResolver ProxyResolverer)

SetProxyResolver overrides the Resolver used by client. You can call this if you want to use specific proxies, rather than using the system default proxy settings.

Note that whether or not the proxy resolver is actually used depends on the setting of Client:enable-proxy, which is not changed by this function (but which is TRUE by default).

The function takes the following parameters:

  • proxyResolver (optional) or NULL for the default.

func (*SocketClient) SetSocketType 

func (client *SocketClient) SetSocketType(typ SocketType)

SetSocketType sets the socket type of the socket client. The sockets created by this object will be of the specified type.

It doesn't make sense to specify a type of G_SOCKET_TYPE_DATAGRAM, as GSocketClient is used for connection oriented services.

The function takes the following parameters:

  • typ: Type.

func (*SocketClient) SetTLS 

func (client *SocketClient) SetTLS(tls bool)

SetTLS sets whether client creates TLS (aka SSL) connections. If tls is TRUE, client will wrap its connections in a ClientConnection and perform a TLS handshake when connecting.

Note that since Client must return a Connection, but ClientConnection is not a Connection, this actually wraps the resulting ClientConnection in a WrapperConnection when returning it. You can use g_tcp_wrapper_connection_get_base_io_stream() on the return value to extract the ClientConnection.

If you need to modify the behavior of the TLS handshake (eg, by setting a client-side certificate to use, or connecting to the Connection::accept-certificate signal), you can connect to client's Client::event signal and wait for it to be emitted with G_SOCKET_CLIENT_TLS_HANDSHAKING, which will give you a chance to see the ClientConnection before the handshake starts.

The function takes the following parameters:

  • tls: whether to use TLS.

func (*SocketClient) SetTLSValidationFlags deprecated 

func (client *SocketClient) SetTLSValidationFlags(flags TLSCertificateFlags)

SetTLSValidationFlags sets the TLS validation flags used when creating TLS connections via client. The default value is G_TLS_CERTIFICATE_VALIDATE_ALL.

This function does not work as originally designed and is impossible to use correctly. See Client:tls-validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function takes the following parameters:

  • flags: validation flags.

func (*SocketClient) SetTimeout 

func (client *SocketClient) SetTimeout(timeout uint)

SetTimeout sets the I/O timeout for sockets created by client. timeout is a time in seconds, or 0 for no timeout (the default).

The timeout value affects the initial connection attempt as well, so setting this may cause calls to g_socket_client_connect(), etc, to fail with G_IO_ERROR_TIMED_OUT.

The function takes the following parameters:

  • timeout: timeout.

func (*SocketClient) SocketType 

func (client *SocketClient) SocketType() SocketType

SocketType gets the socket type of the socket client.

See g_socket_client_set_socket_type() for details.

The function returns the following values:

  • socketType: Family.

func (*SocketClient) TLS 

func (client *SocketClient) TLS() bool

TLS gets whether client creates TLS connections. See g_socket_client_set_tls() for details.

The function returns the following values:

  • ok: whether client uses TLS.

func (*SocketClient) TLSValidationFlags deprecated 

func (client *SocketClient) TLSValidationFlags() TLSCertificateFlags

TLSValidationFlags gets the TLS validation flags used creating TLS connections via client.

This function does not work as originally designed and is impossible to use correctly. See Client:tls-validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function returns the following values:

  • tlsCertificateFlags: TLS validation flags.

func (*SocketClient) Timeout 

func (client *SocketClient) Timeout() uint

Timeout gets the I/O timeout time for sockets created by client.

See g_socket_client_set_timeout() for details.

The function returns the following values:

  • guint: timeout in seconds.

type SocketClientClass added in v0.0.5 

type SocketClientClass struct {
	// contains filtered or unexported fields
}

SocketClientClass: instance of this type is always passed by reference.

type SocketClientEvent 

type SocketClientEvent C.gint

SocketClientEvent describes an event occurring on a Client. See the Client::event signal for more details.

Additional values may be added to this type in the future. 

const (
	// SocketClientResolving: client is doing a DNS lookup.
	SocketClientResolving SocketClientEvent = iota
	// SocketClientResolved: client has completed a DNS lookup.
	SocketClientResolved
	// SocketClientConnecting: client is connecting to a remote host (either a
	// proxy or the destination server).
	SocketClientConnecting
	// SocketClientConnected: client has connected to a remote host.
	SocketClientConnected
	// SocketClientProxyNegotiating: client is negotiating with a proxy to
	// connect to the destination server.
	SocketClientProxyNegotiating
	// SocketClientProxyNegotiated: client has negotiated with the proxy server.
	SocketClientProxyNegotiated
	// SocketClientTLSHandshaking: client is performing a TLS handshake.
	SocketClientTLSHandshaking
	// SocketClientTLSHandshaked: client has performed a TLS handshake.
	SocketClientTLSHandshaked
	// SocketClientComplete: client is done with a particular Connectable.
	SocketClientComplete
)

func (SocketClientEvent) String 

func (s SocketClientEvent) String() string

String returns the name in string for SocketClientEvent.

type SocketClientOverrides added in v0.0.5 

type SocketClientOverrides struct {
	// The function takes the following parameters:
	//
	//   - event
	//   - connectable
	//   - connection
	Event func(event SocketClientEvent, connectable SocketConnectabler, connection IOStreamer)
}

SocketClientOverrides contains methods that are overridable.

type SocketConnectable 

type SocketConnectable struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

SocketConnectable objects that describe one or more potential socket endpoints implement GSocketConnectable. Callers can then use gio.SocketConnectable.Enumerate() to get a gio.SocketAddressEnumerator to try out each socket address in turn until one succeeds, as shown in the sample code below. 

MyConnectionType *
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;
    }
}.

SocketConnectable wraps an interface. This means the user can get the underlying type by calling Cast().

func (*SocketConnectable) Enumerate 

func (connectable *SocketConnectable) Enumerate() SocketAddressEnumeratorrer

Enumerate creates a AddressEnumerator for connectable.

The function returns the following values:

  • socketAddressEnumerator: new AddressEnumerator.

func (*SocketConnectable) ProxyEnumerate 

func (connectable *SocketConnectable) ProxyEnumerate() SocketAddressEnumeratorrer

ProxyEnumerate creates a AddressEnumerator for connectable that will return a Address for each of its addresses that you must connect to via a proxy.

If connectable does not implement g_socket_connectable_proxy_enumerate(), this will fall back to calling g_socket_connectable_enumerate().

The function returns the following values:

  • socketAddressEnumerator: new AddressEnumerator.

func (*SocketConnectable) String 

func (connectable *SocketConnectable) String() string

String: format a Connectable as a string. This is a human-readable format for use in debugging output, and is not a stable serialization format. It is not suitable for use in user interfaces as it exposes too much information for a user.

If the Connectable implementation does not support string formatting, the implementation’s type name will be returned as a fallback.

The function returns the following values:

  • utf8: formatted string.

type SocketConnectableIface added in v0.0.5 

type SocketConnectableIface struct {
	// contains filtered or unexported fields
}

SocketConnectableIface provides an interface for returning a AddressEnumerator and AddressEnumerator

An instance of this type is always passed by reference.

type SocketConnectabler 

type SocketConnectabler interface {
	coreglib.Objector

	// Enumerate creates a AddressEnumerator for connectable.
	Enumerate() SocketAddressEnumeratorrer
	// ProxyEnumerate creates a AddressEnumerator for connectable that will
	// return a Address for each of its addresses that you must connect to via a
	// proxy.
	ProxyEnumerate() SocketAddressEnumeratorrer
	// String: format a Connectable as a string.
	String() string
}

SocketConnectabler describes SocketConnectable's interface methods.

type SocketConnection 

type SocketConnection struct {
	IOStream
	// contains filtered or unexported fields
}

SocketConnection: GSocketConnection is a gio.IOStream for a connected socket. They can be created either by gio.SocketClient when connecting to a host, or by gio.SocketListener 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 a gio.TCPConnection.

Choosing what type of object to construct is done with the socket connection factory, and it is possible for third parties to register custom socket connection types for specific combination of socket family/type/protocol using gio.SocketConnection().FactoryRegisterType.

To close a GSocketConnection, use gio.IOStream.Close(). Closing both substreams of the gio.IOStream separately will not close the underlying gio.Socket.

func (*SocketConnection) ConnectAsync 

func (connection *SocketConnection) ConnectAsync(ctx context.Context, address SocketAddresser, callback AsyncReadyCallback)

ConnectAsync: asynchronously connect connection to the specified remote address.

This clears the #GSocket:blocking flag on connection's underlying socket if it is currently set.

If #GSocket:timeout is set, the operation will time out and return G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue indefinitely until operating system timeouts (if any) are hit.

Use g_socket_connection_connect_finish() to retrieve the result.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address specifying the remote address.
  • callback (optional): ReadyCallback.

func (*SocketConnection) ConnectFinish 

func (connection *SocketConnection) ConnectFinish(result AsyncResulter) error

ConnectFinish gets the result of a g_socket_connection_connect_async() call.

The function takes the following parameters:

  • result: Result.

func (*SocketConnection) ConnectSocketConnection 

func (connection *SocketConnection) ConnectSocketConnection(ctx context.Context, address SocketAddresser) error

ConnectSocketConnection: connect connection to the specified remote address.

The function takes the following parameters:

  • ctx (optional): GCancellable or NULL.
  • address specifying the remote address.

func (*SocketConnection) IsConnected 

func (connection *SocketConnection) IsConnected() bool

IsConnected checks if connection is connected. This is equivalent to calling g_socket_is_connected() on connection's underlying #GSocket.

The function returns the following values:

  • ok: whether connection is connected.

func (*SocketConnection) LocalAddress 

func (connection *SocketConnection) LocalAddress() (SocketAddresser, error)

LocalAddress: try to get the local address of a socket connection.

The function returns the following values:

  • socketAddress or NULL on error. Free the returned object with g_object_unref().

func (*SocketConnection) RemoteAddress 

func (connection *SocketConnection) RemoteAddress() (SocketAddresser, error)

RemoteAddress: try to get the remote address of a socket connection.

Since GLib 2.40, when used with g_socket_client_connect() or g_socket_client_connect_async(), during emission of G_SOCKET_CLIENT_CONNECTING, this function will return the remote address that will be used for the connection. This allows applications to print e.g. "Connecting to example.com (10.42.77.3)...".

The function returns the following values:

  • socketAddress or NULL on error. Free the returned object with g_object_unref().

func (*SocketConnection) Socket 

func (connection *SocketConnection) Socket() *Socket

Socket gets the underlying #GSocket object of the connection. This can be useful if you want to do something unusual on it not supported by the Connection APIs.

The function returns the following values:

  • socket or NULL on error.

type SocketConnectionClass added in v0.0.5 

type SocketConnectionClass struct {
	// contains filtered or unexported fields
}

SocketConnectionClass: instance of this type is always passed by reference.

func (*SocketConnectionClass) ParentClass added in v0.0.5 

func (s *SocketConnectionClass) ParentClass() *IOStreamClass

type SocketConnectionOverrides added in v0.0.5 

type SocketConnectionOverrides struct {
}

SocketConnectionOverrides contains methods that are overridable.

type SocketControlMessage 

type SocketControlMessage struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

SocketControlMessage: GSocketControlMessage is a special-purpose utility message that can be sent to or received from a gio.Socket. 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 gio.Socket.SendMessage() and received with gio.Socket.ReceiveMessage().

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 gobject.Type type system before calling gio.Socket.ReceiveMessage() to read such a message.

func BaseSocketControlMessage 

func BaseSocketControlMessage(obj SocketControlMessager) *SocketControlMessage

BaseSocketControlMessage returns the underlying base object.

func (*SocketControlMessage) Level 

func (message *SocketControlMessage) Level() int

Level returns the "level" (i.e. the originating protocol) of the control message. This is often SOL_SOCKET.

The function returns the following values:

  • gint: integer describing the level.

func (*SocketControlMessage) MsgType 

func (message *SocketControlMessage) MsgType() int

MsgType returns the protocol specific type of the control message. For instance, for UNIX fd passing this would be SCM_RIGHTS.

The function returns the following values:

  • gint: integer describing the type of control message.

func (*SocketControlMessage) Serialize 

func (message *SocketControlMessage) Serialize(data unsafe.Pointer)

Serialize converts the data in the message to bytes placed in the message.

data is guaranteed to have enough space to fit the size returned by g_socket_control_message_get_size() on this object.

The function takes the following parameters:

  • data: buffer to write data to.

func (*SocketControlMessage) Size 

func (message *SocketControlMessage) Size() uint

Size returns the space required for the control message, not including headers or alignment.

The function returns the following values:

  • gsize: number of bytes required.

type SocketControlMessageClass added in v0.0.5 

type SocketControlMessageClass struct {
	// contains filtered or unexported fields
}

SocketControlMessageClass class structure for ControlMessage.

An instance of this type is always passed by reference.

type SocketControlMessageOverrides added in v0.0.5 

type SocketControlMessageOverrides struct {
	// Level returns the "level" (i.e. the originating protocol) of the control
	// message. This is often SOL_SOCKET.
	//
	// The function returns the following values:
	//
	//   - gint: integer describing the level.
	Level func() int
	// Size returns the space required for the control message, not including
	// headers or alignment.
	//
	// The function returns the following values:
	//
	//   - gsize: number of bytes required.
	Size func() uint
	// Type gets the protocol specific type of the message.
	Type func() int
	// Serialize converts the data in the message to bytes placed in the
	// message.
	//
	// data is guaranteed to have enough space to fit the size returned by
	// g_socket_control_message_get_size() on this object.
	//
	// The function takes the following parameters:
	//
	//   - data: buffer to write data to.
	Serialize func(data unsafe.Pointer)
}

SocketControlMessageOverrides contains methods that are overridable.

type SocketControlMessager 

type SocketControlMessager interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

SocketControlMessager describes types inherited from class SocketControlMessage.

To get the original type, the caller must assert this to an interface or another type.

func SocketControlMessageDeserialize 

func SocketControlMessageDeserialize(level, typ int, data []byte) SocketControlMessager

SocketControlMessageDeserialize tries to deserialize a socket control message of a given level and type. This will ask all known (to GType) subclasses of ControlMessage if they can understand this kind of message and if so deserialize it into a ControlMessage.

If there is no implementation for this kind of control message, NULL will be returned.

The function takes the following parameters:

  • level: socket level.
  • typ: socket control message type for the given level.
  • data: pointer to the message data.

The function returns the following values:

  • socketControlMessage (optional): deserialized message or NULL.

type SocketFamily 

type SocketFamily C.gint

SocketFamily: protocol family of a Address. (These values are identical to the system defines AF_INET, AF_INET6 and AF_UNIX, if available.). 

const (
	// SocketFamilyInvalid: no address family.
	SocketFamilyInvalid SocketFamily = 0
	// SocketFamilyUnix: UNIX domain family.
	SocketFamilyUnix SocketFamily = 1
	// SocketFamilyIPv4: IPv4 family.
	SocketFamilyIPv4 SocketFamily = 2
	// SocketFamilyIPv6: IPv6 family.
	SocketFamilyIPv6 SocketFamily = 10
)

func (SocketFamily) String 

func (s SocketFamily) String() string

String returns the name in string for SocketFamily.

type SocketListener 

type SocketListener struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

SocketListener: 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 gio.SocketListener.AddAddress() and gio.SocketListener.AddInetPort(). These will be listened on until gio.SocketListener.Close() is called. Dropping your final reference to the GSocketListener will not cause gio.SocketListener.Close() to be called implicitly, as some references to the GSocketListener may be held internally.

If you want to implement a network server, also look at gio.SocketService and gio.ThreadedSocketService which are subclasses of GSocketListener that make this even easier.

func NewSocketListener 

func NewSocketListener() *SocketListener

NewSocketListener creates a new Listener with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port().

The function returns the following values:

  • socketListener: new Listener.

func (*SocketListener) Accept 

func (listener *SocketListener) Accept(ctx context.Context) (*coreglib.Object, *SocketConnection, error)

Accept blocks waiting for a client to connect to any of the sockets added to the listener. Returns a Connection for the socket that was accepted.

If source_object is not NULL it will be filled out with the source object specified when the corresponding socket or address was added to the listener.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • sourceObject (optional): location where #GObject pointer will be stored, or NULL.
  • socketConnection on success, NULL on error.

func (*SocketListener) AcceptAsync 

func (listener *SocketListener) AcceptAsync(ctx context.Context, callback AsyncReadyCallback)

AcceptAsync: this is the asynchronous version of g_socket_listener_accept().

When the operation is finished callback will be called. You can then call g_socket_listener_accept_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional): ReadyCallback.

func (*SocketListener) AcceptFinish 

func (listener *SocketListener) AcceptFinish(result AsyncResulter) (*coreglib.Object, *SocketConnection, error)

AcceptFinish finishes an async accept operation. See g_socket_listener_accept_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • sourceObject (optional): optional #GObject identifying this source.
  • socketConnection on success, NULL on error.

func (*SocketListener) AcceptSocket 

func (listener *SocketListener) AcceptSocket(ctx context.Context) (*coreglib.Object, *Socket, error)

AcceptSocket blocks waiting for a client to connect to any of the sockets added to the listener. Returns the #GSocket that was accepted.

If you want to accept the high-level Connection, not a #GSocket, which is often the case, then you should use g_socket_listener_accept() instead.

If source_object is not NULL it will be filled out with the source object specified when the corresponding socket or address was added to the listener.

If cancellable is not NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error G_IO_ERROR_CANCELLED will be returned.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.

The function returns the following values:

  • sourceObject (optional): location where #GObject pointer will be stored, or NULL.
  • socket on success, NULL on error.

func (*SocketListener) AcceptSocketAsync 

func (listener *SocketListener) AcceptSocketAsync(ctx context.Context, callback AsyncReadyCallback)

AcceptSocketAsync: this is the asynchronous version of g_socket_listener_accept_socket().

When the operation is finished callback will be called. You can then call g_socket_listener_accept_socket_finish() to get the result of the operation.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • callback (optional): ReadyCallback.

func (*SocketListener) AcceptSocketFinish 

func (listener *SocketListener) AcceptSocketFinish(result AsyncResulter) (*coreglib.Object, *Socket, error)

AcceptSocketFinish finishes an async accept operation. See g_socket_listener_accept_socket_async().

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • sourceObject (optional): optional #GObject identifying this source.
  • socket on success, NULL on error.

func (*SocketListener) AddAddress 

func (listener *SocketListener) AddAddress(address SocketAddresser, typ SocketType, protocol SocketProtocol, sourceObject *coreglib.Object) (SocketAddresser, error)

AddAddress creates a socket of type type and protocol protocol, binds it to address and adds it to the set of sockets we're accepting sockets from.

Note that adding an IPv6 address, depending on the platform, may or may not result in a listener that also accepts IPv4 connections. For more deterministic behavior, see g_socket_listener_add_inet_port().

source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

If successful and effective_address is non-NULL then it will be set to the address that the binding actually occurred at. This is helpful for determining the port number that was used for when requesting a binding to port 0 (ie: "any port"). This address, if requested, belongs to the caller and must be freed.

Call g_socket_listener_close() to stop listening on address; this will not be done automatically when you drop your final reference to listener, as references may be held internally.

The function takes the following parameters:

  • address: Address.
  • typ: Type.
  • protocol: Protocol.
  • sourceObject (optional): optional #GObject identifying this source.

The function returns the following values:

  • effectiveAddress (optional): location to store the address that was bound to, or NULL.

func (*SocketListener) AddAnyInetPort 

func (listener *SocketListener) AddAnyInetPort(sourceObject *coreglib.Object) (uint16, error)

AddAnyInetPort listens for TCP connections on any available port number for both IPv6 and IPv4 (if each is available).

This is useful if you need to have a socket for incoming connections but don't care about the specific port number.

source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

The function takes the following parameters:

  • sourceObject (optional): optional #GObject identifying this source.

The function returns the following values:

  • guint16: port number, or 0 in case of failure.

func (*SocketListener) AddInetPort 

func (listener *SocketListener) AddInetPort(port uint16, sourceObject *coreglib.Object) error

AddInetPort: helper function for g_socket_listener_add_address() that creates a TCP/IP socket listening on IPv4 and IPv6 (if supported) on the specified port on all interfaces.

source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

Call g_socket_listener_close() to stop listening on port; this will not be done automatically when you drop your final reference to listener, as references may be held internally.

The function takes the following parameters:

  • port: IP port number (non-zero).
  • sourceObject (optional): optional #GObject identifying this source.

func (*SocketListener) AddSocket 

func (listener *SocketListener) AddSocket(socket *Socket, sourceObject *coreglib.Object) error

AddSocket adds socket to the set of sockets that we try to accept new clients from. The socket must be bound to a local address and listened to.

source_object will be passed out in the various calls to accept to identify this particular source, which is useful if you're listening on multiple addresses and do different things depending on what address is connected to.

The socket will not be automatically closed when the listener is finalized unless the listener held the final reference to the socket. Before GLib 2.42, the socket was automatically closed on finalization of the listener, even if references to it were held elsewhere.

The function takes the following parameters:

  • socket: listening #GSocket.
  • sourceObject (optional): optional #GObject identifying this source.

func (*SocketListener) Close 

func (listener *SocketListener) Close()

Close closes all the sockets in the listener.

func (*SocketListener) ConnectEvent 

func (listener *SocketListener) ConnectEvent(f func(event SocketListenerEvent, socket *Socket)) coreglib.SignalHandle

ConnectEvent is emitted when listener's activity on socket changes state. Note that when listener is used to listen on both IPv4 and IPv6, a separate set of signals will be emitted for each, and the order they happen in is undefined.

func (*SocketListener) SetBacklog 

func (listener *SocketListener) SetBacklog(listenBacklog int)

SetBacklog sets the listen backlog on the sockets in the listener. This must be called before adding any sockets, addresses or ports to the Listener (for example, by calling g_socket_listener_add_inet_port()) to be effective.

See g_socket_set_listen_backlog() for details.

The function takes the following parameters:

  • listenBacklog: integer.

type SocketListenerClass added in v0.0.5 

type SocketListenerClass struct {
	// contains filtered or unexported fields
}

SocketListenerClass class structure for Listener.

An instance of this type is always passed by reference.

type SocketListenerEvent 

type SocketListenerEvent C.gint

SocketListenerEvent describes an event occurring on a Listener. See the Listener::event signal for more details.

Additional values may be added to this type in the future. 

const (
	// SocketListenerBinding: listener is about to bind a socket.
	SocketListenerBinding SocketListenerEvent = iota
	// SocketListenerBound: listener has bound a socket.
	SocketListenerBound
	// SocketListenerListening: listener is about to start listening on this
	// socket.
	SocketListenerListening
	// SocketListenerListened: listener is now listening on this socket.
	SocketListenerListened
)

func (SocketListenerEvent) String 

func (s SocketListenerEvent) String() string

String returns the name in string for SocketListenerEvent.

type SocketListenerOverrides added in v0.0.5 

type SocketListenerOverrides struct {
	// Changed: virtual method called when the set of socket listened to
	// changes.
	Changed func()
	// The function takes the following parameters:
	//
	//   - event
	//   - socket
	Event func(event SocketListenerEvent, socket *Socket)
}

SocketListenerOverrides contains methods that are overridable.

type SocketMsgFlags 

type SocketMsgFlags C.guint

SocketMsgFlags flags used in g_socket_receive_message() and g_socket_send_message(). The flags listed in the enum are some commonly available flags, but the values used for them are the same as on the platform, and any other flags are passed in/out as is. So to use a platform specific flag, just include the right system header and pass in the flag. 

const (
	// SocketMsgNone: no flags.
	SocketMsgNone SocketMsgFlags = 0b0
	// SocketMsgOob: request to send/receive out of band data.
	SocketMsgOob SocketMsgFlags = 0b1
	// SocketMsgPeek: read data from the socket without removing it from the
	// queue.
	SocketMsgPeek SocketMsgFlags = 0b10
	// SocketMsgDontroute: don't use a gateway to send out the packet, only send
	// to hosts on directly connected networks.
	SocketMsgDontroute SocketMsgFlags = 0b100
)

func (SocketMsgFlags) Has 

func (s SocketMsgFlags) Has(other SocketMsgFlags) bool

Has returns true if s contains other.

func (SocketMsgFlags) String 

func (s SocketMsgFlags) String() string

String returns the names in string for SocketMsgFlags.

type SocketOverrides added in v0.0.5 

type SocketOverrides struct {
}

SocketOverrides contains methods that are overridable.

type SocketProtocol 

type SocketProtocol C.gint

SocketProtocol: protocol identifier is specified when creating a #GSocket, which is a family/type specific identifier, where 0 means the default protocol for the particular family/type.

This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. 

const (
	// SocketProtocolUnknown: protocol type is unknown.
	SocketProtocolUnknown SocketProtocol = -1
	// SocketProtocolDefault: default protocol for the family/type.
	SocketProtocolDefault SocketProtocol = 0
	// SocketProtocolTCP: TCP over IP.
	SocketProtocolTCP SocketProtocol = 6
	// SocketProtocolUDP: UDP over IP.
	SocketProtocolUDP SocketProtocol = 17
	// SocketProtocolSCTP: SCTP over IP.
	SocketProtocolSCTP SocketProtocol = 132
)

func (SocketProtocol) String 

func (s SocketProtocol) String() string

String returns the name in string for SocketProtocol.

type SocketService 

type SocketService struct {
	SocketListener
	// contains filtered or unexported fields
}

SocketService: GSocketService is an object that represents a service that is provided to the network or over local sockets. When a new connection is made to the service the gio.SocketService::incoming signal is emitted.

A GSocketService is a subclass of gio.SocketListener and you need to add the addresses you want to accept connections on with the gio.SocketListener APIs.

There are two options for implementing a network service based on GSocketService. The first is to create the service using gio.SocketService.New and to connect to the gio.SocketService::incoming signal. The second is to subclass GSocketService and override the default signal handler implementation.

In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain blocking code then see gio.ThreadedSocketService.

The socket service runs on the main loop of the thread-default context (see glib.MainContext.PushThreadDefault()) 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.

func NewSocketService 

func NewSocketService() *SocketService

NewSocketService creates a new Service with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() or g_socket_listener_add_inet_port().

New services are created active, there is no need to call g_socket_service_start(), unless g_socket_service_stop() has been called before.

The function returns the following values:

  • socketService: new Service.

func (*SocketService) ConnectIncoming 

func (service *SocketService) ConnectIncoming(f func(connection *SocketConnection, sourceObject *coreglib.Object) (ok bool)) coreglib.SignalHandle

ConnectIncoming signal is emitted when a new incoming connection to service needs to be handled. The handler must initiate the handling of connection, but may not block; in essence, asynchronous operations must be used.

connection will be unreffed once the signal handler returns, so you need to ref it yourself if you are planning to use it.

func (*SocketService) IsActive 

func (service *SocketService) IsActive() bool

IsActive: check whether the service is active or not. An active service will accept new clients that connect, while a non-active service will let connecting clients queue up until the service is started.

The function returns the following values:

  • ok: TRUE if the service is active, FALSE otherwise.

func (*SocketService) Start 

func (service *SocketService) Start()

Start restarts the service, i.e. start accepting connections from the added sockets when the mainloop runs. This only needs to be called after the service has been stopped from g_socket_service_stop().

This call is thread-safe, so it may be called from a thread handling an incoming client request.

func (*SocketService) Stop 

func (service *SocketService) Stop()

Stop stops the service, i.e. stops accepting connections from the added sockets when the mainloop runs.

This call is thread-safe, so it may be called from a thread handling an incoming client request.

Note that this only stops accepting new connections; it does not close the listening sockets, and you can call g_socket_service_start() again later to begin listening again. To close the listening sockets, call g_socket_listener_close(). (This will happen automatically when the Service is finalized.)

This must be called before calling g_socket_listener_close() as the socket service will start accepting connections immediately when a new socket is added.

type SocketServiceClass added in v0.0.5 

type SocketServiceClass struct {
	// contains filtered or unexported fields
}

SocketServiceClass class structure for Service.

An instance of this type is always passed by reference.

func (*SocketServiceClass) ParentClass added in v0.0.5 

func (s *SocketServiceClass) ParentClass() *SocketListenerClass

type SocketServiceOverrides added in v0.0.5 

type SocketServiceOverrides struct {
	// Incoming: signal emitted when new connections are accepted.
	//
	// The function takes the following parameters:
	//
	//   - connection
	//   - sourceObject
	Incoming func(connection *SocketConnection, sourceObject *coreglib.Object) bool
}

SocketServiceOverrides contains methods that are overridable.

type SocketType 

type SocketType C.gint

SocketType flags used when creating a #GSocket. Some protocols may not implement all the socket types. 

const (
	// SocketTypeInvalid: type unknown or wrong.
	SocketTypeInvalid SocketType = iota
	// SocketTypeStream: reliable connection-based byte streams (e.g. TCP).
	SocketTypeStream
	// SocketTypeDatagram: connectionless, unreliable datagram passing. (e.g.
	// UDP).
	SocketTypeDatagram
	// SocketTypeSeqpacket: reliable connection-based passing of datagrams of
	// fixed maximum length (e.g. SCTP).
	SocketTypeSeqpacket
)

func (SocketType) String 

func (s SocketType) String() string

String returns the name in string for SocketType.

type SrvTarget 

type SrvTarget struct {
	// contains filtered or unexported fields
}

SrvTarget: single target host/port that a network service is running on.

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 gio.Resolver.LookupService() or gio.Resolver.LookupServiceAsync() to find the GSrvTargets for a given service. However, if you are simply planning to connect to the remote service, you can use gio.NetworkService’s gio.SocketConnectable interface and not need to worry about GSrvTarget at all.

An instance of this type is always passed by reference.

func NewSrvTarget 

func NewSrvTarget(hostname string, port uint16, priority uint16, weight uint16) *SrvTarget

NewSrvTarget constructs a struct SrvTarget.

func (*SrvTarget) Copy 

func (target *SrvTarget) Copy() *SrvTarget

Copy copies target.

The function returns the following values:

  • srvTarget: copy of target.

func (*SrvTarget) Hostname 

func (target *SrvTarget) Hostname() string

Hostname gets target's hostname (in ASCII form; if you are going to present this to the user, you should use g_hostname_is_ascii_encoded() to check if it contains encoded Unicode segments, and use g_hostname_to_unicode() to convert it if it does.).

The function returns the following values:

  • utf8 target's hostname.

func (*SrvTarget) Port 

func (target *SrvTarget) Port() uint16

Port gets target's port.

The function returns the following values:

  • guint16 target's port.

func (*SrvTarget) Priority 

func (target *SrvTarget) Priority() uint16

Priority gets target's priority. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782.

The function returns the following values:

  • guint16 target's priority.

func (*SrvTarget) Weight 

func (target *SrvTarget) Weight() uint16

Weight gets target's weight. You should not need to look at this; #GResolver already sorts the targets according to the algorithm in RFC 2782.

The function returns the following values:

  • guint16 target's weight.

type StaticResource 

type StaticResource struct {
	// contains filtered or unexported fields
}

StaticResource is an opaque data structure and can only be accessed using the following functions.

An instance of this type is always passed by reference.

func (*StaticResource) Fini 

func (staticResource *StaticResource) Fini()

Fini: finalized a GResource initialized by g_static_resource_init().

This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code.

func (*StaticResource) Init 

func (staticResource *StaticResource) Init()

Init initializes a GResource from static data using a GStaticResource.

This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code.

func (*StaticResource) Resource 

func (staticResource *StaticResource) Resource() *Resource

Resource gets the GResource that was registered by a call to g_static_resource_init().

This is normally used by code generated by [glib-compile-resources][glib-compile-resources] and is not typically used by other code.

The function returns the following values:

  • resource: #GResource.

type SubprocessFlags 

type SubprocessFlags C.guint

SubprocessFlags flags to define the behaviour of a #GSubprocess.

Note that the default for stdin is to redirect from /dev/null. For stdout and stderr the default are for them to inherit the corresponding descriptor from the calling process.

Note that it is a programmer error to mix 'incompatible' flags. For example, you may not request both G_SUBPROCESS_FLAGS_STDOUT_PIPE and G_SUBPROCESS_FLAGS_STDOUT_SILENCE. 

const (
	// SubprocessFlagsNone: no flags.
	SubprocessFlagsNone SubprocessFlags = 0b0
	// SubprocessFlagsStdinPipe: create a pipe for the stdin of the spawned
	// process that can be accessed with g_subprocess_get_stdin_pipe().
	SubprocessFlagsStdinPipe SubprocessFlags = 0b1
	// SubprocessFlagsStdinInherit: stdin is inherited from the calling process.
	SubprocessFlagsStdinInherit SubprocessFlags = 0b10
	// SubprocessFlagsStdoutPipe: create a pipe for the stdout of the spawned
	// process that can be accessed with g_subprocess_get_stdout_pipe().
	SubprocessFlagsStdoutPipe SubprocessFlags = 0b100
	// SubprocessFlagsStdoutSilence: silence the stdout of the spawned process
	// (ie: redirect to /dev/null).
	SubprocessFlagsStdoutSilence SubprocessFlags = 0b1000
	// SubprocessFlagsStderrPipe: create a pipe for the stderr of the spawned
	// process that can be accessed with g_subprocess_get_stderr_pipe().
	SubprocessFlagsStderrPipe SubprocessFlags = 0b10000
	// SubprocessFlagsStderrSilence: silence the stderr of the spawned process
	// (ie: redirect to /dev/null).
	SubprocessFlagsStderrSilence SubprocessFlags = 0b100000
	// SubprocessFlagsStderrMerge: merge the stderr of the spawned process with
	// whatever the stdout happens to be. This is a good way of directing both
	// streams to a common log file, for example.
	SubprocessFlagsStderrMerge SubprocessFlags = 0b1000000
	// SubprocessFlagsInheritFds: spawned processes will inherit the file
	// descriptors of their parent, unless those descriptors have been
	// explicitly marked as close-on-exec. This flag has no effect over the
	// "standard" file descriptors (stdin, stdout, stderr).
	SubprocessFlagsInheritFds SubprocessFlags = 0b10000000
	// SubprocessFlagsSearchPathFromEnvp: if path searching is needed when
	// spawning the subprocess, use the PATH in the launcher environment.
	// (Since: 2.72).
	SubprocessFlagsSearchPathFromEnvp SubprocessFlags = 0b100000000
)

func (SubprocessFlags) Has 

func (s SubprocessFlags) Has(other SubprocessFlags) bool

Has returns true if s contains other.

func (SubprocessFlags) String 

func (s SubprocessFlags) String() string

String returns the names in string for SubprocessFlags.

type TCPConnection 

type TCPConnection struct {
	SocketConnection
	// contains filtered or unexported fields
}

TCPConnection: this is the subclass of gio.SocketConnection that is created for TCP/IP sockets.

func (*TCPConnection) GracefulDisconnect 

func (connection *TCPConnection) GracefulDisconnect() bool

GracefulDisconnect checks if graceful disconnects are used. See g_tcp_connection_set_graceful_disconnect().

The function returns the following values:

  • ok: TRUE if graceful disconnect is used on close, FALSE otherwise.

func (*TCPConnection) SetGracefulDisconnect 

func (connection *TCPConnection) SetGracefulDisconnect(gracefulDisconnect bool)

SetGracefulDisconnect: this enables graceful disconnects on close. A graceful disconnect means that we signal the receiving end that the connection is terminated and wait for it to close the connection before closing the connection.

A graceful disconnect means that we can be sure that we successfully sent all the outstanding data to the other end, or get an error reported. However, it also means we have to wait for all the data to reach the other side and for it to acknowledge this by closing the socket, which may take a while. For this reason it is disabled by default.

The function takes the following parameters:

  • gracefulDisconnect: whether to do graceful disconnects or not.

type TCPConnectionClass added in v0.0.5 

type TCPConnectionClass struct {
	// contains filtered or unexported fields
}

TCPConnectionClass: instance of this type is always passed by reference.

func (*TCPConnectionClass) ParentClass added in v0.0.5 

func (t *TCPConnectionClass) ParentClass() *SocketConnectionClass

type TCPConnectionOverrides added in v0.0.5 

type TCPConnectionOverrides struct {
}

TCPConnectionOverrides contains methods that are overridable.

type TCPWrapperConnection 

type TCPWrapperConnection struct {
	TCPConnection
	// contains filtered or unexported fields
}

TCPWrapperConnection: GTcpWrapperConnection can be used to wrap a gio.IOStream that is based on a gio.Socket, but which is not actually a gio.SocketConnection. This is used by gio.SocketClient so that it can always return a gio.SocketConnection, even when the connection it has actually created is not directly a gio.SocketConnection.

func NewTCPWrapperConnection 

func NewTCPWrapperConnection(baseIoStream IOStreamer, socket *Socket) *TCPWrapperConnection

NewTCPWrapperConnection wraps base_io_stream and socket together as a Connection.

The function takes the following parameters:

  • baseIoStream to wrap.
  • socket associated with base_io_stream.

The function returns the following values:

  • tcpWrapperConnection: new Connection.

func (*TCPWrapperConnection) BaseIOStream 

func (conn *TCPWrapperConnection) BaseIOStream() IOStreamer

BaseIOStream gets conn's base OStream.

The function returns the following values:

  • ioStream conn's base OStream.

type TCPWrapperConnectionClass added in v0.0.5 

type TCPWrapperConnectionClass struct {
	// contains filtered or unexported fields
}

TCPWrapperConnectionClass: instance of this type is always passed by reference.

func (*TCPWrapperConnectionClass) ParentClass added in v0.0.5 

func (t *TCPWrapperConnectionClass) ParentClass() *TCPConnectionClass

type TCPWrapperConnectionOverrides added in v0.0.5 

type TCPWrapperConnectionOverrides struct {
}

TCPWrapperConnectionOverrides contains methods that are overridable.

type TLSAuthenticationMode 

type TLSAuthenticationMode C.gint

TLSAuthenticationMode: client authentication mode for a ServerConnection. 

const (
	// TLSAuthenticationNone: client authentication not required.
	TLSAuthenticationNone TLSAuthenticationMode = iota
	// TLSAuthenticationRequested: client authentication is requested.
	TLSAuthenticationRequested
	// TLSAuthenticationRequired: client authentication is required.
	TLSAuthenticationRequired
)

func (TLSAuthenticationMode) String 

func (t TLSAuthenticationMode) String() string

String returns the name in string for TLSAuthenticationMode.

type TLSBackend 

type TLSBackend struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TLSBackend: TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an internal type used to coordinate the different classes implemented by a TLS backend.

TLSBackend wraps an interface. This means the user can get the underlying type by calling Cast().

func TLSBackendGetDefault 

func TLSBackendGetDefault() *TLSBackend

TLSBackendGetDefault gets the default Backend for the system.

The function returns the following values:

  • tlsBackend which will be a dummy object if no TLS backend is available.

func (*TLSBackend) CertificateType 

func (backend *TLSBackend) CertificateType() coreglib.Type

CertificateType gets the #GType of backend's Certificate implementation.

The function returns the following values:

  • gType of backend's Certificate implementation.

func (*TLSBackend) ClientConnectionType 

func (backend *TLSBackend) ClientConnectionType() coreglib.Type

ClientConnectionType gets the #GType of backend's ClientConnection implementation.

The function returns the following values:

  • gType of backend's ClientConnection implementation.

func (*TLSBackend) DTLSClientConnectionType 

func (backend *TLSBackend) DTLSClientConnectionType() coreglib.Type

DTLSClientConnectionType gets the #GType of backend’s ClientConnection implementation.

The function returns the following values:

  • gType of backend’s ClientConnection implementation, or G_TYPE_INVALID if this backend doesn’t support DTLS.

func (*TLSBackend) DTLSServerConnectionType 

func (backend *TLSBackend) DTLSServerConnectionType() coreglib.Type

DTLSServerConnectionType gets the #GType of backend’s ServerConnection implementation.

The function returns the following values:

  • gType of backend’s ServerConnection implementation, or G_TYPE_INVALID if this backend doesn’t support DTLS.

func (*TLSBackend) DefaultDatabase 

func (backend *TLSBackend) DefaultDatabase() TLSDatabaser

DefaultDatabase gets the default Database used to verify TLS connections.

The function returns the following values:

  • tlsDatabase: default database, which should be unreffed when done.

func (*TLSBackend) FileDatabaseType 

func (backend *TLSBackend) FileDatabaseType() coreglib.Type

FileDatabaseType gets the #GType of backend's FileDatabase implementation.

The function returns the following values:

  • gType of backend's FileDatabase implementation.

func (*TLSBackend) ServerConnectionType 

func (backend *TLSBackend) ServerConnectionType() coreglib.Type

ServerConnectionType gets the #GType of backend's ServerConnection implementation.

The function returns the following values:

  • gType of backend's ServerConnection implementation.

func (*TLSBackend) SetDefaultDatabase 

func (backend *TLSBackend) SetDefaultDatabase(database TLSDatabaser)

SetDefaultDatabase: set the default Database used to verify TLS connections

Any subsequent call to g_tls_backend_get_default_database() will return the database set in this call. Existing databases and connections are not modified.

Setting a NULL default database will reset to using the system default database as if g_tls_backend_set_default_database() had never been called.

The function takes the following parameters:

  • database (optional): Database.

func (*TLSBackend) SupportsDTLS 

func (backend *TLSBackend) SupportsDTLS() bool

SupportsDTLS checks if DTLS is supported. DTLS support may not be available even if TLS support is available, and vice-versa.

The function returns the following values:

  • ok: whether DTLS is supported.

func (*TLSBackend) SupportsTLS 

func (backend *TLSBackend) SupportsTLS() bool

SupportsTLS checks if TLS is supported; if this returns FALSE for the default Backend, it means no "real" TLS backend is available.

The function returns the following values:

  • ok: whether or not TLS is supported.

type TLSBackendInterface added in v0.0.5 

type TLSBackendInterface struct {
	// contains filtered or unexported fields
}

TLSBackendInterface provides an interface for describing TLS-related types.

An instance of this type is always passed by reference.

type TLSBackender 

type TLSBackender interface {
	coreglib.Objector

	// CertificateType gets the #GType of backend's Certificate implementation.
	CertificateType() coreglib.Type
	// ClientConnectionType gets the #GType of backend's ClientConnection
	// implementation.
	ClientConnectionType() coreglib.Type
	// DefaultDatabase gets the default Database used to verify TLS connections.
	DefaultDatabase() TLSDatabaser
	// DTLSClientConnectionType gets the #GType of backend’s ClientConnection
	// implementation.
	DTLSClientConnectionType() coreglib.Type
	// DTLSServerConnectionType gets the #GType of backend’s ServerConnection
	// implementation.
	DTLSServerConnectionType() coreglib.Type
	// FileDatabaseType gets the #GType of backend's FileDatabase
	// implementation.
	FileDatabaseType() coreglib.Type
	// ServerConnectionType gets the #GType of backend's ServerConnection
	// implementation.
	ServerConnectionType() coreglib.Type
	// SetDefaultDatabase: set the default Database used to verify TLS
	// connections.
	SetDefaultDatabase(database TLSDatabaser)
	// SupportsDTLS checks if DTLS is supported.
	SupportsDTLS() bool
	// SupportsTLS checks if TLS is supported; if this returns FALSE for the
	// default Backend, it means no "real" TLS backend is available.
	SupportsTLS() bool
}

TLSBackender describes TLSBackend's interface methods.

type TLSCertificate 

type TLSCertificate struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TLSCertificate: certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a gio.TLSServerConnection).

func BaseTLSCertificate 

func BaseTLSCertificate(obj TLSCertificater) *TLSCertificate

BaseTLSCertificate returns the underlying base object.

func NewTLSCertificateFromFile 

func NewTLSCertificateFromFile(file string) (*TLSCertificate, error)

NewTLSCertificateFromFile creates a Certificate from the data in file.

As of 2.72, if the filename ends in .p12 or .pfx the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by g_tls_certificate_new_from_pem(). See those functions for exact details.

If file cannot be read or parsed, the function will return NULL and set error.

The function takes the following parameters:

  • file containing a certificate to import.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL on error.

func NewTLSCertificateFromFileWithPassword added in v0.3.0 

func NewTLSCertificateFromFileWithPassword(file, password string) (*TLSCertificate, error)

NewTLSCertificateFromFileWithPassword creates a Certificate from the data in file.

If file cannot be read or parsed, the function will return NULL and set error.

Any unknown file types will error with G_IO_ERROR_NOT_SUPPORTED. Currently only .p12 and .pfx files are supported. See g_tls_certificate_new_from_pkcs12() for more details.

The function takes the following parameters:

  • file containing a certificate to import.
  • password for PKCS #12 files.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL on error.

func NewTLSCertificateFromFiles 

func NewTLSCertificateFromFiles(certFile, keyFile string) (*TLSCertificate, error)

NewTLSCertificateFromFiles creates a Certificate from the PEM-encoded data in cert_file and key_file. The returned certificate will be the first certificate found in cert_file. As of GLib 2.44, if cert_file contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the Certificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

If either file cannot be read or parsed, the function will return NULL and set error. Otherwise, this behaves like g_tls_certificate_new_from_pem().

The function takes the following parameters:

  • certFile: file containing one or more PEM-encoded certificates to import.
  • keyFile: file containing a PEM-encoded private key to import.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL on error.

func NewTLSCertificateFromPKCS11URIs 

func NewTLSCertificateFromPKCS11URIs(pkcs11Uri, privateKeyPkcs11Uri string) (*TLSCertificate, error)

NewTLSCertificateFromPKCS11URIs creates a Certificate from a PKCS \#11 (https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI.

An example pkcs11_uri would be pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My20Client20Certificate;id=01

Where the token’s layout is: 

Object 0:
  URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My20Client20Certificate;id=01;object=private20key;type=private
  Type: Private key (RSA-2048)
  ID: 01

Object 1:
  URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My20Client20Certificate;id=01;object=Certificate20for20Authentication;type=cert
  Type: X.509 Certificate (RSA-2048)
  ID: 01

In this case the certificate and private key would both be detected and used as expected. pkcs_uri may also just reference an X.509 certificate object and then optionally private_key_pkcs11_uri allows using a private key exposed under a different URI.

Note that the private key is not accessed until usage and may fail or require a PIN later.

The function takes the following parameters:

  • pkcs11Uri: PKCS \#11 URI.
  • privateKeyPkcs11Uri (optional): PKCS \#11 URI.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL on error.

func NewTLSCertificateFromPKCS12 added in v0.3.0 

func NewTLSCertificateFromPKCS12(data []byte, password string) (*TLSCertificate, error)

NewTLSCertificateFromPKCS12 creates a Certificate from the data in data. It must contain a certificate and matching private key.

If extra certificates are included they will be verified as a chain and the Certificate:issuer property will be set. All other data will be ignored.

You can pass as single password for all of the data which will be used both for the PKCS #12 container as well as encrypted private keys. If decryption fails it will error with G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD.

This constructor requires support in the current Backend. If support is missing it will error with G_IO_ERROR_NOT_SUPPORTED.

Other parsing failures will error with G_TLS_ERROR_BAD_CERTIFICATE.

The function takes the following parameters:

  • data: DER-encoded PKCS #12 format certificate data.
  • password (optional): optional password for encrypted certificate data.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL if data is invalid.

func NewTLSCertificateFromPem 

func NewTLSCertificateFromPem(data string) (*TLSCertificate, error)

NewTLSCertificateFromPem creates a Certificate from the PEM-encoded data in data. If data includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the Certificate:private-key-pem property for information about supported formats.)

The returned certificate will be the first certificate found in data. As of GLib 2.44, if data contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the Certificate:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned.

The function takes the following parameters:

  • data: PEM-encoded certificate data.

The function returns the following values:

  • tlsCertificate: new certificate, or NULL if data is invalid.

func (*TLSCertificate) IsSame 

func (certOne *TLSCertificate) IsSame(certTwo TLSCertificater) bool

IsSame: check if two Certificate objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their Certificate:issuer, Certificate:private-key, or Certificate:private-key-pem properties differ.

The function takes the following parameters:

  • certTwo: second certificate to compare.

The function returns the following values:

  • ok: whether the same or not.

func (*TLSCertificate) Issuer 

func (cert *TLSCertificate) Issuer() TLSCertificater

Issuer gets the Certificate representing cert's issuer, if known.

The function returns the following values:

  • tlsCertificate (optional): certificate of cert's issuer, or NULL if cert is self-signed or signed with an unknown certificate.

func (*TLSCertificate) IssuerName added in v0.3.0 

func (cert *TLSCertificate) IssuerName() string

IssuerName returns the issuer name from the certificate.

The function returns the following values:

  • utf8 (optional): issuer name, or NULL if it's not available.

func (*TLSCertificate) NotValidAfter added in v0.3.0 

func (cert *TLSCertificate) NotValidAfter() *glib.DateTime

NotValidAfter returns the time at which the certificate became or will become invalid.

The function returns the following values:

  • dateTime (optional): not-valid-after date, or NULL if it's not available.

func (*TLSCertificate) NotValidBefore added in v0.3.0 

func (cert *TLSCertificate) NotValidBefore() *glib.DateTime

NotValidBefore returns the time at which the certificate became or will become valid.

The function returns the following values:

  • dateTime (optional): not-valid-before date, or NULL if it's not available.

func (*TLSCertificate) SubjectName added in v0.3.0 

func (cert *TLSCertificate) SubjectName() string

SubjectName returns the subject name from the certificate.

The function returns the following values:

  • utf8 (optional): subject name, or NULL if it's not available.

func (*TLSCertificate) Verify 

func (cert *TLSCertificate) Verify(identity SocketConnectabler, trustedCa TLSCertificater) TLSCertificateFlags

Verify: this verifies cert and returns a set of CertificateFlags indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database.

If cert is valid, G_TLS_CERTIFICATE_NO_FLAGS is returned.

If identity is not NULL, cert's name(s) will be compared against it, and G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value if it does not match. If identity is NULL, that bit will never be set in the return value.

If trusted_ca is not NULL, then cert (or one of the certificates in its chain) must be signed by it, or else G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If trusted_ca is NULL, that bit will never be set in the return value.

GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate.

Because TLS session context is not used, Certificate may not perform as many checks on the certificates as Connection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let Connection handle the verification.

The function takes the following parameters:

  • identity (optional): expected peer identity.
  • trustedCa (optional): certificate of a trusted authority.

The function returns the following values:

  • tlsCertificateFlags: appropriate CertificateFlags.

type TLSCertificateClass added in v0.0.5 

type TLSCertificateClass struct {
	// contains filtered or unexported fields
}

TLSCertificateClass: instance of this type is always passed by reference.

type TLSCertificateFlags 

type TLSCertificateFlags C.guint

TLSCertificateFlags: set of flags describing TLS certification validation. This can be used to describe why a particular certificate was rejected (for example, in Connection::accept-certificate).

GLib guarantees that if certificate verification fails, at least one flag will be set, but it does not guarantee that all possible flags will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. 

const (
	// TLSCertificateNoFlags: no flags set. Since: 2.74.
	TLSCertificateNoFlags TLSCertificateFlags = 0b0
	// TLSCertificateUnknownCa: signing certificate authority is not known.
	TLSCertificateUnknownCa TLSCertificateFlags = 0b1
	// TLSCertificateBadIdentity: certificate does not match the expected
	// identity of the site that it was retrieved from.
	TLSCertificateBadIdentity TLSCertificateFlags = 0b10
	// TLSCertificateNotActivated certificate's activation time is still in the
	// future.
	TLSCertificateNotActivated TLSCertificateFlags = 0b100
	// TLSCertificateExpired: certificate has expired.
	TLSCertificateExpired TLSCertificateFlags = 0b1000
	// TLSCertificateRevoked: certificate has been revoked according to the
	// Connection's certificate revocation list.
	TLSCertificateRevoked TLSCertificateFlags = 0b10000
	// TLSCertificateInsecure certificate's algorithm is considered insecure.
	TLSCertificateInsecure TLSCertificateFlags = 0b100000
	// TLSCertificateGenericError: some other error occurred validating the
	// certificate.
	TLSCertificateGenericError TLSCertificateFlags = 0b1000000
	// TLSCertificateValidateAll: combination of all of the above flags.
	TLSCertificateValidateAll TLSCertificateFlags = 0b1111111
)

func (TLSCertificateFlags) Has 

func (t TLSCertificateFlags) Has(other TLSCertificateFlags) bool

Has returns true if t contains other.

func (TLSCertificateFlags) String 

func (t TLSCertificateFlags) String() string

String returns the names in string for TLSCertificateFlags.

type TLSCertificateOverrides added in v0.0.5 

type TLSCertificateOverrides struct {
	// Verify: this verifies cert and returns a set of CertificateFlags
	// indicating any problems found with it. This can be used to verify a
	// certificate outside the context of making a connection, or to check a
	// certificate against a CA that is not part of the system CA database.
	//
	// If cert is valid, G_TLS_CERTIFICATE_NO_FLAGS is returned.
	//
	// If identity is not NULL, cert's name(s) will be compared against it,
	// and G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value if it
	// does not match. If identity is NULL, that bit will never be set in the
	// return value.
	//
	// If trusted_ca is not NULL, then cert (or one of the certificates in its
	// chain) must be signed by it, or else G_TLS_CERTIFICATE_UNKNOWN_CA will
	// be set in the return value. If trusted_ca is NULL, that bit will never be
	// set in the return value.
	//
	// GLib guarantees that if certificate verification fails, at least one
	// error will be set in the return value, but it does not guarantee that
	// all possible errors will be set. Accordingly, you may not safely
	// decide to ignore any particular type of error. For example, it would be
	// incorrect to mask G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
	// certificates, because this could potentially be the only error flag set
	// even if other problems exist with the certificate.
	//
	// Because TLS session context is not used, Certificate may not perform
	// as many checks on the certificates as Connection would. For example,
	// certificate constraints may not be honored, and revocation checks may
	// not be performed. The best way to verify TLS certificates used by a TLS
	// connection is to let Connection handle the verification.
	//
	// The function takes the following parameters:
	//
	//   - identity (optional): expected peer identity.
	//   - trustedCa (optional): certificate of a trusted authority.
	//
	// The function returns the following values:
	//
	//   - tlsCertificateFlags: appropriate CertificateFlags.
	Verify func(identity SocketConnectabler, trustedCa TLSCertificater) TLSCertificateFlags
}

TLSCertificateOverrides contains methods that are overridable.

type TLSCertificateRequestFlags 

type TLSCertificateRequestFlags C.gint

TLSCertificateRequestFlags flags for g_tls_interaction_request_certificate(), g_tls_interaction_request_certificate_async(), and g_tls_interaction_invoke_request_certificate(). 

const (
	// TLSCertificateRequestNone: no flags.
	TLSCertificateRequestNone TLSCertificateRequestFlags = iota
)

func (TLSCertificateRequestFlags) String 

func (t TLSCertificateRequestFlags) String() string

String returns the name in string for TLSCertificateRequestFlags.

type TLSCertificater 

type TLSCertificater interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

TLSCertificater describes types inherited from class TLSCertificate.

To get the original type, the caller must assert this to an interface or another type.

func TLSCertificateListNewFromFile 

func TLSCertificateListNewFromFile(file string) ([]TLSCertificater, error)

TLSCertificateListNewFromFile creates one or more Certificates from the PEM-encoded data in file. If file cannot be read or parsed, the function will return NULL and set error. If file does not contain any PEM-encoded certificates, this will return an empty list and not set error.

The function takes the following parameters:

  • file containing PEM-encoded certificates to import.

The function returns the following values:

  • list: a #GList containing Certificate objects. You must free the list and its contents when you are done with it.

type TLSChannelBindingError 

type TLSChannelBindingError C.gint

TLSChannelBindingError: error code used with G_TLS_CHANNEL_BINDING_ERROR in a #GError to indicate a TLS channel binding retrieval error. 

const (
	// TLSChannelBindingErrorNotImplemented: either entire binding retrieval
	// facility or specific binding type is not implemented in the TLS backend.
	TLSChannelBindingErrorNotImplemented TLSChannelBindingError = iota
	// TLSChannelBindingErrorInvalidState: handshake is not yet complete on the
	// connection which is a strong requirement for any existing binding type.
	TLSChannelBindingErrorInvalidState
	// TLSChannelBindingErrorNotAvailable: handshake is complete but binding
	// data is not available. That normally indicates the TLS implementation
	// failed to provide the binding data. For example, some implementations do
	// not provide a peer certificate for resumed connections.
	TLSChannelBindingErrorNotAvailable
	// TLSChannelBindingErrorNotSupported: binding type is not supported on
	// the current connection. This error could be triggered when requesting
	// tls-server-end-point binding data for a certificate which has no hash
	// function or uses multiple hash functions.
	TLSChannelBindingErrorNotSupported
	// TLSChannelBindingErrorGeneralError: any other backend error preventing
	// binding data retrieval.
	TLSChannelBindingErrorGeneralError
)

func (TLSChannelBindingError) String 

func (t TLSChannelBindingError) String() string

String returns the name in string for TLSChannelBindingError.

type TLSChannelBindingType 

type TLSChannelBindingType C.gint

TLSChannelBindingType: type of TLS channel binding data to retrieve from Connection or Connection, as documented by RFC 5929 or RFC 9266. The tls-unique-for-telnet (https://tools.ietf.org/html/rfc5929#section-5) binding type is not currently implemented. 

const (
	// TLSChannelBindingTLSUnique: tls-unique
	// (https://tools.ietf.org/html/rfc5929#section-3) binding type.
	TLSChannelBindingTLSUnique TLSChannelBindingType = iota
	// TLSChannelBindingTLSServerEndPoint: tls-server-end-point
	// (https://tools.ietf.org/html/rfc5929#section-4) binding type.
	TLSChannelBindingTLSServerEndPoint
	// TLSChannelBindingTLSExporter: tls-exporter
	// (https://www.rfc-editor.org/rfc/rfc9266.html) binding type. Since: 2.74.
	TLSChannelBindingTLSExporter
)

func (TLSChannelBindingType) String 

func (t TLSChannelBindingType) String() string

String returns the name in string for TLSChannelBindingType.

type TLSClientConnection 

type TLSClientConnection struct {
	TLSConnection
	// contains filtered or unexported fields
}

TLSClientConnection: GTlsClientConnection is the client-side subclass of gio.TLSConnection, representing a client-side TLS connection.

TLSClientConnection wraps an interface. This means the user can get the underlying type by calling Cast().

func NewTLSClientConnection 

func NewTLSClientConnection(baseIoStream IOStreamer, serverIdentity SocketConnectabler) (*TLSClientConnection, error)

NewTLSClientConnection creates a new ClientConnection wrapping base_io_stream (which must have pollable input and output streams) which is assumed to communicate with the server identified by server_identity.

See the documentation for Connection:base-io-stream for restrictions on when application code can run operations on the base_io_stream after this function has returned.

The function takes the following parameters:

  • baseIoStream to wrap.
  • serverIdentity (optional): expected identity of the server.

The function returns the following values:

  • tlsClientConnection: new ClientConnection, or NULL on error.

func (*TLSClientConnection) CopySessionState 

func (conn *TLSClientConnection) CopySessionState(source TLSClientConnectioner)

CopySessionState: possibly copies session state from one connection to another, for use in TLS session resumption. This is not normally needed, but may be used when the same session needs to be used between different endpoints, as is required by some protocols, such as FTP over TLS. source should have already completed a handshake and, since TLS 1.3, it should have been used to read data at least once. conn should not have completed a handshake.

It is not possible to know whether a call to this function will actually do anything. Because session resumption is normally used only for performance benefit, the TLS backend might not implement this function. Even if implemented, it may not actually succeed in allowing conn to resume source's TLS session, because the server may not have sent a session resumption token to source, or it may refuse to accept the token from conn. There is no way to know whether a call to this function is actually successful.

Using this function is not required to benefit from session resumption. If the TLS backend supports session resumption, the session will be resumed automatically if it is possible to do so without weakening the privacy guarantees normally provided by TLS, without need to call this function. For example, with TLS 1.3, a session ticket will be automatically copied from any ClientConnection that has previously received session tickets from the server, provided a ticket is available that has not previously been used for session resumption, since session ticket reuse would be a privacy weakness. Using this function causes the ticket to be copied without regard for privacy considerations.

The function takes the following parameters:

  • source: ClientConnection.

func (*TLSClientConnection) ServerIdentity 

func (conn *TLSClientConnection) ServerIdentity() *SocketConnectable

ServerIdentity gets conn's expected server identity.

The function returns the following values:

  • socketConnectable (optional) describing the expected server identity, or NULL if the expected identity is not known.

func (*TLSClientConnection) SetServerIdentity 

func (conn *TLSClientConnection) SetServerIdentity(identity SocketConnectabler)

SetServerIdentity sets conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let conn know what name to look for in the certificate when performing G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.

The function takes the following parameters:

  • identity describing the expected server identity.

func (*TLSClientConnection) SetUseSSL3 deprecated 

func (conn *TLSClientConnection) SetUseSSL3(useSsl3 bool)

SetUseSSL3: since GLib 2.42.1, SSL 3.0 is no longer supported.

From GLib 2.42.1 through GLib 2.62, this function could be used to force use of TLS 1.0, the lowest-supported TLS protocol version at the time. In the past, this was needed to connect to broken TLS servers that exhibited protocol version intolerance. Such servers are no longer common, and using TLS 1.0 is no longer considered acceptable.

Since GLib 2.64, this function does nothing.

Deprecated: SSL 3.0 is insecure.

The function takes the following parameters:

  • useSsl3: #gboolean, ignored.

func (*TLSClientConnection) SetValidationFlags deprecated 

func (conn *TLSClientConnection) SetValidationFlags(flags TLSCertificateFlags)

SetValidationFlags sets conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, G_TLS_CERTIFICATE_VALIDATE_ALL is used.

This function does not work as originally designed and is impossible to use correctly. See ClientConnection:validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function takes the following parameters:

  • flags to use.

func (*TLSClientConnection) UseSSL3 deprecated 

func (conn *TLSClientConnection) UseSSL3() bool

UseSSL3: SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details.

Deprecated: SSL 3.0 is insecure.

The function returns the following values:

  • ok: FALSE.

func (*TLSClientConnection) ValidationFlags deprecated 

func (conn *TLSClientConnection) ValidationFlags() TLSCertificateFlags

ValidationFlags gets conn's validation flags

This function does not work as originally designed and is impossible to use correctly. See ClientConnection:validation-flags for more information.

Deprecated: Do not attempt to ignore validation errors.

The function returns the following values:

  • tlsCertificateFlags: validation flags.

type TLSClientConnectionInterface added in v0.0.5 

type TLSClientConnectionInterface struct {
	// contains filtered or unexported fields
}

TLSClientConnectionInterface: vtable for a ClientConnection implementation.

An instance of this type is always passed by reference.

type TLSClientConnectioner 

type TLSClientConnectioner interface {
	coreglib.Objector

	// CopySessionState: possibly copies session state from one connection to
	// another, for use in TLS session resumption.
	CopySessionState(source TLSClientConnectioner)
	// ServerIdentity gets conn's expected server identity.
	ServerIdentity() *SocketConnectable
	// UseSSL3: SSL 3.0 is no longer supported.
	UseSSL3() bool
	// ValidationFlags gets conn's validation flags.
	ValidationFlags() TLSCertificateFlags
	// SetServerIdentity sets conn's expected server identity, which is used
	// both to tell servers on virtual hosts which certificate to present,
	// and also to let conn know what name to look for in the certificate when
	// performing G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled.
	SetServerIdentity(identity SocketConnectabler)
	// SetUseSSL3: since GLib 2.42.1, SSL 3.0 is no longer supported.
	SetUseSSL3(useSsl3 bool)
	// SetValidationFlags sets conn's validation flags, to override the default
	// set of checks performed when validating a server certificate.
	SetValidationFlags(flags TLSCertificateFlags)
}

TLSClientConnectioner describes TLSClientConnection's interface methods.

type TLSConnection 

type TLSConnection struct {
	IOStream
	// contains filtered or unexported fields
}

TLSConnection: GTlsConnection is the base TLS connection class type, which wraps a gio.IOStream and provides TLS encryption on top of it. Its subclasses, gio.TLSClientConnection and gio.TLSServerConnection, implement client-side and server-side TLS, respectively.

For DTLS (Datagram TLS) support, see gio.DTLSConnection.

func BaseTLSConnection 

func BaseTLSConnection(obj TLSConnectioner) *TLSConnection

BaseTLSConnection returns the underlying base object.

func (*TLSConnection) Certificate 

func (conn *TLSConnection) Certificate() TLSCertificater

Certificate gets conn's certificate, as set by g_tls_connection_set_certificate().

The function returns the following values:

  • tlsCertificate (optional) conn's certificate, or NULL.

func (*TLSConnection) ChannelBindingData 

func (conn *TLSConnection) ChannelBindingData(typ TLSChannelBindingType) ([]byte, error)

ChannelBindingData: query the TLS backend for TLS channel binding data of type for conn.

This call retrieves TLS channel binding data as specified in RFC 5056 (https://tools.ietf.org/html/rfc5056), RFC 5929 (https://tools.ietf.org/html/rfc5929), and related RFCs. The binding data is returned in data. The data is resized by the callee using Array buffer management and will be freed when the data is destroyed by g_byte_array_unref(). If data is NULL, it will only check whether TLS backend is able to fetch the data (e.g. whether type is supported by the TLS backend). It does not guarantee that the data will be available though. That could happen if TLS connection does not support type or the binding data is not available yet due to additional negotiation or input required.

The function takes the following parameters:

  • typ type of data to fetch.

The function returns the following values:

  • data (optional) is filled with the binding data, or NULL.

func (*TLSConnection) CiphersuiteName added in v0.3.0 

func (conn *TLSConnection) CiphersuiteName() string

CiphersuiteName returns the name of the current TLS ciphersuite, or NULL if the connection has not handshaked or has been closed. Beware that the TLS backend may use any of multiple different naming conventions, because OpenSSL and GnuTLS have their own ciphersuite naming conventions that are different from each other and different from the standard, IANA- registered ciphersuite names. The ciphersuite name is intended to be displayed to the user for informative purposes only, and parsing it is not recommended.

The function returns the following values:

  • utf8 (optional): name of the current TLS ciphersuite, or NULL.

func (*TLSConnection) ConnectAcceptCertificate 

func (conn *TLSConnection) ConnectAcceptCertificate(f func(peerCert TLSCertificater, errors TLSCertificateFlags) (ok bool)) coreglib.SignalHandle

ConnectAcceptCertificate is emitted during the TLS handshake after the peer certificate has been received. You can examine peer_cert's certification path by calling g_tls_certificate_get_issuer() on it.

For a client-side connection, peer_cert is the server's certificate, and the signal will only be emitted if the certificate was not acceptable according to conn's ClientConnection:validation_flags. If you would like the certificate to be accepted despite errors, return TRUE from the signal handler. Otherwise, if no handler accepts the certificate, the handshake will fail with G_TLS_ERROR_BAD_CERTIFICATE.

GLib guarantees that if certificate verification fails, this signal will be emitted with at least one error will be set in errors, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to ignore G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate.

For a server-side connection, peer_cert is the certificate presented by the client, if this was requested via the server's ServerConnection:authentication_mode. On the server side, the signal is always emitted when the client presents a certificate, and the certificate will only be accepted if a handler returns TRUE.

Note that if this signal is emitted as part of asynchronous I/O in the main thread, then you should not attempt to interact with the user before returning from the signal handler. If you want to let the user decide whether or not to accept the certificate, you would have to return FALSE from the signal handler on the first attempt, and then after the connection attempt returns a G_TLS_ERROR_BAD_CERTIFICATE, you can interact with the user, and if the user decides to accept the certificate, remember that fact, create a new connection, and return TRUE from the signal handler the next time.

If you are doing I/O in another thread, you do not need to worry about this, and can simply block in the signal handler until the UI thread returns an answer.

func (*TLSConnection) Database 

func (conn *TLSConnection) Database() TLSDatabaser

Database gets the certificate database that conn uses to verify peer certificates. See g_tls_connection_set_database().

The function returns the following values:

  • tlsDatabase (optional): certificate database that conn uses or NULL.

func (*TLSConnection) EmitAcceptCertificate 

func (conn *TLSConnection) EmitAcceptCertificate(peerCert TLSCertificater, errors TLSCertificateFlags) bool

EmitAcceptCertificate: used by Connection implementations to emit the Connection::accept-certificate signal.

The function takes the following parameters:

  • peerCert peer's Certificate.
  • errors problems with peer_cert.

The function returns the following values:

  • ok: TRUE if one of the signal handlers has returned TRUE to accept peer_cert.

func (*TLSConnection) Handshake 

func (conn *TLSConnection) Handshake(ctx context.Context) error

Handshake attempts a TLS handshake on conn.

On the client side, it is never necessary to call this method; although the connection needs to perform a handshake after connecting (or after sending a "STARTTLS"-type command), Connection will handle this for you automatically when you try to send or receive data on the connection. You can call g_tls_connection_handshake() manually if you want to know whether the initial handshake succeeded or failed (as opposed to just immediately trying to use conn to read or write, in which case, if it fails, it may not be possible to tell if it failed before or after completing the handshake), but beware that servers may reject client authentication after the handshake has completed, so a successful handshake does not indicate the connection will be usable.

Likewise, on the server side, although a handshake is necessary at the beginning of the communication, you do not need to call this function explicitly unless you want clearer error reporting.

Previously, calling g_tls_connection_handshake() after the initial handshake would trigger a rehandshake; however, this usage was deprecated in GLib 2.60 because rehandshaking was removed from the TLS protocol in TLS 1.3. Since GLib 2.64, calling this function after the initial handshake will no longer do anything.

When using a Connection created by Client, the Client performs the initial handshake, so calling this function manually is not recommended.

Connection::accept_certificate may be emitted during the handshake.

The function takes the following parameters:

  • ctx (optional) or NULL.

func (*TLSConnection) HandshakeAsync 

func (conn *TLSConnection) HandshakeAsync(ctx context.Context, ioPriority int, callback AsyncReadyCallback)

HandshakeAsync: asynchronously performs a TLS handshake on conn. See g_tls_connection_handshake() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • ioPriority: [I/O priority][io-priority] of the request.
  • callback (optional) to call when the handshake is complete.

func (*TLSConnection) HandshakeFinish 

func (conn *TLSConnection) HandshakeFinish(result AsyncResulter) error

HandshakeFinish: finish an asynchronous TLS handshake operation. See g_tls_connection_handshake() for more information.

The function takes the following parameters:

  • result: Result.

func (*TLSConnection) Interaction 

func (conn *TLSConnection) Interaction() *TLSInteraction

Interaction: get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If NULL is returned, then no user interaction will occur for this connection.

The function returns the following values:

  • tlsInteraction (optional): interaction object.

func (*TLSConnection) NegotiatedProtocol 

func (conn *TLSConnection) NegotiatedProtocol() string

NegotiatedProtocol gets the name of the application-layer protocol negotiated during the handshake.

If the peer did not use the ALPN extension, or did not advertise a protocol that matched one of conn's protocols, or the TLS backend does not support ALPN, then this will be NULL. See g_tls_connection_set_advertised_protocols().

The function returns the following values:

  • utf8 (optional): negotiated protocol, or NULL.

func (*TLSConnection) PeerCertificate 

func (conn *TLSConnection) PeerCertificate() TLSCertificater

PeerCertificate gets conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of Connection::accept-certificate.).

The function returns the following values:

  • tlsCertificate (optional) conn's peer's certificate, or NULL.

func (*TLSConnection) PeerCertificateErrors 

func (conn *TLSConnection) PeerCertificateErrors() TLSCertificateFlags

PeerCertificateErrors gets the errors associated with validating conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of Connection::accept-certificate.)

See Connection:peer-certificate-errors for more information.

The function returns the following values:

  • tlsCertificateFlags conn's peer's certificate errors.

func (*TLSConnection) ProtocolVersion added in v0.3.0 

func (conn *TLSConnection) ProtocolVersion() TLSProtocolVersion

ProtocolVersion returns the current TLS protocol version, which may be G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or has been closed, or if the TLS backend has implemented a protocol version that is not a recognized ProtocolVersion.

The function returns the following values:

  • tlsProtocolVersion: current TLS protocol version.

func (*TLSConnection) RehandshakeMode deprecated 

func (conn *TLSConnection) RehandshakeMode() TLSRehandshakeMode

RehandshakeMode gets conn rehandshaking mode. See g_tls_connection_set_rehandshake_mode() for details.

Deprecated: Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3.

The function returns the following values:

  • tlsRehandshakeMode: G_TLS_REHANDSHAKE_SAFELY.

func (*TLSConnection) RequireCloseNotify 

func (conn *TLSConnection) RequireCloseNotify() bool

RequireCloseNotify tests whether or not conn expects a proper TLS close notification when the connection is closed. See g_tls_connection_set_require_close_notify() for details.

The function returns the following values:

  • ok: TRUE if conn requires a proper TLS close notification.

func (*TLSConnection) SetAdvertisedProtocols 

func (conn *TLSConnection) SetAdvertisedProtocols(protocols []string)

SetAdvertisedProtocols sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be used to negotiate a compatible protocol with the peer; use g_tls_connection_get_negotiated_protocol() to find the negotiated protocol after the handshake. Specifying NULL for the the value of protocols will disable ALPN negotiation.

See IANA TLS ALPN Protocol IDs (https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids) for a list of registered protocol IDs.

The function takes the following parameters:

  • protocols (optional): NULL-terminated array of ALPN protocol names (eg, "http/1.1", "h2"), or NULL.

func (*TLSConnection) SetCertificate 

func (conn *TLSConnection) SetCertificate(certificate TLSCertificater)

SetCertificate: this sets the certificate that conn will present to its peer during the TLS handshake. For a ServerConnection, it is mandatory to set this, and that will normally be done at construct time.

For a ClientConnection, this is optional. If a handshake fails with G_TLS_ERROR_CERTIFICATE_REQUIRED, that means that the server requires a certificate, and if you try connecting again, you should call this method first. You can call g_tls_client_connection_get_accepted_cas() on the failed connection to get a list of Certificate Authorities that the server will accept certificates from.

(It is also possible that a server will allow the connection with or without a certificate; in that case, if you don't provide a certificate, you can tell that the server requested one by the fact that g_tls_client_connection_get_accepted_cas() will return non-NULL.).

The function takes the following parameters:

  • certificate to use for conn.

func (*TLSConnection) SetDatabase 

func (conn *TLSConnection) SetDatabase(database TLSDatabaser)

SetDatabase sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to NULL, then peer certificate validation will always set the G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning Connection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in ClientConnection:validation-flags).

There are nonintuitive security implications when using a non-default database. See Connection:database for details.

The function takes the following parameters:

  • database (optional): Database.

func (*TLSConnection) SetInteraction 

func (conn *TLSConnection) SetInteraction(interaction *TLSInteraction)

SetInteraction: set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords.

The interaction argument will normally be a derived subclass of Interaction. NULL can also be provided if no user interaction should occur for this connection.

The function takes the following parameters:

  • interaction (optional) object, or NULL.

func (*TLSConnection) SetRehandshakeMode deprecated 

func (conn *TLSConnection) SetRehandshakeMode(mode TLSRehandshakeMode)

SetRehandshakeMode: since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and rekey operations.

Deprecated: Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3.

The function takes the following parameters:

  • mode: rehandshaking mode.

func (*TLSConnection) SetRequireCloseNotify 

func (conn *TLSConnection) SetRequireCloseNotify(requireCloseNotify bool)

SetRequireCloseNotify sets whether or not conn expects a proper TLS close notification before the connection is closed. If this is TRUE (the default), then conn will expect to receive a TLS close notification from its peer before the connection is closed, and will return a G_TLS_ERROR_EOF error if the connection is closed without proper notification (since this may indicate a network error, or man-in-the-middle attack).

In some protocols, the application will know whether or not the connection was closed cleanly based on application-level data (because the application-level data includes a length field, or is somehow self-delimiting); in this case, the close notify is redundant and sometimes omitted. (TLS 1.1 explicitly allows this; in TLS 1.0 it is technically an error, but often done anyway.) You can use g_tls_connection_set_require_close_notify() to tell conn to allow an "unannounced" connection close, in which case the close will show up as a 0-length read, as in a non-TLS Connection, and it is up to the application to check that the data has been fully received.

Note that this only affects the behavior when the peer closes the connection; when the application calls g_io_stream_close() itself on conn, this will send a close notification regardless of the setting of this property. If you explicitly want to do an unclean close, you can close conn's Connection:base-io-stream rather than closing conn itself, but note that this may only be done when no other operations are pending on conn or the base I/O stream.

The function takes the following parameters:

  • requireCloseNotify: whether or not to require close notification.

func (*TLSConnection) SetUseSystemCertDB deprecated 

func (conn *TLSConnection) SetUseSystemCertDB(useSystemCertdb bool)

SetUseSystemCertDB sets whether conn uses the system certificate database to verify peer certificates. This is TRUE by default. If set to FALSE, then peer certificate validation will always set the G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning Connection::accept-certificate will always be emitted on client-side connections, unless that bit is not set in ClientConnection:validation-flags).

Deprecated: Use g_tls_connection_set_database() instead.

The function takes the following parameters:

  • useSystemCertdb: whether to use the system certificate database.

func (*TLSConnection) UseSystemCertDB deprecated 

func (conn *TLSConnection) UseSystemCertDB() bool

UseSystemCertDB gets whether conn uses the system certificate database to verify peer certificates. See g_tls_connection_set_use_system_certdb().

Deprecated: Use g_tls_connection_get_database() instead.

The function returns the following values:

  • ok: whether conn uses the system certificate database.

type TLSConnectionClass added in v0.0.5 

type TLSConnectionClass struct {
	// contains filtered or unexported fields
}

TLSConnectionClass class structure for the Connection type.

An instance of this type is always passed by reference.

func (*TLSConnectionClass) ParentClass added in v0.0.5 

func (t *TLSConnectionClass) ParentClass() *IOStreamClass

ParentClass: parent class.

type TLSConnectionOverrides added in v0.0.5 

type TLSConnectionOverrides struct {
	// AcceptCertificate: check whether to accept a certificate.
	//
	// The function takes the following parameters:
	//
	//   - peerCert
	//   - errors
	AcceptCertificate func(peerCert TLSCertificater, errors TLSCertificateFlags) bool
	// BindingData: retrieve TLS channel binding data (Since: 2.66).
	//
	// The function takes the following parameters:
	//
	//   - typ
	//   - data
	BindingData func(typ TLSChannelBindingType, data []byte) error
	// NegotiatedProtocol gets the name of the application-layer protocol
	// negotiated during the handshake.
	//
	// If the peer did not use the ALPN extension, or did not advertise
	// a protocol that matched one of conn's protocols, or the TLS
	// backend does not support ALPN, then this will be NULL. See
	// g_tls_connection_set_advertised_protocols().
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): negotiated protocol, or NULL.
	NegotiatedProtocol func() string
	// Handshake attempts a TLS handshake on conn.
	//
	// On the client side, it is never necessary to call this method; although
	// the connection needs to perform a handshake after connecting (or after
	// sending a "STARTTLS"-type command), Connection will handle this for you
	// automatically when you try to send or receive data on the connection.
	// You can call g_tls_connection_handshake() manually if you want to
	// know whether the initial handshake succeeded or failed (as opposed to
	// just immediately trying to use conn to read or write, in which case,
	// if it fails, it may not be possible to tell if it failed before or
	// after completing the handshake), but beware that servers may reject
	// client authentication after the handshake has completed, so a successful
	// handshake does not indicate the connection will be usable.
	//
	// Likewise, on the server side, although a handshake is necessary at the
	// beginning of the communication, you do not need to call this function
	// explicitly unless you want clearer error reporting.
	//
	// Previously, calling g_tls_connection_handshake() after the initial
	// handshake would trigger a rehandshake; however, this usage was deprecated
	// in GLib 2.60 because rehandshaking was removed from the TLS protocol
	// in TLS 1.3. Since GLib 2.64, calling this function after the initial
	// handshake will no longer do anything.
	//
	// When using a Connection created by Client, the Client performs the
	// initial handshake, so calling this function manually is not recommended.
	//
	// Connection::accept_certificate may be emitted during the handshake.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	Handshake func(ctx context.Context) error
	// HandshakeFinish: finish an asynchronous TLS handshake operation.
	// See g_tls_connection_handshake() for more information.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	HandshakeFinish func(result AsyncResulter) error
}

TLSConnectionOverrides contains methods that are overridable.

type TLSConnectioner 

type TLSConnectioner interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

TLSConnectioner describes types inherited from class TLSConnection.

To get the original type, the caller must assert this to an interface or another type.

type TLSDatabase 

type TLSDatabase struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TLSDatabase: GTlsDatabase is used to look up certificates and other information from a certificate or key store. It is an abstract base class which TLS library specific subtypes override.

A GTlsDatabase may be accessed from multiple threads by the TLS backend. All implementations are required to be fully thread-safe.

Most common client applications will not directly interact with GTlsDatabase. It is used internally by gio.TLSConnection.

func BaseTLSDatabase 

func BaseTLSDatabase(obj TLSDatabaser) *TLSDatabase

BaseTLSDatabase returns the underlying base object.

func (*TLSDatabase) CreateCertificateHandle 

func (self *TLSDatabase) CreateCertificateHandle(certificate TLSCertificater) string

CreateCertificateHandle: create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In cases where the database cannot create a handle for a certificate, NULL will be returned.

This handle should be stable across various instances of the application, and between applications. If a certificate is modified in the database, then it is not guaranteed that this handle will continue to point to it.

The function takes the following parameters:

  • certificate for which to create a handle.

The function returns the following values:

  • utf8 (optional): newly allocated string containing the handle.

func (*TLSDatabase) LookupCertificateForHandle 

func (self *TLSDatabase) LookupCertificateForHandle(ctx context.Context, handle string, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) (TLSCertificater, error)

LookupCertificateForHandle: look up a certificate by its handle.

The handle should have been created by calling g_tls_database_create_certificate_handle() on a Database object of the same TLS backend. The handle is designed to remain valid across instantiations of the database.

If the handle is no longer valid, or does not point to a certificate in this database, then NULL will be returned.

This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform the lookup operation asynchronously.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • handle: certificate handle.
  • interaction (optional): used to interact with the user if necessary.
  • flags flags which affect the lookup.

The function returns the following values:

  • tlsCertificate (optional): newly allocated Certificate, or NULL. Use g_object_unref() to release the certificate.

func (*TLSDatabase) LookupCertificateForHandleAsync 

func (self *TLSDatabase) LookupCertificateForHandleAsync(ctx context.Context, handle string, interaction *TLSInteraction, flags TLSDatabaseLookupFlags, callback AsyncReadyCallback)

LookupCertificateForHandleAsync: asynchronously look up a certificate by its handle in the database. See g_tls_database_lookup_certificate_for_handle() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • handle: certificate handle.
  • interaction (optional): used to interact with the user if necessary.
  • flags flags which affect the lookup.
  • callback (optional) to call when the operation completes.

func (*TLSDatabase) LookupCertificateForHandleFinish 

func (self *TLSDatabase) LookupCertificateForHandleFinish(result AsyncResulter) (TLSCertificater, error)

LookupCertificateForHandleFinish: finish an asynchronous lookup of a certificate by its handle. See g_tls_database_lookup_certificate_for_handle() for more information.

If the handle is no longer valid, or does not point to a certificate in this database, then NULL will be returned.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • tlsCertificate: newly allocated Certificate object. Use g_object_unref() to release the certificate.

func (*TLSDatabase) LookupCertificateIssuer 

func (self *TLSDatabase) LookupCertificateIssuer(ctx context.Context, certificate TLSCertificater, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) (TLSCertificater, error)

LookupCertificateIssuer: look up the issuer of certificate in the database. The Certificate:issuer property of certificate is not modified, and the two certificates are not hooked into a chain.

This function can block. Use g_tls_database_lookup_certificate_issuer_async() to perform the lookup operation asynchronously.

Beware this function cannot be used to build certification paths. The issuer certificate returned by this function may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. RFC 4158 (https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used when verifying a TLS certificate. Accordingly, this function cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • certificate: Certificate.
  • interaction (optional): used to interact with the user if necessary.
  • flags which affect the lookup operation.

The function returns the following values:

  • tlsCertificate: newly allocated issuer Certificate, or NULL. Use g_object_unref() to release the certificate.

func (*TLSDatabase) LookupCertificateIssuerAsync 

func (self *TLSDatabase) LookupCertificateIssuerAsync(ctx context.Context, certificate TLSCertificater, interaction *TLSInteraction, flags TLSDatabaseLookupFlags, callback AsyncReadyCallback)

LookupCertificateIssuerAsync: asynchronously look up the issuer of certificate in the database. See g_tls_database_lookup_certificate_issuer() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • certificate: Certificate.
  • interaction (optional): used to interact with the user if necessary.
  • flags which affect the lookup operation.
  • callback (optional) to call when the operation completes.

func (*TLSDatabase) LookupCertificateIssuerFinish 

func (self *TLSDatabase) LookupCertificateIssuerFinish(result AsyncResulter) (TLSCertificater, error)

LookupCertificateIssuerFinish: finish an asynchronous lookup issuer operation. See g_tls_database_lookup_certificate_issuer() for more information.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • tlsCertificate: newly allocated issuer Certificate, or NULL. Use g_object_unref() to release the certificate.

func (*TLSDatabase) LookupCertificatesIssuedBy 

func (self *TLSDatabase) LookupCertificatesIssuedBy(ctx context.Context, issuerRawDn []byte, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) ([]TLSCertificater, error)

LookupCertificatesIssuedBy: look up certificates issued by this issuer in the database.

This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform the lookup operation asynchronously.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • issuerRawDn which holds the DER encoded issuer DN.
  • interaction (optional): used to interact with the user if necessary.
  • flags flags which affect the lookup operation.

The function returns the following values:

  • list: newly allocated list of Certificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.

func (*TLSDatabase) LookupCertificatesIssuedByAsync 

func (self *TLSDatabase) LookupCertificatesIssuedByAsync(ctx context.Context, issuerRawDn []byte, interaction *TLSInteraction, flags TLSDatabaseLookupFlags, callback AsyncReadyCallback)

LookupCertificatesIssuedByAsync: asynchronously look up certificates issued by this issuer in the database. See g_tls_database_lookup_certificates_issued_by() for more information.

The database may choose to hold a reference to the issuer byte array for the duration of this asynchronous operation. The byte array should not be modified during this time.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • issuerRawDn which holds the DER encoded issuer DN.
  • interaction (optional): used to interact with the user if necessary.
  • flags flags which affect the lookup operation.
  • callback (optional) to call when the operation completes.

func (*TLSDatabase) LookupCertificatesIssuedByFinish 

func (self *TLSDatabase) LookupCertificatesIssuedByFinish(result AsyncResulter) ([]TLSCertificater, error)

LookupCertificatesIssuedByFinish: finish an asynchronous lookup of certificates. See g_tls_database_lookup_certificates_issued_by() for more information.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • list: newly allocated list of Certificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.

func (*TLSDatabase) VerifyChain 

func (self *TLSDatabase) VerifyChain(ctx context.Context, chain TLSCertificater, purpose string, identity SocketConnectabler, interaction *TLSInteraction, flags TLSDatabaseVerifyFlags) (TLSCertificateFlags, error)

VerifyChain determines the validity of a certificate chain, outside the context of a TLS session.

chain is a chain of Certificate objects each pointing to the next certificate in the chain by its Certificate:issuer property.

purpose describes the purpose (or usage) for which the certificate is being used. Typically purpose will be set to G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER which means that the certificate is being used to authenticate a server (and we are acting as the client).

The identity is used to ensure the server certificate is valid for the expected peer identity. If the identity does not match the certificate, G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value. If identity is NULL, that bit will never be set in the return value. The peer identity may also be used to check for pinned certificates (trust exceptions) in the database. These may override the normal verification process on a host-by-host basis.

Currently there are no flags, and G_TLS_DATABASE_VERIFY_NONE should be used.

If chain is found to be valid, then the return value will be 0. If chain is found to be invalid, then the return value will indicate at least one problem found. If the function is unable to determine whether chain is valid (for example, because cancellable is triggered before it completes) then the return value will be G_TLS_CERTIFICATE_GENERIC_ERROR and error will be set accordingly. error is not set when chain is successfully analyzed but found to be invalid.

GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask G_TLS_CERTIFICATE_EXPIRED if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate.

Prior to GLib 2.48, GLib's default TLS backend modified chain to represent the certification path built by Database during certificate verification by adjusting the Certificate:issuer property of each certificate in chain. Since GLib 2.48, this no longer occurs, so you cannot rely on Certificate:issuer to represent the actual certification path used during certificate verification.

Because TLS session context is not used, Database may not perform as many checks on the certificates as Connection would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let Connection handle the verification.

The TLS backend may attempt to look up and add missing certificates to the chain. This may involve HTTP requests to download missing certificates.

This function can block. Use g_tls_database_verify_chain_async() to perform the verification operation asynchronously.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • chain: Certificate chain.
  • purpose that this certificate chain will be used for.
  • identity (optional): expected peer identity.
  • interaction (optional): used to interact with the user if necessary.
  • flags: additional verify flags.

The function returns the following values:

  • tlsCertificateFlags: appropriate CertificateFlags which represents the result of verification.

func (*TLSDatabase) VerifyChainAsync 

func (self *TLSDatabase) VerifyChainAsync(ctx context.Context, chain TLSCertificater, purpose string, identity SocketConnectabler, interaction *TLSInteraction, flags TLSDatabaseVerifyFlags, callback AsyncReadyCallback)

VerifyChainAsync: asynchronously determines the validity of a certificate chain after looking up and adding any missing certificates to the chain. See g_tls_database_verify_chain() for more information.

The function takes the following parameters:

  • ctx (optional) or NULL.
  • chain: Certificate chain.
  • purpose that this certificate chain will be used for.
  • identity (optional): expected peer identity.
  • interaction (optional): used to interact with the user if necessary.
  • flags: additional verify flags.
  • callback (optional) to call when the operation completes.

func (*TLSDatabase) VerifyChainFinish 

func (self *TLSDatabase) VerifyChainFinish(result AsyncResulter) (TLSCertificateFlags, error)

VerifyChainFinish: finish an asynchronous verify chain operation. See g_tls_database_verify_chain() for more information.

If chain is found to be valid, then the return value will be 0. If chain is found to be invalid, then the return value will indicate the problems found. If the function is unable to determine whether chain is valid or not (eg, because cancellable is triggered before it completes) then the return value will be G_TLS_CERTIFICATE_GENERIC_ERROR and error will be set accordingly. error is not set when chain is successfully analyzed but found to be invalid.

The function takes the following parameters:

  • result: Result.

The function returns the following values:

  • tlsCertificateFlags: appropriate CertificateFlags which represents the result of verification.

type TLSDatabaseClass added in v0.0.5 

type TLSDatabaseClass struct {
	// contains filtered or unexported fields
}

TLSDatabaseClass class for Database. Derived classes should implement the various virtual methods. _async and _finish methods have a default implementation that runs the corresponding sync method in a thread.

An instance of this type is always passed by reference.

type TLSDatabaseLookupFlags 

type TLSDatabaseLookupFlags C.gint

TLSDatabaseLookupFlags flags for g_tls_database_lookup_certificate_for_handle(), g_tls_database_lookup_certificate_issuer(), and g_tls_database_lookup_certificates_issued_by(). 

const (
	// TLSDatabaseLookupNone: no lookup flags.
	TLSDatabaseLookupNone TLSDatabaseLookupFlags = iota
	// TLSDatabaseLookupKeypair: restrict lookup to certificates that have a
	// private key.
	TLSDatabaseLookupKeypair
)

func (TLSDatabaseLookupFlags) String 

func (t TLSDatabaseLookupFlags) String() string

String returns the name in string for TLSDatabaseLookupFlags.

type TLSDatabaseOverrides added in v0.0.5 

type TLSDatabaseOverrides struct {
	// CreateCertificateHandle: create a handle string for the certificate.
	// The database will only be able to create a handle for certificates that
	// originate from the database. In cases where the database cannot create a
	// handle for a certificate, NULL will be returned.
	//
	// This handle should be stable across various instances of the application,
	// and between applications. If a certificate is modified in the database,
	// then it is not guaranteed that this handle will continue to point to it.
	//
	// The function takes the following parameters:
	//
	//   - certificate for which to create a handle.
	//
	// The function returns the following values:
	//
	//   - utf8 (optional): newly allocated string containing the handle.
	CreateCertificateHandle func(certificate TLSCertificater) string
	// LookupCertificateForHandle: look up a certificate by its handle.
	//
	// The handle should have been created by calling
	// g_tls_database_create_certificate_handle() on a Database object of
	// the same TLS backend. The handle is designed to remain valid across
	// instantiations of the database.
	//
	// If the handle is no longer valid, or does not point to a certificate in
	// this database, then NULL will be returned.
	//
	// This function can block, use
	// g_tls_database_lookup_certificate_for_handle_async() to perform the
	// lookup operation asynchronously.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - handle: certificate handle.
	//   - interaction (optional): used to interact with the user if necessary.
	//   - flags flags which affect the lookup.
	//
	// The function returns the following values:
	//
	//   - tlsCertificate (optional): newly allocated Certificate, or NULL.
	//     Use g_object_unref() to release the certificate.
	LookupCertificateForHandle func(ctx context.Context, handle string, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) (TLSCertificater, error)
	// LookupCertificateForHandleFinish: finish an
	// asynchronous lookup of a certificate by its handle. See
	// g_tls_database_lookup_certificate_for_handle() for more information.
	//
	// If the handle is no longer valid, or does not point to a certificate in
	// this database, then NULL will be returned.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - tlsCertificate: newly allocated Certificate object. Use
	//     g_object_unref() to release the certificate.
	LookupCertificateForHandleFinish func(result AsyncResulter) (TLSCertificater, error)
	// LookupCertificateIssuer: look up the issuer of certificate in the
	// database. The Certificate:issuer property of certificate is not modified,
	// and the two certificates are not hooked into a chain.
	//
	// This function can block. Use
	// g_tls_database_lookup_certificate_issuer_async() to perform the lookup
	// operation asynchronously.
	//
	// Beware this function cannot be used to build certification paths.
	// The issuer certificate returned by this function may not be the
	// same as the certificate that would actually be used to construct a
	// valid certification path during certificate verification. RFC 4158
	// (https://datatracker.ietf.org/doc/html/rfc4158) explains why an issuer
	// certificate cannot be naively assumed to be part of the the certification
	// path (though GLib's TLS backends may not follow the path building
	// strategies outlined in this RFC). Due to the complexity of certification
	// path building, GLib does not provide any way to know which certification
	// path will actually be used when verifying a TLS certificate. Accordingly,
	// this function cannot be used to make security-related decisions. Only
	// GLib itself should make security decisions about TLS certificates.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - certificate: Certificate.
	//   - interaction (optional): used to interact with the user if necessary.
	//   - flags which affect the lookup operation.
	//
	// The function returns the following values:
	//
	//   - tlsCertificate: newly allocated issuer Certificate, or NULL.
	//     Use g_object_unref() to release the certificate.
	LookupCertificateIssuer func(ctx context.Context, certificate TLSCertificater, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) (TLSCertificater, error)
	// LookupCertificateIssuerFinish: finish an asynchronous lookup issuer
	// operation. See g_tls_database_lookup_certificate_issuer() for more
	// information.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - tlsCertificate: newly allocated issuer Certificate, or NULL.
	//     Use g_object_unref() to release the certificate.
	LookupCertificateIssuerFinish func(result AsyncResulter) (TLSCertificater, error)
	// LookupCertificatesIssuedBy: look up certificates issued by this issuer in
	// the database.
	//
	// This function can block, use
	// g_tls_database_lookup_certificates_issued_by_async() to perform the
	// lookup operation asynchronously.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - issuerRawDn which holds the DER encoded issuer DN.
	//   - interaction (optional): used to interact with the user if necessary.
	//   - flags flags which affect the lookup operation.
	//
	// The function returns the following values:
	//
	//   - list: newly allocated list of Certificate objects. Use
	//     g_object_unref() on each certificate, and g_list_free() on the
	//     release the list.
	LookupCertificatesIssuedBy func(ctx context.Context, issuerRawDn []byte, interaction *TLSInteraction, flags TLSDatabaseLookupFlags) ([]TLSCertificater, error)
	// LookupCertificatesIssuedByFinish: finish an asynchronous lookup of
	// certificates. See g_tls_database_lookup_certificates_issued_by() for more
	// information.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - list: newly allocated list of Certificate objects. Use
	//     g_object_unref() on each certificate, and g_list_free() on the
	//     release the list.
	LookupCertificatesIssuedByFinish func(result AsyncResulter) ([]TLSCertificater, error)
	// VerifyChain determines the validity of a certificate chain, outside the
	// context of a TLS session.
	//
	// chain is a chain of Certificate objects each pointing to the next
	// certificate in the chain by its Certificate:issuer property.
	//
	// purpose describes the purpose (or usage) for which the
	// certificate is being used. Typically purpose will be set to
	// G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER which means that the
	// certificate is being used to authenticate a server (and we are acting as
	// the client).
	//
	// The identity is used to ensure the server certificate is valid for the
	// expected peer identity. If the identity does not match the certificate,
	// G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the return value.
	// If identity is NULL, that bit will never be set in the return value. The
	// peer identity may also be used to check for pinned certificates (trust
	// exceptions) in the database. These may override the normal verification
	// process on a host-by-host basis.
	//
	// Currently there are no flags, and G_TLS_DATABASE_VERIFY_NONE should be
	// used.
	//
	// If chain is found to be valid, then the return value will be 0. If chain
	// is found to be invalid, then the return value will indicate at least one
	// problem found. If the function is unable to determine whether chain is
	// valid (for example, because cancellable is triggered before it completes)
	// then the return value will be G_TLS_CERTIFICATE_GENERIC_ERROR and error
	// will be set accordingly. error is not set when chain is successfully
	// analyzed but found to be invalid.
	//
	// GLib guarantees that if certificate verification fails, at least one
	// error will be set in the return value, but it does not guarantee that
	// all possible errors will be set. Accordingly, you may not safely
	// decide to ignore any particular type of error. For example, it would be
	// incorrect to mask G_TLS_CERTIFICATE_EXPIRED if you want to allow expired
	// certificates, because this could potentially be the only error flag set
	// even if other problems exist with the certificate.
	//
	// Prior to GLib 2.48, GLib's default TLS backend modified chain to
	// represent the certification path built by Database during certificate
	// verification by adjusting the Certificate:issuer property of each
	// certificate in chain. Since GLib 2.48, this no longer occurs, so you
	// cannot rely on Certificate:issuer to represent the actual certification
	// path used during certificate verification.
	//
	// Because TLS session context is not used, Database may not perform
	// as many checks on the certificates as Connection would. For example,
	// certificate constraints may not be honored, and revocation checks may
	// not be performed. The best way to verify TLS certificates used by a TLS
	// connection is to let Connection handle the verification.
	//
	// The TLS backend may attempt to look up and add missing certificates
	// to the chain. This may involve HTTP requests to download missing
	// certificates.
	//
	// This function can block. Use g_tls_database_verify_chain_async() to
	// perform the verification operation asynchronously.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional) or NULL.
	//   - chain: Certificate chain.
	//   - purpose that this certificate chain will be used for.
	//   - identity (optional): expected peer identity.
	//   - interaction (optional): used to interact with the user if necessary.
	//   - flags: additional verify flags.
	//
	// The function returns the following values:
	//
	//   - tlsCertificateFlags: appropriate CertificateFlags which represents
	//     the result of verification.
	VerifyChain func(ctx context.Context, chain TLSCertificater, purpose string, identity SocketConnectabler, interaction *TLSInteraction, flags TLSDatabaseVerifyFlags) (TLSCertificateFlags, error)
	// VerifyChainFinish: finish an asynchronous verify chain operation.
	// See g_tls_database_verify_chain() for more information.
	//
	// If chain is found to be valid, then the return value will be 0. If chain
	// is found to be invalid, then the return value will indicate the problems
	// found. If the function is unable to determine whether chain is valid or
	// not (eg, because cancellable is triggered before it completes) then the
	// return value will be G_TLS_CERTIFICATE_GENERIC_ERROR and error will be
	// set accordingly. error is not set when chain is successfully analyzed but
	// found to be invalid.
	//
	// The function takes the following parameters:
	//
	//   - result: Result.
	//
	// The function returns the following values:
	//
	//   - tlsCertificateFlags: appropriate CertificateFlags which represents
	//     the result of verification.
	VerifyChainFinish func(result AsyncResulter) (TLSCertificateFlags, error)
}

TLSDatabaseOverrides contains methods that are overridable.

type TLSDatabaseVerifyFlags 

type TLSDatabaseVerifyFlags C.guint

TLSDatabaseVerifyFlags flags for g_tls_database_verify_chain(). 

const (
	// TLSDatabaseVerifyNone: no verification flags.
	TLSDatabaseVerifyNone TLSDatabaseVerifyFlags = 0b0
)

func (TLSDatabaseVerifyFlags) Has 

func (t TLSDatabaseVerifyFlags) Has(other TLSDatabaseVerifyFlags) bool

Has returns true if t contains other.

func (TLSDatabaseVerifyFlags) String 

func (t TLSDatabaseVerifyFlags) String() string

String returns the names in string for TLSDatabaseVerifyFlags.

type TLSDatabaser 

type TLSDatabaser interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

TLSDatabaser describes types inherited from class TLSDatabase.

To get the original type, the caller must assert this to an interface or another type.

type TLSError 

type TLSError C.gint

TLSError: error code used with G_TLS_ERROR in a #GError returned from a TLS-related routine. 

const (
	// TLSErrorUnavailable: no TLS provider is available.
	TLSErrorUnavailable TLSError = iota
	// TLSErrorMisc miscellaneous TLS error.
	TLSErrorMisc
	// TLSErrorBadCertificate: certificate presented could not be parsed or
	// failed validation.
	TLSErrorBadCertificate
	// TLSErrorNotTLS: TLS handshake failed because the peer does not seem to be
	// a TLS server.
	TLSErrorNotTLS
	// TLSErrorHandshake: TLS handshake failed because the peer's certificate
	// was not acceptable.
	TLSErrorHandshake
	// TLSErrorCertificateRequired: TLS handshake failed because the server
	// requested a client-side certificate, but none was provided. See
	// g_tls_connection_set_certificate().
	TLSErrorCertificateRequired
	// TLSErrorEOF: TLS connection was closed without proper notice, which may
	// indicate an attack. See g_tls_connection_set_require_close_notify().
	TLSErrorEOF
	// TLSErrorInappropriateFallback: TLS handshake failed because the client
	// sent the fallback SCSV, indicating a protocol downgrade attack. Since:
	// 2.60.
	TLSErrorInappropriateFallback
	// TLSErrorBadCertificatePassword: certificate failed to load because a
	// password was incorrect. Since: 2.72.
	TLSErrorBadCertificatePassword
)

func (TLSError) String 

func (t TLSError) String() string

String returns the name in string for TLSError.

type TLSFileDatabase 

type TLSFileDatabase struct {
	TLSDatabase
	// contains filtered or unexported fields
}

TLSFileDatabase: GTlsFileDatabase is implemented by gio.TLSDatabase objects which load their certificate information from a file. It is an interface which TLS library specific subtypes implement.

TLSFileDatabase wraps an interface. This means the user can get the underlying type by calling Cast().

func BaseTLSFileDatabase 

func BaseTLSFileDatabase(obj TLSFileDatabaser) *TLSFileDatabase

BaseTLSFileDatabase returns the underlying base object.

func NewTLSFileDatabase 

func NewTLSFileDatabase(anchors string) (*TLSFileDatabase, error)

NewTLSFileDatabase creates a new FileDatabase which uses anchor certificate authorities in anchors to verify certificate chains.

The certificates in anchors must be PEM encoded.

The function takes the following parameters:

  • anchors: filename of anchor certificate authorities.

The function returns the following values:

  • tlsFileDatabase: new FileDatabase, or NULL on error.

type TLSFileDatabaseInterface added in v0.0.5 

type TLSFileDatabaseInterface struct {
	// contains filtered or unexported fields
}

TLSFileDatabaseInterface provides an interface for FileDatabase implementations.

An instance of this type is always passed by reference.

type TLSFileDatabaseOverrider 

type TLSFileDatabaseOverrider interface {
}

TLSFileDatabaseOverrider contains methods that are overridable.

type TLSFileDatabaser 

type TLSFileDatabaser interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

TLSFileDatabaser describes TLSFileDatabase's interface methods.

type TLSInteraction 

type TLSInteraction struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TLSInteraction: GTlsInteraction provides a mechanism for the TLS connection and database code to interact with the user. It can be used to ask the user for passwords.

To use a GTlsInteraction with a TLS connection use gio.TLSConnection.SetInteraction().

Callers should instantiate a derived class that implements the various interaction methods to show the required dialogs.

Callers should use the 'invoke' functions like gio.TLSInteraction.InvokeAskPassword() to run interaction methods. These functions make sure that the interaction is invoked in the main loop and not in the current thread, if the current thread is not running the main loop.

Derived classes can choose to implement whichever interactions methods they’d like to support by overriding those virtual methods in their class initialization function. Any interactions not implemented will return G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, it must also implement the corresponding finish method.

func (*TLSInteraction) AskPassword 

func (interaction *TLSInteraction) AskPassword(ctx context.Context, password *TLSPassword) (TLSInteractionResult, error)

AskPassword: run synchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function.

Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The password value will be filled in and then callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • password: Password object.

The function returns the following values:

  • tlsInteractionResult status of the ask password interaction.

func (*TLSInteraction) AskPasswordAsync 

func (interaction *TLSInteraction) AskPasswordAsync(ctx context.Context, password *TLSPassword, callback AsyncReadyCallback)

AskPasswordAsync: run asynchronous interaction to ask the user for a password. In general, g_tls_interaction_invoke_ask_password() should be used instead of this function.

Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The password value will be filled in and then callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation.

Certain implementations may not support immediate cancellation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • password: Password object.
  • callback (optional) will be called when the interaction completes.

func (*TLSInteraction) AskPasswordFinish 

func (interaction *TLSInteraction) AskPasswordFinish(result AsyncResulter) (TLSInteractionResult, error)

AskPasswordFinish: complete an ask password user interaction request. This should be once the g_tls_interaction_ask_password_async() completion callback is called.

If G_TLS_INTERACTION_HANDLED is returned, then the Password passed to g_tls_interaction_ask_password() will have its password filled in.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code.

The function takes the following parameters:

  • result passed to the callback.

The function returns the following values:

  • tlsInteractionResult status of the ask password interaction.

func (*TLSInteraction) InvokeAskPassword 

func (interaction *TLSInteraction) InvokeAskPassword(ctx context.Context, password *TLSPassword) (TLSInteractionResult, error)

InvokeAskPassword: invoke the interaction to ask the user for a password. It invokes this interaction in the main loop, specifically the Context returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by Connection or Database to ask the user for a password.

Derived subclasses usually implement a password prompt, although they may also choose to provide a password from elsewhere. The password value will be filled in and then callback will be called. Alternatively the user may abort this password request, which will usually abort the TLS connection.

The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • password: Password object.

The function returns the following values:

  • tlsInteractionResult status of the ask password interaction.

func (*TLSInteraction) InvokeRequestCertificate 

func (interaction *TLSInteraction) InvokeRequestCertificate(ctx context.Context, connection TLSConnectioner, flags TLSCertificateRequestFlags) (TLSInteractionResult, error)

InvokeRequestCertificate: invoke the interaction to ask the user to choose a certificate to use with the connection. It invokes this interaction in the main loop, specifically the Context returned by g_main_context_get_thread_default() when the interaction is created. This is called by called by Connection when the peer requests a certificate during the handshake.

Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which may or may not abort the TLS connection.

The implementation can either be a synchronous (eg: modal dialog) or an asynchronous one (eg: modeless dialog). This function will take care of calling which ever one correctly.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • connection: Connection object.
  • flags providing more information about the request.

The function returns the following values:

  • tlsInteractionResult status of the certificate request interaction.

func (*TLSInteraction) RequestCertificate 

func (interaction *TLSInteraction) RequestCertificate(ctx context.Context, connection TLSConnectioner, flags TLSCertificateRequestFlags) (TLSInteractionResult, error)

RequestCertificate: run synchronous interaction to ask the user to choose a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function.

Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. Alternatively the user may abort this certificate request, which will usually abort the TLS connection.

If G_TLS_INTERACTION_HANDLED is returned, then the Connection passed to g_tls_interaction_request_certificate() will have had its Connection:certificate filled in.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code. Certain implementations may not support immediate cancellation.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • connection: Connection object.
  • flags providing more information about the request.

The function returns the following values:

  • tlsInteractionResult status of the request certificate interaction.

func (*TLSInteraction) RequestCertificateAsync 

func (interaction *TLSInteraction) RequestCertificateAsync(ctx context.Context, connection TLSConnectioner, flags TLSCertificateRequestFlags, callback AsyncReadyCallback)

RequestCertificateAsync: run asynchronous interaction to ask the user for a certificate to use with the connection. In general, g_tls_interaction_invoke_request_certificate() should be used instead of this function.

Derived subclasses usually implement a certificate selector, although they may also choose to provide a certificate from elsewhere. callback will be called when the operation completes. Alternatively the user may abort this certificate request, which will usually abort the TLS connection.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable cancellation object.
  • connection: Connection object.
  • flags providing more information about the request.
  • callback (optional) will be called when the interaction completes.

func (*TLSInteraction) RequestCertificateFinish 

func (interaction *TLSInteraction) RequestCertificateFinish(result AsyncResulter) (TLSInteractionResult, error)

RequestCertificateFinish: complete a request certificate user interaction request. This should be once the g_tls_interaction_request_certificate_async() completion callback is called.

If G_TLS_INTERACTION_HANDLED is returned, then the Connection passed to g_tls_interaction_request_certificate_async() will have had its Connection:certificate filled in.

If the interaction is cancelled by the cancellation object, or by the user then G_TLS_INTERACTION_FAILED will be returned with an error that contains a G_IO_ERROR_CANCELLED error code.

The function takes the following parameters:

  • result passed to the callback.

The function returns the following values:

  • tlsInteractionResult status of the request certificate interaction.

type TLSInteractionClass added in v0.0.5 

type TLSInteractionClass struct {
	// contains filtered or unexported fields
}

TLSInteractionClass class for Interaction. Derived classes implement the various virtual interaction methods to handle TLS interactions.

Derived classes can choose to implement whichever interactions methods they'd like to support by overriding those virtual methods in their class initialization function. If a derived class implements an async method, it must also implement the corresponding finish method.

The synchronous interaction methods should implement to display modal dialogs, and the asynchronous methods to display modeless dialogs.

If the user cancels an interaction, then the result should be G_TLS_INTERACTION_FAILED and the error should be set with a domain of G_IO_ERROR and code of G_IO_ERROR_CANCELLED.

An instance of this type is always passed by reference.

type TLSInteractionOverrides added in v0.0.5 

type TLSInteractionOverrides struct {
	// AskPassword: run synchronous interaction to ask the user for a password.
	// In general, g_tls_interaction_invoke_ask_password() should be used
	// instead of this function.
	//
	// Derived subclasses usually implement a password prompt, although they may
	// also choose to provide a password from elsewhere. The password value will
	// be filled in and then callback will be called. Alternatively the user may
	// abort this password request, which will usually abort the TLS connection.
	//
	// If the interaction is cancelled by the cancellation object, or by the
	// user then G_TLS_INTERACTION_FAILED will be returned with an error that
	// contains a G_IO_ERROR_CANCELLED error code. Certain implementations may
	// not support immediate cancellation.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable cancellation object.
	//   - password: Password object.
	//
	// The function returns the following values:
	//
	//   - tlsInteractionResult status of the ask password interaction.
	AskPassword func(ctx context.Context, password *TLSPassword) (TLSInteractionResult, error)
	// AskPasswordFinish: complete an ask password user interaction request.
	// This should be once the g_tls_interaction_ask_password_async() completion
	// callback is called.
	//
	// If G_TLS_INTERACTION_HANDLED is returned, then the Password passed to
	// g_tls_interaction_ask_password() will have its password filled in.
	//
	// If the interaction is cancelled by the cancellation object, or by the
	// user then G_TLS_INTERACTION_FAILED will be returned with an error that
	// contains a G_IO_ERROR_CANCELLED error code.
	//
	// The function takes the following parameters:
	//
	//   - result passed to the callback.
	//
	// The function returns the following values:
	//
	//   - tlsInteractionResult status of the ask password interaction.
	AskPasswordFinish func(result AsyncResulter) (TLSInteractionResult, error)
	// RequestCertificate: run synchronous interaction to ask the user
	// to choose a certificate to use with the connection. In general,
	// g_tls_interaction_invoke_request_certificate() should be used instead of
	// this function.
	//
	// Derived subclasses usually implement a certificate selector,
	// although they may also choose to provide a certificate from elsewhere.
	// Alternatively the user may abort this certificate request, which will
	// usually abort the TLS connection.
	//
	// If G_TLS_INTERACTION_HANDLED is returned, then the Connection
	// passed to g_tls_interaction_request_certificate() will have had its
	// Connection:certificate filled in.
	//
	// If the interaction is cancelled by the cancellation object, or by the
	// user then G_TLS_INTERACTION_FAILED will be returned with an error that
	// contains a G_IO_ERROR_CANCELLED error code. Certain implementations may
	// not support immediate cancellation.
	//
	// The function takes the following parameters:
	//
	//   - ctx (optional): optional #GCancellable cancellation object.
	//   - connection: Connection object.
	//   - flags providing more information about the request.
	//
	// The function returns the following values:
	//
	//   - tlsInteractionResult status of the request certificate interaction.
	RequestCertificate func(ctx context.Context, connection TLSConnectioner, flags TLSCertificateRequestFlags) (TLSInteractionResult, error)
	// RequestCertificateFinish: complete a request certificate
	// user interaction request. This should be once the
	// g_tls_interaction_request_certificate_async() completion callback is
	// called.
	//
	// If G_TLS_INTERACTION_HANDLED is returned, then the Connection passed
	// to g_tls_interaction_request_certificate_async() will have had its
	// Connection:certificate filled in.
	//
	// If the interaction is cancelled by the cancellation object, or by the
	// user then G_TLS_INTERACTION_FAILED will be returned with an error that
	// contains a G_IO_ERROR_CANCELLED error code.
	//
	// The function takes the following parameters:
	//
	//   - result passed to the callback.
	//
	// The function returns the following values:
	//
	//   - tlsInteractionResult status of the request certificate interaction.
	RequestCertificateFinish func(result AsyncResulter) (TLSInteractionResult, error)
}

TLSInteractionOverrides contains methods that are overridable.

type TLSInteractionResult 

type TLSInteractionResult C.gint

TLSInteractionResult is returned by various functions in Interaction when finishing an interaction request. 

const (
	// TLSInteractionUnhandled: interaction was unhandled (i.e. not
	// implemented).
	TLSInteractionUnhandled TLSInteractionResult = iota
	// TLSInteractionHandled: interaction completed, and resulting data is
	// available.
	TLSInteractionHandled
	// TLSInteractionFailed: interaction has failed, or was cancelled. and the
	// operation should be aborted.
	TLSInteractionFailed
)

func (TLSInteractionResult) String 

func (t TLSInteractionResult) String() string

String returns the name in string for TLSInteractionResult.

type TLSPassword 

type TLSPassword struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TLSPassword: abstract interface representing a password used in TLS. Often used in user interaction such as unlocking a key storage token.

func NewTLSPassword 

func NewTLSPassword(flags TLSPasswordFlags, description string) *TLSPassword

NewTLSPassword: create a new Password object.

The function takes the following parameters:

  • flags: password flags.
  • description of what the password is for.

The function returns the following values:

  • tlsPassword: newly allocated password object.

func (*TLSPassword) Description 

func (password *TLSPassword) Description() string

Description: get a description string about what the password will be used for.

The function returns the following values:

  • utf8: description of the password.

func (*TLSPassword) Flags 

func (password *TLSPassword) Flags() TLSPasswordFlags

Flags: get flags about the password.

The function returns the following values:

  • tlsPasswordFlags flags about the password.

func (*TLSPassword) SetDescription 

func (password *TLSPassword) SetDescription(description string)

SetDescription: set a description string about what the password will be used for.

The function takes the following parameters:

  • description of the password.

func (*TLSPassword) SetFlags 

func (password *TLSPassword) SetFlags(flags TLSPasswordFlags)

SetFlags: set flags about the password.

The function takes the following parameters:

  • flags about the password.

func (*TLSPassword) SetValue 

func (password *TLSPassword) SetValue(value []byte)

SetValue: set the value for this password. The value will be copied by the password object.

Specify the length, for a non-nul-terminated password. Pass -1 as length if using a nul-terminated password, and length will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.).

The function takes the following parameters:

  • value: new password value.

func (*TLSPassword) SetWarning 

func (password *TLSPassword) SetWarning(warning string)

SetWarning: set a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags().

The function takes the following parameters:

  • warning: user readable warning.

func (*TLSPassword) Value 

func (password *TLSPassword) Value() []byte

Value: get the password value. If length is not NULL then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass NULL for length in contexts where you know the password will have a certain fixed length.).

The function returns the following values:

  • guint8s: password value (owned by the password object).

func (*TLSPassword) Warning 

func (password *TLSPassword) Warning() string

Warning: get a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags().

The function returns the following values:

  • utf8: warning.

type TLSPasswordClass added in v0.0.5 

type TLSPasswordClass struct {
	// contains filtered or unexported fields
}

TLSPasswordClass class structure for Password.

An instance of this type is always passed by reference.

type TLSPasswordFlags 

type TLSPasswordFlags C.guint

TLSPasswordFlags various flags for the password. 

const (
	// TLSPasswordNone: no flags.
	TLSPasswordNone TLSPasswordFlags = 0b0
	// TLSPasswordRetry: password was wrong, and the user should retry.
	TLSPasswordRetry TLSPasswordFlags = 0b10
	// TLSPasswordManyTries: hint to the user that the password has been wrong
	// many times, and the user may not have many chances left.
	TLSPasswordManyTries TLSPasswordFlags = 0b100
	// TLSPasswordFinalTry: hint to the user that this is the last try to get
	// this password right.
	TLSPasswordFinalTry TLSPasswordFlags = 0b1000
	// TLSPasswordPKCS11User: for PKCS #11, the user PIN is required. Since:
	// 2.70.
	TLSPasswordPKCS11User TLSPasswordFlags = 0b10000
	// TLSPasswordPKCS11SecurityOfficer: for PKCS #11, the security officer PIN
	// is required. Since: 2.70.
	TLSPasswordPKCS11SecurityOfficer TLSPasswordFlags = 0b100000
	// TLSPasswordPKCS11ContextSpecific: for PKCS #11, the context-specific PIN
	// is required. Since: 2.70.
	TLSPasswordPKCS11ContextSpecific TLSPasswordFlags = 0b1000000
)

func (TLSPasswordFlags) Has 

func (t TLSPasswordFlags) Has(other TLSPasswordFlags) bool

Has returns true if t contains other.

func (TLSPasswordFlags) String 

func (t TLSPasswordFlags) String() string

String returns the names in string for TLSPasswordFlags.

type TLSPasswordOverrides added in v0.0.5 

type TLSPasswordOverrides struct {
	// DefaultWarning: virtual method for g_tls_password_get_warning() if no
	// value has been set using g_tls_password_set_warning().
	DefaultWarning func() string
	// Value: get the password value. If length is not NULL then it will be
	// filled in with the length of the password value. (Note that the password
	// value is not nul-terminated, so you can only pass NULL for length in
	// contexts where you know the password will have a certain fixed length.).
	//
	// The function returns the following values:
	//
	//   - guint8s: password value (owned by the password object).
	Value func() []byte
}

TLSPasswordOverrides contains methods that are overridable.

type TLSProtocolVersion added in v0.3.0 

type TLSProtocolVersion C.gint

TLSProtocolVersion: TLS or DTLS protocol version used by a Connection or Connection. The integer values of these versions are sequential to ensure newer known protocol versions compare greater than older known versions. Any known DTLS protocol version will compare greater than any SSL or TLS protocol version. The protocol version may be G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer protocol version that GLib does not yet know about. This means that it's possible for an unknown DTLS protocol version to compare less than the TLS protocol versions. 

const (
	// TLSProtocolVersionUnknown: no protocol version or unknown protocol
	// version.
	TLSProtocolVersionUnknown TLSProtocolVersion = 0
	// TLSProtocolVersionSSL30: SSL 3.0, which is insecure and should not be
	// used.
	TLSProtocolVersionSSL30 TLSProtocolVersion = 1
	// TLSProtocolVersionTLS10: TLS 1.0, which is insecure and should not be
	// used.
	TLSProtocolVersionTLS10 TLSProtocolVersion = 2
	// TLSProtocolVersionTLS11: TLS 1.1, which is insecure and should not be
	// used.
	TLSProtocolVersionTLS11 TLSProtocolVersion = 3
	// TLSProtocolVersionTLS12: TLS 1.2, defined by RFC 5246
	// (https://datatracker.ietf.org/doc/html/rfc5246).
	TLSProtocolVersionTLS12 TLSProtocolVersion = 4
	// TLSProtocolVersionTLS13: TLS 1.3, defined by RFC 8446
	// (https://datatracker.ietf.org/doc/html/rfc8446).
	TLSProtocolVersionTLS13 TLSProtocolVersion = 5
	// TLSProtocolVersionDTLS10: DTLS 1.0, which is insecure and should not be
	// used.
	TLSProtocolVersionDTLS10 TLSProtocolVersion = 201
	// TLSProtocolVersionDTLS12: DTLS 1.2, defined by RFC 6347
	// (https://datatracker.ietf.org/doc/html/rfc6347).
	TLSProtocolVersionDTLS12 TLSProtocolVersion = 202
)

func (TLSProtocolVersion) String added in v0.3.0 

func (t TLSProtocolVersion) String() string

String returns the name in string for TLSProtocolVersion.

type TLSRehandshakeMode deprecated 

type TLSRehandshakeMode C.gint

TLSRehandshakeMode: when to allow rehandshaking. See g_tls_connection_set_rehandshake_mode().

Deprecated: Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. 

const (
	// TLSRehandshakeNever: never allow rehandshaking.
	TLSRehandshakeNever TLSRehandshakeMode = iota
	// TLSRehandshakeSafely: allow safe rehandshaking only.
	TLSRehandshakeSafely
	// TLSRehandshakeUnsafely: allow unsafe rehandshaking.
	TLSRehandshakeUnsafely
)

func (TLSRehandshakeMode) String 

func (t TLSRehandshakeMode) String() string

String returns the name in string for TLSRehandshakeMode.

type TLSServerConnection 

type TLSServerConnection struct {
	TLSConnection
	// contains filtered or unexported fields
}

TLSServerConnection: GTlsServerConnection is the server-side subclass of gio.TLSConnection, representing a server-side TLS connection.

TLSServerConnection wraps an interface. This means the user can get the underlying type by calling Cast().

func BaseTLSServerConnection 

func BaseTLSServerConnection(obj TLSServerConnectioner) *TLSServerConnection

BaseTLSServerConnection returns the underlying base object.

func NewTLSServerConnection 

func NewTLSServerConnection(baseIoStream IOStreamer, certificate TLSCertificater) (*TLSServerConnection, error)

NewTLSServerConnection creates a new ServerConnection wrapping base_io_stream (which must have pollable input and output streams).

See the documentation for Connection:base-io-stream for restrictions on when application code can run operations on the base_io_stream after this function has returned.

The function takes the following parameters:

  • baseIoStream to wrap.
  • certificate (optional): default server certificate, or NULL.

The function returns the following values:

  • tlsServerConnection: new ServerConnection, or NULL on error.

type TLSServerConnectionInterface added in v0.0.5 

type TLSServerConnectionInterface struct {
	// contains filtered or unexported fields
}

TLSServerConnectionInterface: vtable for a ServerConnection implementation.

An instance of this type is always passed by reference.

type TLSServerConnectionOverrider 

type TLSServerConnectionOverrider interface {
}

TLSServerConnectionOverrider contains methods that are overridable.

type TLSServerConnectioner 

type TLSServerConnectioner interface {
	coreglib.Objector
	// contains filtered or unexported methods
}

TLSServerConnectioner describes TLSServerConnection's interface methods.

type Task 

type Task struct {
	*coreglib.Object

	AsyncResult
	// contains filtered or unexported fields
}

Task: GTask represents and manages a cancellable ‘task’.

Asynchronous operations

The most common usage of GTask is as a gio.AsyncResult, to manage data during an asynchronous operation. You call gio.Task.New in the ‘start’ method, followed by gio.Task.SetTaskData() 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 as gio.Task.ReturnPointer() or gio.Task.ReturnError(), which will save the value you give it and then invoke the task’s callback function in the thread-default main context (see glib.MainContext.PushThreadDefault()) where it was created (waiting until the next iteration of the main loop first, if necessary). The caller will pass the GTask back to the operation’s finish function (as a gio.AsyncResult), and you can use gio.Task.PropagatePointer() or the like to extract the return value.

Using GTask requires the thread-default glib.MainContext from when the GTask was constructed to be running at least until the task has completed and its data has been freed.

If a GTask has been constructed and its callback set, it is an error to not call g_task_return_*() on it. GLib will warn at runtime if this happens (since 2.76).

Here is an example for using GTask as a gio.AsyncResult: 

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. gio.Task.GetCancellable(), gio.Task.GetContext(), and gio.Task.GetPriority() allow you to get back the task’s gio.Cancellable, glib.MainContext, and I/O priority (iface.AsyncResult.html#io-priority) when starting a new subtask, so you don’t have to keep track of them yourself. gio.Task.AttachSource() simplifies the case of waiting for a source to fire (automatically using the correct glib.MainContext and priority).

Here is an example for chained asynchronous operations: 

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 gio.Task.RunInThread() 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 (see glib.MainContext.PushThreadDefault()) where the GTask was created.

Running a task in a thread: 

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, gio.Task.RunInThread() and gio.Task.RunInThreadSync() can be used to turn an uncancellable operation into a cancellable one. If you call gio.Task.SetReturnOnCancel(), passing TRUE, then if the task’s gio.Cancellable 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: 

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 gio.SimpleAsyncResult

GTask’s API attempts to be simpler than gio.SimpleAsyncResult’s in several ways:

- You can save task-specific data with gio.Task.SetTaskData(), and retrieve it later with gio.Task.GetTaskData(). This replaces the abuse of gio.SimpleAsyncResult.SetOpResGpointer() for the same purpose with gio.SimpleAsyncResult.

- In addition to the task data, GTask also keeps track of the priority (iface.AsyncResult.html#io-priority), gio.Cancellable, and glib.MainContext 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.

- gio.Task.ReturnErrorIfCancelled() provides simplified handling for cancellation. In addition, cancellation overrides any other GTask return value by default, like gio.SimpleAsyncResult does when gio.SimpleAsyncResult.SetCheckCancellable() is called. (You can use gio.Task.SetCheckCancellable() to turn off that behavior.) On the other hand, gio.Task.RunInThread() guarantees that it will always run your task_func, even if the task’s gio.Cancellable is already cancelled before the task gets a chance to run; you can start your task_func with a gio.Task.ReturnErrorIfCancelled() check if you need the old behavior.

- The ‘return’ methods (eg, gio.Task.ReturnPointer()) 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 another glib.MainContext, or delayed until the next iteration of the current glib.MainContext.)

- The ‘finish’ functions for GTask based operations are generally much simpler than gio.SimpleAsyncResult ones, normally consisting of only a single call to gio.Task.PropagatePointer() or the like. Since gio.Task.PropagatePointer() ‘steals’ the return value from the GTask, it is not necessary to juggle pointers around to prevent it from being freed twice.

- With gio.SimpleAsyncResult, it was common to call gio.SimpleAsyncResult.PropagateError() 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 appropriate g_task_propagate_ function. Note that wrapper methods can now use gio.AsyncResult.LegacyPropagateError() to do old-style gio.SimpleAsyncResult error-returning behavior, and gio.AsyncResult.IsTagged() to check if a result is tagged as having come from the _async() wrapper function (for ‘short-circuit’ results, such as when passing 0 to gio.InputStream.ReadAsync()).

Thread-safety considerations

Due to some infelicities in the API design, there is a thread-safety concern that users of GTask have to be aware of:

If the main thread drops its last reference to the source object or the task data before the task is finalized, then the finalizers of these objects may be called on the worker thread.

This is a problem if the finalizers use non-threadsafe API, and can lead to hard-to-debug crashes. Possible workarounds include:

- Clear task data in a signal handler for notify::completed

- Keep iterating a main context in the main thread and defer dropping the reference to the source object to that main context when the task is finalized.

func NewTask 

func NewTask(ctx context.Context, sourceObject *coreglib.Object, callback AsyncReadyCallback) *Task

NewTask creates a #GTask acting on source_object, which will eventually be used to invoke callback in the current [thread-default main context][g-main-context-push-thread-default].

Call this in the "start" method of your asynchronous method, and pass the #GTask around throughout the asynchronous operation. You can use g_task_set_task_data() to attach task-specific data to the object, which you can retrieve later via g_task_get_task_data().

By default, if cancellable is cancelled, then the return value of the task will always be G_IO_ERROR_CANCELLED, even if the task had already completed before the cancellation. This allows for simplified handling in cases where cancellation may imply that other objects that the task depends on have been destroyed. If you do not want this behavior, you can use g_task_set_check_cancellable() to change it.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • sourceObject (optional) that owns this task, or NULL.
  • callback (optional): ReadyCallback.

The function returns the following values:

  • task: #GTask.

func (*Task) Cancellable 

func (task *Task) Cancellable() *Cancellable

Cancellable gets task's #GCancellable.

The function returns the following values:

  • cancellable (optional) task's #GCancellable.

func (*Task) CheckCancellable 

func (task *Task) CheckCancellable() bool

CheckCancellable gets task's check-cancellable flag. See g_task_set_check_cancellable() for more details.

func (*Task) Completed 

func (task *Task) Completed() bool

Completed gets the value of #GTask:completed. This changes from FALSE to TRUE after the task’s callback is invoked, and will return FALSE if called from inside the callback.

The function returns the following values:

  • ok: TRUE if the task has completed, FALSE otherwise.

func (*Task) Context 

func (task *Task) Context() *glib.MainContext

Context gets the Context that task will return its result in (that is, the context that was the [thread-default main context][g-main-context-push-thread-default] at the point when task was created).

This will always return a non-NULL value, even if the task's context is the default Context.

The function returns the following values:

  • mainContext task's Context.

func (*Task) HadError 

func (task *Task) HadError() bool

HadError tests if task resulted in an error.

The function returns the following values:

  • ok: TRUE if the task resulted in an error, FALSE otherwise.

func (*Task) Name 

func (task *Task) Name() string

Name gets task’s name. See g_task_set_name().

The function returns the following values:

  • utf8 (optional) task’s name, or NULL.

func (*Task) Priority 

func (task *Task) Priority() int

Priority gets task's priority.

The function returns the following values:

  • gint task's priority.

func (*Task) PropagateBoolean 

func (task *Task) PropagateBoolean() error

PropagateBoolean gets the result of task as a #gboolean.

If the task resulted in an error, or was cancelled, then this will instead return FALSE and set error.

Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.

func (*Task) PropagateInt 

func (task *Task) PropagateInt() (int, error)

PropagateInt gets the result of task as an integer (#gssize).

If the task resulted in an error, or was cancelled, then this will instead return -1 and set error.

Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.

The function returns the following values:

  • gssize: task result, or -1 on error.

func (*Task) PropagatePointer 

func (task *Task) PropagatePointer() (unsafe.Pointer, error)

PropagatePointer gets the result of task as a pointer, and transfers ownership of that value to the caller.

If the task resulted in an error, or was cancelled, then this will instead return NULL and set error.

Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.

The function returns the following values:

  • gpointer (optional): task result, or NULL on error.

func (*Task) PropagateValue 

func (task *Task) PropagateValue() (coreglib.Value, error)

PropagateValue gets the result of task as a #GValue, and transfers ownership of that value to the caller. As with g_task_return_value(), this is a generic low-level method; g_task_propagate_pointer() and the like will usually be more useful for C code.

If the task resulted in an error, or was cancelled, then this will instead set error and return FALSE.

Since this method transfers ownership of the return value (or error) to the caller, you may only call it once.

The function returns the following values:

  • value: return location for the #GValue.

func (*Task) ReturnBoolean 

func (task *Task) ReturnBoolean(result bool)

ReturnBoolean sets task's result to result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means).

The function takes the following parameters:

  • result result of a task function.

func (*Task) ReturnError 

func (task *Task) ReturnError(err error)

ReturnError sets task's result to error (which task assumes ownership of) and completes the task (see g_task_return_pointer() for more discussion of exactly what this means).

Note that since the task takes ownership of error, and since the task may be completed before returning from g_task_return_error(), you cannot assume that error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well.

See also gio.Task.ReturnNewError(), gio.Task.ReturnNewErrorLiteral().

The function takes the following parameters:

  • err result of a task function.

func (*Task) ReturnErrorIfCancelled 

func (task *Task) ReturnErrorIfCancelled() bool

ReturnErrorIfCancelled checks if task's #GCancellable has been cancelled, and if so, sets task's error accordingly and completes the task (see g_task_return_pointer() for more discussion of exactly what this means).

The function returns the following values:

  • ok: TRUE if task has been cancelled, FALSE if not.

func (*Task) ReturnInt 

func (task *Task) ReturnInt(result int)

ReturnInt sets task's result to result and completes the task (see g_task_return_pointer() for more discussion of exactly what this means).

The function takes the following parameters:

  • result: integer (#gssize) result of a task function.

func (*Task) ReturnNewErrorLiteral added in v0.3.0 

func (task *Task) ReturnNewErrorLiteral(domain glib.Quark, code int, message string)

ReturnNewErrorLiteral sets task’s result to a new glib.Error created from domain, code, message and completes the task.

See gio.Task.ReturnPointer() for more discussion of exactly what ‘completing the task’ means.

See also gio.Task.ReturnNewError().

The function takes the following parameters:

  • domain: #GQuark.
  • code: error code.
  • message: error message.

func (*Task) ReturnOnCancel 

func (task *Task) ReturnOnCancel() bool

ReturnOnCancel gets task's return-on-cancel flag. See g_task_set_return_on_cancel() for more details.

func (*Task) ReturnValue 

func (task *Task) ReturnValue(result *coreglib.Value)

ReturnValue sets task's result to result (by copying it) and completes the task.

If result is NULL then a #GValue of type G_TYPE_POINTER with a value of NULL will be used for the result.

This is a very generic low-level method intended primarily for use by language bindings; for C code, g_task_return_pointer() and the like will normally be much easier to use.

The function takes the following parameters:

  • result (optional) result of a task function.

func (*Task) SetCheckCancellable 

func (task *Task) SetCheckCancellable(checkCancellable bool)

SetCheckCancellable sets or clears task's check-cancellable flag. If this is TRUE (the default), then g_task_propagate_pointer(), etc, and g_task_had_error() will check the task's #GCancellable first, and if it has been cancelled, then they will consider the task to have returned an "Operation was cancelled" error (G_IO_ERROR_CANCELLED), regardless of any other error or return value the task may have had.

If check_cancellable is FALSE, then the #GTask will not check the cancellable itself, and it is up to task's owner to do this (eg, via g_task_return_error_if_cancelled()).

If you are using g_task_set_return_on_cancel() as well, then you must leave check-cancellable set TRUE.

The function takes the following parameters:

  • checkCancellable: whether #GTask will check the state of its #GCancellable for you.

func (*Task) SetName 

func (task *Task) SetName(name string)

SetName sets task’s name, used in debugging and profiling. The name defaults to NULL.

The task name should describe in a human readable way what the task does. For example, ‘Open file’ or ‘Connect to network host’. It is used to set the name of the #GSource used for idle completion of the task.

This function may only be called before the task is first used in a thread other than the one it was constructed in. It is called automatically by g_task_set_source_tag() if not called already.

The function takes the following parameters:

  • name (optional): human readable name for the task, or NULL to unset it.

func (*Task) SetPriority 

func (task *Task) SetPriority(priority int)

SetPriority sets task's priority. If you do not call this, it will default to G_PRIORITY_DEFAULT.

This will affect the priority of #GSources created with g_task_attach_source() and the scheduling of tasks run in threads, and can also be explicitly retrieved later via g_task_get_priority().

The function takes the following parameters:

  • priority: priority (iface.AsyncResult.html#io-priority) of the request.

func (*Task) SetReturnOnCancel 

func (task *Task) SetReturnOnCancel(returnOnCancel bool) bool

SetReturnOnCancel sets or clears task's return-on-cancel flag. This is only meaningful for tasks run via g_task_run_in_thread() or g_task_run_in_thread_sync().

If return_on_cancel is TRUE, then cancelling task's #GCancellable will immediately cause it to return, as though the task's ThreadFunc had called g_task_return_error_if_cancelled() and then returned.

This allows you to create a cancellable wrapper around an uninterruptible function. The ThreadFunc just needs to be careful that it does not modify any externally-visible state after it has been cancelled. To do that, the thread should call g_task_set_return_on_cancel() again to (atomically) set return-on-cancel FALSE before making externally-visible changes; if the task gets cancelled before the return-on-cancel flag could be changed, g_task_set_return_on_cancel() will indicate this by returning FALSE.

You can disable and re-enable this flag multiple times if you wish. If the task's #GCancellable is cancelled while return-on-cancel is FALSE, then calling g_task_set_return_on_cancel() to set it TRUE again will cause the task to be cancelled at that point.

If the task's #GCancellable is already cancelled before you call g_task_run_in_thread()/g_task_run_in_thread_sync(), then the ThreadFunc will still be run (for consistency), but the task will also be completed right away.

The function takes the following parameters:

  • returnOnCancel: whether the task returns automatically when it is cancelled.

The function returns the following values:

  • ok: TRUE if task's return-on-cancel flag was changed to match return_on_cancel. FALSE if task has already been cancelled.

func (*Task) SetSourceTag 

func (task *Task) SetSourceTag(sourceTag unsafe.Pointer)

SetSourceTag sets task's source tag.

You can use this to tag a task return value with a particular pointer (usually a pointer to the function doing the tagging) and then later check it using g_task_get_source_tag() (or g_async_result_is_tagged()) in the task's "finish" function, to figure out if the response came from a particular place.

A macro wrapper around this function will automatically set the task’s name to the string form of source_tag if it’s not already set, for convenience.

The function takes the following parameters:

  • sourceTag (optional): opaque pointer indicating the source of this task.

func (*Task) SetStaticName added in v0.3.0 

func (task *Task) SetStaticName(name string)

SetStaticName sets task’s name, used in debugging and profiling.

This is a variant of g_task_set_name() that avoids copying name.

The function takes the following parameters:

  • name (optional): human readable name for the task. Must be a string literal.

func (*Task) SourceObject 

func (task *Task) SourceObject() *coreglib.Object

SourceObject gets the source object from task. Like g_async_result_get_source_object(), but does not ref the object.

The function returns the following values:

  • object (optional) task's source object, or NULL.

func (*Task) SourceTag 

func (task *Task) SourceTag() unsafe.Pointer

SourceTag gets task's source tag. See g_task_set_source_tag().

The function returns the following values:

  • gpointer (optional) task's source tag.

func (*Task) TaskData 

func (task *Task) TaskData() unsafe.Pointer

TaskData gets task's task_data.

The function returns the following values:

  • gpointer (optional) task's task_data.

type TestDBus 

type TestDBus struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

TestDBus: helper class for testing code which uses D-Bus without touching the user’s session bus.

Note that GTestDBus modifies the user’s environment, calling setenv() (man:setenv(3)). This is not thread-safe, so all GTestDBus calls should be completed before threads are spawned, or should have appropriate locking to ensure no access conflicts to environment variables shared between GTestDBus and other threads.

Creating unit tests using GTestDBus

Testing of D-Bus services can be tricky because normally we only ever run D-Bus services over an existing instance of the D-Bus daemon thus we usually don’t activate D-Bus services that are not yet installed into the target system. The GTestDBus object makes this easier for us by taking care of the lower level tasks such as running a private D-Bus daemon and looking up uninstalled services in customizable locations, typically in your source code tree.

The first thing you will need is a separate service description file for the D-Bus daemon. Typically a services subdirectory of your tests directory is a good place to put this file.

The service file should list your service along with an absolute path to the uninstalled service executable in your source tree. Using autotools we would achieve this by adding a file such as my-server.service.in in the services directory and have it processed by configure. 

[D-BUS Service]
Name=org.gtk.GDBus.Examples.ObjectManager
Exec=abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server

You will also need to indicate this service directory in your test fixtures, so you will need to pass the path while compiling your test cases. Typically this is done with autotools with an added preprocessor flag specified to compile your tests such as: 

-DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"

Once you have a service definition file which is local to your source tree, you can proceed to set up a GTest fixture using the GTestDBus scaffolding.

An example of a test fixture for D-Bus services can be found here: gdbus-test-fixture.c (https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)

Note that these examples only deal with isolating the D-Bus aspect of your service. To successfully run isolated unit tests on your service you may need some additional modifications to your test case fixture. For example; if your service uses gio.Settings and installs a schema then it is important that your test service not load the schema in the ordinary installed location (chances are that your service and schema files are not yet installed, or worse; there is an older version of the schema file sitting in the install location).

Most of the time we can work around these obstacles using the environment. Since the environment is inherited by the D-Bus daemon created by GTestDBus and then in turn inherited by any services the D-Bus daemon activates, using the setup routine for your fixture is a practical place to help sandbox your runtime environment. For the rather typical GSettings case we can work around this by setting GSETTINGS_SCHEMA_DIR to the in tree directory holding your schemas in the above fixture_setup() routine.

The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved by compiling the schemas locally as a step before running test cases, an autotools setup might do the following in the directory holding schemas: 

all-am:
        $(GLIB_COMPILE_SCHEMAS) .

CLEANFILES += gschemas.compiled.

func NewTestDBus 

func NewTestDBus(flags TestDBusFlags) *TestDBus

NewTestDBus: create a new DBus object.

The function takes the following parameters:

  • flags: DBusFlags.

The function returns the following values:

  • testDBus: new DBus.

func (*TestDBus) AddServiceDir 

func (self *TestDBus) AddServiceDir(path string)

AddServiceDir: add a path where dbus-daemon will look up .service files. This can't be called after g_test_dbus_up().

The function takes the following parameters:

  • path to a directory containing .service files.

func (*TestDBus) BusAddress 

func (self *TestDBus) BusAddress() string

BusAddress: get the address on which dbus-daemon is running. If g_test_dbus_up() has not been called yet, NULL is returned. This can be used with g_dbus_connection_new_for_address().

The function returns the following values:

  • utf8 (optional) address of the bus, or NULL.

func (*TestDBus) Down 

func (self *TestDBus) Down()

Down: stop the session bus started by g_test_dbus_up().

This will wait for the singleton returned by g_bus_get() or g_bus_get_sync() to be destroyed. This is done to ensure that the next unit test won't get a leaked singleton from this test.

func (*TestDBus) Flags 

func (self *TestDBus) Flags() TestDBusFlags

Flags: get the flags of the DBus object.

The function returns the following values:

  • testDBusFlags: value of DBus:flags property.

func (*TestDBus) Stop 

func (self *TestDBus) Stop()

Stop the session bus started by g_test_dbus_up().

Unlike g_test_dbus_down(), this won't verify the BusConnection singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit tests wanting to verify behaviour after the session bus has been stopped can use this function but should still call g_test_dbus_down() when done.

func (*TestDBus) Up 

func (self *TestDBus) Up()

Up: start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this call, it is safe for unit tests to start sending messages on the session bus.

If this function is called from setup callback of g_test_add(), g_test_dbus_down() must be called in its teardown callback.

If this function is called from unit test's main(), then g_test_dbus_down() must be called after g_test_run().

type TestDBusFlags 

type TestDBusFlags C.guint

TestDBusFlags flags to define future DBus behaviour. 

const (
	// TestDBusNone: no flags.
	TestDBusNone TestDBusFlags = 0b0
)

func (TestDBusFlags) Has 

func (t TestDBusFlags) Has(other TestDBusFlags) bool

Has returns true if t contains other.

func (TestDBusFlags) String 

func (t TestDBusFlags) String() string

String returns the names in string for TestDBusFlags.

type ThemedIcon 

type ThemedIcon struct {
	*coreglib.Object

	Icon
	// contains filtered or unexported fields
}

ThemedIcon: GThemedIcon is an implementation of gio.Icon that supports icon themes.

GThemedIcon contains a list of all of the icons present in an icon theme, so that icons can be looked up quickly. GThemedIcon does not provide actual pixmaps for icons, just the icon names. Ideally something like gtk.IconTheme.ChooseIcon() should be used to resolve the list of names so that fallback icons work nicely with themes that inherit other themes.

func NewThemedIcon 

func NewThemedIcon(iconname string) *ThemedIcon

NewThemedIcon creates a new themed icon for iconname.

The function takes the following parameters:

  • iconname: string containing an icon name.

The function returns the following values:

  • themedIcon: new Icon.

func NewThemedIconFromNames 

func NewThemedIconFromNames(iconnames []string) *ThemedIcon

NewThemedIconFromNames creates a new themed icon for iconnames.

The function takes the following parameters:

  • iconnames: array of strings containing icon names.

The function returns the following values:

  • themedIcon: new Icon.

func NewThemedIconWithDefaultFallbacks 

func NewThemedIconWithDefaultFallbacks(iconname string) *ThemedIcon

NewThemedIconWithDefaultFallbacks creates a new themed icon for iconname, and all the names that can be created by shortening iconname at '-' characters.

In the following example, icon1 and icon2 are equivalent: 

const char *names[] = {
  "gnome-dev-cdrom-audio",
  "gnome-dev-cdrom",
  "gnome-dev",
  "gnome"
};

icon1 = g_themed_icon_new_from_names (names, 4);
icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio");.

The function takes the following parameters:

  • iconname: string containing an icon name.

The function returns the following values:

  • themedIcon: new Icon.

func (*ThemedIcon) AppendName 

func (icon *ThemedIcon) AppendName(iconname string)

AppendName: append a name to the list of icons from within icon.

Note that doing so invalidates the hash computed by prior calls to g_icon_hash().

The function takes the following parameters:

  • iconname: name of icon to append to list of icons from within icon.

func (*ThemedIcon) Names 

func (icon *ThemedIcon) Names() []string

Names gets the names of icons from within icon.

The function returns the following values:

  • utf8s: list of icon names.

func (*ThemedIcon) PrependName 

func (icon *ThemedIcon) PrependName(iconname string)

PrependName: prepend a name to the list of icons from within icon.

Note that doing so invalidates the hash computed by prior calls to g_icon_hash().

The function takes the following parameters:

  • iconname: name of icon to prepend to list of icons from within icon.

type ThreadedResolver added in v0.3.0 

type ThreadedResolver struct {
	Resolver
	// contains filtered or unexported fields
}

ThreadedResolver is an implementation of #GResolver which calls the libc lookup functions in threads to allow them to run asynchronously.

type ThreadedSocketService 

type ThreadedSocketService struct {
	SocketService
	// contains filtered or unexported fields
}

ThreadedSocketService: GThreadedSocketService is a simple subclass of gio.SocketService that handles incoming connections by creating a worker thread and dispatching the connection to it by emitting the gio.ThreadedSocketService::run signal in the new thread.

The signal handler may perform blocking I/O and need not return until the connection is closed.

The service is implemented using a thread pool, so there is a limited amount of threads available to serve incoming requests. The service automatically stops the gio.SocketService from accepting new connections when all threads are busy.

As with gio.SocketService, you may connect to gio.ThreadedSocketService::run, or subclass and override the default handler.

func NewThreadedSocketService 

func NewThreadedSocketService(maxThreads int) *ThreadedSocketService

NewThreadedSocketService creates a new SocketService with no listeners. Listeners must be added with one of the Listener "add" methods.

The function takes the following parameters:

  • maxThreads: maximal number of threads to execute concurrently handling incoming clients, -1 means no limit.

The function returns the following values:

  • threadedSocketService: new Service.

func (*ThreadedSocketService) ConnectRun 

func (v *ThreadedSocketService) ConnectRun(f func(connection *SocketConnection, sourceObject *coreglib.Object) (ok bool)) coreglib.SignalHandle

ConnectRun signal is emitted in a worker thread in response to an incoming connection. This thread is dedicated to handling connection and may perform blocking IO. The signal handler need not return until the connection is closed.

type ThreadedSocketServiceClass added in v0.0.5 

type ThreadedSocketServiceClass struct {
	// contains filtered or unexported fields
}

ThreadedSocketServiceClass: instance of this type is always passed by reference.

func (*ThreadedSocketServiceClass) ParentClass added in v0.0.5 

func (t *ThreadedSocketServiceClass) ParentClass() *SocketServiceClass

type ThreadedSocketServiceOverrides added in v0.0.5 

type ThreadedSocketServiceOverrides struct {
	// The function takes the following parameters:
	//
	//   - connection
	//   - sourceObject
	Run func(connection *SocketConnection, sourceObject *coreglib.Object) bool
}

ThreadedSocketServiceOverrides contains methods that are overridable.

type VFS 

type VFS struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

VFS: entry point for using GIO functionality.

func VFSGetDefault 

func VFSGetDefault() *VFS

VFSGetDefault gets the default #GVfs for the system.

The function returns the following values:

  • vfs which will be the local file system #GVfs if no other implementation is available.

func VFSGetLocal 

func VFSGetLocal() *VFS

VFSGetLocal gets the local #GVfs for the system.

The function returns the following values:

  • vfs: #GVfs.

func (*VFS) FileForPath 

func (vfs *VFS) FileForPath(path string) *File

FileForPath gets a #GFile for path.

The function takes the following parameters:

  • path: string containing a VFS path.

The function returns the following values:

  • file: #GFile. Free the returned object with g_object_unref().

func (*VFS) FileForURI 

func (vfs *VFS) FileForURI(uri string) *File

FileForURI gets a #GFile for uri.

This operation never fails, but the returned object might not support any I/O operation if the URI is malformed or if the URI scheme is not supported.

The function takes the following parameters:

  • uri: string containing a URI.

The function returns the following values:

  • file: #GFile. Free the returned object with g_object_unref().

func (*VFS) IsActive 

func (vfs *VFS) IsActive() bool

IsActive checks if the VFS is active.

The function returns the following values:

  • ok: TRUE if construction of the vfs was successful and it is now active.

func (*VFS) ParseName 

func (vfs *VFS) ParseName(parseName string) *File

ParseName: this operation never fails, but the returned object might not support any I/O operations if the parse_name cannot be parsed by the #GVfs module.

The function takes the following parameters:

  • parseName: string to be parsed by the VFS module.

The function returns the following values:

  • file for the given parse_name. Free the returned object with g_object_unref().

func (*VFS) RegisterURIScheme 

func (vfs *VFS) RegisterURIScheme(scheme string, uriFunc, parseNameFunc VFSFileLookupFunc) bool

RegisterURIScheme registers uri_func and parse_name_func as the #GFile URI and parse name lookup functions for URIs with a scheme matching scheme. Note that scheme is registered only within the running application, as opposed to desktop-wide as it happens with GVfs backends.

When a #GFile is requested with an URI containing scheme (e.g. through g_file_new_for_uri()), uri_func will be called to allow a custom constructor. The implementation of uri_func should not be blocking, and must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().

When g_file_parse_name() is called with a parse name obtained from such file, parse_name_func will be called to allow the #GFile to be created again. In that case, it's responsibility of parse_name_func to make sure the parse name matches what the custom #GFile implementation returned when g_file_get_parse_name() was previously called. The implementation of parse_name_func should not be blocking, and must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().

It's an error to call this function twice with the same scheme. To unregister a custom URI scheme, use g_vfs_unregister_uri_scheme().

The function takes the following parameters:

  • scheme: URI scheme, e.g. "http".
  • uriFunc (optional): FileLookupFunc.
  • parseNameFunc (optional): FileLookupFunc.

The function returns the following values:

  • ok: TRUE if scheme was successfully registered, or FALSE if a handler for scheme already exists.

func (*VFS) SupportedURISchemes 

func (vfs *VFS) SupportedURISchemes() []string

SupportedURISchemes gets a list of URI schemes supported by vfs.

The function returns the following values:

  • utf8s: NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified.

func (*VFS) UnregisterURIScheme 

func (vfs *VFS) UnregisterURIScheme(scheme string) bool

UnregisterURIScheme unregisters the URI handler for scheme previously registered with g_vfs_register_uri_scheme().

The function takes the following parameters:

  • scheme: URI scheme, e.g. "http".

The function returns the following values:

  • ok: TRUE if scheme was successfully unregistered, or FALSE if a handler for scheme does not exist.

type VFSClass added in v0.0.5 

type VFSClass struct {
	// contains filtered or unexported fields
}

VFSClass: instance of this type is always passed by reference.

type VFSFileLookupFunc 

type VFSFileLookupFunc func(vfs *VFS, identifier string) (file *File)

VFSFileLookupFunc: this function type is used by g_vfs_register_uri_scheme() to make it possible for a client to associate an URI scheme to a different #GFile implementation.

The client should return a reference to the new file that has been created for uri, or NULL to continue with the default implementation.

type VFSOverrides added in v0.0.5 

type VFSOverrides struct {
	AddWritableNamespaces func(list *FileAttributeInfoList)
	// FileForPath gets a #GFile for path.
	//
	// The function takes the following parameters:
	//
	//   - path: string containing a VFS path.
	//
	// The function returns the following values:
	//
	//   - file: #GFile. Free the returned object with g_object_unref().
	FileForPath func(path string) *File
	// FileForURI gets a #GFile for uri.
	//
	// This operation never fails, but the returned object might not support
	// any I/O operation if the URI is malformed or if the URI scheme is not
	// supported.
	//
	// The function takes the following parameters:
	//
	//   - uri: string containing a URI.
	//
	// The function returns the following values:
	//
	//   - file: #GFile. Free the returned object with g_object_unref().
	FileForURI func(uri string) *File
	// SupportedURISchemes gets a list of URI schemes supported by vfs.
	//
	// The function returns the following values:
	//
	//   - utf8s: NULL-terminated array of strings. The returned array belongs
	//     to GIO and must not be freed or modified.
	SupportedURISchemes func() []string
	// IsActive checks if the VFS is active.
	//
	// The function returns the following values:
	//
	//   - ok: TRUE if construction of the vfs was successful and it is now
	//     active.
	IsActive func() bool
	// The function takes the following parameters:
	//
	//   - source
	//   - dest
	LocalFileMoved   func(source, dest string)
	LocalFileRemoved func(filename string)
	// The function takes the following parameters:
	//
	//   - ctx (optional)
	//   - filename
	//   - info
	//   - flags
	LocalFileSetAttributes func(ctx context.Context, filename string, info *FileInfo, flags FileQueryInfoFlags) error
	// ParseName: this operation never fails, but the returned object might
	// not support any I/O operations if the parse_name cannot be parsed by the
	// #GVfs module.
	//
	// The function takes the following parameters:
	//
	//   - parseName: string to be parsed by the VFS module.
	//
	// The function returns the following values:
	//
	//   - file for the given parse_name. Free the returned object with
	//     g_object_unref().
	ParseName func(parseName string) *File
}

VFSOverrides contains methods that are overridable.

type Volume 

type Volume struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

Volume: GVolume interface represents user-visible objects that can be mounted. Note, when porting from GnomeVFS (migrating-gnome-vfs.html), GVolume is the moral equivalent of GnomeVFSDrive.

Mounting a GVolume instance is an asynchronous operation. For more information about asynchronous operations, see gio.AsyncResult and gio.Task. To mount a GVolume, first call gio.Volume.Mount() with (at least) the GVolume instance, optionally a gio.MountOperation object and a gio.AsyncReadyCallback.

Typically, one will only want to pass NULL for the gio.MountOperation if automounting all volumes when a desktop session starts since it’s not desirable to put up a lot of dialogs asking for credentials.

The callback will be fired when the operation has resolved (either with success or failure), and a gio.AsyncResult instance will be passed to the callback. That callback should then call gio.Volume.MountFinish() with the GVolume instance and the gio.AsyncResult data to see if the operation was completed successfully. If a glib.Error is present when gio.Volume.MountFinish() is called, then it will be filled with any error information.

Volume Identifiers

It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the command line). For this purpose, GIO allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. /dev/sda2), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: G_VOLUME_IDENTIFIER_KIND_UUID, G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use gio.Volume.GetIdentifier() to obtain an identifier for a volume.

Note that G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available when the GVFS hal volume monitor is in use. Other volume monitors will generally be able to provide the G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE identifier, which can be used to obtain a hal device by means of libhal_manager_find_device_string_match().

Volume wraps an interface. This means the user can get the underlying type by calling Cast().

func VolumeMonitorAdoptOrphanMount deprecated 

func VolumeMonitorAdoptOrphanMount(mount Mounter) *Volume

VolumeMonitorAdoptOrphanMount: this function should be called by any Monitor implementation when a new #GMount object is created that is not associated with a #GVolume object. It must be called just before emitting the mount_added signal.

If the return value is not NULL, the caller must associate the returned #GVolume object with the #GMount. This involves returning it in its g_mount_get_volume() implementation. The caller must also listen for the "removed" signal on the returned object and give up its reference when handling that signal

Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), the implementor must take a reference to mount and return it in its g_volume_get_mount() implemented. Also, the implementor must listen for the "unmounted" signal on mount and give up its reference upon handling that signal.

There are two main use cases for this function.

One is when implementing a user space file system driver that reads blocks of a block device that is already represented by the native volume monitor (for example a CD Audio file system driver). Such a driver will generate its own #GMount object that needs to be associated with the #GVolume object that represents the volume.

The other is for implementing a Monitor whose sole purpose is to return #GVolume objects representing entries in the users "favorite servers" list or similar.

Deprecated: Instead of using this function, Monitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions.

The function takes the following parameters:

  • mount object to find a parent for.

The function returns the following values:

  • volume object that is the parent for mount or NULL if no wants to adopt the #GMount.

func (*Volume) ActivationRoot 

func (volume *Volume) ActivationRoot() *File

ActivationRoot gets the activation root for a #GVolume if it is known ahead of mount time. Returns NULL otherwise. If not NULL and if volume is mounted, then the result of g_mount_get_root() on the #GMount object obtained from g_volume_get_mount() will always either be equal or a prefix of what this function returns. In other words, in code 

(g_file_has_prefix (volume_activation_root, mount_root) ||
 g_file_equal (volume_activation_root, mount_root))

will always be TRUE.

Activation roots are typically used in Monitor implementations to find the underlying mount to shadow, see g_mount_is_shadowed() for more details.

The function returns the following values:

  • file (optional): activation root of volume or NULL. Use g_object_unref() to free.

func (*Volume) CanEject 

func (volume *Volume) CanEject() bool

CanEject checks if a volume can be ejected.

The function returns the following values:

  • ok: TRUE if the volume can be ejected. FALSE otherwise.

func (*Volume) CanMount 

func (volume *Volume) CanMount() bool

CanMount checks if a volume can be mounted.

The function returns the following values:

  • ok: TRUE if the volume can be mounted. FALSE otherwise.

func (*Volume) ConnectChanged 

func (volume *Volume) ConnectChanged(f func()) coreglib.SignalHandle

ConnectChanged is emitted when the volume has been changed.

func (*Volume) ConnectRemoved 

func (volume *Volume) ConnectRemoved(f func()) coreglib.SignalHandle

ConnectRemoved: this signal is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.

func (*Volume) Drive 

func (volume *Volume) Drive() *Drive

Drive gets the drive for the volume.

The function returns the following values:

  • drive (optional) or NULL if volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Volume) Eject deprecated 

func (volume *Volume) Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)

Eject ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_finish() with the volume and Result returned in the callback.

Deprecated: Use g_volume_eject_with_operation() instead.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • callback (optional) or NULL.

func (*Volume) EjectFinish deprecated 

func (volume *Volume) EjectFinish(result AsyncResulter) error

EjectFinish finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

Deprecated: Use g_volume_eject_with_operation_finish() instead.

The function takes the following parameters:

  • result: Result.

func (*Volume) EjectWithOperation 

func (volume *Volume) EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

EjectWithOperation ejects a volume. This is an asynchronous operation, and is finished by calling g_volume_eject_with_operation_finish() with the volume and Result data returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the unmount if required for eject.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Volume) EjectWithOperationFinish 

func (volume *Volume) EjectWithOperationFinish(result AsyncResulter) error

EjectWithOperationFinish finishes ejecting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

The function takes the following parameters:

  • result: Result.

func (*Volume) EnumerateIdentifiers 

func (volume *Volume) EnumerateIdentifiers() []string

EnumerateIdentifiers gets the kinds of identifiers (#volume-identifiers) that volume has. Use g_volume_get_identifier() to obtain the identifiers themselves.

The function returns the following values:

  • utf8s: NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.

func (*Volume) GetMount 

func (volume *Volume) GetMount() *Mount

GetMount gets the mount for the volume.

The function returns the following values:

  • mount (optional) or NULL if volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Volume) Icon 

func (volume *Volume) Icon() *Icon

Icon gets the icon for volume.

The function returns the following values:

  • icon: #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Volume) Identifier 

func (volume *Volume) Identifier(kind string) string

Identifier gets the identifier of the given kind for volume. See the introduction (#volume-identifiers) for more information about volume identifiers.

The function takes the following parameters:

  • kind of identifier to return.

The function returns the following values:

  • utf8 (optional): newly allocated string containing the requested identifier, or NULL if the #GVolume doesn't have this kind of identifier.

func (*Volume) Mount 

func (volume *Volume) Mount(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)

Mount mounts a volume. This is an asynchronous operation, and is finished by calling g_volume_mount_finish() with the volume and Result returned in the callback.

The function takes the following parameters:

  • ctx (optional): optional #GCancellable object, NULL to ignore.
  • flags affecting the operation.
  • mountOperation (optional) or NULL to avoid user interaction.
  • callback (optional) or NULL.

func (*Volume) MountFinish 

func (volume *Volume) MountFinish(result AsyncResulter) error

MountFinish finishes mounting a volume. If any errors occurred during the operation, error will be set to contain the errors and FALSE will be returned.

If the mount operation succeeded, g_volume_get_mount() on volume is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on Monitor.

The function takes the following parameters:

  • result: Result.

func (*Volume) Name 

func (volume *Volume) Name() string

Name gets the name of volume.

The function returns the following values:

  • utf8: name for the given volume. The returned string should be freed with g_free() when no longer needed.

func (*Volume) ShouldAutomount 

func (volume *Volume) ShouldAutomount() bool

ShouldAutomount returns whether the volume should be automatically mounted.

The function returns the following values:

  • ok: TRUE if the volume should be automatically mounted.

func (*Volume) SortKey 

func (volume *Volume) SortKey() string

SortKey gets the sort key for volume, if any.

The function returns the following values:

  • utf8 (optional): sorting key for volume or NULL if no such key is available.

func (*Volume) SymbolicIcon 

func (volume *Volume) SymbolicIcon() *Icon

SymbolicIcon gets the symbolic icon for volume.

The function returns the following values:

  • icon: #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.

func (*Volume) UUID 

func (volume *Volume) UUID() string

UUID gets the UUID for the volume. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns NULL if there is no UUID available.

The function returns the following values:

  • utf8 (optional): UUID for volume or NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.

type VolumeIface added in v0.0.5 

type VolumeIface struct {
	// contains filtered or unexported fields
}

VolumeIface: interface for implementing operations for mountable volumes.

An instance of this type is always passed by reference.

type VolumeMonitor 

type VolumeMonitor struct {
	*coreglib.Object
	// contains filtered or unexported fields
}

VolumeMonitor: GVolumeMonitor is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar.

GVolumeMonitor is not thread-default-context aware (see glib.MainContext.PushThreadDefault()), and so should not be used other than from the main thread, with no thread-default-context active.

In order to receive updates about volumes and mounts monitored through GVFS, a main loop must be running.

func VolumeMonitorGet 

func VolumeMonitorGet() *VolumeMonitor

VolumeMonitorGet gets the volume monitor used by gio.

The function returns the following values:

  • volumeMonitor: reference to the Monitor used by gio. Call g_object_unref() when done with it.

func (*VolumeMonitor) ConnectDriveChanged 

func (volumeMonitor *VolumeMonitor) ConnectDriveChanged(f func(drive Driver)) coreglib.SignalHandle

ConnectDriveChanged is emitted when a drive changes.

func (*VolumeMonitor) ConnectDriveConnected 

func (volumeMonitor *VolumeMonitor) ConnectDriveConnected(f func(drive Driver)) coreglib.SignalHandle

ConnectDriveConnected is emitted when a drive is connected to the system.

func (*VolumeMonitor) ConnectDriveDisconnected 

func (volumeMonitor *VolumeMonitor) ConnectDriveDisconnected(f func(drive Driver)) coreglib.SignalHandle

ConnectDriveDisconnected is emitted when a drive is disconnected from the system.

func (*VolumeMonitor) ConnectDriveEjectButton 

func (volumeMonitor *VolumeMonitor) ConnectDriveEjectButton(f func(drive Driver)) coreglib.SignalHandle

ConnectDriveEjectButton is emitted when the eject button is pressed on drive.

func (*VolumeMonitor) ConnectDriveStopButton 

func (volumeMonitor *VolumeMonitor) ConnectDriveStopButton(f func(drive Driver)) coreglib.SignalHandle

ConnectDriveStopButton is emitted when the stop button is pressed on drive.

func (*VolumeMonitor) ConnectMountAdded 

func (volumeMonitor *VolumeMonitor) ConnectMountAdded(f func(mount Mounter)) coreglib.SignalHandle

ConnectMountAdded is emitted when a mount is added.

func (*VolumeMonitor) ConnectMountChanged 

func (volumeMonitor *VolumeMonitor) ConnectMountChanged(f func(mount Mounter)) coreglib.SignalHandle

ConnectMountChanged is emitted when a mount changes.

func (*VolumeMonitor) ConnectMountPreUnmount 

func (volumeMonitor *VolumeMonitor) ConnectMountPreUnmount(f func(mount Mounter)) coreglib.SignalHandle

ConnectMountPreUnmount: may be emitted when a mount is about to be removed.

This signal depends on the backend and is only emitted if GIO was used to unmount.

func (*VolumeMonitor) ConnectMountRemoved 

func (volumeMonitor *VolumeMonitor) ConnectMountRemoved(f func(mount Mounter)) coreglib.SignalHandle

ConnectMountRemoved is emitted when a mount is removed.

func (*VolumeMonitor) ConnectVolumeAdded 

func (volumeMonitor *VolumeMonitor) ConnectVolumeAdded(f func(volume Volumer)) coreglib.SignalHandle

ConnectVolumeAdded is emitted when a mountable volume is added to the system.

func (*VolumeMonitor) ConnectVolumeChanged 

func (volumeMonitor *VolumeMonitor) ConnectVolumeChanged(f func(volume Volumer)) coreglib.SignalHandle

ConnectVolumeChanged is emitted when mountable volume is changed.

func (*VolumeMonitor) ConnectVolumeRemoved 

func (volumeMonitor *VolumeMonitor) ConnectVolumeRemoved(f func(volume Volumer)) coreglib.SignalHandle

ConnectVolumeRemoved is emitted when a mountable volume is removed from the system.

func (*VolumeMonitor) ConnectedDrives 

func (volumeMonitor *VolumeMonitor) ConnectedDrives() []*Drive

ConnectedDrives gets a list of drives connected to the system.

The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

The function returns the following values:

  • list of connected #GDrive objects.

func (*VolumeMonitor) MountForUUID 

func (volumeMonitor *VolumeMonitor) MountForUUID(uuid string) *Mount

MountForUUID finds a #GMount object by its UUID (see g_mount_get_uuid()).

The function takes the following parameters:

  • uuid: UUID to look for.

The function returns the following values:

  • mount (optional) or NULL if no such mount is available. Free the returned object with g_object_unref().

func (*VolumeMonitor) Mounts 

func (volumeMonitor *VolumeMonitor) Mounts() []*Mount

Mounts gets a list of the mounts on the system.

The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

The function returns the following values:

  • list of #GMount objects.

func (*VolumeMonitor) VolumeForUUID 

func (volumeMonitor *VolumeMonitor) VolumeForUUID(uuid string) *Volume

VolumeForUUID finds a #GVolume object by its UUID (see g_volume_get_uuid()).

The function takes the following parameters:

  • uuid: UUID to look for.

The function returns the following values:

  • volume (optional) or NULL if no such volume is available. Free the returned object with g_object_unref().

func (*VolumeMonitor) Volumes 

func (volumeMonitor *VolumeMonitor) Volumes() []*Volume

Volumes gets a list of the volumes on the system.

The returned list should be freed with g_list_free(), after its elements have been unreffed with g_object_unref().

The function returns the following values:

  • list of #GVolume objects.

type VolumeMonitorClass added in v0.0.5 

type VolumeMonitorClass struct {
	// contains filtered or unexported fields
}

VolumeMonitorClass: instance of this type is always passed by reference.

type VolumeMonitorOverrides added in v0.0.5 

type VolumeMonitorOverrides struct {
	DriveChanged      func(drive Driver)
	DriveConnected    func(drive Driver)
	DriveDisconnected func(drive Driver)
	DriveEjectButton  func(drive Driver)
	DriveStopButton   func(drive Driver)
	// ConnectedDrives gets a list of drives connected to the system.
	//
	// The returned list should be freed with g_list_free(), after its elements
	// have been unreffed with g_object_unref().
	//
	// The function returns the following values:
	//
	//   - list of connected #GDrive objects.
	ConnectedDrives func() []*Drive
	// MountForUUID finds a #GMount object by its UUID (see g_mount_get_uuid()).
	//
	// The function takes the following parameters:
	//
	//   - uuid: UUID to look for.
	//
	// The function returns the following values:
	//
	//   - mount (optional) or NULL if no such mount is available. Free the
	//     returned object with g_object_unref().
	MountForUUID func(uuid string) *Mount
	// Mounts gets a list of the mounts on the system.
	//
	// The returned list should be freed with g_list_free(), after its elements
	// have been unreffed with g_object_unref().
	//
	// The function returns the following values:
	//
	//   - list of #GMount objects.
	Mounts func() []*Mount
	// VolumeForUUID finds a #GVolume object by its UUID (see
	// g_volume_get_uuid()).
	//
	// The function takes the following parameters:
	//
	//   - uuid: UUID to look for.
	//
	// The function returns the following values:
	//
	//   - volume (optional) or NULL if no such volume is available. Free the
	//     returned object with g_object_unref().
	VolumeForUUID func(uuid string) *Volume
	// Volumes gets a list of the volumes on the system.
	//
	// The returned list should be freed with g_list_free(), after its elements
	// have been unreffed with g_object_unref().
	//
	// The function returns the following values:
	//
	//   - list of #GVolume objects.
	Volumes         func() []*Volume
	MountAdded      func(mount Mounter)
	MountChanged    func(mount Mounter)
	MountPreUnmount func(mount Mounter)
	MountRemoved    func(mount Mounter)
	VolumeAdded     func(volume Volumer)
	VolumeChanged   func(volume Volumer)
	VolumeRemoved   func(volume Volumer)
}

VolumeMonitorOverrides contains methods that are overridable.

type Volumer 

type Volumer interface {
	coreglib.Objector

	// CanEject checks if a volume can be ejected.
	CanEject() bool
	// CanMount checks if a volume can be mounted.
	CanMount() bool
	// Eject ejects a volume.
	Eject(ctx context.Context, flags MountUnmountFlags, callback AsyncReadyCallback)
	// EjectFinish finishes ejecting a volume.
	EjectFinish(result AsyncResulter) error
	// EjectWithOperation ejects a volume.
	EjectWithOperation(ctx context.Context, flags MountUnmountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// EjectWithOperationFinish finishes ejecting a volume.
	EjectWithOperationFinish(result AsyncResulter) error
	// EnumerateIdentifiers gets the kinds of identifiers (#volume-identifiers)
	// that volume has.
	EnumerateIdentifiers() []string
	// ActivationRoot gets the activation root for a #GVolume if it is known
	// ahead of mount time.
	ActivationRoot() *File
	// Drive gets the drive for the volume.
	Drive() *Drive
	// Icon gets the icon for volume.
	Icon() *Icon
	// Identifier gets the identifier of the given kind for volume.
	Identifier(kind string) string
	// GetMount gets the mount for the volume.
	GetMount() *Mount
	// Name gets the name of volume.
	Name() string
	// SortKey gets the sort key for volume, if any.
	SortKey() string
	// SymbolicIcon gets the symbolic icon for volume.
	SymbolicIcon() *Icon
	// UUID gets the UUID for the volume.
	UUID() string
	// Mount mounts a volume.
	Mount(ctx context.Context, flags MountMountFlags, mountOperation *MountOperation, callback AsyncReadyCallback)
	// MountFinish finishes mounting a volume.
	MountFinish(result AsyncResulter) error
	// ShouldAutomount returns whether the volume should be automatically
	// mounted.
	ShouldAutomount() bool

	// Changed is emitted when the volume has been changed.
	ConnectChanged(func()) coreglib.SignalHandle
	// Removed: this signal is emitted when the #GVolume have been removed.
	ConnectRemoved(func()) coreglib.SignalHandle
}

Volumer describes Volume's interface methods.

type ZlibCompressor 

type ZlibCompressor struct {
	*coreglib.Object

	Converter
	// contains filtered or unexported fields
}

ZlibCompressor: GZlibCompressor is an implementation of gio.Converter that compresses data using zlib.

func NewZlibCompressor 

func NewZlibCompressor(format ZlibCompressorFormat, level int) *ZlibCompressor

NewZlibCompressor creates a new Compressor.

The function takes the following parameters:

  • format to use for the compressed data.
  • level: compression level (0-9), -1 for default.

The function returns the following values:

  • zlibCompressor: new Compressor.

func (*ZlibCompressor) FileInfo 

func (compressor *ZlibCompressor) FileInfo() *FileInfo

FileInfo returns the Compressor:file-info property.

The function returns the following values:

  • fileInfo (optional) or NULL.

func (*ZlibCompressor) SetFileInfo 

func (compressor *ZlibCompressor) SetFileInfo(fileInfo *FileInfo)

SetFileInfo sets file_info in compressor. If non-NULL, and compressor's Compressor:format property is G_ZLIB_COMPRESSOR_FORMAT_GZIP, it will be used to set the file name and modification time in the GZIP header of the compressed data.

Note: it is an error to call this function while a compression is in progress; it may only be called immediately after creation of compressor, or after resetting it with g_converter_reset().

The function takes the following parameters:

  • fileInfo (optional): Info.

type ZlibCompressorClass added in v0.0.5 

type ZlibCompressorClass struct {
	// contains filtered or unexported fields
}

ZlibCompressorClass: instance of this type is always passed by reference.

type ZlibCompressorFormat 

type ZlibCompressorFormat C.gint

ZlibCompressorFormat: used to select the type of data format to use for Decompressor and Compressor. 

const (
	// ZlibCompressorFormatZlib: deflate compression with zlib header.
	ZlibCompressorFormatZlib ZlibCompressorFormat = iota
	// ZlibCompressorFormatGzip: gzip file format.
	ZlibCompressorFormatGzip
	// ZlibCompressorFormatRaw: deflate compression with no header.
	ZlibCompressorFormatRaw
)

func (ZlibCompressorFormat) String 

func (z ZlibCompressorFormat) String() string

String returns the name in string for ZlibCompressorFormat.

type ZlibCompressorOverrides added in v0.0.5 

type ZlibCompressorOverrides struct {
}

ZlibCompressorOverrides contains methods that are overridable.

type ZlibDecompressor 

type ZlibDecompressor struct {
	*coreglib.Object

	Converter
	// contains filtered or unexported fields
}

ZlibDecompressor: GZlibDecompressor is an implementation of gio.Converter that decompresses data compressed with zlib.

func NewZlibDecompressor 

func NewZlibDecompressor(format ZlibCompressorFormat) *ZlibDecompressor

NewZlibDecompressor creates a new Decompressor.

The function takes the following parameters:

  • format to use for the compressed data.

The function returns the following values:

  • zlibDecompressor: new Decompressor.

func (*ZlibDecompressor) FileInfo 

func (decompressor *ZlibDecompressor) FileInfo() *FileInfo

FileInfo retrieves the Info constructed from the GZIP header data of compressed data processed by compressor, or NULL if decompressor's Decompressor:format property is not G_ZLIB_COMPRESSOR_FORMAT_GZIP, or the header data was not fully processed yet, or it not present in the data stream at all.

The function returns the following values:

  • fileInfo (optional) or NULL.

type ZlibDecompressorClass added in v0.0.5 

type ZlibDecompressorClass struct {
	// contains filtered or unexported fields
}

ZlibDecompressorClass: instance of this type is always passed by reference.

type ZlibDecompressorOverrides added in v0.0.5 

type ZlibDecompressorOverrides struct {
}

ZlibDecompressorOverrides contains methods that are overridable.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.