GMountOperation: GIO Reference Manual

## GMountOperation GMountOperation — Object used for authentication and user interaction |

## Functions

GMountOperation * | g_mount_operation_new ()
const char * | g_mount_operation_get_username ()
void | g_mount_operation_set_username ()
const char * | g_mount_operation_get_password ()
void | g_mount_operation_set_password ()
gboolean | g_mount_operation_get_anonymous ()
void | g_mount_operation_set_anonymous ()
const char * | g_mount_operation_get_domain ()
void | g_mount_operation_set_domain ()
GPasswordSave | g_mount_operation_get_password_save ()
void | g_mount_operation_set_password_save ()
int | g_mount_operation_get_choice ()
void | g_mount_operation_set_choice ()
gboolean | g_mount_operation_get_is_tcrypt_hidden_volume ()
void | g_mount_operation_set_is_tcrypt_hidden_volume ()
gboolean | g_mount_operation_get_is_tcrypt_system_volume ()
void | g_mount_operation_set_is_tcrypt_system_volume ()
guint | g_mount_operation_get_pim ()
void | g_mount_operation_set_pim ()
void | g_mount_operation_reply ()

## Properties

gboolean | anonymous | Read / Write
int | choice | Read / Write
char * | domain | Read / Write
gboolean | is-tcrypt-hidden-volume | Read / Write
gboolean | is-tcrypt-system-volume | Read / Write
char * | password | Read / Write
GPasswordSave | password-save | Read / Write
guint | pim | Read / Write
char * | username | Read / Write

## Signals

void | aborted | Run Last
void | ask-password | Run Last
void | ask-question | Run Last
void | reply | Run Last
void | show-processes | Run Last
void | show-unmount-progress | Run Last

## Types and Values

enum | GAskPasswordFlags
enum | GPasswordSave
| GMountOperation
enum | GMountOperationResult

## Object Hierarchy

        GEnum
        ├── GMountOperationResult
        ╰── GPasswordSave
        GFlags
        ╰── GAskPasswordFlags
        GObject
        ╰── GMountOperation

## Includes

    #include <gio/gio.h>

## Description

GMountOperation provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing.

Note that GMountOperation is used for more than just GMount objects – for example it is also used in `g_drive_start()` and `g_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 `NULL` can be passed, see each method taking a GMountOperation for details.

The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. TrueCrypt is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. VeraCrypt is a maintained fork of TrueCrypt with various improvements and auditing fixes.

## Functions

### g_mount_operation_new ()

    GMountOperation *
    g_mount_operation_new (void);

Creates a new mount operation.

#### Returns

a GMountOperation.

### g_mount_operation_get_username ()

    const char *
    g_mount_operation_get_username (GMountOperation *op);

Get the user name from the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

a string containing the user name.

[nullable]

### g_mount_operation_set_username ()

    void
    g_mount_operation_set_username (GMountOperation *op,
                                    const char *username);

Sets the user name within `op` to `username` .

#### Parameters

op | a GMountOperation. |
username | input username. | [nullable]

### g_mount_operation_get_password ()

    const char *
    g_mount_operation_get_password (GMountOperation *op);

Gets a password from the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

a string containing the password within `op` .

[nullable]

### g_mount_operation_set_password ()

    void
    g_mount_operation_set_password (GMountOperation *op,
                                    const char *password);

Sets the mount operation's password to `password` .

#### Parameters

op | a GMountOperation. |
password | password to set. | [nullable]

### g_mount_operation_get_anonymous ()

    gboolean
    g_mount_operation_get_anonymous (GMountOperation *op);

Check to see whether the mount operation is being used for an anonymous user.

#### Parameters

op | a GMountOperation. |

#### Returns

`TRUE` if mount operation is anonymous.

### g_mount_operation_set_anonymous ()

    void
    g_mount_operation_set_anonymous (GMountOperation *op,
                                     gboolean anonymous);

Sets the mount operation to use an anonymous user if `anonymous` is `TRUE`.

#### Parameters

op | a GMountOperation. |
anonymous | boolean value. |

### g_mount_operation_get_domain ()

    const char *
    g_mount_operation_get_domain (GMountOperation *op);

Gets the domain of the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

a string set to the domain.

[nullable]

### g_mount_operation_set_domain ()

    void
    g_mount_operation_set_domain (GMountOperation *op,
                                  const char *domain);

Sets the mount operation's domain.

#### Parameters

op | a GMountOperation. |
domain | the domain to set. | [nullable]

### g_mount_operation_get_password_save ()

    GPasswordSave
    g_mount_operation_get_password_save (GMountOperation *op);

Gets the state of saving passwords for the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

a GPasswordSave flag.

### g_mount_operation_set_password_save ()

    void
    g_mount_operation_set_password_save (GMountOperation *op,
                                         GPasswordSave save);

Sets the state of saving passwords for the mount operation.

#### Parameters

op | a GMountOperation. |
save | a set of GPasswordSave flags. |

### g_mount_operation_get_choice ()

    int
    g_mount_operation_get_choice (GMountOperation *op);

Gets a choice from the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

an integer containing an index of the user's choice from the choice's list, or `0`.

### g_mount_operation_set_choice ()

    void
    g_mount_operation_set_choice (GMountOperation *op,
                                  int choice);

Sets a default choice for the mount operation.

#### Parameters

op | a GMountOperation. |
choice | an integer. |

### g_mount_operation_get_is_tcrypt_hidden_volume ()

    gboolean
    g_mount_operation_get_is_tcrypt_hidden_volume
                                   (GMountOperation *op);

Check to see whether the mount operation is being used for a TCRYPT hidden volume.

#### Parameters

op | a GMountOperation. |

#### Returns

`TRUE` if mount operation is for hidden volume.

Since: 2.58

### g_mount_operation_set_is_tcrypt_hidden_volume ()

    void
    g_mount_operation_set_is_tcrypt_hidden_volume
                                   (GMountOperation *op,
                                    gboolean hidden_volume);

Sets the mount operation to use a hidden volume if `hidden_volume` is `TRUE`.

#### Parameters

op | a GMountOperation. |
hidden_volume | boolean value. |

Since: 2.58

### g_mount_operation_get_is_tcrypt_system_volume ()

    gboolean
    g_mount_operation_get_is_tcrypt_system_volume
                                   (GMountOperation *op);

Check to see whether the mount operation is being used for a TCRYPT system volume.

#### Parameters

op | a GMountOperation. |

#### Returns

`TRUE` if mount operation is for system volume.

Since: 2.58

### g_mount_operation_set_is_tcrypt_system_volume ()

    void
    g_mount_operation_set_is_tcrypt_system_volume
                                   (GMountOperation *op,
                                    gboolean system_volume);

Sets the mount operation to use a system volume if `system_volume` is `TRUE`.

#### Parameters

op | a GMountOperation. |
system_volume | boolean value. |

Since: 2.58

### g_mount_operation_get_pim ()

    guint
    g_mount_operation_get_pim (GMountOperation *op);

Gets a PIM from the mount operation.

#### Parameters

op | a GMountOperation. |

#### Returns

The VeraCrypt PIM within `op` .

Since: 2.58

### g_mount_operation_set_pim ()

    void
    g_mount_operation_set_pim (GMountOperation *op,
                               guint pim);

Sets the mount operation's PIM to `pim` .

#### Parameters

op | a GMountOperation. |
pim | an unsigned integer. |

Since: 2.58

### g_mount_operation_reply ()

    void
    g_mount_operation_reply (GMountOperation *op,
                             GMountOperationResult result);

Emits the “reply” signal.

#### Parameters

op | a GMountOperation |
result | a GMountOperationResult |

## Types and Values

### enum GAskPasswordFlags

GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation.

#### Members

G_ASK_PASSWORD_NEED_PASSWORD | operation requires a password. |
G_ASK_PASSWORD_NEED_USERNAME | operation requires a username. |
G_ASK_PASSWORD_NEED_DOMAIN | operation requires a domain. |
G_ASK_PASSWORD_SAVING_SUPPORTED | operation supports saving settings. |
G_ASK_PASSWORD_ANONYMOUS_SUPPORTED | operation supports anonymous users. |
G_ASK_PASSWORD_TCRYPT | operation takes TCRYPT parameters (Since: 2.58) |

### enum GPasswordSave

GPasswordSave 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.

#### Members

G_PASSWORD_SAVE_NEVER | never save a password. |
G_PASSWORD_SAVE_FOR_SESSION | save a password for the session. |
G_PASSWORD_SAVE_PERMANENTLY | save a password permanently. |

### GMountOperation

    typedef struct _GMountOperation GMountOperation;

Class for providing authentication methods for mounting operations, such as mounting a file locally, or authenticating with a server.

### enum GMountOperationResult

GMountOperationResult is returned as a result when a request for information is send by the mounting operation.

#### Members

G_MOUNT_OPERATION_HANDLED | The request was fulfilled and the user specified data is now available |
G_MOUNT_OPERATION_ABORTED | The user requested the mount operation to be aborted |
G_MOUNT_OPERATION_UNHANDLED | The request was unhandled (i.e. not implemented) |

## Property Details

### The `“anonymous”` property

      “anonymous”                gboolean

Whether to use an anonymous user when authenticating.

Owner: GMountOperation

Flags: Read / Write

Default value: FALSE

### The `“choice”` property

      “choice”                   int

The index of the user's choice when a question is asked during the mount operation. See the “ask-question” signal.

Owner: GMountOperation

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“domain”` property

      “domain”                   char *

The domain to use for the mount operation.

Owner: GMountOperation

Flags: Read / Write

Default value: NULL

### The `“is-tcrypt-hidden-volume”` property

      “is-tcrypt-hidden-volume”  gboolean

Whether the device to be unlocked is a TCRYPT hidden volume. See the VeraCrypt documentation.

Owner: GMountOperation

Flags: Read / Write

Default value: FALSE

Since: 2.58

### The `“is-tcrypt-system-volume”` property

      “is-tcrypt-system-volume”  gboolean

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 the VeraCrypt documentation.

Owner: GMountOperation

Flags: Read / Write

Default value: FALSE

Since: 2.58

### The `“password”` property

      “password”                 char *

The password that is used for authentication when carrying out the mount operation.

Owner: GMountOperation

Flags: Read / Write

Default value: NULL

### The `“password-save”` property

      “password-save”            GPasswordSave

Determines if and how the password information should be saved.

Owner: GMountOperation

Flags: Read / Write

Default value: G_PASSWORD_SAVE_NEVER

### The `“pim”` property

      “pim”                      guint

The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See the VeraCrypt documentation.html).

Owner: GMountOperation

Flags: Read / Write

Default value: 0

Since: 2.58

### The `“username”` property

      “username”                 char *

The user name that is used for authentication when carrying out the mount operation.

Owner: GMountOperation

Flags: Read / Write

Default value: NULL

## Signal Details

### The `“aborted”` signal

    void
    user_function (GMountOperation *gmountoperation,
                   gpointer         user_data)

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.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.20

### The `“ask-password”` signal

    void
    user_function (GMountOperation  *op,
                   char             *message,
                   char             *default_user,
                   char             *default_domain,
                   GAskPasswordFlags flags,
                   gpointer          user_data)

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.

#### Parameters

op | a GMountOperation requesting a password. |
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 GAskPasswordFlags. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“ask-question”` signal

    void
    user_function (GMountOperation *op,
                   char            *message,
                   GStrv            choices,
                   gpointer         user_data)

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.

#### Parameters

op | a GMountOperation asking a question. |
message | string containing a message to display to the user. |
choices | an array of strings for each possible choice. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“reply”` signal

    void
    user_function (GMountOperation      *op,
                   GMountOperationResult result,
                   gpointer              user_data)

Emitted when the user has replied to the mount operation.

#### Parameters

op | a GMountOperation. |
result | a GMountOperationResult indicating how the request was handled |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

### The `“show-processes”` signal

    void
    user_function (GMountOperation *op,
                   char            *message,
                   GArray          *processes,
                   GStrv            choices,
                   gpointer         user_data)

Emitted when one or more processes are blocking an operation e.g. unmounting/ejecting a GMount or stopping a GDrive.

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 `g_mount_operation_reply()` to the latest signal (setting “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.

#### Parameters

op | a GMountOperation. |
message | string containing a message to display to the user. |
processes | an array of GPid for processes blocking the operation. | [element-type GPid]
choices | an array of strings for each possible choice. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.22

### The `“show-unmount-progress”` signal

    void
    user_function (GMountOperation *op,
                   char            *message,
                   gint64           time_left,
                   gint64           bytes_left,
                   gpointer         user_data)

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.

#### Parameters

op | a GMountOperation: |
message | string containing a message 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 |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 2.34