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

  GFlags
   +----GAskPasswordFlags

  GEnum
   +----GPasswordSave

  GObject
   +----GMountOperation

  GEnum
   +----GMountOperationResult

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.
Generated by GTK-Doc V1.18