diff options
Diffstat (limited to 'docs/reference/pygio-file.xml')
| -rw-r--r-- | docs/reference/pygio-file.xml | 4534 |
1 files changed, 4534 insertions, 0 deletions
diff --git a/docs/reference/pygio-file.xml b/docs/reference/pygio-file.xml new file mode 100644 index 0000000..ac85840 --- /dev/null +++ b/docs/reference/pygio-file.xml @@ -0,0 +1,4534 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofile"> + <refnamediv> + <refname>gio.File</refname> + <refpurpose>File and Directory Handling.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.File</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giofile">gio.File</link></methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">path</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">uri</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to">append_to</link></methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to-async">append_to_async</link></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">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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to-finish">append_to_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy">copy</link></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> + <methodsynopsis language="python"> + <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">cancellable</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"> + <methodname><link linkend="method-giofile--copy-attributes">copy_attributes</link></methodname> + <methodparam><parameter role="keyword">destination</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> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy-finish">copy_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create">create</link></methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create-async">create_async</link></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">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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create-finish">create_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--delete">delete</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--dup">dup</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--eject-mountable">eject_mountable</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--eject-mountable-finish">eject_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children">enumerate_children</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children-async">enumerate_children_async</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children-finish">enumerate_children_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--equal">equal</link></methodname> + <methodparam><parameter role="keyword">file2</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount">find_enclosing_mount</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount-async">find_enclosing_mount_async</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount-finish">find_enclosing_mount_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-basename">get_basename</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-child">get_child</link></methodname> + <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><parameter role="keyword">display_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-parent">get_parent</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-parse-name">get_parse_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-path">get_path</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-relative-path">get_relative_path</link></methodname> + <methodparam><parameter role="keyword">descendant</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-uri">get_uri</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-uri-scheme">get_uri_scheme</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--has-prefix">has_prefix</link></methodname> + <methodparam><parameter role="keyword">prefix</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--has-uri-scheme">has_uri_scheme</link></methodname> + <methodparam><parameter role="keyword">uri_scheme</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--is-native">is_native</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents">load_contents</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents-async">load_contents_async</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents-finish">load_contents_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--make-directory">make_directory</link></methodname> + <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><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--make-symbolic-link">make_symbolic_link</link></methodname> + <methodparam><parameter role="keyword">symlink_value</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--monitor">monitor</link></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> + <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><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><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-enclosing-volume">mount_enclosing_volume</link></methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_MOUNT_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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-enclosing-volume-finish">mount_enclosing_volume_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-mountable">mount_mountable</link></methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_MOUNT_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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-mountable-finish">mount_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--move">move</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-default-handler">query_default_handler</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-exists">query_exists</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-file-type">query_file_type</link></methodname> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info">query_filesystem_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info-async">query_filesystem_info_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info-finish">query_filesystem_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info">query_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info-async">query_info_async</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info-finish">query_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-settable-attributes">query_settable_attributes</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-writable-namespace">query_writable_namespace</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read">read</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read-async">read_async</link></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read-finish">read_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace">replace</link></methodname> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</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> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-async">replace_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</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">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents">replace_contents</link></methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents-async">replace_contents_async</link></methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents-finish">replace_contents_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-finish">replace_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--resolve-relative-path">resolve_relative_path</link></methodname> + <methodparam><parameter role="keyword">relative_path</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute">set_attribute</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">value_p</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-byte-string">set_attribute_byte_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-int32">set_attribute_int32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-int64">set_attribute_int64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-string">set_attribute_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-uint32">set_attribute_uint32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-uint64">set_attribute_uint64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-async">set_attributes_async</link></methodname> + <methodparam><parameter role="keyword">info</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-finish">set_attributes_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-from-info">set_attributes_from_info</link></methodname> + <methodparam><parameter role="keyword">info</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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name">set_dispay_name</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name-async">set_display_name_async</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name-finish">set_display_name_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--trash">trash</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--unmount-mountable">unmount_mountable</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_UNMOUNT_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> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--unmount-mountable-finish">unmount_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname> + <methodparam><parameter role="keyword">parse_name</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-giofile">gio.File</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link> is implemented by + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link> is a high + level abstraction for manipulating files on a virtual file system. + <link linkend="class-giofile"><classname>gio.File</classname></link>s are lightweight, + immutable objects that do no I/O upon creation. It is necessary to understand that + <link linkend="class-giofile"><classname>gio.File</classname></link> + objects do not represent files, merely an identifier for a file. All file content + I/O is implemented as streaming operations (see + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> and + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>). + </para> + <para> + To construct a <link linkend="class-giofile"><classname>gio.File</classname></link>, you can use + it's constructor either with a path, an uri or a commandline argument. + <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname>() + from a utf8 string gotten from + <methodname><link linkend="method-giofile--get-parse-name">gio.File.get_parse_name</link></methodname>(). + </para> + <para> + One way to think of a <link linkend="class-giofile"><classname>gio.File</classname></link> is as + an abstraction of a pathname. For normal files the system pathname is what is stored internally, + but as <link linkend="class-giofile"><classname>gio.File</classname></link>s are extensible it + could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. + </para> + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link>s make up hierarchies of + directories and files that correspond to the files on a filesystem. You can move through the + file system with GFile using + <methodname><link linkend="method-giofile--get-parent">gio.File.get_parent</link></methodname>() + to get an identifier for the parent directory, + <methodname><link linkend="method-giofile--get-child">gio.File.get_child</link></methodname>() + to get a child within a directory, + <methodname><link linkend="method-giofile--resolve-relative-path">gio.File.resolve_relative_path</link></methodname>() + to resolve a relative path between two <link linkend="class-giofile"><classname>gio.File</classname></link>s. + There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call + <methodname><link linkend="method-giofile--get-parent">gio.File.get_parent</link></methodname>() + on two different files. + </para> + <para> + All <link linkend="class-giofile"><classname>gio.File</classname></link>s have a basename (get with + <methodname><link linkend="method-giofile--get-basename">gio.File.get_basename</link></methodname>() + ). These names are byte strings that are used to identify the file on the filesystem + (relative to its parent directory) and there is no guarantees that they have any particular charset + encoding or even make any sense at all. 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>(). + This is guaranteed to be in utf8 and can be used in a user interface. But always store the real basename or the + GFile to use to actually access the file, because there is no way to go from a display name to the actual name. + </para> + <para> + Using <link linkend="class-giofile"><classname>gio.File</classname></link> as an identifier has the same + weaknesses as using a path in that there may be multiple aliases for the same file. For instance, + hard or soft links may cause two different <link linkend="class-giofile"><classname>gio.File</classname></link>s + to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and + long names on Fat/NTFS, or bind mounts in Linux. If you want to check if two GFiles point to the same file + you can query for the gio.FILE_ATTRIBUTE_ID_FILE attribute. Note that + <link linkend="class-giofile"><classname>gio.File</classname></link> does some trivial canonicalization + of pathnames passed in, so that trivial differences in the path string used at creation + (duplicated slashes, slash at end of path, "." or ".." path segments, etc) does not create different + <link linkend="class-giofile"><classname>gio.File</classname></link>s. + </para> + <para> + Many <link linkend="class-giofile"><classname>gio.File</classname></link> operations have both synchronous + and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply + have _async() appended to their function names. The asynchronous I/O functions call a + GAsyncReadyCallback which is then used to finalize the operation, producing a GAsyncResult + which is then passed to the function's matching _finish() operation. + </para> + <para> + Some <link linkend="class-giofile"><classname>gio.File</classname></link> operations do not have + synchronous analogs, as they may take a very long time to finish, and blocking may leave an application + unusable. Notable cases include: + <methodname><link linkend="method-giofile--mount-mountable">gio.File.mount_mountable</link></methodname>() + to mount a mountable file. + <methodname><link linkend="method-giofile--unmount-mountable">gio.File.unmount_mountable</link></methodname>() + to unmount a mountable file. + <methodname><link linkend="method-giofile--eject-mountable">gio.File.eject_mountable</link></methodname>() + to eject a mountable file. + </para> + <para> + One notable feature of <link linkend="class-giofile"><classname>gio.File</classname></link>s are + entity tags, or "etags" for short. Entity tags are somewhat like a more abstract + version of the traditional mtime, and can be used to quickly determine if the file + has been modified from the version on the file system. See the HTTP 1.1 + specification for HTTP Etag headers, which are a very similar concept. + </para> + </refsect1> + + <refsect1 id="constructor-giofile"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.File</methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">path</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">uri</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>commandline</parameter> :</term> + <listitem><simpara>a command line string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>path</parameter> :</term> + <listitem><simpara>a string containing a relative or absolute path. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>uri</parameter> :</term> + <listitem><simpara>a string containing a URI. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giofile"><classname>gio.File</classname></link> either from a commandline, + a path or an uri. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofile--append-to"> + <title>gio.File.append_to</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_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 set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_to</methodname>() method gets an output stream for + appending data to the file. If the file doesn't already exist it is created. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to the + current user, to the level that is supported on the target 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.ERROR_CANCELLED will be returned. + </para> + <para> + Some file systems don't allow all file names, and may return an + gio.ERROR_INVALID_FILENAME error. If the file is a directory the + gio.ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, + and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--append-to-async"> + <title>gio.File.append_to_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to_async</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">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>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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>append_to_async</methodname>() method asynchronously opens file for appending. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--append-to">gio.File.append_to</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--append-to-finish">gio.File.append_to_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--append-to-finish"> + <title>gio.File.append_to_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to_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 valid + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_to_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giofile--append-to-async">gio.File.append_to_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--copy"> + <title>gio.File.copy</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>copy</methodname>() method copies the file source to + the location specified by destination. Can not handle recursive copies of directories. + </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. user_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 gio.ERROR_WOULD_RECURSE error is returned. + </para> + <para> + If you are interested in copying the + <link linkend="class-giofile"><classname>gio.File</classname></link> object + itself (not the on-disk file), see + <methodname><link linkend="method-giofile--dup">gio.File.dup</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-async"> + <title>gio.File.copy_async</title> + + <programlisting><methodsynopsis language="python"> + <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">cancellable</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> + + <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>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </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>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> + <varlistentry> + <term><parameter>progress_callback_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_async</methodname>() method copies the file source to + the location specified by destination asynchronously. For details of the behaviour, + see <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>(). + </para> + <para> + If progress_callback is not <literal>None</literal>, then that function that will + be called just like in + <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>(), + however the callback will run in the main loop, not in the thread that is doing the I/O operation. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--copy-finish">gio.File.copy_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-attributes"> + <title>gio.File.copy_attributes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy_attributes</methodname> + <methodparam><parameter role="keyword">destination</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> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>destination</parameter> :</term> + <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link> + to copy attributes to. + </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><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attributes were copied successfully, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_attributes</methodname>() method copies the file attributes + from source to destination. + </para> + <para> + Normally only a subset of the file attributes are copied, those that are copies + in a normal file copy operation (which for instance does not include e.g. owner). + However if gio.FILE_COPY_ALL_METADATA is specified in flags, then all the metadata + that is possible to copy is copied. This is useful when implementing move by copy + delete source. + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-finish"> + <title>gio.File.copy_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy_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> on success, + <literal>False</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--copy-async">gio.File.copy_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--create"> + <title>gio.File.create</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_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 set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>create</methodname>() method creates a new file and returns + an output stream for writing to it. The file must not already exist. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to the + current user, to the level that is supported on the target 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.ERROR_CANCELLED will be returned. + </para> + <para> + If a file or directory with this name already exists the gio.ERROR_EXISTS + error will be returned. Some file systems don't allow all file names, and + may return an gio.ERROR_INVALID_FILENAME error, and if the name is to long + gio.ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, + and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--create-async"> + <title>gio.File.create_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create_async</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">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>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>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>create_async</methodname>() method asynchronously creates a new + file and returns an output stream for writing to it. The file must not already exist. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--create">gio.File.create</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--create-finish">gio.File.create_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--create-finish"> + <title>gio.File.create_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create_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-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</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--delete"> + <title>gio.File.delete</title> + + <programlisting><methodsynopsis language="python"> + <methodname>delete</methodname> + <methodparam><parameter role="keyword">cancellable</parameter></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 was deleted, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>deleted</methodname>() method deletes a file. If the file is a + directory, it will only be deleted if it is empty. + </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--dup"> + <title>gio.File.dup</title> + + <programlisting><methodsynopsis language="python"> + <methodname>dup</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link linkend="class-giofile"><classname>gio.File</classname></link> + that is a duplicate of the given <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>dup</methodname>() method duplicates a + <link linkend="class-giofile"><classname>gio.File</classname></link> + handle. This operation does not duplicate the actual file or directory represented + by the <link linkend="class-giofile"><classname>gio.File</classname></link>; see + <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>() + if attempting to copy a file. + </para> + <para> + 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 gio.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.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> + + <refsect2 id="method-giofile--query-filesystem-info-async"> + <title>gio.File.query_filesystem_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_filesystem_info_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <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>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>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>query_filesystem_info_async</methodname>() method asynchronously + gets the requested information about the filesystem that the specified file is on. + The result is a GFileInfo object that contains key-value attributes + (such as type or size for the file). + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--query-filesystem-info">query_filesystem_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--query-filesystem-info-finish">gio.File.query_filesystem_info_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-filesystem-info-finish"> + <title>gio.File.query_filesystem_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_filesystem_info_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-giofileinfo"><classname>gio.FileInfo</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_filesystem_info_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--query-filesystem-info-async">gio.File.query_filesystem_info_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--query-info"> + <title>gio.File.query_filesystem_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info</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 <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-giofileinfo"><classname>gio.FileInfo</classname></link> + for the given file or <literal>None</literal> if there was an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info</methodname>() method gets the requested + information about specified file. The result is a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + object that contains key-value attributes (such as the type or size of the file). + </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> + For symlinks, normally the information about the target of the symlink is returned, + rather than information about the symlink itself. However if you pass + gio.FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in flags the information about + the symlink itself will be returned. Also, for symlinks that point to non-existing + files the information about the symlink itself 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> + + <refsect2 id="method-giofile--query-info-async"> + <title>gio.File.query_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_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 <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>query_info_async</methodname>() method asynchronously gets the + requested information about specified file. The result is a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + object that contains key-value attributes (such as type or size for the file). + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--query-info">query_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--query-info-finish">gio.File.query_info_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-info-finish"> + <title>gio.File.query_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_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-giofileinfo"><classname>gio.FileInfo</classname></link> + for the given file or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--query-info-async">gio.File.query_info_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--query-settable-attributes"> + <title>gio.File.query_settable_attributes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_settable_attributes</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 list of + <link linkend="class-giofileattributeinfo"><classname>gio.FileAttributeInfo</classname></link> + describing the settable attributes. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_settable_attributes</methodname>() method obtain the + list of settable attributes for the file. + </para> + <para> + Returns the type and full attribute name of all the attributes that can be + set on this file. This doesn't mean setting it will always succeed though, + you might get an access failure, or some specific file may not support a specific attribute. + </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-writable-namespace"> + <title>gio.File.query_writable_namespace</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_writable_namespace</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 list of + <link linkend="class-giofileattributeinfo"><classname>gio.FileAttributeInfo</classname></link> + describing the writable namespaces. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_writable_namespace</methodname>() method obtain the + list of attribute namespaces where new attributes can be created by a user. + An example of this is extended attributes (in the "xattr" namespace). + </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--read"> + <title>gio.File.read</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read</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-giofileinputstream"><classname>gio.FileInputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read</methodname>() method opens a file for reading. The result + is a <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + that can be used to read the contents 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> + <para> + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. + If the file is a directory, the gio.ERROR_IS_DIRECTORY error will be returned. + Other errors are possible too, and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--read-async"> + <title>gio.File.read_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_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>read_async</methodname>() method asynchronously opens file for reading. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--read">read</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--read-finish">gio.File.read_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--read-finish"> + <title>gio.File.read_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_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-giofileinputstream"><classname>gio.FileInputStream</classname></link> + file or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--read-async">gio.File.read_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--replace"> + <title>gio.File.replace</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace</methodname> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</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> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace</methodname>() method returns an output stream for + overwriting the file, possibly creating a backup copy of the file first. + If the file doesn't exist, it will be created. + </para> + <para> + This will try to replace the file in the safest way possible so that any + errors during the writing will not affect an already existing copy of the file. + For instance, for local files it may write to a temporary file and then atomically + rename over the destination when the stream is closed. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to + the current user, to the level that is supported on the target 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.ERROR_CANCELLED will be returned. + </para> + <para> + If you pass in a non-<literal>None</literal> etag value, then this value is compared + to the current entity tag of the file, and if they differ an gio.ERROR_WRONG_ETAG error + is returned. This generally means that the file has been changed since you last read it. + You can get the new etag from + <methodname><link linkend="method-giofileoutputstream--get-etag">gio.FileOutputStream.get_etag</link></methodname>() + after you've finished writing and closed the GFileOutputStream. When you load a new file you can use + <methodname><link linkend="method-giofileinputstream--query-info">gio.FileInputStream.query_info</link></methodname>() + to get the etag of the file. + </para> + <para> + If make_backup is <literal>True</literal>, this function will attempt to make a backup + of the current file before overwriting it. If this fails a gio.ERROR_CANT_CREATE_BACKUP + error will be returned. If you want to replace anyway, try again + with make_backup set to <literal>False</literal>. + </para> + <para> + If the file is a directory the gio.ERROR_IS_DIRECTORY error will be returned, and + if the file is some other form of non-regular file then a gio.ERROR_NOT_REGULAR_FILE + error will be returned. Some file systems don't allow all file names, and may return an + gio.ERROR_INVALID_FILENAME error, and if the name is to long gio.ERROR_FILENAME_TOO_LONG + will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-async"> + <title>gio.File.replace_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</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">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>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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>replace_async</methodname>() method asynchronously overwrites the file, + replacing the contents, possibly creating a backup copy of the file first. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--replace">replace</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--replace-finish">gio.File.replace_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents"> + <title>gio.File.replace_contents</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_contents</methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</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> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>contents</parameter> :</term> + <listitem><simpara>a string containing the new contents for file. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>the old entity tag for the document + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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>the new entity tag for the document. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_contents</methodname>() method replaces the contents + of file with contents of length bytes. If etag is specified (not NULL) any existing + file must have that etag, or the error gio.ERROR_WRONG_ETAG will be returned. + </para> + <para> + If make_backup is <literal>True</literal>, this function will attempt to make a backup of 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> + <para> + The returned etag can be used to verify that the file hasn't changed the next time it is saved over. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents-async"> + <title>gio.File.replace_contents_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_contents_async</methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</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">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>contents</parameter> :</term> + <listitem><simpara>a string containing the new contents for file. + </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>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-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>replace_contents_async</methodname>() method starts an asynchronous + replacement of file with the given contents of length bytes. etag will + replace the document's current entity tag. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--replace-contents">replace_contents</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--replace-contents-finish">gio.File.replace_contents_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents-finish"> + <title>gio.File.replace_contents_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_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>the new entity tag for the document. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_contents_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--replace-contents-async">gio.File.replace_contents_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-finish"> + <title>gio.File.replace_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_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-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--replace-async">gio.File.replace_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--resolve-relative-path"> + <title>gio.File.resolve_relative_path</title> + + <programlisting><methodsynopsis language="python"> + <methodname>resolve_relative_path</methodname> + <methodparam><parameter role="keyword">relative_path</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">relative_path</parameter> :</term> + <listitem><simpara>a given relative path string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link> + to the resolved path. <literal>None</literal> if relative_path is <literal>None</literal> + or if file is invalid. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>resolve_relative_path</methodname>() method resolves a + relative path for file to an absolute path. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute"> + <title>gio.File.set_attribute</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">value_p</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>the type of the attribute . + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value_p</parameter> :</term> + <listitem><simpara>the value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute</methodname>() method sets an attribute in + the file with attribute name attribute to value. + </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--set-attribute-byte-string"> + <title>gio.File.set_attribute_byte_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_byte_string</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a string containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_byte_string</methodname>() method Sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING to value. If attribute is of a different type, + this operation will fail, returning <literal>False</literal>. + </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--set-attribute-int32"> + <title>gio.File.set_attribute_int32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_int32</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>an int containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_int32</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_INT32 to value. If attribute is of a different type, + this operation will fail. + </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--set-attribute-int64"> + <title>gio.File.set_attribute_int64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_int64</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a long containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_int64</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_INT64 to value. If attribute is of a different type, + this operation will fail. + </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--set-attribute-string"> + <title>gio.File.set_attribute_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_string</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a string containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_string</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_STRING to value. If attribute is of a different type, + this operation will fail. + </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--set-attribute-uint32"> + <title>gio.File.set_attribute_uint32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_uint32</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>an int containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_uint32</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_UINT32 to value. If attribute is of a different type, + this operation will fail. + </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--set-attribute-uint64"> + <title>gio.File.set_attribute_uint64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_uint64</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</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>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a long containing the attribute's new value. + </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><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_uint64</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_UINT64 to value. If attribute is of a different type, + this operation will fail. + </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--set-attributes-async"> + <title>gio.File.set_attributes_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_async</methodname> + <methodparam><parameter role="keyword">info</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>info</parameter> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </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>set_attributes_async</methodname>() method asynchronously + sets the attributes of file with info. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--set-attributes-from-info">set_attributes_from_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--set-attributes-finish">gio.File.set_attributes_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attributes-finish"> + <title>gio.File.set_attributes_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_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 attributes were set correctly, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attributes_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--set-attributes-async">gio.File.set_attributes_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attributes-from-info"> + <title>gio.File.set_attributes_from_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_from_info</methodname> + <methodparam><parameter role="keyword">info</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>info</parameter> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </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><literal>True</literal> if the attributes were set correctly, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attributes_from_info</methodname>() method tries to set + all attributes in the GFileInfo on the target values, not stopping on the first error. + </para> + If there is any error during this operation then error will be set to the + first error. Error on particular fields are flagged by setting the "status" + field in the attribute value to gio.FILE_ATTRIBUTE_STATUS_ERROR_SETTING, + which means you can also detect further errors. + <para> + </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--set-display-name"> + <title>gio.File.set_display_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name</methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>display_name</parameter> :</term> + <listitem><simpara>a string conaining the name to display. + </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-giofile"><classname>gio.File</classname></link> + specifying what file was renamed to, or <literal>None</literal> if there was an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_display_name</methodname>() method renames file to + the specified display name. + </para> + <para> + The display name is converted from UTF8 to the correct encoding for the + target filesystem if possible and the file is renamed to this. + </para> + <para> + If you want to implement a rename operation in the user interface the + edit name (gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the + initial value in the rename widget, and then the result after editing + should be passed to + <methodname><link linkend="method-giofile--set-display-name">gio.File.set_dispay_name</link></methodname>(). + </para> + <para> + On success the resulting converted filename is 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--set-display-name-async"> + <title>gio.File.set_display_name_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name_async</methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <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>display_name</parameter> :</term> + <listitem><simpara>a string conaining the name to display. + </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>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>set_display_name_async</methodname>() method asynchronously + sets the display name for a given GFile. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--set-display-name">set_display_name</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--set-display-name-finish">gio.File.set_display_name_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-display-name-finish"> + <title>gio.File.set_display_name_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name_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>set_display_name_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--set-display-name-async">gio.File.set_display_name_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--trash"> + <title>gio.File.trash</title> + + <programlisting><methodsynopsis language="python"> + <methodname>trash</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 trash, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>trash</methodname>() method sends file to the "Trashcan", if possible. + This is similar to deleting it, but the user can recover it before emptying the trashcan. + Not all file systems support trashing, so this call can return the gio.ERROR_NOT_SUPPORTED error. + </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--unmount-mountable"> + <title>gio.File.unmount_mountable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount_mountable</methodname> + <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">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-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><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>unmount_mountable</methodname>() method unmounts a file of type gio.FILE_TYPE_MOUNTABLE. + </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> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--unmount-mountable-finish">gio.File.unmount_mountable_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--unmount-mountable-finish"> + <title>gio.File.unmount_mountable_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount_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 operation finished successfully, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>unmount_mountable_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--unmount-mountable">gio.File.unmount_mountable</link></methodname>(). + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--file-parse-name"> + <title>gio.file_parse_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>file_parse_name</methodname> + <methodparam><parameter role="keyword">parse_name</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>parse_name</parameter> :</term> + <listitem><simpara>a file name or path to be parsed. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>parse_name</methodname>() function constructs a + <link linkend="class-giofile"><classname>gio.File</classname></link> + with the given parse_name (i.e. something given by g_file_get_parse_name()). + This operation never fails, but the returned object might not support any I/O + operation if the parse_name cannot be parsed. + </para> + </refsect2> + </refsect1> +</refentry> |