From 3785c47e26f6ecc0d434d527d7ec9f9caa3ac03d Mon Sep 17 00:00:00 2001 From: Gian Mario Tagliaretti Date: Sun, 29 Mar 2009 16:34:55 +0000 Subject: Add gio.Volume in docs. 2009-03-29 Gian Mario Tagliaretti * docs/Makefile.am: * docs/reference/pygio-classes.xml: * docs/reference/pygio-constants.xml: * docs/reference/pygio-volume.xml: Add gio.Volume in docs. svn path=/trunk/; revision=1041 --- docs/reference/ChangeLog | 7 + docs/reference/pygio-classes.xml | 1 + docs/reference/pygio-constants.xml | 42 +++ docs/reference/pygio-volume.xml | 718 +++++++++++++++++++++++++++++++++++++ 4 files changed, 768 insertions(+) create mode 100644 docs/reference/pygio-volume.xml (limited to 'docs/reference') diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 46be0e7..8fe9c3f 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,10 @@ +2009-03-29 Gian Mario Tagliaretti + + * docs/Makefile.am: + * docs/reference/pygio-classes.xml: + * docs/reference/pygio-constants.xml: + * docs/reference/pygio-volume.xml: Add gio.Volume in docs. + 2009-03-28 Gian Mario Tagliaretti * docs/Makefile.am: diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml index 90dc71b..8ceb70e 100644 --- a/docs/reference/pygio-classes.xml +++ b/docs/reference/pygio-classes.xml @@ -19,6 +19,7 @@ + diff --git a/docs/reference/pygio-constants.xml b/docs/reference/pygio-constants.xml index d167de8..b2bcbf2 100644 --- a/docs/reference/pygio-constants.xml +++ b/docs/reference/pygio-constants.xml @@ -17,6 +17,8 @@ + + @@ -388,6 +390,46 @@ + + + Gio Mount Mount Flags Constants + + + Flags used when mounting a mount. + + + + + gio.MOUNT_MOUNT_NONE + + No flags set. + + + + + + + Gio Mount Unmount Flags Constants + + + Flags used when unmounting a mount. + + + + + gio.MOUNT_UNMOUNT_NONE + + No flags set. + + + + gio.MOUNT_UNMOUNT_FORCE + + Unmount even if there are outstanding file operations on the mount. + + + + diff --git a/docs/reference/pygio-volume.xml b/docs/reference/pygio-volume.xml new file mode 100644 index 0000000..8ff981c --- /dev/null +++ b/docs/reference/pygio-volume.xml @@ -0,0 +1,718 @@ + + + + + + gio.Volume + Volume management. + + + + Synopsis + + + gio.Volume + gobject.GInterface + + + can_eject + + + + can_mount + + + + eject + callback + flagsgio.MOUNT_UNMOUNT_NONE + cancellableNone + user_dataNone + + + eject_finish + result + + + enumerate_identifiers + + + + get_activation_root + + + + get_drive + + + + get_icon + + + + get_identifier + + + + get_mount + + + + get_name + + + + get_uuid + + + + mount + mount_operation + callback + flagsgio.MOUNT_MOUNT_NONE + cancellableNone + user_dataNone + + + mount_finish + result + + + should_automount + + + + + + + + + Ancestry + ++-- gobject.GInterface + +-- gio.Volume + + + + + + Prerequisites + + gio.Volume requires + gobject.GObject + + + + + gio.Volume Signal Prototypes + + gobject.GObject Signal Prototypes + + + + "changed" + + callback + volume + user_param1 + ... + + + + + "removed" + + callback + volume + user_param1 + ... + + + + + + + + + Description + + + The gio.Volume + interface represents user-visible objects that can be mounted. Note, when porting + from GnomeVFS, gio.Volume + is the moral equivalent of GnomeVFSDrive. + + + Mounting a gio.Volume + instance is an asynchronous operation. For more information about asynchronous operations. + To mount a gio.Volume, first call + gio.Volume.mount() + with (at least) the gio.Volume + instance, optionally a + gio.MountOperation + object and a GAsyncReadyCallback. + + + Typically, one will only want to pass None for the GMountOperation + if automounting all volumes when a desktop session starts since it's not desirable + to put up a lot of dialogs asking for credentials. + + + The callback will be fired when the operation has resolved (either with success or failure), + and a GAsyncReady structure will be passed to the callback. That callback should then call + gio.Volume.mount_finish() + with the GVolume instance and the GAsyncReady data to see if the operation was completed + successfully. If an error is present when + gio.Volume.mount_finish() + is called, then it will be filled with any error information. + + + It is sometimes necessary to directly access the underlying operating system object behind a volume + (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain + an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs, + filesystem labels, traditional Unix devices (e.g. /dev/sda2), uuids. GIO uses predefind strings + as names for the different kinds of identifiers: + "hal-udi", "label", etc. Use + gio.Volume.get_identifier() + to obtain an identifier for a volume. + + + + + Methods + + + gio.Volume.can_eject + + + can_eject + + + + + + Returns : + True if the volume can be ejected, + False otherwise. + + + + + + The can_eject() method checks if a volume can be ejected. + + + + + gio.Volume.can_mount + + + can_mount + + + + + + Returns : + True if the volume can be mounted + for media changes, False otherwise. + + + + + + The can_mount() method checks if a volume + can be mounted. + + + + + gio.Volume.eject + + + eject + + callback + + + flagsgio.MOUNT_UNMOUNT_NONE + + + cancellableNone + + + user_dataNone + + + + + + callback : + A GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + flags affecting the unmount if required for eject. + + + + cancellable : + Optional + gio.Cancellable + object, None to ignore. + + + + user_data : + The data to pass to callback function. + + + + + + The eject() method asynchronously ejects a volume. + + + When the operation is finished, callback will be called. You can then call + gio.Volume.eject_finish() + to obtain the result of the operation. + + + + + gio.Volume.eject_finish + + + eject_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True if the volume has been ejected + successfully, False otherwise. + + + + + + The eject_finish() method finishes ejecting a volume. + If any errors occured during the operation, error will be set to contain the + errors and False will be returned. + + + + + gio.Volume.enumerate_identifiers + + + enumerate_identifiers + + + + + + Returns : + a list of strings containing kinds of identifiers. + + + + + + The enumerate_identifiers() method gets the kinds + of identifiers that volume has. Use + gio.Volume.get_identifier() + to obtain the identifiers themselves. + + + + + gio.Volume.get_activation_root + + + get_activation_root + + + + + + Returns : + the activation root of volume or None. + + + + + + The get_activation_root() method gets the activation + root for a gio.Volume + if it is known ahead of mount time. Returns None otherwise. + If not None and if volume is mounted, then the result of + gio.Mount.get_root() + on the GMount object obtained from + gio.Volume.get_mount() + will always either be equal or a prefix of what this function returns. + In other words, in code: + + +mount = volume.get_mount() # mounted, so never None +mount_root = mount.get_root() +volume_activation_root = volume.get_activation_root() # assume not None + + + then the expression + + +volume_activation_root.has_prefix(mount_root) || volume_activation_root.equal(mount_root) + + + will always be True. + + + Activation roots are typically used in + gio.VolumeMonitor + implementations to find the underlying mount to shadow, see + gio.Mount.is_shadowed() + for more details. + + + + + gio.Volume.get_drive + + + get_drive + + + + + + Returns : + A gio.Drive + or None if volume is not associated with a drive. + + + + + + The get_drive() method gets the drive for the volume. + + + + + gio.Volume.get_icon + + + get_icon + + + + + + Returns : + gio.Icon + for the volume. + + + + + + The get_icon() method gets the icon for volume. + + + + + gio.Volume.get_identifier + + + get_identifier + + + + + + Returns : + A string containing the requested identfier, or + None if the + gio.Volume + doesn't have this kind of identifier. + + + + + + The get_identifier() method gets the identifier of + the given kind for volume. + + + + + gio.Volume.get_mount + + + get_mount + + + + + + Returns : + A + gio.Mount + or None if volume isn't mounted. + + + + + + The get_mount() method gets the mount for the volume. + + + + + gio.Volume.get_name + + + get_name + + + + + + Returns : + A string containing volume's name. + + + + + + The get_name() method gets the name of volume. + + + + + gio.Volume.get_uuid + + + get_uuid + + + + + + Returns : + the UUID for volume or None + if no UUID can be computed. + + + + + + The get_uuid() method gets the UUID for the volume. + The reference is typically based on the file system UUID for the volume in + question and should be considered an opaque string. + Returns None if there is no UUID available. + + + + + gio.Volume.mount + + + mount + + mount_operation + + + callback + + + flagsgio.MOUNT_MOUNT_NONE + + + cancellableNone + + + user_dataNone + + + + + + mount_operation : + A + gio.MountOperation + or None to avoid user interaction. + + + + callback : + A GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + Flags affecting the operation + + + + cancellable : + Optional + gio.Cancellable + object, None to ignore. + + + + user_data : + The data to pass to callback function. + + + + + + The mount() method mounts a volume. This is an + asynchronous operation, and is finished by calling + gio.Volume.mount_finish() + with the volume and GAsyncResult returned in the callback. + + + + + gio.Volume.mount_finish + + + mount_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True if the volume has been mounted + successfully, False otherwise. + + + + + + The mounted() method finishes mounting a volume. + If any errors occured during the operation, error will be set to contain + the errors and False will be returned. + + + If the mount operation succeeded, + get_mount() + on volume is guaranteed to return the mount right after calling this function; + there's no need to listen for the 'mount-added' signal on + gio.VolumeMonitor. + + + + + gio.Volume.should_automount + + + should_automount + + + + + + Returns : + True if the volume should + be automatically mounted. + + + + + + The should_automount() method returns whether + the volume should be automatically mounted. + + + + + + Signals + + + The "changed" gio.Volume Signal + + callback + volume + user_param1 + ... + + + + + volume : + the volume + + + user_param1 : + the first user parameter (if any) specified + with the connect() + method + + + ... : + additional user parameters (if any) + + + + + Emitted when the volume has been changed. + + + + + The "removed" gio.Volume Signal + + callback + volume + user_param1 + ... + + + + + volume : + the volume + + + user_param1 : + the first user parameter (if any) specified + with the connect() + method + + + ... : + additional user parameters (if any) + + + + + This signal is emitted when the + gio.Volume + have been removed. If the recipient is holding references to the object + they should release them so the object can be finalized. + + + + + -- cgit