`SECURITY UNLOCK DEVICE`` command) `Emblem` is an implementation of `Icon` that supports having an emblem, which is an icon with additional properties. It can than be added to a `EmblemedIcon`. Currently, only metainformation about the emblem's origin is supported. More may be added in the future. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) Creates a new emblem for `icon`. ## `icon` a GIcon containing the icon. # Returns a new `Emblem`. Creates a new emblem for `icon`. ## `icon` a GIcon containing the icon. ## `origin` a GEmblemOrigin enum defining the emblem's origin # Returns a new `Emblem`. Gives back the icon from `self`. # Returns a `Icon`. The returned object belongs to the emblem and should not be modified or freed. Gets the origin of the emblem. # Returns the origin of the emblem GEmblemOrigin is used to add information about the origin of the emblem to `Emblem`. Emblem of unknown origin Emblem adds device-specific information Emblem depicts live metadata, such as "readonly" Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) `EmblemedIcon` is an implementation of `Icon` that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via `EmblemedIconExt::add_emblem`. Note that `EmblemedIcon` allows no control over the position of the emblems. See also `Emblem` for more information. # Implements [`EmblemedIconExt`](trait.EmblemedIconExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html) Trait containing all `EmblemedIcon` methods. # Implementors [`EmblemedIcon`](struct.EmblemedIcon.html) Creates a new emblemed icon for `icon` with the emblem `emblem`. ## `icon` a `Icon` ## `emblem` a `Emblem`, or `None` # Returns a new `Icon` Adds `emblem` to the `glib::List` of `GEmblems`. ## `emblem` a `Emblem` Removes all the emblems from `icon`. Gets the list of emblems for the `icon`. # Returns a `glib::List` of `GEmblems` that is owned by `self` Gets the main icon for `self`. # Returns a `Icon` that is owned by `self` `File` 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 `File` objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations (see `InputStream` and `OutputStream`). To construct a `File`, you can use: - `File::new_for_path` if you have a path. - `File::new_for_uri` if you have a URI. - `File::new_for_commandline_arg` for a command line argument. - `File::new_tmp` to create a temporary file from a template. - `File::parse_name` from a UTF-8 string gotten from `File::get_parse_name`. - `File::new_build_filename` to create a file from path elements. One way to think of a `File` 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 `File` using `File::get_parent` to get an identifier for the parent directory, `File::get_child` to get a child within a directory, `File::resolve_relative_path` 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 `File::get_parent` on two different files. All `GFiles` have a basename (get with `File::get_basename`). 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 `File::query_info`. This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the `File` to use to actually access the file, because there is no way to go from a display name to the actual name. Using `File` 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 `File` 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 `File` 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 `GAsyncReadyCallback` which is then used to finalize the operation, producing a GAsyncResult 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][async-programming] for more. Some `File` operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include: - `File::mount_mountable` to mount a mountable file. - `File::unmount_mountable_with_operation` to unmount a mountable file. - `File::eject_mountable_with_operation` to eject a mountable file. ## Entity Tags # {`gfile`-etag} 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. # Implements [`FileExt`](trait.FileExt.html), [`FileExtManual`](prelude/trait.FileExtManual.html) Trait containing all `File` methods. # Implementors [`File`](struct.File.html) Constructs a `File` from a series of elements using the correct separator for filenames. Using this function is equivalent to calling `g_build_filename`, followed by `File::new_for_path` on the result. Feature: `v2_56` ## `first_element` the first element in the path # Returns a new `File` Creates a `File` 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. `Application` also uses UTF-8 but `ApplicationCommandLineExt::create_file_for_arg` may be more useful for you there. It is also always possible to use this function with `glib::OptionContext` arguments of type `glib::OptionArg::Filename`. ## `arg` a command line string # Returns a new `File`. Free the returned object with `gobject::ObjectExt::unref`. Creates a `File` with the given argument from the command line. This function is similar to `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 `ApplicationCommandLineExt::create_file_for_arg`. ## `arg` a command line string ## `cwd` the current working directory of the commandline # Returns a new `File` Constructs a `File` for a given path. This operation never fails, but the returned object might not support any I/O operation if `path` is malformed. ## `path` a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. # Returns a new `File` for the given `path`. Free the returned object with `gobject::ObjectExt::unref`. Constructs a `File` 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. ## `uri` a UTF-8 string containing a URI # Returns a new `File` for the given `uri`. Free the returned object with `gobject::ObjectExt::unref`. Opens a file in the preferred directory for temporary files (as returned by `g_get_tmp_dir`) and returns a `File` and `FileIOStream` 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 `None`, a default template is used. Unlike the other `File` constructors, this will return `None` if a temporary file could not be created. ## `tmpl` Template for the file name, as in `g_file_open_tmp`, or `None` for a default template ## `iostream` on return, a `FileIOStream` for the created file # Returns a new `File`. Free the returned object with `gobject::ObjectExt::unref`. Constructs a `File` with the given `parse_name` (i.e. something given by `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. ## `parse_name` a file name or path to be parsed # Returns a new `File`. 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 `FileCreateFlags::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error. If the file is a directory the `IOErrorEnum::IsDirectory` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for appending. For more details, see `File::append_to` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::append_to_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file append operation started with `File::append_to_async`. ## `res` `AsyncResult` # Returns a valid `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Copies the file `self` to the location specified by `destination`. Can not handle recursive copies of directories. If the flag `FileCopyFlags::Overwrite` is specified an already existing `destination` file is overwritten. If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks will be copied as symlinks, otherwise the target of the `self` symlink will be copied. If the flag `FileCopyFlags::AllMetadata` is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see `FileInfo`). If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `progress_callback` is not `None`, then the operation can be monitored by setting this to a `GFileProgressCallback` function. `progress_callback_data` will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the `self` file does not exist, then the `IOErrorEnum::NotFound` error is returned, independent on the status of the `destination`. If `FileCopyFlags::Overwrite` is not specified and the target exists, then the error `IOErrorEnum::Exists` is returned. If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` error is returned. If trying to overwrite a directory with a directory the `IOErrorEnum::WouldMerge` error is returned. If the source is a directory and the target does not exist, or `FileCopyFlags::Overwrite` is specified and the target is a file, then the `IOErrorEnum::WouldRecurse` error is returned. If you are interested in copying the `File` object itself (not the on-disk file), see `File::dup`. ## `destination` destination `File` ## `flags` set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` function to callback with progress information, or `None` if progress information is not needed ## `progress_callback_data` user data to pass to `progress_callback` # Returns `true` on success, `false` otherwise. Copies the file `self` to the location specified by `destination` asynchronously. For details of the behaviour, see `File::copy`. If `progress_callback` is not `None`, then that function that will be called just like in `File::copy`. The callback will run in the default main context of the thread calling `File::copy_async` — the same context as `callback` is run in. When the operation is finished, `callback` will be called. You can then call `File::copy_finish` to get the result of the operation. ## `destination` destination `File` ## `flags` set of `FileCopyFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` function to callback with progress information, or `None` if progress information is not needed ## `progress_callback_data` user data to pass to `progress_callback` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Copies the file attributes from `self` 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 `FileCopyFlags::AllMetadata` 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. ## `destination` a `File` to copy attributes to ## `flags` a set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the attributes were copied successfully, `false` otherwise. Finishes copying the file started with `File::copy_async`. ## `res` a `AsyncResult` # Returns a `true` on success, `false` on error. 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 `FileCreateFlags::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If a file or directory with this name already exists the `IOErrorEnum::Exists` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is to long `IOErrorEnum::FilenameTooLong` will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream` for the newly created file, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist. For more details, see `File::create` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::create_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file create operation started with `File::create_async`. ## `res` a `AsyncResult` # Returns a `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `FileCreateFlags::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If a file or directory with this name already exists, the `IOErrorEnum::Exists` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is too long, `IOErrorEnum::FilenameTooLong` 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. ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileIOStream` for the newly created file, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `File::create_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::create_readwrite_finish` to get the result of the operation. ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file create operation started with `File::create_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Deletes a file. If the `self` is a directory, it will only be deleted if it is empty. This has the same semantics as `g_unlink`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the file was deleted. `false` otherwise. Asynchronously delete a file. If the `self` is a directory, it will only be deleted if it is empty. This has the same semantics as `g_unlink`. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes deleting a file started with `File::delete_async`. ## `result` a `AsyncResult` # Returns `true` if the file was deleted. `false` otherwise. Duplicates a `File` handle. This operation does not duplicate the actual file or directory represented by the `File`; see `File::copy` if attempting to copy a file. `File::dup` is useful when a second handle is needed to the same underlying file, for use in a separate thread (`File` is not thread-safe). For use within the same thread, use `gobject::ObjectExt::ref` to increment the existing object’s reference count. This call does no blocking I/O. # Returns a new `File` that is a duplicate of the given `File`. 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 `File::eject_mountable_with_operation_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an asynchronous eject operation started by `File::eject_mountable_with_operation`. ## `result` a `AsyncResult` # Returns `true` if the `self` was ejected successfully. `false` otherwise. Gets the requested information about the files in a directory. The result is a `FileEnumerator` object that will give out `FileInfo` 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`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is not a directory, the `IOErrorEnum::NotDirectory` error will be returned. Other errors are possible too. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns A `FileEnumerator` if successful, `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about the files in a directory. The result is a `FileEnumerator` object that will give out `FileInfo` objects for all the files in the directory. For more details, see `File::enumerate_children` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::enumerate_children_finish` to get the result of the operation. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an async enumerate children operation. See `File::enumerate_children_async`. ## `res` a `AsyncResult` # Returns a `FileEnumerator` or `None` if an error occurred. Free the returned object with `gobject::ObjectExt::unref`. 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. ## `file2` the second `File` # Returns `true` if `self` and `file2` are equal. Gets a `Mount` for the `File`. If the `FileIface` for `self` does not have a mount (e.g. possibly a remote share), `error` will be set to `IOErrorEnum::NotFound` and `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `Mount` where the `self` is located or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the mount for the file. For more details, see `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 `File::find_enclosing_mount_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous find mount request. See `File::find_enclosing_mount_async`. ## `res` a `AsyncResult` # Returns `Mount` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the base name (the last component of the path) for a given `File`. 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 `File::query_info`. This call does no blocking I/O. # Returns string containing the `File`'s base name, or `None` if given `File` is invalid. The returned string should be freed with `g_free` when no longer needed. Gets a child of `self` with basename equal to `name`. Note that the file with that specific name might not exist, but you can still have a `File` that points to it. You can use this for instance to create that file. This call does no blocking I/O. ## `name` string containing the child's basename # Returns a `File` to a child specified by `name`. Free the returned object with `gobject::ObjectExt::unref`. Gets the child of `self` for a given `display_name` (i.e. a UTF-8 version of the name). If this function fails, it returns `None` and `error` will be set. This is very useful when constructing a `File` 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. ## `display_name` string to a possible child # Returns a `File` to the specified child, or `None` if the display name couldn't be converted. Free the returned object with `gobject::ObjectExt::unref`. Gets the parent directory for the `self`. If the `self` represents the root directory of the file system, then `None` will be returned. This call does no blocking I/O. # Returns a `File` structure to the parent of the given `File` or `None` if there is no parent. Free the returned object with `gobject::ObjectExt::unref`. Gets the parse name of the `self`. A parse name is a UTF-8 string that describes the file such that one can get the `File` back using `File::parse_name`. This is generally used to show the `File` 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. # Returns a string containing the `File`'s parse name. The returned string should be freed with `g_free` when no longer needed. Gets the local pathname for `File`, if one exists. If non-`None`, this is guaranteed to be an absolute, canonical path. It might contain symlinks. This call does no blocking I/O. # Returns string containing the `File`'s path, or `None` if no such path exists. The returned string should be freed with `g_free` when no longer needed. Gets the path for `descendant` relative to `self`. This call does no blocking I/O. ## `descendant` input `File` # Returns string with the relative path from `descendant` to `self`, or `None` if `descendant` doesn't have `self` as prefix. The returned string should be freed with `g_free` when no longer needed. Gets the URI for the `self`. This call does no blocking I/O. # Returns a string containing the `File`'s URI. The returned string should be freed with `g_free` when no longer needed. Gets the URI scheme for a `File`. RFC 3986 decodes the scheme as: ```text URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ``` Common schemes include "file", "http", "ftp", etc. This call does no blocking I/O. # Returns a string containing the URI scheme for the given `File`. The returned string should be freed with `g_free` when no longer needed. Checks if `self` has a parent, and optionally, if it is `parent`. If `parent` is `None` then this function returns `true` if `self` has any parent at all. If `parent` is non-`None` then `true` is only returned if `self` is an immediate child of `parent`. ## `parent` the parent to check for, or `None` # Returns `true` if `self` is an immediate child of `parent` (or any parent in the case that `parent` is `None`). Checks whether `self` has the prefix specified by `prefix`. In other words, if the names of initial elements of `self`'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 `File` is not a prefix of itself. If you want to check for equality, use `File::equal`. This call does no I/O, as it works purely on names. As such it can sometimes return `false` even if `self` is inside a `prefix` (from a filesystem point of view), because the prefix of `self` is an alias of `prefix`. ## `prefix` input `File` # Returns `true` if the `files`'s parent, grandparent, etc is `prefix`, `false` otherwise. Checks to see if a `File` has a given URI scheme. This call does no blocking I/O. ## `uri_scheme` a string containing a URI scheme # Returns `true` if `File`'s backend supports the given URI scheme, `false` if URI scheme is `None`, not supported, or `File` is invalid. Creates a hash value for a `File`. This call does no blocking I/O. # Returns 0 if `self` is not a valid `File`, otherwise an integer that can be used as hash value for the `File`. This function is intended for easily hashing a `File` to add to a `glib::HashTable` or similar data structure. 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 `File::get_path` will still return a native path. This call does no blocking I/O. # Returns `true` if `self` is native Loads the contents of `self` and returns it as `glib::Bytes`. If `self` is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling `File::load_contents` and `glib::Bytes::new_take`. For resources, `etag_out` will be set to `None`. The data contained in the resulting `glib::Bytes` is always zero-terminated, but this is not included in the `glib::Bytes` length. The resulting `glib::Bytes` should be freed with `glib::Bytes::unref` when no longer in use. Feature: `v2_56` ## `cancellable` a `Cancellable` or `None` ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns a `glib::Bytes` or `None` and `error` is set Asynchronously loads the contents of `self` as `glib::Bytes`. If `self` is a resource:// based URI, the resulting bytes will reference the embedded resource instead of a copy. Otherwise, this is equivalent to calling `File::load_contents_async` and `glib::Bytes::new_take`. `callback` should call `File::load_bytes_finish` to get the result of this asynchronous operation. See `File::load_bytes` for more information. Feature: `v2_56` ## `cancellable` a `Cancellable` or `None` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Completes an asynchronous request to `File::load_bytes_async`. For resources, `etag_out` will be set to `None`. The data contained in the resulting `glib::Bytes` is always zero-terminated, but this is not included in the `glib::Bytes` length. The resulting `glib::Bytes` should be freed with `glib::Bytes::unref` when no longer in use. See `File::load_bytes` for more information. Feature: `v2_56` ## `result` a `AsyncResult` provided to the callback ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns a `glib::Bytes` or `None` and `error` is set 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 `content` should be freed with `g_free` when no longer needed. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the `self`'s contents were successfully loaded. `false` if there were errors. Starts an asynchronous load of the `self`'s contents. For more details, see `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 `File::load_contents_finish` with the `AsyncResult` returned by the `callback`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous load of the `self`'s contents. The contents are placed in `contents`, and `length` is set to the size of the `contents` string. The `content` 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 `self`. ## `res` a `AsyncResult` ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the load was successful. If `false` and `error` is present, it will be set appropriately. Reads the partial contents of a file. A `GFileReadMoreCallback` should be used to stop reading from the file when appropriate, else this function will behave exactly as `File::load_contents_async`. This operation can be finished by `File::load_partial_contents_finish`. Users of this function should be aware that `user_data` is passed to both the `read_more_callback` and the `callback`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `read_more_callback` a `GFileReadMoreCallback` to receive partial data and to specify whether further data should be read ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to the callback functions Finishes an asynchronous partial load operation that was started with `File::load_partial_contents_async`. The data is always zero-terminated, but this is not included in the resultant `length`. The returned `content` should be freed with `g_free` when no longer needed. ## `res` a `AsyncResult` ## `contents` a location to place the contents of the file ## `length` a location to place the length of the contents of the file, or `None` if the length is not needed ## `etag_out` a location to place the current entity tag for the file, or `None` if the entity tag is not needed # Returns `true` if the load was successful. If `false` and `error` is present, it will be set appropriately. 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 `File`. To recursively create directories, see `File::make_directory_with_parents`. This function will fail if the parent directory does not exist, setting `error` to `IOErrorEnum::NotFound`. If the file system doesn't support creating directories, this function will fail, setting `error` to `IOErrorEnum::NotSupported`. For a local `File` the newly created directory will have the default (current) ownership and permissions of the current process. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on successful creation, `false` otherwise. Asynchronously creates a directory. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous directory creation, started with `File::make_directory_async`. ## `result` a `AsyncResult` # Returns `true` on successful directory creation, `false` otherwise. 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 `IOErrorEnum::NotSupported`. If the directory itself already exists, this function will fail setting `error` to `IOErrorEnum::Exists`, unlike the similar `g_mkdir_with_parents`. For a local `File` the newly created directories will have the default (current) ownership and permissions of the current process. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if all directories have been successfully created, `false` otherwise. Creates a symbolic link named `self` which contains the string `symlink_value`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `symlink_value` a string with the path for the target of the new symlink ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on the creation of a new symlink, `false` otherwise. Recursively measures the disk usage of `self`. This is essentially an analog of the 'du' command, but it also reports the number of directories and non-directory files encountered (including things like symbolic links). By default, errors are only reported against the toplevel file itself. Errors found while recursing are silently ignored, unless `G_FILE_DISK_USAGE_REPORT_ALL_ERRORS` is given in `flags`. The returned size, `disk_usage`, is in bytes and should be formatted with `g_format_size` in order to get something reasonable for showing in a user interface. `progress_callback` and `progress_data` can be given to request periodic progress updates while scanning. See the documentation for `GFileMeasureProgressCallback` for information about when and how the callback will be invoked. ## `flags` `FileMeasureFlags` ## `cancellable` optional `Cancellable` ## `progress_callback` a `GFileMeasureProgressCallback` ## `progress_data` user_data for `progress_callback` ## `disk_usage` the number of bytes of disk space used ## `num_dirs` the number of directories encountered ## `num_files` the number of non-directories encountered # Returns `true` if successful, with the out parameters set. `false` otherwise, with `error` set. Recursively measures the disk usage of `self`. This is the asynchronous version of `File::measure_disk_usage`. See there for more information. ## `flags` `FileMeasureFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` ## `progress_callback` a `GFileMeasureProgressCallback` ## `progress_data` user_data for `progress_callback` ## `callback` a `GAsyncReadyCallback` to call when complete ## `user_data` the data to pass to callback function Collects the results from an earlier call to `File::measure_disk_usage_async`. See `File::measure_disk_usage` for more information. ## `result` the `AsyncResult` passed to your `GAsyncReadyCallback` ## `disk_usage` the number of bytes of disk space used ## `num_dirs` the number of directories encountered ## `num_files` the number of non-directories encountered # Returns `true` if successful, with the out parameters set. `false` otherwise, with `error` set. Obtains a file or directory monitor for the given file, depending on the type of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Obtains a directory monitor for the given file. This may fail if directory monitoring is not supported. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. It does not make sense for `flags` to contain `FileMonitorFlags::WatchHardLinks`, 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 `File::monitor`. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `flags` contains `FileMonitorFlags::WatchHardLinks` 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 `self` to be reported. Using this flag may result in an increase in resource usage, and may not have any effect depending on the `FileMonitor` backend and/or filesystem type. ## `flags` a set of `FileMonitorFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileMonitor` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Starts a `mount_operation`, mounting the volume that contains the file `self`. When this operation has completed, `callback` will be called with `user_user` data, and the operation can be finalized with `File::mount_enclosing_volume_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a mount operation started by `File::mount_enclosing_volume`. ## `result` a `AsyncResult` # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a mount operation. See `File::mount_mountable` for details. Finish an asynchronous mount operation that was started with `File::mount_mountable`. ## `result` a `AsyncResult` # Returns a `File` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Tries to move the file or directory `self` to the location specified by `destination`. If native move operations are supported then this is used, otherwise a copy + delete fallback is used. The native implementation may support moving directories (for instance on moves inside the same filesystem), but the fallback code does not. If the flag `FileCopyFlags::Overwrite` is specified an already existing `destination` file is overwritten. If the flag `FileCopyFlags::NofollowSymlinks` is specified then symlinks will be copied as symlinks, otherwise the target of the `self` symlink will be copied. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `progress_callback` is not `None`, then the operation can be monitored by setting this to a `GFileProgressCallback` function. `progress_callback_data` will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation. If the `self` file does not exist, then the `IOErrorEnum::NotFound` error is returned, independent on the status of the `destination`. If `FileCopyFlags::Overwrite` is not specified and the target exists, then the error `IOErrorEnum::Exists` is returned. If trying to overwrite a file over a directory, the `IOErrorEnum::IsDirectory` error is returned. If trying to overwrite a directory with a directory the `IOErrorEnum::WouldMerge` error is returned. If the source is a directory and the target does not exist, or `FileCopyFlags::Overwrite` is specified and the target is a file, then the `IOErrorEnum::WouldRecurse` error may be returned (if the native move operation isn't available). ## `destination` `File` pointing to the destination location ## `flags` set of `FileCopyFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `progress_callback` `GFileProgressCallback` function for updates ## `progress_callback_data` gpointer to user data for the callback function # Returns `true` on successful move, `false` otherwise. Opens an existing file for reading and writing. The result is a `FileIOStream` that can be used to read and write the contents of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is a directory, the `IOErrorEnum::IsDirectory` 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. ## `cancellable` a `Cancellable` # Returns `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for reading and writing. For more details, see `File::open_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::open_readwrite_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file read operation started with `File::open_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Exactly like `File::get_path`, but caches the result via `gobject::ObjectExt::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. Feature: `v2_56` # Returns string containing the `File`'s path, or `None` if no such path exists. The returned string is owned by `self`. Polls a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a poll operation. See `File::poll_mountable` for details. Finish an asynchronous poll operation that was polled with `File::poll_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Returns the `AppInfo` that is registered as the default application to handle the file specified by `self`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `AppInfo` if the handle was found, `None` if there were errors. When you are done with it, release it with `gobject::ObjectExt::unref` Utility function to check if a particular file exists. This is implemented using `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 `File::create` which will either atomically create the file or fail with a `IOErrorEnum::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. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the file exists (and can be detected without error), `false` otherwise (or if cancelled). Utility function to inspect the `FileType` of a file. This is implemented using `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. ## `flags` a set of `FileQueryInfoFlags` passed to `File::query_info` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns The `FileType` of the file and `FileType::Unknown` if the file does not exist Similar to `File::query_info`, but obtains information about the filesystem the `self` 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `attributes` an attribute query string ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileInfo` or `None` if there was an error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about the filesystem that the specified `self` is on. The result is a `FileInfo` object that contains key-value attributes (such as type or size for the file). For more details, see `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 `File::query_info_finish` to get the result of the operation. ## `attributes` an attribute query string ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous filesystem info query. See `File::query_filesystem_info_async`. ## `res` a `AsyncResult` # Returns `FileInfo` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Gets the requested information about specified `self`. The result is a `FileInfo` 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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 `FileQueryInfoFlags::NofollowSymlinks` 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 `IOErrorEnum::NotFound` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileInfo` for the given `self`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously gets the requested information about specified `self`. The result is a `FileInfo` object that contains key-value attributes (such as type or size for the file). For more details, see `File::query_info` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::query_info_finish` to get the result of the operation. ## `attributes` an attribute query string ## `flags` a set of `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file info query. See `File::query_info_async`. ## `res` a `AsyncResult` # Returns `FileInfo` for given `self` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileAttributeInfoList` describing the settable attributes. When you are done with it, release it with `FileAttributeInfoList::unref` 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileAttributeInfoList` describing the writable namespaces. When you are done with it, release it with `FileAttributeInfoList::unref` Opens a file for reading. The result is a `FileInputStream` that can be used to read the contents of the file. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If the file does not exist, the `IOErrorEnum::NotFound` error will be returned. If the file is a directory, the `IOErrorEnum::IsDirectory` error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `cancellable` a `Cancellable` # Returns `FileInputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously opens `self` for reading. For more details, see `File::read` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::read_finish` to get the result of the operation. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file read operation started with `File::read_async`. ## `res` a `AsyncResult` # Returns a `FileInputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `FileCreateFlags::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If you pass in a non-`None` `etag` value and `self` already exists, then this value is compared to the current entity tag of the file, and if they differ an `IOErrorEnum::WrongEtag` error is returned. This generally means that the file has been changed since you last read it. You can get the new etag from `FileOutputStreamExt::get_etag` after you've finished writing and closed the `FileOutputStream`. When you load a new file you can use `FileInputStreamExt::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 `IOErrorEnum::CantCreateBackup` 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 `IOErrorEnum::IsDirectory` error will be returned, and if the file is some other form of non-regular file then a `IOErrorEnum::NotRegularFile` error will be returned. Some file systems don't allow all file names, and may return an `IOErrorEnum::InvalidFilename` error, and if the name is to long `IOErrorEnum::FilenameTooLong` will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. ## `etag` an optional [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileOutputStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously overwrites the file, replacing the contents, possibly creating a backup copy of the file first. For more details, see `File::replace` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::replace_finish` to get the result of the operation. ## `etag` an [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Replaces the contents of `self` with `contents` of `length` bytes. If `etag` is specified (not `None`), any existing file must have that etag, or the error `IOErrorEnum::WrongEtag` will be returned. If `make_backup` is `true`, this function will attempt to make a backup of `self`. Internally, it uses `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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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. ## `contents` a string containing the new contents for `self` ## `length` the length of `contents` in bytes ## `etag` the old [entity-tag][gfile-etag] for the document, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `new_etag` a location to a new [entity tag][gfile-etag] for the document. This should be freed with `g_free` when no longer needed, or `None` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if successful. If an error has occurred, this function will return `false` and set `error` appropriately if present. Starts an asynchronous replacement of `self` 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 `File::replace_contents_finish`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If `make_backup` is `true`, this function will attempt to make a backup of `self`. Note that no copy of `content` will be made, so it must stay valid until `callback` is called. See `File::replace_contents_bytes_async` for a `glib::Bytes` version that will automatically hold a reference to the contents (without copying) for the duration of the call. ## `contents` string of contents to replace the file with ## `length` the length of `contents` in bytes ## `etag` a new [entity tag][gfile-etag] for the `self`, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Same as `File::replace_contents_async` but takes a `glib::Bytes` input instead. This function will keep a ref on `contents` until the operation is done. Unlike `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 `File::replace_contents_finish`. ## `contents` a `glib::Bytes` ## `etag` a new [entity tag][gfile-etag] for the `self`, or `None` ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous replace of the given `self`. See `File::replace_contents_async`. Sets `new_etag` to the new entity tag for the document, if present. ## `res` a `AsyncResult` ## `new_etag` a location of a new [entity tag][gfile-etag] for the document. This should be freed with `g_free` when it is no longer needed, or `None` # Returns `true` on success, `false` on failure. Finishes an asynchronous file replace operation started with `File::replace_async`. ## `res` a `AsyncResult` # Returns a `FileOutputStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. 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 `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. ## `etag` an optional [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `FileIOStream` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously overwrites the file in read-write mode, replacing the contents, possibly creating a backup copy of the file first. For more details, see `File::replace_readwrite` which is the synchronous version of this call. When the operation is finished, `callback` will be called. You can then call `File::replace_readwrite_finish` to get the result of the operation. ## `etag` an [entity tag][gfile-etag] for the current `File`, or `None` to ignore ## `make_backup` `true` if a backup should be created ## `flags` a set of `FileCreateFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file replace operation started with `File::replace_readwrite_async`. ## `res` a `AsyncResult` # Returns a `FileIOStream`, or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Resolves a relative path for `self` to an absolute path. This call does no blocking I/O. ## `relative_path` a given relative path string # Returns `File` to the resolved path. `None` if `relative_path` is `None` or if `self` is invalid. Free the returned object with `gobject::ObjectExt::unref`. Sets an attribute in the file with attribute name `attribute` to `value`. Some attributes can be unset by setting `type_` to `FileAttributeType::Invalid` and `value_p` to `None`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `type_` The type of the attribute ## `value_p` a pointer to the value (or the pointer itself if the type is a pointer type) ## `flags` a set of `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the attribute was set, `false` otherwise. Sets `attribute` of type `FileAttributeType::ByteString` to `value`. If `attribute` is of a different type, this operation will fail, returning `false`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a string containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Int32` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `gint32` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Int64` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint64` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set, `false` otherwise. Sets `attribute` of type `FileAttributeType::String` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a string containing the attribute's value ## `flags` `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set, `false` otherwise. Sets `attribute` of type `FileAttributeType::Uint32` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint32` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Sets `attribute` of type `FileAttributeType::Uint64` to `value`. If `attribute` is of a different type, this operation will fail. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `attribute` a string containing the attribute's name ## `value` a `guint64` containing the attribute's new value ## `flags` a `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` if the `attribute` was successfully set to `value` in the `self`, `false` otherwise. Asynchronously sets the attributes of `self` with `info`. For more details, see `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 `File::set_attributes_finish` to get the result of the operation. ## `info` a `FileInfo` ## `flags` a `FileQueryInfoFlags` ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` ## `user_data` a `gpointer` Finishes setting an attribute started in `File::set_attributes_async`. ## `result` a `AsyncResult` ## `info` a `FileInfo` # Returns `true` if the attributes were set correctly, `false` otherwise. Tries to set all attributes in the `FileInfo` 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 `FileAttributeStatus::ErrorSetting`, which means you can also detect further errors. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `info` a `FileInfo` ## `flags` `FileQueryInfoFlags` ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `false` if there was any error, `true` otherwise. Renames `self` 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 `self` 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 `File::set_display_name`. On success the resulting converted filename is returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `display_name` a string ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `File` specifying what `self` was renamed to, or `None` if there was an error. Free the returned object with `gobject::ObjectExt::unref`. Asynchronously sets the display name for a given `File`. For more details, see `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 `File::set_display_name_finish` to get the result of the operation. ## `display_name` a string ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes setting a display name started with `File::set_display_name_async`. ## `res` a `AsyncResult` # Returns a `File` or `None` on error. Free the returned object with `gobject::ObjectExt::unref`. Starts a file of type `FileType::Mountable`. Using `start_operation`, you can request callbacks when, for instance, passwords are needed during authentication. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::mount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `start_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes a start operation. See `File::start_mountable` for details. Finish an asynchronous start operation that was started with `File::start_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Stops a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::stop_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an stop operation, see `File::stop_mountable` for details. Finish an asynchronous stop operation that was started with `File::stop_mountable`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Checks if `self` supports [thread-default contexts][g-main-context-push-thread-default-context]. If this returns `false`, you cannot perform asynchronous operations on `self` in a thread that has a thread-default context. # Returns Whether or not `self` supports thread-default contexts. Sends `self` 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 `IOErrorEnum::NotSupported` error. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on successful trash, `false` otherwise. Asynchronously sends `self` to the Trash location, if possible. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous file trashing operation, started with `File::trash_async`. ## `result` a `AsyncResult` # Returns `true` on successful trash, `false` otherwise. Unmounts a file of type `FileType::Mountable`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. When the operation is finished, `callback` will be called. You can then call `File::unmount_mountable_finish` to get the result of the operation. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation`, or `None` to avoid user interaction ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied, or `None` ## `user_data` the data to pass to callback function Finishes an unmount operation, see `File::unmount_mountable_with_operation` for details. Finish an asynchronous unmount operation that was started with `File::unmount_mountable_with_operation`. ## `result` a `AsyncResult` # Returns `true` if the operation finished successfully. `false` otherwise. Determines if a string matches a file attribute. Creates a new file attribute matcher, which matches attributes against a given string. `GFileAttributeMatchers` are reference counted structures, and are created with a reference count of 1. If the number of references falls to 0, the `FileAttributeMatcher` is automatically destroyed. The `attribute` string should be formatted with specific keys separated from namespaces with a double colon. Several "namespace::key" strings may be concatenated with a single comma (e.g. "standard::type,standard::is-hidden"). The wildcard "*" may be used to match all keys and namespaces, or "namespace::*" will match all keys in a given namespace. ## Examples of file attribute matcher strings and results - `"*"`: matches all attributes. - `"standard::is-hidden"`: matches only the key is-hidden in the standard namespace. - `"standard::type,unix::*"`: matches the type key in the standard namespace and all keys in the unix namespace. ## `attributes` an attribute string to match. # Returns a `FileAttributeMatcher` 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. ## `ns` a string containing a file attribute namespace. # Returns `true` if the matcher matches all of the entries in the given `ns`, `false` otherwise. Gets the next matched attribute from a `FileAttributeMatcher`. # Returns a string containing the next attribute or `None` if no more attribute exist. 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`. ## `attribute` a file attribute key. # Returns `true` if `attribute` matches `self`. `false` otherwise. Checks if a attribute matcher only matches a given attribute. Always returns `false` if "*" was used when creating the matcher. ## `attribute` a file attribute key. # Returns `true` if the matcher only matches `attribute`. `false` otherwise. References a file attribute matcher. # Returns a `FileAttributeMatcher`. Subtracts all attributes of `subtract` from `self` and returns a matcher that supports those attributes. Note that currently it is not possible to remove a single attribute when the `self` 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. ## `subtract` The matcher to subtract # Returns A file attribute matcher matching all attributes of `self` that are not matched by `subtract` Prints what the matcher is matching against. The format will be equal to the format passed to `FileAttributeMatcher::new`. The output however, might not be identical, as the matcher may decide to use a different order or omit needless parts. # Returns a string describing the attributes the matcher matches against or `None` if `self` was `None`. Unreferences `self`. If the reference count falls below 1, the `self` is automatically freed. Used by `File::set_attributes_from_info` when setting file attributes. Attribute value is unset (empty). Attribute value is set. Indicates an error in setting the value. The data types for file attributes. indicates an invalid or uninitalized type. a null terminated UTF8 string. a zero terminated string of non-zero bytes. a boolean value. an unsigned 4-byte/32-bit integer. a signed 4-byte/32-bit integer. an unsigned 8-byte/64-bit integer. a signed 8-byte/64-bit integer. a `gobject::Object`. a `None` terminated char **. Since 2.22 GFileIOStream provides io streams that both read and write to the same file handle. GFileIOStream implements `Seekable`, which allows the io 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 io stream, use `Seekable::tell`. To find out if a file io stream supports seeking, use `Seekable::can_seek`. To position a file io stream, use `Seekable::seek`. To find out if a file io stream supports truncating, use `Seekable::can_truncate`. To truncate a file io stream, use `Seekable::truncate`. The default implementation of all the `FileIOStream` operations and the implementation of `Seekable` just call into the same operations on the output stream. # Implements [`FileIOStreamExt`](trait.FileIOStreamExt.html), [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html) Trait containing all `FileIOStream` methods. # Implementors [`FileIOStream`](struct.FileIOStream.html) 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. # Returns the entity tag for the stream. Queries a file io stream for the given `attributes`. This function blocks while querying the stream. For the asynchronous version of this function, see `FileIOStreamExt::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 `IOErrorEnum::Pending`. Can fail if the stream was already closed (with `error` being set to `IOErrorEnum::Closed`), the stream has pending operations (with `error` being set to `IOErrorEnum::Pending`), or if querying info is not supported for the stream's interface (with `error` being set to `IOErrorEnum::NotSupported`). I all cases of failure, `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set, and `None` will be returned. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo` for the `self`, or `None` on error. Asynchronously queries the `self` for a `FileInfo`. When completed, `callback` will be called with a `AsyncResult` which can be used to finish the operation with `FileIOStreamExt::query_info_finish`. For the synchronous version of this function, see `FileIOStreamExt::query_info`. ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][gio-GIOScheduler] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finalizes the asynchronous query started by `FileIOStreamExt::query_info_async`. ## `result` a `AsyncResult`. # Returns A `FileInfo` for the finished query. `FileIcon` specifies an icon by pointing to an image file to be used as icon. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`IconExt`](trait.IconExt.html), [`LoadableIconExt`](trait.LoadableIconExt.html) Creates a new icon for a file. ## `file` a `File`. # Returns a `Icon` for the given `file`, or `None` on error. Gets the `File` associated with the given `self`. # Returns a `File`, or `None`. The file containing the icon. The file containing the icon. Functionality for manipulating basic metadata for files. `FileInfo` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. See [GFileAttribute][gio-GFileAttribute] for more information on how GIO handles file attributes. To obtain a `FileInfo` for a `File`, use `File::query_info` (or its async variant). To obtain a `FileInfo` for a file input or output stream, use `FileInputStreamExt::query_info` or `FileOutputStreamExt::query_info` (or their async variants). To change the actual attributes of a file, you should then set the attribute in the `FileInfo` and call `File::set_attributes_from_info` or `File::set_attributes_async` 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 `FileInfo::set_size`. You may call `File::query_settable_attributes` and `File::query_writable_namespaces` to discover the settable attributes of a particular file at runtime. `FileAttributeMatcher` allows for searching through a `FileInfo` for attributes. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new file info structure. # Returns a `FileInfo`. Clears the status information from `self`. First clears all of the [GFileAttribute][gio-GFileAttribute] of `dest_info`, and then copies all of the file attributes from `self` to `dest_info`. ## `dest_info` destination to copy attributes to. Duplicates a file info structure. # Returns a duplicate `FileInfo` of `self`. Gets the value of a attribute, formated as a string. This escapes things as needed to make the string valid utf8. ## `attribute` a file attribute key. # Returns a UTF-8 string associated with the given `attribute`. When you're done with the string it must be freed with `g_free`. Gets the value of a boolean attribute. If the attribute does not contain a boolean value, `false` will be returned. ## `attribute` a file attribute key. # Returns the boolean value contained within the attribute. Gets the value of a byte string attribute. If the attribute does not contain a byte string, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a byte string, or `None` otherwise. Gets the attribute type, value and status for an attribute key. ## `attribute` a file attribute key ## `type_` return location for the attribute type, or `None` ## `value_pp` return location for the attribute value, or `None`; the attribute value will not be `None` ## `status` return location for the attribute status, or `None` # Returns `true` if `self` has an attribute named `attribute`, `false` otherwise. 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. ## `attribute` a file attribute key. # Returns a signed 32-bit integer from the attribute. Gets a signed 64-bit integer contained within the attribute. If the attribute does not contain an signed 64-bit integer, or is invalid, 0 will be returned. ## `attribute` a file attribute key. # Returns a signed 64-bit integer from the attribute. Gets the value of a `gobject::Object` attribute. If the attribute does not contain a `gobject::Object`, `None` will be returned. ## `attribute` a file attribute key. # Returns a `gobject::Object` associated with the given `attribute`, or `None` otherwise. Gets the attribute status for an attribute key. ## `attribute` a file attribute key # Returns a `FileAttributeStatus` for the given `attribute`, or `FileAttributeStatus::Unset` if the key is invalid. Gets the value of a string attribute. If the attribute does not contain a string, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a UTF-8 string, or `None` otherwise. Gets the value of a stringv attribute. If the attribute does not contain a stringv, `None` will be returned. ## `attribute` a file attribute key. # Returns the contents of the `attribute` value as a stringv, or `None` otherwise. Do not free. These returned strings are UTF-8. Gets the attribute type for an attribute key. ## `attribute` a file attribute key. # Returns a `FileAttributeType` for the given `attribute`, or `FileAttributeType::Invalid` if the key is not set. 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. ## `attribute` a file attribute key. # Returns an unsigned 32-bit integer from the attribute. 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. ## `attribute` a file attribute key. # Returns a unsigned 64-bit integer from the attribute. Gets the file's content type. # Returns a string containing the file's content type. Returns the `glib::DateTime` 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, `None` is returned. # Returns a `glib::DateTime`, or `None`. Gets a display name for a file. # Returns a string containing the display name. Gets the edit name for a file. # Returns a string containing the edit name. Gets the [entity tag][gfile-etag] for a given `FileInfo`. See `G_FILE_ATTRIBUTE_ETAG_VALUE`. # Returns a string containing the value of the "etag:value" attribute. Gets a file's type (whether it is a regular file, symlink, etc). This is different from the file's content type, see `FileInfo::get_content_type`. # Returns a `FileType` for the given file. Gets the icon for a file. # Returns `Icon` for the given `self`. Checks if a file is a backup file. # Returns `true` if file is a backup file, `false` otherwise. Checks if a file is hidden. # Returns `true` if the file is a hidden file, `false` otherwise. Checks if a file is a symlink. # Returns `true` if the given `self` is a symlink. Gets the modification time of the current `self` and sets it in `result`. ## `result` a `glib::TimeVal`. Gets the name for a file. # Returns a string containing the file name. Gets the file's size. # Returns a `goffset` containing the file's size. Gets the value of the sort_order attribute from the `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. # Returns a `gint32` containing the value of the "standard::sort_order" attribute. Gets the symbolic icon for a file. # Returns `Icon` for the given `self`. Gets the symlink target for a given `FileInfo`. # Returns a string containing the symlink target. Checks if a file info structure has an attribute named `attribute`. ## `attribute` a file attribute key. # Returns `true` if `Ginfo` has an attribute named `attribute`, `false` otherwise. Checks if a file info structure has an attribute in the specified `name_space`. ## `name_space` a file attribute namespace. # Returns `true` if `Ginfo` has an attribute in `name_space`, `false` otherwise. Lists the file info structure's attributes. ## `name_space` a file attribute key's namespace, or `None` to list all attributes. # Returns a null-terminated array of strings of all of the possible attribute types for the given `name_space`, or `None` on error. Removes all cases of `attribute` from `self` if it exists. ## `attribute` a file attribute key. Sets the `attribute` to contain the given value, if possible. To unset the attribute, use `FileAttributeType::Invalid` for `type_`. ## `attribute` a file attribute key. ## `type_` a `FileAttributeType` ## `value_p` pointer to the value Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a boolean value. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a byte string. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a signed 32-bit integer Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` attribute name to set. ## `attr_value` int64 value to set attribute to. Sets `mask` on `self` to match specific attribute types. ## `mask` a `FileAttributeMatcher`. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a `gobject::Object`. Sets the attribute status for an attribute key. This is only needed by external code that implement `File::set_attributes_from_info` or similar functions. The attribute must exist in `self` for this to work. Otherwise `false` is returned and `self` is unchanged. ## `attribute` a file attribute key ## `status` a `FileAttributeStatus` # Returns `true` if the status was changed, `false` if the key was not set. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` a UTF-8 string. Sets the `attribute` to contain the given `attr_value`, if possible. Sinze: 2.22 ## `attribute` a file attribute key ## `attr_value` a `None` terminated array of UTF-8 strings. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` an unsigned 32-bit integer. Sets the `attribute` to contain the given `attr_value`, if possible. ## `attribute` a file attribute key. ## `attr_value` an unsigned 64-bit integer. Sets the content type attribute for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE`. ## `content_type` a content type. See [GContentType][gio-GContentType] Sets the display name for the current `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME`. ## `display_name` a string containing a display name. Sets the edit name for the current file. See `G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME`. ## `edit_name` a string containing an edit name. Sets the file type in a `FileInfo` to `type_`. See `G_FILE_ATTRIBUTE_STANDARD_TYPE`. ## `type_` a `FileType`. Sets the icon for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_ICON`. ## `icon` a `Icon`. Sets the "is_hidden" attribute in a `FileInfo` according to `is_hidden`. See `G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN`. ## `is_hidden` a `gboolean`. Sets the "is_symlink" attribute in a `FileInfo` according to `is_symlink`. See `G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK`. ## `is_symlink` a `gboolean`. Sets the `G_FILE_ATTRIBUTE_TIME_MODIFIED` attribute in the file info to the given time value. ## `mtime` a `glib::TimeVal`. Sets the name attribute for the current `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_NAME`. ## `name` a string containing a name. Sets the `G_FILE_ATTRIBUTE_STANDARD_SIZE` attribute in the file info to the given size. ## `size` a `goffset` containing the file's size. Sets the sort order attribute in the file info structure. See `G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER`. ## `sort_order` a sort order integer. Sets the symbolic icon for a given `FileInfo`. See `G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON`. ## `icon` a `Icon`. Sets the `G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET` attribute in the file info to the given symlink target. ## `symlink_target` a static string containing a path to a symlink target. Unsets a mask set by `FileInfo::set_attribute_mask`, if one is set. GFileInputStream provides input streams that take their content from a file. GFileInputStream implements `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 `Seekable::tell`. To find out if a file input stream supports seeking, use `Seekable::can_seek`. To position a file input stream, use `Seekable::seek`. # Implements [`FileInputStreamExt`](trait.FileInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `FileInputStream` methods. # Implementors [`FileInputStream`](struct.FileInputStream.html) 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 `FileInputStreamExt::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 `IOErrorEnum::Pending`. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo`, or `None` on error. Queries the stream information asynchronously. When the operation is finished `callback` will be called. You can then call `FileInputStreamExt::query_info_finish` to get the result of the operation. For the synchronous version of this function, see `FileInputStreamExt::query_info`. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous info query operation. ## `result` a `AsyncResult`. # Returns `FileInfo`. Monitors a file or directory for changes. To obtain a `FileMonitor` for a file or directory, use `File::monitor`, `File::monitor_file`, or `File::monitor_directory`. To get informed about changes to the file or directory you are monitoring, connect to the `FileMonitor::changed` signal. The signal will be emitted in the [thread-default main context][g-main-context-push-thread-default] 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). # Implements [`FileMonitorExt`](trait.FileMonitorExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `FileMonitor` methods. # Implementors [`FileMonitor`](struct.FileMonitor.html) Cancels a file monitor. # Returns always `true` Emits the `FileMonitor::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. ## `child` a `File`. ## `other_file` a `File`. ## `event_type` a set of `FileMonitorEvent` flags. Returns whether the monitor is canceled. # Returns `true` if monitor is canceled. `false` otherwise. Sets the rate limit to which the `self` will report consecutive change events to the same file. ## `limit_msecs` a non-negative integer with the limit in milliseconds to poll for changes Emitted when `file` has been changed. If using `FileMonitorFlags::WatchMoves` on a directory monitor, and the information is available (and if supported by the backend), `event_type` may be `FileMonitorEvent::Renamed`, `FileMonitorEvent::MovedIn` or `FileMonitorEvent::MovedOut`. 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 `FileMonitorEvent::MovedIn` as equivalent to `FileMonitorEvent::Created` and `FileMonitorEvent::MovedOut` as equivalent to `FileMonitorEvent::Deleted`, with extra information. `FileMonitorEvent::Renamed` is equivalent to a delete/create pair. This is exactly how the events will be reported in the case that the `FileMonitorFlags::WatchMoves` flag is not in use. If using the deprecated flag `FileMonitorFlags::SendMoved` flag and `event_type` is `FileMonitorEvent::Moved`, `file` will be set to a `File` containing the old path, and `other_file` will be set to a `File` containing the new path. In all the other cases, `other_file` will be set to `None`. ## `file` a `File`. ## `other_file` a `File` or `None`. ## `event_type` a `FileMonitorEvent`. Specifies what type of event a monitor event is. a file changed. a hint that this was probably the last change in a set of changes. a file was deleted. a file was created. a file attribute was changed. the file location will soon be unmounted. the file location was unmounted. the file was moved -- only sent if the (deprecated) `FileMonitorFlags::SendMoved` flag is set the file was renamed within the current directory -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46. the file was moved into the monitored directory from another location -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46. the file was moved out of the monitored directory to another location -- only sent if the `FileMonitorFlags::WatchMoves` flag is set. Since: 2.46 GFileOutputStream provides output streams that write their content to a file. GFileOutputStream implements `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 `Seekable::tell`. To find out if a file output stream supports seeking, use `Seekable::can_seek`.To position a file output stream, use `Seekable::seek`. To find out if a file output stream supports truncating, use `Seekable::can_truncate`. To truncate a file output stream, use `Seekable::truncate`. # Implements [`FileOutputStreamExt`](trait.FileOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `FileOutputStream` methods. # Implementors [`FileOutputStream`](struct.FileOutputStream.html) 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. # Returns the entity tag for the stream. Queries a file output stream for the given `attributes`. This function blocks while querying the stream. For the asynchronous version of this function, see `FileOutputStreamExt::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 `IOErrorEnum::Pending`. Can fail if the stream was already closed (with `error` being set to `IOErrorEnum::Closed`), the stream has pending operations (with `error` being set to `IOErrorEnum::Pending`), or if querying info is not supported for the stream's interface (with `error` being set to `IOErrorEnum::NotSupported`). In all cases of failure, `None` will be returned. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be set, and `None` will be returned. ## `attributes` a file attribute query string. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `FileInfo` for the `self`, or `None` on error. Asynchronously queries the `self` for a `FileInfo`. When completed, `callback` will be called with a `AsyncResult` which can be used to finish the operation with `FileOutputStreamExt::query_info_finish`. For the synchronous version of this function, see `FileOutputStreamExt::query_info`. ## `attributes` a file attribute query string. ## `io_priority` the [I/O priority][gio-GIOScheduler] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finalizes the asynchronous query started by `FileOutputStreamExt::query_info_async`. ## `result` a `AsyncResult`. # Returns A `FileInfo` for the finished query. Indicates the file's on-disk type. File's type is unknown. File handle represents a regular file. File handle represents a directory. File handle represents a symbolic link (Unix systems). File is a "special" file, such as a socket, fifo, block device, or character device. File is a shortcut (Windows systems). File is a mountable location. 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. # Implements [`FilenameCompleterExt`](trait.FilenameCompleterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `FilenameCompleter` methods. # Implementors [`FilenameCompleter`](struct.FilenameCompleter.html) Creates a new filename completer. # Returns a `FilenameCompleter`. Obtains a completion for `initial_text` from `self`. ## `initial_text` text to be completed. # Returns a completed string, or `None` if no completion exists. This string is not owned by GIO, so remember to `g_free` it when finished. Gets an array of completion strings for a given initial text. ## `initial_text` text to be completed. # Returns array of strings with possible completions for `initial_text`. This array must be freed by `g_strfreev` when finished. If `dirs_only` is `true`, `self` will only complete directory names, and not file names. ## `dirs_only` a `gboolean`. Emitted when the file name completion information comes available. 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. # Implements [`FilterInputStreamExt`](trait.FilterInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `FilterInputStream` methods. # Implementors [`BufferedInputStream`](struct.BufferedInputStream.html), [`ConverterInputStream`](struct.ConverterInputStream.html), [`FilterInputStream`](struct.FilterInputStream.html) Gets the base stream for the filter stream. # Returns a `InputStream`. Returns whether the base stream will be closed when `self` is closed. # Returns `true` if the base stream will be closed. Sets whether the base stream will be closed when `self` is closed. ## `close_base` `true` to close the base stream. 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. # Implements [`FilterOutputStreamExt`](trait.FilterOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `FilterOutputStream` methods. # Implementors [`BufferedOutputStream`](struct.BufferedOutputStream.html), [`ConverterOutputStream`](struct.ConverterOutputStream.html), [`DataOutputStream`](struct.DataOutputStream.html), [`FilterOutputStream`](struct.FilterOutputStream.html) Gets the base stream for the filter stream. # Returns a `OutputStream`. Returns whether the base stream will be closed when `self` is closed. # Returns `true` if the base stream will be closed. Sets whether the base stream will be closed when `self` is closed. ## `close_base` `true` to close the base stream. 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 `IOErrorEnum::Failed` in cases that were not explicitly distinguished before. You should therefore avoid writing code like ```C 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 `IOErrorEnum::Failed`. Generic error condition for when an operation fails and no more specific `IOErrorEnum` value is defined. File not found. File already exists. File is a directory. File is not a directory. File is a directory that isn't empty. File is not a regular file. File is not a symbolic link. File cannot be mounted. Filename is too many characters. Filename is invalid or contains invalid characters. File contains too many symbolic links. No space left on drive. Invalid argument. Permission denied. Operation (or one of its parameters) not supported File isn't mounted. File is already mounted. File was closed. Operation was cancelled. See `Cancellable`. Operations are still pending. File is read only. Backup couldn't be created. File's Entity Tag was incorrect. Operation timed out. Operation would be recursive. File is busy. Operation would block. Host couldn't be found (remote operations). Operation would merge files. Operation failed and a helper program has already interacted with the user. Do not display any error dialog. The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 The object has not been initialized. Since 2.22 The requested address is already in use. Since 2.22 Need more input to finish operation. Since 2.24 The input data was invalid. Since 2.24 A remote object generated an error that doesn't correspond to a locally registered `glib::Error` error domain. Use `DBusError::get_remote_error` to extract the D-Bus error name and `DBusError::strip_remote_error` to fix up the message so it matches what was received on the wire. Since 2.26. Host unreachable. Since 2.26 Network unreachable. Since 2.26 Connection refused. Since 2.26 Connection to proxy server failed. Since 2.26 Proxy authentication failed. Since 2.26 Proxy server needs authentication. Since 2.26 Proxy connection is not allowed by ruleset. Since 2.26 Broken pipe. Since 2.36 Connection closed by peer. Note that this is the same code as `IOErrorEnum::BrokenPipe`; before 2.44 some "connection closed" errors returned `IOErrorEnum::BrokenPipe`, but others returned `IOErrorEnum::Failed`. Now they should all return the same value, which has this more logical name. Since 2.44. Transport endpoint is not connected. Since 2.44 Message too large. Since 2.48. 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 `IOStream` objects are `SocketConnection`, which represents a two-way network connection; and `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 `IOStreamExt::get_input_stream` and `IOStreamExt::get_output_stream`. The `IOStream` object owns the input and the output streams, not the other way around, so keeping the substreams alive will not keep the `IOStream` object alive. If the `IOStream` object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will always return `IOErrorEnum::Closed` for all operations. To close a stream use `IOStreamExt::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 `IOStream` 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 `IOStream` or its substreams is in progress. Specifically, an application can read from the `InputStream` and write to the `OutputStream` simultaneously (either in separate threads, or as asynchronous operations in the same thread), but an application cannot start any `IOStream` operation while there is a `IOStream`, `InputStream` or `OutputStream` operation in progress, and an application can’t start any `InputStream` or `OutputStream` operation while there is a `IOStream` 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 `glib::MainContext`. 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 `BufferedInputStream` or `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). # Implements [`IOStreamExt`](trait.IOStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `IOStream` methods. # Implementors [`FileIOStream`](struct.FileIOStream.html), [`IOStream`](struct.IOStream.html), [`SimpleIOStream`](struct.SimpleIOStream.html), [`SocketConnection`](struct.SocketConnection.html), [`TlsConnection`](struct.TlsConnection.html) Finishes an asynchronous io stream splice operation. ## `result` a `AsyncResult`. # Returns `true` on success, `false` otherwise. Clears the pending flag on `self`. 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 `IOErrorEnum::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 `IOErrorEnum::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 `IOErrorEnum::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. ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns `true` on success, `false` on failure 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 `IOStreamExt::close_finish` to get the result of the operation. For behaviour details see `IOStreamExt::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. ## `io_priority` the io priority of the request ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Closes a stream. ## `result` a `AsyncResult` # Returns `true` if stream was successfully closed, `false` otherwise. Gets the input stream for this object. This is used for reading. # Returns a `InputStream`, owned by the `IOStream`. Do not free. Gets the output stream for this object. This is used for writing. # Returns a `OutputStream`, owned by the `IOStream`. Do not free. Checks if a stream has pending actions. # Returns `true` if `self` has pending actions. Checks if a stream is closed. # Returns `true` if the stream is closed. Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Asyncronously splice the output stream of `self` to the input stream of `stream2`, and splice the output stream of `stream2` to the input stream of `self`. When the operation is finished `callback` will be called. You can then call `IOStream::splice_finish` to get the result of the operation. ## `stream2` a `IOStream`. ## `flags` a set of `IOStreamSpliceFlags`. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`. ## `user_data` user data passed to `callback`. `Icon` 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. `Icon` does not provide the actual pixmap for the icon as this is out of GIO's scope, however implementations of `Icon` may contain the name of an icon (see `ThemedIcon`), or the path to an icon (see `LoadableIcon`). To obtain a hash of a `Icon`, see `Icon::hash`. To check if two `GIcons` are equal, see `Icon::equal`. For serializing a `Icon`, use `Icon::serialize` and `Icon::deserialize`. If you want to consume `Icon` (for example, in a toolkit) you must be prepared to handle at least the three following cases: `LoadableIcon`, `ThemedIcon` and `EmblemedIcon`. It may also make sense to have fast-paths for other cases (like handling ``GdkPixbuf`` directly, for example) but all compliant `Icon` implementations outside of GIO must implement `LoadableIcon`. If your application or library provides one or more `Icon` implementations you need to ensure that your new implementation also implements `LoadableIcon`. Additionally, you must provide an implementation of `Icon::serialize` that gives a result that is understood by `Icon::deserialize`, yielding one of the built-in icon types. # Implements [`IconExt`](trait.IconExt.html) Trait containing all `Icon` methods. # Implementors [`BytesIcon`](struct.BytesIcon.html), [`Emblem`](struct.Emblem.html), [`EmblemedIcon`](struct.EmblemedIcon.html), [`FileIcon`](struct.FileIcon.html), [`Icon`](struct.Icon.html), [`LoadableIcon`](struct.LoadableIcon.html), [`ThemedIcon`](struct.ThemedIcon.html) Deserializes a `Icon` previously serialized using `Icon::serialize`. ## `value` a `glib::Variant` created with `Icon::serialize` # Returns a `Icon`, or `None` when deserialization fails. Gets a hash for an icon. ## `icon` `gconstpointer` to an icon object. # Returns a `guint` containing a hash for the `icon`, suitable for use in a `glib::HashTable` or similar data structure. Generate a `Icon` instance from `str`. This function can fail if `str` is not valid - see `Icon::to_string` for discussion. If your application or library provides one or more `Icon` implementations you need to ensure that each `glib::Type` is registered with the type system prior to calling `Icon::new_for_string`. ## `str` A string obtained via `Icon::to_string`. # Returns An object implementing the `Icon` interface or `None` if `error` is set. Checks if two icons are equal. ## `icon2` pointer to the second `Icon`. # Returns `true` if `self` is equal to `icon2`. `false` otherwise. Serializes a `Icon` into a `glib::Variant`. An equivalent `Icon` can be retrieved back by calling `Icon::deserialize` on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the `glib::Variant` between processes on the same machine, (as opposed to over the network), and within the same file system namespace. # Returns a `glib::Variant`, or `None` when serialization fails. Generates a textual representation of `self` that can be used for serialization such as when passing `self` to a different process or saving it to persistent storage. Use `Icon::new_for_string` to get `self` back from the returned string. The encoding of the returned string is proprietary to `Icon` except in the following two cases - If `self` is a `FileIcon`, the returned string is a native path (such as `/path/to/my icon.png`) without escaping if the `File` for `self` is a native file. If the file is not native, the returned string is the result of `File::get_uri` (such as `sftp://path/to/my%20icon.png`). - If `self` is a `ThemedIcon` with exactly one name and no fallbacks, the encoding is simply the name (such as `network-server`). # Returns An allocated NUL-terminated UTF8 string or `None` if `self` can't be serialized. Use `g_free` to free. `InetAddress` represents an IPv4 or IPv6 internet address. Use `ResolverExt::lookup_by_name` or `ResolverExt::lookup_by_name_async` to look up the `InetAddress` for a hostname. Use `ResolverExt::lookup_by_address` or `ResolverExt::lookup_by_address_async` to look up the hostname for a `InetAddress`. To actually connect to a remote host, you will need a `InetSocketAddress` (which includes a `InetAddress` as well as a port number). # Implements [`InetAddressExt`](trait.InetAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `InetAddress` methods. # Implementors [`InetAddress`](struct.InetAddress.html) Creates a `InetAddress` for the "any" address (unassigned/"don't care") for `family`. ## `family` the address family # Returns a new `InetAddress` corresponding to the "any" address for `family`. Free the returned object with `gobject::ObjectExt::unref`. Creates a new `InetAddress` from the given `family` and `bytes`. `bytes` should be 4 bytes for `SocketFamily::Ipv4` and 16 bytes for `SocketFamily::Ipv6`. ## `bytes` raw address data ## `family` the address family of `bytes` # Returns a new `InetAddress` corresponding to `family` and `bytes`. Free the returned object with `gobject::ObjectExt::unref`. Parses `string` as an IP address and creates a new `InetAddress`. ## `string` a string representation of an IP address # Returns a new `InetAddress` corresponding to `string`, or `None` if `string` could not be parsed. Free the returned object with `gobject::ObjectExt::unref`. Creates a `InetAddress` for the loopback address for `family`. ## `family` the address family # Returns a new `InetAddress` corresponding to the loopback address for `family`. Free the returned object with `gobject::ObjectExt::unref`. Checks if two `InetAddress` instances are equal, e.g. the same address. ## `other_address` Another `InetAddress`. # Returns `true` if `self` and `other_address` are equal, `false` otherwise. Gets `self`'s family # Returns `self`'s family Tests whether `self` is the "any" address for its family. # Returns `true` if `self` is the "any" address for its family. Tests whether `self` is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet). # Returns `true` if `self` is a link-local address. Tests whether `self` is the loopback address for its family. # Returns `true` if `self` is the loopback address for its family. Tests whether `self` is a global multicast address. # Returns `true` if `self` is a global multicast address. Tests whether `self` is a link-local multicast address. # Returns `true` if `self` is a link-local multicast address. Tests whether `self` is a node-local multicast address. # Returns `true` if `self` is a node-local multicast address. Tests whether `self` is an organization-local multicast address. # Returns `true` if `self` is an organization-local multicast address. Tests whether `self` is a site-local multicast address. # Returns `true` if `self` is a site-local multicast address. Tests whether `self` is a multicast address. # Returns `true` if `self` is a multicast address. Tests whether `self` 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). # Returns `true` if `self` is a site-local address. Gets the size of the native raw binary address for `self`. This is the size of the data that you get from `InetAddress::to_bytes`. # Returns the number of bytes used for the native version of `self`. Gets the raw binary address data from `self`. # Returns a pointer to an internal array of the bytes in `self`, which should not be modified, stored, or freed. The size of this array can be gotten with `InetAddressExt::get_native_size`. Converts `self` to string form. # Returns a representation of `self` as a string, which should be freed after use. Whether this is the "any" address for its family. See `InetAddressExt::get_is_any`. Whether this is a link-local address. See `InetAddressExt::get_is_link_local`. Whether this is the loopback address for its family. See `InetAddressExt::get_is_loopback`. Whether this is a global multicast address. See `InetAddressExt::get_is_mc_global`. Whether this is a link-local multicast address. See `InetAddressExt::get_is_mc_link_local`. Whether this is a node-local multicast address. See `InetAddressExt::get_is_mc_node_local`. Whether this is an organization-local multicast address. See `InetAddressExt::get_is_mc_org_local`. Whether this is a site-local multicast address. See `InetAddressExt::get_is_mc_site_local`. Whether this is a multicast address. See `InetAddressExt::get_is_multicast`. Whether this is a site-local address. See `InetAddressExt::get_is_loopback`. `InetAddressMask` 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. Eg, "10.0.0.0/8", or "fe80::/10". # Implements [`InetAddressMaskExt`](trait.InetAddressMaskExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `InetAddressMask` methods. # Implementors [`InetAddressMask`](struct.InetAddressMask.html) Creates a new `InetAddressMask` representing all addresses whose first `length` bits match `addr`. ## `addr` a `InetAddress` ## `length` number of bits of `addr` to use # Returns a new `InetAddressMask`, or `None` on error Parses `mask_string` as an IP address and (optional) length, and creates a new `InetAddressMask`. 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. ## `mask_string` an IP address or address/length string # Returns a new `InetAddressMask` corresponding to `string`, or `None` on error. Tests if `self` and `mask2` are the same mask. ## `mask2` another `InetAddressMask` # Returns whether `self` and `mask2` are the same mask Gets `self`'s base address # Returns `self`'s base address Gets the `SocketFamily` of `self`'s address # Returns the `SocketFamily` of `self`'s address Gets `self`'s length # Returns `self`'s length Tests if `address` falls within the range described by `self`. ## `address` a `InetAddress` # Returns whether `address` falls within the range described by `self`. Converts `self` back to its corresponding string form. # Returns a string corresponding to `self`. An IPv4 or IPv6 socket address; that is, the combination of a `InetAddress` and a port number. # Implements [`InetSocketAddressExt`](trait.InetSocketAddressExt.html), [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `InetSocketAddress` methods. # Implementors [`InetSocketAddress`](struct.InetSocketAddress.html), [`ProxyAddress`](struct.ProxyAddress.html) Creates a new `InetSocketAddress` for `address` and `port`. ## `address` a `InetAddress` ## `port` a port number # Returns a new `InetSocketAddress` Creates a new `InetSocketAddress` for `address` and `port`. If `address` is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). ## `address` the string form of an IP address ## `port` a port number # Returns a new `InetSocketAddress`, or `None` if `address` cannot be parsed. Gets `self`'s `InetAddress`. # Returns the `InetAddress` for `self`, which must be `gobject::ObjectExt::ref`'d if it will be stored Gets the `sin6_flowinfo` field from `self`, which must be an IPv6 address. # Returns the flowinfo field Gets `self`'s port. # Returns the port for `self` Gets the `sin6_scope_id` field from `self`, which must be an IPv6 address. # Returns the scope id field The `sin6_flowinfo` field, for IPv6 addresses. The `sin6_flowinfo` field, for IPv6 addresses. `InputStream` has functions to read from a stream (`InputStream::read`), to close a stream (`InputStreamExt::close`) and to skip some content (`InputStreamExt::skip`). To copy the content of an input stream to an output stream without manually handling the reads and writes, use `OutputStreamExt::splice`. See the documentation for `IOStream` for details of thread safety of streaming APIs. All of these functions have async variants too. # Implements [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `InputStream` methods. # Implementors [`FileInputStream`](struct.FileInputStream.html), [`FilterInputStream`](struct.FilterInputStream.html), [`InputStream`](struct.InputStream.html), [`MemoryInputStream`](struct.MemoryInputStream.html), [`PollableInputStream`](struct.PollableInputStream.html), [`UnixInputStream`](struct.UnixInputStream.html) Clears the pending flag on `self`. Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return `IOErrorEnum::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 `IOErrorEnum::Closed` for all operations. Still, it is important to check and report the error to the user. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` on failure 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 `InputStreamExt::close_finish` to get the result of the operation. For behaviour details see `InputStreamExt::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. ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes closing a stream asynchronously, started from `InputStreamExt::close_async`. ## `result` a `AsyncResult`. # Returns `true` if the stream was closed successfully. Checks if an input stream has pending actions. # Returns `true` if `self` has pending actions. Checks if an input stream is closed. # Returns `true` if the stream is closed. 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 `IOErrorEnum::InvalidArgument` 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns Number of bytes read, or -1 on error, or 0 on end of file. Tries to read `count` bytes from the stream into the buffer starting at `buffer`. Will block during this read. This function is similar to `InputStream::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 `glib::Error`, 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 `InputStream::read`. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `bytes_read` location to store the number of bytes that was read from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` if there was an error Request an asynchronous read of `count` bytes from the stream into the buffer starting at `buffer`. This is the asynchronous equivalent of `InputStream::read_all`. Call `InputStreamExt::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`. Feature: `v2_44` ## `buffer` a buffer to read data into (which should be at least count bytes long) ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream read operation started with `InputStream::read_all_async`. As a special exception to the normal conventions for functions that use `glib::Error`, 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 `InputStream::read_async`. Feature: `v2_44` ## `result` a `AsyncResult` ## `bytes_read` location to store the number of bytes that was read from the stream # Returns `true` on success, `false` if there was an error 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 `InputStreamExt::read_finish` to get the result of the operation. During an async request no other sync and async calls are allowed on `self`, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` 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. ## `buffer` a buffer to read data into (which should be at least count bytes long). ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Like `InputStream::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 `glib::Bytes` containing the data that was read. This may be easier to use from language bindings. If count is zero, returns a zero-length `glib::Bytes` and does nothing. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, a new `glib::Bytes` 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 `glib::Bytes` is returned on end of file (or if `count` is zero), but never otherwise. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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 `None` is returned and `error` is set accordingly. ## `count` maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a new `glib::Bytes`, or `None` on error Request an asynchronous read of `count` bytes from the stream into a new `glib::Bytes`. When the operation is finished `callback` will be called. You can then call `InputStreamExt::read_bytes_finish` to get the result of the operation. During an async request no other sync and async calls are allowed on `self`, and will result in `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` error. On success, the new `glib::Bytes` 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`. ## `count` the number of bytes that will be read from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream read-into-`glib::Bytes` operation. ## `result` a `AsyncResult`. # Returns the newly-allocated `glib::Bytes`, or `None` on error Finishes an asynchronous stream read operation. ## `result` a `AsyncResult`. # Returns number of bytes read in, or -1 on error, or 0 on end of file. Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Tries to skip `count` bytes from the stream. Will block during the operation. This is identical to `InputStream::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. ## `count` the number of bytes that will be skipped from the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns Number of bytes skipped, or -1 on error Request an asynchronous skip of `count` bytes from the stream. When the operation is finished `callback` will be called. You can then call `InputStreamExt::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 `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` 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. ## `count` the number of bytes that will be skipped from the stream ## `io_priority` the [I/O priority][io-priority] of the request ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes a stream skip operation. ## `result` a `AsyncResult`. # Returns the size of the bytes skipped, or %-1 on error. `ListModel` is an interface that represents a mutable list of `GObjects`. 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 `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 `ListModel` 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 `ListModel` are of (or derived from) the same type. `ListModel::get_item_type` returns that type. The type may be an interface, in which case all objects in the list must implement it. The semantics are close to that of an array: `ListModel::get_n_items` returns the number of items in the list and `ListModel::get_item` returns an item at a (0-based) position. In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly call `ListModel::get_item` until it returns `None`. An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on objects that are currently "user visible", in order to faciliate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns the [thread-default main context][g-main-context-push-thread-default] in effect at the time that the model was created. Feature: `v2_44` # Implements [`ListModelExt`](trait.ListModelExt.html) Trait containing all `ListModel` methods. Feature: `v2_44` # Implementors [`ListModel`](struct.ListModel.html), [`ListStore`](struct.ListStore.html) Get the item at `position`. If `position` is greater than the number of items in `self`, `None` is returned. `None` is never returned for an index that is smaller than the length of the list. See `ListModel::get_n_items`. Feature: `v2_44` ## `position` the position of the item to fetch # Returns the item at `position`. Gets the type of the items in `self`. All items returned from `g_list_model_get_type` are of that type or a subtype, or are an implementation of that interface. The item type of a `ListModel` can not change during the life of the model. Feature: `v2_44` # Returns the `glib::Type` of the items contained in `self`. Gets the number of items in `self`. Depending on the model implementation, calling this function may be less efficient than iterating the list with increasing values for `position` until `ListModel::get_item` returns `None`. Feature: `v2_44` # Returns the number of items in `self`. Get the item at `position`. If `position` is greater than the number of items in `self`, `None` is returned. `None` is never returned for an index that is smaller than the length of the list. See `ListModel::get_n_items`. Feature: `v2_44` ## `position` the position of the item to fetch # Returns the object at `position`. Emits the `ListModel::items-changed` signal on `self`. This function should only be called by classes implementing `ListModel`. It has to be called after the internal representation of `self` 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 `ListStore`), 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 `ListModel` 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. Feature: `v2_44` ## `position` the position at which `self` changed ## `removed` the number of items removed ## `added` the number of items added This signal is emitted whenever items were added or removed to `list`. At `position`, `removed` items were removed and `added` items were added in their place. Feature: `v2_44` ## `position` the position at which `list` changed ## `removed` the number of items removed ## `added` the number of items added `ListStore` is a simple implementation of `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. Feature: `v2_44` # Implements [`ListStoreExt`](trait.ListStoreExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ListModelExt`](trait.ListModelExt.html), [`ListStoreExtManual`](prelude/trait.ListStoreExtManual.html) Trait containing all `ListStore` methods. Feature: `v2_44` # Implementors [`ListStore`](struct.ListStore.html) Creates a new `ListStore` with items of type `item_type`. `item_type` must be a subclass of `gobject::Object`. Feature: `v2_44` ## `item_type` the `glib::Type` of items in the list # Returns a new `ListStore` Appends `item` to `self`. `item` must be of type `ListStore:item-type`. This function takes a ref on `item`. Use `ListStoreExt::splice` to append multiple items at the same time efficiently. Feature: `v2_44` ## `item` the new item Inserts `item` into `self` at `position`. `item` must be of type `ListStore: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 `ListStoreExt::splice` to insert multiple items at the same time efficiently. Feature: `v2_44` ## `position` the position at which to insert the new item ## `item` the new item Inserts `item` into `self` 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`. Feature: `v2_44` ## `item` the new item ## `compare_func` pairwise comparison function for sorting ## `user_data` user data for `compare_func` # Returns the position at which `item` was inserted Removes the item from `self` that is at `position`. `position` must be smaller than the current length of the list. Use `ListStoreExt::splice` to remove multiple items at the same time efficiently. Feature: `v2_44` ## `position` the position of the item that is to be removed Removes all items from `self`. Feature: `v2_44` Sort the items in `self` according to `compare_func`. Feature: `v2_46` ## `compare_func` pairwise comparison function for sorting ## `user_data` user data for `compare_func` Changes `self` by removing `n_removals` items and adding `n_additions` items to it. `additions` must contain `n_additions` items of type `ListStore:item-type`. `None` is not permitted. This function is more efficient than `ListStoreExt::insert` and `ListStoreExt::remove`, because it only emits `ListModel::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). Feature: `v2_44` ## `position` the position at which to make the change ## `n_removals` the number of items to remove ## `additions` the items to add ## `n_additions` the number of items to add The type of items contained in this list store. Items must be subclasses of `gobject::Object`. Feature: `v2_44` The type of items contained in this list store. Items must be subclasses of `gobject::Object`. Feature: `v2_44` Extends the `Icon` interface and adds the ability to load icons from streams. # Implements [`LoadableIconExt`](trait.LoadableIconExt.html), [`IconExt`](trait.IconExt.html) Trait containing all `LoadableIcon` methods. # Implementors [`BytesIcon`](struct.BytesIcon.html), [`FileIcon`](struct.FileIcon.html), [`LoadableIcon`](struct.LoadableIcon.html) Loads a loadable icon. For the asynchronous version of this function, see `LoadableIcon::load_async`. ## `size` an integer. ## `type_` a location to store the type of the loaded icon, `None` to ignore. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `InputStream` to read the icon from. Loads an icon asynchronously. To finish this function, see `LoadableIcon::load_finish`. For the synchronous, blocking version of this function, see `LoadableIcon::load`. ## `size` an integer. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous icon load started in `LoadableIcon::load_async`. ## `res` a `AsyncResult`. ## `type_` a location to store the type of the loaded icon, `None` to ignore. # Returns a `InputStream` to read the icon from. `MemoryInputStream` is a class for using arbitrary memory chunks as input for GIO streaming input operations. As of GLib 2.34, `MemoryInputStream` implements `PollableInputStream`. # Implements [`MemoryInputStreamExt`](trait.MemoryInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`SeekableExt`](trait.SeekableExt.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html) Trait containing all `MemoryInputStream` methods. # Implementors [`MemoryInputStream`](struct.MemoryInputStream.html) Creates a new empty `MemoryInputStream`. # Returns a new `InputStream` Creates a new `MemoryInputStream` with data from the given `bytes`. ## `bytes` a `glib::Bytes` # Returns new `InputStream` read from `bytes` Creates a new `MemoryInputStream` with data in memory of a given size. ## `data` input data ## `len` length of the data, may be -1 if `data` is a nul-terminated string ## `destroy` function that is called to free `data`, or `None` # Returns new `InputStream` read from `data` of `len` bytes. Appends `bytes` to data that can be read from the input stream. ## `bytes` input data Appends `data` to data that can be read from the input stream ## `data` input data ## `len` length of the data, may be -1 if `data` is a nul-terminated string ## `destroy` function that is called to free `data`, or `None` `MemoryOutputStream` is a class for using arbitrary memory chunks as output for GIO streaming output operations. As of GLib 2.34, `MemoryOutputStream` trivially implements `PollableOutputStream`: it always polls as ready. # Implements [`MemoryOutputStreamExt`](trait.MemoryOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`SeekableExt`](trait.SeekableExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html) Trait containing all `MemoryOutputStream` methods. # Implementors [`MemoryOutputStream`](struct.MemoryOutputStream.html) Creates a new `MemoryOutputStream`. In most cases this is not the function you want. See `MemoryOutputStream::new_resizable` instead. If `data` is non-`None`, the stream will use that for its internal storage. If `realloc_fn` is non-`None`, it will be used for resizing the internal storage when necessary and the stream will be considered resizable. In that case, the stream will start out being (conceptually) empty. `size` is used only as a hint for how big `data` is. Specifically, seeking to the end of a newly-created stream will seek to zero, not `size`. Seeking past the end of the stream and then writing will introduce a zero-filled gap. If `realloc_fn` is `None` then the stream is fixed-sized. Seeking to the end will seek to `size` exactly. Writing past the end will give an 'out of space' error. Attempting to seek past the end will fail. Unlike the resizable case, seeking to an offset within the stream and writing will preserve the bytes passed in as `data` before that point and will return them as part of `MemoryOutputStream::steal_data`. If you intend to seek you should probably therefore ensure that `data` is properly initialised. It is probably only meaningful to provide `data` and `size` in the case that you want a fixed-sized stream. Put another way: if `realloc_fn` is non-`None` then it makes most sense to give `data` as `None` and `size` as 0 (allowing `MemoryOutputStream` to do the initial allocation for itself). ```C // a stream that can grow stream = g_memory_output_stream_new (NULL, 0, realloc, free); // another stream that can grow stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); // a fixed-size stream data = malloc (200); stream3 = g_memory_output_stream_new (data, 200, NULL, free); ``` ## `data` pointer to a chunk of memory to use, or `None` ## `size` the size of `data` ## `realloc_function` a function with `realloc` semantics (like `g_realloc`) to be called when `data` needs to be grown, or `None` ## `destroy_function` a function to be called on `data` when the stream is finalized, or `None` # Returns A newly created `MemoryOutputStream` object. Creates a new `MemoryOutputStream`, using `g_realloc` and `g_free` for memory allocation. Gets any loaded data from the `self`. Note that the returned pointer may become invalid on the next write or truncate operation on the stream. # Returns pointer to the stream's data, or `None` if the data has been stolen Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. # Returns the number of bytes written to the stream Gets the size of the currently allocated data area (available from `MemoryOutputStream::get_data`). You probably don't want to use this function on resizable streams. See `MemoryOutputStreamExt::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 `MemoryOutputStream::new`) then this is the maximum size of the stream and further writes will return `IOErrorEnum::NoSpace`. In any case, if you want the number of bytes currently written to the stream, use `MemoryOutputStreamExt::get_data_size`. # Returns the number of bytes allocated for the data buffer Returns data from the `self` as a `glib::Bytes`. `self` must be closed before calling this function. # Returns the stream's data Gets any loaded data from the `self`. Ownership of the data is transferred to the caller; when no longer needed it must be freed using the free function set in `self`'s `MemoryOutputStream:destroy-function` property. `self` must be closed before calling this function. # Returns the stream's data, or `None` if it has previously been stolen Pointer to buffer where data will be written. Pointer to buffer where data will be written. Size of data written to the buffer. Function called with the buffer as argument when the stream is destroyed. Function called with the buffer as argument when the stream is destroyed. Function with realloc semantics called to enlarge the buffer. Function with realloc semantics called to enlarge the buffer. Current size of the data buffer. Current size of the data buffer. `Menu` is a simple implementation of `MenuModel`. You populate a `Menu` by adding `MenuItem` instances to it. There are some convenience functions to allow you to directly add items (avoiding `MenuItem`) for the common cases. To add a regular item, use `Menu::insert`. To add a section, use `Menu::insert_section`. To add a submenu, use `Menu::insert_submenu`. # Implements [`MenuModelExt`](trait.MenuModelExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Menu`. The new menu has no items. # Returns a new `Menu` Convenience function for appending a normal menu item to the end of `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Appends `item` to the end of `self`. See `Menu::insert_item` for more information. ## `item` a `MenuItem` to append Convenience function for appending a section menu item to the end of `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for appending a submenu menu item to the end of `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu Marks `self` 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 `Menu` API must no longer be used. This function causes `MenuModelExt::is_mutable` to begin returning `false`, which has some positive performance implications. Convenience function for inserting a normal menu item into `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Inserts `item` into `self`. 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 `self`. 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 `Menu::insert`, `Menu::insert_section` and `Menu::insert_submenu` as well as "prepend" and "append" variants of each of these functions. ## `position` the position at which to insert the item ## `item` the `MenuItem` to insert Convenience function for inserting a section menu item into `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for inserting a submenu menu item into `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `position` the position at which to insert the item ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu Convenience function for prepending a normal menu item to the start of `self`. Combine `MenuItem::new` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` Prepends `item` to the start of `self`. See `Menu::insert_item` for more information. ## `item` a `MenuItem` to prepend Convenience function for prepending a section menu item to the start of `self`. Combine `MenuItem::new_section` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section Convenience function for prepending a submenu menu item to the start of `self`. Combine `MenuItem::new_submenu` and `Menu::insert_item` for a more flexible alternative. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu 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). ## `position` the position of the item to remove Removes all items in the menu. `MenuAttributeIter` is an opaque structure type. You must access it using the functions below. # Implements [`MenuAttributeIterExt`](trait.MenuAttributeIterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuAttributeIter` methods. # Implementors [`MenuAttributeIter`](struct.MenuAttributeIter.html) Gets the name of the attribute at the current iterator position, as a string. The iterator is not advanced. # Returns the name of the attribute This function combines `MenuAttributeIterExt::next` with `MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::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, `MenuAttributeIterExt::get_name` and `MenuAttributeIterExt::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 `glib::Variant::unref` when it is no longer in use. ## `out_name` the type of the attribute ## `value` the attribute value # Returns `true` on success, or `false` if there is no additional attribute Gets the value of the attribute at the current iterator position. The iterator is not advanced. # Returns the value of the current attribute 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). # Returns `true` on success, or `false` when there are no more attributes `MenuItem` is an opaque structure type. You must access it using the functions below. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `MenuItem`. If `label` is non-`None` it is used to set the "label" attribute of the new item. If `detailed_action` is non-`None` it is used to set the "action" and possibly the "target" attribute of the new item. See `MenuItem::set_detailed_action` for more information. ## `label` the section label, or `None` ## `detailed_action` the detailed action string, or `None` # Returns a new `MenuItem` Creates a `MenuItem` as an exact copy of an existing menu item in a `MenuModel`. `item_index` must be valid (ie: be sure to call `MenuModelExt::get_n_items` first). ## `model` a `MenuModel` ## `item_index` the index of an item in `model` # Returns a new `MenuItem`. Creates a new `MenuItem` representing a section. This is a convenience API around `MenuItem::new` and `MenuItem::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-`None` 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 `Menu` 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: ```text ``` 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). ```text ``` ## `label` the section label, or `None` ## `section` a `MenuModel` with the items of the section # Returns a new `MenuItem` Creates a new `MenuItem` representing a submenu. This is a convenience API around `MenuItem::new` and `MenuItem::set_submenu`. ## `label` the section label, or `None` ## `submenu` a `MenuModel` with the items of the submenu # Returns a new `MenuItem` Queries the named `attribute` on `self`. If the attribute exists and matches the `glib::VariantType` corresponding to `format_string` then `format_string` is used to deconstruct the value into the positional parameters and `true` is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and `false` is returned. ## `attribute` the attribute name to query ## `format_string` a `glib::Variant` format string # Returns `true` if the named attribute was found with the expected type Queries the named `attribute` on `self`. If `expected_type` is specified and the attribute does not have this type, `None` is returned. `None` is also returned if the attribute simply does not exist. ## `attribute` the attribute name to query ## `expected_type` the expected type of the attribute # Returns the attribute value, or `None` Queries the named `link` on `self`. ## `link` the link name to query # Returns the link, or `None` Sets or unsets the "action" and "target" attributes of `self`. If `action` is `None` then both the "action" and "target" attributes are unset (and `format_string` is ignored along with the positional parameters). If `action` is non-`None` then the "action" attribute is set. `format_string` is then inspected. If it is non-`None` then the proper position parameters are collected to create a `glib::Variant` instance to use as the target value. If it is `None` then the positional parameters are ignored and the "target" attribute is unset. See also `MenuItem::set_action_and_target_value` for an equivalent call that directly accepts a `glib::Variant`. See `MenuItem::set_detailed_action` for a more convenient version that works with string-typed targets. See also `MenuItem::set_action_and_target_value` for a description of the semantics of the action and target attributes. ## `action` the name of the action for this item ## `format_string` a GVariant format string Sets or unsets the "action" and "target" attributes of `self`. If `action` is `None` then both the "action" and "target" attributes are unset (and `target_value` is ignored). If `action` is non-`None` then the "action" attribute is set. The "target" attribute is then set to the value of `target_value` if it is non-`None` 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 `Action` and `ActionGroup` 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 `MenuItem::set_action_and_target` or `MenuItem::set_detailed_action` for two equivalent calls that are probably more convenient for most uses. ## `action` the name of the action for this item ## `target_value` a `glib::Variant` to use as the action target Sets or unsets an attribute on `self`. 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. If `format_string` is non-`None` then the proper position parameters are collected to create a `glib::Variant` instance to use as the attribute value. If it is `None` then the positional parameterrs are ignored and the named attribute is unset. See also `MenuItem::set_attribute_value` for an equivalent call that directly accepts a `glib::Variant`. ## `attribute` the attribute to set ## `format_string` a `glib::Variant` format string, or `None` Sets or unsets an attribute on `self`. 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-`None` then it is used as the new value for the attribute. If `value` is `None` then the attribute is unset. If the `value` `glib::Variant` is floating, it is consumed. See also `MenuItem::set_attribute` for a more convenient way to do the same. ## `attribute` the attribute to set ## `value` a `glib::Variant` to use as the value, or `None` Sets the "action" and possibly the "target" attribute of `self`. The format of `detailed_action` is the same format parsed by `Action::parse_detailed_name`. See `MenuItem::set_action_and_target` or `MenuItem::set_action_and_target_value` for more flexible (but slightly less convenient) alternatives. See also `MenuItem::set_action_and_target_value` for a description of the semantics of the action and target attributes. ## `detailed_action` the "detailed" action string Sets (or unsets) the icon on `self`. This call is the same as calling `Icon::serialize` and using the result as the value to `MenuItem::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 `None` then the icon is unset. ## `icon` a `Icon`, or `None` Sets or unsets the "label" attribute of `self`. If `label` is non-`None` it is used as the label for the menu item. If it is `None` then the label attribute is unset. ## `label` the label to set, or `None` to unset Creates a link from `self` to `model` if non-`None`, 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. ## `link` type of link to establish or unset ## `model` the `MenuModel` to link to (or `None` to unset) Sets or unsets the "section" link of `self` 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 `self` is added to. See `MenuItem::new_section` for more information about what it means for a menu item to be a section. ## `section` a `MenuModel`, or `None` Sets or unsets the "submenu" link of `self` to `submenu`. If `submenu` is non-`None`, it is linked to. If it is `None` then the link is unset. The effect of having one menu appear as a submenu of another is exactly as it sounds. ## `submenu` a `MenuModel`, or `None` `MenuLinkIter` is an opaque structure type. You must access it using the functions below. # Implements [`MenuLinkIterExt`](trait.MenuLinkIterExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuLinkIter` methods. # Implementors [`MenuLinkIter`](struct.MenuLinkIter.html) Gets the name of the link at the current iterator position. The iterator is not advanced. # Returns the type of the link This function combines `MenuLinkIterExt::next` with `MenuLinkIterExt::get_name` and `MenuLinkIterExt::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 `MenuModel` of the link that has just been advanced to. At this point, `MenuLinkIterExt::get_name` and `MenuLinkIterExt::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 `gobject::ObjectExt::unref` when it is no longer in use. ## `out_link` the name of the link ## `value` the linked `MenuModel` # Returns `true` on success, or `false` if there is no additional link Gets the linked `MenuModel` at the current iterator position. The iterator is not advanced. # Returns the `MenuModel` that is linked to 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). # Returns `true` on success, or `false` when there are no more links `MenuModel` 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 `MenuModel` is hierarchical: sections and submenus are again represented by `GMenuModels`. Menus themselves do not define their own roles. Rather, the role of a particular `MenuModel` 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}  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][menu-model] 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}  Notice that the separators visible in the [example][menu-example] appear nowhere in the [menu model][menu-model]. This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, a display system may show a section header instead of a separator. The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, dash boards, etc. To support such uses, it is necessary to 'export' information about actions and their representation in menus, which is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] and the [GMenuModel exporter][gio-GMenuModel-exporter] do for `ActionGroup` and `MenuModel`. The client-side counterparts to make use of the exported information are `DBusActionGroup` and `DBusMenuModel`. The API of `MenuModel` is very generic, with iterators for the attributes and links of an item, see `MenuModelExt::iterate_item_attributes` and `MenuModelExt::iterate_item_links`. The 'standard' attributes and link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`, `G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION` and `G_MENU_LINK_SUBMENU`. Items in a `MenuModel` 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``, 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. # Implements [`MenuModelExt`](trait.MenuModelExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MenuModel` methods. # Implementors [`MenuModel`](struct.MenuModel.html), [`Menu`](struct.Menu.html) Queries item at position `item_index` in `self` for the attribute specified by `attribute`. If the attribute exists and matches the `glib::VariantType` corresponding to `format_string` then `format_string` is used to deconstruct the value into the positional parameters and `true` is returned. If the attribute does not exist, or it does exist but has the wrong type, then the positional parameters are ignored and `false` is returned. This function is a mix of `MenuModelExt::get_item_attribute_value` and `glib::Variant::get`, followed by a `glib::Variant::unref`. As such, `format_string` must make a complete copy of the data (since the `glib::Variant` may go away after the call to `glib::Variant::unref`). In particular, no '&' characters are allowed in `format_string`. ## `item_index` the index of the item ## `attribute` the attribute to query ## `format_string` a `glib::Variant` format string # Returns `true` if the named attribute was found with the expected type Queries the item at position `item_index` in `self` for the attribute specified by `attribute`. If `expected_type` is non-`None` then it specifies the expected type of the attribute. If it is `None` 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 `None` is returned. ## `item_index` the index of the item ## `attribute` the attribute to query ## `expected_type` the expected type of the attribute, or `None` # Returns the value of the attribute Queries the item at position `item_index` in `self` for the link specified by `link`. If the link exists, the linked `MenuModel` is returned. If the link does not exist, `None` is returned. ## `item_index` the index of the item ## `link` the link to query # Returns the linked `MenuModel`, or `None` Query the number of items in `self`. # Returns the number of items Queries if `self` is mutable. An immutable `MenuModel` will never emit the `MenuModel::items-changed` signal. Consumers of the model may make optimisations accordingly. # Returns `true` if the model is mutable (ie: "items-changed" may be emitted). Requests emission of the `MenuModel::items-changed` signal on `self`. This function should never be called except by `MenuModel` 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 `MenuModel` API. Said another way: the menu must not change while user code is running without returning to the mainloop. ## `position` the position of the change ## `removed` the number of items removed ## `added` the number of items added Creates a `MenuAttributeIter` to iterate over the attributes of the item at position `item_index` in `self`. You must free the iterator with `gobject::ObjectExt::unref` when you are done. ## `item_index` the index of the item # Returns a new `MenuAttributeIter` Creates a `MenuLinkIter` to iterate over the links of the item at position `item_index` in `self`. You must free the iterator with `gobject::ObjectExt::unref` when you are done. ## `item_index` the index of the item # Returns a new `MenuLinkIter` Emitted when a change has occured 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. ## `position` the position of the change ## `removed` the number of items removed ## `added` the number of items added The `Mount` interface represents user-visible mounts. Note, when porting from GnomeVFS, `Mount` is the moral equivalent of `GnomeVFSVolume`. `Mount` 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 `Mount` instance is an asynchronous operation. For more information about asynchronous operations, see `AsyncResult` and `Task`. To unmount a `Mount` instance, first call `Mount::unmount_with_operation` with (at least) the `Mount` instance and a `GAsyncReadyCallback`. The callback will be fired when the operation has resolved (either with success or failure), and a `AsyncResult` structure will be passed to the callback. That callback should then call `Mount::unmount_with_operation_finish` with the `Mount` and the `AsyncResult` data to see if the operation was completed successfully. If an `error` is present when `Mount::unmount_with_operation_finish` is called, then it will be filled with any error information. # Implements [`MountExt`](trait.MountExt.html) Trait containing all `Mount` methods. # Implementors [`Mount`](struct.Mount.html) Checks if `self` can be ejected. # Returns `true` if the `self` can be ejected. Checks if `self` can be unmounted. # Returns `true` if the `self` can be unmounted. Ejects a mount. This is an asynchronous operation, and is finished by calling `Mount::eject_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the unmount if required for eject ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes ejecting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully ejected. `false` otherwise. Gets the default location of `self`. The default location of the given `self` is a path that reflects the main entry point for the user (e.g. the home directory, or the root of the volume). # Returns a `File`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the drive for the `self`. This is a convenience method for getting the `Volume` and then using that object to get the `Drive`. # Returns a `Drive` or `None` if `self` is not associated with a volume or a drive. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the name of `self`. # Returns the name for the given `self`. The returned string should be freed with `g_free` when no longer needed. Gets the root directory on `self`. # Returns a `File`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the sort key for `self`, if any. # Returns Sorting key for `self` or `None` if no such key is available. Gets the symbolic icon for `self`. # Returns a `Icon`. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Gets the UUID for the `self`. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns `None` if there is no UUID available. # Returns the UUID for `self` or `None` if no UUID can be computed. The returned string should be freed with `g_free` when no longer needed. Gets the volume for the `self`. # Returns a `Volume` or `None` if `self` is not associated with a volume. The returned object should be unreffed with `gobject::ObjectExt::unref` when no longer needed. Tries to guess the type of content stored on `self`. 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 `Mount::guess_content_type_sync` for the synchronous version), and is finished by calling `Mount::guess_content_type_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `force_rescan` Whether to force a rescan of the content. Otherwise a cached result will be used if available ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` a `GAsyncReadyCallback` ## `user_data` user data passed to `callback` Finishes guessing content types of `self`. 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 `IOErrorEnum::NotSupported` if the mount does not support content guessing. ## `result` a `AsyncResult` # Returns a `None`-terminated array of content types or `None` on error. Caller should free this array with `g_strfreev` when done with it. Tries to guess the type of content stored on `self`. 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 synchronous operation and as such may block doing IO; see `Mount::guess_content_type` for the asynchronous version. ## `force_rescan` Whether to force a rescan of the content. Otherwise a cached result will be used if available ## `cancellable` optional `Cancellable` object, `None` to ignore # Returns a `None`-terminated array of content types or `None` on error. Caller should free this array with `g_strfreev` when done with it. Determines if `self` is shadowed. Applications or libraries should avoid displaying `self` 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 `Mount` objects) with a root that is inside the root of `self`. One application of shadow mounts is when exposing a single file system that is used to address several logical volumes. In this situation, a `VolumeMonitor` implementation would create two `Volume` 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 `VolumeMonitor` implementation would create two `Mount` 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 `Volume` is set. # Returns `true` if `self` is shadowed. Remounts a mount. This is an asynchronous operation, and is finished by calling `Mount::remount_finish` with the `self` and `GAsyncResults` 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. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes remounting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully remounted. `false` otherwise. Increments the shadow count on `self`. Usually used by `VolumeMonitor` implementations when creating a shadow mount for `self`, see `Mount::is_shadowed` for more information. The caller will need to emit the `Mount::changed` signal on `self` manually. Unmounts a mount. This is an asynchronous operation, and is finished by calling `Mount::unmount_with_operation_finish` with the `self` and `AsyncResult` data returned in the `callback`. ## `flags` flags affecting the operation ## `mount_operation` a `MountOperation` or `None` to avoid user interaction. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`, or `None`. ## `user_data` user data passed to `callback`. Finishes unmounting a mount. If any errors occurred during the operation, `error` will be set to contain the errors and `false` will be returned. ## `result` a `AsyncResult`. # Returns `true` if the mount was successfully unmounted. `false` otherwise. Decrements the shadow count on `self`. Usually used by `VolumeMonitor` implementations when destroying a shadow mount for `self`, see `Mount::is_shadowed` for more information. The caller will need to emit the `Mount::changed` signal on `self` manually. Emitted when the mount has been changed. This signal may be emitted when the `Mount` is about to be unmounted. This signal depends on the backend and is only emitted if GIO was used to unmount. This signal is emitted when the `Mount` have been unmounted. If the recipient is holding references to the object they should release them so the object can be finalized. `MountOperation` 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 `MountOperation` is used for more than just `Mount` objects – for example it is also used in `Drive::start` and `Drive::stop`. Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as ``GtkMountOperation``. If no user interaction is desired (for example when automounting filesystems at login time), usually `None` can be passed, see each method taking a `MountOperation` for details. 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. # Implements [`MountOperationExt`](trait.MountOperationExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `MountOperation` methods. # Implementors [`MountOperation`](struct.MountOperation.html) Creates a new mount operation. # Returns a `MountOperation`. Check to see whether the mount operation is being used for an anonymous user. # Returns `true` if mount operation is anonymous. Gets a choice from the mount operation. # Returns an integer containing an index of the user's choice from the choice's list, or `0`. Gets the domain of the mount operation. # Returns a string set to the domain. Check to see whether the mount operation is being used for a TCRYPT hidden volume. Feature: `v2_58` # Returns `true` if mount operation is for hidden volume. Check to see whether the mount operation is being used for a TCRYPT system volume. Feature: `v2_58` # Returns `true` if mount operation is for system volume. Gets a password from the mount operation. # Returns a string containing the password within `self`. Gets the state of saving passwords for the mount operation. # Returns a `PasswordSave` flag. Gets a PIM from the mount operation. Feature: `v2_58` # Returns The VeraCrypt PIM within `self`. Get the user name from the mount operation. # Returns a string containing the user name. Emits the `MountOperation::reply` signal. ## `result` a `MountOperationResult` Sets the mount operation to use an anonymous user if `anonymous` is `true`. ## `anonymous` boolean value. Sets a default choice for the mount operation. ## `choice` an integer. Sets the mount operation's domain. ## `domain` the domain to set. Sets the mount operation to use a hidden volume if `hidden_volume` is `true`. Feature: `v2_58` ## `hidden_volume` boolean value. Sets the mount operation to use a system volume if `system_volume` is `true`. Feature: `v2_58` ## `system_volume` boolean value. Sets the mount operation's password to `password`. ## `password` password to set. Sets the state of saving passwords for the mount operation. ## `save` a set of `PasswordSave` flags. Sets the mount operation's PIM to `pim`. Feature: `v2_58` ## `pim` an unsigned integer. Sets the user name within `self` to `username`. ## `username` input username. 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. 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 ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `default_user` string containing the default user name. ## `default_domain` string containing the default domain. ## `flags` a set of `AskPasswordFlags`. 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 ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `choices` an array of strings for each possible choice. Emitted when the user has replied to the mount operation. ## `result` a `MountOperationResult` indicating how the request was handled Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a `Mount` or stopping a `Drive`. Note that this signal may be emitted several times to update the list of blocking processes as processes close files. The application should only respond with `MountOperationExt::reply` to the latest signal (setting `MountOperation:choice` to the choice the user made). 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 ``GtkMessageDialog``. ## `message` string containing a message to display to the user. ## `processes` an array of `glib::Pid` for processes blocking the operation. ## `choices` an array of strings for each possible choice. 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 ``GtkMessageDialog``. ## `message` string containing a mesage to display to the user ## `time_left` the estimated time left before the operation completes, in microseconds, or -1 ## `bytes_left` the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed Whether to use an anonymous user when authenticating. Whether to use an anonymous user when authenticating. The index of the user's choice when a question is asked during the mount operation. See the `MountOperation::ask-question` signal. The index of the user's choice when a question is asked during the mount operation. See the `MountOperation::ask-question` signal. The domain to use for the mount operation. The domain to use for the mount operation. Whether the device to be unlocked is a TCRYPT hidden volume. See https://www.veracrypt.fr/en/Hidden`20Volume.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT hidden volume. See https://www.veracrypt.fr/en/Hidden`20Volume.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see https://www.veracrypt.fr/en/System`20Encryption.html`. Feature: `v2_58` Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows operating systems. For further documentation, see https://www.veracrypt.fr/en/System`20Encryption.html`. Feature: `v2_58` The password that is used for authentication when carrying out the mount operation. The password that is used for authentication when carrying out the mount operation. Determines if and how the password information should be saved. Determines if and how the password information should be saved. The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See https://www.veracrypt.fr/en/Personal`20Iterations`%20Multiplier`20`(PIM).html. Feature: `v2_58` The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See https://www.veracrypt.fr/en/Personal`20Iterations`%20Multiplier`20`(PIM).html. Feature: `v2_58` The user name that is used for authentication when carrying out the mount operation. The user name that is used for authentication when carrying out the mount operation. `MountOperationResult` is returned as a result when a request for information is send by the mounting operation. The request was fulfilled and the user specified data is now available The user requested the mount operation to be aborted The request was unhandled (i.e. not implemented) `NetworkAddress` 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. See `SocketConnectable` for and example of using the connectable interface. # Implements [`NetworkAddressExt`](trait.NetworkAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `NetworkAddress` methods. # Implementors [`NetworkAddress`](struct.NetworkAddress.html) Creates a new `SocketConnectable` 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 `NetworkAddress::new_loopback` to create a `NetworkAddress` that is guaranteed to resolve to both addresses. ## `hostname` the hostname ## `port` the port # Returns the new `NetworkAddress` Creates a new `SocketConnectable` 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, `NetworkAddress::new` will often only return an IPv4 address when resolving `localhost`, and an IPv6 address for `localhost6`. `NetworkAddressExt::get_hostname` will always return `localhost` for `GNetworkAddresses` created with this constructor. Feature: `v2_44` ## `port` the port # Returns the new `NetworkAddress` Creates a new `SocketConnectable` for connecting to the given `hostname` and `port`. May fail and return `None` 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.) ## `host_and_port` the hostname and optionally a port ## `default_port` the default port if not in `host_and_port` # Returns the new `NetworkAddress`, or `None` on error Creates a new `SocketConnectable` for connecting to the given `uri`. May fail and return `None` in case parsing `uri` fails. Using this rather than `NetworkAddress::new` or `NetworkAddress::parse` allows `SocketClient` to determine when to use application-specific proxy protocols. ## `uri` the hostname and optionally a port ## `default_port` The default port if none is found in the URI # Returns the new `NetworkAddress`, or `None` on error Gets `self`'s hostname. This might be either UTF-8 or ASCII-encoded, depending on what `self` was created with. # Returns `self`'s hostname Gets `self`'s port number # Returns `self`'s port (which may be 0) Gets `self`'s scheme # Returns `self`'s scheme (`None` if not built from URI) The host's network connectivity state, as reported by `NetworkMonitor`. The host is not configured with a route to the Internet; it may or may not be connected to a local network. The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. The host is behind a captive portal and cannot reach the full Internet. The host is connected to a network, and appears to be able to reach the full Internet. Feature: `v2_44` `NetworkMonitor` 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. # Implements [`NetworkMonitorExt`](trait.NetworkMonitorExt.html) Trait containing all `NetworkMonitor` methods. # Implementors [`NetworkMonitor`](struct.NetworkMonitor.html) Gets the default `NetworkMonitor` for the system. # Returns a `NetworkMonitor` 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 `NetworkMonitor:network-available` is `false`, if, for example, `self` can determine that `connectable` refers to a host on a local network. If `self` 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 `IOErrorEnum::HostUnreachable`). 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 `NetworkMonitor::can_reach_async`. ## `connectable` a `SocketConnectable` ## `cancellable` a `Cancellable`, or `None` # Returns `true` if `connectable` is reachable, `false` if not. 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 `NetworkMonitor::can_reach`. When the operation is finished, `callback` will be called. You can then call `NetworkMonitor::can_reach_finish` to get the result of the operation. ## `connectable` a `SocketConnectable` ## `cancellable` a `Cancellable`, or `None` ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an async network connectivity test. See `NetworkMonitor::can_reach_async`. ## `result` a `AsyncResult` # Returns `true` if network is reachable, `false` if not. Gets a more detailed networking state than `NetworkMonitor::get_network_available`. If `NetworkMonitor:network-available` is `false`, then the connectivity state will be `NetworkConnectivity::Local`. If `NetworkMonitor:network-available` is `true`, then the connectivity state will be `NetworkConnectivity::Full` (if there is full Internet connectivity), `NetworkConnectivity::Limited` (if the host has a default route, but appears to be unable to actually reach the full Internet), or `NetworkConnectivity::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 `NetworkConnectivity::Limited` and `NetworkConnectivity::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. Feature: `v2_44` # Returns the network connectivity state 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 `NetworkMonitor:network-available` for more details. # Returns whether the network is available Checks if the network is metered. See `NetworkMonitor:network-metered` for more details. Feature: `v2_46` # Returns whether the connection is metered Emitted when the network configuration changes. ## `network_available` the current value of `NetworkMonitor:network-available` More detailed information about the host's network connectivity. See `NetworkMonitor::get_connectivity` and `NetworkConnectivity` for more details. Feature: `v2_44` Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. Real-world networks are of course much more complicated than this; the machine may be connected to a wifi hotspot that requires payment before allowing traffic through, or may be connected to a functioning router that has lost its own upstream connectivity. Some hosts might only be accessible when a VPN is active. Other hosts might only be accessible when the VPN is not active. Thus, it is best to use `NetworkMonitor::can_reach` or `NetworkMonitor::can_reach_async` to test for reachability on a host-by-host basis. (On the other hand, when the property is `false`, the application can reasonably expect that no remote hosts at all are reachable, and should indicate this to the user in its UI.) See also `NetworkMonitor::network-changed`. Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is subject to limitations set by service providers. For example, traffic might be billed by the amount of data transmitted, or there might be a quota on the amount of traffic per month. This is typical with tethered connections (3G and 4G) and in such situations, bandwidth intensive applications may wish to avoid network activity where possible if it will cost the user money or use up their limited quota. If more information is required about specific devices then the system network management API should be used instead (for example, NetworkManager or ConnMan). If this information is not available then no networks will be marked as metered. See also `NetworkMonitor:network-available`. Feature: `v2_46` Like `NetworkAddress` does with hostnames, `NetworkService` 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 `SrvTarget` for more information about SRV records, and see `SocketConnectable` for and example of using the connectable interface. # Implements [`NetworkServiceExt`](trait.NetworkServiceExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `NetworkService` methods. # Implementors [`NetworkService`](struct.NetworkService.html) Creates a new `NetworkService` representing the given `service`, `protocol`, and `domain`. This will initially be unresolved; use the `SocketConnectable` interface to resolve it. ## `service` the service type to look up (eg, "ldap") ## `protocol` the networking protocol to use for `service` (eg, "tcp") ## `domain` the DNS domain to look up the service in # Returns a new `NetworkService` Gets the domain that `self` serves. This might be either UTF-8 or ASCII-encoded, depending on what `self` was created with. # Returns `self`'s domain name Gets `self`'s protocol name (eg, "tcp"). # Returns `self`'s protocol name Get's the URI scheme used to resolve proxies. By default, the service name is used as scheme. # Returns `self`'s scheme name Gets `self`'s service name (eg, "ldap"). # Returns `self`'s service name Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. ## `scheme` a URI scheme `Notification` 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 `Notification` and other similar APIs is that, if supported by the desktop environment, notifications sent with `Notification` 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 `Notification` should be able to be started as a D-Bus service, using `Application`. 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 `ApplicationExt::send_notification`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Creates a new `Notification` with `title` as its title. After populating `notification` with more details, it can be sent to the desktop shell with `ApplicationExt::send_notification`. Changing any properties after this call will not have any effect until resending `notification`. ## `title` the title of the notification # Returns a new `Notification` instance Adds a button to `self` 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 `Action::parse_detailed_name` for a description of the format for `detailed_action`. ## `label` label of the button ## `detailed_action` a detailed action name Adds a button to `self` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app."). If `target_format` is given, it is used to collect remaining positional parameters into a `glib::Variant` instance, similar to `glib::Variant::new`. `action` will be activated with that `glib::Variant` as its parameter. ## `label` label of the button ## `action` an action name ## `target_format` a `glib::Variant` format string, or `None` Adds a button to `self` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app."). If `target` is non-`None`, `action` will be activated with `target` as its parameter. ## `label` label of the button ## `action` an action name ## `target` a `glib::Variant` to use as `action`'s parameter, or `None` Sets the body of `self` to `body`. ## `body` the new body for `self`, or `None` Sets the default action of `self` 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 `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. ## `detailed_action` a detailed action name Sets the default action of `self` to `action`. This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app."). If `target_format` is given, it is used to collect remaining positional parameters into a `glib::Variant` instance, similar to `glib::Variant::new`. `action` will be activated with that `glib::Variant` as its parameter. When no default action is set, the application that the notification was sent on is activated. ## `action` an action name ## `target_format` a `glib::Variant` format string, or `None` Sets the default action of `self` 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-`None`, `action` will be activated with `target` as its parameter. When no default action is set, the application that the notification was sent on is activated. ## `action` an action name ## `target` a `glib::Variant` to use as `action`'s parameter, or `None` Sets the icon of `self` to `icon`. ## `icon` the icon to be shown in `self`, as a `Icon` Sets the priority of `self` to `priority`. See `NotificationPriority` for possible values. ## `priority` a `NotificationPriority` Sets the title of `self` to `title`. ## `title` the new title for `self` Priority levels for `GNotifications`. the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) `OutputStream` has functions to write to a stream (`OutputStreamExt::write`), to close a stream (`OutputStreamExt::close`) and to flush pending writes (`OutputStreamExt::flush`). To copy the content of an input stream to an output stream without manually handling the reads and writes, use `OutputStreamExt::splice`. See the documentation for `IOStream` for details of thread safety of streaming APIs. All of these functions have async variants too. # Implements [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `OutputStream` methods. # Implementors [`FileOutputStream`](struct.FileOutputStream.html), [`FilterOutputStream`](struct.FilterOutputStream.html), [`MemoryOutputStream`](struct.MemoryOutputStream.html), [`OutputStream`](struct.OutputStream.html), [`PollableOutputStream`](struct.PollableOutputStream.html), [`UnixOutputStream`](struct.UnixOutputStream.html) Clears the pending flag on `self`. Closes the stream, releasing resources related to it. Once the stream is closed, all other operations will return `IOErrorEnum::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 `IOErrorEnum::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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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. ## `cancellable` optional cancellable object # Returns `true` on success, `false` on failure 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 `OutputStreamExt::close_finish` to get the result of the operation. For behaviour details see `OutputStreamExt::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. ## `io_priority` the io priority of the request. ## `cancellable` optional cancellable object ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Closes an output stream. ## `result` a `AsyncResult`. # Returns `true` if stream was successfully closed, `false` otherwise. Forces a write of all user-space buffered data for the given `self`. Will block during the operation. Closing the stream will implicitly cause a flush. This function is optional for inherited classes. If `cancellable` is not `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::Cancelled` will be returned. ## `cancellable` optional cancellable object # Returns `true` on success, `false` on error Forces an asynchronous write of all user-space buffered data for the given `self`. For behaviour details see `OutputStreamExt::flush`. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::flush_finish` to get the result of the operation. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback` to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes flushing an output stream. ## `result` a GAsyncResult. # Returns `true` if flush operation succeeded, `false` otherwise. Checks if an output stream has pending actions. # Returns `true` if `self` has pending actions. Checks if an output stream has already been closed. # Returns `true` if `self` is closed. `false` otherwise. 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. # Returns `true` if `self` is being closed. `false` otherwise. This is a utility function around `OutputStream::write_all`. It uses `g_strdup_vprintf` to turn `format` and @... into a string that is then written to `self`. See the documentation of `OutputStream::write_all` about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own `printf`-like wrapper around `OutputStreamExt::write` or `OutputStream::write_all`. ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `error` location to store the error occurring, or `None` to ignore ## `format` the format string. See the `printf` documentation # Returns `true` on success, `false` if there was an error Sets `self` to have actions pending. If the pending flag is already set or `self` is closed, it will return `false` and set `error`. # Returns `true` if pending was previously unset and is now set. Splices an input stream into an output stream. ## `source` a `InputStream`. ## `flags` a set of `OutputStreamSpliceFlags`. ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns a `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. Splices a stream asynchronously. When the operation is finished `callback` will be called. You can then call `OutputStreamExt::splice_finish` to get the result of the operation. For the synchronous, blocking version of this function, see `OutputStreamExt::splice`. ## `source` a `InputStream`. ## `flags` a set of `OutputStreamSpliceFlags`. ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` a `GAsyncReadyCallback`. ## `user_data` user data passed to `callback`. Finishes an asynchronous stream splice operation. ## `result` a `AsyncResult`. # Returns a `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. This is a utility function around `OutputStream::write_all`. It uses `g_strdup_vprintf` to turn `format` and `args` into a string that is then written to `self`. See the documentation of `OutputStream::write_all` about the behavior of the actual write operation. Note that partial writes cannot be properly checked with this function due to the variable length of the written string, if you need precise control over partial write failures, you need to create you own `printf`-like wrapper around `OutputStreamExt::write` or `OutputStream::write_all`. ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `error` location to store the error occurring, or `None` to ignore ## `format` the format string. See the `printf` documentation ## `args` the parameters to insert into the format string # Returns `true` on success, `false` if there was an error 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 `IOErrorEnum::InvalidArgument` 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 `None`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error `IOErrorEnum::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. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `cancellable` optional cancellable object # Returns Number of bytes written, or -1 on error Tries to write `count` bytes from `buffer` into the stream. Will block during the operation. This function is similar to `OutputStreamExt::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 `glib::Error`, 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 `OutputStreamExt::write`. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `bytes_written` location to store the number of bytes that was written to the stream ## `cancellable` optional `Cancellable` object, `None` to ignore. # Returns `true` on success, `false` if there was an error 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 `OutputStreamExt::write_all_finish` to get the result of the operation. This is the asynchronous version of `OutputStream::write_all`. Call `OutputStreamExt::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. Feature: `v2_44` ## `buffer` the buffer containing the data to write ## `count` the number of bytes to write ## `io_priority` the io priority of the request ## `cancellable` optional `Cancellable` object, `None` to ignore ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes an asynchronous stream write operation started with `OutputStream::write_all_async`. As a special exception to the normal conventions for functions that use `glib::Error`, 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 `OutputStream::write_async`. Feature: `v2_44` ## `result` a `AsyncResult` ## `bytes_written` location to store the number of bytes that was written to the stream # Returns `true` on success, `false` if there was an error 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 `OutputStreamExt::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 `IOErrorEnum::Pending` errors. A value of `count` larger than `G_MAXSSIZE` will cause a `IOErrorEnum::InvalidArgument` 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 `IOErrorEnum::WouldBlock` - if `self` 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 `OutputStreamExt::write`. Note that no copy of `buffer` will be made, so it must stay valid until `callback` is called. See `OutputStreamExt::write_bytes_async` for a `glib::Bytes` version that will automatically hold a reference to the contents (without copying) for the duration of the call. ## `buffer` the buffer containing the data to write. ## `count` the number of bytes to write ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function A wrapper function for `OutputStreamExt::write` which takes a `glib::Bytes` as input. This can be more convenient for use by language bindings or in other cases where the refcounted nature of `glib::Bytes` is helpful over a bare pointer interface. However, note that this function may still perform partial writes, just like `OutputStreamExt::write`. If that occurs, to continue writing, you will need to create a new `glib::Bytes` containing just the remaining bytes, using `glib::Bytes::new_from_bytes`. Passing the same `glib::Bytes` instance multiple times potentially can result in duplicated data in the output stream. ## `bytes` the `glib::Bytes` to write ## `cancellable` optional cancellable object # Returns Number of bytes written, or -1 on error This function is similar to `OutputStream::write_async`, but takes a `glib::Bytes` as input. Due to the refcounted nature of `glib::Bytes`, this allows the stream to avoid taking a copy of the data. However, note that this function may still perform partial writes, just like `OutputStream::write_async`. If that occurs, to continue writing, you will need to create a new `glib::Bytes` containing just the remaining bytes, using `glib::Bytes::new_from_bytes`. Passing the same `glib::Bytes` instance multiple times potentially can result in duplicated data in the output stream. For the synchronous, blocking version of this function, see `OutputStreamExt::write_bytes`. ## `bytes` The bytes to write ## `io_priority` the io priority of the request. ## `cancellable` optional `Cancellable` object, `None` to ignore. ## `callback` callback to call when the request is satisfied ## `user_data` the data to pass to callback function Finishes a stream write-from-`glib::Bytes` operation. ## `result` a `AsyncResult`. # Returns a `gssize` containing the number of bytes written to the stream. Finishes a stream write operation. ## `result` a `AsyncResult`. # Returns a `gssize` containing the number of bytes written to the stream. `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. never save a password. save a password for the session. save a password permanently. A `Permission` 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 `Permission` might represent the ability for the user to write to a `Settings` object. This `Permission` 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. # Implements [`PermissionExt`](trait.PermissionExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html) Trait containing all `Permission` methods. # Implementors [`Permission`](struct.Permission.html), [`SimplePermission`](struct.SimplePermission.html) Attempts to acquire the permission represented by `self`. 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 `PermissionExt::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 `PermissionExt::acquire_async` for the non-blocking version. ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the permission was successfully acquired Attempts to acquire the permission represented by `self`. This is the first half of the asynchronous version of `PermissionExt::acquire`. ## `cancellable` a `Cancellable`, or `None` ## `callback` the `GAsyncReadyCallback` to call when done ## `user_data` the user data to pass to `callback` Collects the result of attempting to acquire the permission represented by `self`. This is the second half of the asynchronous version of `PermissionExt::acquire`. ## `result` the `AsyncResult` given to the `GAsyncReadyCallback` # Returns `true` if the permission was successfully acquired Gets the value of the 'allowed' property. This property is `true` if the caller currently has permission to perform the action that `self` represents the permission to perform. # Returns the value of the 'allowed' property Gets the value of the 'can-acquire' property. This property is `true` if it is generally possible to acquire the permission by calling `PermissionExt::acquire`. # Returns the value of the 'can-acquire' property Gets the value of the 'can-release' property. This property is `true` if it is generally possible to release the permission by calling `PermissionExt::release`. # Returns the value of the 'can-release' property This function is called by the `Permission` implementation to update the properties of the permission. You should never call this function except from a `Permission` implementation. GObject notify signals are generated, as appropriate. ## `allowed` the new value for the 'allowed' property ## `can_acquire` the new value for the 'can-acquire' property ## `can_release` the new value for the 'can-release' property Attempts to release the permission represented by `self`. 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 `PermissionExt::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 `PermissionExt::release_async` for the non-blocking version. ## `cancellable` a `Cancellable`, or `None` # Returns `true` if the permission was successfully released Attempts to release the permission represented by `self`. This is the first half of the asynchronous version of `PermissionExt::release`. ## `cancellable` a `Cancellable`, or `None` ## `callback` the `GAsyncReadyCallback` to call when done ## `user_data` the user data to pass to `callback` Collects the result of attempting to release the permission represented by `self`. This is the second half of the asynchronous version of `PermissionExt::release`. ## `result` the `AsyncResult` given to the `GAsyncReadyCallback` # Returns `true` if the permission was successfully released `true` if the caller currently has permission to perform the action that `permission` represents the permission to perform. `true` if it is generally possible to acquire the permission by calling `PermissionExt::acquire`. `true` if it is generally possible to release the permission by calling `PermissionExt::release`. `PollableInputStream` is implemented by `GInputStreams` 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. # Implements [`PollableInputStreamExt`](trait.PollableInputStreamExt.html), [`InputStreamExt`](trait.InputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableInputStreamExtManual`](prelude/trait.PollableInputStreamExtManual.html), [`InputStreamExtManual`](prelude/trait.InputStreamExtManual.html) Trait containing all `PollableInputStream` methods. # Implementors [`ConverterInputStream`](struct.ConverterInputStream.html), [`MemoryInputStream`](struct.MemoryInputStream.html), [`PollableInputStream`](struct.PollableInputStream.html), [`UnixInputStream`](struct.UnixInputStream.html) Checks if `self` is actually pollable. Some classes may implement `PollableInputStream` but have only certain instances of that class be pollable. If this method returns `false`, then the behavior of other `PollableInputStream` 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. # Returns `true` if `self` is pollable, `false` if not. Creates a `glib::Source` that triggers when `self` can be read, or `cancellable` is triggered or an error occurs. The callback on the source is of the `GPollableSourceFunc` type. As with `PollableInputStream::is_readable`, it is possible that the stream may not actually be readable even after the source triggers, so you should use `PollableInputStream::read_nonblocking` rather than `InputStream::read` from the callback. ## `cancellable` a `Cancellable`, or `None` # Returns a new `glib::Source` Checks if `self` 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 `InputStream::read` after this returns `true` would still block. To guarantee non-blocking behavior, you should always use `PollableInputStream::read_nonblocking`, which will return a `IOErrorEnum::WouldBlock` error rather than blocking. # Returns `true` if `self` is readable, `false` if not. If an error has occurred on `self`, this will result in `PollableInputStream::is_readable` returning `true`, and the next attempt to read will return the error. Attempts to read up to `count` bytes from `self` into `buffer`, as with `InputStream::read`. If `self` is not currently readable, this will immediately return `IOErrorEnum::WouldBlock`, and you can use `PollableInputStream::create_source` to create a `glib::Source` that will be triggered when `self` 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. ## `buffer` a buffer to read data into (which should be at least `count` bytes long). ## `count` the number of bytes you want to read ## `cancellable` a `Cancellable`, or `None` # Returns the number of bytes read, or -1 on error (including `IOErrorEnum::WouldBlock`). `PollableOutputStream` is implemented by `GOutputStreams` 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. # Implements [`PollableOutputStreamExt`](trait.PollableOutputStreamExt.html), [`OutputStreamExt`](trait.OutputStreamExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`PollableOutputStreamExtManual`](prelude/trait.PollableOutputStreamExtManual.html), [`OutputStreamExtManual`](prelude/trait.OutputStreamExtManual.html) Trait containing all `PollableOutputStream` methods. # Implementors [`ConverterOutputStream`](struct.ConverterOutputStream.html), [`MemoryOutputStream`](struct.MemoryOutputStream.html), [`PollableOutputStream`](struct.PollableOutputStream.html), [`UnixOutputStream`](struct.UnixOutputStream.html) Checks if `self` is actually pollable. Some classes may implement `PollableOutputStream` but have only certain instances of that class be pollable. If this method returns `false`, then the behavior of other `PollableOutputStream` 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. # Returns `true` if `self` is pollable, `false` if not. Creates a `glib::Source` that triggers when `self` can be written, or `cancellable` is triggered or an error occurs. The callback on the source is of the `GPollableSourceFunc` type. As with `PollableOutputStream::is_writable`, it is possible that the stream may not actually be writable even after the source triggers, so you should use `PollableOutputStream::write_nonblocking` rather than `OutputStreamExt::write` from the callback. ## `cancellable` a `Cancellable`, or `None` # Returns a new `glib::Source` Checks if `self` 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 `OutputStreamExt::write` after this returns `true` would still block. To guarantee non-blocking behavior, you should always use `PollableOutputStream::write_nonblocking`, which will return a `IOErrorEnum::WouldBlock` error rather than blocking. # Returns `true` if `self` is writable, `false` if not. If an error has occurred on `self`, this will result in `PollableOutputStream::is_writable` returning `true`, and the next attempt to write will return the error. Attempts to write up to `count` bytes from `buffer` to `self`, as with `OutputStreamExt::write`. If `self` is not currently writable, this will immediately return `IOErrorEnum::WouldBlock`, and you can use `PollableOutputStream::create_source` to create a `glib::Source` that will be triggered when `self` 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 `IOErrorEnum::WouldBlock` is returned some underlying transports like D/TLS require that you send the same `buffer` and `count`. ## `buffer` a buffer to write data from ## `count` the number of bytes you want to write ## `cancellable` a `Cancellable`, or `None` # Returns the number of bytes written, or -1 on error (including `IOErrorEnum::WouldBlock`). A `PropertyAction` is a way to get a `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). `PropertyAction` 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 `Action` corresponding to the "visible-child-name" property of a ``GtkStack`` 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``. This is because the state of the combobox itself is probably uninteresting and is actually being used to control something else. Another anti-example would be to bind to the "visible-child-name" property of a ``GtkStack`` if this value is actually stored in `Settings`. In that case, the real source of the value is `Settings`. If you want a `Action` to control a setting stored in `Settings`, see `SettingsExt::create_action` instead, and possibly combine its use with `SettingsExt::bind`. # Implements [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`ActionExt`](trait.ActionExt.html) Creates a `Action` 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. ## `name` the name of the action to create ## `object` the object that has the property to wrap ## `property_name` the name of the property # Returns a new `PropertyAction` If `action` is currently enabled. If the action is disabled then calls to `Action::activate` and `Action::change_state` have no effect. If `true`, the state of the action will be the negation of the property value, provided the property is boolean. Feature: `v2_46` If `true`, the state of the action will be the negation of the property value, provided the property is boolean. Feature: `v2_46` The name of the action. This is mostly meaningful for identifying the action once it has been added to a `ActionMap`. The name of the action. This is mostly meaningful for identifying the action once it has been added to a `ActionMap`. The object to wrap a property on. The object must be a non-`None` `gobject::Object` with properties. The type of the parameter that must be given when activating the action. The name of the property to wrap on the object. The property must exist on the passed-in object and it must be readable and writable (and not construct-only). The state of the action, or `None` if the action is stateless. The `glib::VariantType` of the state that the action has, or `None` if the action is stateless. A `Proxy` 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 `IOExtensionPoint::get_extension_by_name`. # Implements [`ProxyExt`](trait.ProxyExt.html) Trait containing all `Proxy` methods. # Implementors [`Proxy`](struct.Proxy.html) Lookup "gio-proxy" extension point for a proxy implementation that supports specified protocol. ## `protocol` the proxy protocol name (e.g. http, socks, etc) # Returns return a `Proxy` or NULL if protocol is not supported. Given `connection` to communicate with a proxy (eg, a `SocketConnection` that is connected to the proxy server), this does the necessary handshake to connect to `proxy_address`, and if required, wraps the `IOStream` to handle proxy payload. ## `connection` a `IOStream` ## `proxy_address` a `ProxyAddress` ## `cancellable` a `Cancellable` # Returns a `IOStream` that will replace `connection`. This might be the same as `connection`, in which case a reference will be added. Asynchronous version of `Proxy::connect`. ## `connection` a `IOStream` ## `proxy_address` a `ProxyAddress` ## `cancellable` a `Cancellable` ## `callback` a `GAsyncReadyCallback` ## `user_data` callback data See `Proxy::connect`. ## `result` a `AsyncResult` # Returns a `IOStream`. 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 `self` is implementing such a protocol. When `false` is returned, the caller should resolve the destination hostname first, and then pass a `ProxyAddress` containing the stringified IP address to `Proxy::connect` or `Proxy::connect_async`. # Returns `true` if hostname resolution is supported. Support for proxied `InetSocketAddress`. # Implements [`ProxyAddressExt`](trait.ProxyAddressExt.html), [`InetSocketAddressExt`](trait.InetSocketAddressExt.html), [`SocketAddressExt`](trait.SocketAddressExt.html), [`glib::object::ObjectExt`](../glib/object/trait.ObjectExt.html), [`SocketConnectableExt`](trait.SocketConnectableExt.html) Trait containing all `ProxyAddress` methods. # Implementors [`ProxyAddress`](struct.ProxyAddress.html) Creates a new `ProxyAddress` for `inetaddr` with `protocol` that should tunnel through `dest_hostname` and `dest_port`. (Note that this method doesn't set the `ProxyAddress:uri` or `ProxyAddress:destination-protocol` fields; use `gobject::Object::new` directly if you want to set those.) ## `inetaddr` The proxy server `InetAddress`. ## `port` The proxy server port. ## `protocol` The proxy protocol to support, in lower case (e.g. socks, http). ## `dest_hostname` The destination hostname the proxy should tunnel to. ## `dest_port` The destination port to tunnel to. ## `username` The username to authenticate to the proxy server (or `None`). ## `password` The password to authenticate to the proxy server (or `None`). # Returns a new `ProxyAddress` Gets `self`'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. # Returns the `self`'s destination hostname Gets `self`'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. # Returns the `self`'s destination port Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". # Returns the `self`'s destination protocol Gets `self`'s password. # Returns the `self`'s password Gets `self`'s protocol. eg, "socks" or "http" # Returns the `self`'s protocol Gets the proxy URI that `self` was constructed from. # Returns the `self`'s URI, or `None` if unknown Gets `self`'s username. # Returns the `self`'s username The protocol being spoke to the destination host, or `None` if the `ProxyAddress` doesn't know. The protocol being spoke to the destination host, or `None` if the `ProxyAddress` doesn't know. The URI string that the proxy was constructed from (or `None` if the creator didn't specify this). The URI string that the proxy was constructed from (or `None` if the creator didn't specify this). `ProxyResolver` provides synchronous and asynchronous network proxy resolution. `ProxyResolver` is used within `SocketClient` through the method `SocketConnectable::proxy_enumerate`. Implementations of `ProxyResolver` based on libproxy and GNOME settings can be found in glib-networking. GIO comes with an implementation for use inside Flatpak portals. # Implements [`ProxyResolverExt`](trait.ProxyResolverExt.html) Trait containing all `ProxyResolver` methods. # Implementors [`ProxyResolver`](struct.ProxyResolver.html) Gets the default `ProxyResolver` for the system. # Returns the default `ProxyResolver`. Checks if `self` can be used on this system. (This is used internally; `ProxyResolver::get_default` will only return a proxy resolver that returns `true` for this method.) # Returns `true` if `self` is supported. 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 `
for T`
Say you want to pass a `*mut GdkWindowAttr` to a foreign function. The `Stash`
will own a `GdkWindowAttr` and a `CString` that `GdkWindowAttr::title` points into.
```ignore
impl <'a> ToGlibPtr<'a, *mut glib_ffi::GdkWindowAttr> for WindowAttr {
type Storage = (Box