Interface Drive

All Superinterfaces:
Proxy
All Known Implementing Classes:
Drive.Drive$Impl
@Generated("org.javagi.JavaGI") public interface Drive extends Proxy

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 getStartStopType().

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

  • Method Details

    • getType

      static @Nullable Type getType()
      Get the GType of the Drive class.
      Returns:
      the GType

    • canEject

      default boolean canEject()
      Checks if a drive can be ejected.
      Returns:
      true if the this Drive can be ejected, false otherwise.

    • canPollForMedia

      default boolean canPollForMedia()
      Checks if a drive can be polled for media changes.
      Returns:
      true if the this Drive can be polled for media changes, false otherwise.

    • canStart

      default boolean canStart()
      Checks if a drive can be started.
      Returns:
      true if the this Drive can be started, false otherwise.
      Since:
      2.22

    • canStartDegraded

      default boolean canStartDegraded()
      Checks if a drive can be started degraded.
      Returns:
      true if the this Drive can be started degraded, false otherwise.
      Since:
      2.22

    • canStop

      default boolean canStop()
      Checks if a drive can be stopped.
      Returns:
      true if the this Drive can be stopped, false otherwise.
      Since:
      2.22

    • eject

      @Deprecated default void eject(Set<MountUnmountFlags> flags, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
      Deprecated.
      Use g_drive_eject_with_operation() instead.

      Asynchronously ejects a drive.

      When the operation is finished, callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the unmount if required for eject
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.

    • eject

      @Deprecated default void eject(MountUnmountFlags flags, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
      Deprecated.
      Use g_drive_eject_with_operation() instead.

      Asynchronously ejects a drive.

      When the operation is finished, callback will be called. You can then call g_drive_eject_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the unmount if required for eject
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.

    • ejectFinish

      @Deprecated default boolean ejectFinish(AsyncResult result) throws GErrorException
      Deprecated.
      Use g_drive_eject_with_operation_finish() instead.
      Finishes ejecting a drive.
      Parameters:
      result - a GAsyncResult.
      Returns:
      true if the drive has been ejected successfully, false otherwise.
      Throws:
      GErrorException - see GError

    • ejectWithOperation

      default void ejectWithOperation(Set<MountUnmountFlags> flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
      Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the this Drive and GAsyncResult data returned in the callback.
      Parameters:
      flags - flags affecting the unmount if required for eject
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • ejectWithOperation

      default void ejectWithOperation(MountUnmountFlags flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)
      Ejects a drive. This is an asynchronous operation, and is finished by calling g_drive_eject_with_operation_finish() with the this Drive and GAsyncResult data returned in the callback.
      Parameters:
      flags - flags affecting the unmount if required for eject
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • ejectWithOperationFinish

      default boolean ejectWithOperationFinish(AsyncResult result) throws GErrorException
      Finishes ejecting a drive. If any errors occurred during the operation, error will be set to contain the errors and false will be returned.
      Parameters:
      result - a GAsyncResult.
      Returns:
      true if the drive was successfully ejected. false otherwise.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • enumerateIdentifiers

      default String[] enumerateIdentifiers()
      Gets the kinds of identifiers that this Drive has. Use g_drive_get_identifier() to obtain the identifiers themselves.
      Returns:
      a null-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.

    • getIcon

      default Icon getIcon()
      Gets the icon for drive.
      Returns:
      GIcon for the drive. Free the returned object with g_object_unref().

    • getIdentifier

      default @Nullable String getIdentifier(String kind)
      Gets the identifier of the given kind for drive. The only identifier currently available is G_DRIVE_IDENTIFIER_KIND_UNIX_DEVICE.
      Parameters:
      kind - the kind of identifier to return
      Returns:
      a newly allocated string containing the requested identifier, or null if the GDrive doesn't have this kind of identifier.

    • getName

      default String getName()
      Gets the name of drive.
      Returns:
      a string containing drive's name. The returned string should be freed when no longer needed.

    • getSortKey

      default @Nullable String getSortKey()
      Gets the sort key for drive, if any.
      Returns:
      Sorting key for this Drive or null if no such key is available.
      Since:
      2.32

    • getStartStopType

      default DriveStartStopType getStartStopType()
      Gets a hint about how a drive can be started/stopped.
      Returns:
      A value from the GDriveStartStopType enumeration.
      Since:
      2.22

    • getSymbolicIcon

      default Icon getSymbolicIcon()
      Gets the icon for drive.
      Returns:
      symbolic GIcon for the drive. Free the returned object with g_object_unref().
      Since:
      2.34

    • getVolumes

      default List<Volume> getVolumes()

      Get a list of mountable volumes for drive.

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

      Returns:
      GList containing any GVolume objects on the given drive.

    • hasMedia

      default boolean hasMedia()
      Checks if the this Drive has media. Note that the OS may not be polling the drive for media changes; see g_drive_is_media_check_automatic() for more details.
      Returns:
      true if this Drive has media, false otherwise.

    • hasVolumes

      default boolean hasVolumes()
      Check if this Drive has any mountable volumes.
      Returns:
      true if the this Drive contains volumes, false otherwise.

    • isMediaCheckAutomatic

      default boolean isMediaCheckAutomatic()
      Checks if this Drive is capable of automatically detecting media changes.
      Returns:
      true if the this Drive is capable of automatically detecting media changes, false otherwise.

    • isMediaRemovable

      default boolean isMediaRemovable()
      Checks if the this Drive supports removable media.
      Returns:
      true if this Drive supports removable media, false otherwise.

    • isRemovable

      default boolean isRemovable()
      Checks if the GDrive and/or its media is considered removable by the user. See g_drive_is_media_removable().
      Returns:
      true if this Drive and/or its media is considered removable, false otherwise.
      Since:
      2.50

    • pollForMedia

      default void pollForMedia(@Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously polls this Drive to see if media has been inserted or removed.

      When the operation is finished, callback will be called. You can then call g_drive_poll_for_media_finish() to obtain the result of the operation.

      Parameters:
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.

    • pollForMediaFinish

      default boolean pollForMediaFinish(AsyncResult result) throws GErrorException
      Finishes an operation started with g_drive_poll_for_media() on a drive.
      Parameters:
      result - a GAsyncResult.
      Returns:
      true if the drive has been poll_for_mediaed successfully, false otherwise.
      Throws:
      GErrorException - see GError

    • start

      default void start(Set<DriveStartFlags> flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously starts a drive.

      When the operation is finished, callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the start operation.
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • start

      default void start(DriveStartFlags flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously starts a drive.

      When the operation is finished, callback will be called. You can then call g_drive_start_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the start operation.
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • startFinish

      default boolean startFinish(AsyncResult result) throws GErrorException
      Finishes starting a drive.
      Parameters:
      result - a GAsyncResult.
      Returns:
      true if the drive has been started successfully, false otherwise.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • stop

      default void stop(Set<MountUnmountFlags> flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously stops a drive.

      When the operation is finished, callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the unmount if required for stopping.
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • stop

      default void stop(MountUnmountFlags flags, @Nullable MountOperation mountOperation, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)

      Asynchronously stops a drive.

      When the operation is finished, callback will be called. You can then call g_drive_stop_finish() to obtain the result of the operation.

      Parameters:
      flags - flags affecting the unmount if required for stopping.
      mountOperation - a GMountOperation or null to avoid user interaction.
      cancellable - optional GCancellable object, null to ignore.
      callback - a GAsyncReadyCallback, or null.
      Since:
      2.22

    • stopFinish

      default boolean stopFinish(AsyncResult result) throws GErrorException
      Finishes stopping a drive.
      Parameters:
      result - a GAsyncResult.
      Returns:
      true if the drive has been stopped successfully, false otherwise.
      Throws:
      GErrorException - see GError
      Since:
      2.22

    • onChanged

      default SignalConnection<Drive.ChangedCallback> onChanged(Drive.ChangedCallback handler)
      Emitted when the drive's state has changed.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitChanged

      default void emitChanged()
      Emits the "changed" signal. See onChanged(Drive.ChangedCallback).

    • onDisconnected

      default SignalConnection<Drive.DisconnectedCallback> onDisconnected(Drive.DisconnectedCallback handler)
      This signal is emitted when the GDrive have been disconnected. If the recipient is holding references to the object they should release them so the object can be finalized.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitDisconnected

      default void emitDisconnected()
      Emits the "disconnected" signal. See onDisconnected(Drive.DisconnectedCallback).

    • onEjectButton

      default SignalConnection<Drive.EjectButtonCallback> onEjectButton(Drive.EjectButtonCallback handler)
      Emitted when the physical eject button (if any) of a drive has been pressed.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      See Also:

    • emitEjectButton

      default void emitEjectButton()
      Emits the "eject-button" signal. See onEjectButton(Drive.EjectButtonCallback).

    • onStopButton

      default SignalConnection<Drive.StopButtonCallback> onStopButton(Drive.StopButtonCallback handler)
      Emitted when the physical stop button (if any) of a drive has been pressed.
      Parameters:
      handler - the signal handler
      Returns:
      a signal handler ID to keep track of the signal connection
      Since:
      2.22
      See Also:

    • emitStopButton

      default void emitStopButton()
      Emits the "stop-button" signal. See onStopButton(Drive.StopButtonCallback).