From 41d1650c9b6b0b8368c0648d2885b83e18020303 Mon Sep 17 00:00:00 2001 From: Alexander Larsson Date: Wed, 12 Dec 2007 12:19:02 +0000 Subject: [PATCH] Fix up a bunch of details in the docs. 2007-12-12 Alexander Larsson * gappinfo.[ch]: * gasyncresult.c: * gbufferedinputstream.c: * gbufferedoutputstream.c: * gcancellable.c: * gcontenttype.c: * gdatainputstream.[ch]: * gdesktopappinfo.c: * gdirectorymonitor.c: * gfile.[ch]: * gfileattribute.[ch]: * gfileicon.[ch]: * gfileinfo.h: * gfileinputstream.h: * gfilemonitor.[ch]: * gfileoutputstream.[ch]: * gfilterinputstream.h: * gfilteroutputstream.h: * gicon.h: * gioscheduler.c: * gloadableicon.[ch]: * gmemoryinputstream.c: * gmountoperation.c: * gthemedicon.c: Fix up a bunch of details in the docs. * glocalfileinfo.c: CR/LF -> LF fixups svn path=/trunk/; revision=6100 --- gio/ChangeLog | 31 +++ gio/gappinfo.c | 78 +++--- gio/gappinfo.h | 31 +-- gio/gasyncresult.c | 13 +- gio/gbufferedinputstream.c | 4 +- gio/gbufferedoutputstream.c | 3 + gio/gcancellable.c | 40 ++- gio/gcontenttype.c | 14 +- gio/gdatainputstream.c | 27 +- gio/gdatainputstream.h | 2 +- gio/gdesktopappinfo.c | 20 +- gio/gdirectorymonitor.c | 13 +- gio/gfile.c | 666 ++++++++++++++++++++++++-------------------- gio/gfile.h | 5 +- gio/gfileattribute.c | 19 +- gio/gfileattribute.h | 10 +- gio/gfileicon.c | 5 +- gio/gfileicon.h | 2 +- gio/gfileinfo.h | 49 +++- gio/gfileinputstream.h | 6 +- gio/gfilemonitor.c | 4 +- gio/gfilemonitor.h | 18 +- gio/gfileoutputstream.c | 4 +- gio/gfileoutputstream.h | 6 +- gio/gfilterinputstream.h | 2 +- gio/gfilteroutputstream.h | 2 +- gio/gicon.h | 4 +- gio/gioscheduler.c | 6 +- gio/gloadableicon.c | 2 +- gio/gloadableicon.h | 4 +- gio/glocalfileinfo.c | 124 ++++----- gio/gmemoryinputstream.c | 3 +- gio/gmountoperation.c | 7 +- gio/gthemedicon.c | 3 + 34 files changed, 690 insertions(+), 537 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index f195252..09971c9 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,34 @@ +2007-12-12 Alexander Larsson + + * gappinfo.[ch]: + * gasyncresult.c: + * gbufferedinputstream.c: + * gbufferedoutputstream.c: + * gcancellable.c: + * gcontenttype.c: + * gdatainputstream.[ch]: + * gdesktopappinfo.c: + * gdirectorymonitor.c: + * gfile.[ch]: + * gfileattribute.[ch]: + * gfileicon.[ch]: + * gfileinfo.h: + * gfileinputstream.h: + * gfilemonitor.[ch]: + * gfileoutputstream.[ch]: + * gfilterinputstream.h: + * gfilteroutputstream.h: + * gicon.h: + * gioscheduler.c: + * gloadableicon.[ch]: + * gmemoryinputstream.c: + * gmountoperation.c: + * gthemedicon.c: + Fix up a bunch of details in the docs. + + * glocalfileinfo.c: + CR/LF -> LF fixups + 2007-12-11 David Zeuthen Rework how volumes, drives and volume monitoring is diff --git a/gio/gappinfo.c b/gio/gappinfo.c index 6b02a77..53e218d 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -33,7 +33,7 @@ * @stability: Unstable * * #GAppInfo and #GAppLaunchContext are used for describing and launching - * installed system applications. + * applications installed on the system. * **/ @@ -134,7 +134,10 @@ g_app_info_equal (GAppInfo *appinfo1, * g_app_info_get_id: * @appinfo: a #GAppInfo. * - * Gets the ID of an application. + * Gets the ID of an application. An id is a string that + * identifies the application. The exact format of the id is + * platform dependent. For instance on Unix this is the + * desktop file id from the xdg menu specification. * * Returns: a string containing the application's ID. **/ @@ -177,7 +180,7 @@ g_app_info_get_name (GAppInfo *appinfo) * Gets a human-readable description of an installed application. * * Returns: a string containing a description of the - * application @appinfo. The returned string should be not freed + * application @appinfo, or %NULL if none. The returned string should be not freed * when no longer needed. **/ const char * @@ -220,11 +223,9 @@ g_app_info_get_executable (GAppInfo *appinfo) * @content_type: the content type. * @error: a #GError. * - * Sets an application as the default handler for a given type. + * Sets the application as the default handler for a given type. * - * Returns: %TRUE if the given @appinfo is the default - * for the given @content_type. %FALSE if not, - * or in case of an error. + * Returns: %TRUE on success, %FALSE on error. **/ gboolean g_app_info_set_as_default_for_type (GAppInfo *appinfo, @@ -245,14 +246,12 @@ g_app_info_set_as_default_for_type (GAppInfo *appinfo, /** * g_app_info_set_as_default_for_extension: * @appinfo: a #GAppInfo. - * @extension: a string containing the file extension. + * @extension: a string containing the file extension (without the dot). * @error: a #GError. * - * Sets an application as the default handler for the given file extention. + * Sets the application as the default handler for the given file extention. * - * Returns: %TRUE if the given @appinfo is the default - * for the given @extension. %FALSE if not, - * or in case of an error. + * Returns: %TRUE on success, %FALSE on error. **/ gboolean g_app_info_set_as_default_for_extension (GAppInfo *appinfo, @@ -283,8 +282,7 @@ g_app_info_set_as_default_for_extension (GAppInfo *appinfo, * Adds a content type to the application information to indicate the * application is capable of opening files with the given content type. * - * Returns: %TRUE if @appinfo supports @content_type. - * %FALSE if not, or in case of an error. + * Returns: %TRUE on success, %FALSE on error. **/ gboolean g_app_info_add_supports_type (GAppInfo *appinfo, @@ -342,8 +340,7 @@ g_app_info_can_remove_supports_type (GAppInfo *appinfo) * * Removes a supported type from an application, if possible. * - * Returns: %TRUE if @content_type support was removed - * from @appinfo. %FALSE if not. + * Returns: %TRUE on success, %FALSE on error. **/ gboolean g_app_info_remove_supports_type (GAppInfo *appinfo, @@ -372,7 +369,7 @@ g_app_info_remove_supports_type (GAppInfo *appinfo, * g_app_info_get_icon: * @appinfo: a #GAppInfo. * - * Gets the default icon for the application. + * Gets the icon for the application. * * Returns: the default #GIcon for @appinfo. **/ @@ -397,10 +394,17 @@ g_app_info_get_icon (GAppInfo *appinfo) * @error: a #GError. * * Launches the application. Passes @files to the launched application - * as arguments, and loads the @launch_context for managing the application - * once it has been launched. On error, @error will be set accordingly. + * as arguments, using the optional @launch_context to get information + * about the details of the launcher (like what screen its is on). + * On error, @error will be set accordingly. * - * Returns: %TRUE on successful launch, %FALSE otherwise. + * To lauch the application without arguments pass a %NULL @files list. + * + * Note that even if the launch is successful the application launched + * can fail to start if it runs into problems during startup. There is + * no way to detect this. + * + * Returns: %TRUE on successful launch, %FALSE otherwise. **/ gboolean g_app_info_launch (GAppInfo *appinfo, @@ -447,10 +451,17 @@ g_app_info_supports_uris (GAppInfo *appinfo) * @error: a #GError. * * Launches the application. Passes @uris to the launched application - * as arguments, and loads the @launch_context for managing the application - * once it has been launched. On error, @error will be set accordingly. + * as arguments, using the optional @launch_context to get information + * about the details of the launcher (like what screen its is on). + * On error, @error will be set accordingly. + * + * To lauch the application without arguments pass a %NULL @uris list. * - * Returns: %TRUE if the @appinfo was launched successfully, %FALSE otherwise. + * Note that even if the launch is successful the application launched + * can fail to start if it runs into problems during startup. There is + * no way to detect this. + * + * Returns: %TRUE on successful launch, %FALSE otherwise. **/ gboolean g_app_info_launch_uris (GAppInfo *appinfo, @@ -471,10 +482,14 @@ g_app_info_launch_uris (GAppInfo *appinfo, /** * g_app_info_should_show: * @appinfo: a #GAppInfo. - * @desktop_env: a string. + * @desktop_env: A string specifying what desktop this is, or %NULL. * * Checks if the application info should be shown when listing * applications available. + * + * @destkop_env is used to hide applications that are specified to + * just show up in specific desktops. For instance, passing in "GNOME" + * would show all applications specific to the Gnome desktop. * * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. **/ @@ -496,7 +511,8 @@ G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT); /** * g_app_launch_context_new: * - * Creates a new application launch context. + * Creates a new application launch context. This is not normally used, + * instead you instantiate a subclass of this, such as GdkLaunchContext. * * Returns: a #GAppLaunchContext. **/ @@ -546,14 +562,15 @@ g_app_launch_context_get_display (GAppLaunchContext *context, return class->get_display (context, info, files); } -/* should this be moved to the g_desktop_app_ implementation? */ /** * g_app_launch_context_get_startup_notify_id: * @context: a #GAppLaunchContext. * @info: a #GAppInfo. * @files: a #GList of files. * - * Gets the DESKTOP_STARTUP_ID for the launched application, if supported. + * Initiates startup notification for the applicaiont and returns the + * DESKTOP_STARTUP_ID for the launched operation, if supported. + * * Startup notification IDs are defined in the FreeDesktop.Org Startup * Notifications standard, at * . @@ -583,11 +600,10 @@ g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context, /** * g_app_launch_context_launch_failed: * @context: a #GAppLaunchContext. - * @startup_notify_id: a string containing the DESKTOP_STARTUP_ID - * of the launched application. + * @startup_notify_id: the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). * - * Called when an application has failed to launch, and cancels the - * application startup notification. + * Called when an application has failed to launch, so that it can cancel + * the application startup notification started in g_app_launch_context_get_startup_notify_id(). * **/ void diff --git a/gio/gappinfo.h b/gio/gappinfo.h index 758a378..e7dfd3c 100644 --- a/gio/gappinfo.h +++ b/gio/gappinfo.h @@ -43,7 +43,7 @@ G_BEGIN_DECLS /** * GAppInfoCreateFlags: * @G_APP_INFO_CREATE_FLAGS_NONE: No flags. - * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens with a terminal window. + * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens in a terminal window. * * Flags used when creating a #GAppInfo. */ @@ -59,7 +59,8 @@ typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate; /** * GAppInfo: * - * Information about an installed application. + * Information about an installed application and methods to launch + * it (with file arguments). */ typedef struct _GAppInfo GAppInfo; /* Dummy typedef */ @@ -77,7 +78,6 @@ typedef struct _GAppInfo GAppInfo; /* Dummy typedef */ * @supports_uris: Indicates whether the application specified supports launching URIs. * @launch_uris: Launches an application with a list of URIs. * @should_show: Returns whether an application should be shown (e.g. when getting a list of installed applications). - * @supports_xdg_startup_notify: Indicates whether the application supports the * * FreeDesktop.Org Startup Notification Specification. * @set_as_default_for_type: Sets an application as default for a given content type. @@ -115,8 +115,6 @@ struct _GAppInfoIface GError **error); gboolean (*should_show) (GAppInfo *appinfo, const char *desktop_env); - gboolean (*supports_xdg_startup_notify) (GAppInfo *appinfo); - /* For changing associations */ gboolean (*set_as_default_for_type) (GAppInfo *appinfo, @@ -132,18 +130,6 @@ struct _GAppInfoIface gboolean (*remove_supports_type) (GAppInfo *appinfo, const char *content_type, GError **error); - /*< private >*/ - /* Padding for future expansion */ - void (*_g_reserved1) (void); - void (*_g_reserved2) (void); - void (*_g_reserved3) (void); - void (*_g_reserved4) (void); - void (*_g_reserved5) (void); - void (*_g_reserved6) (void); - void (*_g_reserved7) (void); - void (*_g_reserved8) (void); - void (*_g_reserved9) (void); - void (*_g_reserved10) (void); }; GType g_app_info_get_type (void) G_GNUC_CONST; @@ -193,18 +179,13 @@ GAppInfo *g_app_info_get_default_for_type (const char *content_type, gboolean must_support_uris); GAppInfo *g_app_info_get_default_for_uri_scheme (const char *uri_scheme); -/* TODO: missing operations: - add app as supporting a content type, but don't make it default - implement set_as_default_for_extension - - can_remove, remove (as in, don't support a specific mimetype) -*/ - /** * GAppLaunchContext: * @parent_instance: The parent instance. * - * Gets feedback from the system when launching an application. + * Integrating the launch with the launching application. This is used to + * handle for instance startup notification and launching the new application + * on the same screen as the launching window. */ struct _GAppLaunchContext { diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c index a8950c9..60c829c 100644 --- a/gio/gasyncresult.c +++ b/gio/gasyncresult.c @@ -52,7 +52,8 @@ * of the operation is not needed, there is no need to call the * "_finish()" function, GIO will take care of cleaning up the * result and error information after the #GAsyncReadyCallback - * returns. + * returns. It is also allowed to take a reference to the #GAsyncResult and + * call "_finish()" later. * * Example of a typical asynchronous operation flow: * |[ @@ -96,9 +97,15 @@ * /* ... */ * } * ]| + * + * The callback for an asynchronous operation is called only once, and is + * always called, even in the case of a cancelled operation. On cancellation + * the result is a %G_IO_ERROR_CANCELLED error. * - * Asynchronous jobs are threaded if #GThread is available, but also may - * be sent to the Main Event Loop and processed in an idle function. + * Some ascynchronous operations are implemented using synchronous call. These + * are run in a separate #GThread has been initialized, but otherwise they + * are sent to the Main Event Loop and processed in an idle function. So, if you + * truly need asynchronous operations, make sure to initialize #GThread. **/ static void g_async_result_base_init (gpointer g_class); diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c index b9f7963..999b488 100644 --- a/gio/gbufferedinputstream.c +++ b/gio/gbufferedinputstream.c @@ -177,12 +177,12 @@ g_buffered_input_stream_class_init (GBufferedInputStreamClass *klass) * * Gets the size of the input buffer. * - * Returns: the current buffer size, or %-1 on error. + * Returns: the current buffer size. **/ gsize g_buffered_input_stream_get_buffer_size (GBufferedInputStream *stream) { - g_return_val_if_fail (G_IS_BUFFERED_INPUT_STREAM (stream), -1); + g_return_val_if_fail (G_IS_BUFFERED_INPUT_STREAM (stream), 0); return stream->priv->len; } diff --git a/gio/gbufferedoutputstream.c b/gio/gbufferedoutputstream.c index aa94f36..06ad691 100644 --- a/gio/gbufferedoutputstream.c +++ b/gio/gbufferedoutputstream.c @@ -248,6 +248,9 @@ g_buffered_output_stream_get_auto_grow (GBufferedOutputStream *stream) * @auto_grow: a #gboolean. * * Sets whether or not the @stream's buffer should automatically grow. + * If @auto_grow is true, then each write will just make the buffer + * larger, and you must manually flush the buffer to actually write out + * the data to the underlying stream. **/ void g_buffered_output_stream_set_auto_grow (GBufferedOutputStream *stream, diff --git a/gio/gcancellable.c b/gio/gcancellable.c index 3cf20fc..5ae3207 100644 --- a/gio/gcancellable.c +++ b/gio/gcancellable.c @@ -43,7 +43,8 @@ * @include: gio/gcancellable.h * * GCancellable is a thread-safe operation cancellation stack used - * throughout GIO to allow for cancellation of asynchronous operations. + * throughout GIO to allow for cancellation of synchronous and + * asynchronous operations. */ enum { @@ -94,6 +95,10 @@ g_cancellable_class_init (GCancellableClass *klass) * @cancellable: a #GCancellable. * * Emitted when the operation has been cancelled from another thread. + * + * Can be used by implementations of cancellable operations. This will + * be emitted in the thread that tried to cancel the operation, not the + * thread the is running the operation. */ signals[CANCELLED] = g_signal_new (I_("cancelled"), @@ -149,6 +154,13 @@ g_cancellable_init (GCancellable *cancellable) * g_cancellable_new: * * Creates a new #GCancellable object. + * + * Applications that want to start one or more operations + * that should be cancellable should create a #GCancellable + * and pass it to the operations. + * + * One #GCancellable can be used in multiple consecutive + * operations, but not in multiple concurrent operations. * * Returns: a #GCancellable. **/ @@ -162,7 +174,14 @@ g_cancellable_new (void) * g_push_current_cancellable: * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Pushes @cancellable onto the cancellable stack. + * Pushes @cancellable onto the cancellable stack. The current + * cancllable can then be recieved using g_cancellable_get_current(). + * + * This is useful when implementing cancellable operations in + * code that does not allow you to pass down the cancellable object. + * + * This is typically called automatically by e.g. #GFile operations, + * so you rarely have to call this yourself. **/ void g_push_current_cancellable (GCancellable *cancellable) @@ -180,8 +199,8 @@ g_push_current_cancellable (GCancellable *cancellable) * g_pop_current_cancellable: * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Pops @cancellable off the cancellable stack if @cancellable - * is on the top of the stack. + * Pops @cancellable off the cancellable stack (verifying that @cancellable + * is on the top of the stack). **/ void g_pop_current_cancellable (GCancellable *cancellable) @@ -260,7 +279,8 @@ g_cancellable_is_cancelled (GCancellable *cancellable) * @cancellable: a #GCancellable object. * @error: #GError to append error state to. * - * Sets the current error to notify that the operation was cancelled. + * If the @cancelalble is cancelled, sets the error to notify + * that the operation was cancelled. * * Returns: %TRUE if @cancellable was cancelled, %FALSE if it was not. **/ @@ -284,7 +304,9 @@ g_cancellable_set_error_if_cancelled (GCancellable *cancellable, * g_cancellable_get_fd: * @cancellable: a #GCancellable. * - * Gets the file descriptor for a cancellable job. + * Gets the file descriptor for a cancellable job. This can be used to + * implement cancellable operations on Unix systems. The returned fd will + * turn readable when @cancellable is cancelled. * * Returns: A valid file descriptor. %-1 if the file descriptor * is not supported, or on errors. @@ -314,7 +336,11 @@ g_cancellable_get_fd (GCancellable *cancellable) * @cancellable: a #GCancellable object. * * Will set @cancellable to cancelled, and will emit the CANCELLED - * signal. This function is thread-safe. + * signal. + * + * This function is thread-safe. In other words, you can safely call it from + * another thread than the one running an operation that was passed + * the @cancellable. **/ void g_cancellable_cancel (GCancellable *cancellable) diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c index a53b566..1ef9d00 100644 --- a/gio/gcontenttype.c +++ b/gio/gcontenttype.c @@ -399,9 +399,11 @@ g_content_type_is_a (const char *type, * g_content_type_is_unknown: * @type: a content type string. * - * Checks if the content type is known by GIO. + * Checks if the content type is the generic "unknown" type. + * On unix this is the "application/octet-stream" mimetype, + * while on win32 it is "*". * - * Returns: %TRUE if the type is unknown. + * Returns: %TRUE if the type is the unknown type. **/ gboolean g_content_type_is_unknown (const char *type) @@ -610,9 +612,9 @@ g_content_type_get_description (const char *type) * g_content_type_get_mime_type: * @type: a content type string. * - * Gets the mime-type for the content type. + * Gets the mime-type for the content type. If one is registered * - * Returns: the registered mime-type for the given @type. + * Returns: the registered mime-type for the given @type, or NULL if unknown. **/ char * g_content_type_get_mime_type (const char *type) @@ -847,8 +849,8 @@ enumerate_mimetypes_dir (const char *dir, /** * g_content_types_get_registered: * - * Gets a list of strings containing the registered content types on - * the system. + * Gets a list of strings containing all the registered content types + * known to the system. * * Returns: #GList of the registered content types. **/ diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c index e377b04..aa90272 100644 --- a/gio/gdatainputstream.c +++ b/gio/gdatainputstream.c @@ -34,7 +34,7 @@ * @see_also: #GInputStream * * Data input stream implements #GInputStream and includes functions for - * reading data directly from an input stream. + * reading structured data directly from a binary input stream. * **/ @@ -246,8 +246,9 @@ g_data_input_stream_get_byte_order (GDataInputStream *stream) * * Sets the newline type for the @stream. * - * TODO: is it valid to set this to G_DATA_STREAM_NEWLINE_TYPE_ANY, or - * should it always be set to {_LF, _CR, _CR_LF} + * Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read + * chunk ends in "CR" we must read an additional byte to know if this is "CR" or + * "CR LF", and this might block if there is no more data availible. * **/ void @@ -331,8 +332,8 @@ read_data (GDataInputStream *stream, **/ guchar g_data_input_stream_read_byte (GDataInputStream *stream, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { guchar c; @@ -405,8 +406,8 @@ g_data_input_stream_read_int16 (GDataInputStream *stream, **/ guint16 g_data_input_stream_read_uint16 (GDataInputStream *stream, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { guint16 v; @@ -453,8 +454,8 @@ g_data_input_stream_read_uint16 (GDataInputStream *stream, **/ gint32 g_data_input_stream_read_int32 (GDataInputStream *stream, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { gint32 v; @@ -501,8 +502,8 @@ g_data_input_stream_read_int32 (GDataInputStream *stream, **/ guint32 g_data_input_stream_read_uint32 (GDataInputStream *stream, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { guint32 v; @@ -736,8 +737,8 @@ scan_for_newline (GDataInputStream *stream, * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a string with the line that was read in. Set @length to - * a #gsize to get the length of the read line. Returns %NULL on an error. + * Returns: a string with the line that was read in (including the newlines). + * Set @length to a #gsize to get the length of the read line. Returns %NULL on an error. **/ char * g_data_input_stream_read_line (GDataInputStream *stream, diff --git a/gio/gdatainputstream.h b/gio/gdatainputstream.h index 6501f4c..3e04e29 100644 --- a/gio/gdatainputstream.h +++ b/gio/gdatainputstream.h @@ -87,7 +87,7 @@ typedef enum { * @G_DATA_STREAM_NEWLINE_TYPE_LF: Selects "LF" line endings, common on most modern UNIX platforms. * @G_DATA_STREAM_NEWLINE_TYPE_CR: Selects "CR" line endings. * @G_DATA_STREAM_NEWLINE_TYPE_CR_LF: Selects "CR, LF" line ending, common on Microsoft Windows. - * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Selects any line ending type. + * @G_DATA_STREAM_NEWLINE_TYPE_ANY: Automatically try to handle any line ending type. * * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. **/ diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 79ec4d2..8fc3a86 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -252,9 +252,9 @@ g_desktop_app_info_new_from_filename (const char *filename) /** * g_desktop_app_info_new: - * @desktop_id: + * @desktop_id: the desktop file id * - * Returns: a new #GDesktopAppInfo. + * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id **/ GDesktopAppInfo * g_desktop_app_info_new (const char *desktop_id) @@ -375,8 +375,11 @@ g_desktop_app_info_get_name (GAppInfo *appinfo) /** * g_desktop_app_info_get_is_hidden: - * @info: - * + * @info: a #GDesktopAppInfo. + * + * A desktop file is hidden if the Hidden key in it is + * set to True. + * * Returns: %TRUE if hidden, %FALSE otherwise. **/ gboolean @@ -910,14 +913,6 @@ g_desktop_app_info_supports_uris (GAppInfo *appinfo) } static gboolean -g_desktop_app_info_supports_xdg_startup_notify (GAppInfo *appinfo) -{ - GDesktopAppInfo *info = G_DESKTOP_APP_INFO (appinfo); - - return info->startup_notify; -} - -static gboolean g_desktop_app_info_launch_uris (GAppInfo *appinfo, GList *uris, GAppLaunchContext *launch_context, @@ -1462,7 +1457,6 @@ g_desktop_app_info_iface_init (GAppInfoIface *iface) iface->get_icon = g_desktop_app_info_get_icon; iface->launch = g_desktop_app_info_launch; iface->supports_uris = g_desktop_app_info_supports_uris; - iface->supports_xdg_startup_notify = g_desktop_app_info_supports_xdg_startup_notify; iface->launch_uris = g_desktop_app_info_launch_uris; iface->should_show = g_desktop_app_info_should_show; iface->set_as_default_for_type = g_desktop_app_info_set_as_default_for_type; diff --git a/gio/gdirectorymonitor.c b/gio/gdirectorymonitor.c index 00c5bdf..018b8bb 100644 --- a/gio/gdirectorymonitor.c +++ b/gio/gdirectorymonitor.c @@ -36,7 +36,7 @@ * @short_description: Directory Monitor * @see_also: #GFileMonitor * - * Monitors a directory for changes. + * Monitors a directory for changes to files in it. * **/ @@ -236,7 +236,10 @@ g_directory_monitor_init (GDirectoryMonitor *monitor) * g_directory_monitor_cancel: * @monitor: a #GDirectoryMonitor. * - * Cancels the monitoring activity on @monitor. + * Cancels the monitoring activity on @monitor. Note that + * the monitor is automatically cancelled when finalized. + * + * It is safe to call this multiple times. * * Returns: %TRUE if the monitor was cancelled successfully. %FALSE otherwise. **/ @@ -260,11 +263,9 @@ g_directory_monitor_cancel (GDirectoryMonitor *monitor) /** * g_directory_monitor_set_rate_limit: * @monitor: a #GDirectoryMonitor. - * @limit_msecs: an integer to set the limit of the directory monitor - * in milliseconds. + * @limit_msecs: the change rate limit of the directory monitor in milliseconds. * - * Sets the limit of the directory monitor to watch for changes every - * @limit_msecs milliseconds. + * Report same consecutive changes of the same type at most once each @limit_msecs milliseconds. **/ void g_directory_monitor_set_rate_limit (GDirectoryMonitor *monitor, diff --git a/gio/gfile.c b/gio/gfile.c index 0cbd91f..e1f3eef 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -238,8 +238,16 @@ g_file_base_init (gpointer g_class) * * Checks to see if a file is native to the platform. * - * Returns: %TRUE if file is native. (If the #GFile's expressed in - * the platform-native filename format, e.g. "C:\Windows", "/usr/bin/"). + * 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. + * + * On some systems non-native files may be availible using + * the native filesystem via a userspace filesystem (FUSE), in + * these cases this call will return %FALSE, but g_file_get_path() + * will still return a native path. + * + * Returns: %TRUE if file is native. **/ gboolean g_file_is_native (GFile *file) @@ -289,7 +297,7 @@ g_file_has_uri_scheme (GFile *file, * * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] * - * Common schemes include "file", "http", "svn", etc. + * Common schemes include "file", "http", "ftp", etc. * * Returns: a string containing the URI scheme for the given * #GFile. The returned string should be freed with g_free() @@ -312,7 +320,11 @@ g_file_get_uri_scheme (GFile *file) * g_file_get_basename: * @file: input #GFile. * - * Gets the basename for a given #GFile. + * Gets the basename (the last component of the path) for a given #GFile. + * + * If called for the toplevel 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). * * Returns: string containing the #GFile's base name, or %NULL * if given #GFile is invalid. The returned string should be @@ -334,10 +346,10 @@ g_file_get_basename (GFile *file) * g_file_get_path: * @file: input #GFile. * - * Gets the current path within a #GFile. + * Gets the local pathname for #GFile, if one exists. * * Returns: string containing the #GFile's path, or %NULL if - * given #GFile is invalid. The returned string should be + * no such path exists. The returned string should be * freed with g_free() when no longer needed. **/ char * @@ -356,11 +368,10 @@ g_file_get_path (GFile *file) * g_file_get_uri: * @file: input #GFile. * - * Gets a URI for the path within a #GFile. + * Gets the URI for the @file. * - * Returns: a string containing the #GFile's URI or %NULL - * if given #GFile is invalid. The returned string should - * be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's URI. + * The returned string should be freed with g_free() when no longer needed. **/ char * g_file_get_uri (GFile *file) @@ -378,10 +389,19 @@ g_file_get_uri (GFile *file) * g_file_get_parse_name: * @file: input #GFile. * - * Gets the UTF-8 parsed name for the #GFile. + * 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 #GFile back using + * g_file_parse_name(). + * + * This is generally used to show the #GFile as a nice + * string in a user interface, like in a location entry. * - * Returns: a string containing the #GFile's parsed name, - * or %NULL if given #GFile is invalid. The returned + * 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). + * + * Returns: a string containing the #GFile's parse name. The returned * string should be freed with g_free() when no longer needed. **/ char * @@ -404,8 +424,7 @@ g_file_get_parse_name (GFile *file) * the actual file or directory represented by the #GFile; see * g_file_copy() if attempting to copy a file. * - * Returns: #GFile that is a duplicate of the given #GFile, - * or %NULL if given #GFile is invalid. + * Returns: #GFile that is a duplicate of the given #GFile. **/ GFile * g_file_dup (GFile *file) @@ -479,7 +498,7 @@ g_file_equal (GFile *file1, * file system, then %NULL will be returned. * * Returns: a #GFile structure to the parent of the given - * #GFile or %NULL. + * #GFile or %NULL if there is no parent. **/ GFile * g_file_get_parent (GFile *file) @@ -498,12 +517,13 @@ g_file_get_parent (GFile *file) * @file: input #GFile. * @name: string containing the child's name. * - * Gets a specific child of @file with name equal to @name if - * it exists. + * Gets a specific child of @file with name equal to @name. + * + * Note that the file with that specific name might not exist, but + * you can still have a #GFile that points to it. You can use this + * for instance to create that file. * - * Returns: a #GFile to a child specified by - * @name or %NULL if @name is %NULL, or the specified - * child doesn't exist. + * Returns: a #GFile to a child specified by @name. **/ GFile * g_file_get_child (GFile *file, @@ -521,12 +541,12 @@ g_file_get_child (GFile *file, * @display_name: string to a possible child. * @error: #GError. * - * Gets the child of @file for a given @display_name. If - * this function fails, it returns %NULL and @error will be - * set with %G_IO_ERROR_INVALID_FILENAME. + * 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. * * Returns: a #GFile to the specified child, or - * %NULL if @display_name is %NULL. + * %NULL if the display name couldn't be converted. **/ GFile * g_file_get_child_for_display_name (GFile *file, @@ -548,9 +568,9 @@ g_file_get_child_for_display_name (GFile *file, * @parent: input #GFile. * @descendant: input #GFile. * - * Checks whether @parent contains the specified @descendent. + * Checks whether @parent (recursively) contains the specified @descendent. * - * Returns: %TRUE if the @descendent's parent is @parent. %FALSE otherwise. + * Returns: %TRUE if the @descendent's parent, grandparent, etc is @parent. %FALSE otherwise. **/ gboolean g_file_contains_file (GFile *parent, @@ -577,7 +597,7 @@ g_file_contains_file (GFile *parent, * Gets the path for @descendant relative to @parent. * * Returns: string with the relative path from @descendant - * to @parent. The returned string should be freed with + * to @parent, or %NULL if @descendant is not a descendant of @parent. The returned string should be freed with * g_free() when no longer needed. **/ char * @@ -624,26 +644,32 @@ g_file_resolve_relative_path (GFile *file, /** * g_file_enumerate_children: * @file: input #GFile. - * @attributes: a string containing a #GFileAttributeInfo query. + * @attributes: an attribute query string. * @flags: a set of #GFileQueryInfoFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: #GError for error reporting. * - * Gets a #GFileEnumerator for the children of @file. The returned enumerator will - * automatically generate a #GFileAttributeMatcher internally that match @attributes, - * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", - * "std:*"). See g_file_enumerator_next_file() for details. - * + * Gets the requested information about the files in a directory. The result + * is a #GFileEnumerator object that will give out #GFileInfo objects for + * all the files in the directory. + * + * The @attribute value is a string that specifies the file attributes that + * should be gathered. It is not an error if its 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 "std:*" means all attributes in the std + * namespace. An example attribute query be "std:*,owner:user". + * The standard attributes are availible as defines, like #G_FILE_ATTRIBUTE_STD_NAME. + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If the #GFileIface for the given @file does not support #GFileEnumerator, - * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will - * be set in @error. * - * Returns: A #GFileEnumerator if successful. %NULL if cancelled or if #GFile's - * backend doesn't support #GFileEnumerator. + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned. + * Other errors are possible too. + * + * Returns: A #GFileEnumerator if successful, %NULL on error. **/ GFileEnumerator * g_file_enumerate_children (GFile *file, @@ -677,7 +703,7 @@ g_file_enumerate_children (GFile *file, /** * g_file_enumerate_children_async: * @file: input #GFile. - * @attributes: a string containing a #GFileAttributeInfo query. + * @attributes: an attribute query string. * @flags: a set of #GFileQueryInfoFlags. * @io_priority: the I/O priority * of the request. @@ -685,13 +711,15 @@ g_file_enumerate_children (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Asynchronously gets a #GFileEnumerator for the children of @file. The returned - * file enumerator will automatically generate a #GFileAttributeMatcher - * that matches @attributes, where attributes is a #GFileAttributeInfo query - * string (e.g. "std:type", "std:*"). See g_file_enumerator_next_file() for details. - * For the synchronous version of this function, see g_file_enumerate_children(). - * - * To finish this asynchronous operation, see g_file_enumerate_children_finish(). + * Asynchronously gets the requested information about the files in a directory. The result + * is a #GFileEnumerator object that will give out #GFileInfo objects for + * all the files in the directory. + * + * For more details, see g_file_enumerate_children() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_enumerate_children_finish() to get the result of the operation. **/ void g_file_enumerate_children_async (GFile *file, @@ -723,17 +751,8 @@ g_file_enumerate_children_async (GFile *file, * @error: a #GError. * * Finishes an async enumerate children operation. + * See g_file_enumerate_children_async(). * - * If @cancellable was not %NULL when g_file_enumerate_children_async() - * was called, then the operation could have been cancelled by triggering - * the cancellable object from another thread. If the operation was cancelled, - * the @error will be set to %G_IO_ERROR_CANCELLED and this function will - * return %NULL. - * - * If the #GFileIface for the given @file does not support enumerating files, - * then %NULL will be returned and the error %G_IO_ERROR_NOT_SUPPORTED will - * be set in @error. - * * Returns: a #GFileEnumerator or %NULL if an error occurred. **/ GFileEnumerator * @@ -761,19 +780,37 @@ g_file_enumerate_children_finish (GFile *file, /** * g_file_query_info: * @file: input #GFile. - * @attributes: a string containing a #GFileAttributeInfo query. + * @attributes: an attribute query string. * @flags: a set of #GFileQueryInfoFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. + * + * Gets the requested information about specified @file. The result + * is a #GFileInfo objects that contains key-value attributes (like type or size + * for the file. + * + * The @attribute value is a string that specifies the file attributes that + * should be gathered. It is not an error if its 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 "std:*" means all attributes in the std + * namespace. An example attribute query be "std:*,owner:user". + * The standard attributes are availible as defines, like #G_FILE_ATTRIBUTE_STD_NAME. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If the #GFileIface for the given @file does not support querying file - * information, then %NULL will be returned and the error - * %G_IO_ERROR_NOT_SUPPORTED will be set in @error. - * + * + * For symlinks, normally the information about the target of the + * symlink is returned, rather than information about the symlink itself. + * However if you pass #G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in @flags the + * information about the symlink itself will be returned. Also, for symlinks + * that points to non-existing files the information about the symlink itself + * will be returned. + * + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * * Returns: a #GFileInfo for the given @file, or %NULL on error. **/ GFileInfo * @@ -806,7 +843,7 @@ g_file_query_info (GFile *file, /** * g_file_query_info_async: * @file: input #GFile. - * @attributes: a string containing a #GFileAttributeInfo query. + * @attributes: an attribute query string. * @flags: a set of #GFileQueryInfoFlags. * @io_priority: the I/O priority * of the request. @@ -814,11 +851,15 @@ g_file_query_info (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * Asynchronously gets the requested information about specified @file. The result + * is a #GFileInfo objects that contains key-value attributes (like type or size + * for the file. * - * To finish this asynchronous operation, see g_file_query_info_finish(). + * For more details, see g_file_query_info() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_enumerate_children_finish() to get the result of the operation. **/ void g_file_query_info_async (GFile *file, @@ -850,15 +891,7 @@ g_file_query_info_async (GFile *file, * @error: a #GError. * * Finishes an asynchronous file info query. - * - * If @cancellable was not %NULL when g_file_query_info_async() was called, - * then the operation could have been cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the @error will - * be set to %G_IO_ERROR_CANCELLED and this function will return %NULL. - * - * If the #GFileIface for the given @file does not support querying file - * information, then %NULL will be returned and the error - * %G_IO_ERROR_NOT_SUPPORTED will be set in @error. + * See g_file_query_info_async(). * * Returns: #GFileInfo for given @file or %NULL on error. **/ @@ -886,20 +919,32 @@ g_file_query_info_finish (GFile *file, /** * g_file_query_filesystem_info: * @file: input #GFile. - * @attributes: a string containing a #GFileAttributeInfo query. + * @attributes: an attribute query string. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Obtains attributes of a #GFile. + * Similar to g_file_query_info(), but obtains information + * about the filesystem the @file is on, rather than the file itself. + * For instance the amount of space availible and the type of + * the filesystem. * + * The @attribute value is a string that specifies the file attributes that + * should be gathered. It is not an error if its 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 #G_FILE_ATTRIBUTE_FS_SIZE + * (the total size of the filesystem in bytes), #G_FILE_ATTRIBUTE_FS_FREE (number of + * bytes availible), and #G_FILE_ATTRIBUTE_FS_TYPE (type of the filesystem). + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * - * If the #GFileIface for the given @file does not support querying file system - * information, then %NULL will be returned and the error - * %G_IO_ERROR_NOT_SUPPORTED will be set in @error. - * + * + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * * Returns: a #GFileInfo or %NULL if there was an error. **/ GFileInfo * @@ -948,8 +993,8 @@ g_file_query_filesystem_info (GFile *file, **/ GMount * g_file_find_enclosing_mount (GFile *file, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { GFileIface *iface; @@ -976,16 +1021,17 @@ g_file_find_enclosing_mount (GFile *file, * @cancellable: a #GCancellable * @error: a #GError, or %NULL * - * Reads a whole file into a #GFileInputStream. Fails returning %NULL if - * given #GFile points to a directory. + * Opens a file for reading. The result is a #GFileInputStream that + * can be used to read the contents of the file. * - * If the #GFileIface for @file does not support reading files, then - * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. - * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * + * If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned. + * If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned. + * Other errors are possible too, and depend on what kind of filesystem the file is on. + * * Returns: #GFileInputStream or %NULL on error. **/ GFileInputStream * @@ -1020,15 +1066,23 @@ g_file_read (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * - * Gets an output stream for appending to the file. + * 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 #G_FILE_CREATE_FLAGS_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 the #GFileIface for @file does not support appending to files, - * then @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will - * be returned. - * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Some filesystems don't allow all filenames, and may + * return an G_IO_ERROR_INVALID_FILENAME error. + * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be + * returned. Other errors are possible too, and depend on what kind of + * filesystem the file is on. * * Returns: a #GFileOutputStream. **/ @@ -1065,14 +1119,26 @@ g_file_append_to (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * - * Creates the file and returns an output stream for writing to it. + * Creates a new file and returns an output stream for writing to it. + * The file must not already exists. * - * If the #GFileIface for @file does not support creating files, then - * @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will be returned. + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_FLAGS_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 %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * If a file with this name already exists the G_IO_ERROR_EXISTS error + * will be returned. If the file is a directory the G_IO_ERROR_IS_DIRECTORY + * error will be returned. + * Some filesystems don't allow all filenames, and may + * return an G_IO_ERROR_INVALID_FILENAME error, and if the name + * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. + * Other errors are possible too, and depend on what kind of + * filesystem the file is on. * * Returns: a #GFileOutputStream for the newly created file, or * %NULL on error. @@ -1106,9 +1172,9 @@ g_file_create (GFile *file, /** * g_file_replace: * @file: input #GFile. - * @etag: an entity tag for the - * current #GFile. - * @make_backup: %TRUE if a backup should be created`. + * @etag: an optional entity tag for the + * current #GFile, or #NULL to ignore. + * @make_backup: %TRUE if a backup should be created. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL @@ -1116,19 +1182,45 @@ g_file_create (GFile *file, * Returns an output stream for overwriting the file, possibly * creating a backup copy of the file first. * - * If the #GFileIface for @file does not support streaming operations, - * then @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will - * be returned. - * + * 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. + * + * By default files created are generally readable by everyone, + * but if you pass #G_FILE_CREATE_FLAGS_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 %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * @etag will replace the entity tag for the current file. - * - * Returns: a #GFileOutputStream or %NULL on error. If @make_backup is - * %TRUE, this function will attempt to make a backup of the current - * file. + * If you pass in a non-#NULL @etag value, then this value is + * compared to the current entity tag of the file, and if they differ + * an G_IO_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 g_file_output_stream_get_etag() after you've + * finished writing and closed the #GFileOutputStream. When you load + * a new file you can use g_file_input_stream_query_info() to get + * the etag of the file. + * + * If @make_backup is %TRUE, this function will attempt to make a backup + * of the current file before overwriting it. If this fails a G_IO_ERROR_CANT_CREATE_BACKUP + * error will be returned. If you want to replace anyway, try again with + * @make_backup set to %FALSE. + * + * If the file is a directory the G_IO_ERROR_IS_DIRECTORY error will be returned, + * and if the file is some other form of non-regular file then a + * G_IO_ERROR_NOT_REGULAR_FILE error will be returned. + * Some filesystems don't allow all filenames, and may + * return an G_IO_ERROR_INVALID_FILENAME error, and if the name + * is to long G_IO_ERROR_FILENAME_TOO_LONG will be returned. + * Other errors are possible too, and depend on what kind of + * filesystem the file is on. + * + * Returns: a #GFileOutputStream or %NULL on error. **/ GFileOutputStream * g_file_replace (GFile *file, @@ -1172,9 +1264,13 @@ g_file_replace (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Asynchronously reads @file. + * Asynchronously opens @file for reading. + * + * For more details, see g_file_read() which is + * the synchronous version of this call. * - * For the synchronous version of this function, see g_file_read(). + * When the operation is finished, @callback will be called. You can then call + * g_file_read_finish() to get the result of the operation. **/ void g_file_read_async (GFile *file, @@ -1204,14 +1300,6 @@ g_file_read_async (GFile *file, * Finishes an asynchronous file read operation started with * g_file_read_async(). * - * If the #GFileIface for @file does not support streaming operations, - * then @error will be set to %G_IO_ERROR_NOT_SUPPORTED and %NULL will - * be returned. - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - * * Returns: a #GFileInputStream or %NULL on error. **/ GFileInputStream * @@ -1245,15 +1333,13 @@ g_file_read_finish (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Readies a file for appending data asynchronously. + * Asynchronously opens @file for appending. * - * For the synchronous version of this function, see g_file_append_to(). - * To finish this operation, see g_file_append_to_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set when - * g_file_append_to_finish() is called, and %NULL will be returned. + * For more details, see g_file_append_to() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_append_to_finish() to get the result of the operation. **/ void g_file_append_to_async (GFile *file, @@ -1282,12 +1368,8 @@ g_file_append_to_async (GFile *file, * @res: #GAsyncResult * @error: a #GError, or %NULL * - * Finishes appending to a file. See g_file_append_to_async(). - * - * If @cancellable was not %NULL when g_file_append_to_async() was called, - * then the operation could have been be cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. + * Finishes an asynchronous file append operation started with + * g_file_append_to_async(). * * Returns: a valid #GFileOutputStream or %NULL on error. **/ @@ -1322,15 +1404,14 @@ g_file_append_to_finish (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Creates a new file asynchronously. + * Asynchronously creates a new file and returns an output stream for writing to it. + * The file must not already exists. * - * For the synchronous version of this function, see g_file_create(). - * To finish this operation, see g_file_create_finish(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and %NULL - * will be returned by g_file_create_finish(). + * For more details, see g_file_creat() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_create_finish() to get the result of the operation. **/ void g_file_create_async (GFile *file, @@ -1359,12 +1440,8 @@ g_file_create_async (GFile *file, * @res: a #GAsyncResult. * @error: a #GError, or %NULL * - * Finishes creating a file. See g_file_create_async(). - * - * If @cancellable was not %NULL when g_file_create_async() was called, - * then the operation could have been be cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. + * Finishes an asynchronous file create operation started with + * g_file_create_async(). * * Returns: a #GFileOutputStream or %NULL on error. **/ @@ -1401,17 +1478,15 @@ g_file_create_finish (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function - * - * Replaces a file's contents asynchronously. If @make_backup is - * %TRUE, this function will attempt to make a backup of the current file. * - * For the synchronous version of this function, see g_file_replace(). - * To finish this operation, see g_file_replace_finish(). + * Asyncronously overwrites the file, replacing the contents, possibly + * creating a backup copy of the file first. * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be set, and - * %NULL will be returned in g_file_replace_finish(). + * For more details, see g_file_replace() which is + * the synchronous version of this call. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_replace_finish() to get the result of the operation. **/ void g_file_replace_async (GFile *file, @@ -1444,14 +1519,10 @@ g_file_replace_async (GFile *file, * @res: a #GAsyncResult. * @error: a #GError, or %NULL * - * Finishes replacing the contents of the file. See g_file_replace_async(). + * Finishes an asynchronous file replace operation started with + * g_file_replace_async(). * - * If @cancellable was not %NULL when g_file_replace_async() was called, - * then the operation could have been be cancelled by triggering the cancellable - * object from another thread. If the operation was cancelled, the error - * %G_IO_ERROR_CANCELLED will be set in @error, and %NULL will be returned. - * - * Returns: a #GFileOutputStream, or %NULL if an error has occured. + * Returns: a #GFileOutputStream, or %NULL on error. **/ GFileOutputStream * g_file_replace_finish (GFile *file, @@ -1672,9 +1743,11 @@ build_attribute_list_for_copy (GFileAttributeInfoList *attributes, * * Copies the file attributes from @source to @destination. * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * 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. mtime). However + * if #G_FILE_COPY_ALL_METADATA is specified in @flags, then + * all the metadata that is possible to copy is copied. * * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. **/ @@ -1900,52 +1973,40 @@ file_copy_fallback (GFile *source, * @progress_callback: function to callback with progress information * @progress_callback_data: userdata to pass to @progress_callback * @error: #GError to set on error, or %NULL - * - * - * - * Copies a file or directory from @source to @destination, with the given - * @flags. This operation may fail, and @error will be set appropriately with - * the given error result (see the following table). - * File copies are always asynchronous. - * + * + * Copies the file @source to the location specified by @destination. + * Can not handle recursive copies of directories. + * + * If the flag #G_FILE_COPY_OVERWRITE is specified an already + * existing @destination file is overwritten. + * + * If the flag #G_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 %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * If @progress_callback is not %NULL, then the operation can be monitored by * setting this to a #GFileProgressCallback function. @progress_callback_data - * will be passed to this function. + * will be passed to this function. It is guaranteed that this callback will + * be called after all data has been transfered with the total number of bytes + * copied during the operation. * - * - * g_file_copy() Error Conditions - * - * SourceDestinationFlagsResults in - * - * %NULLAnythingAnything%G_IO_ERROR_NOT_FOUND - * File%NULLAnythingNo Error - * FileAnything0%G_IO_ERROR_EXISTS - * FileFile%G_FILE_COPY_OVERWRITENo Error - * FileDirectory%G_FILE_COPY_OVERWRITE%G_IO_ERROR_IS_DIRECTORY - * Directory%NULLAnything%G_IO_ERROR_WOULD_RECURSE - * DirectoryAnything0%G_IO_ERROR_EXISTS - * DirectoryDirectory%G_FILE_COPY_OVERWRITE%G_IO_ERROR_IS_DIRECTORY - * DirectoryFile%G_FILE_COPY_OVERWRITE%G_IO_ERROR_WOULD_RECURSE - * - * - *
+ * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND + * error is returned, independent on the status of the @destination. + * + * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the + * error G_IO_ERROR_EXISTS is returned. + * + * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY + * error is returned. If trying to overwrite a directory with a directory the + * G_IO_ERROR_WOULD_MERGE error is returned. + * + * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is + * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error + * is returned. * * If you are interested in copying the #GFile object itself (not the on-disk * file), see g_file_dup(). @@ -2007,60 +2068,42 @@ g_file_copy (GFile *source, * @progress_callback_data: gpointer to user data for the callback function. * @error: #GError for returning error conditions, or %NULL * - * - * - * Moves a file or directory from @source to @destination, with the given - * @flags. This operation may fail, and @error will be set appropriately with - * the given error result (see the following table). - * File moves are always asynchronous. + * + * Tries to move the file or directory @source to the location specified by @destination. + * If native move operations is 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. * + * If the flag #G_FILE_COPY_OVERWRITE is specified an already + * existing @destination file is overwritten. + * + * If the flag #G_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 %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * If @progress_callback is not %NULL, then the operation can be monitored by * setting this to a #GFileProgressCallback function. @progress_callback_data - * will be passed to this function. - * - * - * g_file_move() Error Conditions - * - * SourceDestination - * FlagsResults in - * - * %NULL Anything - * Anything %G_IO_ERROR_NOT_FOUND - * File %NULL - * Anything No Error - * File Anything - * 0 %G_IO_ERROR_EXISTS - * File File - * %G_FILE_COPY_OVERWRITE No Error - * File Directory - * %G_FILE_COPY_OVERWRITE %G_IO_ERROR_IS_DIRECTORY - * Directory %NULL - * Anything No Error or %G_IO_ERROR_WOULD_RECURSE - * Directory Anything - * 0 %G_IO_ERROR_EXISTS - * Directory Directory - * %G_FILE_COPY_OVERWRITE %G_IO_ERROR_IS_DIRECTORY - * Directory File - * %G_FILE_COPY_OVERWRITE No Error or %G_IO_ERROR_WOULD_RECURSE - * - * - *
+ * will be passed to this function. It is guaranteed that this callback will + * be called after all data has been transfered with the total number of bytes + * copied during the operation. + * + * If the @source file does not exist then the G_IO_ERROR_NOT_FOUND + * error is returned, independent on the status of the @destination. + * + * If #G_FILE_COPY_OVERWRITE is not specified and the target exists, then the + * error G_IO_ERROR_EXISTS is returned. + * + * If trying to overwrite a file over a directory the G_IO_ERROR_IS_DIRECTORY + * error is returned. If trying to overwrite a directory with a directory the + * G_IO_ERROR_WOULD_MERGE error is returned. + * + * If the source is a directory and the target does not exist, or #G_FILE_COPY_OVERWRITE is + * specified and the target is a file, then the G_IO_ERROR_WOULD_RECURSE error + * may be returned (if the native move operation isn't availible). * * Returns: %TRUE on successful move, %FALSE otherwise. **/ @@ -2162,7 +2205,7 @@ g_file_make_directory (GFile *file, /** * g_file_make_symbolic_link: * @file: input #GFile. - * @symlink_value: a string with the name of the new symlink. + * @symlink_value: a string with the value of the new symlink. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * @@ -2254,10 +2297,11 @@ g_file_delete (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * - * Sends @file to the virtual file system "Trash" location. If the - * virtual file system does not have support having a "Trash" location, - * %FALSE will be returned, and @error will be set to - * %G_IO_ERROR_NOT_SUPPORTED. + * 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 filesystems support trashing, so this call can return the + * %G_IO_ERROR_NOT_SUPPORTED error. + * * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -2297,15 +2341,22 @@ g_file_trash (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError, or %NULL * - * Sets the display name for @file. If the display name contains invalid - * characters, @error will be set to %G_IO_ERROR_INVALID_ARGUMENT. For the - * asynchronous version of this function, see g_file_set_display_name_async(). + * Renames @file to the specified display name. + * + * The display name is converted from UTF8 to the correct encoding for the target + * filesystem if possible and the @file is renamed to this. + * + * If you want to implement a rename operation in the user interface the edit name + * (#G_FILE_ATTRIBUTE_STD_EDIT_NAME) should be used as the initial value in the rename + * widget, and then the result after editing should be passed to g_file_set_display_name(). + * + * On success the resulting converted filename is returned. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFile, or %NULL if there was an error. + * Returns: a #GFile specifying what @file was renamed to, or %NULL if there was an error. **/ GFile * g_file_set_display_name (GFile *file, @@ -2347,10 +2398,6 @@ g_file_set_display_name (GFile *file, * * Asynchronously sets the display name for a given #GFile. * For the synchronous version of this function, see g_file_set_display_name(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. **/ void g_file_set_display_name_async (GFile *file, @@ -2414,14 +2461,17 @@ g_file_set_display_name_finish (GFile *file, * * Obtain the list of settable attributes for the file. * + * 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. + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: the type and full attribute name of all the attributes - * that the file can set. 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. + * Returns: a #GFileAttributeInfoList describing the settable attributes. + * When you are done with it, release it with g_file_attribute_info_list_unref() **/ GFileAttributeInfoList * g_file_query_settable_attributes (GFile *file, @@ -2466,15 +2516,15 @@ g_file_query_settable_attributes (GFile *file, * @error: a #GError, or %NULL * * Obtain the list of attribute namespaces where new attributes - * can be created. + * can be created by a user. An example of this is extended + * attributes (in the "xattr" namespace). * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList of attribute namespaces - * where the user can create their own attribute names, such - * as extended attributes. + * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * When you are done with it, release it with g_file_attribute_info_list_unref() **/ GFileAttributeInfoList * g_file_query_writable_namespaces (GFile *file, @@ -2522,8 +2572,6 @@ g_file_query_writable_namespaces (GFile *file, * @error: a #GError, or %NULL * * Sets an attribute in the file with attribute name @attribute to @value. - * If setting attributes is not suppored by the #GFileIface for @file, - * then @error will be set to %G_IO_ERROR_NOT_SUPPORTED. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -2571,14 +2619,17 @@ g_file_set_attribute (GFile *file, * Tries to set all attributes in the #GFileInfo on the target values, * not stopping on the first error. * + * 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 + * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING, which means you can also detect + * further errors. + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if there was any error, and @error will be set to - * the first error. Error on particular fields are flagged by setting - * the "status" field in the attribute value to - * %G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING. + * Returns: %TRUE if there was any error, %FALSE otherwise. **/ gboolean g_file_set_attributes_from_info (GFile *file, @@ -2659,10 +2710,6 @@ g_file_real_set_attributes_from_info (GFile *file, * * Asynchronously sets the attributes of @file with @info. * For the synchronous version of this function, see g_file_set_attributes(). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. **/ void g_file_set_attributes_async (GFile *file, @@ -2923,16 +2970,21 @@ g_file_set_attribute_int64 (GFile *file, /** * g_file_mount_mountable: * @file: input #GFile. - * @mount_operation: a #GMountOperation. + * @mount_operation: a #GMountOperation, or %NULL. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Mounts a mountable file using @mount_operation, if possible. + * Mounts a file of type G_FILE_TYPE_MOUNTABLE. + * You can speciy using @mount_operation to get callbacks when for instance + * passwords are needed during authentication. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_mount_mountable_finish() to get the result of the operation. **/ void g_file_mount_mountable (GFile *file, @@ -3004,13 +3056,14 @@ g_file_mount_mountable_finish (GFile *file, * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Starts an asynchronous unmount operation. - * - * Unmounts a mounted file. + * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * When the operation is finished, @callback will be called. You can then call + * g_file_mount_mountable_finish() to get the result of the operation. **/ void g_file_unmount_mountable (GFile *file, @@ -3155,6 +3208,7 @@ g_file_eject_mountable_finish (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * * Obtains a directory monitor for the given file. + * This may fail if directory monitoring is not supported. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -3186,14 +3240,14 @@ g_file_monitor_directory (GFile *file, * @flags: a set of #GFileMonitorFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Obtains a file monitor for the given file. + * Obtains a file monitor for the given file. If no file notification + * mechanism exists, then regular polling of the file is used. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileMonitor for the given @file, - * or %NULL on error. + * Returns: a #GFileMonitor for the given @file. **/ GFileMonitor* g_file_monitor_file (GFile *file, @@ -3843,10 +3897,9 @@ g_file_new_for_uri (const char *uri) * g_file_parse_name: * @parse_name: a file name or path to be parsed. * - * Constructs a #GFile with the given @parse_name, - * looked up by #GVfs. This operation never fails, - * but the returned object might not support any I/O - * operation if the @parse_name cannot be parsed by #GVfs. + * Constructs a #GFile 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. * * Returns: a new #GFile. **/ @@ -3885,8 +3938,8 @@ has_valid_scheme (const char *uri) * g_file_new_for_commandline_arg: * @arg: a command line string. * - * Attempts to generate a #GFile with the given line from - * the command line argument. + * Creates a #GFile with the given argument from + * the command line. * * Returns: a new #GFile. **/ @@ -3923,7 +3976,7 @@ g_file_new_for_commandline_arg (const char *arg) * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function * - * Starts the @mount_operation, mounting the volume at @location. + * Starts a @mount_operation, mounting the volume that contains the file @location. * * When this operation has completed, @callback will be called with * @user_user data, and the operation can be finalized with @@ -4009,14 +4062,17 @@ g_mount_for_location_finish (GFile *location, * @length: a location to place the length of the contents of the file. * @etag_out: a location to place the current entity tag for the file. * @error: a #GError, or %NULL + * + * Loads the content of the file into memory, returning the size of + * the data. The data is always zero terminated, but this is not + * included in the resultant @length. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * Returns: %TRUE if the @file's contents were successfully loaded. - * %FALSE if there were errors. The length of the loaded data will be - * put into @length, the contents in @contents. + * %FALSE if there were errors.. **/ gboolean g_file_load_contents (GFile *file, diff --git a/gio/gfile.h b/gio/gfile.h index 49e24cb..cf16027 100644 --- a/gio/gfile.h +++ b/gio/gfile.h @@ -44,6 +44,7 @@ G_BEGIN_DECLS * Flags used when querying a #GFileInfo. */ typedef enum { + G_FILE_QUERY_INFO_FLAGS_NONE = 0, G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (1<<0) /*< nick=nofollow-symlinks >*/ } GFileQueryInfoFlags; @@ -64,9 +65,9 @@ typedef enum { * GFileCopyFlags: * @G_FILE_COPY_FLAGS_NONE: No flags set. * @G_FILE_COPY_OVERWRITE: Overwrite any existing files - * @G_FILE_COPY_BACKUP: Make a backup of any existing files. TODO: explain backup naming scheme. + * @G_FILE_COPY_BACKUP: Make a backup of any existing files. * @G_FILE_COPY_NOFOLLOW_SYMLINKS: Don't follow symlinks. - * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set (see #GFileInfo). + * @G_FILE_COPY_ALL_METADATA: Copy all file metadata instead of just default set used for copy (see #GFileInfo). * @G_FILE_COPY_NO_FALLBACK_FOR_MOVE: Don't use copy and delete fallback if native move not supported. * * Flags used when copying or moving files. diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index 31bb1e1..45ccae3 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -39,8 +39,8 @@ * * Keys are strings that contain a key namespace and a key name, separated * by a colon, e.g. "namespace:keyname". Namespaces are included to sort - * key-value pairs by namespaces for relevance. Keys can be searched - * for using wildcards, e.g. "std:*" will return all of the keys in the + * key-value pairs by namespaces for relevance. Keys can be retrived + * using wildcards, e.g. "std:*" will return all of the keys in the * "std" namespace. * * Values are stored within the list in #GFileAttributeValue structures. @@ -48,16 +48,14 @@ * Upon creation of a #GFileAttributeValue, the type will be set to * %G_FILE_ATTRIBUTE_TYPE_INVALID. * - * The Key-value list is stored within the #GFile structure as a - * #GFileAttributeInfoList. This list is queryable by key names + * The list of possible attributes for a filesystem (pointed to by a #GFile) is + * availible as a #GFileAttributeInfoList. This list is queryable by key names * as indicated earlier. * * Classes that implement #GFileIface will create a #GFileAttributeInfoList and * install default keys and values for their given file system, architecture, * and other possible implementation details (e.g., on a UNIX system, a file - * attribute key will be registered for the user id for a given file). Other - * attributes can be appended to a #GFileAttributeList later by - * g_file_attribute_info_list_add(). + * attribute key will be registered for the user id for a given file). * * * @@ -83,7 +81,7 @@ * NTFS ACLs in Windows should be mapped to these values. * "mountable"The "Mountable" namespace. Includes * simple boolean keys for checking if a file or path supports mount operations, e.g. - * mount, unmount, eject. + * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. * "time"The "Time" namespace. Includes file * access, changed, created times. * "unix"The "Unix" namespace. Includes UNIX-specific @@ -95,11 +93,12 @@ * for checking if a file is marked as an archive file. * "owner"The "Owner" namespace. Includes information * about who owns a file. May not be available for all file systems. Examples include - * "user" for getting the user name of the file owner. + * "user" for getting the user name of the file owner. This information is often mapped from + * some backend specific data such as a unix UID. * "thumbnail"The "Thumbnail" namespace. Includes * information about file thumbnails and their location within the file system. Exaples of * keys in this namespace include "path" to get the location of a thumbnail, and "failed" - * to check if thumbnailing failed. + * to check if thumbnailing of the file failed. * "fs"The "Filesystem" namespace. Gets information * about the file system where a file is located, such as its type, how much * space is left available, and the overall size of the file system. diff --git a/gio/gfileattribute.h b/gio/gfileattribute.h index 23565b8..0c96e99 100644 --- a/gio/gfileattribute.h +++ b/gio/gfileattribute.h @@ -30,7 +30,7 @@ G_BEGIN_DECLS /** * GFileAttributeType: * @G_FILE_ATTRIBUTE_TYPE_INVALID: indicates an invalid or uninitalized type. - * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated C string. + * @G_FILE_ATTRIBUTE_TYPE_STRING: a null terminated UTF8 string. * @G_FILE_ATTRIBUTE_TYPE_BYTE_STRING: a zero terminated string of non-zero bytes. * @G_FILE_ATTRIBUTE_TYPE_BOOLEAN: a boolean value. * @G_FILE_ATTRIBUTE_TYPE_UINT32: an unsigned 4-byte/32-bit integer. @@ -59,7 +59,7 @@ typedef enum { * @G_FILE_ATTRIBUTE_FLAGS_COPY_WITH_FILE: copy the attribute values when the file is copied. * @G_FILE_ATTRIBUTE_FLAGS_COPY_WHEN_MOVED: copy the attribute values when the file is moved. * - * Indicates how to transfer file attributes to new #GFile structures when they are copied. + * A flag specifying the behaviour of an attribute. **/ typedef enum { G_FILE_ATTRIBUTE_FLAGS_NONE = 0, @@ -107,11 +107,11 @@ typedef struct { /** * GFileAttributeInfo: - * @name: a string containing the key's name. - * @type: a #GFileAttributeType for the key. + * @name: the name of the attribute. + * @type: the #GFileAttributeType type of the attribute. * @flags: a set of #GFileAttributeFlags. * - * A Key-Value pair definition. + * Information about a specific attribute. **/ typedef struct { char *name; diff --git a/gio/gfileicon.c b/gio/gfileicon.c index 7e2ec45..571d901 100644 --- a/gio/gfileicon.c +++ b/gio/gfileicon.c @@ -29,11 +29,12 @@ /** * SECTION:gfileicon - * @short_description: Icons for given files + * @short_description: Icons pointing to an image file * @see_also: #GIcon, #GLoadableIcon * @include: gio/gfileicon.h * - * #GFileIcon gets the default icon for a #GFile. + * #GFileIcon specifies an icon by pointing to an image file + * to be used as icon. * **/ diff --git a/gio/gfileicon.h b/gio/gfileicon.h index 1d43cce..e31c42d 100644 --- a/gio/gfileicon.h +++ b/gio/gfileicon.h @@ -38,7 +38,7 @@ G_BEGIN_DECLS /** * GFileIcon: * - * Gets an icon for a #GFile. Implements #GLoadabeIcon. + * Gets an icon for a #GFile. Implements #GLoadableIcon. **/ typedef struct _GFileIcon GFileIcon; typedef struct _GFileIconClass GFileIconClass; diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h index f377efe..7633fc3 100644 --- a/gio/gfileinfo.h +++ b/gio/gfileinfo.h @@ -106,6 +106,8 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_IS_SYMLINK: * * A key in the "std" namespace for checking if the file is a symlink. + * Typically the actual type is something else, if we followed the symlink + * to get the type. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_STD_IS_SYMLINK "std:is_symlink" /* boolean */ @@ -122,6 +124,10 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_NAME: * * A key in the "std" namespace for getting the name of the file. + * The name is the on-disk filename which may not be in any known encoding, + * and can thus not be generally displayed as is. + * Use #G_FILE_ATTRIBUTE_STD_DISPLAY_NAME if you need to display the + * name in a user interface. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. **/ #define G_FILE_ATTRIBUTE_STD_NAME "std:name" /* byte string */ @@ -130,6 +136,8 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_DISPLAY_NAME: * * A key in the "std" namespace for getting the display name of the file. + * A display name is guaranteed to be in UTF8 and can thus be displayed in + * the UI. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STD_DISPLAY_NAME "std:display_name" /* string */ @@ -138,6 +146,11 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_EDIT_NAME: * * A key in the "std" namespace for edit name of the file. + * An edit name is similar to the display name, but it is meant to be + * used when you want to rename the file in the UI. The display name + * might contain information you don't want in the new filename (such as + * "(invalid unicode)" if the filename was in an invalid encoding). + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STD_EDIT_NAME "std:edit_name" /* string */ @@ -146,6 +159,12 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_COPY_NAME: * * A key in the "std" namespace for getting the copy name of the file. + * The copy name is an optional version of the name. If availible its always + * in UTF8, and corresponds directly to the original filename (only transcoded to + * UTF8). This is useful if you want to copy the file to another filesystem that + * might have a different encoding. If the filename is not a valid string in the + * encoding selected for the filesystem it is in then the copy name will not be set. + * * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STD_COPY_NAME "std:copy_name" /* string */ @@ -172,6 +191,9 @@ typedef enum { * G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE: * * A key in the "std" namespace for getting the fast content type. + * The fast content type isn't as reliable as the regular one, as it + * only uses the filename to guess it, but it is faster to calculate than the + * regular content type. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * **/ @@ -180,7 +202,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_STD_SIZE: * - * A key in the "std" namespace for getting the file's size. + * A key in the "std" namespace for getting the file's size (in bytes). * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_STD_SIZE "std:size" /* uint64 */ @@ -197,7 +219,8 @@ typedef enum { /** * G_FILE_ATTRIBUTE_STD_TARGET_URI: * - * A key in the "std" namespace for getting the target URI for the file. + * A key in the "std" namespace for getting the target URI for the file, in + * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_STD_TARGET_URI "std:target_uri" /* string */ @@ -208,7 +231,9 @@ typedef enum { * A key in the "std" namespace for setting the sort order of a file. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. * An example use would be in file managers, which would use this key - * to set the order files are displayed. + * to set the order files are displayed. Files with smaller sort order + * should be sorted first, and files without sort order as if sort order + * was zero. **/ #define G_FILE_ATTRIBUTE_STD_SORT_ORDER "std:sort_order" /* int32 */ @@ -290,8 +315,8 @@ typedef enum { * * A key in the "access" namespace for checking trashing privileges. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - * This attribute will be %TRUE if the user is able to send the file to - * the virtual file system trash location. + * This attribute will be %TRUE if the user is able to move the file to + * the trash. **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH "access:can_trash" /* boolean */ @@ -311,7 +336,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: * - * A key in the "mountable" namespace for checking if a file is mountable. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable:can_mount" /* boolean */ @@ -319,7 +344,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: * - * A key in the "mountable" namespace for checking if a file is unmountable. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable:can_unmount" /* boolean */ @@ -327,7 +352,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: * - * A key in the "mountable" namespace for checking if a file can be ejected. + * A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable:can_eject" /* boolean */ @@ -343,7 +368,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: * - * A key in the "mountable" namespace for getting the HAL UDI for the mounted + * A key in the "mountable" namespace for getting the HAL UDI for the mountable * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable:hal_udi" /* string */ @@ -603,8 +628,8 @@ typedef enum { /** * G_FILE_ATTRIBUTE_FS_SIZE: * - * A key in the "fs" namespace for getting the size of the file system, - * used in g_file_get_filesystem_info(). Corresponding #GFileAttributeType + * A key in the "fs" namespace for getting the total size (in bytes) of the file system, + * used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType * is %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ #define G_FILE_ATTRIBUTE_FS_SIZE "fs:size" /* uint64 */ @@ -612,7 +637,7 @@ typedef enum { /** * G_FILE_ATTRIBUTE_FS_FREE: * - * A key in the "fs" namespace for getting the free space left on the + * A key in the "fs" namespace for getting the number of bytes of free space left on the * file system. Corresponding #GFileAttributeType is * %G_FILE_ATTRIBUTE_TYPE_UINT64. **/ diff --git a/gio/gfileinputstream.h b/gio/gfileinputstream.h index 9b61ed6..c737f4f 100644 --- a/gio/gfileinputstream.h +++ b/gio/gfileinputstream.h @@ -37,9 +37,11 @@ G_BEGIN_DECLS /** * GFileInputStream: - * @parent: the parent #GInputStream instance. * - * Implements #GInputStream and #GSeekable for file input operations. + * A subclass of GInputStream for opened files. This adds + * a few file-specific operations and seeking. + * + * #GFileInputStream implements #GSeekable. **/ typedef struct _GFileInputStream GFileInputStream; typedef struct _GFileInputStreamClass GFileInputStreamClass; diff --git a/gio/gfilemonitor.c b/gio/gfilemonitor.c index 730aa66..fdfbc11 100644 --- a/gio/gfilemonitor.c +++ b/gio/gfilemonitor.c @@ -269,8 +269,8 @@ g_file_monitor_cancel (GFileMonitor* monitor) * @limit_msecs: a integer with the limit in milliseconds to * poll for changes. * - * Sets the rate limit to which the @monitor will poll for changes - * on the device. + * Sets the rate limit to which the @monitor will report + * consecutive change events to the same file. * **/ void diff --git a/gio/gfilemonitor.h b/gio/gfilemonitor.h index bb96f6c..42171c9 100644 --- a/gio/gfilemonitor.h +++ b/gio/gfilemonitor.h @@ -37,15 +37,15 @@ G_BEGIN_DECLS /** * GFileMonitorEvent: - * @G_FILE_MONITOR_EVENT_CHANGED: Monitor file changed events. - * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: Monitor file changed done events. - * @G_FILE_MONITOR_EVENT_DELETED: Monitors file deleted events. - * @G_FILE_MONITOR_EVENT_CREATED: Monitors file created events. - * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: Monitors file attribute changed events. - * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: Monitors pre-unmount events. - * @G_FILE_MONITOR_EVENT_UNMOUNTED: Monitors unmount events. + * @G_FILE_MONITOR_EVENT_CHANGED: a file changed. + * @G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT: a hint that this was probably the last change in a set of changes. + * @G_FILE_MONITOR_EVENT_DELETED: a file was deleted. + * @G_FILE_MONITOR_EVENT_CREATED: a file was created. + * @G_FILE_MONITOR_EVENT_ATTRIBUTE_CHANGED: a file attribute was changed. + * @G_FILE_MONITOR_EVENT_PRE_UNMOUNT: the file location will soon be unmounted. + * @G_FILE_MONITOR_EVENT_UNMOUNTED: the file location was be unmounted. * - * Flags used when creating a #GFileMonitor to define what events to monitor for. + * Specifies what type of event a monitor event is. **/ typedef enum { G_FILE_MONITOR_EVENT_CHANGED, @@ -63,7 +63,7 @@ typedef struct _GFileMonitorPrivate GFileMonitorPrivate; /** * GFileMonitor: * - * Watches for changes within a #GFile. + * Watches for changes to a file. **/ struct _GFileMonitor { diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c index 40ec2c0..80a15fe 100644 --- a/gio/gfileoutputstream.c +++ b/gio/gfileoutputstream.c @@ -263,7 +263,9 @@ g_file_output_stream_query_info_finish (GFileOutputStream *stream, * g_file_output_stream_get_etag: * @stream: a #GFileOutputStream. * - * Gets the entity tag for the file output stream. + * Gets the entity tag for the file when its been written. + * This must be called after the stream has been written + * and closed. As the etag can change while writing. * * Returns: the entity tag for the stream. **/ diff --git a/gio/gfileoutputstream.h b/gio/gfileoutputstream.h index 853f5d4..a31f25f 100644 --- a/gio/gfileoutputstream.h +++ b/gio/gfileoutputstream.h @@ -37,9 +37,11 @@ G_BEGIN_DECLS /** * GFileOutputStream: - * @parent: The parent #GOutputStream instance. * - * Implements #GOutputStream and #GSeekable for file output operations. + * A subclass of GOutputStream for opened files. This adds + * a few file-specific operations and seeking and truncating. + * + * #GFileOutputStream implements GSeekable. **/ typedef struct _GFileOutputStream GFileOutputStream; typedef struct _GFileOutputStreamClass GFileOutputStreamClass; diff --git a/gio/gfilterinputstream.h b/gio/gfilterinputstream.h index e136359..e71231b 100644 --- a/gio/gfilterinputstream.h +++ b/gio/gfilterinputstream.h @@ -38,7 +38,7 @@ G_BEGIN_DECLS /** * GFilterInputStream: * - * Filtered input streams. Implements #GInputStream. + * A base class for all input streams that work on an underlying stream. **/ typedef struct _GFilterInputStream GFilterInputStream; typedef struct _GFilterInputStreamClass GFilterInputStreamClass; diff --git a/gio/gfilteroutputstream.h b/gio/gfilteroutputstream.h index 1a131a5..e676632 100644 --- a/gio/gfilteroutputstream.h +++ b/gio/gfilteroutputstream.h @@ -38,7 +38,7 @@ G_BEGIN_DECLS /** * GFilterOutputStream: * - * Filtered output streams. Implements #GOutputStream. + * A base class for all output streams that work on an underlying stream. **/ typedef struct _GFilterOutputStream GFilterOutputStream; typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass; diff --git a/gio/gicon.h b/gio/gicon.h index 039cbee..b7dab6a 100644 --- a/gio/gicon.h +++ b/gio/gicon.h @@ -35,7 +35,7 @@ G_BEGIN_DECLS /** * GIcon: * - * Icons for file, content, drive and volume types. + * An abstract type that specifies an icon. **/ typedef struct _GIcon GIcon; /* Dummy typedef */ typedef struct _GIconIface GIconIface; @@ -48,7 +48,7 @@ typedef struct _GIconIface GIconIface; * * GIconIface is used to implement GIcon types for various * different systems. See #GThemedIcon and #GLoadableIcon for - * examples of how to use this interface. + * examples of how to implement this interface. */ struct _GIconIface { diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c index 46484af..61b7fbe 100644 --- a/gio/gioscheduler.c +++ b/gio/gioscheduler.c @@ -329,12 +329,12 @@ mainloop_proxy_notify (gpointer data) /** * g_io_job_send_to_mainloop: * @job: a #GIOJob. - * @func: a #GIODataFunc. + * @func: a #GIODataFunc callback that will be called the main thread. * @user_data: a #gpointer. * @notify: a #GDestroyNotify. - * @block: boolean flag indicating whether or not this job should block. + * @block: boolean flag indicating whether or not the job should block until the callback has returned. * - * Sends an I/O job to the application's main loop for processing. + * Sends a notification from an I/O job to the mainloop processing on the main thread. **/ void g_io_job_send_to_mainloop (GIOJob *job, diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c index bcddde3..e9cac77 100644 --- a/gio/gloadableicon.c +++ b/gio/gloadableicon.c @@ -32,7 +32,7 @@ * @short_description: Loadable Icons * @see_also: #GIcon, #GThemedIcon * - * Extends the #GIcon interface and adds the ability to load icons. + * Extends the #GIcon interface and adds the ability to load icons from streams. **/ static void g_loadable_icon_real_load_async (GLoadableIcon *icon, diff --git a/gio/gloadableicon.h b/gio/gloadableicon.h index fdbece2..88f42df 100644 --- a/gio/gloadableicon.h +++ b/gio/gloadableicon.h @@ -37,7 +37,7 @@ G_BEGIN_DECLS /** * GLoadableIcon: * - * Dummy type for subclassing loadable icon types. + * Generic interface for all kinds of icons that can be loaded as a stream to an image file. **/ typedef struct _GLoadableIcon GLoadableIcon; /* Dummy typedef */ typedef struct _GLoadableIconIface GLoadableIconIface; @@ -49,8 +49,6 @@ typedef struct _GLoadableIconIface GLoadableIconIface; * @load_async: Loads an icon asynchronously. * @load_finish: Finishes an asynchronous icon load. * - * GLoadableIconIface is used for implementing loadable icon types, - * for implementations that need to load an icon. **/ struct _GLoadableIconIface { diff --git a/gio/glocalfileinfo.c b/gio/glocalfileinfo.c index f9eadd0..0a5e04c 100644 --- a/gio/glocalfileinfo.c +++ b/gio/glocalfileinfo.c @@ -1288,70 +1288,70 @@ win32_get_file_user_info (const gchar* filename, sd_size, &sd_size)) { - PSID psid = 0; + PSID psid = 0; BOOL defaulted; SID_NAME_USE name_use = 0; /* don't care? */ - wchar_t *name = NULL; - wchar_t *domain = NULL; - DWORD name_len = 0; - DWORD domain_len = 0; - /* get the user name */ - do { - if (!user_name) - break; - if (!GetSecurityDescriptorOwner (psd, &psid, &defaulted)) - break; - if (!LookupAccountSidW (NULL, /* local machine */ - psid, - name, &name_len, - domain, &domain_len, /* no domain info yet */ - &name_use) && (ERROR_INSUFFICIENT_BUFFER != GetLastError())) - break; - name = g_try_malloc (name_len*sizeof(wchar_t)); - domain = g_try_malloc (domain_len*sizeof(wchar_t)); - if (name && domain && - LookupAccountSidW (NULL, /* local machine */ - psid, - name, &name_len, - domain, &domain_len, /* no domain info yet */ - &name_use)) - { - *user_name = g_utf16_to_utf8 (name, -1, NULL, NULL, NULL); - } - g_free (name); - g_free (domain); - } while (FALSE); - - /* get the group name */ - do { - if (!group_name) - break; - if (!GetSecurityDescriptorGroup (psd, &psid, &defaulted)) - break; - if (!LookupAccountSidW (NULL, /* local machine */ - psid, - name, &name_len, - domain, &domain_len, /* no domain info yet */ - &name_use) && (ERROR_INSUFFICIENT_BUFFER != GetLastError())) - break; - name = g_try_malloc (name_len*sizeof(wchar_t)); - domain = g_try_malloc (domain_len*sizeof(wchar_t)); - if (name && domain && - LookupAccountSidW (NULL, /* local machine */ - psid, - name, &name_len, - domain, &domain_len, /* no domain info yet */ - &name_use)) - { - *group_name = g_utf16_to_utf8 (name, -1, NULL, NULL, NULL); - } - g_free (name); - g_free (domain); - } while (FALSE); - - /* TODO: get real name */ - - g_free (psd); + wchar_t *name = NULL; + wchar_t *domain = NULL; + DWORD name_len = 0; + DWORD domain_len = 0; + /* get the user name */ + do { + if (!user_name) + break; + if (!GetSecurityDescriptorOwner (psd, &psid, &defaulted)) + break; + if (!LookupAccountSidW (NULL, /* local machine */ + psid, + name, &name_len, + domain, &domain_len, /* no domain info yet */ + &name_use) && (ERROR_INSUFFICIENT_BUFFER != GetLastError())) + break; + name = g_try_malloc (name_len*sizeof(wchar_t)); + domain = g_try_malloc (domain_len*sizeof(wchar_t)); + if (name && domain && + LookupAccountSidW (NULL, /* local machine */ + psid, + name, &name_len, + domain, &domain_len, /* no domain info yet */ + &name_use)) + { + *user_name = g_utf16_to_utf8 (name, -1, NULL, NULL, NULL); + } + g_free (name); + g_free (domain); + } while (FALSE); + + /* get the group name */ + do { + if (!group_name) + break; + if (!GetSecurityDescriptorGroup (psd, &psid, &defaulted)) + break; + if (!LookupAccountSidW (NULL, /* local machine */ + psid, + name, &name_len, + domain, &domain_len, /* no domain info yet */ + &name_use) && (ERROR_INSUFFICIENT_BUFFER != GetLastError())) + break; + name = g_try_malloc (name_len*sizeof(wchar_t)); + domain = g_try_malloc (domain_len*sizeof(wchar_t)); + if (name && domain && + LookupAccountSidW (NULL, /* local machine */ + psid, + name, &name_len, + domain, &domain_len, /* no domain info yet */ + &name_use)) + { + *group_name = g_utf16_to_utf8 (name, -1, NULL, NULL, NULL); + } + g_free (name); + g_free (domain); + } while (FALSE); + + /* TODO: get real name */ + + g_free (psd); } g_free (wfilename); } diff --git a/gio/gmemoryinputstream.c b/gio/gmemoryinputstream.c index 8bae37b..2e113bd 100644 --- a/gio/gmemoryinputstream.c +++ b/gio/gmemoryinputstream.c @@ -252,8 +252,7 @@ g_memory_input_stream_get_data (GMemoryInputStream *stream) * * Gets the size of the data within the #GMemoryInputStream. * - * Returns: a gsize with the size of the data in @stream, or -1 - * on error. + * Returns: a gsize with the size of the data in @stream. **/ gsize g_memory_input_stream_get_data_size (GMemoryInputStream *stream) diff --git a/gio/gmountoperation.c b/gio/gmountoperation.c index 6679c2e..e2b3ac9 100644 --- a/gio/gmountoperation.c +++ b/gio/gmountoperation.c @@ -39,11 +39,14 @@ * operations, such as loop mounting files, hard drive partitions or * server locations. * - * Mountable GIO backends should implement #GMountOperation if they + * Mountin operations are handed a #GMountOperation that then can use if they * require any privileges or authentication for their volumes to be * mounted (e.g. a hard disk partition or an encrypted filesystem), or * if they are implementing a remote server protocol which requires user - * credentials such as FTP or WebDAV. + * credentials such as FTP or WebDAV. + * + * Users should instantiate a subclass of this that implements all + * the various callbacks to show the required dialogs. **/ G_DEFINE_TYPE (GMountOperation, g_mount_operation, G_TYPE_OBJECT); diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index 11e9d3f..9f68df4 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -35,6 +35,9 @@ * #GThemedIcon contains a list of all of the icons present in an icon * theme, so that icons can be looked up quickly. #GThemedIcon does * not provide actual pixmaps for icons, just the icon names. + * Ideally something like gtk_icon_theme_choose_icon() should be used to + * resolve the list of names so that fallback icons work nicely with + * themes that inherit other themes. **/ static void g_themed_icon_icon_iface_init (GIconIface *iface); -- 2.7.4