## GMountOperation GMountOperation — Authentication methods for mountable locations |

## Synopsis

    #include <gio/gio.h>

    enum                GAskPasswordFlags;
    enum                GPasswordSave;
                        GMountOperation;
    enum                GMountOperationResult;
    GMountOperation *   g_mount_operation_new               (void);
    const char *        g_mount_operation_get_username      (GMountOperation *op);
    void                g_mount_operation_set_username      (GMountOperation *op,
                                                             const char *username);
    const char *        g_mount_operation_get_password      (GMountOperation *op);
    void                g_mount_operation_set_password      (GMountOperation *op,
                                                             const char *password);
    gboolean            g_mount_operation_get_anonymous     (GMountOperation *op);
    void                g_mount_operation_set_anonymous     (GMountOperation *op,
                                                             gboolean anonymous);
    const char *        g_mount_operation_get_domain        (GMountOperation *op);
    void                g_mount_operation_set_domain        (GMountOperation *op,
                                                             const char *domain);
    GPasswordSave       g_mount_operation_get_password_save (GMountOperation *op);
    void                g_mount_operation_set_password_save (GMountOperation *op,
                                                             GPasswordSave save);
    int                 g_mount_operation_get_choice        (GMountOperation *op);
    void                g_mount_operation_set_choice        (GMountOperation *op,
                                                             int choice);
    void                g_mount_operation_reply             (GMountOperation *op,
                                                             GMountOperationResult result);

## Object Hierarchy

      GObject
       +----GMountOperation

## Properties

      "anonymous"                gboolean              : Read / Write
      "choice"                   gint                  : Read / Write
      "domain"                   gchar*                : Read / Write
      "password"                 gchar*                : Read / Write
      "password-save"            GPasswordSave         : Read / Write
      "username"                 gchar*                : Read / Write

## Signals

      "aborted"                                        : Run Last
      "ask-password"                                   : Run Last
      "ask-question"                                   : Run Last
      "reply"                                          : Run Last

## Description

GMountOperation provides a mechanism for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations.

Mounting operations are handed a GMountOperation that then can use if they require any privileges or authentication for their volumes to be mounted (e.g. a hard disk partition or an encrypted filesystem), or if they are implementing a remote server protocol which requires user credentials such as FTP or WebDAV.

Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as GtkMountOperation.

## Details

### enum GAskPasswordFlags

    typedef enum {
      G_ASK_PASSWORD_NEED_PASSWORD       = (1 << 0),
      G_ASK_PASSWORD_NEED_USERNAME       = (1 << 1),
      G_ASK_PASSWORD_NEED_DOMAIN         = (1 << 2),
      G_ASK_PASSWORD_SAVING_SUPPORTED    = (1 << 3),
      G_ASK_PASSWORD_ANONYMOUS_SUPPORTED = (1 << 4)
    } GAskPasswordFlags;

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

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

### enum GPasswordSave

    typedef enum {
      G_PASSWORD_SAVE_NEVER,
      G_PASSWORD_SAVE_FOR_SESSION,
      G_PASSWORD_SAVE_PERMANENTLY
    } 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.

`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

    typedef enum {
      G_MOUNT_OPERATION_HANDLED,
      G_MOUNT_OPERATION_ABORTED,
      G_MOUNT_OPERATION_UNHANDLED
    } GMountOperationResult;

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

`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)

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

`op` : | a GMountOperation.
Returns : | a string containing the user name.

### g_mount_operation_set_username ()

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

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

`op` : | a GMountOperation.
`username` : | input username.

### g_mount_operation_get_password ()

    const char *        g_mount_operation_get_password      (GMountOperation *op);

Gets a password from the mount operation.

`op` : | a GMountOperation.
Returns : | a string containing the password within `op`.

### g_mount_operation_set_password ()

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

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

`op` : | a GMountOperation.
`password` : | password to set.

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

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

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

`op` : | a GMountOperation.
Returns : | a string set to the domain.

### g_mount_operation_set_domain ()

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

Sets the mount operation's domain.

`op` : | a GMountOperation.
`domain` : | the domain to set.

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

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

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

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

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

### g_mount_operation_reply ()

    void                g_mount_operation_reply             (GMountOperation *op,
                                                             GMountOperationResult result);

Emits the "reply" signal.

`op` : | a GMountOperation
`result` : | a GMountOperationResult

## Property Details

### The `"anonymous"` property

      "anonymous"                gboolean              : Read / Write

Whether to use an anonymous user when authenticating.

Default value: FALSE

### The `"choice"` property

      "choice"                   gint                  : Read / Write

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

Allowed values: >= 0

Default value: 0

### The `"domain"` property

      "domain"                   gchar*                : Read / Write

The domain to use for the mount operation.

Default value: NULL

### The `"password"` property

      "password"                 gchar*                : Read / Write

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

Default value: NULL

### The `"password-save"` property

      "password-save"            GPasswordSave         : Read / Write

Determines if and how the password information should be saved.

Default value: G_PASSWORD_SAVE_NEVER

### The `"username"` property

      "username"                 gchar*                : Read / Write

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

Default value: NULL

## Signal Details

### The `"aborted"` signal

    void                user_function                      (GMountOperation *arg0,
                                                            gpointer         user_data)      : Run Last

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.

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

Since 2.20

### The `"ask-password"` signal

    void                user_function                      (GMountOperation  *op,
                                                            gchar            *message,
                                                            gchar            *default_user,
                                                            gchar            *default_domain,
                                                            GAskPasswordFlags flags,
                                                            gpointer          user_data)           : Run Last

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.

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

### The `"ask-question"` signal

    void                user_function                      (GMountOperation *op,
                                                            gchar           *message,
                                                            GStrv           *choices,
                                                            gpointer         user_data)      : Run Last

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.

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

### The `"reply"` signal

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

Emitted when the user has replied to the mount operation.

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