1/* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright (C) 2006-2007 Red Hat, Inc.
4 *
5 * SPDX-License-Identifier: LGPL-2.1-or-later
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 *
20 * Author: Alexander Larsson <alexl@redhat.com>
21 * David Zeuthen <davidz@redhat.com>
22 */
23
24#ifndef __G_VOLUME_H__
25#define __G_VOLUME_H__
26
27#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
28#error "Only <gio/gio.h> can be included directly."
29#endif
30
31#include <gio/giotypes.h>
32
33G_BEGIN_DECLS
34
35/**
36 * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
37 *
38 * The string used to obtain a Hal UDI with g_volume_get_identifier().
39 *
40 * Deprecated: 2.58: Do not use, HAL is deprecated.
41 */
42#define G_VOLUME_IDENTIFIER_KIND_HAL_UDI "hal-udi" GIO_DEPRECATED_MACRO_IN_2_58
43
44/**
45 * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
46 *
47 * The string used to obtain a Unix device path with g_volume_get_identifier().
48 */
49#define G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE "unix-device"
50
51/**
52 * G_VOLUME_IDENTIFIER_KIND_LABEL:
53 *
54 * The string used to obtain a filesystem label with g_volume_get_identifier().
55 */
56#define G_VOLUME_IDENTIFIER_KIND_LABEL "label"
57
58/**
59 * G_VOLUME_IDENTIFIER_KIND_UUID:
60 *
61 * The string used to obtain a UUID with g_volume_get_identifier().
62 */
63#define G_VOLUME_IDENTIFIER_KIND_UUID "uuid"
64
65/**
66 * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
67 *
68 * The string used to obtain a NFS mount with g_volume_get_identifier().
69 */
70#define G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT "nfs-mount"
71
72/**
73 * G_VOLUME_IDENTIFIER_KIND_CLASS:
74 *
75 * The string used to obtain the volume class with g_volume_get_identifier().
76 *
77 * Known volume classes include `device`, `network`, and `loop`. Other
78 * classes may be added in the future.
79 *
80 * This is intended to be used by applications to classify #GVolume
81 * instances into different sections - for example a file manager or
82 * file chooser can use this information to show `network` volumes under
83 * a "Network" heading and `device` volumes under a "Devices" heading.
84 */
85#define G_VOLUME_IDENTIFIER_KIND_CLASS "class"
86
87
88#define G_TYPE_VOLUME (g_volume_get_type ())
89#define G_VOLUME(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_VOLUME, GVolume))
90#define G_IS_VOLUME(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_VOLUME))
91#define G_VOLUME_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_VOLUME, GVolumeIface))
92
93/**
94 * GVolumeIface:
95 * @g_iface: The parent interface.
96 * @changed: Changed signal that is emitted when the volume's state has changed.
97 * @removed: The removed signal that is emitted when the #GVolume have been removed. If the recipient is holding references to the object they should release them so the object can be finalized.
98 * @get_name: Gets a string containing the name of the #GVolume.
99 * @get_icon: Gets a #GIcon for the #GVolume.
100 * @get_uuid: Gets the UUID for the #GVolume. The reference is typically based on the file system UUID for the mount in question and should be considered an opaque string. Returns %NULL if there is no UUID available.
101 * @get_drive: Gets a #GDrive the volume is located on. Returns %NULL if the #GVolume is not associated with a #GDrive.
102 * @get_mount: Gets a #GMount representing the mounted volume. Returns %NULL if the #GVolume is not mounted.
103 * @can_mount: Returns %TRUE if the #GVolume can be mounted.
104 * @can_eject: Checks if a #GVolume can be ejected.
105 * @mount_fn: Mounts a given #GVolume.
106 * #GVolume implementations must emit the #GMountOperation::aborted
107 * signal before completing a mount operation that is aborted while
108 * awaiting input from the user through a #GMountOperation instance.
109 * @mount_finish: Finishes a mount operation.
110 * @eject: Ejects a given #GVolume.
111 * @eject_finish: Finishes an eject operation.
112 * @get_identifier: Returns the [identifier](#volume-identifiers) of the given kind, or %NULL if
113 * the #GVolume doesn't have one.
114 * @enumerate_identifiers: Returns an array strings listing the kinds
115 * of [identifiers](#volume-identifiers) which the #GVolume has.
116 * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
117 * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if
118 * it is not known.
119 * @eject_with_operation: Starts ejecting a #GVolume using a #GMountOperation. Since 2.22.
120 * @eject_with_operation_finish: Finishes an eject operation using a #GMountOperation. Since 2.22.
121 * @get_sort_key: Gets a key used for sorting #GVolume instance or %NULL if no such key exists. Since 2.32.
122 * @get_symbolic_icon: Gets a symbolic #GIcon for the #GVolume. Since 2.34.
123 *
124 * Interface for implementing operations for mountable volumes.
125 **/
126typedef struct _GVolumeIface GVolumeIface;
127
128struct _GVolumeIface
129{
130 GTypeInterface g_iface;
131
132 /* signals */
133
134 void (* changed) (GVolume *volume);
135 void (* removed) (GVolume *volume);
136
137 /* Virtual Table */
138
139 char * (* get_name) (GVolume *volume);
140 GIcon * (* get_icon) (GVolume *volume);
141 char * (* get_uuid) (GVolume *volume);
142 GDrive * (* get_drive) (GVolume *volume);
143 GMount * (* get_mount) (GVolume *volume);
144 gboolean (* can_mount) (GVolume *volume);
145 gboolean (* can_eject) (GVolume *volume);
146 void (* mount_fn) (GVolume *volume,
147 GMountMountFlags flags,
148 GMountOperation *mount_operation,
149 GCancellable *cancellable,
150 GAsyncReadyCallback callback,
151 gpointer user_data);
152 gboolean (* mount_finish) (GVolume *volume,
153 GAsyncResult *result,
154 GError **error);
155 void (* eject) (GVolume *volume,
156 GMountUnmountFlags flags,
157 GCancellable *cancellable,
158 GAsyncReadyCallback callback,
159 gpointer user_data);
160 gboolean (* eject_finish) (GVolume *volume,
161 GAsyncResult *result,
162 GError **error);
163
164 char * (* get_identifier) (GVolume *volume,
165 const char *kind);
166 char ** (* enumerate_identifiers) (GVolume *volume);
167
168 gboolean (* should_automount) (GVolume *volume);
169
170 GFile * (* get_activation_root) (GVolume *volume);
171
172 void (* eject_with_operation) (GVolume *volume,
173 GMountUnmountFlags flags,
174 GMountOperation *mount_operation,
175 GCancellable *cancellable,
176 GAsyncReadyCallback callback,
177 gpointer user_data);
178 gboolean (* eject_with_operation_finish) (GVolume *volume,
179 GAsyncResult *result,
180 GError **error);
181
182 const gchar * (* get_sort_key) (GVolume *volume);
183 GIcon * (* get_symbolic_icon) (GVolume *volume);
184};
185
186GIO_AVAILABLE_IN_ALL
187GType g_volume_get_type (void) G_GNUC_CONST;
188
189GIO_AVAILABLE_IN_ALL
190char * g_volume_get_name (GVolume *volume);
191GIO_AVAILABLE_IN_ALL
192GIcon * g_volume_get_icon (GVolume *volume);
193GIO_AVAILABLE_IN_ALL
194GIcon * g_volume_get_symbolic_icon (GVolume *volume);
195GIO_AVAILABLE_IN_ALL
196char * g_volume_get_uuid (GVolume *volume);
197GIO_AVAILABLE_IN_ALL
198GDrive * g_volume_get_drive (GVolume *volume);
199GIO_AVAILABLE_IN_ALL
200GMount * g_volume_get_mount (GVolume *volume);
201GIO_AVAILABLE_IN_ALL
202gboolean g_volume_can_mount (GVolume *volume);
203GIO_AVAILABLE_IN_ALL
204gboolean g_volume_can_eject (GVolume *volume);
205GIO_AVAILABLE_IN_ALL
206gboolean g_volume_should_automount (GVolume *volume);
207GIO_AVAILABLE_IN_ALL
208void g_volume_mount (GVolume *volume,
209 GMountMountFlags flags,
210 GMountOperation *mount_operation,
211 GCancellable *cancellable,
212 GAsyncReadyCallback callback,
213 gpointer user_data);
214GIO_AVAILABLE_IN_ALL
215gboolean g_volume_mount_finish (GVolume *volume,
216 GAsyncResult *result,
217 GError **error);
218GIO_DEPRECATED_FOR(g_volume_eject_with_operation)
219void g_volume_eject (GVolume *volume,
220 GMountUnmountFlags flags,
221 GCancellable *cancellable,
222 GAsyncReadyCallback callback,
223 gpointer user_data);
224
225GIO_DEPRECATED_FOR(g_volume_eject_with_operation_finish)
226gboolean g_volume_eject_finish (GVolume *volume,
227 GAsyncResult *result,
228 GError **error);
229GIO_AVAILABLE_IN_ALL
230char * g_volume_get_identifier (GVolume *volume,
231 const char *kind);
232GIO_AVAILABLE_IN_ALL
233char ** g_volume_enumerate_identifiers (GVolume *volume);
234
235GIO_AVAILABLE_IN_ALL
236GFile * g_volume_get_activation_root (GVolume *volume);
237
238GIO_AVAILABLE_IN_ALL
239void g_volume_eject_with_operation (GVolume *volume,
240 GMountUnmountFlags flags,
241 GMountOperation *mount_operation,
242 GCancellable *cancellable,
243 GAsyncReadyCallback callback,
244 gpointer user_data);
245GIO_AVAILABLE_IN_ALL
246gboolean g_volume_eject_with_operation_finish (GVolume *volume,
247 GAsyncResult *result,
248 GError **error);
249
250GIO_AVAILABLE_IN_2_32
251const gchar *g_volume_get_sort_key (GVolume *volume);
252
253G_END_DECLS
254
255#endif /* __G_VOLUME_H__ */
256