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 ()
void	g_mount_operation_reply ()

Properties

gboolean	anonymous	Read / Write
gint	choice	Read / Write
gchar *	domain	Read / Write
gchar *	password	Read / Write
GPasswordSave	password-save	Read / Write
gchar *	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

    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.

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

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 .

Parameters

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.

Parameters

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 .

Parameters

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.

Parameters

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

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.

Parameters

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.

Parameters

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

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

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.

Flags: Read / Write

Default value: FALSE

The `“choice”` property

  “choice”                   gint

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

Flags: Read / Write

Allowed values: >= 0

Default value: 0

The `“domain”` property

  “domain”                   gchar *

The domain to use for the mount operation.

Flags: Read / Write

Default value: NULL

The `“password”` property

  “password”                 gchar *

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

Flags: Read / Write

Default value: NULL

The `“password-save”` property

  “password-save”            GPasswordSave

Determines if and how the password information should be saved.

Flags: Read / Write

Default value: G_PASSWORD_SAVE_NEVER

The `“username”` property

  “username”                 gchar *

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

Flags: Read / Write

Default value: NULL

Signal Details

The `“aborted”` signal

void
user_function (GMountOperation *arg0,
               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,
               gchar            *message,
               gchar            *default_user,
               gchar            *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,
               gchar           *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,
               gchar           *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,
               gchar           *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 mesage 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

GMountOperation

Functions

Properties

Signals

Types and Values

Object Hierarchy

Includes

Description

Functions

g_mount_operation_new ()

Returns

g_mount_operation_get_username ()

Parameters

Returns

g_mount_operation_set_username ()

Parameters

g_mount_operation_get_password ()

Parameters

Returns

g_mount_operation_set_password ()

Parameters

g_mount_operation_get_anonymous ()

Parameters

Returns

g_mount_operation_set_anonymous ()

Parameters

g_mount_operation_get_domain ()

Parameters

Returns

g_mount_operation_set_domain ()

Parameters

g_mount_operation_get_password_save ()

Parameters

Returns

g_mount_operation_set_password_save ()

Parameters

g_mount_operation_get_choice ()

Parameters

Returns

g_mount_operation_set_choice ()

Parameters

g_mount_operation_reply ()

Parameters

Types and Values

enum GAskPasswordFlags

Members

enum GPasswordSave

Members

GMountOperation

enum GMountOperationResult

Members

Property Details

The “anonymous” property

The “choice” property

The “domain” property

The “password” property

The “password-save” property

The “username” property

Signal Details

The “aborted” signal

Parameters

The “ask-password” signal

Parameters

The “ask-question” signal

Parameters

The “reply” signal

Parameters

The “show-processes” signal

Parameters

The “show-unmount-progress” signal

Parameters

The `“anonymous”` property

The `“choice”` property

The `“domain”` property

The `“password”` property

The `“password-save”` property

The `“username”` property

The `“aborted”` signal

The `“ask-password”` signal

The `“ask-question”` signal

The `“reply”` signal

The `“show-processes”` signal

The `“show-unmount-progress”` signal