[pygobject] Commit some more work on gio.File Docs
- From: Gian Mario Tagliaretti <gianmt src gnome org>
- To: svn-commits-list gnome org
- Subject: [pygobject] Commit some more work on gio.File Docs
- Date: Sat, 18 Apr 2009 16:52:01 -0400 (EDT)
commit 784b229c9f54e5197adbd566cd42009e4bcfd055
Author: Gian Mario Tagliaretti <gianmt gnome org>
Date: Sat Apr 18 13:32:03 2009 +0200
Commit some more work on gio.File Docs
Added some more methods to gio.File and gio file constants
---
docs/reference/pygio-constants.xml | 542 ++++++++++++-
docs/reference/pygio-file.xml | 1652 +++++++++++++++++++++++++++++++++++-
2 files changed, 2167 insertions(+), 27 deletions(-)
diff --git a/docs/reference/pygio-constants.xml b/docs/reference/pygio-constants.xml
index 6bddc93..cc71fe3 100644
--- a/docs/reference/pygio-constants.xml
+++ b/docs/reference/pygio-constants.xml
@@ -15,12 +15,14 @@
<xref linkend="gio-app-info-constants" endterm="gio-app-info-constants-title"></xref>
<xref linkend="gio-emblem-origin-constants" endterm="gio-emblem-origin-constants-title"></xref>
<xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref>
+<xref linkend="gio-file-attribute-constants" endterm="gio-file-attribute-constants-title"></xref>
<xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
<xref linkend="gio-file-attribute-flags-constants" endterm="gio-file-attribute-flags-constants-title"></xref>
<xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref>
<xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>
<xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref>
<xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>
+<xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref>
<xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref>
<xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>
</programlisting>
@@ -301,6 +303,489 @@
</variablelist>
</refsect2>
+ <refsect2 id="gio-file-attribute-constants">
+ <title id="gio-file-attribute-constants-title">Gio File Attribute Constants</title>
+
+ <para>
+ The file attributes.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_TYPE</literal></term>
+ <listitem>
+ <simpara>
+ "standard::type" A key in the "standard" namespace for storing file types. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32. The value for this key should contain a
+ <xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref>
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</literal></term>
+ <listitem>
+ <simpara>
+ "standard::is-hidden" A key in the "standard" namespace for checking if a file is hidden. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_BACKUP</literal></term>
+ <listitem>
+ <simpara>
+ "standard::is-backup" A key in the "standard" namespace for checking if a file is a backup file. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</literal></term>
+ <listitem>
+ <simpara>
+ "standard::is-symlink" A key in the "standard" namespace for checking if the file is a symlink.
+ Typically the actual type is something else, if we followed the symlink to get the type. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</literal></term>
+ <listitem>
+ <simpara>
+ "standard::is-virtual" A key in the "standard" namespace for checking if a file is virtual. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_NAME</literal></term>
+ <listitem>
+ <simpara>
+ "standard::name" A key in the "standard" namespace for getting the name of the file.
+ The name is the on-disk filename which may not be in any known encoding,
+ and can thus not be generally displayed as is. Use
+ gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user
+ interface. Corresponding GFileAttributeType is gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</literal></term>
+ <listitem>
+ <simpara>
+ "standard::display-name" A key in the "standard" namespace for getting the display
+ name of the file. A display name is guaranteed to be in UTF8 and can thus be displayed
+ in the UI. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME</literal></term>
+ <listitem>
+ <simpara>
+ "standard::edit-name" A key in the "standard" namespace for edit name of the file.
+ An edit name is similar to the display name, but it is meant to be used when you want
+ to rename the file in the UI. The display name might contain information you don't
+ want in the new filename (such as "(invalid unicode)" if the filename was in an
+ invalid encoding). Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_COPY_NAME</literal></term>
+ <listitem>
+ <simpara>
+ "standard::copy-name" A key in the "standard" namespace for getting the copy
+ name of the file. The copy name is an optional version of the name. If available
+ it's always in UTF8, and corresponds directly to the original filename (only transcoded
+ to UTF8). This is useful if you want to copy the file to another filesystem that might
+ have a different encoding. If the filename is not a valid string in the encoding selected
+ for the filesystem it is in then the copy name will not be set. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_ICON</literal></term>
+ <listitem>
+ <simpara>
+ "standard::icon" A key in the "standard" namespace for getting the icon for the file. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a
+ <link linkend="class-gioicon"><classname>gio.Icon</classname></link>.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</literal></term>
+ <listitem>
+ <simpara>
+ "standard::content-type" A key in the "standard" namespace for getting the content type of the file. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING. The value for this key should contain a valid content type.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</literal></term>
+ <listitem>
+ <simpara>
+ "standard::fast-content-type" A key in the "standard" namespace for getting the fast
+ content type. The fast content type isn't as reliable as the regular one, as it
+ only uses the filename to guess it, but it is faster to calculate than the regular
+ content type. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SIZE</literal></term>
+ <listitem>
+ <simpara>
+ "standard::size" A key in the "standard" namespace for getting the file's size (in bytes). Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT64.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</literal></term>
+ <listitem>
+ <simpara>
+ "standard::symlink-target" A key in the "standard" namespace for getting the target URI
+ for the file, in the case of gio.FILE_TYPE_SHORTCUT or gio.FILE_TYPE_MOUNTABLE files. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is G_FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER</literal></term>
+ <listitem>
+ <simpara>
+ "standard::sort-order" A key in the "standard" namespace for setting the sort order of a file. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_INT32. An example use would be in file managers, which would use this
+ key to set the order files are displayed. Files with smaller sort order should be sorted first,
+ and files without sort order as if sort order was zero.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ETAG_VALUE</literal></term>
+ <listitem>
+ <simpara>
+ "etag::value" A key in the "etag" namespace for getting the value of the file's entity tag. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ID_FILE</literal></term>
+ <listitem>
+ <simpara>
+ "id::file" A key in the "id" namespace for getting a file identifier. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during listing files,
+ to avoid recursive directory scanning.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ID_FILESYSTEM</literal></term>
+ <listitem>
+ <simpara>
+ "id::filesystem" A key in the "id" namespace for getting the file system identifier. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during drag and
+ drop to see if the source and target are on the same filesystem (default to move) or not (default to copy).
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_READ</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-read" A key in the "access" namespace for getting read privileges. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to read the file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_WRITE</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-write" A key in the "access" namespace for getting write privileges.Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to write to the file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-execute" A key in the "access" namespace for getting execution privileges. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to execute the file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_DELETE</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-delete" A key in the "access" namespace for checking deletion privileges. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to delete the file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_TRASH</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-trash" A key in the "access" namespace for checking trashing privileges. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to move the file to the trash.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_RENAME</literal></term>
+ <listitem>
+ <simpara>
+ "access::can-rename" A key in the "access" namespace for checking renaming privileges. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal>
+ if the user is able to rename the file.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</literal></term>
+ <listitem>
+ <simpara>
+ "mountable::can-mount" A key in the "mountable" namespace for checking if
+ a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</literal></term>
+ <listitem>
+ <simpara>
+ "mountable::can-unmount" A key in the "mountable" namespace for checking if a file
+ (of type G_FILE_TYPE_MOUNTABLE) is unmountable. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</literal></term>
+ <listitem>
+ <simpara>
+ "mountable::can-eject" A key in the "mountable" namespace for checking if a file
+ (of type G_FILE_TYPE_MOUNTABLE) can be ejected. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</literal></term>
+ <listitem>
+ <simpara>
+ "mountable::unix-device" A key in the "mountable" namespace for getting the unix device. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</literal></term>
+ <listitem>
+ <simpara>
+ "mountable::hal-udi" A key in the "mountable" namespace for getting the
+ HAL UDI for the mountable file. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_STRING.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_MODIFIED</literal></term>
+ <listitem>
+ <simpara>
+ "time::modified" A key in the "time" namespace for getting the time the file was last modified. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was modified.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC</literal></term>
+ <listitem>
+ <simpara>
+ "time::modified-usec" A key in the "time" namespace for getting the miliseconds
+ of the time the file was last modified. This should be used in conjunction
+ with G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is G_FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_ACCESS</literal></term>
+ <listitem>
+ <simpara>
+ "time::access" A key in the "time" namespace for getting the time the file was last accessed. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last accessed.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_ACCESS_USEC</literal></term>
+ <listitem>
+ <simpara>
+ "time::access-usec" A key in the "time" namespace for getting the microseconds of
+ the time the file was last accessed. This should be used in conjunction
+ with G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_CHANGED</literal></term>
+ <listitem>
+ <simpara>
+ "time::changed" A key in the "time" namespace for getting the time the
+ file was last changed. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last changed.
+ This corresponds to the traditional UNIX ctime.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_CHANGED_USEC</literal></term>
+ <listitem>
+ <simpara>
+ "time::changed-usec" A key in the "time" namespace for getting the microseconds
+ of the time the file was last changed. This should be used in conjunction
+ with G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_CREATED</literal></term>
+ <listitem>
+ <simpara>
+ "time::created" A key in the "time" namespace for getting the time the file was created. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was created.
+ This corresponds to the NTFS ctime.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_TIME_CREATED_USEC</literal></term>
+ <listitem>
+ <simpara>
+ "time::created-usec" A key in the "time" namespace for getting the microseconds of the time the
+ file was created. This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_UNIX_DEVICE</literal></term>
+ <listitem>
+ <simpara>
+ "unix::device" A key in the "unix" namespace for getting the device id of the device the file
+ is located on (see stat() documentation). This attribute is only available
+ for UNIX file systems. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_UNIX_INODE</literal></term>
+ <listitem>
+ <simpara>
+ "unix::inode" A key in the "unix" namespace for getting the inode of the file. This attribute is only
+ available for UNIX file systems. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is G_FILE_ATTRIBUTE_TYPE_UINT64.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_UNIX_MODE</literal></term>
+ <listitem>
+ <simpara>
+ "unix::mode" A key in the "unix" namespace for getting the mode of the file (e.g.
+ whether the file is a regular file, symlink, etc). See lstat() documentation.
+ This attribute is only available for UNIX file systems. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_UNIX_NLINK</literal></term>
+ <listitem>
+ <simpara>
+ "unix::nlink" A key in the "unix" namespace for getting the number of hard links
+ for a file. See lstat() documentation. This attribute is only available for UNIX
+ file systems. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_ATTRIBUTE_UNIX_UID</literal></term>
+ <listitem>
+ <simpara>
+ "unix::uid" A key in the "unix" namespace for getting the user ID for the file. This attribute
+ is only available for UNIX file systems. Corresponding
+ <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref>
+ is gio.FILE_ATTRIBUTE_TYPE_UINT32.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2 id="gio-file-attribute-type-constants">
<title id="gio-file-attribute-type-constants-title">Gio File Attribute Type Constants</title>
@@ -485,7 +970,7 @@
</refsect2>
<refsect2 id="gio-file-monitor-flags-constants">
- <title id="gio-file-monitor-flags-constants-title">Gio File Copy Monitor Constants</title>
+ <title id="gio-file-monitor-flags-constants-title">Gio File Monitor Flags Constants</title>
<para>
Flags used to set what a
@@ -510,7 +995,7 @@
</refsect2>
<refsect2 id="gio-file-query-info-flags-constants">
- <title id="gio-file-query-info-flags-constants-title">Gio File Create Flags Constants</title>
+ <title id="gio-file-query-info-flags-constants-title">Gio File Query Info Flags Constants</title>
<para>
Flags used when querying a
@@ -533,6 +1018,59 @@
</variablelist>
</refsect2>
+ <refsect2 id="gio-file-type-constants">
+ <title id="gio-file-type-constants-title">Gio File Type Constants</title>
+
+ <para>
+ Indicates the file's on-disk type.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_DIRECTORY</literal></term>
+ <listitem>
+ <simpara>File handle represents a directory.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_MOUNTABLE</literal></term>
+ <listitem>
+ <simpara>File is a mountable location.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_REGULAR</literal></term>
+ <listitem>
+ <simpara>File handle represents a regular file.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_SHORTCUT</literal></term>
+ <listitem>
+ <simpara>File is a shortcut (Windows systems).</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_SPECIAL</literal></term>
+ <listitem>
+ <simpara>File is a "special" file, such as a socket, fifo, block device, or character device.</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_SYMBOLIC_LINK</literal></term>
+ <listitem>
+ <simpara>File handle represents a symbolic link (Unix systems).</simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>gio.FILE_TYPE_UNKNOWN</literal></term>
+ <listitem>
+ <simpara>File's type is unknown.</simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2 id="gio-mount-mount-flags-constants">
<title id="gio-mount-mount-flags-constants-title">Gio Mount Mount Flags Constants</title>
diff --git a/docs/reference/pygio-file.xml b/docs/reference/pygio-file.xml
index 148aff7..9c58199 100644
--- a/docs/reference/pygio-file.xml
+++ b/docs/reference/pygio-file.xml
@@ -5,7 +5,7 @@
<refentry id="class-giofile">
<refnamediv>
<refname>gio.File</refname>
- <refpurpose>Information about an installed application and methods to launch it (with file arguments).</refpurpose>
+ <refpurpose>File and Directory Handling.</refpurpose>
</refnamediv>
<refsect1>
@@ -51,11 +51,11 @@
<methodname><link linkend="method-giofile--copy-async">copy_async</link></methodname>
<methodparam><parameter role="keyword">destination</parameter></methodparam>
<methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam>
<methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
- <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
- <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">progress_callback_data</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
@@ -148,11 +148,11 @@
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--get-child">get_child</link></methodname>
- <methodparam></methodparam>
+ <methodparam><parameter role="keyword">name</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--get-child-for-display-name">get_child_for_display_name</link></methodname>
- <methodparam></methodparam>
+ <methodparam><parameter role="keyword">display_name</parameter></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--get-parent">get_parent</link></methodname>
@@ -206,11 +206,11 @@
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--make-directory">make_directory</link></methodname>
- <methodparam><parameter role="keyword">cancellable</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--make-directory-with-parents">make_directory_with_parents</link></methodname>
- <methodparam><parameter role="keyword">cancellable</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--make-symbolic-link">make_symbolic_link</link></methodname>
@@ -219,18 +219,18 @@
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--monitor">monitor</link></methodname>
- <methodparam><parameter role="keyword">flags</parameter></methodparam>
- <methodparam><parameter role="keyword">cancellable</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--monitor-directory">monitor_directory</link></methodname>
<methodparam><parameter role="keyword">flags</parameter></methodparam>
- <methodparam><parameter role="keyword">cancellable</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--monitor-file">monitor_file</link></methodname>
<methodparam><parameter role="keyword">flags</parameter></methodparam>
- <methodparam><parameter role="keyword">cancellable</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
</methodsynopsis>
<methodsynopsis language="python">
<methodname><link linkend="method-giofile--mount-enclosing-volume">mount_enclosing_volume</link></methodname>
@@ -720,7 +720,7 @@
</refsect2>
<refsect2 id="method-giofile--append-to-finish">
- <title>gio.Volume.append_to_finish</title>
+ <title>gio.File.append_to_finish</title>
<programlisting><methodsynopsis language="python">
<methodname>append_to_finish</methodname>
@@ -853,11 +853,11 @@
<methodname>append_to_async</methodname>
<methodparam><parameter role="keyword">destination</parameter></methodparam>
<methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam>
<methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
- <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
- <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
<methodparam><parameter role="keyword">progress_callback_data</parameter><initializer>None</initializer></methodparam>
</methodsynopsis></programlisting>
@@ -873,6 +873,11 @@
</simpara></listitem>
</varlistentry>
<varlistentry>
+ <term><parameter>progress_callback</parameter> :</term>
+ <listitem><simpara>function to callback with progress information.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
<term><parameter>flags</parameter> :</term>
<listitem><simpara>a set of
<xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>.
@@ -886,19 +891,14 @@
</simpara></listitem>
</varlistentry>
<varlistentry>
- <term><parameter>user_data</parameter> :</term>
- <listitem><simpara>the data to pass to callback function.
- </simpara></listitem>
- </varlistentry>
- <varlistentry>
<term><parameter>cancellable</parameter> :</term>
<listitem><simpara>optional
<link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
object, <literal>None</literal> to ignore.</simpara></listitem>
</varlistentry>
<varlistentry>
- <term><parameter>progress_callback</parameter> :</term>
- <listitem><simpara>function to callback with progress information.
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to callback function.
</simpara></listitem>
</varlistentry>
<varlistentry>
@@ -976,7 +976,7 @@
</refsect2>
<refsect2 id="method-giofile--copy-finish">
- <title>gio.Volume.copy_finish</title>
+ <title>gio.File.copy_finish</title>
<programlisting><methodsynopsis language="python">
<methodname>copy_finish</methodname>
@@ -1119,7 +1119,7 @@
</refsect2>
<refsect2 id="method-giofile--create-finish">
- <title>gio.Volume.create_finish</title>
+ <title>gio.File.create_finish</title>
<programlisting><methodsynopsis language="python">
<methodname>create_finish</methodname>
@@ -1149,7 +1149,7 @@
</refsect2>
<refsect2 id="method-giofile--delete">
- <title>gio.Volume.delete</title>
+ <title>gio.File.delete</title>
<programlisting><methodsynopsis language="python">
<methodname>delete</methodname>
@@ -1183,7 +1183,7 @@
</refsect2>
<refsect2 id="method-giofile--dup">
- <title>gio.Volume.dup</title>
+ <title>gio.File.dup</title>
<programlisting><methodsynopsis language="python">
<methodname>dup</methodname>
@@ -1211,5 +1211,1607 @@
This call does no blocking i/o.
</para>
</refsect2>
+
+ <refsect2 id="method-giofile--eject-mountable">
+ <title>gio.File.eject_mountable</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>eject_mountable</methodname>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>eject_mountable</methodname>() method starts an asynchronous eject on a
+ mountable. When this operation has completed, callback will be called with
+ user_user data, and the operation can be finalized with
+ <methodname><link linkend="method-giofile--eject-mountable-finish">gio.File.eject_mountable_finish</link></methodname>().
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be cancelled by
+ triggering the cancellable object from another thread. If the operation was cancelled,
+ the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--eject-mountable-finish">
+ <title>gio.File.eject_mountable_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>eject_mountable_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if the file was ejected successfully,
+ <literal>False</literal> on error.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>create_finish</methodname>() method finishes an asynchronous
+ copy operation started with
+ <methodname><link linkend="method-giofile--create-async">gio.File.create_async</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--enumerate-children">
+ <title>gio.File.enumerate_children</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>enumerate_children</methodname>
+ <methodparam><parameter role="keyword">attributes</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>attributes</parameter> :</term>
+ <listitem><simpara>an attribute query string.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
+ or <literal>None</literal> on error.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>enumerate_children</methodname>() method gets the requested information
+ about the files in a directory. The result is a GFileEnumerator object that will give out
+ <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> objects
+ for all the files in the directory.
+ </para>
+ <para>
+ The attribute value is a string that specifies the file attributes that should be gathered.
+ It is not an error if it's not possible to read a particular requested attribute from a file -
+ it just won't be set. attribute should be a comma-separated list of attribute or attribute
+ wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all
+ attributes in the standard namespace. An example attribute query be "standard::*,owner::user".
+ The standard attributes are available as defines, like gio.FILE_ATTRIBUTE_STANDARD_NAME.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ <para>
+ If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. If the file
+ is not a directory, the gio.FILE_ERROR_NOTDIR error will be returned.
+ Other errors are possible too.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--enumerate-children-async">
+ <title>gio.File.enumerate_children_async</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>enumerate_children_async</methodname>
+ <methodparam><parameter role="keyword">attributes</parameter></methodparam>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>attributes</parameter> :</term>
+ <listitem><simpara>an attribute query string.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>io_priority</parameter> :</term>
+ <listitem><simpara>the
+ <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref>
+ of the request.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>enumerate_children_async</methodname>() method asynchronously gets the
+ requested information about the files in a directory. The result is a
+ <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
+ object that will give out <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+ objects for all the files in the directory.
+ </para>
+ <para>
+ For more details, see
+ <methodname><link linkend="method-giofile--enumerate-children">enumerate_children</link></methodname>()
+ which is the synchronous version of this call.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--enumerate-children-finish">
+ <title>gio.File.eject_mountable_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>enumerate_children_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link>
+ or <literal>None</literal> if an error occurred.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>enumerate_children_finish</methodname>() method finishes an asynchronous
+ copy operation started with
+ <methodname><link linkend="method-giofile--enumerate-children-async">gio.File.enumerate_children_async</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--equal">
+ <title>gio.File.equal</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>equal</methodname>
+ <methodparam><parameter role="keyword">file2</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">file2</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if file1 and file2 are equal.
+ <literal>False</literal> if either is not a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>equal</methodname>() method checks equality of two given
+ <link linkend="class-giofile"><classname>gio.File</classname></link>s.
+ Note that two <link linkend="class-giofile"><classname>gio.File</classname></link>s
+ that differ can still refer to the same file on the filesystem due to various
+ forms of filename aliasing.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--find-enclosing-mount">
+ <title>gio.File.find_enclosing_mount</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>enumerate_children</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giomount"><classname>gio.Mount</classname></link>
+ or <literal>None</literal> on error.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>find_enclosing_mount</methodname>() method gets a
+ <link linkend="class-giomount"><classname>gio.Mount</classname></link> for the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </para>
+ <para>
+ If the interface for file does not have a mount (e.g. possibly a remote share),
+ error will be set to gio.ERROR_NOT_FOUND and <literal>None</literal> will be returned.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--find-enclosing-mount-async">
+ <title>gio.File.find_enclosing_mount_async</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>find_enclosing_mount_async</methodname>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>io_priority</parameter> :</term>
+ <listitem><simpara>the
+ <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref>
+ of the request.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>find_enclosing_mount_async</methodname>() method asynchronously
+ gets the mount for the file.
+ </para>
+ <para>
+ For more details, see
+ <methodname><link linkend="method-giofile--find-enclosing-mount">gio.File.find_enclosing_mount</link></methodname>()
+ which is the synchronous version of this call.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--find-enclosing-mount-finish">
+ <title>gio.File.find_enclosing_mount_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>find_enclosing_mount_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giomount"><classname>gio.Mount</classname></link>
+ or <literal>None</literal> if an error occurred.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>find_enclosing_mount_finish</methodname>() method finishes an asynchronous
+ find mount started with
+ <methodname><link linkend="method-giofile--find-enclosing-mount-async">gio.File.find_enclosing_mount_async</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-basename">
+ <title>gio.File.get_basename</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_basename</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>string containing the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>'s
+ base name, or <literal>None</literal> if given
+ <link linkend="class-giofile"><classname>gio.File</classname></link> is invalid.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_basename</methodname>() method gets the base name
+ (the last component of the path) for a given
+ <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </para>
+ <para>
+ If called for the top level of a system (such as the filesystem root or
+ a uri like sftp://host/) it will return a single directory separator
+ (and on Windows, possibly a drive letter).
+ </para>
+ <para>
+ The base name is a byte string (*not* UTF-8). It has no defined encoding
+ or rules other than it may not contain zero bytes. If you want to use filenames
+ in a user interface you should use the display name that you can get by requesting
+ the gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with
+ <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>().
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-child">
+ <title>gio.File.get_child</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_child</methodname>
+ <methodparam><parameter role="keyword">name</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">name</parameter> :</term>
+ <listitem><simpara>string containing the child's basename.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>
+ to a child specified by name.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_child</methodname>() method gets a child of file
+ with basename equal to name.
+ </para>
+ <para>
+ Note that the file with that specific name might not exist, but you can
+ still have a <link linkend="class-giofile"><classname>gio.File</classname></link>
+ that points to it. You can use this for instance to create that file.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-child-for-display-name">
+ <title>gio.File.get_child_for_display_name</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_child_for_display_name</methodname>
+ <methodparam><parameter role="keyword">display_name</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">display_name</parameter> :</term>
+ <listitem><simpara>string to a possible child.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>
+ to the specified child or <literal>None</literal>
+ if the display name couldn't be converted.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_child_for_display_name</methodname>() method gets the
+ child of file for a given display_name (i.e. a UTF8 version of the name).
+ If this function fails, it returns NULL and error will be set. This is very
+ useful when constructing a GFile for a new file and the user entered the filename
+ in the user interface, for instance when you select a directory and type a filename
+ in the file selector.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-parent">
+ <title>gio.File.get_parent</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_parent</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>
+ structure to the parent of the given
+ <link linkend="class-giofile"><classname>gio.File</classname></link> or
+ <literal>None</literal> if there is no parent.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_parent</methodname>() method gets the parent directory for the file.
+ If the file represents the root directory of the file system, then <literal>None</literal>
+ will be returned.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-parse-name">
+ <title>gio.File.get_parse_name</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_parse_name</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a string containing the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>'s parse name.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_parse_name</methodname>() method gets the parse name
+ of the file. A parse name is a UTF-8 string that describes the file such
+ that one can get the <link linkend="class-giofile"><classname>gio.File</classname></link>
+ back using
+ <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname>().
+ </para>
+ <para>
+ This is generally used to show the <link linkend="class-giofile"><classname>gio.File</classname></link>
+ as a nice full-pathname kind of string in a user interface, like in a location entry.
+ </para>
+ <para>
+ For local files with names that can safely be converted to UTF8 the pathname is used,
+ otherwise the IRI is used (a form of URI that allows UTF8 characters unescaped).
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-path">
+ <title>gio.File.get_path</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_path</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a string containing the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>'s path,
+ or <literal>None</literal> if no such path exists.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_path</methodname>() method gets the local pathname for
+ <link linkend="class-giofile"><classname>gio.File</classname></link>, if one exists.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-relative-path">
+ <title>gio.File.get_relative_path</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_relative_path</methodname>
+ <methodparam><parameter role="keyword">descendant</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">descendant</parameter> :</term>
+ <listitem><simpara>input <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>string with the relative path from descendant to parent,
+ or <literal>None</literal> if descendant doesn't have parent as prefix.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_relative_path</methodname>() method gets the path for
+ descendant relative to parent.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-uri">
+ <title>gio.File.get_uri</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_uri</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a string containing the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>'s URI.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_uri</methodname>() method gets the URI for the file.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--get-uri-scheme">
+ <title>gio.File.get_uri_scheme</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>get_uri_scheme</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a string containing the URI scheme for the
+ <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>get_uri_scheme</methodname>() method gets the URI scheme for a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ RFC 3986 decodes the scheme as:
+ </para>
+<programlisting>
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
+</programlisting>
+ <para>
+ Common schemes include "file", "http", "ftp", etc.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--has-prefix">
+ <title>gio.File.has_prefix</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>has_prefix</methodname>
+ <methodparam><parameter role="keyword">prefix</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">prefix</parameter> :</term>
+ <listitem><simpara>input <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if the files's parent, grandparent,
+ etc is prefix. <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>has_prefix</methodname>() method checks whether file has the prefix
+ specified by prefix. In other word, if the names of inital elements of files pathname
+ match prefix. Only full pathname elements are matched, so a path like /foo is not
+ considered a prefix of /foobar, only of /foo/bar.
+ </para>
+ <para>
+ This call does no blocking i/o, as it works purely on names. As such it can sometimes
+ return <literal>False</literal> even if file is inside a prefix (from a filesystem point
+ of view), because the prefix of file is an alias of prefix.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--has-uri-scheme">
+ <title>gio.File.has_uri_scheme</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>has_uri_scheme</methodname>
+ <methodparam><parameter role="keyword">uri_scheme</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">uri_scheme</parameter> :</term>
+ <listitem><simpara>a string containing a URI scheme.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if
+ <link linkend="class-giofile"><classname>gio.File</classname></link>'s
+ backend supports the given URI scheme, <literal>False</literal> if URI scheme
+ is <literal>None</literal>, not supported, or
+ <link linkend="class-giofile"><classname>gio.File</classname></link> is invalid.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>has_uri_scheme</methodname>() method checks to see if a
+ <link linkend="class-giofile"><classname>gio.File</classname></link>
+ has a given URI scheme.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--is-native">
+ <title>gio.File.is_native</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>is_native</methodname>
+ <methodparam></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if file is native.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>is_native</methodname>() method checks to see if a file
+ is native to the platform.
+ </para>
+ <para>
+ A native file s one expressed in the platform-native filename format, e.g.
+ "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it
+ might be on a locally mounted remote filesystem.
+ </para>
+ <para>
+ On some systems non-native files may be available using the native filesystem
+ via a userspace filesystem (FUSE), in these cases this call will return
+ <literal>False</literal>, but
+ <methodname><link linkend="method-giofile--get-path">gio.File.get_path</link></methodname>()
+ will still return a native path.
+ </para>
+ <para>
+ This call does no blocking i/o.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--load-contents">
+ <title>gio.File.load_contents</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>load_contents</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a three tuple containing the contents of the file,
+ the length of the contents of the file and the current entity tag for the file.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>load_contents</methodname>() method loads the content of the file into memory.
+ The data is always zero-terminated, but this is not included in the resultant length.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--load-contents-async">
+ <title>gio.File.load_contents_async</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>load_contents_async</methodname>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>load_contents_async</methodname>() method starts an asynchronous load of the file's contents.
+ </para>
+ <para>
+ For more details, see
+ <methodname><link linkend="method-giofile--load-contents">gio.File.load_contents</link></methodname>()
+ which is the synchronous version of this call.
+ </para>
+ <para>
+ When the load operation has completed, callback will be called with user data. To finish
+ the operation, call
+ <methodname><link linkend="method-giofile--load-contents-finish">gio.File.load_contents_finish</link></methodname>()
+ with the GAsyncResult returned by the callback.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--load-contents-finish">
+ <title>gio.File.load_contents_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>load_contents_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a three tuple containing the contents of the file,
+ the length of the contents of the file and the current entity tag for the file.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>load_contents_finish</methodname>() method finishes an asynchronous
+ find mount started with
+ <methodname><link linkend="method-giofile--load-contents-async">gio.File.load_contents_async</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--make-directory">
+ <title>gio.File.make_directory</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>make_directory</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> on successful creation,
+ <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>make_directory</methodname>() method creates a directory.
+ Note that this will only create a child directory of the immediate parent directory
+ of the path or URI given by the <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ To recursively create directories, see
+ <methodname><link linkend="method-giofile--make-directory-with-parents">gio.File.make_directory_with_parents</link></methodname>().
+ This function will fail if the parent directory does not exist, setting error to
+ gio.ERROR_NOT_FOUND. If the file system doesn't support creating directories, this
+ function will fail, setting error to gio.ERROR_NOT_SUPPORTED.
+ </para>
+ <para>
+ For a local <link linkend="class-giofile"><classname>gio.File</classname></link> the newly
+ created directory will have the default (current) ownership and permissions of the current process.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--make-directory-with-parents">
+ <title>gio.File.make_directory_with_parents</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>make_directory_with_parents</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if all directories have been successfully created,
+ <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>make_directory_with_parents</methodname>() method creates a directory
+ and any parent directories that may not exist similar to 'mkdir -p'. If the file system
+ does not support creating directories, this function will fail, setting error to gio.ERROR_NOT_SUPPORTED.
+ </para>
+ <para>
+ For a local <link linkend="class-giofile"><classname>gio.File</classname></link> the newly
+ created directories will have the default (current) ownership and permissions of the current process.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--make-symbolic-link">
+ <title>gio.File.make_symbolic_link</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>make_symbolic_link</methodname>
+ <methodparam><parameter role="keyword">symlink_value</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>symlink_value</parameter> :</term>
+ <listitem><simpara>a string with the value of the new symlink.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> on the creation of a new symlink,
+ <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>make_symbolic_link</methodname>() method creates a symbolic link.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--monitor">
+ <title>gio.File.monitor</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>monitor</methodname>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>
+ a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link>
+ for the given file, or <literal>None</literal> on error
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>monitor</methodname>() method obtains a file or directory
+ monitor for the given file, depending on the type of the file.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--monitor-directory">
+ <title>gio.File.monitor_directory</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>monitor_directory</methodname>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>
+ a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link>
+ for the given file, or <literal>None</literal> on error
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>monitor_directory</methodname>() method obtains a directory monitor
+ for the given file. This may fail if directory monitoring is not supported.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--monitor-file">
+ <title>gio.File.monitor_file</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>monitor_file</methodname>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>
+ a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link>
+ for the given file, or <literal>None</literal> on error
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>monitor_file</methodname>() method obtains a file monitor for the
+ given file. If no file notification mechanism exists, then regular polling
+ of the file is used.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--mount-enclosing-volume">
+ <title>gio.File.mount_enclosing_volume</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>mount_enclosing_volume</methodname>
+ <methodparam><parameter role="keyword">mount_operation</parameter></methodparam>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>mount_operation</parameter> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
+ or <literal>None</literal> to avoid user interaction.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request
+ is satisfied, or <literal>None</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to the progress callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>mount_enclosing_volume</methodname>() method starts a mount_operation,
+ mounting the volume that contains the file location.
+ </para>
+ <para>
+ When this operation has completed, callback will be called with user_user data,
+ and the operation can be finalized with
+ <methodname><link linkend="method-giofile--mount-enclosing-volume-finish">gio.File.mount_enclosing_volume_finish</link></methodname>().
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be cancelled
+ by triggering the cancellable object from another thread. If the operation was cancelled,
+ the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--mount-enclosing-volume-finish">
+ <title>gio.File.mount_enclosing_volume_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>mount_enclosing_volume_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if successful. If an error has occurred,
+ this function will return <literal>False</literal> and set error appropriately if present.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>mount_enclosing_volume_finish</methodname>() method finishes an asynchronous
+ find mount started with
+ <methodname><link linkend="method-giofile--mount-enclosing-volume">gio.File.mount_enclosing_volume</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--mount-mountable">
+ <title>gio.File.mount_mountable</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>mount_mountable</methodname>
+ <methodparam><parameter role="keyword">mount_operation</parameter></methodparam>
+ <methodparam><parameter role="keyword">callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>mount_operation</parameter> :</term>
+ <listitem><simpara>a
+ <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>
+ or <literal>None</literal> to avoid user interaction.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter> :</term>
+ <listitem><simpara>a GAsyncReadyCallback to call when the request
+ is satisfied, or <literal>None</literal>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to the progress callback function.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>mount_mountable</methodname>() method mounts a file of type
+ gio.FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when,
+ for instance, passwords are needed during authentication.
+ </para>
+ <para>
+ When this operation has completed, callback will be called with user_user data,
+ and the operation can be finalized with
+ <methodname><link linkend="method-giofile--mount-mountable-finish">gio.File.mount_mountable_finish</link></methodname>().
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be cancelled
+ by triggering the cancellable object from another thread. If the operation was cancelled,
+ the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--mount-mountable-finish">
+ <title>gio.File.mount_mountable_finish</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>mount_mountable_finish</methodname>
+ <methodparam><parameter role="keyword">result</parameter></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter role="keyword">result</parameter> :</term>
+ <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link>
+ or <literal>None</literal> on error.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>mount_mountable_finish</methodname>() method finishes an asynchronous
+ find mount started with
+ <methodname><link linkend="method-giofile--mount-mountable">gio.File.mount_mountable</link></methodname>().
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--move">
+ <title>gio.File.move</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>copy</methodname>
+ <methodparam><parameter role="keyword">destination</parameter></methodparam>
+ <methodparam><parameter role="keyword">progress_callback</parameter></methodparam>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>destination</parameter> :</term>
+ <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link>.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>progress_callback</parameter> :</term>
+ <listitem><simpara>function to callback with progress information.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>a set of
+ <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>user_data</parameter> :</term>
+ <listitem><simpara>the data to pass to the progress callback function.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> on success,
+ <literal>False</literal> otherwise.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>move</methodname>() method tries to move the file or directory
+ source to the location specified by destination. If native move operations are
+ supported then this is used, otherwise a copy + delete fallback is used. The native
+ implementation may support moving directories (for instance on moves inside the same
+ filesystem), but the fallback code does not.
+ </para>
+ <para>
+ If the flag gio.FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten.
+ </para>
+ <para>
+ If the flag gio.FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied
+ as symlinks, otherwise the target of the source symlink will be copied.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be cancelled
+ by triggering the cancellable object from another thread. If the operation was cancelled,
+ the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ <para>
+ If progress_callback is not <literal>None</literal>, then the operation can be monitored
+ by setting this to a GFileProgressCallback function. progress_callback_data will be passed
+ to this function. It is guaranteed that this callback will be called after all data has been
+ transferred with the total number of bytes copied during the operation.
+ </para>
+ <para>
+ If the source file does not exist then the gio.ERROR_NOT_FOUND error is returned,
+ independent on the status of the destination.
+ </para>
+ <para>
+ If gio.FILE_COPY_OVERWRITE is not specified and the target exists, then the error
+ gio.ERROR_EXISTS is returned.
+ </para>
+ <para>
+ If trying to overwrite a file over a directory the gio.ERROR_IS_DIRECTORY error is returned.
+ If trying to overwrite a directory with a directory the gio.ERROR_WOULD_MERGE error is returned.
+ </para>
+ <para>
+ If the source is a directory and the target does not exist, or gio.FILE_COPY_OVERWRITE is specified
+ and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error may be returned
+ (if the native move operation isn't available).
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--query-default-handler">
+ <title>gio.File.query_default_handler</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>query_default_handler</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>
+ if the handle was found, <literal>None</literal> if there were errors.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>query_default_handler</methodname>() method returns the
+ <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> that
+ is registered as the default application to handle the file specified by file.
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be
+ cancelled by triggering the cancellable object from another thread. If the
+ operation was cancelled, the error gio.ERROR_CANCELLED will be returned.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--query-exists">
+ <title>gio.File.query_exists</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>query_exists</methodname>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara><literal>True</literal> if the file exists (and can be detected
+ without error), <literal>False</literal> otherwise (or if cancelled).
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>query_exists</methodname>() method is an tility function to check
+ if a particular file exists. This is implemented using
+ <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>()
+ and as such does blocking I/O.
+ </para>
+ <para>
+ Note that in many cases it is racy to first check for file existence and then execute
+ something based on the outcome of that, because the file might have been created or
+ removed in between the operations. The general approach to handling that is to not check,
+ but just do the operation and handle the errors as they come.
+ </para>
+ <para>
+ As an example of race-free checking, take the case of reading a file, and if it doesn't
+ exist, creating it. There are two racy versions: read it, and on error create it; and:
+ check if it exists, if not create it. These can both result in two processes creating the
+ file (with perhaps a partially written file as the result). The correct approach is to
+ always try to create the file with
+ <methodname><link linkend="method-giofile--create">gio.File.create</link></methodname>()
+ which will either atomically create the file or fail with a gio.ERROR_EXISTS error.
+ </para>
+ <para>
+ However, in many cases an existence check is useful in a user interface, for instance
+ to make a menu item sensitive/insensitive, so that you don't have to fool users that
+ something is possible and then just show and error dialog. If you do this, you should
+ make sure to also handle the errors that can happen due to races when you execute the operation.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--query-file-type">
+ <title>gio.File.query_file_type</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>query_file_type</methodname>
+ <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>flags</parameter> :</term>
+ <listitem><simpara>
+ a <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>
+ <xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref>
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>query_file_type</methodname>() method it's an utility function to inspect
+ the <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>
+ of a file. This is implemented using
+ <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>()
+ and as such does blocking I/O.
+ </para>
+ <para>
+ The primary use case of this method is to check if a file is a regular file, directory, or symlink.
+ </para>
+ </refsect2>
+
+ <refsect2 id="method-giofile--query-filesystem-info">
+ <title>gio.File.query_filesystem_info</title>
+
+ <programlisting><methodsynopsis language="python">
+ <methodname>query_filesystem_info</methodname>
+ <methodparam><parameter role="keyword">attributes</parameter></methodparam>
+ <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam>
+ </methodsynopsis></programlisting>
+
+ <variablelist>
+ <varlistentry>
+ <term><parameter>attributes</parameter> :</term>
+ <listitem><simpara>an attribute query string.
+ </simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>cancellable</parameter> :</term>
+ <listitem><simpara>optional
+ <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>
+ object, <literal>None</literal> to ignore.</simpara></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Returns</emphasis> :</term>
+ <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>
+ or <literal>None</literal> if there was an error.
+ </simpara></listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>
+ The <methodname>query_filesystem_info</methodname>() method it's similar to
+ <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>(),
+ but obtains information about the filesystem the file is on, rather than the
+ file itself. For instance the amount of space available and the type of the filesystem.
+ </para>
+ <para>
+ The attribute value is a string that specifies the file attributes that should be gathered.
+ It is not an error if it's not possible to read a particular requested attribute from a file -
+ it just won't be set. attribute should be a comma-separated list of attribute or attribute
+ wildcards. The wildcard "*" means all attributes, and a wildcard like "fs:*" means all attributes
+ in the fs namespace. The standard namespace for filesystem attributes is "fs". Common attributes
+ of interest are gio.FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes),
+ gio.FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and gio.FILE_ATTRIBUTE_FILESYSTEM_TYPE
+ (type of the filesystem).
+ </para>
+ <para>
+ If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering
+ the cancellable object from another thread. If the operation was cancelled, the error
+ gio.IO_ERROR_CANCELLED will be returned.
+ </para>
+ <para>
+ If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. Other errors
+ are possible too, and depend on what kind of filesystem the file is on.
+ </para>
+ </refsect2>
</refsect1>
</refentry>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
