1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gio.VolumeIF;
26 
27 private import gio.AsyncResultIF;
28 private import gio.Cancellable;
29 private import gio.Drive;
30 private import gio.DriveIF;
31 private import gio.File;
32 private import gio.FileIF;
33 private import gio.Icon;
34 private import gio.IconIF;
35 private import gio.Mount;
36 private import gio.MountIF;
37 private import gio.MountOperation;
38 private import glib.ErrorG;
39 private import glib.GException;
40 private import glib.Str;
41 private import gobject.ObjectG;
42 private import gobject.Signals;
43 public  import gtkc.gdktypes;
44 private import gtkc.gio;
45 public  import gtkc.giotypes;
46 
47 
48 /**
49  * The #GVolume interface represents user-visible objects that can be
50  * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
51  * equivalent of #GnomeVFSDrive.
52  * 
53  * Mounting a #GVolume instance is an asynchronous operation. For more
54  * information about asynchronous operations, see #GAsyncResult and
55  * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
56  * least) the #GVolume instance, optionally a #GMountOperation object
57  * and a #GAsyncReadyCallback.
58  * 
59  * Typically, one will only want to pass %NULL for the
60  * #GMountOperation if automounting all volumes when a desktop session
61  * starts since it's not desirable to put up a lot of dialogs asking
62  * for credentials.
63  * 
64  * The callback will be fired when the operation has resolved (either
65  * with success or failure), and a #GAsyncReady structure will be
66  * passed to the callback.  That callback should then call
67  * g_volume_mount_finish() with the #GVolume instance and the
68  * #GAsyncReady data to see if the operation was completed
69  * successfully.  If an @error is present when g_volume_mount_finish()
70  * is called, then it will be filled with any error information.
71  * 
72  * ## Volume Identifiers # {#volume-identifier}
73  * 
74  * It is sometimes necessary to directly access the underlying
75  * operating system object behind a volume (e.g. for passing a volume
76  * to an application via the commandline). For this purpose, GIO
77  * allows to obtain an 'identifier' for the volume. There can be
78  * different kinds of identifiers, such as Hal UDIs, filesystem labels,
79  * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
80  * strings as names for the different kinds of identifiers:
81  * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
82  * Use g_volume_get_identifier() to obtain an identifier for a volume.
83  * 
84  * 
85  * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
86  * when the gvfs hal volume monitor is in use. Other volume monitors
87  * will generally be able to provide the #G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE
88  * identifier, which can be used to obtain a hal device by means of
89  * libhal_manager_find_device_string_match().
90  */
91 public interface VolumeIF{
92 	/** Get the main Gtk struct */
93 	public GVolume* getVolumeStruct();
94 
95 	/** the main Gtk struct as a void* */
96 	protected void* getStruct();
97 
98 
99 	/**
100 	 * Checks if a volume can be ejected.
101 	 *
102 	 * Return: %TRUE if the @volume can be ejected. %FALSE otherwise
103 	 */
104 	public bool canEject();
105 
106 	/**
107 	 * Checks if a volume can be mounted.
108 	 *
109 	 * Return: %TRUE if the @volume can be mounted. %FALSE otherwise
110 	 */
111 	public bool canMount();
112 
113 	/**
114 	 * Ejects a volume. This is an asynchronous operation, and is
115 	 * finished by calling g_volume_eject_finish() with the @volume
116 	 * and #GAsyncResult returned in the @callback.
117 	 *
118 	 * Deprecated: Use g_volume_eject_with_operation() instead.
119 	 *
120 	 * Params:
121 	 *     flags = flags affecting the unmount if required for eject
122 	 *     cancellable = optional #GCancellable object, %NULL to ignore
123 	 *     callback = a #GAsyncReadyCallback, or %NULL
124 	 *     userData = user data that gets passed to @callback
125 	 */
126 	public void eject(GMountUnmountFlags flags, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
127 
128 	/**
129 	 * Finishes ejecting a volume. If any errors occurred during the operation,
130 	 * @error will be set to contain the errors and %FALSE will be returned.
131 	 *
132 	 * Deprecated: Use g_volume_eject_with_operation_finish() instead.
133 	 *
134 	 * Params:
135 	 *     result = a #GAsyncResult
136 	 *
137 	 * Return: %TRUE, %FALSE if operation failed
138 	 *
139 	 * Throws: GException on failure.
140 	 */
141 	public bool ejectFinish(AsyncResultIF result);
142 
143 	/**
144 	 * Ejects a volume. This is an asynchronous operation, and is
145 	 * finished by calling g_volume_eject_with_operation_finish() with the @volume
146 	 * and #GAsyncResult data returned in the @callback.
147 	 *
148 	 * Params:
149 	 *     flags = flags affecting the unmount if required for eject
150 	 *     mountOperation = a #GMountOperation or %NULL to
151 	 *         avoid user interaction
152 	 *     cancellable = optional #GCancellable object, %NULL to ignore
153 	 *     callback = a #GAsyncReadyCallback, or %NULL
154 	 *     userData = user data passed to @callback
155 	 *
156 	 * Since: 2.22
157 	 */
158 	public void ejectWithOperation(GMountUnmountFlags flags, MountOperation mountOperation, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
159 
160 	/**
161 	 * Finishes ejecting a volume. If any errors occurred during the operation,
162 	 * @error will be set to contain the errors and %FALSE will be returned.
163 	 *
164 	 * Params:
165 	 *     result = a #GAsyncResult
166 	 *
167 	 * Return: %TRUE if the volume was successfully ejected. %FALSE otherwise
168 	 *
169 	 * Since: 2.22
170 	 *
171 	 * Throws: GException on failure.
172 	 */
173 	public bool ejectWithOperationFinish(AsyncResultIF result);
174 
175 	/**
176 	 * Gets the kinds of [identifiers][volume-identifier] that @volume has.
177 	 * Use g_volume_get_identifier() to obtain the identifiers themselves.
178 	 *
179 	 * Return: a %NULL-terminated array
180 	 *     of strings containing kinds of identifiers. Use g_strfreev() to free.
181 	 */
182 	public string[] enumerateIdentifiers();
183 
184 	/**
185 	 * Gets the activation root for a #GVolume if it is known ahead of
186 	 * mount time. Returns %NULL otherwise. If not %NULL and if @volume
187 	 * is mounted, then the result of g_mount_get_root() on the
188 	 * #GMount object obtained from g_volume_get_mount() will always
189 	 * either be equal or a prefix of what this function returns. In
190 	 * other words, in code
191 	 *
192 	 * |[<!-- language="C" -->
193 	 * GMount *mount;
194 	 * GFile *mount_root
195 	 * GFile *volume_activation_root;
196 	 *
197 	 * mount = g_volume_get_mount (volume); // mounted, so never NULL
198 	 * mount_root = g_mount_get_root (mount);
199 	 * volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
200 	 * ]|
201 	 * then the expression
202 	 * |[<!-- language="C" -->
203 	 * (g_file_has_prefix (volume_activation_root, mount_root) ||
204 	 * g_file_equal (volume_activation_root, mount_root))
205 	 * ]|
206 	 * will always be %TRUE.
207 	 *
208 	 * Activation roots are typically used in #GVolumeMonitor
209 	 * implementations to find the underlying mount to shadow, see
210 	 * g_mount_is_shadowed() for more details.
211 	 *
212 	 * Return: the activation root of @volume
213 	 *     or %NULL. Use g_object_unref() to free.
214 	 *
215 	 * Since: 2.18
216 	 */
217 	public FileIF getActivationRoot();
218 
219 	/**
220 	 * Gets the drive for the @volume.
221 	 *
222 	 * Return: a #GDrive or %NULL if @volume is not
223 	 *     associated with a drive. The returned object should be unreffed
224 	 *     with g_object_unref() when no longer needed.
225 	 */
226 	public DriveIF getDrive();
227 
228 	/**
229 	 * Gets the icon for @volume.
230 	 *
231 	 * Return: a #GIcon.
232 	 *     The returned object should be unreffed with g_object_unref()
233 	 *     when no longer needed.
234 	 */
235 	public IconIF getIcon();
236 
237 	/**
238 	 * Gets the identifier of the given kind for @volume.
239 	 * See the [introduction][volume-identifier] for more
240 	 * information about volume identifiers.
241 	 *
242 	 * Params:
243 	 *     kind = the kind of identifier to return
244 	 *
245 	 * Return: a newly allocated string containing the
246 	 *     requested identfier, or %NULL if the #GVolume
247 	 *     doesn't have this kind of identifier
248 	 */
249 	public string getIdentifier(string kind);
250 
251 	/**
252 	 * Gets the mount for the @volume.
253 	 *
254 	 * Return: a #GMount or %NULL if @volume isn't mounted.
255 	 *     The returned object should be unreffed with g_object_unref()
256 	 *     when no longer needed.
257 	 */
258 	public MountIF getMount();
259 
260 	/**
261 	 * Gets the name of @volume.
262 	 *
263 	 * Return: the name for the given @volume. The returned string should
264 	 *     be freed with g_free() when no longer needed.
265 	 */
266 	public string getName();
267 
268 	/**
269 	 * Gets the sort key for @volume, if any.
270 	 *
271 	 * Return: Sorting key for @volume or %NULL if no such key is available
272 	 *
273 	 * Since: 2.32
274 	 */
275 	public string getSortKey();
276 
277 	/**
278 	 * Gets the symbolic icon for @volume.
279 	 *
280 	 * Return: a #GIcon.
281 	 *     The returned object should be unreffed with g_object_unref()
282 	 *     when no longer needed.
283 	 *
284 	 * Since: 2.34
285 	 */
286 	public IconIF getSymbolicIcon();
287 
288 	/**
289 	 * Gets the UUID for the @volume. The reference is typically based on
290 	 * the file system UUID for the volume in question and should be
291 	 * considered an opaque string. Returns %NULL if there is no UUID
292 	 * available.
293 	 *
294 	 * Return: the UUID for @volume or %NULL if no UUID can be computed.
295 	 *     The returned string should be freed with g_free()
296 	 *     when no longer needed.
297 	 */
298 	public string getUuid();
299 
300 	/**
301 	 * Mounts a volume. This is an asynchronous operation, and is
302 	 * finished by calling g_volume_mount_finish() with the @volume
303 	 * and #GAsyncResult returned in the @callback.
304 	 *
305 	 * Params:
306 	 *     flags = flags affecting the operation
307 	 *     mountOperation = a #GMountOperation or %NULL to avoid user interaction
308 	 *     cancellable = optional #GCancellable object, %NULL to ignore
309 	 *     callback = a #GAsyncReadyCallback, or %NULL
310 	 *     userData = user data that gets passed to @callback
311 	 */
312 	public void mount(GMountMountFlags flags, MountOperation mountOperation, Cancellable cancellable, GAsyncReadyCallback callback, void* userData);
313 
314 	/**
315 	 * Finishes mounting a volume. If any errors occurred during the operation,
316 	 * @error will be set to contain the errors and %FALSE will be returned.
317 	 *
318 	 * If the mount operation succeeded, g_volume_get_mount() on @volume
319 	 * is guaranteed to return the mount right after calling this
320 	 * function; there's no need to listen for the 'mount-added' signal on
321 	 * #GVolumeMonitor.
322 	 *
323 	 * Params:
324 	 *     result = a #GAsyncResult
325 	 *
326 	 * Return: %TRUE, %FALSE if operation failed
327 	 *
328 	 * Throws: GException on failure.
329 	 */
330 	public bool mountFinish(AsyncResultIF result);
331 
332 	/**
333 	 * Returns whether the volume should be automatically mounted.
334 	 *
335 	 * Return: %TRUE if the volume should be automatically mounted
336 	 */
337 	public bool shouldAutomount();
338 	@property void delegate(VolumeIF)[] onChangedListeners();
339 	/**
340 	 * Emitted when the volume has been changed.
341 	 */
342 	void addOnChanged(void delegate(VolumeIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
343 
344 	@property void delegate(VolumeIF)[] onRemovedListeners();
345 	/**
346 	 * This signal is emitted when the #GVolume have been removed. If
347 	 * the recipient is holding references to the object they should
348 	 * release them so the object can be finalized.
349 	 */
350 	void addOnRemoved(void delegate(VolumeIF) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0);
351 
352 }