gi-gio-2.0.27: Gio bindings

Copyright | Will Thompson Iñaki García Etxebarria and Jonas Platte
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gio.Interfaces.Volume

Contents

- Exported types
- Methods
  - Overloaded methods
  - canEject
  - canMount
  - eject
  - ejectFinish
  - ejectWithOperation
  - ejectWithOperationFinish
  - enumerateIdentifiers
  - getActivationRoot
  - getDrive
  - getIcon
  - getIdentifier
  - getMount
  - getName
  - getSortKey
  - getSymbolicIcon
  - getUuid
  - mount
  - mountFinish
  - shouldAutomount
- Signals
  - changed
  - removed

Description

The `Volume` interface represents user-visible objects that can be mounted. Note, when porting from GnomeVFS, `Volume` is the moral equivalent of `GnomeVFSDrive`.

Mounting a `Volume` instance is an asynchronous operation. For more information about asynchronous operations, see `AsyncResult` and `Task`. To mount a `Volume`, first call `volumeMount` with (at least) the `Volume` instance, optionally a `MountOperation` object and a `AsyncReadyCallback`.

Typically, one will only want to pass `Nothing` for the `MountOperation` if automounting all volumes when a desktop session starts since it's not desirable to put up a lot of dialogs asking for credentials.

The callback will be fired when the operation has resolved (either with success or failure), and a `AsyncResult` instance will be passed to the callback. That callback should then call `volumeMountFinish` with the `Volume` instance and the `AsyncResult` data to see if the operation was completed successfully. If an `error` is present when `volumeMountFinish` is called, then it will be filled with any error information.

# {`volume`-identifier}

It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: `VOLUME_IDENTIFIER_KIND_UUID`, `VOLUME_IDENTIFIER_KIND_LABEL`, etc. Use `volumeGetIdentifier` to obtain an identifier for a volume.

Note that `VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available when the gvfs hal volume monitor is in use. Other volume monitors will generally be able to provide the `VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of `libhal_manager_find_device_string_match()`.

Synopsis

- newtype Volume = Volume (ManagedPtr Volume)
- class (GObject o, IsDescendantOf Volume o) => IsVolume o
- toVolume :: (MonadIO m, IsVolume o) => o -> m Volume
- volumeCanEject :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Bool
- volumeCanMount :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Bool
- volumeEject :: (HasCallStack, MonadIO m, IsVolume a, IsCancellable b) => a -> [MountUnmountFlags] -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- volumeEjectFinish :: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) => a -> b -> m ()
- volumeEjectWithOperation :: (HasCallStack, MonadIO m, IsVolume a, IsMountOperation b, IsCancellable c) => a -> [MountUnmountFlags] -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- volumeEjectWithOperationFinish :: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) => a -> b -> m ()
- volumeEnumerateIdentifiers :: (HasCallStack, MonadIO m, IsVolume a) => a -> m [Text]
- volumeGetActivationRoot :: (HasCallStack, MonadIO m, IsVolume a) => a -> m (Maybe File)
- volumeGetDrive :: (HasCallStack, MonadIO m, IsVolume a) => a -> m (Maybe Drive)
- volumeGetIcon :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Icon
- volumeGetIdentifier :: (HasCallStack, MonadIO m, IsVolume a) => a -> Text -> m (Maybe Text)
- volumeGetMount :: (HasCallStack, MonadIO m, IsVolume a) => a -> m (Maybe Mount)
- volumeGetName :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Text
- volumeGetSortKey :: (HasCallStack, MonadIO m, IsVolume a) => a -> m (Maybe Text)
- volumeGetSymbolicIcon :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Icon
- volumeGetUuid :: (HasCallStack, MonadIO m, IsVolume a) => a -> m (Maybe Text)
- volumeMount :: (HasCallStack, MonadIO m, IsVolume a, IsMountOperation b, IsCancellable c) => a -> [MountMountFlags] -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- volumeMountFinish :: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) => a -> b -> m ()
- volumeShouldAutomount :: (HasCallStack, MonadIO m, IsVolume a) => a -> m Bool
- type C_VolumeChangedCallback = Ptr () -> Ptr () -> IO ()
- type VolumeChangedCallback = IO ()
- afterVolumeChanged :: (IsVolume a, MonadIO m) => a -> VolumeChangedCallback -> m SignalHandlerId
- genClosure_VolumeChanged :: MonadIO m => VolumeChangedCallback -> m (GClosure C_VolumeChangedCallback)
- mk_VolumeChangedCallback :: C_VolumeChangedCallback -> IO (FunPtr C_VolumeChangedCallback)
- noVolumeChangedCallback :: Maybe VolumeChangedCallback
- onVolumeChanged :: (IsVolume a, MonadIO m) => a -> VolumeChangedCallback -> m SignalHandlerId
- wrap_VolumeChangedCallback :: VolumeChangedCallback -> C_VolumeChangedCallback
- type C_VolumeRemovedCallback = Ptr () -> Ptr () -> IO ()
- type VolumeRemovedCallback = IO ()
- afterVolumeRemoved :: (IsVolume a, MonadIO m) => a -> VolumeRemovedCallback -> m SignalHandlerId
- genClosure_VolumeRemoved :: MonadIO m => VolumeRemovedCallback -> m (GClosure C_VolumeRemovedCallback)
- mk_VolumeRemovedCallback :: C_VolumeRemovedCallback -> IO (FunPtr C_VolumeRemovedCallback)
- noVolumeRemovedCallback :: Maybe VolumeRemovedCallback
- onVolumeRemoved :: (IsVolume a, MonadIO m) => a -> VolumeRemovedCallback -> m SignalHandlerId
- wrap_VolumeRemovedCallback :: VolumeRemovedCallback -> C_VolumeRemovedCallback

# Exported types

newtype Volume Source #

Memory-managed wrapper type.

Constructors

Volume (ManagedPtr Volume) |

#### Instances

Instances details

Eq Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume Methods (==) :: Volume -> Volume -> Bool # (/=) :: Volume -> Volume -> Bool #
GObject Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume
TypedObject Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume Methods glibType :: IO GType Source #
ManagedPtrNewtype Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume Methods toManagedPtr :: Volume -> ManagedPtr Volume Source #
IsGValue Volume Source # | Convert `Volume` to and from `GValue` with `toGValue` and `fromGValue`.
Instance details Defined in GI.Gio.Interfaces.Volume Methods toGValue :: Volume -> IO GValue Source # fromGValue :: GValue -> IO Volume Source #
HasParentTypes Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume
type ParentTypes Volume Source # |
Instance details Defined in GI.Gio.Interfaces.Volume type ParentTypes Volume = '[Object]

class (GObject o, IsDescendantOf Volume o) => IsVolume o Source #

Type class for types which can be safely cast to `Volume`, for instance with `toVolume`.

#### Instances

Instances details

(GObject o, IsDescendantOf Volume o) => IsVolume o Source # |
Instance details Defined in GI.Gio.Interfaces.Volume

toVolume :: (MonadIO m, IsVolume o) => o -> m Volume Source #

Cast to `Volume`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

## Overloaded methods

## canEject

volumeCanEject Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Bool | Returns: `True` if the `volume` can be ejected. `False` otherwise

Checks if a volume can be ejected.

## canMount

volumeCanMount Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Bool | Returns: `True` if the `volume` can be mounted. `False` otherwise

Checks if a volume can be mounted.

## eject

volumeEject Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsCancellable b) |
=> a | `volume`: a `Volume`
-> [MountUnmountFlags] | `flags`: flags affecting the unmount if required for eject
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback`, or `Nothing`
-> m () |

Deprecated: (Since version 2.22)Use `volumeEjectWithOperation` instead.

Ejects a volume. This is an asynchronous operation, and is finished by calling `volumeEjectFinish` with the `volume` and `AsyncResult` returned in the `callback`.

## ejectFinish

volumeEjectFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) |
=> a | `volume`: pointer to a `Volume`
-> b | `result`: a `AsyncResult`
-> m () | (Can throw `GError`)

Deprecated: (Since version 2.22)Use `volumeEjectWithOperationFinish` instead.

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `False` will be returned.

## ejectWithOperation

volumeEjectWithOperation Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsMountOperation b, IsCancellable c) |
=> a | `volume`: a `Volume`
-> [MountUnmountFlags] | `flags`: flags affecting the unmount if required for eject
-> Maybe b | `mountOperation`: a `MountOperation` or `Nothing` to avoid user interaction
-> Maybe c | `cancellable`: optional `Cancellable` object, `Nothing` to ignore
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback`, or `Nothing`
-> m () |

Ejects a volume. This is an asynchronous operation, and is finished by calling `volumeEjectWithOperationFinish` with the `volume` and `AsyncResult` data returned in the `callback`.

Since: 2.22

## ejectWithOperationFinish

volumeEjectWithOperationFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) |
=> a | `volume`: a `Volume`
-> b | `result`: a `AsyncResult`
-> m () | (Can throw `GError`)

Finishes ejecting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `False` will be returned.

Since: 2.22

## enumerateIdentifiers

volumeEnumerateIdentifiers Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m [Text] | Returns: a `Nothing`-terminated array of strings containing kinds of identifiers. Use `strfreev` to free.

Gets the kinds of [identifiers][volume-identifier] that `volume` has. Use `volumeGetIdentifier` to obtain the identifiers themselves.

## getActivationRoot

volumeGetActivationRoot Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m (Maybe File) | Returns: the activation root of `volume` or `Nothing`. Use `objectUnref` to free.

Gets the activation root for a `Volume` if it is known ahead of mount time. Returns `Nothing` otherwise. If not `Nothing` and if `volume` is mounted, then the result of `mountGetRoot` on the `Mount` object obtained from `volumeGetMount` will always either be equal or a prefix of what this function returns. In other words, in code

### C code

     GMount *mount;
     GFile *mount_root
     GFile *volume_activation_root;

     mount = g_volume_get_mount (volume); // mounted, so never NULL
     mount_root = g_mount_get_root (mount);
     volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL

then the expression

### C code

     (g_file_has_prefix (volume_activation_root, mount_root) ||
      g_file_equal (volume_activation_root, mount_root))

will always be `True`.

Activation roots are typically used in `VolumeMonitor` implementations to find the underlying mount to shadow, see `mountIsShadowed` for more details.

Since: 2.18

## getDrive

volumeGetDrive Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m (Maybe Drive) | Returns: a `Drive` or `Nothing` if `volume` is not associated with a drive. The returned object should be unreffed with `objectUnref` when no longer needed.

Gets the drive for the `volume`.

## getIcon

volumeGetIcon Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Icon | Returns: a `Icon`. The returned object should be unreffed with `objectUnref` when no longer needed.

Gets the icon for `volume`.

## getIdentifier

volumeGetIdentifier Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> Text | `kind`: the kind of identifier to return
-> m (Maybe Text) | Returns: a newly allocated string containing the requested identifier, or `Nothing` if the `Volume` doesn't have this kind of identifier

Gets the identifier of the given kind for `volume`. See the [introduction][volume-identifier] for more information about volume identifiers.

## getMount

volumeGetMount Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m (Maybe Mount) | Returns: a `Mount` or `Nothing` if `volume` isn't mounted. The returned object should be unreffed with `objectUnref` when no longer needed.

Gets the mount for the `volume`.

## getName

volumeGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Text | Returns: the name for the given `volume`. The returned string should be freed with `free` when no longer needed.

Gets the name of `volume`.

## getSortKey

volumeGetSortKey Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m (Maybe Text) | Returns: Sorting key for `volume` or `Nothing` if no such key is available

Gets the sort key for `volume`, if any.

Since: 2.32

## getSymbolicIcon

volumeGetSymbolicIcon Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Icon | Returns: a `Icon`. The returned object should be unreffed with `objectUnref` when no longer needed.

Gets the symbolic icon for `volume`.

Since: 2.34

## getUuid

volumeGetUuid Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m (Maybe Text) | Returns: the UUID for `volume` or `Nothing` if no UUID can be computed. The returned string should be freed with `free` when no longer needed.

Gets the UUID for the `volume`. The reference is typically based on the file system UUID for the volume in question and should be considered an opaque string. Returns `Nothing` if there is no UUID available.

## mount

volumeMount Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsMountOperation b, IsCancellable c) |
=> a | `volume`: a `Volume`
-> [MountMountFlags] | `flags`: flags affecting the operation
-> Maybe b | `mountOperation`: a `MountOperation` or `Nothing` to avoid user interaction
-> Maybe c | `cancellable`: optional `Cancellable` object, `Nothing` to ignore
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback`, or `Nothing`
-> m () |

Mounts a volume. This is an asynchronous operation, and is finished by calling `volumeMountFinish` with the `volume` and `AsyncResult` returned in the `callback`.

## mountFinish

volumeMountFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a, IsAsyncResult b) |
=> a | `volume`: a `Volume`
-> b | `result`: a `AsyncResult`
-> m () | (Can throw `GError`)

Finishes mounting a volume. If any errors occurred during the operation, `error` will be set to contain the errors and `False` will be returned.

If the mount operation succeeded, `volumeGetMount` on `volume` is guaranteed to return the mount right after calling this function; there's no need to listen for the 'mount-added' signal on `VolumeMonitor`.

## shouldAutomount

volumeShouldAutomount Source #

Arguments

:: (HasCallStack, MonadIO m, IsVolume a) |
=> a | `volume`: a `Volume`
-> m Bool | Returns: `True` if the volume should be automatically mounted

Returns whether the volume should be automatically mounted.

# Signals

## changed

type C_VolumeChangedCallback = Ptr () -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

type VolumeChangedCallback = IO () Source #

Emitted when the volume has been changed.

afterVolumeChanged :: (IsVolume a, MonadIO m) => a -> VolumeChangedCallback -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after volume #changed callback

genClosure_VolumeChanged :: MonadIO m => VolumeChangedCallback -> m (GClosure C_VolumeChangedCallback) Source #

Wrap the callback into a `GClosure`.

mk_VolumeChangedCallback :: C_VolumeChangedCallback -> IO (FunPtr C_VolumeChangedCallback) Source #

Generate a function pointer callable from C code, from a `C_VolumeChangedCallback`.

noVolumeChangedCallback :: Maybe VolumeChangedCallback Source #

A convenience synonym for ``Nothing` :: `Maybe` `VolumeChangedCallback``.

onVolumeChanged :: (IsVolume a, MonadIO m) => a -> VolumeChangedCallback -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on volume #changed callback

wrap_VolumeChangedCallback :: VolumeChangedCallback -> C_VolumeChangedCallback Source #

Wrap a `VolumeChangedCallback` into a `C_VolumeChangedCallback`.

## removed

type C_VolumeRemovedCallback = Ptr () -> Ptr () -> IO () Source #

Type for the callback on the (unwrapped) C side.

type VolumeRemovedCallback = IO () Source #

This signal is emitted when the `Volume` have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.

afterVolumeRemoved :: (IsVolume a, MonadIO m) => a -> VolumeRemovedCallback -> m SignalHandlerId Source #

Connect a signal handler for the removed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after volume #removed callback

genClosure_VolumeRemoved :: MonadIO m => VolumeRemovedCallback -> m (GClosure C_VolumeRemovedCallback) Source #

Wrap the callback into a `GClosure`.

mk_VolumeRemovedCallback :: C_VolumeRemovedCallback -> IO (FunPtr C_VolumeRemovedCallback) Source #

Generate a function pointer callable from C code, from a `C_VolumeRemovedCallback`.

noVolumeRemovedCallback :: Maybe VolumeRemovedCallback Source #

A convenience synonym for ``Nothing` :: `Maybe` `VolumeRemovedCallback``.

onVolumeRemoved :: (IsVolume a, MonadIO m) => a -> VolumeRemovedCallback -> m SignalHandlerId Source #

Connect a signal handler for the removed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on volume #removed callback

wrap_VolumeRemovedCallback :: VolumeRemovedCallback -> C_VolumeRemovedCallback Source #

Wrap a `VolumeRemovedCallback` into a `C_VolumeRemovedCallback`.