X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gio%2Fgfile.c;h=9cf3f4dd0fe9582a26ce30b8e31c8bacac912bf2;hb=c3842d1969feace4bfb12919be730e75e53877d9;hp=f70bddf2f55ba9521ff626cbf3de2d727364f6c9;hpb=5baa0f2af590d3febbcd7eba0f38dee7d1621fdc;p=platform%2Fupstream%2Fglib.git diff --git a/gio/gfile.c b/gio/gfile.c index f70bddf..9cf3f4d 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -76,13 +76,11 @@ * (see #GInputStream and #GOutputStream). * * To construct a #GFile, you can use: - * - * g_file_new_for_path() if you have a path. - * g_file_new_for_uri() if you have a URI. - * g_file_new_for_commandline_arg() for a command line argument. - * g_file_new_tmp() to create a temporary file from a template. - * g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). - * + * - g_file_new_for_path() if you have a path. + * - g_file_new_for_uri() if you have a URI. + * - g_file_new_for_commandline_arg() for a command line argument. + * - g_file_new_tmp() to create a temporary file from a template. + * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). * * One way to think of a #GFile is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as @@ -131,11 +129,9 @@ * Some #GFile 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: - * - * g_file_mount_mountable() to mount a mountable file. - * g_file_unmount_mountable_with_operation() to unmount a mountable file. - * g_file_eject_mountable_with_operation() to eject a mountable file. - * + * - g_file_mount_mountable() to mount a mountable file. + * - g_file_unmount_mountable_with_operation() to unmount a mountable file. + * - g_file_eject_mountable_with_operation() to eject a mountable file. * * ## Entity Tags # {#gfile-etag} * @@ -490,8 +486,8 @@ g_file_get_uri_scheme (GFile *file) * * This call does no blocking I/O. * - * Returns: string containing the #GFile's base name, or %NULL - * if given #GFile is invalid. The returned string should be + * Returns: (nullable): string containing the #GFile's base name, or + * %NULL if given #GFile is invalid. The returned string should be * freed with g_free() when no longer needed. */ char * @@ -514,9 +510,9 @@ g_file_get_basename (GFile *file) * * This call does no blocking I/O. * - * Returns: string containing the #GFile's path, or %NULL if - * no such path exists. The returned string should be - * freed with g_free() when no longer needed. + * Returns: (nullable): string containing the #GFile's path, or %NULL + * if no such path exists. The returned string should be freed + * with g_free() when no longer needed. */ char * g_file_get_path (GFile *file) @@ -654,7 +650,6 @@ g_file_hash (gconstpointer file) * This call does no blocking I/O. * * Returns: %TRUE if @file1 and @file2 are equal. - * %FALSE if either is not a #GFile. */ gboolean g_file_equal (GFile *file1, @@ -684,9 +679,9 @@ g_file_equal (GFile *file1, * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile structure to the - * parent of the given #GFile or %NULL if there is - * no parent. Free the returned object with g_object_unref(). + * Returns: (nullable) (transfer full): a #GFile structure to the + * parent of the given #GFile or %NULL if there is no parent. Free + * the returned object with g_object_unref(). */ GFile * g_file_get_parent (GFile *file) @@ -853,10 +848,10 @@ g_file_has_prefix (GFile *file, * * This call does no blocking I/O. * - * Returns: string with the relative path from @descendant - * to @parent, or %NULL if @descendant doesn't have @parent - * as prefix. The returned string should be freed with g_free() - * when no longer needed. + * Returns: (nullable): string with the relative path from @descendant + * to @parent, or %NULL if @descendant doesn't have @parent as + * prefix. The returned string should be freed with g_free() when + * no longer needed. */ char * g_file_get_relative_path (GFile *parent, @@ -971,8 +966,7 @@ g_file_enumerate_children (GFile *file, * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -1209,8 +1203,7 @@ g_file_query_info (GFile *file, * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -1347,8 +1340,7 @@ g_file_query_filesystem_info (GFile *file, * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -1470,8 +1462,7 @@ g_file_find_enclosing_mount (GFile *file, /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -1699,7 +1690,7 @@ g_file_create (GFile *file, /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -1904,7 +1895,7 @@ g_file_create_readwrite (GFile *file, /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -1959,8 +1950,7 @@ g_file_replace_readwrite (GFile *file, /** * g_file_read_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2028,8 +2018,7 @@ g_file_read_finish (GFile *file, * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2100,8 +2089,7 @@ g_file_append_to_finish (GFile *file, * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2171,12 +2159,11 @@ g_file_create_finish (GFile *file, /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2250,8 +2237,7 @@ g_file_replace_finish (GFile *file, /** * g_file_open_readwrite_async * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2323,8 +2309,7 @@ g_file_open_readwrite_finish (GFile *file, * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -2398,12 +2383,11 @@ g_file_create_readwrite_finish (GFile *file, /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -3267,7 +3251,7 @@ file_copy_fallback (GFile *source, info, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS, cancellable, - error); + NULL); } g_clear_object (&info); @@ -3404,8 +3388,7 @@ g_file_copy (GFile *source, * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @progress_callback: (allow-none): function to callback with progress @@ -3418,8 +3401,9 @@ g_file_copy (GFile *source, * asynchronously. For details of the behaviour, see g_file_copy(). * * If @progress_callback is not %NULL, then that function that will be called - * just like in g_file_copy(), however the callback will run in the main loop, - * not in the thread that is doing the I/O operation. + * just like in g_file_copy(). The callback will run in the default main context + * of the thread calling g_file_copy_async() — the same context as @callback is + * run in. * * When the operation is finished, @callback will be called. You can then call * g_file_copy_finish() to get the result of the operation. @@ -3665,8 +3649,7 @@ g_file_make_directory (GFile *file, /** * g_file_make_directory_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -3915,8 +3898,7 @@ g_file_delete (GFile *file, /** * g_file_delete_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -4025,8 +4007,7 @@ g_file_trash (GFile *file, /** * g_file_trash_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -4144,8 +4125,7 @@ g_file_set_display_name (GFile *file, * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -4474,8 +4454,7 @@ g_file_real_set_attributes_from_info (GFile *file, * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback @@ -7093,11 +7072,11 @@ g_file_load_contents_finish (GFile *file, * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old entity tag - * for the document, or %NULL + * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document, + * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new entity tag + * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when no longer * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7298,7 +7277,7 @@ replace_contents_open_callback (GObject *obj, * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7348,7 +7327,7 @@ g_file_replace_contents_async (GFile *file, * g_file_replace_contents_bytes_async: * @file: input #GFile * @contents: a #GBytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -7402,7 +7381,7 @@ g_file_replace_contents_bytes_async (GFile *file, * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new entity tag + * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when it is no * longer needed, or %NULL * @error: a #GError, or %NULL @@ -7656,8 +7635,7 @@ g_file_measure_disk_usage (GFile *file, * g_file_measure_disk_usage_async: * @file: a #GFile * @flags: #GFileMeasureFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable * @progress_callback: (allow-none): a #GFileMeasureProgressCallback * @progress_data: user_data for @progress_callback @@ -7986,11 +7964,10 @@ g_file_poll_mountable_finish (GFile *file, * g_file_supports_thread_contexts: * @file: a #GFile * - * Checks if @file supports thread-default - * contexts. If this returns %FALSE, you cannot perform - * asynchronous operations on @file in a thread that has a - * thread-default context. + * Checks if @file supports + * [thread-default contexts][g-main-context-push-thread-default-context]. + * If this returns %FALSE, you cannot perform asynchronous operations on + * @file in a thread that has a thread-default context. * * Returns: Whether or not @file supports thread-default contexts. *