gi-gio-2.0.38: Gio bindings

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

GI.Gio.Interfaces.Drive

Contents

- Exported types
- Methods
  - canEject
  - canPollForMedia
  - canStart
  - canStartDegraded
  - canStop
  - eject
  - ejectFinish
  - ejectWithOperation
  - ejectWithOperationFinish
  - enumerateIdentifiers
  - getIcon
  - getIdentifier
  - getName
  - getSortKey
  - getStartStopType
  - getSymbolicIcon
  - getVolumes
  - hasMedia
  - hasVolumes
  - isMediaCheckAutomatic
  - isMediaRemovable
  - isRemovable
  - pollForMedia
  - pollForMediaFinish
  - start
  - startFinish
  - stop
  - stopFinish
- Signals
  - changed
  - disconnected
  - ejectButton
  - stopButton

Description

`GDrive` represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with removable media. For example, an optical disc drive, or a USB flash drive.

`GDrive` is a container class for `Volume` objects that stem from the same piece of media. As such, `GDrive` abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media.

If the `GDrive` reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise.

`GDrive` supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual semantics and side-effects of starting/stopping a `GDrive` may vary according to implementation. To choose the correct verbs in e.g. a file manager, use `driveGetStartStopType`.

For porting from GnomeVFS note that there is no equivalent of `GDrive` in that API.

Synopsis

- newtype Drive = Drive (ManagedPtr Drive)
- class (GObject o, IsDescendantOf Drive o) => IsDrive o
- toDrive :: (MonadIO m, IsDrive o) => o -> m Drive
- driveCanEject :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveCanPollForMedia :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveCanStart :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveCanStartDegraded :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveCanStop :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveEject :: (HasCallStack, MonadIO m, IsDrive a, IsCancellable b) => a -> [MountUnmountFlags] -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- driveEjectFinish :: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) => a -> b -> m ()
- driveEjectWithOperation :: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) => a -> [MountUnmountFlags] -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- driveEjectWithOperationFinish :: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) => a -> b -> m ()
- driveEnumerateIdentifiers :: (HasCallStack, MonadIO m, IsDrive a) => a -> m [Text]
- driveGetIcon :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Icon
- driveGetIdentifier :: (HasCallStack, MonadIO m, IsDrive a) => a -> Text -> m (Maybe Text)
- driveGetName :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Text
- driveGetSortKey :: (HasCallStack, MonadIO m, IsDrive a) => a -> m (Maybe Text)
- driveGetStartStopType :: (HasCallStack, MonadIO m, IsDrive a) => a -> m DriveStartStopType
- driveGetSymbolicIcon :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Icon
- driveGetVolumes :: (HasCallStack, MonadIO m, IsDrive a) => a -> m [Volume]
- driveHasMedia :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveHasVolumes :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveIsMediaCheckAutomatic :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveIsMediaRemovable :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- driveIsRemovable :: (HasCallStack, MonadIO m, IsDrive a) => a -> m Bool
- drivePollForMedia :: (HasCallStack, MonadIO m, IsDrive a, IsCancellable b) => a -> Maybe b -> Maybe AsyncReadyCallback -> m ()
- drivePollForMediaFinish :: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) => a -> b -> m ()
- driveStart :: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) => a -> [DriveStartFlags] -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- driveStartFinish :: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) => a -> b -> m ()
- driveStop :: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) => a -> [MountUnmountFlags] -> Maybe b -> Maybe c -> Maybe AsyncReadyCallback -> m ()
- driveStopFinish :: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) => a -> b -> m ()
- type DriveChangedCallback = IO ()
- afterDriveChanged :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveChangedCallback) -> m SignalHandlerId
- onDriveChanged :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveChangedCallback) -> m SignalHandlerId
- type DriveDisconnectedCallback = IO ()
- afterDriveDisconnected :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveDisconnectedCallback) -> m SignalHandlerId
- onDriveDisconnected :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveDisconnectedCallback) -> m SignalHandlerId
- type DriveEjectButtonCallback = IO ()
- afterDriveEjectButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveEjectButtonCallback) -> m SignalHandlerId
- onDriveEjectButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveEjectButtonCallback) -> m SignalHandlerId
- type DriveStopButtonCallback = IO ()
- afterDriveStopButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveStopButtonCallback) -> m SignalHandlerId
- onDriveStopButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveStopButtonCallback) -> m SignalHandlerId

# Exported types

newtype Drive Source #

Memory-managed wrapper type.

Constructors

Drive (ManagedPtr Drive) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf Drive o) => IsDrive o Source #

Type class for types which can be safely cast to `Drive`, for instance with `toDrive`.

#### Instances

Instances details

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

toDrive :: (MonadIO m, IsDrive o) => o -> m Drive Source #

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

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, canEject, canPollForMedia, canStart, canStartDegraded, canStop, eject, ejectFinish, ejectWithOperation, ejectWithOperationFinish, enumerateIdentifiers, forceFloating, freezeNotify, getv, hasMedia, hasVolumes, isFloating, isMediaCheckAutomatic, isMediaRemovable, isRemovable, notify, notifyByPspec, pollForMedia, pollForMediaFinish, ref, refSink, runDispose, start, startFinish, stealData, stealQdata, stop, stopFinish, thawNotify, unref, watchClosure.

#### Getters

getData, getIcon, getIdentifier, getName, getProperty, getQdata, getSortKey, getStartStopType, getSymbolicIcon, getVolumes.

#### Setters

setData, setDataFull, setProperty.

## canEject

driveCanEject Source #

Arguments

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

Checks if a drive can be ejected.

## canPollForMedia

driveCanPollForMedia Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` can be polled for media changes, `False` otherwise.

Checks if a drive can be polled for media changes.

## canStart

driveCanStart Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` can be started, `False` otherwise.

Checks if a drive can be started.

Since: 2.22

## canStartDegraded

driveCanStartDegraded Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` can be started degraded, `False` otherwise.

Checks if a drive can be started degraded.

Since: 2.22

## canStop

driveCanStop Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` can be stopped, `False` otherwise.

Checks if a drive can be stopped.

Since: 2.22

## eject

driveEject Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsCancellable b) |
=> a | `drive`: a `Drive`.
-> [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 `driveEjectWithOperation` instead.

Asynchronously ejects a drive.

When the operation is finished, `callback` will be called. You can then call `driveEjectFinish` to obtain the result of the operation.

## ejectFinish

driveEjectFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) |
=> a | `drive`: a `Drive`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

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

Finishes ejecting a drive.

## ejectWithOperation

driveEjectWithOperation Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) |
=> a | `drive`: a `Drive`.
-> [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 drive. This is an asynchronous operation, and is finished by calling `driveEjectWithOperationFinish` with the `drive` and `AsyncResult` data returned in the `callback`.

Since: 2.22

## ejectWithOperationFinish

driveEjectWithOperationFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) |
=> a | `drive`: a `Drive`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

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

Since: 2.22

## enumerateIdentifiers

driveEnumerateIdentifiers Source #

Arguments

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

Gets the kinds of identifiers that `drive` has. Use `driveGetIdentifier` to obtain the identifiers themselves.

## getIcon

driveGetIcon Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Icon | Returns: `Icon` for the `drive`. Free the returned object with `objectUnref`.

Gets the icon for `drive`.

## getIdentifier

driveGetIdentifier Source #

Arguments

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

Gets the identifier of the given kind for `drive`. The only identifier currently available is `DRIVE_IDENTIFIER_KIND_UNIX_DEVICE`.

## getName

driveGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Text | Returns: a string containing `drive`'s name. The returned string should be freed when no longer needed.

Gets the name of `drive`.

## getSortKey

driveGetSortKey Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: A `Drive`.
-> m (Maybe Text) | Returns: Sorting key for `drive` or `Nothing` if no such key is available.

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

Since: 2.32

## getStartStopType

driveGetStartStopType Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m DriveStartStopType | Returns: A value from the `DriveStartStopType` enumeration.

Gets a hint about how a drive can be started/stopped.

Since: 2.22

## getSymbolicIcon

driveGetSymbolicIcon Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Icon | Returns: symbolic `Icon` for the `drive`. Free the returned object with `objectUnref`.

Gets the icon for `drive`.

Since: 2.34

## getVolumes

driveGetVolumes Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m [Volume] | Returns: `List` containing any `Volume` objects on the given `drive`.

Get a list of mountable volumes for `drive`.

The returned list should be freed with `g_list_free()`, after its elements have been unreffed with `objectUnref`.

## hasMedia

driveHasMedia Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if `drive` has media, `False` otherwise.

Checks if the `drive` has media. Note that the OS may not be polling the drive for media changes; see `driveIsMediaCheckAutomatic` for more details.

## hasVolumes

driveHasVolumes Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` contains volumes, `False` otherwise.

Check if `drive` has any mountable volumes.

## isMediaCheckAutomatic

driveIsMediaCheckAutomatic Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if the `drive` is capable of automatically detecting media changes, `False` otherwise.

Checks if `drive` is capable of automatically detecting media changes.

## isMediaRemovable

driveIsMediaRemovable Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if `drive` supports removable media, `False` otherwise.

Checks if the `drive` supports removable media.

## isRemovable

driveIsRemovable Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a) |
=> a | `drive`: a `Drive`.
-> m Bool | Returns: `True` if `drive` and/or its media is considered removable, `False` otherwise.

Checks if the `Drive` and/or its media is considered removable by the user. See `driveIsMediaRemovable`.

Since: 2.50

## pollForMedia

drivePollForMedia Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsCancellable b) |
=> a | `drive`: a `Drive`.
-> Maybe b | `cancellable`: optional `Cancellable` object, `Nothing` to ignore.
-> Maybe AsyncReadyCallback | `callback`: a `AsyncReadyCallback`, or `Nothing`.
-> m () |

Asynchronously polls `drive` to see if media has been inserted or removed.

When the operation is finished, `callback` will be called. You can then call `drivePollForMediaFinish` to obtain the result of the operation.

## pollForMediaFinish

drivePollForMediaFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) |
=> a | `drive`: a `Drive`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

Finishes an operation started with `drivePollForMedia` on a drive.

## start

driveStart Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) |
=> a | `drive`: a `Drive`.
-> [DriveStartFlags] | `flags`: flags affecting the start 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 () |

Asynchronously starts a drive.

When the operation is finished, `callback` will be called. You can then call `driveStartFinish` to obtain the result of the operation.

Since: 2.22

## startFinish

driveStartFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) |
=> a | `drive`: a `Drive`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

Finishes starting a drive.

Since: 2.22

## stop

driveStop Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsMountOperation b, IsCancellable c) |
=> a | `drive`: a `Drive`.
-> [MountUnmountFlags] | `flags`: flags affecting the unmount if required for stopping.
-> 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 () |

Asynchronously stops a drive.

When the operation is finished, `callback` will be called. You can then call `driveStopFinish` to obtain the result of the operation.

Since: 2.22

## stopFinish

driveStopFinish Source #

Arguments

:: (HasCallStack, MonadIO m, IsDrive a, IsAsyncResult b) |
=> a | `drive`: a `Drive`.
-> b | `result`: a `AsyncResult`.
-> m () | (Can throw `GError`)

Finishes stopping a drive.

Since: 2.22

# Signals

## changed

type DriveChangedCallback = IO () Source #

Emitted when the drive's state has changed.

afterDriveChanged :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveChangedCallback) -> 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 drive #changed callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDriveChanged :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveChangedCallback) -> 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 drive #changed callback

## disconnected

type DriveDisconnectedCallback = IO () Source #

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

afterDriveDisconnected :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveDisconnectedCallback) -> m SignalHandlerId Source #

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

    after drive #disconnected callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDriveDisconnected :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveDisconnectedCallback) -> m SignalHandlerId Source #

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

    on drive #disconnected callback

## ejectButton

type DriveEjectButtonCallback = IO () Source #

Emitted when the physical eject button (if any) of a drive has been pressed.

afterDriveEjectButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveEjectButtonCallback) -> m SignalHandlerId Source #

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

    after drive #ejectButton callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDriveEjectButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveEjectButtonCallback) -> m SignalHandlerId Source #

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

    on drive #ejectButton callback

## stopButton

type DriveStopButtonCallback = IO () Source #

Emitted when the physical stop button (if any) of a drive has been pressed.

Since: 2.22

afterDriveStopButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveStopButtonCallback) -> m SignalHandlerId Source #

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

    after drive #stopButton callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onDriveStopButton :: (IsDrive a, MonadIO m) => a -> ((?self :: a) => DriveStopButtonCallback) -> m SignalHandlerId Source #

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

    on drive #stopButton callback