GMountOperation

GMountOperation — Object used for authentication and user interaction

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
  "show-processes"                                 : Run Last

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.

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.

The "show-processes" signal

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

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.

op :

 a GMountOperation.

message :

 string containing a message to display to the user.

processes :

 an array of GPid for processes blocking the operation.

choices :

 an array of strings for each possible choice.

user_data :

 user data set when the signal handler was connected.

Since 2.22

Generated by GTK-Doc V1.14