From f2ab953f48ab69a7a205578f4cc37e289e962ee1 Mon Sep 17 00:00:00 2001 From: Gian Mario Tagliaretti Date: Sat, 11 Apr 2009 08:18:40 +0000 Subject: Add gio.File and gio.Seekable in docs, gio.File it's not yet completed 2009-04-11 Gian Mario Tagliaretti * docs/Makefile.am: * docs/reference/pygio-classes.xml: * docs/reference/pygio-constants.xml: * docs/reference/pygio-file.xml: * docs/reference/pygio-seekable.xml: Add gio.File and gio.Seekable in docs, gio.File it's not yet completed only the index is. svn path=/trunk/; revision=1058 --- docs/reference/pygio-file.xml | 1215 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1215 insertions(+) create mode 100644 docs/reference/pygio-file.xml (limited to 'docs/reference/pygio-file.xml') diff --git a/docs/reference/pygio-file.xml b/docs/reference/pygio-file.xml new file mode 100644 index 0000000..148aff7 --- /dev/null +++ b/docs/reference/pygio-file.xml @@ -0,0 +1,1215 @@ + + + + + + gio.File + Information about an installed application and methods to launch it (with file arguments). + + + + Synopsis + + + gio.File + gobject.GInterface + + + gio.File + commandline + pathNone + uriNone + + + + append_to + flagsgio.FILE_CREATE_NONE + cancellableNone + + + append_to_async + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + append_to_finish + result + + + copy + destination + progress_callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + copy_async + destination + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + user_dataNone + cancellableNone + progress_callbackNone + progress_callback_dataNone + + + copy_attributes + destination + flagsgio.FILE_COPY_NONE + cancellableNone + + + copy_finish + result + + + create + flagsgio.FILE_CREATE_NONE + cancellableNone + + + create_async + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + create_finish + result + + + delete + cancellableNone + + + dup + + + + eject_mountable + callback + flagsgio.FILE_CREATE_NONE + cancellableNone + user_dataNone + + + eject_mountable_finish + result + + + enumerate_children + attributes + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + enumerate_children_async + attributes + callback + flagsgio.FILE_QUERY_INFO_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + enumerate_children_finish + result + + + equal + file2 + + + find_enclosing_mount + cancellable + + + find_enclosing_mount_async + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + find_enclosing_mount_finish + result + + + get_basename + + + + get_child + + + + get_child_for_display_name + + + + get_parent + + + + get_parse_name + + + + get_path + + + + get_relative_path + descendant + + + get_uri + + + + get_uri_scheme + + + + has_prefix + prefix + + + has_uri_scheme + uri_scheme + + + is_native + + + + load_contents + cancellable + + + load_contents_async + callback + cancellableNone + user_dataNone + + + load_contents_finish + result + + + make_directory + cancellable + + + make_directory_with_parents + cancellable + + + make_symbolic_link + symlink_value + cancellable + + + monitor + flags + cancellable + + + monitor_directory + flags + cancellable + + + monitor_file + flags + cancellable + + + mount_enclosing_volume + mount_operation + callback + flagsgio.MOUNT_MOUNT_NONE + cancellableNone + user_dataNone + + + mount_enclosing_volume_finish + result + + + mount_mountable + mount_operation + callback + flagsgio.MOUNT_MOUNT_NONE + cancellableNone + user_dataNone + + + mount_mountable_finish + result + + + move + destination + progress_callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + query_default_handler + cancellable + + + query_exists + cancellable + + + query_file_type + flags + cancellable + + + query_filesystem_info + attributes + cancellable + + + query_filesystem_info_async + attributes + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + query_filesystem_info_finish + result + + + query_info + attributes + flags + cancellable + + + query_info_async + callback + attributes + flagsgio.FILE_QUERY_INFO_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + query_info_finish + result + + + query_settable_attributes + cancellableNone + + + query_writable_namespace + cancellableNone + + + read + cancellableNone + + + read_async + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + read_finish + resultNone + + + replace + etag + make_backup + flagsgio.FILE_CREATE_NONE + cancellableNone + + + replace_async + callback + etagNone + make_backupTrue + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + replace_contents + contents + etagNone + make_backupTrue + flagsgio.FILE_CREATE_NONE + cancellableNone + + + replace_contents_async + contents + callback + etagNone + make_backupTrue + flagsgio.FILE_CREATE_NONE + cancellableNone + user_dataNone + + + replace_contents_finish + resultNone + + + replace_finish + resultNone + + + resolve_relative_path + relative_path + + + set_attribute + attribute + type + value_p + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_byte_string + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_int32 + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_int64 + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_string + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_uint32 + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attribute_uint64 + attribute + value + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_attributes_async + info + callback + flagsgio.FILE_QUERY_INFO_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + set_attributes_finish + result + + + set_attributes_from_info + info + flagsgio.FILE_QUERY_INFO_NONE + cancellableNone + + + set_dispay_name + display_name + cancellableNone + + + set_display_name_async + display_name + callback + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + set_display_name_finish + result + + + trash + cancellableNone + + + unmount_mountable + callback + flagsgio.MOUNT_UNMOUNT_NONE + cancellableNone + user_dataNone + + + unmount_mountable_finish + cancellableNone + + + + + +Functions + + gio.file_parse_name + parse_name + + + + + + Ancestry + ++-- gobject.GInterface + +-- gio.File + + + + + + Prerequisites + + gio.File is implemented by + gobject.GObject + + + + + Description + + + gio.File is a high + level abstraction for manipulating files on a virtual file system. + gio.Files are lightweight, + immutable objects that do no I/O upon creation. It is necessary to understand that + gio.File + objects do not represent files, merely an identifier for a file. All file content + I/O is implemented as streaming operations (see + gio.InputStream and + gio.OutputStream). + + + To construct a gio.File, you can use + it's constructor either with a path, an uri or a commandline argument. + gio.file_parse_name() + from a utf8 string gotten from + gio.File.get_parse_name(). + + + One way to think of a gio.File is as + an abstraction of a pathname. For normal files the system pathname is what is stored internally, + but as gio.Files are extensible it + could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. + + + gio.Files 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 + gio.File.get_parent() + to get an identifier for the parent directory, + gio.File.get_child() + to get a child within a directory, + gio.File.resolve_relative_path() + to resolve a relative path between two gio.Files. + There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call + gio.File.get_parent() + on two different files. + + + All gio.Files have a basename (get with + gio.File.get_basename() + ). 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 + gio.File.query_info(). + 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. + + + Using gio.File 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 gio.Files + 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 + gio.File 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 + gio.Files. + + + Many gio.File 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. + + + Some gio.File 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: + gio.File.mount_mountable() + to mount a mountable file. + gio.File.unmount_mountable() + to unmount a mountable file. + gio.File.eject_mountable() + to eject a mountable file. + + + One notable feature of gio.Files 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. + + + + + Methods + + + gio.File.append_to + + + append_to + flagsgio.FILE_CREATE_NONE + cancellableNone + + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a + gio.FileOutputStream + or None on error. + + + + + + The append_to() method gets an output stream for + appending data to the file. If the file doesn't already exist it is created. + + + 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. + + + If cancellable is not None, 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. + + + 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. + + + + + gio.File.append_to_async + + + append_to_async + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + a set of + . + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The append_to_async() method asynchronously opens file for appending. + + + For more details, see + gio.File.append_to() + which is the synchronous version of this call. + + + When the operation is finished, callback will be called. You can then call + gio.File.append_to_finish() + to get the result of the operation. + + + + + gio.Volume.append_to_finish + + + append_to_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a valid + gio.OutputStream + or None on error. + + + + + + The append_to_finish() method finishes an asynchronous + file append operation started with + gio.File.append_to_async(). + + + + + gio.File.copy + + + copy + destination + progress_callback + flagsgio.FILE_COPY_NONE + cancellableNone + user_dataNone + + + + + destination : + destination gio.File. + + + + progress_callback : + function to callback with progress information. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to the progress callback function. + + + + Returns : + True on success, + False otherwise. + + + + + + The copy() method copies the file source to + the location specified by destination. Can not handle recursive copies of directories. + + + If the flag gio.FILE_COPY_OVERWRITE is specified an already existing + destination file is overwritten. + + + 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. + + + If cancellable is not None, 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. + + + If progress_callback is not None, 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. + + + If the source file does not exist then the gio.ERROR_NOT_FOUND error is returned, + independent on the status of the destination. + + + If gio.FILE_COPY_OVERWRITE is not specified and the target exists, + then the error gio.ERROR_EXISTS is returned. + + + 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. + + + 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. + + + If you are interested in copying the + gio.File object + itself (not the on-disk file), see + gio.File.dup(). + + + + + gio.File.copy_async + + + append_to_async + destination + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + user_dataNone + cancellableNone + progress_callbackNone + progress_callback_dataNone + + + + + destination : + destination gio.File. + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + a set of + . + + + + io_priority : + the + + of the request. + + + + user_data : + the data to pass to callback function. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + progress_callback : + function to callback with progress information. + + + + progress_callback_data : + the data to pass to the progress callback function. + + + + + + The copy_async() method copies the file source to + the location specified by destination asynchronously. For details of the behaviour, + see gio.File.copy(). + + + If progress_callback is not None, then that function that will + be called just like in + gio.File.copy(), + however the callback will run in the main loop, not in the thread that is doing the I/O operation. + + + When the operation is finished, callback will be called. You can then call + gio.File.copy_finish() + to get the result of the operation. + + + + + gio.File.copy_attributes + + + copy_attributes + destination + flagsgio.FILE_COPY_NONE + cancellableNone + + + + + destination : + destination gio.File + to copy attributes to. + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True if the attributes were copied successfully, + False otherwise. + + + + + + The copy_attributes() method copies the file attributes + from source to destination. + + + 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. + + + + + gio.Volume.copy_finish + + + copy_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + True on success, + False on error. + + + + + + The copy_finish() method finishes an asynchronous + copy operation started with + gio.File.copy_async(). + + + + + gio.File.create + + + create + flagsgio.FILE_CREATE_NONE + cancellableNone + + + + + flags : + a set of + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + a + gio.FileOutputStream + or None on error. + + + + + + The create() method creates a new file and returns + an output stream for writing to it. The file must not already exist. + + + 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. + + + If cancellable is not None, 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. + + + 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. + + + + + gio.File.create_async + + + create_async + callback + flagsgio.FILE_CREATE_NONE + io_priorityglib.PRIORITY_DEFAULT + cancellableNone + user_dataNone + + + + + callback : + a GAsyncReadyCallback to call when the request is satisfied. + + + + flags : + a set of + . + + + + io_priority : + the + + of the request. + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + user_data : + the data to pass to callback function. + + + + + + The create_async() method asynchronously creates a new + file and returns an output stream for writing to it. The file must not already exist. + + + For more details, see + gio.File.create() + which is the synchronous version of this call. + + + When the operation is finished, callback will be called. You can then call + gio.File.create_finish() + to get the result of the operation. + + + + + gio.Volume.create_finish + + + create_finish + result + + + + + result : + a gio.AsyncResult. + + + + Returns : + a + gio.FileOutputStream + or None on error. + + + + + + The create_finish() method finishes an asynchronous + copy operation started with + gio.File.create_async(). + + + + + gio.Volume.delete + + + delete + cancellable + + + + + cancellable : + optional + gio.Cancellable + object, None to ignore. + + + Returns : + True if the file was deleted, + False otherwise. + + + + + + The deleted() method deletes a file. If the file is a + directory, it will only be deleted if it is empty. + + + If cancellable is not None, 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. + + + + + gio.Volume.dup + + + dup + + + + + + Returns : + a new gio.File + that is a duplicate of the given gio.File. + + + + + + The dup() method duplicates a + gio.File + handle. This operation does not duplicate the actual file or directory represented + by the gio.File; see + gio.File.copy() + if attempting to copy a file. + + + This call does no blocking i/o. + + + + -- cgit