From 5247f12f3649726471080440de0d37b78c1cec33 Mon Sep 17 00:00:00 2001 From: Andrew Walton Date: Tue, 27 Nov 2007 14:00:13 +0000 Subject: [PATCH] Bumps documentation to 93% symbol coverage, touching most of the public files. Fixes broken function documentation prototypes. Fixes GCancellable inaccuracies. Removes unnecessary incomplete gtk-doc headers in private files. svn path=/trunk/; revision=5953 --- gio/ChangeLog | 93 ++++++ gio/gappinfo.c | 85 ++++- gio/gappinfo.h | 48 ++- gio/gasynchelper.c | 9 + gio/gasyncresult.c | 66 +++- gio/gasyncresult.h | 23 ++ gio/gbufferedinputstream.c | 40 ++- gio/gbufferedinputstream.h | 6 + gio/gbufferedoutputstream.c | 37 ++- gio/gbufferedoutputstream.h | 7 + gio/gcancellable.c | 27 +- gio/gcancellable.h | 8 +- gio/gcontenttype.c | 58 +++- gio/gdatainputstream.c | 44 ++- gio/gdatainputstream.h | 28 +- gio/gdataoutputstream.c | 70 +++- gio/gdataoutputstream.h | 9 +- gio/gdirectorymonitor.c | 39 ++- gio/gdirectorymonitor.h | 7 + gio/gdrive.c | 40 ++- gio/gdrive.h | 18 + gio/gfile.c | 619 +++++++++++++++++++++++++---------- gio/gfile.h | 149 ++++++++- gio/gfileattribute.c | 255 +++++++++++++-- gio/gfileattribute.h | 54 ++- gio/gfileenumerator.c | 13 + gio/gfileenumerator.h | 11 +- gio/gfileicon.c | 22 +- gio/gfileicon.h | 5 + gio/gfileinfo.c | 373 ++++++++++++++++----- gio/gfileinfo.h | 474 ++++++++++++++++++++++++++- gio/gfileinputstream.c | 73 ++++- gio/gfileinputstream.h | 8 +- gio/gfilemonitor.c | 33 +- gio/gfilemonitor.h | 19 +- gio/gfilenamecompleter.c | 24 +- gio/gfilenamecompleter.h | 6 + gio/gfileoutputstream.c | 92 ++++-- gio/gfileoutputstream.h | 6 + gio/gfilterinputstream.c | 6 + gio/gfilterinputstream.h | 8 +- gio/gfilteroutputstream.c | 6 + gio/gfilteroutputstream.h | 6 + gio/gicon.c | 4 + gio/gicon.h | 16 +- gio/ginputstream.c | 46 ++- gio/ginputstream.h | 6 + gio/gioerror.c | 20 +- gio/gioerror.h | 42 +++ gio/giomodule.c | 18 +- gio/giomodule.h | 20 ++ gio/gioscheduler.c | 14 +- gio/gioscheduler.h | 21 ++ gio/gloadableicon.c | 44 ++- gio/gloadableicon.h | 16 +- gio/glocalfileoutputstream.c | 29 -- gio/gmemoryinputstream.c | 12 +- gio/gmemoryinputstream.h | 5 + gio/gmemoryoutputstream.c | 10 + gio/gmemoryoutputstream.h | 6 + gio/gmountoperation.c | 118 +++++-- gio/gmountoperation.h | 33 +- gio/goutputstream.c | 78 +++-- gio/goutputstream.h | 18 + gio/gpollfilemonitor.c | 4 +- gio/gseekable.c | 61 +++- gio/gseekable.h | 16 + gio/gsimpleasyncresult.c | 213 ++++++++---- gio/gsimpleasyncresult.h | 14 + gio/gsocketinputstream.c | 19 +- gio/gsocketinputstream.h | 6 + gio/gsocketoutputstream.c | 17 +- gio/gsocketoutputstream.h | 6 + gio/gthemedicon.c | 28 +- gio/gthemedicon.h | 5 + gio/gunixdrive.c | 1 - gio/gunixmounts.c | 120 +++++-- gio/gunixmounts.h | 34 ++ gio/gunixvolume.c | 1 - gio/gunixvolumemonitor.c | 1 - gio/gurifuncs.c | 42 ++- gio/gurifuncs.h | 29 ++ gio/gvfs.c | 46 ++- gio/gvfs.h | 7 +- gio/gvolume.c | 99 ++++-- gio/gvolume.h | 22 ++ gio/gvolumemonitor.c | 54 ++- gio/gvolumemonitor.h | 10 +- 88 files changed, 3708 insertions(+), 747 deletions(-) diff --git a/gio/ChangeLog b/gio/ChangeLog index cdd4a761f..0bd45400b 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,96 @@ +2007-11-27 Andrew Walton + * gappinfo.c: + * gappinfo.h: + * gasynchelper.c: + * gasyncresult.c: + * gasyncresult.h: + * gbufferedinputstream.c: + * gbufferedinputstream.h: + * gbufferedoutputstream.c: + * gbufferedoutputstream.h: + * gcancellable.c: + * gcancellable.h: + * gcontenttype.c: + * gdatainputstream.c: + * gdatainputstream.h: + * gdataoutputstream.c: + * gdataoutputstream.h: + * gdirectorymonitor.c: + * gdirectorymonitor.h: + * gdrive.c: + * gdrive.h: + * gfile.c: + * gfile.h: + * gfileattribute.c: + * gfileattribute.h: + * gfileenumerator.c: + * gfileenumerator.h: + * gfileicon.c: + * gfileicon.h: + * gfileinfo.c: + * gfileinfo.h: + * gfileinputstream.c: + * gfileinputstream.h: + * gfilemonitor.c: + * gfilemonitor.h: + * gfilenamecompleter.c: + * gfilenamecompleter.h: + * gfileoutputstream.c: + * gfileoutputstream.h: + * gfilterinputstream.c: + * gfilterinputstream.h: + * gfilteroutputstream.c: + * gfilteroutputstream.h: + * gicon.c: + * gicon.h: + * ginputstream.c: + * ginputstream.h: + * gioerror.c: + * gioerror.h: + * giomodule.c: + * giomodule.h: + * gioscheduler.c: + * gioscheduler.h: + * gloadableicon.c: + * gloadableicon.h: + * glocalfileoutputstream.c: + * gmemoryinputstream.c: + * gmemoryinputstream.h: + * gmemoryoutputstream.c: + * gmemoryoutputstream.h: + * gmountoperation.c: + * gmountoperation.h: + * goutputstream.c: + * goutputstream.h: + * gpollfilemonitor.c: + * gseekable.c: + * gseekable.h: + * gsimpleasyncresult.c: + * gsimpleasyncresult.h: + * gsocketinputstream.c: + * gsocketinputstream.h: + * gsocketoutputstream.c: + * gsocketoutputstream.h: + * gthemedicon.c: + * gthemedicon.h: + * gunixdrive.c: + * gunixmounts.c: + * gunixmounts.h: + * gunixvolume.c: + * gunixvolumemonitor.c: + * gurifuncs.c: + * gurifuncs.h: + * gvfs.c: + * gvfs.h: + * gvolume.c: + * gvolume.h: + * gvolumemonitor.c: + * gvolumemonitor.h: + Bumps documentation to 93% symbol coverage, touching most + of the public files. Fixes broken function documentation prototypes. + Fixes GCancellable inaccuracies. Removes unnecessary incomplete + gtk-doc headers in private files. + 2007-11-27 Jürg Billeter * gbufferedinputstream.c: (g_buffered_input_stream_peek_buffer), diff --git a/gio/gappinfo.c b/gio/gappinfo.c index 922d70072..eb26f6bbc 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -25,6 +25,17 @@ #include "glibintl.h" #include +/** + * SECTION:gappinfo + * @short_description: Application information and launch contexts. + * @stability: Unstable + * + * #GAppInfo and #GAppLaunchContext are used for describing and launching + * installed system applications. + * + * @Note: These may/will be moved to Gtk+ in the future. + * + **/ static void g_app_info_base_init (gpointer g_class); static void g_app_info_class_init (gpointer g_class, @@ -76,6 +87,8 @@ g_app_info_base_init (gpointer g_class) /** * g_app_info_dup: * @appinfo: a #GAppInfo. + * + * Creates a duplicate of a #GAppInfo. * * Returns: a duplicate of @appinfo. **/ @@ -95,9 +108,10 @@ g_app_info_dup (GAppInfo *appinfo) * g_app_info_equal: * @appinfo1: the first #GAppInfo. * @appinfo2: the second #GAppInfo. + * + * Checks if two #GAppInfos are equal. * * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. - * **/ gboolean g_app_info_equal (GAppInfo *appinfo1, @@ -119,8 +133,10 @@ g_app_info_equal (GAppInfo *appinfo1, /** * g_app_info_get_id: * @appinfo: a #GAppInfo. + * + * Gets the ID of an application. * - * Returns: + * Returns: a string containing the application's ID. **/ const char * g_app_info_get_id (GAppInfo *appinfo) @@ -137,6 +153,8 @@ g_app_info_get_id (GAppInfo *appinfo) /** * g_app_info_get_name: * @appinfo: a #GAppInfo. + * + * Gets the installed name of the application. * * Returns: the name of the application for @appinfo. **/ @@ -155,10 +173,12 @@ g_app_info_get_name (GAppInfo *appinfo) /** * g_app_info_get_description: * @appinfo: a #GAppInfo. + * + * 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 when no longer needed. + * application @appinfo. The returned string should be not freed + * when no longer needed. **/ const char * g_app_info_get_description (GAppInfo *appinfo) @@ -175,6 +195,8 @@ g_app_info_get_description (GAppInfo *appinfo) /** * g_app_info_get_executable: * @appinfo: a #GAppInfo. + * + * Gets the executable's name for the installed application. * * Returns: a string containing the @appinfo's application * binary's name. @@ -197,6 +219,8 @@ g_app_info_get_executable (GAppInfo *appinfo) * @appinfo: a #GAppInfo. * @content_type: the content type. * @error: a #GError. + * + * Sets an 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, @@ -223,6 +247,8 @@ g_app_info_set_as_default_for_type (GAppInfo *appinfo, * @appinfo: a #GAppInfo. * @extension: a string containing the file extension. * @error: a #GError. + * + * Sets an 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, @@ -253,6 +279,9 @@ g_app_info_set_as_default_for_extension (GAppInfo *appinfo, * @appinfo: a #GAppInfo. * @content_type: a string. * @error: a #GError. + * + * 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. @@ -280,6 +309,8 @@ g_app_info_add_supports_type (GAppInfo *appinfo, /** * g_app_info_can_remove_support_type: * @appinfo: a #GAppInfo. + * + * Checks if a supported content type can be removed from an application. * * Returns: %TRUE if it is possible to remove supported * content types from a given @appinfo, %FALSE if not. @@ -306,6 +337,8 @@ g_app_info_can_remove_supports_type (GAppInfo *appinfo) * @content_type: a string. * @error: a #GError. * + * Removes a supported type from an application, if possible. + * * Returns: %TRUE if @content_type support was removed * from @appinfo. %FALSE if not. **/ @@ -332,6 +365,8 @@ g_app_info_remove_supports_type (GAppInfo *appinfo, /** * g_app_info_get_icon: * @appinfo: a #GAppInfo. + * + * Gets the default icon for the application. * * Returns: the default #GIcon for @appinfo. **/ @@ -354,8 +389,12 @@ g_app_info_get_icon (GAppInfo *appinfo) * @files: a #GList of #GFile objects. * @launch_context: a #GAppLaunchContext. * @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. * - * Returns: %TRUE on successful launch. + * Returns: %TRUE on successful launch, %FALSE otherwise. **/ gboolean g_app_info_launch (GAppInfo *appinfo, @@ -376,6 +415,8 @@ g_app_info_launch (GAppInfo *appinfo, /** * g_app_info_supports_uris: * @appinfo: a #GAppInfo. + * + * Checks if the application supports reading files and directories from URIs. * * Returns: %TRUE if the @appinfo supports URIs. **/ @@ -398,9 +439,12 @@ g_app_info_supports_uris (GAppInfo *appinfo) * @uris: a #GList containing URIs to launch. * @launch_context: a #GAppLaunchContext. * @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. * - * Returns: %TRUE if the @appinfo was launched - * with the given @uris. + * Returns: %TRUE if the @appinfo was launched successfully, %FALSE otherwise. **/ gboolean g_app_info_launch_uris (GAppInfo *appinfo, @@ -423,8 +467,10 @@ g_app_info_launch_uris (GAppInfo *appinfo, * @appinfo: a #GAppInfo. * @desktop_env: a string. * - * Returns: %TRUE if the @GAppInfo should be shown, - * %FALSE otherwise. + * Checks if the application info should be shown when listing + * applications available. + * + * Returns: %TRUE if the @appinfo should be shown, %FALSE otherwise. **/ gboolean g_app_info_should_show (GAppInfo *appinfo, @@ -443,8 +489,10 @@ G_DEFINE_TYPE (GAppLaunchContext, g_app_launch_context, G_TYPE_OBJECT); /** * g_app_launch_context_new: + * + * Creates a new application launch context. * - * Returns: A new #GAppLaunchContext. + * Returns: a #GAppLaunchContext. **/ GAppLaunchContext * g_app_launch_context_new (void) @@ -468,6 +516,11 @@ g_app_launch_context_init (GAppLaunchContext *launch_context) * @info: a #GAppInfo. * @files: a #GList of files. * + * Gets the DISPLAY for a launched application. + * TODO: can't find an implementation. DISPLAY as in X atom "DISPLAY"? + * Environmental variable "DISPLAY"? + * + * Returns: a display string. **/ char * g_app_launch_context_get_display (GAppLaunchContext *context, @@ -487,12 +540,18 @@ 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. + * Startup notification IDs are defined in the FreeDesktop.Org Startup Notifications standard, + * at . * + * Returns: a startup notifaction ID for the application, or %NULL if not supported. **/ char * g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context, @@ -514,10 +573,12 @@ g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context, /** - * g_app_launch_context_get_startup_notify_id: + * g_app_launch_context_launch_failed: * @context: a #GAppLaunchContext. - * @startup_notify_id: a string containing the startup ID of the application. + * @startup_notify_id: a string containing the DESKTOP_STARTUP_ID of the launched application. * + * TODO: what does this do? Can't find it implemented anywhere. + * **/ void g_app_launch_context_launch_failed (GAppLaunchContext *context, diff --git a/gio/gappinfo.h b/gio/gappinfo.h index 0a88349d4..4e42685f9 100644 --- a/gio/gappinfo.h +++ b/gio/gappinfo.h @@ -40,6 +40,13 @@ G_BEGIN_DECLS #define G_IS_APP_LAUNCH_CONTEXT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_APP_LAUNCH_CONTEXT)) #define G_APP_LAUNCH_CONTEXT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_APP_LAUNCH_CONTEXT, GAppLaunchContextClass)) +/** + * GAppInfoCreateFlags: + * @G_APP_INFO_CREATE_FLAGS_NONE: No flags. + * @G_APP_INFO_CREATE_NEEDS_TERMINAL: Application opens with a terminal window. + * + * Flags used when creating a #GAppInfo. + */ typedef enum { G_APP_INFO_CREATE_FLAGS_NONE = 0, G_APP_INFO_CREATE_NEEDS_TERMINAL = (1<<0) @@ -49,7 +56,38 @@ typedef struct _GAppLaunchContext GAppLaunchContext; typedef struct _GAppLaunchContextClass GAppLaunchContextClass; typedef struct _GAppLaunchContextPrivate GAppLaunchContextPrivate; +/** + * GAppInfo: + * + * Information about an installed application. + */ typedef struct _GAppInfo GAppInfo; /* Dummy typedef */ + +/** + * GAppInfoIface: + * @g_iface: The parent interface. + * @dup: Copies a #GAppInfo. + * @equal: Checks two #GAppInfos for equality. + * @get_id: Gets a string identifier for a #GAppInfo. + * @get_name: Gets the name of the application for a #GAppInfo. + * @get_description: Gets a short description for the application described by the #GAppInfo. + * @get_executable: Gets the execuable name for the #GAppInfo. + * @get_icon: Gets the #GIcon for the #GAppInfo. + * @launch: Launches an application specified by the #GAppInfo. + * @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. + * @set_as_default_for_extension: Sets an application as default for a given file extention. + * @add_supports_type: Adds to the #GAppInfo information about supported file types. + * @can_remove_supports_type: Checks for support for removing supported file types from a #GAppInfo. + * @remove_supports_type: Removes a supported application type from a #GAppInfo. + * + * Application Information interface, for operating system portability. + */ typedef struct _GAppInfoIface GAppInfoIface; struct _GAppInfoIface @@ -94,7 +132,7 @@ 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); @@ -162,11 +200,17 @@ GAppInfo *g_app_info_get_default_for_uri_scheme (const char *uri_scheme); 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. + */ struct _GAppLaunchContext { GObject parent_instance; + /*< private >*/ GAppLaunchContextPrivate *priv; }; diff --git a/gio/gasynchelper.c b/gio/gasynchelper.c index b6a9352c7..98bce1b48 100644 --- a/gio/gasynchelper.c +++ b/gio/gasynchelper.c @@ -24,6 +24,15 @@ #include "gasynchelper.h" +/** + * SECTION:gasynchelper + * @short_description: Asynchronous Helper Functions + * @see_also: #GAsyncReady. + * + * Provides helper functions for asynchronous operations. + * + **/ + static void async_result_free (gpointer data) { diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c index 840931976..9d698a599 100644 --- a/gio/gasyncresult.c +++ b/gio/gasyncresult.c @@ -24,6 +24,65 @@ #include "gasyncresult.h" #include "glibintl.h" +/** + * SECTION:gasyncresult + * @short_description: Asynchronous Function Results + * @see_also: #GSimpleAsyncResult + * + * Provides a base class for implementing asynchronous function results. + * + * Asynchronous operations are broken up into two separate operations + * which are chained together by a #GAsyncReadyCallback. To begin + * an asynchronous operation, provide a #GAsyncReadyCallback to the asynchronous + * function. This callback will be triggered when the operation has completed, + * and will be passed a #GAsyncReady instance filled with the details of the operation's + * success or failure, the object the asynchronous function was + * started for and any error codes returned. The asynchronous callback function + * is then expected to call the corresponding "_finish()" operation with the + * object the function was called for, and the #GAsyncReady instance, and optionally, + * an @error to grab any error conditions that may have occurred. + * + * Example of a typical asynchronous operation flow: + * + * + * void _theoretical_frobnitz_async (Theoretical *t, + * GCancellable *c, + * GAsyncReadyCallback *cb, + * gpointer u); + * + * gboolean _theoretical_frobnitz_finish (Theoretical *t, + * GAsyncResult *res, + * GError **e); + * + * static void + * frobnitz_result_func (GObject *source_object, + * GAsyncResult *res, + * gpointer user_data) + * { + * gboolean success = FALSE; + * success = _theoretical_frobnitz_finish( source_object, res, NULL ); + * if (success) + * g_printf("Hurray!/n"); + * else + * g_printf("Uh oh!/n"); + * /* ... */ + * g_free(res); + * } + * + * int main (int argc, void *argv[]) + * { + * /* ... */ + * _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL); + * + * /* ... */ + * + * + * + * Asynchronous jobs are threaded if #GThread is available, but also may + * be sent to the Main Event Loop and processed in an idle function. + * + **/ + static void g_async_result_base_init (gpointer g_class); static void g_async_result_class_init (gpointer g_class, gpointer class_data); @@ -73,8 +132,9 @@ g_async_result_base_init (gpointer g_class) * g_async_result_get_user_data: * @res: a #GAsyncResult. * - * Returns: the user data for the given @res, or - * %NULL on failure. + * Gets the user data from a #GAsyncResult. + * + * Returns: the user data for @res. **/ gpointer g_async_result_get_user_data (GAsyncResult *res) @@ -92,6 +152,8 @@ g_async_result_get_user_data (GAsyncResult *res) * g_async_result_get_source_object: * @res: a #GAsyncResult. * + * Gets the source object from a #GAsyncResult. + * * Returns: the source object for the @res. **/ GObject * diff --git a/gio/gasyncresult.h b/gio/gasyncresult.h index 26f867e02..123c20a7b 100644 --- a/gio/gasyncresult.h +++ b/gio/gasyncresult.h @@ -32,13 +32,36 @@ G_BEGIN_DECLS #define G_IS_ASYNC_RESULT(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT)) #define G_ASYNC_RESULT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface)) +/** + * GAsyncResult: + * + * Holds results information for an asynchronous operation, + * usually passed directly to a asynchronous _finish() operation. + **/ typedef struct _GAsyncResult GAsyncResult; /* Dummy typedef */ typedef struct _GAsyncResultIface GAsyncResultIface; +/** + * GAsyncReadyCallback: + * @source_object: the object the asynchronous operation was started with. + * @res: a #GAsyncResult. + * @user_data: user data passed to the callback. + * + * Type definition for a function that will be called back when an asynchronous + * operation within GIO has been completed. + **/ typedef void (*GAsyncReadyCallback) (GObject *source_object, GAsyncResult *res, gpointer user_data); +/** + * GAsyncResultIface: + * @g_iface: The parent interface. + * @get_user_data: Gets the user data passed to the callback. + * @get_source_object: Gets the source object that issued the asynchronous operation. + * + * Interface definition for #GAsyncResult. + **/ struct _GAsyncResultIface { GTypeInterface g_iface; diff --git a/gio/gbufferedinputstream.c b/gio/gbufferedinputstream.c index dfd6c2ea5..1c7d377ef 100644 --- a/gio/gbufferedinputstream.c +++ b/gio/gbufferedinputstream.c @@ -22,14 +22,35 @@ */ #include - #include "gbufferedinputstream.h" #include "ginputstream.h" #include "gsimpleasyncresult.h" #include - #include "glibintl.h" +/** + * SECTION:gbufferedinputstream + * @short_description: Buffered Input Stream + * @see_also: #GFilterInputStream, #GInputStream. + * + * Buffered input stream implements #GFilterInputStream and provides + * for buffered reads. + * + * By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. + * + * To create a buffered input stream, use g_buffered_input_stream_new(), or + * g_buffered_input_stream_new_sized() to specify the buffer's size at construction. + * + * To get the size of a buffer within a buffered input stream, use + * g_buffered_input_stream_get_buffer_size(). To change the size of a + * buffered input stream's buffer, use g_buffered_input_stream_set_buffer_size(). + * Note: the buffer's size cannot be reduced below the size of the data within the + * buffer. + * + **/ + + + #define DEFAULT_BUFFER_SIZE 4096 struct _GBufferedInputStreamPrivate { @@ -151,7 +172,9 @@ g_buffered_input_stream_class_init (GBufferedInputStreamClass *klass) * g_buffered_input_stream_get_buffer_size: * @stream: #GBufferedInputStream. * - * Returns: the current buffer size, or -1 on error. + * Gets the size of the input buffer. + * + * Returns: the current buffer size, or %-1 on error. **/ gsize g_buffered_input_stream_get_buffer_size (GBufferedInputStream *stream) @@ -496,14 +519,14 @@ g_buffered_input_stream_fill_async (GBufferedInputStream *stream, } /** - * g_buffered_input_stream_fill_finished: + * g_buffered_input_stream_fill_finish: * @stream: a #GBufferedInputStream. * @result: a #GAsyncResult. * @error: a #GError. * * Finishes an asynchronous read. * - * Returns: a #gssize of the read stream, or -1 on an error. + * Returns: a #gssize of the read stream, or %-1 on an error. **/ gssize g_buffered_input_stream_fill_finish (GBufferedInputStream *stream, @@ -535,6 +558,8 @@ g_buffered_input_stream_fill_finish (GBufferedInputStream *stream, * g_buffered_input_stream_get_available: * @stream: #GBufferedInputStream. * + * Gets the size of the available data within the stream. + * * Returns: size of the available stream. **/ gsize @@ -552,7 +577,10 @@ g_buffered_input_stream_get_available (GBufferedInputStream *stream) * @offset: a #gsize. * @count: a #gsize. * - * Returns: + * Peeks in the buffer, copying data of size @count into @buffer, offset + * @offset bytes. + * + * Returns: a #gsize of the number of bytes peeked, or %-1 on error. **/ gsize g_buffered_input_stream_peek (GBufferedInputStream *stream, diff --git a/gio/gbufferedinputstream.h b/gio/gbufferedinputstream.h index fcf9cb405..cac5d186c 100644 --- a/gio/gbufferedinputstream.h +++ b/gio/gbufferedinputstream.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_BUFFERED_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_INPUT_STREAM)) #define G_BUFFERED_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_INPUT_STREAM, GBufferedInputStreamClass)) +/** + * GBufferedInputStream: + * + * Implements #GFilterInputStream with a sized input buffer. + **/ typedef struct _GBufferedInputStream GBufferedInputStream; typedef struct _GBufferedInputStreamClass GBufferedInputStreamClass; typedef struct _GBufferedInputStreamPrivate GBufferedInputStreamPrivate; @@ -67,6 +72,7 @@ struct _GBufferedInputStreamClass GAsyncResult *result, GError **error); + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gbufferedoutputstream.c b/gio/gbufferedoutputstream.c index 210ccfb0d..c924425cb 100644 --- a/gio/gbufferedoutputstream.c +++ b/gio/gbufferedoutputstream.c @@ -21,14 +21,35 @@ */ #include - #include "gbufferedoutputstream.h" #include "goutputstream.h" #include "gsimpleasyncresult.h" #include "string.h" - #include "glibintl.h" +/** + * SECTION:gbufferedoutputstream + * @short_description: Buffered Output Stream + * @see_also: #GFilterOutputStream, #GOutputStream. + * + * Buffered output stream implements #GFilterOutputStream and provides + * for buffered writes. + * + * By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. + * + * To create a buffered output stream, use g_buffered_output_stream_new(), or + * g_buffered_output_stream_new_sized() to specify the buffer's size at construction. + * + * To get the size of a buffer within a buffered input stream, use + * g_buffered_output_stream_get_buffer_size(). To change the size of a + * buffered output stream's buffer, use g_buffered_output_stream_set_buffer_size(). + * Note: the buffer's size cannot be reduced below the size of the data within the + * buffer. + * + **/ + + + #define DEFAULT_BUFFER_SIZE 4096 struct _GBufferedOutputStreamPrivate { @@ -140,6 +161,8 @@ g_buffered_output_stream_class_init (GBufferedOutputStreamClass *klass) * g_buffered_output_stream_get_buffer_size: * @stream: a #GBufferedOutputStream. * + * Gets the size of the buffer in the @stream. + * * Returns: the current size of the buffer. **/ gsize @@ -156,7 +179,6 @@ g_buffered_output_stream_get_buffer_size (GBufferedOutputStream *stream) * @size: a #gsize. * * Sets the size of the internal buffer to @size. - * **/ void g_buffered_output_stream_set_buffer_size (GBufferedOutputStream *stream, @@ -192,6 +214,8 @@ g_buffered_output_stream_set_buffer_size (GBufferedOutputStream *stream, * g_buffered_output_stream_get_auto_grow: * @stream: a #GBufferedOutputStream. * + * Checks if the buffer automatically grows as data is added. + * * Returns: %TRUE if the @stream's buffer automatically grows, * %FALSE otherwise. **/ @@ -206,10 +230,9 @@ g_buffered_output_stream_get_auto_grow (GBufferedOutputStream *stream) /** * g_buffered_output_stream_set_auto_grow: * @stream: a #GBufferedOutputStream. - * @auto_grow: a boolean. + * @auto_grow: a #gboolean. * * Sets whether or not the @stream's buffer should automatically grow. - * **/ void g_buffered_output_stream_set_auto_grow (GBufferedOutputStream *stream, @@ -300,6 +323,8 @@ g_buffered_output_stream_init (GBufferedOutputStream *stream) * g_buffered_output_stream_new: * @base_stream: a #GOutputStream. * + * Creates a new buffered output stream for a base stream. + * * Returns: a #GOutputStream for the given @base_stream. **/ GOutputStream * @@ -321,6 +346,8 @@ g_buffered_output_stream_new (GOutputStream *base_stream) * @base_stream: a #GOutputStream. * @size: a #gsize. * + * Creates a new buffered output stream with a given buffer size. + * * Returns: a #GOutputStream with an internal buffer set to @size. **/ GOutputStream * diff --git a/gio/gbufferedoutputstream.h b/gio/gbufferedoutputstream.h index 54086448c..816f07e87 100644 --- a/gio/gbufferedoutputstream.h +++ b/gio/gbufferedoutputstream.h @@ -35,6 +35,12 @@ G_BEGIN_DECLS #define G_IS_BUFFERED_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_BUFFERED_OUTPUT_STREAM)) #define G_BUFFERED_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_BUFFERED_OUTPUT_STREAM, GBufferedOutputStreamClass)) +/** + * GBufferedOutputStream: + * @parent_class: The parent class. + * + * An implementation of #GFilterOutputStream with a sized buffer. + **/ typedef struct _GBufferedOutputStream GBufferedOutputStream; typedef struct _GBufferedOutputStreamClass GBufferedOutputStreamClass; typedef struct _GBufferedOutputStreamPrivate GBufferedOutputStreamPrivate; @@ -51,6 +57,7 @@ struct _GBufferedOutputStreamClass { GOutputStreamClass parent_class; + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gcancellable.c b/gio/gcancellable.c index c55737a32..a31420bb2 100644 --- a/gio/gcancellable.c +++ b/gio/gcancellable.c @@ -25,11 +25,14 @@ #include #include #include "gcancellable.h" - #include "glibintl.h" -/* +/** + * SECTION:gcancellable + * @short_description: Thread-safe Operation Cancellation Stack + * @include: gio/gcancellable.h + * * GCancellable is a thread-safe operation cancellation stack used * throughout GIO to allow for cancellation of asynchronous operations. */ @@ -77,6 +80,12 @@ g_cancellable_class_init (GCancellableClass *klass) gobject_class->finalize = g_cancellable_finalize; + /** + * GCancellable::cancelled: + * @cancellable: a #GCancellable. + * + * Emitted when the operation has been cancelled from another thread. + */ signals[CANCELLED] = g_signal_new (I_("cancelled"), G_TYPE_FROM_CLASS (gobject_class), @@ -129,8 +138,10 @@ g_cancellable_init (GCancellable *cancellable) /** * g_cancellable_new: + * + * Creates a new #GCancellable object. * - * Returns: a new #GCancellable object. + * Returns: a #GCancellable. **/ GCancellable * g_cancellable_new (void) @@ -180,6 +191,8 @@ g_pop_current_cancellable (GCancellable *cancellable) /** * g_cancellable_get_current: * + * Gets the top cancellable from the stack. + * * Returns: a #GCancellable from the top of the stack, or %NULL * if the stack is empty. **/ @@ -200,7 +213,6 @@ g_cancellable_get_current (void) * @cancellable: a #GCancellable object. * * Resets @cancellable to its uncancelled state. - * **/ void g_cancellable_reset (GCancellable *cancellable) @@ -223,6 +235,8 @@ g_cancellable_reset (GCancellable *cancellable) * g_cancellable_is_cancelled: * @cancellable: a #GCancellable or NULL. * + * Checks if a cancellable job has been cancelled. + * * Returns: %TRUE if @cancellable is is cancelled, * FALSE if called with %NULL or if item is not cancelled. **/ @@ -261,7 +275,9 @@ g_cancellable_set_error_if_cancelled (GCancellable *cancellable, * g_cancellable_get_fd: * @cancellable: a #GCancellable. * - * Returns: A valid file descriptor. -1 if the file descriptor + * Gets the file descriptor for a cancellable job. + * + * Returns: A valid file descriptor. %-1 if the file descriptor * is not supported, or on errors. **/ int @@ -290,7 +306,6 @@ g_cancellable_get_fd (GCancellable *cancellable) * * Will set @cancellable to cancelled, and will emit the CANCELLED * signal. This function is thread-safe. - * **/ void g_cancellable_cancel (GCancellable *cancellable) diff --git a/gio/gcancellable.h b/gio/gcancellable.h index a6229da4f..be8495f6c 100644 --- a/gio/gcancellable.h +++ b/gio/gcancellable.h @@ -34,6 +34,11 @@ G_BEGIN_DECLS #define G_IS_CANCELLABLE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_CANCELLABLE)) #define G_CANCELLABLE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_CANCELLABLE, GCancellableClass)) +/** + * GCancellable: + * + * Allows actions to be cancelled. + */ typedef struct _GCancellable GCancellable; typedef struct _GCancellableClass GCancellableClass; @@ -42,7 +47,8 @@ struct _GCancellableClass GObjectClass parent_class; void (* cancelled) (GCancellable *cancellable); - + + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gcontenttype.c b/gio/gcontenttype.c index 5952cacdb..c3f2079a5 100644 --- a/gio/gcontenttype.c +++ b/gio/gcontenttype.c @@ -21,20 +21,27 @@ */ #include - #include #include #include #include - #include "gcontenttypeprivate.h" #include "glibintl.h" -/* A content type is a platform specific string that defines the type - of a file. On unix it is a mime type, on win32 it is an extension string - like ".doc", ".txt" or a percieved string like "audio". Such strings - can be looked up in the registry at HKEY_CLASSES_ROOT. -*/ +/* This really sucks. GTK-Doc isn't smart enough to realize there are two + * different versions of the functions within this file, based on the platform. + * I can move the definitions out of this file, but that's ugly. + */ + +/** + * SECTION:gcontenttype + * @short_description: platform specific content typing + * + * A content type is a platform specific string that defines the type + * of a file. On unix it is a mime type, on win32 it is an extension string + * like ".doc", ".txt" or a percieved string like "audio". Such strings + * can be looked up in the registry at HKEY_CLASSES_ROOT. + **/ #ifdef G_OS_WIN32 @@ -112,7 +119,7 @@ g_content_type_equals (const char *type1, /** * g_content_type_is_a: - * @type: a content type string. a content type string. + * @type: a content type string. * @supertype: a string. * * Determines if @type is a subset of @supertype. @@ -144,9 +151,11 @@ g_content_type_is_a (const char *type, /** * g_content_type_is_unknown: - * @type: a content type string. a content type string. + * @type: a content type string. * - * Returns: + * Checks if the content type is known by GIO. + * + * Returns: %TRUE if the type is unknown. **/ gboolean g_content_type_is_unknown (const char *type) @@ -158,7 +167,9 @@ g_content_type_is_unknown (const char *type) /** * g_content_type_get_description: - * @type: a content type string. a content type string. + * @type: a content type string. + * + * Gets the human readable description of the content type. * * Returns: a short description of the content type @type. **/ @@ -187,7 +198,9 @@ g_content_type_get_description (const char *type) /** * g_content_type_get_mime_type: - * @type: a content type string. a content type string. + * @type: a content type string. + * + * Gets the mime-type for the content type. * * Returns: the registered mime-type for the given @type. **/ @@ -212,7 +225,9 @@ g_content_type_get_mime_type (const char *type) /** * g_content_type_get_icon: - * @type: a content type string. a content type string. + * @type: a content type string. + * + * Gets the icon for a content type. * * Returns: #GIcon corresponding to the content type. **/ @@ -235,9 +250,11 @@ g_content_type_get_icon (const char *type) * g_content_type_can_be_executable: * @type: a content type string. * - * Returns: %TRUE if the file type corresponds to something that - * can be executable, %FALSE otherwise. Note that for instance - * things like textfiles can be executables (i.e. scripts) + * Checks if a content type can be executable. Note that for instance + * things like text files can be executables (i.e. scripts and batch files). + * + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. **/ gboolean g_content_type_can_be_executable (const char *type) @@ -273,9 +290,11 @@ looks_like_text (const guchar *data, gsize data_size) * @result_uncertain: a flag indicating the certainty of the * result. * + * Guesses the content type based on example data. If the function is + * uncertain, @result_uncertain will be set to %TRUE. + * * Returns: a string indicating a guessed content type for the - * given data. If the function is uncertain, @result_uncertain - * will be set to %TRUE. + * given data. **/ char * g_content_type_guess (const char *filename, @@ -310,6 +329,9 @@ g_content_type_guess (const char *filename, /** * g_content_types_get_registered: * + * Gets a list of strings containing the registered content types on + * the system. + * * Returns: #GList of the registered content types. **/ GList * diff --git a/gio/gdatainputstream.c b/gio/gdatainputstream.c index a55e53132..06796ec02 100644 --- a/gio/gdatainputstream.c +++ b/gio/gdatainputstream.c @@ -25,6 +25,16 @@ #include "gdatainputstream.h" #include "glibintl.h" +/** + * SECTION:gdatainputstream + * @short_description: Data Input Stream. + * @see_also: #GInputStream. + * + * Data input stream implements #GInputStream and includes functions for + * reading data directly from an input stream. + * + **/ + struct _GDataInputStreamPrivate { GDataStreamByteOrder byte_order; GDataStreamNewlineType newline_type; @@ -116,7 +126,9 @@ g_data_input_stream_init (GDataInputStream *stream) /** * g_data_input_stream_new: - * @base_stream: a given #GInputStream. + * @base_stream: a #GInputStream. + * + * Creates a new data input stream for the @base_stream. * * Returns: a new #GDataInputStream. **/ @@ -156,6 +168,8 @@ g_data_input_stream_set_byte_order (GDataInputStream *stream, * g_data_input_stream_get_byte_order: * @stream: a given #GDataInputStream. * + * Gets the byte order for the data input stream. + * * Returns the @stream's current #GDataStreamByteOrder. **/ GDataStreamByteOrder @@ -168,7 +182,7 @@ g_data_input_stream_get_byte_order (GDataInputStream *stream) /** * g_data_input_stream_set_newline_type: - * @stream: a given #GDataInputStream. + * @stream: a #GDataInputStream. * @type: the type of new line return as #GDataStreamNewlineType. * * Sets the newline type for the @stream. @@ -248,7 +262,6 @@ read_data (GDataInputStream *stream, * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 * if an error occured. **/ - guchar g_data_input_stream_read_byte (GDataInputStream *stream, GCancellable *cancellable, @@ -357,6 +370,10 @@ g_data_input_stream_read_uint16 (GDataInputStream *stream, * * In order to get the correct byte order for this read operation, * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order(). + * + * 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 signed 32-bit/4-byte value read from the @stream or %0 if * an error occured. @@ -399,6 +416,10 @@ g_data_input_stream_read_int32 (GDataInputStream *stream, * * In order to get the correct byte order for this read operation, * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order(). + * + * 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 an unsigned 32-bit/4-byte value read from the @stream or %0 if * an error occured. @@ -441,6 +462,10 @@ g_data_input_stream_read_uint32 (GDataInputStream *stream, * * In order to get the correct byte order for this read operation, * see g_data_stream_get_byte_order() and g_data_stream_set_byte_order(). + * + * 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 signed 64-bit/8-byte value read from @stream or %0 if * an error occured. @@ -483,6 +508,10 @@ g_data_input_stream_read_int64 (GDataInputStream *stream, * * In order to get the correct byte order for this read operation, * see g_data_stream_get_byte_order(). + * + * 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 an unsigned 64-bit/8-byte read from @stream or %0 if * an error occured. @@ -621,10 +650,15 @@ scan_for_newline (GDataInputStream *stream, * @length: a #gsize to get the length of the data read in. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: #GError for error reporting. + * + * Reads a line from the data input stream. + * + * 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 string with the line that was read in. Set @length to - * a #gsize to get the length of the read line. This function will - * return %NULL on an error. + * 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 d68be6c45..a096b1b6f 100644 --- a/gio/gdatainputstream.h +++ b/gio/gdatainputstream.h @@ -35,6 +35,13 @@ G_BEGIN_DECLS #define G_IS_DATA_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_INPUT_STREAM)) #define G_DATA_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_INPUT_STREAM, GDataInputStreamClass)) +/** + * GDataInputStream: + * @parent: a #GBufferedInputStream. + * + * An implementation of #GBufferedInputStream that allows for high-level + * data manipulation of arbitrary data (including binary operations). + **/ typedef struct _GDataInputStream GDataInputStream; typedef struct _GDataInputStreamClass GDataInputStreamClass; typedef struct _GDataInputStreamPrivate GDataInputStreamPrivate; @@ -50,7 +57,7 @@ struct _GDataInputStream struct _GDataInputStreamClass { GBufferedInputStreamClass parent_class; - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); @@ -59,12 +66,31 @@ struct _GDataInputStreamClass void (*_g_reserved5) (void); }; +/** + * GDataStreamByteOrder: + * @G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN: Selects Big Endian byte order. + * @G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN: Selects Little Endian byte order. + * @G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN: Selects endianness based on host machine's architecture. + * + * #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources + * across various machine architectures. + * + **/ typedef enum { G_DATA_STREAM_BYTE_ORDER_BIG_ENDIAN, G_DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN, G_DATA_STREAM_BYTE_ORDER_HOST_ENDIAN } GDataStreamByteOrder; +/** + * GDataStreamNewlineType: + * @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. + * + * #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. + **/ typedef enum { G_DATA_STREAM_NEWLINE_TYPE_LF, G_DATA_STREAM_NEWLINE_TYPE_CR, diff --git a/gio/gdataoutputstream.c b/gio/gdataoutputstream.c index 6393d7c82..40f0e7290 100644 --- a/gio/gdataoutputstream.c +++ b/gio/gdataoutputstream.c @@ -25,6 +25,18 @@ #include "gdataoutputstream.h" #include "glibintl.h" +/** + * SECTION:gdataoutputstream + * @short_description: Data Output Stream. + * @see_also: #GOutputStream. + * + * Data output stream implements #GOutputStream and includes functions for + * writing data directly to an output stream. + * + **/ + + + struct _GDataOutputStreamPrivate { GDataStreamByteOrder byte_order; }; @@ -116,6 +128,8 @@ g_data_output_stream_init (GDataOutputStream *stream) * g_data_output_stream_new: * @base_stream: a #GOutputStream. * + * Creates a new data output stream for @base_stream. + * * Returns: #GDataOutputStream. **/ GDataOutputStream * @@ -134,9 +148,11 @@ g_data_output_stream_new (GOutputStream *base_stream) /** * g_data_output_stream_set_byte_order: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @order: a %GDataStreamByteOrder. * + * Sets the byte order of the data output stream to @order. + * **/ void g_data_output_stream_set_byte_order (GDataOutputStream *stream, @@ -149,9 +165,11 @@ g_data_output_stream_set_byte_order (GDataOutputStream *stream, /** * g_data_output_stream_get_byte_order: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * - * Returns: the %GDataStreamByteOrder for the @stream. + * Gets the byte order for the stream. + * + * Returns: the #GDataStreamByteOrder for the @stream. **/ GDataStreamByteOrder g_data_output_stream_get_byte_order (GDataOutputStream *stream) @@ -166,7 +184,9 @@ g_data_output_stream_get_byte_order (GDataOutputStream *stream) * @data_stream: a #GDataOutputStream. * @data: a #guchar. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts a byte into the output stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -188,10 +208,12 @@ g_data_output_stream_put_byte (GDataOutputStream *data_stream, /** * g_data_output_stream_put_int16: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #gint16. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 16-bit integer into the output stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -226,10 +248,12 @@ g_data_output_stream_put_int16 (GDataOutputStream *stream, /** * g_data_output_stream_put_uint16: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #guint16. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 16-bit integer into the output stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -264,10 +288,12 @@ g_data_output_stream_put_uint16 (GDataOutputStream *stream, /** * g_data_output_stream_put_int32: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #gint32. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 32-bit integer into the output stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -302,10 +328,12 @@ g_data_output_stream_put_int32 (GDataOutputStream *stream, /** * g_data_output_stream_put_uint32: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #guint32. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 32-bit integer into the stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -340,10 +368,12 @@ g_data_output_stream_put_uint32 (GDataOutputStream *stream, /** * g_data_output_stream_put_int64: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #gint64. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts a signed 64-bit integer into the stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -378,10 +408,12 @@ g_data_output_stream_put_int64 (GDataOutputStream *stream, /** * g_data_output_stream_put_uint64: - * @stream: a #GDataOutputStream. a #GDataOutputStream. + * @stream: a #GDataOutputStream. * @data: a #guint64. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. + * + * Puts an unsigned 64-bit integer into the stream. * * Returns: %TRUE if @data was successfully added to the @stream. **/ @@ -419,9 +451,11 @@ g_data_output_stream_put_uint64 (GDataOutputStream *stream, * @stream: a #GDataOutputStream. * @str: a string. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError. + * @error: a #GError, %NULL to ignore. * - * Returns: %TRUE if @data was successfully added to the @stream. + * Puts a string into the output stream. + * + * Returns: %TRUE if @string was successfully added to the @stream. **/ gboolean g_data_output_stream_put_string (GDataOutputStream *stream, diff --git a/gio/gdataoutputstream.h b/gio/gdataoutputstream.h index 94bdfa5c2..00b8cf2a4 100644 --- a/gio/gdataoutputstream.h +++ b/gio/gdataoutputstream.h @@ -36,6 +36,13 @@ G_BEGIN_DECLS #define G_IS_DATA_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_DATA_OUTPUT_STREAM)) #define G_DATA_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_DATA_OUTPUT_STREAM, GDataOutputStreamClass)) +/** + * GDataOutputStream: + * @parent: a #GBufferedOutputStream. + * + * An implementation of #GBufferedOutputStream that allows for high-level + * data manipulation of arbitrary data (including binary operations). + **/ typedef struct _GDataOutputStream GDataOutputStream; typedef struct _GDataOutputStreamClass GDataOutputStreamClass; typedef struct _GDataOutputStreamPrivate GDataOutputStreamPrivate; @@ -51,7 +58,7 @@ struct _GDataOutputStream struct _GDataOutputStreamClass { GFilterOutputStreamClass parent_class; - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gdirectorymonitor.c b/gio/gdirectorymonitor.c index eb50a958c..c0517c68e 100644 --- a/gio/gdirectorymonitor.c +++ b/gio/gdirectorymonitor.c @@ -29,6 +29,15 @@ #include "gvfs.h" #include "glibintl.h" +/** + * SECTION:gdirectorymonitor + * @short_description: Directory Monitor + * @see_also: #GFileMonitor. + * + * Monitors a directory for changes. + * + **/ + enum { CHANGED, LAST_SIGNAL @@ -146,9 +155,11 @@ g_directory_monitor_init (GDirectoryMonitor *monitor) /** * g_directory_monitor_cancel: - * @monitor: + * @monitor: a #GDirectoryMonitor. + * + * Cancels the monitoring activity on @monitor. * - * Returns: + * Returns: %TRUE if the monitor was cancelled successfully. %FALSE otherwise. **/ gboolean g_directory_monitor_cancel (GDirectoryMonitor* monitor) @@ -168,8 +179,10 @@ g_directory_monitor_cancel (GDirectoryMonitor* monitor) /** * g_directory_monitor_set_rate_limit: - * @monitor: - * @limit_msecs: + * @monitor: a #GDirectoryMonitor. + * @limit_msecs: an integer to set the limit of the directory monitor in milliseconds. + * + * Sets the limit of the directory monitor to watch for changes every @limit_msecs milliseconds. * **/ void @@ -183,9 +196,11 @@ g_directory_monitor_set_rate_limit (GDirectoryMonitor *monitor, /** * g_directory_monitor_is_cancelled: - * @monitor: + * @monitor: a #GDirectoryMonitor. * - * Returns: + * Checks whether @monitor is cancelled. + * + * Returns: %TRUE if the monitor on the directory was cancelled. %FALSE otherwise. **/ gboolean g_directory_monitor_is_cancelled (GDirectoryMonitor *monitor) @@ -394,10 +409,14 @@ update_rate_limiter_timeout (GDirectoryMonitor *monitor, guint new_time) /** * g_directory_monitor_emit_event: - * @monitor: - * @child: - * @other_file: - * @event_type: + * @monitor: a #GDirectoryMonitor. + * @child: a #GFile. + * @other_file: a #GFile. + * @event_type: a set of #GFileMonitorEvent flags. + * + * Emits the GDirectoryMonitor::changed signal if a change + * has taken place. Should be called from directory monitor + * implementations only. * **/ void diff --git a/gio/gdirectorymonitor.h b/gio/gdirectorymonitor.h index d4e357307..709c006a8 100644 --- a/gio/gdirectorymonitor.h +++ b/gio/gdirectorymonitor.h @@ -39,6 +39,12 @@ G_BEGIN_DECLS typedef struct _GDirectoryMonitorClass GDirectoryMonitorClass; typedef struct _GDirectoryMonitorPrivate GDirectoryMonitorPrivate; +/** + * GDirectoryMonitor: + * @parent: The parent class. + * + * Implements a monitor on the given #GFile that points to a directory. + **/ struct _GDirectoryMonitor { GObject parent; @@ -60,6 +66,7 @@ struct _GDirectoryMonitorClass /* Virtual Table */ gboolean (*cancel)(GDirectoryMonitor* monitor); + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gdrive.c b/gio/gdrive.c index b953c2c88..26ec192c5 100644 --- a/gio/gdrive.c +++ b/gio/gdrive.c @@ -25,6 +25,16 @@ #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:gdrive + * @short_description: Virtual File System drive management. + * @include: gio/gdrive.h + * + * #GDrive manages drive operations from GVFS, including volume mounting + * and ejecting, and getting the drive's name and icon. + * + **/ + static void g_drive_base_init (gpointer g_class); static void g_drive_class_init (gpointer g_class, gpointer class_data); @@ -72,6 +82,13 @@ g_drive_base_init (gpointer g_class) if (! initialized) { + /** + * GDrive::changed: + * @volume: a #GVolume. + * + * Emitted when the drive's state has changed. + * + **/ g_signal_new (I_("changed"), G_TYPE_DRIVE, G_SIGNAL_RUN_LAST, @@ -90,7 +107,7 @@ g_drive_base_init (gpointer g_class) * * Returns: string containing @drive's name. * - * The returned string should be freed when no longer needed + * The returned string should be freed when no longer needed. **/ char * g_drive_get_name (GDrive *drive) @@ -128,6 +145,8 @@ g_drive_get_icon (GDrive *drive) * g_drive_has_volumes: * @drive: a #GDrive. * + * Checks if a drive has any volumes. + * * Returns: %TRUE if @drive contains volumes, %FALSE otherwise. **/ gboolean @@ -146,7 +165,9 @@ g_drive_has_volumes (GDrive *drive) * g_drive_get_volumes: * @drive: a #GDrive. * - * Returns: #GList containing any #GVolume s on the given @drive. + * Gets a list of volumes for a drive. + * + * Returns: #GList containing any #GVolumes on the given @drive. * NOTE: Fact-check this. **/ GList * @@ -165,6 +186,8 @@ g_drive_get_volumes (GDrive *drive) * g_drive_is_automounted: * @drive: a #GDrive. * + * Checks if a drive was automatically mounted, e.g. by HAL. + * * Returns: %TRUE if the drive was automounted. %FALSE otherwise. **/ gboolean @@ -183,6 +206,8 @@ g_drive_is_automounted (GDrive *drive) * g_drive_can_mount: * @drive: a #GDrive. * + * Checks if a drive can be mounted. + * * Returns: %TRUE if the @drive can be mounted. %FALSE otherwise. **/ gboolean @@ -204,6 +229,8 @@ g_drive_can_mount (GDrive *drive) * g_drive_can_eject: * @drive: pointer to a #GDrive. * + * Checks if a drive can be ejected. + * * Returns: %TRUE if the @drive can be ejected. %FALSE otherwise. **/ gboolean @@ -225,9 +252,11 @@ g_drive_can_eject (GDrive *drive) * g_drive_mount: * @drive: a #GDrive. * @mount_operation: a #GMountOperation. + * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * + * Mounts a drive. * **/ void @@ -262,6 +291,8 @@ g_drive_mount (GDrive *drive, * @result: a #GAsyncResult. * @error: a #GError. * + * Finishes mounting a drive. + * * Returns: %TRUE, %FALSE if operation failed. **/ gboolean @@ -288,9 +319,12 @@ g_drive_mount_finish (GDrive *drive, /** * g_drive_eject: * @drive: a #GDrive. + * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * + * Ejects a drive. + * **/ void g_drive_eject (GDrive *drive, @@ -322,6 +356,8 @@ g_drive_eject (GDrive *drive, * @result: a #GAsyncResult. * @error: a #GError. * + * Finishes ejecting a drive. + * * Returns: %TRUE if the drive has been ejected successfully, * %FALSE otherwise. **/ diff --git a/gio/gdrive.h b/gio/gdrive.h index 7a0413ea9..4770b132a 100644 --- a/gio/gdrive.h +++ b/gio/gdrive.h @@ -34,6 +34,24 @@ G_BEGIN_DECLS #define G_IS_DRIVE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_DRIVE)) #define G_DRIVE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_DRIVE, GDriveIface)) +/** + * GDriveIface: + * @g_iface: The parent interface. + * @changed: Signal emitted when the drive is changed. + * @get_name: Returns the name for the given #GDrive. + * @get_icon: Returns a #GIcon for the given #GDrive. + * @has_volumes: Returns %TRUE if the #GDrive has mountable volumes. + * @get_volumes: Returns a #GList of volumes for the #GDrive. + * @is_automounted: returns %TRUE if the #GDrive was automounted. + * @can_mount: Returns %TRUE if the #GDrive can be mounted. + * @can_eject: Returns %TRUE if the #GDrive can be ejected. + * @mount: Mounts a given #GDrive. + * @mount_finish: Finishes a mount operation. + * @eject: Ejects a #GDrive. + * @eject_finish: Finishes an eject operation. + * + * Interface for creating #GDrive implementations. + */ typedef struct _GDriveIface GDriveIface; struct _GDriveIface diff --git a/gio/gfile.c b/gio/gfile.c index 617422f17..f833b589d 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -34,6 +34,39 @@ #include "gpollfilemonitor.h" #include "glibintl.h" +/** + * SECTION:gfile + * @short_description: File and Directory Handling + * @see_also: #GFileInfo, #GFileEnumerator + * @include: gio/gfile.h + * + * #GFile is a high level abstraction for manipulating files on a + * virtual file system. #GFiles are lightweight, immutable + * objects that do no I/O upon creation. It is necessary to understand that + * #GFile objects do not represent files, merely a handle to a file. All + * file I/O is implemented as streams (see #GInputStream and #GOutputStream). + * + * To construct a #GFile, you can use: + * g_file_new_for_path() if you have a path. + * g_file_new_for_uri() if you have a URI. + * + * You can move through the filesystem with #GFile handles with + * g_file_get_parent() to get a handle to the parent directory. + * g_file_get_child() to get a handle to a child within a directory. + * g_file_resolve_relative_path() to resolve a relative path between + * two #GFiles. + * + * Many #GFile operations have both synchronous (or blocking) and + * asynchronous (non-blocking) versions to suit your application. + * Asynchronous versions of synchronous functions simply have _async() + * appended to their function names. The asynchronous I/O functions + * call a #GAsyncReadyCallback which is then used to finalize the operation, + * which is then passed to the function's matching _finish() operation. + * + * + * + **/ + static void g_file_base_init (gpointer g_class); static void g_file_class_init (gpointer g_class, gpointer class_data); @@ -186,8 +219,10 @@ g_file_base_init (gpointer g_class) * g_file_is_native: * @file: input #GFile. * - * Returns: %TRUE if file is native. - * TODO: Explain what "native" means. + * Checks to see if a file is native to the system. + * + * Returns: %TRUE if file is native. (If the file is native + * to the system, e.g. located in file:///). **/ gboolean g_file_is_native (GFile *file) @@ -207,6 +242,8 @@ g_file_is_native (GFile *file) * @file: input #GFile. * @uri_scheme: a string containing a URI scheme. * + * Checks to see if a #GFile has a given URI scheme. + * * Returns: %TRUE if #GFile's backend supports the * given URI scheme, FALSE if URI scheme is %NULL, * not supported, or #GFile is invalid. @@ -230,12 +267,13 @@ g_file_has_uri_scheme (GFile *file, * g_file_get_uri_scheme: * @file: input #GFile. * + * Gets the URI scheme for a #GFile. + * * Returns: string to the URI scheme for the given #GFile. * RFC 3986 decodes the scheme as: * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * Popular schemes include "file", "http", "svn", etc. - * - * The returned string should be freed when no longer needed. + * Common schemes include "file", "http", "svn", etc. The returned + * string should be freed when no longer needed. **/ char * g_file_get_uri_scheme (GFile *file) @@ -254,10 +292,11 @@ g_file_get_uri_scheme (GFile *file) * g_file_get_basename: * @file: input #GFile. * - * Returns: string containing the #GFile's base name, or %NULL if given - * #GFile is invalid. + * Gets the basename for a given #GFile. * - * The returned string should be freed when no longer needed + * Returns: string containing the #GFile's base name, or %NULL if given + * #GFile is invalid. The returned string should be freed when no longer + * needed. **/ char * g_file_get_basename (GFile *file) @@ -275,10 +314,10 @@ g_file_get_basename (GFile *file) * g_file_get_path: * @file: input #GFile. * - * Returns: string containing the #GFile's path, or %NULL if given - * #GFile is invalid. - * - * The returned string should be freed when no longer needed + * Gets the current path within a #GFile. + * + * Returns: string containing the #GFile's path, or %NULL if given #GFile is + * invalid. The returned string should be freed when no longer needed. **/ char * g_file_get_path (GFile *file) @@ -296,10 +335,11 @@ g_file_get_path (GFile *file) * g_file_get_uri: * @file: input #GFile. * + * Gets a URI for the path within a #GFile. + * * Returns: string to the #GFile's Universal Resource Identifier (URI), - * or %NULL if given #GFile is invalid. - * - * The returned string should be freed when no longer needed + * or %NULL if given #GFile is invalid. The returned string should be freed + * when no longer needed. **/ char * g_file_get_uri (GFile *file) @@ -317,10 +357,10 @@ g_file_get_uri (GFile *file) * g_file_parse_name: * @file: input #GFile. * - * Returns: string to the GFile's parsed name, or %NULL if given - * GFile is invalid. - * - * The returned string should be freed when no longer needed + * Gets the parsed name for the #GFile. + * + * Returns: string to the #GFile's parsed name, or %NULL if given + * #GFile is invalid. The returned string should be freed when no longer needed. **/ char * g_file_get_parse_name (GFile *file) @@ -338,6 +378,10 @@ g_file_get_parse_name (GFile *file) * g_file_dup: * @file: input #GFile. * + * Duplicates a #GFile handle. This operation does not duplicate + * 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. **/ @@ -357,7 +401,9 @@ g_file_dup (GFile *file) * g_file_hash: * @file: #gconstpointer to a #GFile. * - * Returns: 0 if @file is not a #GFile, otherwise a + * Creates a hash of a #GFile. + * + * Returns: 0 if @file is not a valid #GFile, otherwise a * guint containing a hash of the #GFile. This function * is intended for easily hashing a #GFile to add to a * #GHashTable or similar data structure. @@ -380,6 +426,8 @@ g_file_hash (gconstpointer file) * @file1: the first #GFile. * @file2: the second #GFile. * + * Checks equality of two given #GFiles + * * Returns: %TRUE if @file1 and @file2 are equal. * %FALSE if either is not a #GFile. **/ @@ -405,12 +453,12 @@ g_file_equal (GFile *file1, * g_file_get_parent: * @file: input #GFile. * - * Returns: a #GFile structure to the parent of the given - * #GFile. - * - * This function should return the parent directory of the given - * @file. If the @file represents the root directory of the + * Gets the parent directory for the @file. + * If the @file represents the root directory of the * file system, then %NULL will be returned. + * + * Returns: a #GFile structure to the parent of the given + * #GFile or %NULL. **/ GFile * g_file_get_parent (GFile *file) @@ -429,6 +477,9 @@ 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. + * * Returns: a #GFile to a child specified by * @name or %NULL if @name is %NULL, or the specified * child doesn't exist. @@ -448,9 +499,13 @@ g_file_get_child (GFile *file, * @file: input #GFile. * @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. * - * Returns: %NULL if @display_name is %NULL, #GFile to - * the specified child. + * Returns: a #GFile to the specified child, or + * %NULL if @display_name is %NULL. **/ GFile * g_file_get_child_for_display_name (GFile *file, @@ -472,8 +527,9 @@ g_file_get_child_for_display_name (GFile *file, * @parent: input #GFile. * @descendant: input #GFile. * - * Returns: %FALSE if either the @parent or @descendant - * is invalid. %TRUE if the @descendent's parent is @parent. + * Checks whether @parent contains the specified @descendent. + * + * Returns: %TRUE if the @descendent's parent is @parent. %FALSE otherwise. **/ gboolean g_file_contains_file (GFile *parent, @@ -497,10 +553,10 @@ g_file_contains_file (GFile *parent, * @parent: input #GFile. * @descendant: input #GFile. * - * Returns: string with the relative path from - * @descendant to @parent. + * Gets the path for @descendant relative to @parent. * - * The returned string should be freed when no longer needed + * Returns: string with the relative path from @descendant to @parent. + * The returned string should be freed when no longer needed. **/ char * g_file_get_relative_path (GFile *parent, @@ -524,6 +580,8 @@ g_file_get_relative_path (GFile *parent, * @file: input #GFile. * @relative_path: a given relative path string. * + * Resolves a relative path for @file to an absolute path. + * * Returns: #GFile to the resolved path. %NULL if @relative_path is NULL. * or if @file is invalid. **/ @@ -544,19 +602,24 @@ g_file_resolve_relative_path (GFile *file, /** * g_file_enumerate_children: * @file: input #GFile. - * @attributes: a string. - * @flags: #GFileQueryInfoFlags field. + * @attributes: a string containing a #GFileAttributeInfo query. + * @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 that match @attributes, + * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", "std:*"). * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * 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: %NULL if cancelled or if #GFile's backend doesn't - * support #GFileEnumerator. Returns a #GFileEnumerator if successful. + * Returns: A #GFileEnumerator if successful. %NULL if cancelled or if #GFile's + * backend doesn't support #GFileEnumerator. **/ GFileEnumerator * g_file_enumerate_children (GFile *file, @@ -590,20 +653,18 @@ g_file_enumerate_children (GFile *file, /** * g_file_enumerate_children_async: * @file: input #GFile. - * @attributes: a string. + * @attributes: a string containing a #GFileAttributeInfo query. * @flags: a set of #GFileQueryInfoFlags. - * @io_priority: the io priority of the request. the io priority of the request. + * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * - * Asynchronously enumerates the children of the given @file. + * Asynchronously gets a #GFileEnumerator for the children of @file that match @attributes, + * where attributes is a #GFileAttributeInfo query string (e.g. "std:type", "std:*"). For the + * synchronous version of this function, see g_file_enumerate_children(). * - * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * To finish this asynchronous operation, see g_file_enumerate_children_finish(). * **/ void @@ -635,6 +696,15 @@ g_file_enumerate_children_async (GFile *file, * @res: a #GAsyncResult. * @error: a #GError. * + * 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 * @@ -662,16 +732,18 @@ g_file_enumerate_children_finish (GFile *file, /** * g_file_query_info: * @file: input #GFile. - * @attributes: a string. + * @attributes: a string containing a #GFileAttributeInfo query. * @flags: a set of #GFileQueryInfoFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * 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. * * Returns: a #GFileInfo for the given @file, or %NULL on error. **/ @@ -705,7 +777,7 @@ g_file_query_info (GFile *file, /** * g_file_query_info_async: * @file: input #GFile. - * @attributes: a string. + * @attributes: a string containing a #GFileAttributeInfo query. * @flags: a set of #GFileQueryInfoFlags. * @io_priority: the io priority of the request. the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. @@ -714,9 +786,9 @@ g_file_query_info (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * To finish this asynchronous operation, see g_file_query_info_finish(). * **/ void @@ -745,13 +817,21 @@ g_file_query_info_async (GFile *file, /** * g_file_query_info_finish: * @file: input #GFile. - * @error: a #GAsyncResult. + * @res: a #GAsyncResult. * @error: a #GError. * - * Finishes an asynchronous file info query. If the operation failed, - * returns %NULL and set @error appropriately if present. + * 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. * - * Returns: #GFileInfo for given @file or %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. + * + * Returns: #GFileInfo for given @file or %NULL on error. **/ GFileInfo * g_file_query_info_finish (GFile *file, @@ -777,17 +857,19 @@ g_file_query_info_finish (GFile *file, /** * g_file_query_filesystem_info: * @file: input #GFile. - * @attributes: a string. + * @attributes: a string containing a #GFileAttributeInfo query. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileInfo or %NULl if there was an error. + * 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. + * + * Returns: a #GFileInfo or %NULL if there was an error. **/ GFileInfo * g_file_query_filesystem_info (GFile *file, @@ -820,14 +902,18 @@ g_file_query_filesystem_info (GFile *file, * @file: input #GFile. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. + * + * Gets a #GVolume for the #GFile. + * + * If the #GFileIface for @file does not have a volume (e.g. possibly a + * remote share), @error will be set to %G_IO_ERROR_NOT_FOUND 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GVolume where the @file is located. + * Returns: a #GVolume where the @file is located or %NULL on error. **/ GVolume * g_file_find_enclosing_volume (GFile *file, @@ -860,15 +946,16 @@ g_file_find_enclosing_volume (GFile *file, * @error: a #GError. * * Reads a whole file into a #GFileInputStream. Fails returning %NULL if - * given #GFile points to a directory. + * given #GFile points to a directory. + * + * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: #GFileInputStream or %NULL. + * Returns: #GFileInputStream or %NULL on error. **/ GFileInputStream * g_file_read (GFile *file, @@ -900,12 +987,13 @@ g_file_read (GFile *file, * @file: input #GFile. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. + * + * 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. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * Returns: a #GFileOutputStream. **/ @@ -941,12 +1029,13 @@ g_file_append_to (GFile *file, * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. - * + * + * 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. + * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * Returns: a #GFileOutputStream for the newly created file, or * %NULL on error. @@ -984,12 +1073,15 @@ g_file_create (GFile *file, * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. + * + * 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. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * 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. @@ -1030,19 +1122,14 @@ g_file_replace (GFile *file, /** * g_file_read_async: * @file: input #GFile. - * @io_priority: the io priority of the request. the io priority of the request. + * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. - * - * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. * * Asynchronously reads @file. For the synchronous version of this function, * see g_file_read(). + * **/ void g_file_read_async (GFile *file, @@ -1066,10 +1153,20 @@ g_file_read_async (GFile *file, /** * g_file_read_finish: * @file: input #GFile. - * @error: a #GAsyncResult. + * @res: a #GAsyncResult. * @error: a #GError. + * + * 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 if there was an error. + * Returns: a #GFileInputStream or %NULL on error. **/ GFileInputStream * g_file_read_finish (GFile *file, @@ -1107,9 +1204,7 @@ g_file_read_finish (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -1139,7 +1234,9 @@ g_file_append_to_async (GFile *file, * @res: #GAsyncResult * @error: a #GError. * - * Returns: a valid #GFileOutputStream or %NULL upon error. + * Finishes appending to a file started with g_file_append_to_async(). + * + * Returns: a valid #GFileOutputStream or %NULL on error. **/ GFileOutputStream * g_file_append_to_finish (GFile *file, @@ -1176,9 +1273,7 @@ g_file_append_to_finish (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -1205,9 +1300,11 @@ g_file_create_async (GFile *file, /** * g_file_create_finish: * @file: input #GFile. - * @error: a #GAsyncResult. + * @res: a #GAsyncResult. * @error: a #GError. * + * Finishes creating a file started with g_file_create_async(). + * * Returns: a #GFileOutputStream. **/ GFileOutputStream * @@ -1248,9 +1345,7 @@ g_file_create_finish (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -1281,11 +1376,12 @@ g_file_replace_async (GFile *file, /** * g_file_replace_finish: * @file: input #GFile. - * @error: a #GAsyncResult. + * @res: a #GAsyncResult. * @error: a #GError. * * Finishes replacing the contents of the file started by - * g_file_replace_async(). + * g_file_replace_async(). This is typically called within + * a #GAsyncReadyCallback. * * Returns: a #GFileOutputStream, or %NULL if an error has occured. **/ @@ -1717,6 +1813,7 @@ file_copy_fallback (GFile *source, * @progress_callback_data: userdata to pass to @progress_callback * @error: #GError to set on error * + * + * + * Copies a file or directory from @source to @destination, with the given @flags. + * @flags should be set to %0 if not used. This operation may fail, and @error will + * be set appropriately with the given error result (see the following table). + * File copies are always asynchronous. + * + * 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_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 + * + * + *
* * Returns: %TRUE on success, %FALSE otherwise. **/ @@ -1779,17 +1908,17 @@ g_file_copy (GFile *source, /** * g_file_move: - * @source: GFile* pointing to the source location. - * @destination: GFile* pointing to the destination location. - * @flags: GFileCopyFlags enum. + * @source: #GFile pointing to the source location. + * @destination: #GFile pointing to the destination location. + * @flags: #GFileCopyFlags enum. * @cancellable: optional #GCancellable object, %NULL to ignore. * @progress_callback: GFileProgressCallback function for updates. * @progress_callback_data: gpointer to user data for the callback function. - * @error: GError for returning error conditions. + * @error: #GError for returning error conditions. * * List of possible returns from g_file_move() with given source, * destination, and flags: - * + * + * + * 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 + * + * + *
* Returns: %TRUE on successful move, %FALSE otherwise. **/ gboolean @@ -1858,6 +2014,10 @@ g_file_move (GFile *source, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * 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 on successful creation, %FALSE otherwise. **/ gboolean @@ -1892,6 +2052,10 @@ g_file_make_directory (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * 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 on the creation of a new symlink, %FALSE otherwise. **/ gboolean @@ -1935,6 +2099,12 @@ g_file_make_symbolic_link (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * Deletes a file. + * + * 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 was deleted. %FALSE otherwise. **/ gboolean @@ -1964,14 +2134,18 @@ g_file_delete (GFile *file, /** * g_file_trash: - * @file: GFile to location to send to trash. + * @file: #GFile to send to trash. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: GError for possible failures. + * @error: a #GError. * - * This function sends the object to the virtual "Trash" location. If the - * GFile interface does not have a corresponding "Trash" location, this function - * returns %FALSE, and will set @error appropriately. + * 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. * + * 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 on successful trash, %FALSE otherwise. **/ gboolean @@ -2006,9 +2180,15 @@ g_file_trash (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * 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(). + * + * 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. - * For the asynchronous version of this function, see - * g_file_set_display_name_async(). **/ GFile * g_file_set_display_name (GFile *file, @@ -2053,9 +2233,7 @@ g_file_set_display_name (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -2083,9 +2261,11 @@ g_file_set_display_name_async (GFile *file, /** * g_file_set_display_name_finish: * @file: input #GFile. - * @error: a #GAsyncResult. + * @res: a #GAsyncResult. * @error: a #GError. * + * Finishes setting a display name started with g_file_set_display_name_async(). + * * Returns: a #GFile or %NULL on error. **/ GFile * @@ -2115,6 +2295,10 @@ g_file_set_display_name_finish (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * 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 @@ -2162,6 +2346,10 @@ g_file_query_settable_attributes (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * 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. @@ -2206,13 +2394,20 @@ g_file_query_writable_namespaces (GFile *file, * g_file_set_attribute: * @file: input #GFile. * @attribute: a string containing the attribute's name. - * @value: #GFileAttributeValue - * @flags: #GFileQueryInfoFlags + * @value: a set of #GFileAttributeValue. + * @flags: a set of #GFileQueryInfoFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Returns: %TRUE if the attribute was correctly set, %FALSE - * otherwise. + * 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 + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. + * + * Returns: %TRUE if the attribute was set, %FALSE otherwise. **/ gboolean g_file_set_attribute (GFile *file, @@ -2251,9 +2446,13 @@ g_file_set_attribute (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Tries to set all attributes in the GFileInfo on the target values, not stopping + * Tries to set all attributes in the #GFileInfo on the target values, not stopping * on the first error. * + * 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. @@ -2330,14 +2529,12 @@ g_file_real_set_attributes_from_info (GFile *file, * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * - * Asynchronously sets the attributes of @file with @info and @flags. + * 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. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -2366,6 +2563,8 @@ g_file_set_attributes_async (GFile *file, * @info: a #GFileInfo. * @error: a #GError. * + * Finishes setting an attribute started in g_file_set_attributes_async(). + * * Returns: %TRUE if the attributes were set correctly, %FALSE otherwise. **/ gboolean @@ -2395,8 +2594,14 @@ g_file_set_attributes_finish (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. If + * @attribute is of a different type, this operation will fail. + * + * 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 @attribute was successfully set, %FALSE otherwise. **/ gboolean g_file_set_attribute_string (GFile *file, @@ -2414,7 +2619,7 @@ g_file_set_attribute_string (GFile *file, } /** - * g_file_attribute_byte_string: + * g_file_set_attribute_byte_string: * @file: input #GFile. * @attribute: a string containing the attribute's name. * @value: a string containing the attribute's new value. @@ -2422,6 +2627,13 @@ g_file_set_attribute_string (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. If + * @attribute is of a different type, this operation will fail, returning %FALSE. + * + * 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 @attribute was successfully set to @value * in the @file, %FALSE otherwise. **/ @@ -2449,6 +2661,13 @@ g_file_set_attribute_byte_string (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. If + * @attribute is of a different type, this operation will fail. + * + * 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 @attribute was successfully set to @value * in the @file, %FALSE otherwise. **/ @@ -2476,6 +2695,13 @@ g_file_set_attribute_uint32 (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. If + * @attribute is of a different type, this operation will fail. + * + * 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 @attribute was successfully set to @value * in the @file, %FALSE otherwise. **/ @@ -2503,6 +2729,13 @@ g_file_set_attribute_int32 (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. If + * @attribute is of a different type, this operation will fail. + * + * 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 @attribute was successfully set to @value * in the @file, %FALSE otherwise. **/ @@ -2530,8 +2763,14 @@ g_file_set_attribute_uint64 (GFile *file, * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Returns: %TRUE if the @attribute was successfully set to @value - * in the @file, %FALSE otherwise. + * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. If + * @attribute is of a different type, this operation will fail. + * + * 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 @attribute was successfully set, %FALSE otherwise. **/ gboolean g_file_set_attribute_int64 (GFile *file, @@ -2556,6 +2795,10 @@ g_file_set_attribute_int64 (GFile *file, * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * + * 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. + * * Mounts a mountable file using @mount_operation, if possible. * **/ @@ -2627,6 +2870,10 @@ g_file_mount_mountable_finish (GFile *file, * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * + * 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_unmount_mountable (GFile *file, @@ -2693,6 +2940,15 @@ g_file_unmount_mountable_finish (GFile *file, * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * + * Starts an asynchronous eject on a mountable. + * When this operation has completed, @callback will be called with + * @user_user data, and the operation can be finalized with + * g_file_eject_mountable_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 returned. + * **/ void g_file_eject_mountable (GFile *file, @@ -2728,6 +2984,9 @@ g_file_eject_mountable (GFile *file, * @result: a #GAsyncResult. * @error: a #GError. * + * Finishes an asynchronous eject operation started by + * g_file_eject_mountable(). + * * Returns: %TRUE if the @file was ejected successfully. %FALSE * otherwise. **/ @@ -2758,6 +3017,10 @@ g_file_eject_mountable_finish (GFile *file, * @flags: a set of #GFileMonitorFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * + * 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 #GDirectoryMonitor for the given @file, * or %NULL on error. **/ @@ -2784,6 +3047,10 @@ g_file_monitor_directory (GFile *file, * @flags: a set of #GFileMonitorFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * + * 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. **/ @@ -3518,11 +3785,15 @@ g_file_new_for_commandline_arg (const char *arg) * @callback: a #GAsyncReadyCallback. * @user_data: a #gpointer. * - * Starts the @mount_operation, mounting the volume at @location. This - * operation is cancellable with @cancellable. When the operation has - * completed, @callback will be called with user data. To finish - * the operation, call g_mount_for_location_finish() with the - * #GAsyncResult returned by the @callback. + * Starts the @mount_operation, mounting the volume at @location. + * + * When this operation has completed, @callback will be called with + * @user_user data, and the operation can be finalized with + * g_mount_for_location_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 returned. * **/ void @@ -3559,10 +3830,11 @@ g_mount_for_location (GFile *location, * @result: a #GAsyncResult. * @error: a #GError. * - * Finishes an Asynchronous mount operation. + * Finishes a mount operation started by g_mount_for_location(). * - * Returns: %TRUE if the mount was finished successfully. If %FALSE and - * @error is present, it will be set appropriately. + * Returns: %TRUE if successful. If an error + * has occured, this function will return %FALSE and set @error + * appropriately if present. **/ gboolean g_mount_for_location_finish (GFile *location, @@ -3596,11 +3868,15 @@ g_mount_for_location_finish (GFile *location, * g_file_load_contents: * @file: input #GFile. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @contents: - * @length: - * @etag_out: a pointer to the current entity tag for the document. + * @contents: a location to place the contents of the file. + * @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. * + * 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. @@ -3854,9 +4130,7 @@ load_contents_open_callback (GObject *obj, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -3890,10 +4164,10 @@ g_file_load_partial_contents_async (GFile *file, /** * g_file_load_partial_contents_finish: * @file: input #GFile. - * @error: a #GAsyncResult. - * @contents: a pointer to where the contents of the file will be placed. - * @length: a pointer to the location where the content's length will be placed. - * @etag_out: a pointer to the current entity tag for the document. + * @res: a #GAsyncResult. + * @contents: a location to place the contents of the file. + * @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. * * Returns: %TRUE if the load was successful. If %FALSE and @error is @@ -3967,9 +4241,7 @@ g_file_load_partial_contents_finish (GFile *file, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * **/ void @@ -3988,10 +4260,10 @@ g_file_load_contents_async (GFile *file, /** * g_file_load_contents_finish: * @file: input #GFile. - * @error: a #GAsyncResult. - * @contents: an array of strings. - * @length: a pointer to a #gsize. - * @etag_out: a pointer to a string to get the new entity tag. + * @res: a #GAsyncResult. + * @contents: a location to place the contents of the file. + * @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. * * Finishes an asynchronous load of the @file's contents. The contents @@ -4022,23 +4294,22 @@ g_file_load_contents_finish (GFile *file, /** * g_file_replace_contents: * @file: input #GFile. - * @length: a #gsize. + * @contents: a string containing the new contents for @file. + * @length: the length of @contents in bytes. * @etag: the old entity tag for the document. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. - * @new_etag: a new entity tag for the document. + * @new_etag: a location to a new entity tag for the document. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError. * - * Replaces the contents of @file with @contents of @length. The old + * Replaces the contents of @file with @contents of @length bytes. The old * @etag will be replaced with the @new_etag. If @make_backup is %TRUE, * this function will attempt to make a backup of @file. * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * Returns: %TRUE if successful. If an error * has occured, this function will return %FALSE and set @error @@ -4231,7 +4502,7 @@ replace_contents_open_callback (GObject *obj, * g_file_replace_contents_async: * @file: input #GFile. * @contents: string of contents to replace the file with. - * @length: length of the @contents string. + * @length: the length of @contents in bytes. * @etag: a new entity tag for the @file. * @make_backup: a #gboolean. * @flags: a set of #GFileCreateFlags. @@ -4249,9 +4520,7 @@ replace_contents_open_callback (GObject *obj, * * 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 an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. + * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. @@ -4297,12 +4566,12 @@ g_file_replace_contents_async (GFile *file, /** * g_file_replace_contents_finish: * @file: input #GFile. - * @error: a #GAsyncResult. - * @new_etag: a pointer to the new entity tag string for the contents of the file. + * @res: a #GAsyncResult. + * @new_etag: a location of a new entity tag for the document. * @error: a #GError. * - * Finishes an asynchronous replace of the given @file. - * This function will take ownership of the @new_etag, if present. + * Finishes an asynchronous replace of the given @file. Sets + * @new_etag to the new entity tag for the document, if present. * * Returns: %TRUE on success, %FALSE on failure. **/ diff --git a/gio/gfile.h b/gio/gfile.h index ac3f02f14..c2e437b69 100644 --- a/gio/gfile.h +++ b/gio/gfile.h @@ -37,15 +37,37 @@ G_BEGIN_DECLS #define G_IS_FILE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_FILE)) #define G_FILE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_FILE, GFileIface)) +/** + * GFileQueryInfoFlags: + * @G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS: + * + * Flags used when querying a #GFileInfo. + */ typedef enum { G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS = (1<<0) } GFileQueryInfoFlags; +/** + * GFileCreateFlags: + * @G_FILE_CREATE_FLAGS_NONE: + * @G_FILE_CREATE_FLAGS_PRIVATE: + * + * Flags used when an operation may create a file. + */ typedef enum { G_FILE_CREATE_FLAGS_NONE = 0, G_FILE_CREATE_FLAGS_PRIVATE = (1<<0) } GFileCreateFlags; +/** + * GFileCopyFlags: + * @G_FILE_COPY_OVERWRITE: Overwrite any existing files + * @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 (see #GFileInfo). + * + * Flags used when copying or moving files. + */ typedef enum { G_FILE_COPY_OVERWRITE = (1<<0), G_FILE_COPY_BACKUP = (1<<1), @@ -53,25 +75,149 @@ typedef enum { G_FILE_COPY_ALL_METADATA = (1<<3) } GFileCopyFlags; +/** + * GFileMonitorFlags: + * @G_FILE_MONITOR_FLAGS_NONE: No flags set. + * @G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS: Watch for mount events. + * + * Flags used to set what a #GFileMonitor or #GDirectoryMonitor will watch for. + */ typedef enum { G_FILE_MONITOR_FLAGS_NONE = 0, G_FILE_MONITOR_FLAGS_MONITOR_MOUNTS = (1<<0) } GFileMonitorFlags; +/** + * GFile: + * + * A handle to an object implementing the #GFileIface interface. + * Generally stores a location within the file system. Handles do not + * necessarily represent files or directories that currently exist. + **/ typedef struct _GFile GFile; /* Dummy typedef */ typedef struct _GFileIface GFileIface; typedef struct _GDirectoryMonitor GDirectoryMonitor; typedef struct _GFileMonitor GFileMonitor; + +/** + * GVolume: + * + * A handle to an object implementing the #GVolumeIface interface. + **/ typedef struct _GVolume GVolume; /* Dummy typedef */ +/** + * GFileProgressCallback: + * @current_num_bytes: the current number of bytes in the operation. + * @total_num_bytes: the total number of bytes in the operation. + * @user_data: user data passed to the callback. + * + * When doing file operations that may take a while, such as moving + * a file or copying a file, a progress callback is used to pass how + * far along that operation is to the application. + **/ typedef void (*GFileProgressCallback) (goffset current_num_bytes, goffset total_num_bytes, gpointer user_data); + +/** + * GFileReadMoreCallback: + * @file_contents: + * @file_size: + * @callback_data: + * + * + **/ typedef gboolean (* GFileReadMoreCallback) (const char *file_contents, goffset file_size, gpointer callback_data); - +/** + * GFileIface: + * @g_iface: The parent interface. + * @dup: Duplicates a #GFile. + * @hash: Creates a hash of a #GFile. + * @equal: Checks equality of two given #GFiles. + * @is_native: Checks to see if a file is native to the system. + * @has_uri_scheme: Checks to see if a #GFile has a given URI scheme. + * @get_uri_scheme: Gets the URI scheme for a #GFile. + * @get_basename: Gets the basename for a given #GFile. + * @get_path: Gets the current path within a #GFile. + * @get_uri: Gets a URI for the path within a #GFile. + * @get_parse_name: Gets the parsed name for the #GFile. + * @get_parent: Gets the parent directory for the #GFile. + * @contains_file: Checks whether a #GFile contains a specified file. + * @get_relative_path: Gets the path for a #GFile relative to a given path. + * @resolve_relative_path: Resolves a relative path for a #GFile to an absolute path. + * @get_child_for_display_name: Gets the child #GFile for a given display name. + * @enumerate_children: Gets a #GFileEnumerator with the children of a #GFile. + * @enumerate_children_async: Asynchronously gets a #GFileEnumerator with the children of a #GFile. + * @enumerate_children_finish: Finishes asynchronously enumerating the children. + * @query_info: Gets the #GFileInfo for a #GFile. + * @query_info_async: Asynchronously gets the #GFileInfo for a #GFile. + * @query_info_finish: Finishes an asynchronous query info operation. + * @query_filesystem_info: Gets a #GFileInfo for the file system #GFile is on. + * @_query_filesystem_info_async: Asynchronously gets a #GFileInfo for the file system #GFile is on. + * @_query_filesystem_info_finish: Finishes asynchronously getting the file system info. + * @find_enclosing_volume: Gets a #GVolume for the #GFile. + * @find_enclosing_volume_async: Asynchronously gets the #GVolume for a #GFile. + * @find_enclosing_volume_finish: Finishes asynchronously getting the volume. + * @set_display_name: Sets the display name for a #GFile. + * @set_display_name_async: Asynchronously sets a #GFile's display name. + * @set_display_name_finish: Finishes asynchronously setting a #GFile's display name. + * @query_settable_attributes: Returns a list of #GFileAttributes that can be set. + * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttributes that can be set. + * @_query_settable_attributes_finish: Finishes asynchronously querying settable attributes. + * @query_writable_namespaces: Returns a list of #GFileAttribute namespaces that are writable. + * @_query_writable_namespaces_async: Asynchronously gets a list of #GFileAttribute namespaces that are writable. + * @_query_writable_namespaces_finish: Finishes asynchronously querying the writable namespaces. + * @set_attribute: Sets a #GFileAttribute. + * @set_attributes_from_info: Sets a #GFileAttribute with information from a #GFileInfo. + * @set_attributes_async: Asynchronously sets a file's attributes. + * @set_attributes_finish: Finishes setting a file's attributes asynchronously. + * @read: Reads a file asynchronously. + * @read_async: Asynchronously reads a file. + * @read_finish: Finishes asynchronously reading a file. + * @append_to: Writes to the end of a file. + * @append_to_async: Asynchronously writes to the end of a file. + * @append_to_finish: Finishes an asynchronous file append operation. + * @create: Creates a new file. + * @create_async: Asynchronously creates a file. + * @create_finish: Finishes asynchronously creating a file. + * @replace: Replaces the contents of a file. + * @replace_async: Asynchronously replaces the contents of a file. + * @replace_finish: Finishes asynchronously replacing a file. + * @delete_file: Deletes a file. + * @_delete_file_async: Asynchronously deletes a file. + * @_delete_file_finish: Finishes an asynchronous delete. + * @trash: Sends a #GFile to the Trash location. + * @_trash_async: Asynchronously sends a #GFile to the Trash location. + * @_trash_finish: Finishes an asynchronous file trashing operation. + * @make_directory: Makes a directory. + * @_make_directory_async: Asynchronously makes a directory. + * @_make_directory_finish: Finishes making a directory asynchronously. + * @make_symbolic_link: Makes a symbolic link. + * @_make_symbolic_link_async: Asynchronously makes a symbolic link + * @_make_symbolic_link_finish: Finishes making a symbolic link asynchronously. + * @copy: Copies a file. + * @_copy_async: Asynchronously copies a file. + * @_copy_finish: Finishes an asynchronous copy operation. + * @move: Moves a file. + * @_move_async: Asynchronously moves a file. + * @_move_finish: Finishes an asynchronous move operation. + * @mount_mountable: Mounts a mountable object. + * @mount_mountable_finish: Finishes a mounting operation. + * @unmount_mountable: Unmounts a mountable object. + * @unmount_mountable_finish: Finishes an unmount operation. + * @eject_mountable: Ejects a mountable. + * @eject_mountable_finish: Finishes an eject operation. + * @mount_for_location: Mounts a specified location. + * @mount_for_location_finish: Finishes mounting a specified location. + * @monitor_dir: Creates a #GDirectoryMonitor for the location. + * @monitor_file: Creates a #GFileMonitor for the location. + * + * An interface for writing VFS file handles. + **/ struct _GFileIface { GTypeInterface g_iface; @@ -346,6 +492,7 @@ struct _GFileIface GFileMonitor* (*monitor_file) (GFile *file, GFileMonitorFlags flags, GCancellable *cancellable); + }; GType g_file_get_type (void) G_GNUC_CONST; diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index ee93d6cce..eeb29a4b1 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -28,6 +28,160 @@ #include #include "glibintl.h" +/** + * SECTION:gfileattribute + * @short_description: Key-Value Paired File Attributes. + * @see_also: #GFile, #GFileInfo. + * + * File attributes in GIO consist of a list of key-value pairs. + * + * 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 + * "std" namespace. + * + * Values are stored within the list in #GFileAttributeValue structures. + * Values can store different types, listed in the enum #GFileAttributeType. + * 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 + * 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(). + * + * + * + * GFileAttributes Namespaces + * + * NamspaceDescription + * + * + * "std"The "Standard" namespace. General file + * information that any application may need should be put in this namespace. Examples + * include the file's name, type, and size. + * "etag"The "Entity Tag" namespace. Remotely shared + * files, like those on HTTP/1.1 file systems, use "entity tags" to quickly determine + * if a file has been modified. Entity tags are globally unique, and should + * always be sent with the current revision of a file. An example of a key + * in this namespace is "value", which contains the value of the current + * entity tag. + * "id"The "Identification" namespace. This + * namespace is used by file managers and applications that list directories + * to check for loops and to uniquely identify files. + * "access"The "Access" namespace. Used to check + * if a user has the proper privilidges to access files and perform + * file operations. Keys in this namespace are made to be generic + * and easily understood, e.g. the "can_read" key is %TRUE if + * the current user has permission to read the file. UNIX permissions and + * 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. + * "time"The "Time" namespace. Includes file + * access, changed, created times. + * "unix"The "Unix" namespace. Includes UNIX-specific + * information and may not be available for all files. Examples include + * the UNIX "UID", "GID", etc. + * "dos"The "DOS" namespace. Includes DOS-specific + * information and may not be available for all files. Examples include + * "is_system" for checking if a file is marked as a system file, and "is_archive" + * 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. + * "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. + * "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. + * "gvfs"The "GVFS" namespace. Keys in this namespace + * contain information about the current GVFS backend in use. + * + * + *
+ * + * + * More namespaces can be added from GIO modules or by individual applications. + * For more information about writing GIO modules, see #GIOModule. + * + * + * GFileAttributes Built-in Keys and Value Types + * + * Enum ValueNamespace:KeyValue Type + * + * %G_FILE_ATTRIBUTE_STD_TYPEstd:typeuint32 (#GFileType) + * %G_FILE_ATTRIBUTE_STD_IS_HIDDENstd:is_hiddenboolean + * %G_FILE_ATTRIBUTE_STD_IS_BACKUPstd:is_backupboolean + * %G_FILE_ATTRIBUTE_STD_IS_SYMLINKstd:is_symlinkboolean + * %G_FILE_ATTRIBUTE_STD_IS_VIRTUALstd:is_virtualboolean + * %G_FILE_ATTRIBUTE_STD_NAMEstd:namebyte string + * %G_FILE_ATTRIBUTE_STD_DISPLAY_NAMEstd:display_namestring + * %G_FILE_ATTRIBUTE_STD_EDIT_NAMEstd:edit_namestring + * %G_FILE_ATTRIBUTE_STD_ICONstd:iconobject (#GIcon) + * %G_FILE_ATTRIBUTE_STD_CONTENT_TYPEstd:content_typestring + * %G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPEstd:fast_content_typestring + * %G_FILE_ATTRIBUTE_STD_SIZEstd:sizeuint64 + * %G_FILE_ATTRIBUTE_STD_SYMLINK_TARGETstd:symlink_targetbyte string + * %G_FILE_ATTRIBUTE_STD_TARGET_URIstd:target_uristring + * %G_FILE_ATTRIBUTE_STD_SORT_ORDERstd:sort_orderint32 + * %G_FILE_ATTRIBUTE_ETAG_VALUEetag:valuestring + * %G_FILE_ATTRIBUTE_ID_FILEid:filestring + * %G_FILE_ATTRIBUTE_ID_FSid:fsstring + * %G_FILE_ATTRIBUTE_ACCESS_CAN_READaccess:can_readboolean + * %G_FILE_ATTRIBUTE_ACCESS_CAN_WRITEaccess:can_writeboolean + * %G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTEaccess:can_executeboolean + * %G_FILE_ATTRIBUTE_ACCESS_CAN_DELETEaccess:can_deleteboolean + * %G_FILE_ATTRIBUTE_ACCESS_CAN_TRASHaccess:can_trashboolean + * %G_FILE_ATTRIBUTE_ACCESS_CAN_RENAMEaccess:can_renameboolean + * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNTmountable:can_mountboolean + * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNTmountable:can_unmountboolean + * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECTmountable:can_ejectboolean + * %G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICEmountable:unix_deviceuint32 + * %G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDImountable:hal_udistring + * %G_FILE_ATTRIBUTE_TIME_MODIFIEDtime:modifieduint64 + * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USECtime:modified_usecuint32 + * %G_FILE_ATTRIBUTE_TIME_ACCESStime:accessuint64 + * %G_FILE_ATTRIBUTE_TIME_ACCESS_USECtime:access_usecuint32 + * %G_FILE_ATTRIBUTE_TIME_CHANGEDtime:changeduint64 + * %G_FILE_ATTRIBUTE_TIME_CHANGED_USECtime:changed_usecuint32 + * %G_FILE_ATTRIBUTE_TIME_CREATEDtime:createduint64 + * %G_FILE_ATTRIBUTE_TIME_CREATED_USECtime:created_usecuint32 + * %G_FILE_ATTRIBUTE_UNIX_DEVICEunix:deviceuint32 + * %G_FILE_ATTRIBUTE_UNIX_INODEunix:inodeuint64 + * %G_FILE_ATTRIBUTE_UNIX_MODEunix:modeuint32 + * %G_FILE_ATTRIBUTE_UNIX_NLINKunix:nlinkuint32 + * %G_FILE_ATTRIBUTE_UNIX_UIDunix:uiduint32 + * %G_FILE_ATTRIBUTE_UNIX_GIDunix:giduint32 + * %G_FILE_ATTRIBUTE_UNIX_RDEVunix:rdevuint32 + * %G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZEunix:block_sizeuint32 + * %G_FILE_ATTRIBUTE_UNIX_BLOCKSunix:blocksuint64 + * %G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINTunix:is_mountpointboolean + * %G_FILE_ATTRIBUTE_DOS_IS_ARCHIVEdos:is_archiveboolean + * %G_FILE_ATTRIBUTE_DOS_IS_SYSTEMdos:is_systemboolean + * %G_FILE_ATTRIBUTE_OWNER_USERowner:userstring + * %G_FILE_ATTRIBUTE_OWNER_USER_REALowner:user_realstring + * %G_FILE_ATTRIBUTE_OWNER_GROUPowner:groupstring + * %G_FILE_ATTRIBUTE_THUMBNAIL_PATHthumbnail:pathbytestring + * %G_FILE_ATTRIBUTE_THUMBNAILING_FAILEDthumbnail:failedboolean + * %G_FILE_ATTRIBUTE_FS_SIZEfs:sizeuint64 + * %G_FILE_ATTRIBUTE_FS_FREEfs:freeuint64 + * %G_FILE_ATTRIBUTE_FS_TYPEfs:typestring + * %G_FILE_ATTRIBUTE_FS_READONLYfs:readonlyboolean + * %G_FILE_ATTRIBUTE_GVFS_BACKENDgvfs:backendstring + *
+ * + **/ + /** * g_file_attribute_value_free: * @attr: a #GFileAttributeValue. @@ -70,9 +224,10 @@ g_file_attribute_value_clear (GFileAttributeValue *attr) /** * g_file_attribute_value_set: - * @attr: a #GFileAttributeValue. - * @new_value: + * @attr: a #GFileAttributeValue to set the value in. + * @new_value: a #GFileAttributeValue to get the value from. * + * Sets an attribute's value from another attribute. **/ void g_file_attribute_value_set (GFileAttributeValue *attr, @@ -96,7 +251,9 @@ g_file_attribute_value_set (GFileAttributeValue *attr, /** * g_file_attribute_value_new: * - * Returns: a new #GFileAttributeValue. + * Creates a new file attribute. + * + * Returns: a #GFileAttributeValue. **/ GFileAttributeValue * g_file_attribute_value_new (void) @@ -113,6 +270,8 @@ g_file_attribute_value_new (void) * g_file_attribute_value_dup: * @other: a #GFileAttributeValue to duplicate. * + * Duplicates a file attribute. + * * Returns: a duplicate of the @other. **/ GFileAttributeValue * @@ -182,10 +341,10 @@ escape_byte_string (const char *str) * @attr: a #GFileAttributeValue. * * Converts a #GFileAttributeValue to a string for display. - * The returned string should be freed when no longer needed + * The returned string should be freed when no longer needed. * - * Returns: a string from the @attr, %NULL on error, or "<invalid>" if - * @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID. + * Returns: a string from the @attr, %NULL on error, or "<invalid>" + * if @attr is of type %G_FILE_ATTRIBUTE_TYPE_INVALID. **/ char * g_file_attribute_value_as_string (const GFileAttributeValue *attr) @@ -235,7 +394,10 @@ g_file_attribute_value_as_string (const GFileAttributeValue *attr) * g_file_attribute_value_get_string: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the string from a file attribute value. If the value is not the + * right type then %NULL will be returned. + * + * Returns: the string value contained within the attribute, or %NULL. **/ const char * g_file_attribute_value_get_string (const GFileAttributeValue *attr) @@ -252,7 +414,10 @@ g_file_attribute_value_get_string (const GFileAttributeValue *attr) * g_file_attribute_value_get_byte_string: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the byte string from a file attribute value. If the value is not the + * right type then %NULL will be returned. + * + * Returns: the byte string contained within the attribute or %NULL. **/ const char * g_file_attribute_value_get_byte_string (const GFileAttributeValue *attr) @@ -269,7 +434,10 @@ g_file_attribute_value_get_byte_string (const GFileAttributeValue *attr) * g_file_attribute_value_get_boolean: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the boolean value from a file attribute value. If the value is not the + * right type then %FALSE will be returned. + * + * Returns: the boolean value contained within the attribute, or %FALSE. **/ gboolean g_file_attribute_value_get_boolean (const GFileAttributeValue *attr) @@ -286,7 +454,10 @@ g_file_attribute_value_get_boolean (const GFileAttributeValue *attr) * g_file_attribute_value_get_uint32: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the unsigned 32-bit integer from a file attribute value. If the value + * is not the right type then %0 will be returned. + * + * Returns: the unsigned 32-bit integer from the attribute, or %0. **/ guint32 g_file_attribute_value_get_uint32 (const GFileAttributeValue *attr) @@ -303,7 +474,10 @@ g_file_attribute_value_get_uint32 (const GFileAttributeValue *attr) * g_file_attribute_value_get_int32: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the signed 32-bit integer from a file attribute value. If the value + * is not the right type then %0 will be returned. + * + * Returns: the signed 32-bit integer from the attribute, or %0. **/ gint32 g_file_attribute_value_get_int32 (const GFileAttributeValue *attr) @@ -320,7 +494,10 @@ g_file_attribute_value_get_int32 (const GFileAttributeValue *attr) * g_file_attribute_value_get_uint64: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the unsigned 64-bit integer from a file attribute value. If the value + * is not the right type then %0 will be returned. + * + * Returns: the unsigned 64-bit integer from the attribute, or %0. **/ guint64 g_file_attribute_value_get_uint64 (const GFileAttributeValue *attr) @@ -337,7 +514,10 @@ g_file_attribute_value_get_uint64 (const GFileAttributeValue *attr) * g_file_attribute_value_get_int64: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the signed 64-bit integer from a file attribute value. If the value + * is not the right type then %0 will be returned. + * + * Returns: the signed 64-bit integer from the attribute, or %0. **/ gint64 g_file_attribute_value_get_int64 (const GFileAttributeValue *attr) @@ -354,7 +534,10 @@ g_file_attribute_value_get_int64 (const GFileAttributeValue *attr) * g_file_attribute_value_get_object: * @attr: a #GFileAttributeValue. * - * Returns: + * Gets the GObject from a file attribute value. If the value + * is not the right type then %NULL will be returned. + * + * Returns: the GObject from the attribute, or %0. **/ GObject * g_file_attribute_value_get_object (const GFileAttributeValue *attr) @@ -370,7 +553,9 @@ g_file_attribute_value_get_object (const GFileAttributeValue *attr) /** * g_file_attribute_value_set_string: * @attr: a #GFileAttributeValue. - * @string: + * @string: a string to set within the type. + * + * Sets the attribute value to a given string. * **/ void @@ -388,7 +573,9 @@ g_file_attribute_value_set_string (GFileAttributeValue *attr, /** * g_file_attribute_value_set_byte_string: * @attr: a #GFileAttributeValue. - * @string: + * @string: a byte string to set within the type. + * + * Sets the attribute value to a given byte string. * **/ void @@ -406,8 +593,10 @@ g_file_attribute_value_set_byte_string (GFileAttributeValue *attr, /** * g_file_attribute_value_set_boolean: * @attr: a #GFileAttributeValue. - * @value: - * + * @value: a #gboolean to set within the type. + * + * Sets the attribute value to the given boolean value. + * **/ void g_file_attribute_value_set_boolean (GFileAttributeValue *attr, @@ -423,7 +612,9 @@ g_file_attribute_value_set_boolean (GFileAttributeValue *attr, /** * g_file_attribute_value_set_uint32: * @attr: a #GFileAttributeValue. - * @value: + * @value: a #guint32 to set within the type. + * + * Sets the attribute value to the given unsigned 32-bit integer. * **/ void @@ -440,7 +631,9 @@ g_file_attribute_value_set_uint32 (GFileAttributeValue *attr, /** * g_file_attribute_value_set_int32: * @attr: a #GFileAttributeValue. - * @value: + * @value: a #gint32 to set within the type. + * + * Sets the attribute value to the given signed 32-bit integer. * **/ void @@ -457,7 +650,9 @@ g_file_attribute_value_set_int32 (GFileAttributeValue *attr, /** * g_file_attribute_value_set_uint64: * @attr: a #GFileAttributeValue. - * @value: + * @value: a #guint64 to set within the type. + * + * Sets the attribute value to a given unsigned 64-bit integer. * **/ void @@ -474,8 +669,10 @@ g_file_attribute_value_set_uint64 (GFileAttributeValue *attr, /** * g_file_attribute_value_set_int64: * @attr: a #GFileAttributeValue. - * @value: a #gint64 to set the value to. - * + * @value: a #gint64 to set within the type. + * + * Sets the attribute value to a given signed 64-bit integer. + * **/ void g_file_attribute_value_set_int64 (GFileAttributeValue *attr, @@ -493,8 +690,8 @@ g_file_attribute_value_set_int64 (GFileAttributeValue *attr, * @attr: a #GFileAttributeValue. * @obj: a #GObject. * - * Sets the file attribute @attr to contain the value @obj. - * The @attr references the object internally. + * Sets the attribute to contain the value @obj. + * The @attr references the GObject internally. * **/ void @@ -525,7 +722,9 @@ list_update_public (GFileAttributeInfoListPriv *priv) /** * g_file_attribute_info_list_new: * - * Returns a new #GFileAttributeInfoList. + * Creates a new file attribute info list. + * + * Returns: a #GFileAttributeInfoList. **/ GFileAttributeInfoList * g_file_attribute_info_list_new (void) @@ -546,6 +745,8 @@ g_file_attribute_info_list_new (void) * g_file_attribute_info_list_dup: * @list: a #GFileAttributeInfoList to duplicate. * + * Makes a duplicate of a file attribute info list. + * * Returns a duplicate of the given @list. **/ GFileAttributeInfoList * @@ -576,6 +777,8 @@ g_file_attribute_info_list_dup (GFileAttributeInfoList *list) * g_file_attribute_info_list_ref: * @list: a #GFileAttributeInfoList to reference. * + * References a file attribute info list. + * * Returns: #GFileAttributeInfoList or %NULL on error. **/ GFileAttributeInfoList * diff --git a/gio/gfileattribute.h b/gio/gfileattribute.h index 125a46d45..23565b8e0 100644 --- a/gio/gfileattribute.h +++ b/gio/gfileattribute.h @@ -27,6 +27,20 @@ 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_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. + * @G_FILE_ATTRIBUTE_TYPE_INT32: a signed 4-byte/32-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_UINT64: an unsigned 8-byte/64-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_INT64: a signed 8-byte/64-bit integer. + * @G_FILE_ATTRIBUTE_TYPE_OBJECT: a #GObject. + * + * The data type for #GFileAttributeValues. + **/ typedef enum { G_FILE_ATTRIBUTE_TYPE_INVALID = 0, G_FILE_ATTRIBUTE_TYPE_STRING, @@ -39,13 +53,28 @@ typedef enum { G_FILE_ATTRIBUTE_TYPE_OBJECT } GFileAttributeType; +/** + * GFileAttributeFlags: + * @G_FILE_ATTRIBUTE_FLAGS_NONE: no flags set. + * @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. + **/ typedef enum { G_FILE_ATTRIBUTE_FLAGS_NONE = 0, G_FILE_ATTRIBUTE_FLAGS_COPY_WITH_FILE = 1 << 0, G_FILE_ATTRIBUTE_FLAGS_COPY_WHEN_MOVED = 1 << 1 } GFileAttributeFlags; -/* Used by g_file_set_attributes_from_info */ +/** + * GFileAttributeStatus: + * @G_FILE_ATTRIBUTE_STATUS_UNSET: Attribute value is unset (empty). + * @G_FILE_ATTRIBUTE_STATUS_SET: Attribute value is set. + * @G_FILE_ATTRIBUTE_STATUS_ERROR_SETTING: Indicates an error in setting the value. + * + * Used by g_file_set_attributes_from_info() when setting file attributes. + **/ typedef enum { G_FILE_ATTRIBUTE_STATUS_UNSET = 0, G_FILE_ATTRIBUTE_STATUS_SET, @@ -54,6 +83,13 @@ typedef enum { #define G_FILE_ATTRIBUTE_VALUE_INIT {0} +/** + * GFileAttributeValue: + * @type: a #GFileAttributeType. + * @status: a #GFileAttributeStatus. + * + * Contains the value data for the Key-Value pair. + **/ typedef struct { GFileAttributeType type : 8; GFileAttributeStatus status : 8; @@ -69,12 +105,28 @@ typedef struct { } u; } GFileAttributeValue; +/** + * GFileAttributeInfo: + * @name: a string containing the key's name. + * @type: a #GFileAttributeType for the key. + * @flags: a set of #GFileAttributeFlags. + * + * A Key-Value pair definition. + **/ typedef struct { char *name; GFileAttributeType type; GFileAttributeFlags flags; } GFileAttributeInfo; +/** + * GFileAttributeInfoList: + * @infos: an array of #GFileAttributeInfos. + * @n_infos: the number of values in the array. + * + * Acts as a lightweight registry for possible valid file attributes. + * The registry stores Key-Value pair formats as #GFileAttributeInfos. + **/ typedef struct { GFileAttributeInfo *infos; int n_infos; diff --git a/gio/gfileenumerator.c b/gio/gfileenumerator.c index 300fff316..7422bb99b 100644 --- a/gio/gfileenumerator.c +++ b/gio/gfileenumerator.c @@ -27,6 +27,13 @@ #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:gfileenumerator + * @short_description: Enumerated Files Routines. + * + * + **/ + G_DEFINE_TYPE (GFileEnumerator, g_file_enumerator, G_TYPE_OBJECT); struct _GFileEnumeratorPrivate { @@ -305,6 +312,9 @@ g_file_enumerator_next_files_async (GFileEnumerator *enumerator, * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. + * + * + * * Returns: **/ GList * @@ -402,6 +412,9 @@ g_file_enumerator_close_async (GFileEnumerator *enumerator, * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. + * + * + * * Returns: %TRUE if the close operation has finished successfully. **/ gboolean diff --git a/gio/gfileenumerator.h b/gio/gfileenumerator.h index 1e83f8856..677311787 100644 --- a/gio/gfileenumerator.h +++ b/gio/gfileenumerator.h @@ -39,7 +39,12 @@ G_BEGIN_DECLS #define G_IS_FILE_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ENUMERATOR)) #define G_FILE_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ENUMERATOR, GFileEnumeratorClass)) - +/** + * GFileEnumerator: + * @parent: The parent class. + * + * A per matched file iterator. + **/ typedef struct _GFileEnumerator GFileEnumerator; typedef struct _GFileEnumeratorClass GFileEnumeratorClass; typedef struct _GFileEnumeratorPrivate GFileEnumeratorPrivate; @@ -84,8 +89,8 @@ struct _GFileEnumeratorClass GAsyncResult *res, GError **error); - - /* Padding for future expansion */ + /*< private >*/ + /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); void (*_g_reserved3) (void); diff --git a/gio/gfileicon.c b/gio/gfileicon.c index 6e46e7f95..be3f3fe9e 100644 --- a/gio/gfileicon.c +++ b/gio/gfileicon.c @@ -25,6 +25,16 @@ #include "gfileicon.h" #include "gsimpleasyncresult.h" +/** + * SECTION:gfileicon + * @short_description: Icons for given files. + * @see_also: #GIcon, #GLoadableIcon. + * @include: gio/gfileicon.h + * + * #GFileIcon gets the default icon for a #GFile. + * + **/ + static void g_file_icon_icon_iface_init (GIconIface *iface); static void g_file_icon_loadable_icon_iface_init (GLoadableIconIface *iface); static void g_file_icon_load_async (GLoadableIcon *icon, @@ -80,9 +90,11 @@ g_file_icon_init (GFileIcon *file) /** * g_file_icon_new: - * @file: + * @file: a #GFile. * - * Returns: + * Creates a new icon for a file. + * + * Returns: a #GIcon for the given @file, or %NULL on error. **/ GIcon * g_file_icon_new (GFile *file) @@ -99,9 +111,11 @@ g_file_icon_new (GFile *file) /** * g_file_icon_get_file: - * @icon: + * @icon: a #GIcon. * - * Returns: + * Gets the #GFile associated with the given @icon. + * + * Returns: a #GFile, or %NULL. **/ GFile * g_file_icon_get_file (GFileIcon *icon) diff --git a/gio/gfileicon.h b/gio/gfileicon.h index 1745e5fba..1d43cce98 100644 --- a/gio/gfileicon.h +++ b/gio/gfileicon.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_FILE_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_ICON)) #define G_FILE_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_ICON, GFileIconClass)) +/** + * GFileIcon: + * + * Gets an icon for a #GFile. Implements #GLoadabeIcon. + **/ typedef struct _GFileIcon GFileIcon; typedef struct _GFileIconClass GFileIconClass; diff --git a/gio/gfileinfo.c b/gio/gfileinfo.c index 07c8f4918..698661523 100644 --- a/gio/gfileinfo.c +++ b/gio/gfileinfo.c @@ -20,6 +20,21 @@ * Author: Alexander Larsson */ +/** + * SECTION:gfileinfo + * @short_description: File Information and Attributes. + * @see_also: #GFile. + * + * Functionality for manipulating basic metadata for files. #GFileInfo + * implements methods for getting information that all files should + * contain, and allows for manipulation of extended attributes. + * #GFileAttributeMatcher allows for searching through a #GFileInfo for + * attributes. + * + * + * + **/ + #include #include @@ -222,7 +237,9 @@ g_file_info_init (GFileInfo *info) /** * g_file_info_new: * - * Returns: a new #GFileInfo. + * Creates a new file info structure. + * + * Returns: a #GFileInfo. **/ GFileInfo * g_file_info_new (void) @@ -235,7 +252,7 @@ g_file_info_new (void) * @src_info: source to copy attributes from. * @dest_info: destination to copy attributes to. * - * Copies all of the attributes from @src_info to @dest_info. + * Copies all of the #GFileAttributes from @src_info to @dest_info. **/ void g_file_info_copy_into (GFileInfo *src_info, GFileInfo *dest_info) @@ -273,6 +290,8 @@ g_file_info_copy_into (GFileInfo *src_info, GFileInfo *dest_info) * g_file_info_dup: * @other: a #GFileInfo. * + * Duplicates a file info structure. + * * Returns: a duplicate #GFileInfo of @other. **/ GFileInfo * @@ -293,7 +312,6 @@ g_file_info_dup (GFileInfo *other) * @mask: a #GFileAttributeMatcher. * * Sets @mask on @info to match specific attribute types. - * **/ void g_file_info_set_attribute_mask (GFileInfo *info, @@ -330,6 +348,8 @@ g_file_info_set_attribute_mask (GFileInfo *info, * g_file_info_unset_attribute_mask: * @info: #GFileInfo. * + * Unsets a mask set by g_file_info_set_attribute_mask(), if one + * is set. **/ void g_file_info_unset_attribute_mask (GFileInfo *info) @@ -346,7 +366,6 @@ g_file_info_unset_attribute_mask (GFileInfo *info) * @info: a #GFileInfo. * * Clears the status information from @info. - * **/ void g_file_info_clear_status (GFileInfo *info) @@ -421,7 +440,9 @@ g_file_info_find_value_by_name (GFileInfo *info, /** * g_file_info_has_attribute: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Checks if a file info structure has an attribute named @attribute. * * Returns: %TRUE if @GFileInfo has an attribute named @attribute, * %FALSE otherwise. @@ -442,7 +463,9 @@ g_file_info_has_attribute (GFileInfo *info, /** * g_file_info_list_attributes: * @info: a #GFileInfo. - * @name_space: a string. + * @name_space: a file attribute key's namespace. + * + * Lists the file info structure's attributes. * * Returns: a null-terminated array of strings of all of the * possible attribute types for the given @name_space, or @@ -478,10 +501,12 @@ g_file_info_list_attributes (GFileInfo *info, /** * g_file_info_get_attribute_type: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Gets the attribute type for an attribute key. * * Returns: a #GFileAttributeType for the given @attribute, or - * %G_FILE_ATTRIBUTE_TYPE_INVALID if one cannot be found. + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is invalid. **/ GFileAttributeType g_file_info_get_attribute_type (GFileInfo *info, @@ -502,9 +527,9 @@ g_file_info_get_attribute_type (GFileInfo *info, /** * g_file_info_remove_attribute: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. * - * Removes @attribute from @info if it exists. + * Removes all cases of @attribute from @info if it exists. * **/ void @@ -533,7 +558,9 @@ g_file_info_remove_attribute (GFileInfo *info, /** * g_file_info_get_attribute: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Gets an attribute value from a file info structure. * * Returns: a #GFileAttributeValue for the given @attribute, or * %NULL otherwise. @@ -552,7 +579,10 @@ g_file_info_get_attribute (GFileInfo *info, /** * g_file_info_get_attribute_object: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Gets the value of a #GObject attribute. If the attribute does + * not contain a #GObject, %NULL will be returned. * * Returns: a #GObject associated with the given @attribute, or * %NULL otherwise. @@ -573,7 +603,10 @@ g_file_info_get_attribute_object (GFileInfo *info, /** * g_file_info_get_attribute_string: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Gets the value of a string attribute. If the attribute does + * not contain a string, %NULL will be returned. * * Returns: the contents of the @attribute value as a string, or * %NULL otherwise. @@ -594,7 +627,10 @@ g_file_info_get_attribute_string (GFileInfo *info, /** * g_file_info_get_attribute_byte_string: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. + * + * Gets the value of a byte string attribute. If the attribute does + * not contain a byte string, %NULL will be returned. * * Returns: the contents of the @attribute value as a byte string, or * %NULL otherwise. @@ -615,9 +651,12 @@ g_file_info_get_attribute_byte_string (GFileInfo *info, /** * g_file_info_get_attribute_boolean: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. * - * Returns: + * Gets the value of a boolean attribute. If the attribute does not + * contain a boolean value, %FALSE will be returned. + * + * Returns: the boolean value contained within the attribute. **/ gboolean g_file_info_get_attribute_boolean (GFileInfo *info, @@ -635,9 +674,13 @@ g_file_info_get_attribute_boolean (GFileInfo *info, /** * g_file_info_get_attribute_uint32: * @info: a #GFileInfo. - * @attribute: a string. + * @attribute: a file attribute key. * - * Returns: + * Gets an unsigned 32-bit integer contained within the attribute. If the + * attribute does not contain an unsigned 32-bit integer, or is invalid, + * %0 will be returned. + * + * Returns: an unsigned 32-bit integer from the attribute. **/ guint32 g_file_info_get_attribute_uint32 (GFileInfo *info, @@ -654,10 +697,14 @@ g_file_info_get_attribute_uint32 (GFileInfo *info, /** * g_file_info_get_attribute_int32: - * @info: - * @attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns: + * Gets a signed 32-bit integer contained within the attribute. If the + * attribute does not contain a signed 32-bit integer, or is invalid, + * %0 will be returned. + * + * Returns: a signed 32-bit integer from the attribute. **/ gint32 g_file_info_get_attribute_int32 (GFileInfo *info, @@ -674,10 +721,14 @@ g_file_info_get_attribute_int32 (GFileInfo *info, /** * g_file_info_get_attribute_uint64: - * @info: - * @attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns: + * Gets a unsigned 64-bit integer contained within the attribute. If the + * attribute does not contain an unsigned 64-bit integer, or is invalid, + * %0 will be returned. + * + * Returns: a unsigned 64-bit integer from the attribute. **/ guint64 g_file_info_get_attribute_uint64 (GFileInfo *info, @@ -694,10 +745,14 @@ g_file_info_get_attribute_uint64 (GFileInfo *info, /** * g_file_info_get_attribute_int64: - * @info: - * @attribute: + * @info: a #GFileInfo. + * @attribute: a file attribute key. * - * Returns: + * Gets a signed 64-bit integer contained within the attribute. If the + * attribute does not contain an signed 64-bit integer, or is invalid, + * %0 will be returned. + * + * Returns: a signed 64-bit integer from the attribute. **/ gint64 g_file_info_get_attribute_int64 (GFileInfo *info, @@ -754,9 +809,12 @@ g_file_info_create_value_by_name (GFileInfo *info, /** * g_file_info_set_attribute: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a #GFileAttributeValue. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -777,9 +835,12 @@ g_file_info_set_attribute (GFileInfo *info, /** * g_file_info_set_attribute_object: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a #GObject. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -800,9 +861,12 @@ g_file_info_set_attribute_object (GFileInfo *info, /** * g_file_info_set_attribute_string: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a string. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -823,9 +887,12 @@ g_file_info_set_attribute_string (GFileInfo *info, /** * g_file_info_set_attribute_byte_string: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a byte string. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -846,9 +913,12 @@ g_file_info_set_attribute_byte_string (GFileInfo *info, /** * g_file_info_set_attribute_boolean: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a boolean value. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -868,9 +938,12 @@ g_file_info_set_attribute_boolean (GFileInfo *info, /** * g_file_info_set_attribute_uint32: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 32-bit integer. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ @@ -892,9 +965,12 @@ g_file_info_set_attribute_uint32 (GFileInfo *info, /** * g_file_info_set_attribute_int32: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: a signed 32-bit integer + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -914,9 +990,12 @@ g_file_info_set_attribute_int32 (GFileInfo *info, /** * g_file_info_set_attribute_uint64: - * @info: - * @attribute: - * @attr_value: + * @info: a #GFileInfo. + * @attribute: a file attribute key. + * @attr_value: an unsigned 64-bit integer. + * + * Sets the @attribute to contain the given @attr_value, + * if possible. * **/ void @@ -936,10 +1015,13 @@ g_file_info_set_attribute_uint64 (GFileInfo *info, /** * g_file_info_set_attribute_int64: - * @info: + * @info: a #GFileInfo. * @attribute: attribute name to set. * @attr_value: int64 value to set attribute to. * + * Sets the @attribute to contain the given @attr_value, + * if possible. + * **/ void g_file_info_set_attribute_int64 (GFileInfo *info, @@ -961,6 +1043,9 @@ g_file_info_set_attribute_int64 (GFileInfo *info, * g_file_info_get_file_type: * @info: a #GFileInfo. * + * Gets a file's type (whether it is a regular file, symlink, etc). + * This is different from the file's content type, see g_file_info_get_content_type(). + * * Returns: a #GFileType for the given file. **/ GFileType @@ -982,6 +1067,8 @@ g_file_info_get_file_type (GFileInfo *info) * g_file_info_get_is_hidden: * @info: a #GFileInfo. * + * Checks if a file is hidden. + * * Returns: %TRUE if the file is a hidden file, %FALSE otherwise. **/ gboolean @@ -1003,7 +1090,9 @@ g_file_info_get_is_hidden (GFileInfo *info) * g_file_info_get_is_backup: * @info: a #GFileInfo. * - * Returns: %TRUE if file is a backup file (.*~), %FALSE otherwise. + * Checks if a file is a backup file. + * + * Returns: %TRUE if file is a backup file, %FALSE otherwise. **/ gboolean g_file_info_get_is_backup (GFileInfo *info) @@ -1024,6 +1113,8 @@ g_file_info_get_is_backup (GFileInfo *info) * g_file_info_get_is_symlink: * @info: a #GFileInfo. * + * Checks if a file is a symlink. + * * Returns: %TRUE if the given @info is a symlink. **/ gboolean @@ -1045,7 +1136,9 @@ g_file_info_get_is_symlink (GFileInfo *info) * g_file_info_get_name: * @info: a #GFileInfo. * - * Returns: + * Gets the name for a file. + * + * Returns: a string containing the file name. **/ const char * g_file_info_get_name (GFileInfo *info) @@ -1066,7 +1159,9 @@ g_file_info_get_name (GFileInfo *info) * g_file_info_get_display_name: * @info: a #GFileInfo. * - * Returns: + * Gets a display name for a file. + * + * Returns: a string containing the display name. **/ const char * g_file_info_get_display_name (GFileInfo *info) @@ -1087,7 +1182,9 @@ g_file_info_get_display_name (GFileInfo *info) * g_file_info_get_edit_name: * @info: a #GFileInfo. * - * Returns: + * Gets the edit name for a file. + * + * Returns: a string containing the edit name. **/ const char * g_file_info_get_edit_name (GFileInfo *info) @@ -1108,6 +1205,8 @@ g_file_info_get_edit_name (GFileInfo *info) * g_file_info_get_icon: * @info: a #GFileInfo. * + * Gets the icon for a file. + * * Returns: #GIcon for the given @info. **/ GIcon * @@ -1133,7 +1232,9 @@ g_file_info_get_icon (GFileInfo *info) * g_file_info_get_content_type: * @info: a #GFileInfo. * - * Returns: + * Gets the file's content type. + * + * Returns: a string containing the file's content type.s **/ const char * g_file_info_get_content_type (GFileInfo *info) @@ -1154,7 +1255,9 @@ g_file_info_get_content_type (GFileInfo *info) * g_file_info_get_size: * @info: a #GFileInfo. * - * Returns: goffset. + * Gets the file's size. + * + * Returns: a #goffset containing the file's size. **/ goffset g_file_info_get_size (GFileInfo *info) @@ -1174,7 +1277,10 @@ g_file_info_get_size (GFileInfo *info) /** * g_file_info_get_modification_time: * @info: a #GFileInfo. - * @result: + * @result: a #GTimeVal. + * + * Gets the modification time of the current @info and sets it + * in @result. * **/ @@ -1204,7 +1310,9 @@ g_file_info_get_modification_time (GFileInfo *info, * g_file_info_get_symlink_target: * @info: a #GFileInfo. * - * Returns: + * Gets the symlink target for a given #GFileInfo. + * + * Returns: a string containing the symlink target. **/ const char * g_file_info_get_symlink_target (GFileInfo *info) @@ -1225,7 +1333,10 @@ g_file_info_get_symlink_target (GFileInfo *info) * g_file_info_get_etag: * @info: a #GFileInfo. * - * Returns: + * Gets the entity tag for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_ETAG_VALUE. + * + * Returns: a string containing the value of the "etag:value" attribute. **/ const char * g_file_info_get_etag (GFileInfo *info) @@ -1246,7 +1357,10 @@ g_file_info_get_etag (GFileInfo *info) * g_file_info_get_sort_order: * @info: a #GFileInfo. * - * Returns: + * Gets the value of the sort_order attribute from the #GFileInfo. + * See %G_FILE_ATTRIBUTE_STD_SORT_ORDER. + * + * Returns: a #gint32 containing the value of the "std:sort_order" attribute. **/ gint32 g_file_info_get_sort_order (GFileInfo *info) @@ -1267,8 +1381,10 @@ g_file_info_get_sort_order (GFileInfo *info) /** * g_file_info_set_file_type: * @info: a #GFileInfo. - * @type: - * + * @type: a #GFileType. + * + * Sets the file type in a #GFileInfo to @type. + * See %G_FILE_ATTRIBUTE_STD_TYPE. **/ void g_file_info_set_file_type (GFileInfo *info, @@ -1290,8 +1406,10 @@ g_file_info_set_file_type (GFileInfo *info, /** * g_file_info_set_is_hidden: * @info: a #GFileInfo. - * @is_hidden: + * @is_hidden: a #gboolean. * + * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink. + * See %G_FILE_ATTRIBUTE_STD_IS_HIDDEN. **/ void g_file_info_set_is_hidden (GFileInfo *info, @@ -1313,7 +1431,10 @@ g_file_info_set_is_hidden (GFileInfo *info, /** * g_file_info_set_is_symlink: * @info: a #GFileInfo. - * @is_symlink: + * @is_symlink: a #gboolean. + * + * Sets the "is_symlink" attribute in a #GFileInfo according to @is_symlink. + * See %G_FILE_ATTRIBUTE_STD_IS_SYMLINK. * **/ void @@ -1336,7 +1457,10 @@ g_file_info_set_is_symlink (GFileInfo *info, /** * g_file_info_set_name: * @info: a #GFileInfo. - * @name: + * @name: a string containing a name. + * + * Sets the name attribute for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STD_NAME. * **/ void @@ -1360,7 +1484,10 @@ g_file_info_set_name (GFileInfo *info, /** * g_file_info_set_display_name: * @info: a #GFileInfo. - * @display_name: + * @display_name: a string containing a display name. + * + * Sets the display name for the current #GFileInfo. + * See %G_FILE_ATTRIBUTE_STD_DISPLAY_NAME. * **/ void @@ -1384,7 +1511,10 @@ g_file_info_set_display_name (GFileInfo *info, /** * g_file_info_set_edit_name: * @info: a #GFileInfo. - * @edit_name: + * @edit_name: a string containing an edit name. + * + * Sets the edit name for the current file. + * See %G_FILE_ATTRIBUTE_STD_EDIT_NAME. * **/ @@ -1409,7 +1539,10 @@ g_file_info_set_edit_name (GFileInfo *info, /** * g_file_info_set_icon: * @info: a #GFileInfo. - * @icon: + * @icon: a #GIcon. + * + * Sets the icon for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STD_ICON. * **/ void @@ -1433,7 +1566,10 @@ g_file_info_set_icon (GFileInfo *info, /** * g_file_info_set_content_type: * @info: a #GFileInfo. - * @content_type: + * @content_type: a content type. See #GContentType. + * + * Sets the content type attribute for a given #GFileInfo. + * See %G_FILE_ATTRIBUTE_STD_CONTENT_TYPE. * **/ void @@ -1457,7 +1593,10 @@ g_file_info_set_content_type (GFileInfo *info, /** * g_file_info_set_size: * @info: a #GFileInfo. - * @size: + * @size: a #goffset containing the file's size. + * + * Sets the %G_FILE_ATTRIBUTE_STD_SIZE attribute in the file info + * to the given size. * **/ void @@ -1480,7 +1619,10 @@ g_file_info_set_size (GFileInfo *info, /** * g_file_info_set_modification_time * @info: a #GFileInfo. - * @mtime: + * @mtime: a #GTimeVal. + * + * Sets the %G_FILE_ATTRIBUTE_TIME_MODIFIED attribute in the file + * info to the given time value. * **/ void @@ -1510,7 +1652,10 @@ g_file_info_set_modification_time (GFileInfo *info, /** * g_file_info_set_symlink_target: * @info: a #GFileInfo. - * @symlink_target: + * @symlink_target: a static string containing a path to a symlink target. + * + * Sets the %G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET attribute in the file info + * to the given symlink target. * **/ void @@ -1534,7 +1679,10 @@ g_file_info_set_symlink_target (GFileInfo *info, /** * g_file_info_set_sort_order: * @info: a #GFileInfo. - * @sort_order: + * @sort_order: a sort order integer. + * + * Sets the sort order attribute in the file info structure. See + * %G_FILE_ATTRIBUTE_STD_SORT_ORDER. * **/ void @@ -1559,6 +1707,17 @@ g_file_info_set_sort_order (GFileInfo *info, #define MEGABYTE_FACTOR (1024.0 * 1024.0) #define GIGABYTE_FACTOR (1024.0 * 1024.0 * 1024.0) +/** + * g_format_file_size_for_display: + * @size: a file size. + * + * Formats a file size into a human readable string. Sizes are rounded + * to the nearest metric prefix and are displayed rounded to the nearest + * tenth. E.g. the file size 3292528 bytes will be converted into the string + * "3.1 MB". + * + * Returns: a formatted string containing a human readable file size. + **/ char * g_format_file_size_for_display (goffset size) { @@ -1647,10 +1806,34 @@ matcher_add (GFileAttributeMatcher *matcher, } /** - * g_file_attribute_matcher_new - * @attributes: + * g_file_attribute_matcher_new: + * @attributes: an attribute string to match. * - * Returns: #GFileAttributeMatcher. + * Creates a new file attribute matcher, which matches attributes against + * a given string. #GFileAttributeMatchers are reference counted structures, + * and are created with a reference count of 1. If the number of references + * falls to 0, the #GFileAttributeMatcher is automatically destroyed. + * + * The @attribute string should be formatted with specific keys separated + * from namespaces with a colon. Several "namespace:key" strings may be + * concatenated with a single comma (e.g. "std:type,std:is_hidden"). + * The wildcard "*" may be used to match all keys and namespaces, or "namespace:*" will + * match all keys in a given namespace. + * + * Examples of strings to use: + * + * File Attribute Matcher strings and results + * + * Matcher String Matches + * + * "*"matches all attributes. + * "std:is_hidden"matches only the key is_hidden in the std namespace. + * "std:type,unix:*"matches the type key in the std namespace and all keys in the unix + * namespace. + * + *
+ * + * Returns: a #GFileAttributeMatcher. **/ GFileAttributeMatcher * g_file_attribute_matcher_new (const char *attributes) @@ -1707,6 +1890,8 @@ g_file_attribute_matcher_new (const char *attributes) * g_file_attribute_matcher_ref: * @matcher: a #GFileAttributeMatcher. * + * References a file attribute matcher. + * * Returns: a #GFileAttributeMatcher. **/ GFileAttributeMatcher * @@ -1746,9 +1931,12 @@ g_file_attribute_matcher_unref (GFileAttributeMatcher *matcher) /** * g_file_attribute_matcher_matches_only: * @matcher: a #GFileAttributeMatcher. - * @attribute: + * @attribute: a file attribute key. * - * Returns: + * Checks if a attribute matcher only matches a given attribute. Always + * returns %FALSE if "*" was used when creating the matcher. + * + * Returns: %TRUE if the matcher only matches @attribute. %FALSE otherwise. **/ gboolean g_file_attribute_matcher_matches_only (GFileAttributeMatcher *matcher, @@ -1817,9 +2005,13 @@ g_file_attribute_matcher_matches_id (GFileAttributeMatcher *matcher, /** * g_file_attribute_matcher_matches: * @matcher: a #GFileAttributeMatcher. - * @attribute: + * @attribute: a file attribute key. + * + * Checks if an attribute will be matched by an attribute matcher. If + * the matcher was created with the "*" matching string, this function + * will always return %TRUE. * - * Returns: + * Returns: %TRUE if @attribute matches @matcher. %FALSE otherwise. **/ gboolean g_file_attribute_matcher_matches (GFileAttributeMatcher *matcher, @@ -1838,9 +2030,17 @@ g_file_attribute_matcher_matches (GFileAttributeMatcher *matcher, /** * g_file_attribute_matcher_enumerate_namespace: * @matcher: a #GFileAttributeMatcher. - * @ns: + * @ns: a string containing a file attribute namespace. * - * Returns: %TRUE, %FALSE. + * Checks if the matcher will match all of the keys in a given namespace. + * This will always return %TRUE if a wildcard character is in use (e.g. if + * matcher was created with "std:*" and @ns is "std", or if matcher was created + * using "*" and namespace is anything.) + * + * TODO: this is awkwardly worded. + * + * Returns: %TRUE if the matcher matches all of the entries + * in the given @ns, %FALSE otherwise. **/ gboolean g_file_attribute_matcher_enumerate_namespace (GFileAttributeMatcher *matcher, @@ -1884,7 +2084,10 @@ g_file_attribute_matcher_enumerate_namespace (GFileAttributeMatcher *matcher, * g_file_attribute_matcher_enumerate_next: * @matcher: a #GFileAttributeMatcher. * - * Returns: + * Gets the next matched attribute from a #GFileAttributeMatcher. + * + * Returns: a string containing the next attribute or %NULL if + * no more attribute exist. **/ const char * g_file_attribute_matcher_enumerate_next (GFileAttributeMatcher *matcher) diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h index 480d6a6de..c8ab32694 100644 --- a/gio/gfileinfo.h +++ b/gio/gfileinfo.h @@ -36,10 +36,33 @@ G_BEGIN_DECLS #define G_IS_FILE_INFO_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INFO)) #define G_FILE_INFO_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INFO, GFileInfoClass)) +/** + * GFileInfo: + * + * Stores information about a file system object referenced by a #GFile. + **/ typedef struct _GFileInfo GFileInfo; typedef struct _GFileInfoClass GFileInfoClass; + +/** + * GFileAttributeMatcher: + * + * Determines if a string matches a file attribute. + **/ typedef struct _GFileAttributeMatcher GFileAttributeMatcher; +/** + * GFileType: + * @G_FILE_TYPE_UNKNOWN: File's type is unknown. + * @G_FILE_TYPE_REGULAR: File handle represents a regular file. + * @G_FILE_TYPE_DIRECTORY: File handle represents a directory. + * @G_FILE_TYPE_SYMBOLIC_LINK: File handle represents a symbolic link (Unix systems) + * @G_FILE_TYPE_SPECIAL: File is a "special" file, such as a socket, fifo, blockdev, or chardev. + * @G_FILE_TYPE_SHORTCUT: File is a shortcut (Windows systems) + * @G_FILE_TYPE_MOUNTABLE: File is a mountable location. + * + * Indicates the file's on-disk type. + **/ typedef enum { G_FILE_TYPE_UNKNOWN = 0, G_FILE_TYPE_REGULAR, @@ -51,102 +74,537 @@ typedef enum { } GFileType; /* Common Attributes: */ - +/** + * G_FILE_ATTRIBUTE_STD_TYPE: + * + * A key in the "std" namespace for storing file types. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * The value for this key should contain a #GFileType. + **/ #define G_FILE_ATTRIBUTE_STD_TYPE "std:type" /* uint32 (GFileType) */ + +/** + * G_FILE_ATTRIBUTE_STD_IS_HIDDEN: + * + * A key in the "std" namespace for checking if a file is hidden. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_STD_IS_HIDDEN "std:is_hidden" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_STD_IS_BACKUP: + * + * A key in the "std" namespace for checking if a file is a backup file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_STD_IS_BACKUP "std:is_backup" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_STD_IS_SYMLINK: + * + * A key in the "std" namespace for checking if the file is a symlink. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_STD_IS_SYMLINK "std:is_symlink" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_STD_IS_VIRTUAL: + * + * A key in the "std" namespace for checking if a file is virtual. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_STD_IS_VIRTUAL "std:is_virtual" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_STD_NAME: + * + * A key in the "std" namespace for getting the name of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_NAME "std:name" /* byte string */ + +/** + * G_FILE_ATTRIBUTE_STD_DISPLAY_NAME: + * + * A key in the "std" namespace for getting the display name of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_DISPLAY_NAME "std:display_name" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_EDIT_NAME: + * + * A key in the "std" namespace for edit name of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_EDIT_NAME "std:edit_name" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_COPY_NAME: + * + * A key in the "std" namespace for getting the copy name of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_COPY_NAME "std:copy_name" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_ICON: + * + * A key in the "std" namespace for getting the icon for the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + * The value for this key should contain a #GIcon. + **/ #define G_FILE_ATTRIBUTE_STD_ICON "std:icon" /* object (GIcon) */ + +/** + * G_FILE_ATTRIBUTE_STD_CONTENT_TYPE: + * + * A key in the "std" namespace for getting the content type of the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * The value for this key should contain a valid content type. + **/ #define G_FILE_ATTRIBUTE_STD_CONTENT_TYPE "std:content_type" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE: + * + * A key in the "std" namespace for getting the fast content type. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * + **/ #define G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE "std:fast_content_type" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_SIZE: + * + * A key in the "std" namespace for getting the file's size. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + **/ #define G_FILE_ATTRIBUTE_STD_SIZE "std:size" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET: + * + * A key in the "std" namespace for getting the symlink target, if the file + * is a symlink. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET "std:symlink_target" /* byte string */ + +/** + * G_FILE_ATTRIBUTE_STD_TARGET_URI: + * + * A key in the "std" namespace for getting the target URI for the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_STD_TARGET_URI "std:target_uri" /* string */ + +/** + * G_FILE_ATTRIBUTE_STD_SORT_ORDER: + * + * 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. + **/ #define G_FILE_ATTRIBUTE_STD_SORT_ORDER "std:sort_order" /* int32 */ /* Entity tags, used to avoid missing updates on save */ - +/** + * G_FILE_ATTRIBUTE_ETAG_VALUE: + * + * A key in the "etag" namespace for getting the value of the file's + * entity tag. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_ETAG_VALUE "etag:value" /* string */ /* File identifier, for e.g. avoiding loops when doing recursive directory scanning */ - +/** + * G_FILE_ATTRIBUTE_ID_FILE: + * + * A key in the "id" namespace for getting a file identifier. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * An example use would be during listing files, to avoid recursive + * directory scanning. + **/ #define G_FILE_ATTRIBUTE_ID_FILE "id:file" /* string */ + +/** + * G_FILE_ATTRIBUTE_ID_FS: + * + * A key in the "id" namespace for getting the file system identifier. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + * An example use would be during listing files, to avoid recursive + * directory scanning. + **/ #define G_FILE_ATTRIBUTE_ID_FS "id:fs" /* string */ /* Calculated Access Rights for current user */ +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_READ: + * + * A key in the "access" namespace for getting read privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to read the file. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access:can_read" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE: + * + * A key in the "access" namespace for getting write privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to write to the file. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access:can_write" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: + * + * A key in the "access" namespace for getting execution privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to execute the file. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access:can_execute" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE: + * + * A key in the "access" namespace for checking deletion privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to delete the file. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access:can_delete" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH: + * + * A key in the "access" namespace for checking trashing privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to send the file to the + * virtual file system trash location. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH "access:can_trash" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME: + * + * A key in the "access" namespace for checking renaming privilidges. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + * This key will be true if the user is able to rename the file. + **/ #define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access:can_rename" /* boolean */ /* TODO: Should we have special version for directories? can_enumerate, etc */ /* Mountable attributes */ - +/** + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: + * + * A key in the "mountable" namespace for checking if a file is mountable. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable:can_mount" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: + * + * A key in the "mountable" namespace for checking if a file is unmountable. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable:can_unmount" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: + * + * A key in the "mountable" namespace for checking if a file can be ejected. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable:can_eject" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: + * + * A key in the "mountable" namespace for getting the unix device. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE "mountable:unix_device" /* uint32 */ + +/** + * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: + * + * A key in the "mountable" namespace for getting the HAL UDI for the mounted + * file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable:hal_udi" /* string */ /* Time attributes */ /* The last time the file content or an attribute was modified */ +/** + * G_FILE_ATTRIBUTE_TIME_MODIFIED: + * + * A key in the "time" namespace for getting the time the file was last + * modified. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was modified. + **/ #define G_FILE_ATTRIBUTE_TIME_MODIFIED "time:modified" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC: + * + * A key in the "time" namespace for getting the milliseconds of the time + * the file was last modified. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time:modified_usec" /* uint32 */ /* The last time the file was read */ +/** + * G_FILE_ATTRIBUTE_TIME_ACCESS: + * + * A key in the "time" namespace for getting the time the file was last + * accessed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was last accessed. + **/ #define G_FILE_ATTRIBUTE_TIME_ACCESS "time:access" /* uint64 */ +/** + * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC: + * + * A key in the "time" namespace for getting the milliseconds of the time + * the file was last accessed. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time:access_usec" /* uint32 */ /* The last time a file attribute was changed (e.g. unix ctime) */ +/** + * G_FILE_ATTRIBUTE_TIME_CHANGED: + * + * A key in the "time" namespace for getting the time the file was last + * changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was last changed. + **/ #define G_FILE_ATTRIBUTE_TIME_CHANGED "time:changed" /* uint64 */ +/** + * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC: + * + * A key in the "time" namespace for getting the milliseconds of the time + * the file was last changed. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time:changed_usec" /* uint32 */ /* When the file was originally created (e.g. ntfs ctime) */ +/** + * G_FILE_ATTRIBUTE_TIME_CREATED: + * + * A key in the "time" namespace for getting the time the file was created. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, + * and contains the UNIX time since the file was created. + **/ #define G_FILE_ATTRIBUTE_TIME_CREATED "time:created" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_TIME_CREATED_USEC: + * + * A key in the "time" namespace for getting the milliseconds of the time + * the file was created. This should be used in conjunction with + * #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time:created_usec" /* uint32 */ /* Unix specific attributes */ - +/** + * G_FILE_ATTRIBUTE_UNIX_DEVICE: + * + * A key in the "unix" namespace for getting the device id of the device the + * file is located on (see man stat(2)). This attribute is only available + * for UNIX file systems. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_UINT32. + * + **/ #define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix:device" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_INODE: + * + * A key in the "unix" namespace for getting the inode of the file. + * This attribute is only available for UNIX file systems. Corresponding + * #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + **/ #define G_FILE_ATTRIBUTE_UNIX_INODE "unix:inode" /* uint64 */ +/** + * G_FILE_ATTRIBUTE_UNIX_MODE: + * + * A key in the "unix" namespace for getting the mode of the file (e.g. whether the file + * is a regular file, symlink, etc). See man lstat(2). This attribute is only available + * for UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_UNIX_MODE "unix:mode" /* uint32 */ + +/** + * G_FILE_ATTRIBUTE_UNIX_NLINK: + * + * A key in the "unix" namespace for getting the number of hard links for a + * file. See man lstat(2). This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + * + **/ #define G_FILE_ATTRIBUTE_UNIX_NLINK "unix:nlink" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_UID: + * + * A key in the "unix" namespace for getting the user ID for the file. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_UNIX_UID "unix:uid" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_GID: + * + * A key in the "unix" namespace for getting the group ID for the file. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_UNIX_GID "unix:gid" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_RDEV: + * + * A key in the "unix" namespace for getting the device ID for the file (if it + * is a special file). See man lstat(2). This attribute is only available for + * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_UNIX_RDEV "unix:rdev" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: + * + * A key in the "unix" namespace for getting the block size for the file system. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + **/ #define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix:block_size" /* uint32 */ +/** + * G_FILE_ATTRIBUTE_UNIX_BLOCKS: + * + * A key in the "unix" namespace for getting the number of blocks allocated for the file. + * This attribute is only available for UNIX file systems. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + **/ #define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix:blocks" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: + * + * A key in the "unix" namespace for checking if the file represents a unix mount point. + * Returns %TRUE if the file is a unix mount point. This attribute is only available for + * UNIX file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix:is_mountpoint" /* boolean */ /* DOS specific attributes */ - +/** + * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE: + * + * A key in the "dos" namespace for checking if the file's archive flag is set. + * Returns %TRUE if the archive flag is set. This attribute is only available for + * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos:is_archive" /* boolean */ + +/** + * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM: + * + * A key in the "dos" namespace for checking if the file's backup flag is set. + * Returns %TRUE if the backup flag is set. This attribute is only available for + * DOS file systems. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos:is_system" /* boolean */ /* Owner attributes */ - +/** + * G_FILE_ATTRIBUTE_OWNER_USER: + * + * A key in the "owner" namespace for getting the user name of the file's owner. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_OWNER_USER "owner:user" /* string */ + +/** + * G_FILE_ATTRIBUTE_OWNER_USER_REAL: + * + * A key in the "owner" namespace for getting the real name of the user that owns the file. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner:user_real" /* string */ + +/** + * G_FILE_ATTRIBUTE_OWNER_GROUP: + * + * A key in the "owner" namespace for getting the file owner's group. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_OWNER_GROUP "owner:group" /* string */ /* Thumbnails */ +/** + * G_FILE_ATTRIBUTE_THUMBNAIL_PATH: + * + * A key in the "thumbnail" namespace for getting the path to the thumbnail image. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + **/ #define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail:path" /* bytestring */ -#define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail:failed" /* bytestring */ +/** + * G_FILE_ATTRIBUTE_THUMBNAIL_THUMNAILING_FAILED: + * + * A key in the "thumbnail" namespace for checking if thumbnailing failed. + * Is set to %TRUE if thumbnailing failed. Corresponding #GFileAttributeType + * is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ +#define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail:failed" /* boolean */ /* File system info (for g_file_get_filesystem_info) */ +/** + * 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 is + * %G_FILE_ATTRIBUTE_TYPE_UINT64. + **/ #define G_FILE_ATTRIBUTE_FS_SIZE "fs:size" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_FS_FREE: + * + * A key in the "fs" namespace for getting the free space left on the file system. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + **/ #define G_FILE_ATTRIBUTE_FS_FREE "fs:free" /* uint64 */ + +/** + * G_FILE_ATTRIBUTE_FS_TYPE: + * + * A key in the "fs" namespace for getting the file system's type. + * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_FS_TYPE "fs:type" /* string */ + +/** + * G_FILE_ATTRIBUTE_FS_READONLY: + * + * A key in the "fs" namespace for checking if the file system is read only. + * Is set to %TRUE if the file system is read only. Corresponding #GFileAttributeType is + * %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + **/ #define G_FILE_ATTRIBUTE_FS_READONLY "fs:readonly" /* boolean */ +/** + * G_FILE_ATTRIBUTE_GVFS_BACKEND: + * + * A key in the "gvfs" namespace that gets the name of the current + * GVFS backend in use. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + **/ #define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs:backend" /* string */ GType g_file_info_get_type (void) G_GNUC_CONST; diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c index 24c8a61fc..51b0ae0a2 100644 --- a/gio/gfileinputstream.c +++ b/gio/gfileinputstream.c @@ -28,6 +28,15 @@ #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:gfileinputstream + * @short_description: file input streaming operations + * @see_also: #GInputStream, #GDataInputStream, #GSeekable. + * + * + * + **/ + static void g_file_input_stream_seekable_iface_init (GSeekableIface *iface); static goffset g_file_input_stream_seekable_tell (GSeekable *seekable); static gboolean g_file_input_stream_seekable_can_seek (GSeekable *seekable); @@ -89,12 +98,19 @@ g_file_input_stream_init (GFileInputStream *stream) /** * g_file_input_stream_query_info: - * @stream: - * @attributes: + * @stream: a #GFileInputStream. + * @attributes: a file attribute query string. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Queries a file input stream the given @attributes.his function blocks while querying + * the stream. For the asynchronous (non-blocking) version of this function, see + * g_file_input_stream_query_info_async(). While the stream is blocked, + * the stream will set the pending flag internally, and any other operations on the + * stream will fail with %G_IO_ERROR_PENDING. + * + * Returns: a #GFileInfo, or %NULL on error. **/ GFileInfo * g_file_input_stream_query_info (GFileInputStream *stream, @@ -161,11 +177,19 @@ async_ready_callback_wrapper (GObject *source_object, /** * g_file_input_stream_query_info_async: - * @stream: - * @attributes: - * @io_priority: the io priority of the request. - * @cancellable: optional #GCancellable object, %NULL to ignore. @callback: - * @user_data: + * @stream: a #GFileInputStream. + * @attributes: a file attribute query string. + * @io_priority: the i/o priority of the request. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: callback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Queries the stream information asynchronously. For the synchronous version + * of this function, see g_file_input_stream_query_info(). + * + * 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 * **/ void @@ -214,10 +238,13 @@ g_file_input_stream_query_info_async (GFileInputStream *stream, /** * g_file_input_stream_query_info_finish: - * @stream: - * @result: + * @stream: a #GFileInputStream. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. + * + * Finishes an asynchronous info query operation. + * * Returns: #GFileInfo. **/ GFileInfo * @@ -244,9 +271,11 @@ g_file_input_stream_query_info_finish (GFileInputStream *stream, /** * g_file_input_stream_tell: - * @stream: + * @stream: a #GFileInputStream. * - * Returns: + * Gets the current position in the stream. + * + * Returns: a #goffset with the position in the stream. **/ goffset g_file_input_stream_tell (GFileInputStream *stream) @@ -273,7 +302,9 @@ g_file_input_stream_seekable_tell (GSeekable *seekable) /** * g_file_input_stream_can_seek: - * @stream: + * @stream: a #GFileInputStream. + * + * Checks if a file input stream can be seeked. * * Returns: %TRUE if stream can be seeked. %FALSE otherwise. **/ @@ -306,13 +337,21 @@ g_file_input_stream_seekable_can_seek (GSeekable *seekable) /** * g_file_input_stream_seek: - * @stream: - * @offset: - * @type: + * @stream: a #GFileInputStream. + * @offset: a #goffset to seek. + * @type: a #GSeekType. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Seeks in the file input stream. + * + * 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. + * + * Returns: %TRUE if the stream was successfully seeked to the position. + * %FALSE on error. **/ gboolean g_file_input_stream_seek (GFileInputStream *stream, diff --git a/gio/gfileinputstream.h b/gio/gfileinputstream.h index ecf876634..9b61ed6d9 100644 --- a/gio/gfileinputstream.h +++ b/gio/gfileinputstream.h @@ -35,6 +35,12 @@ G_BEGIN_DECLS #define G_IS_FILE_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM)) #define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass)) +/** + * GFileInputStream: + * @parent: the parent #GInputStream instance. + * + * Implements #GInputStream and #GSeekable for file input operations. + **/ typedef struct _GFileInputStream GFileInputStream; typedef struct _GFileInputStreamClass GFileInputStreamClass; typedef struct _GFileInputStreamPrivate GFileInputStreamPrivate; @@ -71,7 +77,7 @@ struct _GFileInputStreamClass GFileInfo *(*query_info_finish) (GFileInputStream *stream, GAsyncResult *res, GError **error); - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gfilemonitor.c b/gio/gfilemonitor.c index ba9fa561b..801034d8c 100644 --- a/gio/gfilemonitor.c +++ b/gio/gfilemonitor.c @@ -28,6 +28,15 @@ #include "gvfs.h" #include "glibintl.h" +/** + * SECTION:gfilemonitor + * @short_description: File Monitor + * @see_also: #GDirectoryMonitor + * + * Monitors a file for changes. + * + **/ + enum { CHANGED, LAST_SIGNAL @@ -103,6 +112,15 @@ g_file_monitor_class_init (GFileMonitorClass *klass) gobject_class->finalize = g_file_monitor_finalize; gobject_class->dispose = g_file_monitor_dispose; + /** + * GFileMonitor::changed: + * @monitor: a #GFileMonitor. + * @file: a #GFile. + * @other_file: a #GFile. + * @event_type: a #GFileMonitorEvent. + * + * Emitted when a file has been changed. + **/ signals[CHANGED] = g_signal_new (I_("changed"), G_TYPE_FILE_MONITOR, @@ -141,7 +159,9 @@ g_file_monitor_is_cancelled (GFileMonitor *monitor) /** * g_file_monitor_cancel: - * @monitor: + * @monitor: a #GFileMonitor. + * + * Cancels a file monitor. * * Returns: %TRUE if monitor was cancelled. **/ @@ -318,10 +338,13 @@ cancel_virtual_changes_done (GFileMonitor *monitor) /** * g_file_monitor_emit_event: - * @monitor: - * @file: - * @other_file: - * @event_type: + * @monitor: a #GFileMonitor. + * @file: a #GFile. + * @other_file: a #GFile. + * @event_type: a #GFileMonitorEvent + * + * Emits a file monitor event. This is mainly necessary for implementations + * of GFileMonitor. * **/ void diff --git a/gio/gfilemonitor.h b/gio/gfilemonitor.h index edb9f64be..bb96f6cad 100644 --- a/gio/gfilemonitor.h +++ b/gio/gfilemonitor.h @@ -35,6 +35,18 @@ G_BEGIN_DECLS #define G_IS_FILE_MONITOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_MONITOR)) #define G_FILE_MONITOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_MONITOR, GFileMonitorClass)) +/** + * 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. + * + * Flags used when creating a #GFileMonitor to define what events to monitor for. + **/ typedef enum { G_FILE_MONITOR_EVENT_CHANGED, G_FILE_MONITOR_EVENT_CHANGES_DONE_HINT, @@ -48,6 +60,11 @@ typedef enum { typedef struct _GFileMonitorClass GFileMonitorClass; typedef struct _GFileMonitorPrivate GFileMonitorPrivate; +/** + * GFileMonitor: + * + * Watches for changes within a #GFile. + **/ struct _GFileMonitor { GObject parent; @@ -69,7 +86,7 @@ struct _GFileMonitorClass /* Virtual Table */ gboolean (*cancel)(GFileMonitor* monitor); - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gfilenamecompleter.c b/gio/gfilenamecompleter.c index c8d85d817..a7ef20705 100644 --- a/gio/gfilenamecompleter.c +++ b/gio/gfilenamecompleter.c @@ -27,6 +27,16 @@ #include #include "glibintl.h" +/** + * SECTION:gfilenamecompleter + * @short_description: Filename Completer. + * + * Completes partial file and directory names given a partial string by + * looking in the file system for clues. Can return a list of possible + * completion strings for widget implementation. + * + **/ + enum { GOT_COMPLETION_DATA, LAST_SIGNAL @@ -84,7 +94,11 @@ g_filename_completer_class_init (GFilenameCompleterClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); gobject_class->finalize = g_filename_completer_finalize; - + /** + * GFilenameCompleter::got-completion-data: + * + * Emitted when the file name completion information comes available. + **/ signals[GOT_COMPLETION_DATA] = g_signal_new (I_("got_completion_data"), G_TYPE_FILENAME_COMPLETER, G_SIGNAL_RUN_LAST, @@ -102,7 +116,9 @@ g_filename_completer_init (GFilenameCompleter *completer) /** * g_filename_completer_new: * - * Returns: a new #GFilenameCompleter. + * Creates a new filename completer. + * + * Returns: a #GFilenameCompleter. **/ GFilenameCompleter * g_filename_completer_new (void) @@ -439,6 +455,8 @@ g_filename_completer_get_completion_suffix (GFilenameCompleter *completer, * @completer: the filename completer. * @initial_text: text to be completed. * + * Gets an array of completion strings for a given initial text. + * * Returns: array of strings with possible completions for @initial_text. * This array must be freed by g_strfreev() when finished. **/ @@ -474,7 +492,7 @@ g_filename_completer_get_completions (GFilenameCompleter *completer, /** * g_filename_completer_set_dirs_only: * @completer: the filename completer. - * @dirs_only: + * @dirs_only: a #gboolean. * * If @dirs_only is %TRUE, @completer will only * complete directory names, and not file names. diff --git a/gio/gfilenamecompleter.h b/gio/gfilenamecompleter.h index cf4cae198..4fd773458 100644 --- a/gio/gfilenamecompleter.h +++ b/gio/gfilenamecompleter.h @@ -34,6 +34,11 @@ G_BEGIN_DECLS #define G_IS_FILENAME_COMPLETER(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_FILENAME_COMPLETER)) #define G_IS_FILENAME_COMPLETER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILENAME_COMPLETER)) +/** + * GFilenameCompleter: + * + * Completes filenames based on files that exist within the file system. + **/ typedef struct _GFilenameCompleter GFilenameCompleter; typedef struct _GFilenameCompleterClass GFilenameCompleterClass; @@ -44,6 +49,7 @@ struct _GFilenameCompleterClass { /* signals */ void (* got_completion_data) (GFilenameCompleter *filename_completer); + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c index 40914d671..35eaf68b7 100644 --- a/gio/gfileoutputstream.c +++ b/gio/gfileoutputstream.c @@ -28,6 +28,15 @@ #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:gfileoutputstream + * @short_description: file output streaming operations + * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable. + * + * + * + **/ + static void g_file_output_stream_seekable_iface_init (GSeekableIface *iface); static goffset g_file_output_stream_seekable_tell (GSeekable *seekable); static gboolean g_file_output_stream_seekable_can_seek (GSeekable *seekable); @@ -89,15 +98,29 @@ g_file_output_stream_init (GFileOutputStream *stream) /** * g_file_output_stream_query_info: * @stream: a #GFileOutputStream. - * @attributes: + * @attributes: a file attribute query string. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. + * @error: a #GError, %NULL to ignore. * - * * Returns: %NULL or a #GFileInfo for the @stream. + * Queries a file output stream for the given @attributes. + * This function blocks while querying the stream. For the asynchronous + * version of this function, see g_file_output_stream_query_info_async(). + * While the stream is blocked, the stream will set the pending flag + * internally, and any other operations on the stream will fail with + * %G_IO_ERROR_PENDING. * - * For the asynchronous version of this function, see - * g_file_output_stream_query_info_async(). + * Can fail if the stream was already closed (with @error being set to + * %G_IO_ERROR_CLOSED), the stream has pending operations (with @error being + * set to %G_IO_ERROR_PENDING), or if querying info is not supported for + * the stream's interface (with @error being set to %G_IO_ERROR_NOT_SUPPORTED). In + * all cases of failure, %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 set, and %NULL will + * be returned. + * + * Returns: a #GFileInfo for the @stream, or %NULL on error. **/ GFileInfo * g_file_output_stream_query_info (GFileOutputStream *stream, @@ -165,11 +188,11 @@ async_ready_callback_wrapper (GObject *source_object, /** * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. - * @attributes: + * @attributes: a file attribute query string. * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback. - * @user_data: user data for @callback. + * @callback: callback to call when the request is satisfied + * @user_data: the data to pass to callback function * * Asynchronously queries the @stream for a #GFileInfo. When completed, * @callback will be called with a #GAsyncResult which can be used to @@ -227,8 +250,7 @@ g_file_output_stream_query_info_async (GFileOutputStream *stream, * g_file_output_stream_query_info_finish: * @stream: a #GFileOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. + * @error: a #GError, %NULL to ignore. * * Finalizes the asynchronous query started * by g_file_output_stream_query_info_async(). @@ -259,9 +281,11 @@ g_file_output_stream_query_info_finish (GFileOutputStream *stream, /** * g_file_output_stream_get_etag: - * @stream: a #GFileOutputString. + * @stream: a #GFileOutputStream. * - * Returns: + * Gets the entity tag for the file output stream. + * + * Returns: the entity tag for the stream. **/ char * g_file_output_stream_get_etag (GFileOutputStream *stream) @@ -291,9 +315,11 @@ g_file_output_stream_get_etag (GFileOutputStream *stream) /** * g_file_output_stream_tell: - * @stream: + * @stream: a #GFileOutputStream. * - * Returns: + * Gets the current location within the stream. + * + * Returns: a #goffset of the location within the stream. **/ goffset g_file_output_stream_tell (GFileOutputStream *stream) @@ -320,9 +346,11 @@ g_file_output_stream_seekable_tell (GSeekable *seekable) /** * g_file_output_stream_can_seek: - * @stream: + * @stream: a #GFileOutputStream. * - * Returns: + * Checks if the stream can be seeked. + * + * Returns: %TRUE if seeking is supported by the stream. **/ gboolean g_file_output_stream_can_seek (GFileOutputStream *stream) @@ -353,13 +381,15 @@ g_file_output_stream_seekable_can_seek (GSeekable *seekable) /** * g_file_output_stream_seek: - * @stream: - * @offset: - * @type: + * @stream: a #GFileOutputStream. + * @offset: a #goffset to seek. + * @type: a #GSeekType. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: + * @error: a #GError, %NULL to ignore. + * + * Seeks to a location in a file output stream. + * + * Returns: %TRUE if the seek was successful. %FALSE otherwise. **/ gboolean g_file_output_stream_seek (GFileOutputStream *stream, @@ -426,7 +456,9 @@ g_file_output_stream_seekable_seek (GSeekable *seekable, /** * g_file_output_stream_can_truncate: - * @stream: + * @stream: a #GFileOutputStream. + * + * Checks if the stream can be truncated. * * Returns: %TRUE if stream can be truncated. **/ @@ -459,12 +491,14 @@ g_file_output_stream_seekable_can_truncate (GSeekable *seekable) /** * g_file_output_stream_truncate: - * @stream: - * @size: + * @stream: a #GFileOutputStream. + * @size: a #goffset to truncate the stream at. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: %TRUE if @stream is truncated. + * @error: a #GError, %NULL to ignore. + * + * Truncates a file output stream. + * + * Returns: %TRUE if @stream is truncated successfully. **/ gboolean g_file_output_stream_truncate (GFileOutputStream *stream, diff --git a/gio/gfileoutputstream.h b/gio/gfileoutputstream.h index 6525754e1..5cead47f8 100644 --- a/gio/gfileoutputstream.h +++ b/gio/gfileoutputstream.h @@ -35,6 +35,12 @@ G_BEGIN_DECLS #define G_IS_FILE_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM)) #define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass)) +/** + * GFileOutputStream: + * @parent: The parent #GOutputStream instance. + * + * Implements #GOutputStream and #GSeekable for file output operations. + **/ typedef struct _GFileOutputStream GFileOutputStream; typedef struct _GFileOutputStreamClass GFileOutputStreamClass; typedef struct _GFileOutputStreamPrivate GFileOutputStreamPrivate; diff --git a/gio/gfilterinputstream.c b/gio/gfilterinputstream.c index 6d2f99a33..edeac01ff 100644 --- a/gio/gfilterinputstream.c +++ b/gio/gfilterinputstream.c @@ -25,6 +25,12 @@ #include "ginputstream.h" #include "glibintl.h" +/** + * SECTION:gfilterinputstream + * @short_description: Filter Input Stream. + * + **/ + enum { PROP_0, PROP_BASE_STREAM diff --git a/gio/gfilterinputstream.h b/gio/gfilterinputstream.h index 331f9be68..e13635946 100644 --- a/gio/gfilterinputstream.h +++ b/gio/gfilterinputstream.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_FILTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM)) #define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass)) +/** + * GFilterInputStream: + * + * Filtered input streams. Implements #GInputStream. + **/ typedef struct _GFilterInputStream GFilterInputStream; typedef struct _GFilterInputStreamClass GFilterInputStreamClass; typedef struct _GFilterInputStreamPrivate GFilterInputStreamPrivate; @@ -50,7 +55,8 @@ struct _GFilterInputStream struct _GFilterInputStreamClass { GInputStreamClass parent_class; - + + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gfilteroutputstream.c b/gio/gfilteroutputstream.c index ca41be5f9..a54683615 100644 --- a/gio/gfilteroutputstream.c +++ b/gio/gfilteroutputstream.c @@ -25,6 +25,12 @@ #include "goutputstream.h" #include "glibintl.h" +/** + * SECTION:gfilteroutputstream + * @short_description: Filter Output Stream + * + **/ + enum { PROP_0, PROP_BASE_STREAM diff --git a/gio/gfilteroutputstream.h b/gio/gfilteroutputstream.h index 604f9283d..1a131a59f 100644 --- a/gio/gfilteroutputstream.h +++ b/gio/gfilteroutputstream.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_FILTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM)) #define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass)) +/** + * GFilterOutputStream: + * + * Filtered output streams. Implements #GOutputStream. + **/ typedef struct _GFilterOutputStream GFilterOutputStream; typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass; typedef struct _GFilterOutputStreamPrivate GFilterOutputStreamPrivate; @@ -51,6 +56,7 @@ struct _GFilterOutputStreamClass { GOutputStreamClass parent_class; + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gicon.c b/gio/gicon.c index 5913ac3ad..4b2bf3f4f 100644 --- a/gio/gicon.c +++ b/gio/gicon.c @@ -74,6 +74,8 @@ g_icon_base_init (gpointer g_class) * g_icon_hash: * @icon: #gconstpointer to an icon object. * + * Gets a hash for an icon. + * * Returns: a #guint containing a hash for the @icon, suitable for * use in a #GHashTable or similar data structure. **/ @@ -94,6 +96,8 @@ g_icon_hash (gconstpointer icon) * @icon1: pointer to the first #GIcon. * @icon2: pointer to the second #GIcon. * + * Checks if two icons are equal. + * * Returns: %TRUE if @icon1 is equal to @icon2. %FALSE otherwise. **/ gboolean diff --git a/gio/gicon.h b/gio/gicon.h index 6c0dbc0de..039cbee98 100644 --- a/gio/gicon.h +++ b/gio/gicon.h @@ -32,10 +32,24 @@ G_BEGIN_DECLS #define G_IS_ICON(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ICON)) #define G_ICON_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ICON, GIconIface)) +/** + * GIcon: + * + * Icons for file, content, drive and volume types. + **/ typedef struct _GIcon GIcon; /* Dummy typedef */ typedef struct _GIconIface GIconIface; - +/** + * GIconIface: + * @g_iface: The parent interface. + * @hash: A hash for a given #GIcon. + * @equal: Checks if two #GIcons are equal. + * + * GIconIface is used to implement GIcon types for various + * different systems. See #GThemedIcon and #GLoadableIcon for + * examples of how to use this interface. + */ struct _GIconIface { GTypeInterface g_iface; diff --git a/gio/ginputstream.c b/gio/ginputstream.c index 127f5200e..77def7016 100644 --- a/gio/ginputstream.c +++ b/gio/ginputstream.c @@ -28,6 +28,14 @@ #include "gseekable.h" #include "gsimpleasyncresult.h" +/** + * SECTION:ginputstream + * @short_description: base class for implementing streaming input + * + * + * + **/ + G_DEFINE_TYPE (GInputStream, g_input_stream, G_TYPE_OBJECT); struct _GInputStreamPrivate { @@ -228,14 +236,14 @@ g_input_stream_read (GInputStream *stream, * read as many bytes as requested, only stopping on an error or end of stream. * * On a successful read of @count bytes, or if we reached the end of the - * stream, TRUE is returned, and @bytes_read is set to the number of bytes + * stream, %TRUE is returned, and @bytes_read is set to the number of bytes * read into @buffer. * - * If there is an error during the operation FALSE is returned and @error + * If there is an error during the operation %FALSE is returned and @error * is set to indicate the error status, @bytes_read is updated to contain * the number of bytes read into @buffer before the error occured. * - * Return value: TRUE on success, FALSE if there was an error + * Return value: %TRUE on success, %FALSE if there was an error **/ gboolean g_input_stream_read_all (GInputStream *stream, @@ -407,6 +415,7 @@ g_input_stream_real_skip (GInputStream *stream, /** * g_input_stream_close: * @stream: A #GInputStream. + * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: location to store the error occuring, or %NULL to ignore * * Closes the stream, releasing resources related to it. @@ -604,11 +613,14 @@ g_input_stream_read_async (GInputStream *stream, /** * g_input_stream_read_finish: - * @stream: - * @result: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Finishes an asynchronous stream read operation. + * + * Returns: number of bytes read in, or -1 on error. **/ gssize g_input_stream_read_finish (GInputStream *stream, @@ -733,11 +745,14 @@ g_input_stream_skip_async (GInputStream *stream, /** * g_input_stream_skip_finish: - * @stream: - * @result: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Finishes a stream skip operation. + * + * Returns: the size of the bytes skipped, or %-1 on error. **/ gssize g_input_stream_skip_finish (GInputStream *stream, @@ -826,11 +841,14 @@ g_input_stream_close_async (GInputStream *stream, /** * g_input_stream_close_finish: - * @stream: - * @result: + * @stream: a #GInputStream. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). + * + * Returns: %TRUE if the stream was closed successfully. **/ gboolean g_input_stream_close_finish (GInputStream *stream, @@ -862,6 +880,8 @@ g_input_stream_close_finish (GInputStream *stream, * g_input_stream_is_closed: * @stream: input stream. * + * Checks if an input stream is closed. + * * Returns: %TRUE if the stream is closed. **/ gboolean @@ -876,6 +896,8 @@ g_input_stream_is_closed (GInputStream *stream) * g_input_stream_has_pending: * @stream: input stream. * + * Checks if an input stream has pending actions. + * * Returns: %TRUE if @stream has pending actions. **/ gboolean diff --git a/gio/ginputstream.h b/gio/ginputstream.h index 7df266298..c6ec44370 100644 --- a/gio/ginputstream.h +++ b/gio/ginputstream.h @@ -37,6 +37,11 @@ G_BEGIN_DECLS #define G_IS_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_INPUT_STREAM)) #define G_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_INPUT_STREAM, GInputStreamClass)) +/** + * GInputStream: + * + * Base class for streaming input operations. + **/ typedef struct _GInputStream GInputStream; typedef struct _GInputStreamClass GInputStreamClass; typedef struct _GInputStreamPrivate GInputStreamPrivate; @@ -97,6 +102,7 @@ struct _GInputStreamClass GAsyncResult *result, GError **error); + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gioerror.c b/gio/gioerror.c index 9b1553d54..829383cd9 100644 --- a/gio/gioerror.c +++ b/gio/gioerror.c @@ -25,9 +25,17 @@ #include "gioerror.h" /** - * g_io_error_quark: + * SECTION:gioerror + * @short_description: Error helper functions. * - * Return value: The quark used as %G_IO_ERROR + **/ + +/** + * g_io_error_quark: + * + * Gets the GIO Error Quark. + * + * Return value: a #GQuark. **/ GQuark g_io_error_quark (void) @@ -35,6 +43,14 @@ g_io_error_quark (void) return g_quark_from_static_string ("g-io-error-quark"); } +/** + * g_io_error_from_errno: + * @err_no: Error number as defined in errno.h. + * + * Converts errno.h error codes into GIO error codes. + * + * Returns: #GIOErrorEnum value for the given errno.h error number. + **/ GIOErrorEnum g_io_error_from_errno (gint err_no) { diff --git a/gio/gioerror.h b/gio/gioerror.h index c4606fcec..b928a9026 100644 --- a/gio/gioerror.h +++ b/gio/gioerror.h @@ -29,6 +29,12 @@ G_BEGIN_DECLS GQuark g_io_error_quark (void); +/** + * G_IO_ERROR: + * + * Error domain for GIO. Errors in this domain will be from the #GIOErrorEnum enumeration. + * See #GError for more information on error domains. + **/ #define G_IO_ERROR g_io_error_quark() /* This enumeration conflicts with GIOError in giochannel.h. However, @@ -37,6 +43,42 @@ GQuark g_io_error_quark (void); * the actual enumeration (which is rarely used) GIOErrorEnum. */ +/** + * GIOErrorEnum: + * @G_IO_ERROR_FAILED: Generic error condition for when any operation fails. + * @G_IO_ERROR_NOT_FOUND: File not found error. + * @G_IO_ERROR_EXISTS: File already exists error. + * @G_IO_ERROR_IS_DIRECTORY: File is a directory error. + * @G_IO_ERROR_NOT_DIRECTORY: File is not a directory. + * @G_IO_ERROR_NOT_EMPTY: File is a directory that isn't empty. + * @G_IO_ERROR_NOT_REGULAR_FILE: File is not a regular file. + * @G_IO_ERROR_NOT_SYMBOLIC_LINK: File is not a symbolic link. + * @G_IO_ERROR_NOT_MOUNTABLE_FILE: File cannot be mounted. + * @G_IO_ERROR_FILENAME_TOO_LONG: Filename is too many characters. + * @G_IO_ERROR_INVALID_FILENAME: Filename is invalid or contains invalid characters. + * @G_IO_ERROR_TOO_MANY_LINKS: File contains too many symbolic links. + * @G_IO_ERROR_NO_SPACE: No space left on drive. + * @G_IO_ERROR_INVALID_ARGUMENT: Invalid argument. + * @G_IO_ERROR_PERMISSION_DENIED: Permission denied. + * @G_IO_ERROR_NOT_SUPPORTED: Operation not supported for the current backend. + * @G_IO_ERROR_NOT_MOUNTED: File isn't mounted. + * @G_IO_ERROR_ALREADY_MOUNTED: File is already mounted. + * @G_IO_ERROR_CLOSED: File was closed. + * @G_IO_ERROR_CANCELLED: Operation was cancelled. See #GCancellable. + * @G_IO_ERROR_PENDING: Operations are still pending. + * @G_IO_ERROR_READ_ONLY: File is read only. + * @G_IO_ERROR_CANT_CREATE_BACKUP: Backup couldn't be created. + * @G_IO_ERROR_WRONG_ETAG: File's Entity Tag was incorrect. + * @G_IO_ERROR_TIMED_OUT: Operation timed out. + * @G_IO_ERROR_WOULD_RECURSE: Operation would be recursive. + * @G_IO_ERROR_BUSY: File is busy. + * @G_IO_ERROR_WOULD_BLOCK: Operation would block. + * @G_IO_ERROR_HOST_NOT_FOUND: Host couldn't be found (remote operations). + * @G_IO_ERROR_WOULD_MERGE: Operation would merge files. + * + * Error codes returned by GIO functions. + * + **/ typedef enum { G_IO_ERROR_FAILED, diff --git a/gio/giomodule.c b/gio/giomodule.c index ab7c29d14..1214d817b 100644 --- a/gio/giomodule.c +++ b/gio/giomodule.c @@ -24,6 +24,15 @@ #include "giomodule.h" +/** + * SECTION:giomodule + * @short_description: Loadable GIO Modules + * + * Provides an interface and default functions for loading and unloading + * GIO modules. + * + **/ + struct _GIOModule { GTypeModule parent_instance; @@ -130,7 +139,9 @@ g_io_module_unload_module (GTypeModule *gmodule) * g_io_module_new: * @filename: filename of the module to load. * - * Returns: a new #GIOModule from given @filename, + * Loads a new module into GIO. + * + * Returns: a #GIOModule from given @filename, * or %NULL on error. **/ GIOModule * @@ -208,9 +219,10 @@ G_LOCK_DEFINE_STATIC (loaded_dirs); static GHashTable *loaded_dirs = NULL; /** - * g_io_module_ensure_loaded: - * @directory: directory to ensure is loaded. + * g_io_modules_ensure_loaded: + * @directory: string containing a directory path. * + * Loads all of the modules within the @directory. **/ void g_io_modules_ensure_loaded (const char *directory) diff --git a/gio/giomodule.h b/gio/giomodule.h index 44ed052f1..031f349a9 100644 --- a/gio/giomodule.h +++ b/gio/giomodule.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IO_IS_MODULE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_IO_TYPE_MODULE)) #define G_IO_MODULE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_IO_TYPE_MODULE, GIOModuleClass)) +/** + * GIOModule: + * + * Opaque module base class for extending GIO. + **/ typedef struct _GIOModule GIOModule; typedef struct _GIOModuleClass GIOModuleClass; @@ -44,7 +49,22 @@ GIOModule *g_io_module_new (const gchar *filename); void g_io_modules_ensure_loaded (const char *directory); /* API for the modules to implement */ +/** + * g_io_module_load: + * @module: a #GIOModule. + * + * Required API for GIO modules to implement. This function is ran after the module + * has been loaded into GIO, to initialize the module. + **/ void g_io_module_load (GIOModule *module); + +/** + * g_io_module_unload: + * @module: a #GIOModule. + * + * Required API for GIO modules to implement. This function is ran when the module + * is being unloaded from GIO, to finalize the module. + **/ void g_io_module_unload (GIOModule *module); G_END_DECLS diff --git a/gio/gioscheduler.c b/gio/gioscheduler.c index 1c5f5485d..932375516 100644 --- a/gio/gioscheduler.c +++ b/gio/gioscheduler.c @@ -24,6 +24,15 @@ #include "gioscheduler.h" +/** + * SECTION:gioscheduler + * @short_description: I/O Scheduler + * + * Schedules asynchronous I/O operations for integration into the main + * event loop (#GMainLoop). + * + **/ + struct _GIOJob { GSList *active_link; GIOJobFunc job_func; @@ -177,10 +186,10 @@ run_job_at_idle (gpointer data) * @job_func: a #GIOJobFunc. * @user_data: a #gpointer. * @notify: a #GDestroyNotify. - * @io_priority: the io priority of the request. a #gint. + * @io_priority: the i/o priority of the request. a #gint. * @cancellable: optional #GCancellable object, %NULL to ignore. * - * Schedules the @job_func. + * Schedules the I/O Job. * **/ void @@ -314,6 +323,7 @@ mainloop_proxy_notify (gpointer data) * @notify: a #GDestroyNotify. * @block: boolean flag indicating whether or not this job should block. * + * Sends an I/O job to the application's main loop for processing. * **/ void diff --git a/gio/gioscheduler.h b/gio/gioscheduler.h index 73f2684e5..c6da94ddf 100644 --- a/gio/gioscheduler.h +++ b/gio/gioscheduler.h @@ -28,12 +28,33 @@ G_BEGIN_DECLS +/** + * GIOJob: + * + * Opaque class for definining and scheduling IO jobs. + **/ typedef struct _GIOJob GIOJob; +/** + * GIOJobFunc: + * @job: a #GIOJob. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @user_data: the data to pass to callback function + * + * I/O Job function. + * + **/ typedef void (*GIOJobFunc) (GIOJob *job, GCancellable *cancellable, gpointer user_data); +/** + * GIODataFunc: + * @user_data: + * + * I/O Data function. + * + **/ typedef void (*GIODataFunc) (gpointer user_data); void g_schedule_io_job (GIOJobFunc job_func, diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c index 569065e94..85e8e6d8e 100644 --- a/gio/gloadableicon.c +++ b/gio/gloadableicon.c @@ -21,11 +21,19 @@ */ #include - #include "gsimpleasyncresult.h" #include "gloadableicon.h" #include "glibintl.h" +/** + * SECTION:gloadableicon + * @short_description: Loadable Icons + * @see_also: #GIcon, #GThemedIcon + * + * Implements #GIcon and adds the ability to load icons. + * + **/ + static void g_loadable_icon_real_load_async (GLoadableIcon *icon, int size, GCancellable *cancellable, @@ -86,13 +94,17 @@ g_loadable_icon_base_init (gpointer g_class) /** * g_loadable_icon_load: - * @icon: - * @size: - * @type: + * @icon: a #GLoadableIcon. + * @size: an integer. + * @type: * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Loads a loadable icon. For the asynchronous version of this function, + * see g_loadable_icon_load_async(). + * + * Returns: a #GInputStream to read the icon from. **/ GInputStream * g_loadable_icon_load (GLoadableIcon *icon, @@ -113,12 +125,15 @@ g_loadable_icon_load (GLoadableIcon *icon, /** * g_loadable_icon_load_async: - * @icon: - * @size: - * @cancellable: optional #GCancellable object, %NULL to ignore. @callback: - * @user_data: + * @icon: a #GLoadableIcon. + * @size: an integer. + * @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 * - * Loads an icon asynchronously. + * Loads an icon asynchronously. To finish this function, see + * g_loadable_icon_load_finish(). For the synchronous, blocking + * version of this function, see g_loadable_icon_load(). * **/ void @@ -140,12 +155,15 @@ g_loadable_icon_load_async (GLoadableIcon *icon, /** * g_loadable_icon_load_finish: - * @icon: - * @res: + * @icon: a #GLoadableIcon. + * @res: a #GAsyncResult. * @type: * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). + * + * Returns: a #GInputStream to read the icon from. **/ GInputStream * g_loadable_icon_load_finish (GLoadableIcon *icon, diff --git a/gio/gloadableicon.h b/gio/gloadableicon.h index ef203d709..fdbece22e 100644 --- a/gio/gloadableicon.h +++ b/gio/gloadableicon.h @@ -34,10 +34,24 @@ G_BEGIN_DECLS #define G_IS_LOADABLE_ICON(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_LOADABLE_ICON)) #define G_LOADABLE_ICON_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_LOADABLE_ICON, GLoadableIconIface)) +/** + * GLoadableIcon: + * + * Dummy type for subclassing loadable icon types. + **/ typedef struct _GLoadableIcon GLoadableIcon; /* Dummy typedef */ typedef struct _GLoadableIconIface GLoadableIconIface; - +/** + * GLoadableIconIface: + * @g_iface: The parent interface. + * @load: Loads an icon. + * @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 { GTypeInterface g_iface; diff --git a/gio/glocalfileoutputstream.c b/gio/glocalfileoutputstream.c index c8b58c9da..db51aad01 100644 --- a/gio/glocalfileoutputstream.c +++ b/gio/glocalfileoutputstream.c @@ -400,15 +400,6 @@ g_local_file_output_stream_query_info (GFileOutputStream *stream, error); } -/** - * g_local_file_output_stream_create: - * @filename: - * @flags: - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: #GFileOutputStream. - **/ GFileOutputStream * g_local_file_output_stream_create (const char *filename, GFileCreateFlags flags, @@ -452,15 +443,6 @@ g_local_file_output_stream_create (const char *filename, return G_FILE_OUTPUT_STREAM (stream); } -/** - * g_local_file_output_stream_append: - * @filename: - * @flags: - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: - **/ GFileOutputStream * g_local_file_output_stream_append (const char *filename, GFileCreateFlags flags, @@ -834,17 +816,6 @@ handle_overwrite_open (const char *filename, return -1; } -/** - * g_local_file_output_stream_replace: - * @filename: the file name. - * @etag: - * @create_backup: if set, create a backup of the file. - * @flags: - * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: #GFileOutputStream - **/ GFileOutputStream * g_local_file_output_stream_replace (const char *filename, const char *etag, diff --git a/gio/gmemoryinputstream.c b/gio/gmemoryinputstream.c index fea27a4d7..ee29df1fd 100644 --- a/gio/gmemoryinputstream.c +++ b/gio/gmemoryinputstream.c @@ -21,15 +21,23 @@ */ #include - #include "gmemoryinputstream.h" #include "ginputstream.h" #include "gseekable.h" #include "string.h" #include "gsimpleasyncresult.h" - #include "glibintl.h" +/** + * SECTION:gmemoryinputstream + * @short_description: streaming input operations on memory chunks + * @see_also: #GMemoryOutputStream. + * + * #GMemoryInputStream is a class for using arbitrary + * memory chunks as input for GIO streaming input operations. + * + */ + struct _GMemoryInputStreamPrivate { guint8 *buffer; gsize pos; diff --git a/gio/gmemoryinputstream.h b/gio/gmemoryinputstream.h index d62cb7fb2..3f39b0c18 100644 --- a/gio/gmemoryinputstream.h +++ b/gio/gmemoryinputstream.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_MEMORY_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_INPUT_STREAM)) #define G_MEMORY_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_INPUT_STREAM, GMemoryInputStreamClass)) +/** + * GMemoryInputStream: + * + * Implements #GInputStream for arbitrary memory chunks. + **/ typedef struct _GMemoryInputStream GMemoryInputStream; typedef struct _GMemoryInputStreamClass GMemoryInputStreamClass; typedef struct _GMemoryInputStreamPrivate GMemoryInputStreamPrivate; diff --git a/gio/gmemoryoutputstream.c b/gio/gmemoryoutputstream.c index 966f34be0..ae5ac9def 100644 --- a/gio/gmemoryoutputstream.c +++ b/gio/gmemoryoutputstream.c @@ -28,6 +28,16 @@ #include "string.h" #include "glibintl.h" +/** + * SECTION:gmemoryoutputstream + * @short_description: streaming output operations on memory chunks + * @see_also: #GMemoryInputStream. + * + * #GMemoryOutputStream is a class for using arbitrary + * memory chunks as output for GIO streaming output operations. + * + */ + struct _GMemoryOutputStreamPrivate { GByteArray *data; diff --git a/gio/gmemoryoutputstream.h b/gio/gmemoryoutputstream.h index bcb3cc7de..5fc32f38a 100644 --- a/gio/gmemoryoutputstream.h +++ b/gio/gmemoryoutputstream.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_MEMORY_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_OUTPUT_STREAM)) #define G_MEMORY_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_OUTPUT_STREAM, GMemoryOutputStreamClass)) +/** + * GMemoryOutputStream: + * + * Implements #GOutputStream for arbitrary memory chunks. + **/ typedef struct _GMemoryOutputStream GMemoryOutputStream; typedef struct _GMemoryOutputStreamClass GMemoryOutputStreamClass; typedef struct _GMemoryOutputStreamPrivate GMemoryOutputStreamPrivate; @@ -51,6 +56,7 @@ struct _GMemoryOutputStreamClass { GOutputStreamClass parent_class; + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gmountoperation.c b/gio/gmountoperation.c index 034854bd3..4c0895e31 100644 --- a/gio/gmountoperation.c +++ b/gio/gmountoperation.c @@ -28,6 +28,21 @@ #include "gio-marshal.h" #include "glibintl.h" +/** + * SECTION:gmountoperation + * @short_description: Authentication methods for mountable locations. + * + * #GMountOperation provides a mechanism for authenticating mountable + * operations, such as loop mounting files, hard drive partitions or + * server locations. + * + * Mountable GIO backends should implement #GMountOperation if they + * require any priviledges 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. + **/ + G_DEFINE_TYPE (GMountOperation, g_mount_operation, G_TYPE_OBJECT); enum { @@ -112,6 +127,16 @@ g_mount_operation_class_init (GMountOperationClass *klass) klass->ask_password = ask_password; klass->ask_question = ask_question; + /** + * GMountOperation::ask-password: + * @op: a #GMountOperation requesting a password. + * @message: string containing a message to display to the user. + * @default_user: string containing the default user name. + * @default_domain: string containing the default domain. + * @flags: a set of #GPasswordFlags. + * + * Emitted when a mount operation asks the user for a password. + */ signals[ASK_PASSWORD] = g_signal_new (I_("ask_password"), G_TYPE_FROM_CLASS (gobject_class), @@ -121,7 +146,16 @@ g_mount_operation_class_init (GMountOperationClass *klass) _gio_marshal_BOOLEAN__STRING_STRING_STRING_INT, G_TYPE_BOOLEAN, 4, G_TYPE_STRING, G_TYPE_STRING, G_TYPE_STRING, G_TYPE_UINT); - + + /** + * GMountOperation::ask-question: + * @op: a #GMountOperation asking a question. + * @message: string containing a message to display to the user. + * @choices: an array of strings for each possible choice. + * + * Emitted when asking the user a question and gives a list of choices for the + * user to choose from. + */ signals[ASK_QUESTION] = g_signal_new (I_("ask_question"), G_TYPE_FROM_CLASS (gobject_class), @@ -131,7 +165,14 @@ g_mount_operation_class_init (GMountOperationClass *klass) _gio_marshal_BOOLEAN__STRING_POINTER, G_TYPE_BOOLEAN, 2, G_TYPE_STRING, G_TYPE_POINTER); - + + /** + * GMountOperation::reply: + * @op: a #GMountOperation. + * @abort: a gboolean indicating %TRUE if the operation was aborted. + * + * Emitted when the user has replied to the mount operation. + */ signals[REPLY] = g_signal_new (I_("reply"), G_TYPE_FROM_CLASS (gobject_class), @@ -154,7 +195,9 @@ g_mount_operation_init (GMountOperation *operation) /** * g_mount_operation_new: * - * Returns: a new #GMountOperation. + * Creates a new mount operation. + * + * Returns: a #GMountOperation. **/ GMountOperation * g_mount_operation_new (void) @@ -164,9 +207,11 @@ g_mount_operation_new (void) /** * g_mount_operation_get_username - * @op: + * @op: a #GMountOperation. * - * Returns: + * Get the user name from the mount operation. + * + * Returns: a string containing the user name. **/ const char * g_mount_operation_get_username (GMountOperation *op) @@ -177,8 +222,10 @@ g_mount_operation_get_username (GMountOperation *op) /** * g_mount_operation_set_username: - * @op: + * @op: a #GMountOperation. * @username: input username. + * + * Sets the user name within @op to @username. * **/ void @@ -192,9 +239,11 @@ g_mount_operation_set_username (GMountOperation *op, /** * g_mount_operation_get_password: - * @op: - * - * Returns: + * @op: a #GMountOperation. + * + * Gets a password from the mount operation. + * + * Returns: a string containing the password within @op. **/ const char * g_mount_operation_get_password (GMountOperation *op) @@ -205,7 +254,7 @@ g_mount_operation_get_password (GMountOperation *op) /** * g_mount_operation_set_password: - * @op: the given #GMountOperation. + * @op: a #GMountOperation. * @password: password to set. * * Sets the mount operation's password to @password. @@ -222,7 +271,10 @@ g_mount_operation_set_password (GMountOperation *op, /** * g_mount_operation_get_anonymous: - * @op: + * @op: a #GMountOperation. + * + * Check to see whether the mount operation is being used + * for an anonymous user. * * Returns: %TRUE if mount operation is anonymous. **/ @@ -235,9 +287,10 @@ g_mount_operation_get_anonymous (GMountOperation *op) /** * g_mount_operation_set_anonymous: - * @op: the given #GMountOperation. + * @op: a #GMountOperation. * @anonymous: boolean value. * + * Sets the mount operation to use an anonymous user if @anonymous is %TRUE. **/ void g_mount_operation_set_anonymous (GMountOperation *op, @@ -249,9 +302,11 @@ g_mount_operation_set_anonymous (GMountOperation *op, /** * g_mount_operation_get_domain: - * @op: + * @op: a #GMountOperation. * - * Returns: a const string set to the domain. + * Gets the domain of the mount operation. + * + * Returns: a string set to the domain. **/ const char * g_mount_operation_get_domain (GMountOperation *op) @@ -262,7 +317,7 @@ g_mount_operation_get_domain (GMountOperation *op) /** * g_mount_operation_set_domain: - * @op: the given #GMountOperation. + * @op: a #GMountOperation. * @domain: the domain to set. * * Sets the mount operation's domain. @@ -278,9 +333,11 @@ g_mount_operation_set_domain (GMountOperation *op, /** * g_mount_operation_get_password_save: - * @op: the given #GMountOperation. + * @op: a #GMountOperation. + * + * Gets the state of saving passwords for the mount operation. * - * Returns: #GPasswordSave. + * Returns: a #GPasswordSave flag. **/ GPasswordSave @@ -291,9 +348,11 @@ g_mount_operation_get_password_save (GMountOperation *op) } /** - * g_mount_operation_set_password_save - * @op: - * @save: #GPasswordSave + * g_mount_operation_set_password_save: + * @op: a #GMountOperation. + * @save: a set of #GPasswordSave flags. + * + * Sets the state of saving passwords for the mount operation. * **/ void @@ -306,9 +365,12 @@ g_mount_operation_set_password_save (GMountOperation *op, /** * g_mount_operation_get_choice: - * @op: + * @op: a #GMountOperation. * - * Returns: + * Gets a choice from the mount operation. + * + * Returns: an integer containing an index of the user's choice from + * the choice's list, or %0. **/ int g_mount_operation_get_choice (GMountOperation *op) @@ -319,9 +381,10 @@ g_mount_operation_get_choice (GMountOperation *op) /** * g_mount_operation_set_choice: - * @op: - * @choice: - * + * @op: a #GMountOperation. + * @choice: an integer. + * + * Sets a default choice for the mount operation. **/ void g_mount_operation_set_choice (GMountOperation *op, @@ -333,11 +396,10 @@ g_mount_operation_set_choice (GMountOperation *op, /** * g_mount_operation_reply: - * @op: #GMountOperation. + * @op: a #GMountOperation. * @abort: boolean. * - * Emits the #GMountOperation::Reply signal with the abort flag set to - * @abort. + * Emits the #GMountOperation::reply signal. **/ void g_mount_operation_reply (GMountOperation *op, diff --git a/gio/gmountoperation.h b/gio/gmountoperation.h index 3b730b5ff..a07bc28b3 100644 --- a/gio/gmountoperation.h +++ b/gio/gmountoperation.h @@ -36,6 +36,12 @@ G_BEGIN_DECLS #define G_IS_MOUNT_OPERATION_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MOUNT_OPERATION)) #define G_MOUNT_OPERATION_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MOUNT_OPERATION, GMountOperationClass)) +/** + * GMountOperation: + * + * Class for providing authentication methods for mounting operations, + * such as mounting a file locally, or authenticating with a server. + **/ typedef struct _GMountOperation GMountOperation; typedef struct _GMountOperationClass GMountOperationClass; typedef struct _GMountOperationPrivate GMountOperationPrivate; @@ -47,6 +53,19 @@ struct _GMountOperation GMountOperationPrivate *priv; }; +/** + * GPasswordFlags: + * @G_PASSWORD_FLAGS_NEED_PASSWORD: operation requires a password. + * @G_PASSWORD_FLAGS_NEED_USERNAME: operation requires a username. + * @G_PASSWORD_FLAGS_NEED_DOMAIN: operation requires a domain. + * @G_PASSWORD_FLAGS_SAVING_SUPPORTED: operation supports saving settings. + * @G_PASSWORD_FLAGS_ANON_SUPPORTED: operation supports anonymous users. + * + * #GPasswordFlags are used to request specific information from the + * user, or to notify the user of their choices in an authentication + * situation. + * + **/ typedef enum { G_PASSWORD_FLAGS_NEED_PASSWORD = 1<<0, G_PASSWORD_FLAGS_NEED_USERNAME = 1<<1, @@ -55,6 +74,14 @@ typedef enum { G_PASSWORD_FLAGS_ANON_SUPPORTED = 1<<5 } GPasswordFlags; +/** + * GPasswordSave: + * @G_PASSWORD_SAVE_NEVER: never save a password. + * @G_PASSWORD_SAVE_FOR_SESSION: save a password for the session. + * @G_PASSWORD_SAVE_PERMANENTLY: save a password permanently. + * + * #GPasswordSave is used to indicate the lifespan of a saved password. + **/ typedef enum { G_PASSWORD_SAVE_NEVER, G_PASSWORD_SAVE_FOR_SESSION, @@ -72,15 +99,15 @@ struct _GMountOperationClass const char *default_user, const char *default_domain, GPasswordFlags flags); - + gboolean (* ask_question) (GMountOperation *op, const char *message, const char *choices[]); - + void (* reply) (GMountOperation *op, gboolean abort); - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/goutputstream.c b/gio/goutputstream.c index 514ea87ba..931e76400 100644 --- a/gio/goutputstream.c +++ b/gio/goutputstream.c @@ -21,11 +21,18 @@ */ #include - #include "goutputstream.h" #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:goutputstream + * @short_description: base class for implementing streaming output + * + * + * + **/ + G_DEFINE_TYPE (GOutputStream, g_output_stream, G_TYPE_OBJECT); struct _GOutputStreamPrivate { @@ -293,11 +300,11 @@ g_output_stream_write_all (GOutputStream *stream, * * This function is optional for inherited classes. * - * If @cancellable is not NULL, then the operation can be cancelled by + * 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. * - * Return value: TRUE on success, FALSE on error + * Return value: %TRUE on success, %FALSE on error **/ gboolean g_output_stream_flush (GOutputStream *stream, @@ -344,15 +351,16 @@ g_output_stream_flush (GOutputStream *stream, /** * g_output_stream_splice: - * @stream: - * @source: - * @flags: + * @stream: a #GOutputStream. + * @source: a #GInputStream. + * @flags: a set of #GOutputStreamSpliceFlags. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. * + * Splices an input stream into an output stream. * - * Returns: + * Returns: a #gssize containig the size of the data spliced. **/ gssize g_output_stream_splice (GOutputStream *stream, @@ -697,8 +705,9 @@ g_output_stream_write_async (GOutputStream *stream, * @error: a #GError location to store the error occuring, or %NULL to * ignore. * + * Finishes a stream write operation. * - * Returns: + * Returns: a #gssize containing the number of bytes written to the stream. **/ gssize g_output_stream_write_finish (GOutputStream *stream, @@ -752,13 +761,15 @@ async_ready_splice_callback_wrapper (GObject *source_object, /** * g_output_stream_splice_async: - * @stream: - * @source: - * @flags: + * @stream: a #GOutputStream. + * @source: a #GInputStream. + * @flags: a set of #GOutputStreamSpliceFlags. * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: - * @user_data: + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * + * Splices a stream asynchronously. * **/ void @@ -827,7 +838,9 @@ g_output_stream_splice_async (GOutputStream *stream, * @error: a #GError location to store the error occuring, or %NULL to * ignore. * - * Returns: + * Finishes an asynchronous stream splice operation. + * + * Returns: a #gssize of the number of bytes spliced. **/ gssize g_output_stream_splice_finish (GOutputStream *stream, @@ -853,11 +866,13 @@ g_output_stream_splice_finish (GOutputStream *stream, /** * g_output_stream_flush_async: - * @stream: + * @stream: a #GOutputStream. * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback. - * @user_data: + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Flushes a stream asynchronously. * **/ void @@ -918,6 +933,9 @@ g_output_stream_flush_async (GOutputStream *stream, * @result: a GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. + * + * Finishes flushing an output stream. + * * Returns: %TRUE if flush operation suceeded, %FALSE otherwise. **/ gboolean @@ -1006,11 +1024,14 @@ g_output_stream_close_async (GOutputStream *stream, /** * g_output_stream_close_finish: - * @stream: - * @result: + * @stream: a #GOutputStream. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: %TRUE, %FALSE otherwise. + * + * Closes an output stream. + * + * Returns: %TRUE if stream was successfully closed, %FALSE otherwise. **/ gboolean g_output_stream_close_finish (GOutputStream *stream, @@ -1040,7 +1061,9 @@ g_output_stream_close_finish (GOutputStream *stream, /** * g_output_stream_is_closed: - * @stream: + * @stream: a #GOutputStream. + * + * Checks if an output stream has already been closed. * * Returns: %TRUE if @stream is closed. %FALSE otherwise. **/ @@ -1054,7 +1077,9 @@ g_output_stream_is_closed (GOutputStream *stream) /** * g_output_stream_has_pending: - * @stream: + * @stream: a #GOutputStream. + * + * Checks if an ouput stream has pending actions. * * Returns: %TRUE if @stream has pending actions. **/ @@ -1068,11 +1093,10 @@ g_output_stream_has_pending (GOutputStream *stream) /** * g_output_stream_set_pending: - * @stream: - * @pending: - * - * Sets the @stream as having pending actions. + * @stream: a #GOutputStream. + * @pending: a #gboolean. * + * Sets the @stream as having pending actions if @pending is %TRUE. **/ void g_output_stream_set_pending (GOutputStream *stream, diff --git a/gio/goutputstream.h b/gio/goutputstream.h index 4bfb621e2..d62afc25d 100644 --- a/gio/goutputstream.h +++ b/gio/goutputstream.h @@ -38,12 +38,29 @@ G_BEGIN_DECLS #define G_IS_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_OUTPUT_STREAM)) #define G_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_OUTPUT_STREAM, GOutputStreamClass)) +/** + * GOutputStreamSpliceFlags: + * @G_OUTPUT_STREAM_SPLICE_FLAGS_NONE: + * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE: + * @G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET: + * + * + **/ typedef enum { G_OUTPUT_STREAM_SPLICE_FLAGS_NONE = 0, G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_SOURCE = 1 << 0, G_OUTPUT_STREAM_SPLICE_FLAGS_CLOSE_TARGET = 1 << 1 } GOutputStreamSpliceFlags; +/** + * GOutputStream: + * + * Base class for writing output. + * + * All classes derived from GOutputStream should implement synchronous + * writing, splicing, flushing and closing streams, but may implement + * asynchronous versions. + **/ typedef struct _GOutputStream GOutputStream; typedef struct _GOutputStreamClass GOutputStreamClass; typedef struct _GOutputStreamPrivate GOutputStreamPrivate; @@ -119,6 +136,7 @@ struct _GOutputStreamClass GAsyncResult *result, GError **error); + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gpollfilemonitor.c b/gio/gpollfilemonitor.c index 0b5a5e79d..4c15ad2e5 100644 --- a/gio/gpollfilemonitor.c +++ b/gio/gpollfilemonitor.c @@ -192,7 +192,9 @@ got_initial_info (GObject *source_object, /** * g_poll_file_monitor_new: - * @file: + * @file: a #GFile. + * + * Polls @file for changes. * * Returns a new #GFileMonitor for the given #GFile. **/ diff --git a/gio/gseekable.c b/gio/gseekable.c index 90f53da0a..bc2a2b219 100644 --- a/gio/gseekable.c +++ b/gio/gseekable.c @@ -24,6 +24,17 @@ #include "gseekable.h" #include "glibintl.h" +/** + * SECTION:gseekable + * @short_description: Stream seeking interface. + * @see_also: #GInputStream, #GOutputStream. + * + * #GSeekable is implemented by streams (implementations of + * #GInputStream or #GOutputStream) that support seeking. + * + **/ + + static void g_seekable_base_init (gpointer g_class); @@ -64,9 +75,11 @@ g_seekable_base_init (gpointer g_class) /** * g_seekable_tell: - * @seekable: + * @seekable: a #GSeekable. * - * Returns: a goffset. + * Tells the current position within the stream. + * + * Returns: the offset from the beginning of the buffer. **/ goffset g_seekable_tell (GSeekable *seekable) @@ -82,7 +95,9 @@ g_seekable_tell (GSeekable *seekable) /** * g_seekable_can_seek: - * @seekable: + * @seekable: a #GSeekable. + * + * Tests if the stream supports the #GSeekableIface. * * Returns: %TRUE if @seekable can be seeked. %FALSE otherwise. **/ @@ -100,13 +115,22 @@ g_seekable_can_seek (GSeekable *seekable) /** * g_seekable_seek: - * @seekable: - * @offset: - * @type: + * @seekable: a #GSeekable. + * @offset: a #goffset. + * @type: a #GSeekType. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: %TRUE, %FALSE otherwise. + * + * Seeks in the stream by the given @offset, modified by @type. + * + * 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 successful. If an error + * has occured, this function will return %FALSE and set @error + * appropriately if present. **/ gboolean g_seekable_seek (GSeekable *seekable, @@ -126,9 +150,11 @@ g_seekable_seek (GSeekable *seekable, /** * g_seekable_can_truncate: - * @seekable: + * @seekable: a #GSeekable. * - * Returns: + * Tests if the stream can be truncated. + * + * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. **/ gboolean g_seekable_can_truncate (GSeekable *seekable) @@ -144,12 +170,23 @@ g_seekable_can_truncate (GSeekable *seekable) /** * g_seekable_truncate: - * @seekable: - * @offset: + * @seekable: a #GSeekable. + * @offset: a #goffset. * @cancellable: optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: + * + * Truncates a stream with a given #offset. + * + * 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 an + * operation was partially finished when the operation was cancelled the + * partial result will be returned, without an error. + * + * Returns: %TRUE if successful. If an error + * has occured, this function will return %FALSE and set @error + * appropriately if present. **/ gboolean g_seekable_truncate (GSeekable *seekable, diff --git a/gio/gseekable.h b/gio/gseekable.h index 33fc619b8..b289df587 100644 --- a/gio/gseekable.h +++ b/gio/gseekable.h @@ -33,9 +33,25 @@ G_BEGIN_DECLS #define G_IS_SEEKABLE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_SEEKABLE)) #define G_SEEKABLE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_SEEKABLE, GSeekableIface)) +/** + * GSeekable: + * + * Seek object for streaming operations. + **/ typedef struct _GSeekable GSeekable; typedef struct _GSeekableIface GSeekableIface; +/** + * GSeekableIface: + * @g_iface: The parent interface. + * @tell: Tells the current location within a stream. + * @can_seek: Checks if seeking is supported by the stream. + * @seek: Seeks to a location within a stream. + * @can_truncate: Chekcs if truncation is suppored by the stream. + * @truncate: Truncates a stream. + * + * Provides an interface for implementing seekable functionality on I/O Streams. + **/ struct _GSeekableIface { GTypeInterface g_iface; diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c index 3c69f19d9..bc4f63513 100644 --- a/gio/gsimpleasyncresult.c +++ b/gio/gsimpleasyncresult.c @@ -34,6 +34,58 @@ #include #include "glibintl.h" +/** + * SECTION:gsimpleasyncresult + * @short_description: simple asynchronous results implementation. + * @see_also: #GAsyncResult. + * + * Implements #GAsyncResult for simple cases. Most of the time, this + * will be all an application needs, and will be used transparently. + * Because of this, #GSimpleAsyncResult is used throughout GIO for + * handling asynchronous functions. + * + * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error reporting, + * operation cancellation and the final state of an operation, completely + * transparent to the application. Results can be returned as a pointer e.g. + * for functions that return data that is collected asynchronously, + * a boolean value for checking the success or failure of an operation, + * or a #gssize for operations which return the number of bytes modified + * by the operation; all of the simple return cases are covered. + * + * Most of the time, an application will not need to know of the details + * of this API; it is handled transparently, and any necessary operations are handled by + * #GAsyncResult's interface. However, if implementing a new GIO module, for writing + * language bindings, or for complex applications that need better control of how + * asynchronous operations are completed, it is important to understand this functionality. + * + * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). If the + * result needs to be created for a #GError, use g_simple_async_result_new_from_error(). + * If a #GError is not available (e.g. the asynchronous operation's doesn't take a #GError + * argument), but the result still needs to be created for an error condition, use + * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() + * if your application or binding requires passing a variable argument list directly), + * and the error can then be propegated through the use of g_simple_async_result_propagate_error(). + * + * An asynchronous operation can be made to ignore a cancellation event by calling + * g_simple_async_result_set_handle_cancellation() with a #GSimpleAsyncResult for the operation + * and %FALSE. + * + * GSimpleAsyncResult can integrate into GLib's Main Event Loop , + * or it can use #GThreads if available. g_simple_async_result_complete() will finish an + * I/O task directly within the main event loop. g_simple_async_result_complete_in_idle() will integrate + * the I/O task into the main event loop as an idle function and g_simple_async_result_run_in_thread() + * will run the job in a separate thread. + * + * To set the results of an asynchronous function, g_simple_async_result_set_op_res_gpointer(), + * g_simple_async_result_set_op_res_gboolean(), and g_simple_async_result_set_op_res_gssize() + * are provided, setting the operation's result to a gpointer, gboolean, or gssize, respectively. + * + * Likewise, to get the result of an asynchronous function, g_simple_async_result_get_op_res_gpointer(), + * g_simple_async_result_get_op_res_gboolean(), and g_simple_async_result_get_op_res_gssize() are + * provided, getting the operation's result as a gpointer, gboolean, and gssize, respectively. + * + **/ + static void g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface); struct _GSimpleAsyncResult @@ -104,12 +156,14 @@ g_simple_async_result_init (GSimpleAsyncResult *simple) /** * g_simple_async_result_new: - * @source_object: - * @callback: - * @user_data: + * @source_object: a #GObject. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. * @source_tag: * - * Returns: #GSimpleAsyncResult + * Creates a #GSimpleAsyncResult. + * + * Returns: a #GSimpleAsyncResult. **/ GSimpleAsyncResult * g_simple_async_result_new (GObject *source_object, @@ -132,12 +186,14 @@ g_simple_async_result_new (GObject *source_object, /** * g_simple_async_result_new_from_error: - * @source_object: - * @callback: - * @user_data: - * @error: a #GError location to store the error occuring, or %NULL to - * ignore. - * Returns: #GSimpleAsyncResult + * @source_object: a #GObject. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @error: a #GError location. + * + * Creates a #GSimpleAsyncResult from an error condition. + * + * Returns: a #GSimpleAsyncResult. **/ GSimpleAsyncResult * g_simple_async_result_new_from_error (GObject *source_object, @@ -159,15 +215,17 @@ g_simple_async_result_new_from_error (GObject *source_object, /** * g_simple_async_result_new_error: - * @source_object: - * @callback: - * @user_data: - * @domain: - * @code: - * @format: - * @... + * @source_object: a #GObject. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @Varargs: a list of values to insert into @format. * - * Returns: #GSimpleAsyncResult. + * Creates a new #GSimpleAsyncResult with a set error. + * + * Returns: a #GSimpleAsyncResult. **/ GSimpleAsyncResult * g_simple_async_result_new_error (GObject *source_object, @@ -220,8 +278,10 @@ g_simple_async_result_async_result_iface_init (GAsyncResultIface *iface) /** * g_simple_async_result_set_handle_cancellation: - * @simple: - * @handle_cancellation: + * @simple: a #GSimpleAsyncResult. + * @handle_cancellation: a #gboolean. + * + * Sets whether to handle cancellation within the asynchronous operation. * **/ void @@ -234,9 +294,11 @@ g_simple_async_result_set_handle_cancellation (GSimpleAsyncResult *simple, /** * g_simple_async_result_get_source_tag: - * @simple: + * @simple: a #GSimpleAsyncResult. * - * Returns: + * Gets the source tag for the #GSimpleAsyncResult. + * + * Returns: a #gpointer to the source object for the #GSimpleAsyncResult. **/ gpointer g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple) @@ -246,11 +308,14 @@ g_simple_async_result_get_source_tag (GSimpleAsyncResult *simple) } /** - * g_simple_async_result_result_propagate_error: - * @simple: - * @dest: + * g_simple_async_result_propagate_error: + * @simple: a #GSimpleAsyncResult. + * @dest: a location to propegate the error to. * - * Returns: + * Propegates an error from within the simple asynchronous result to + * a given destination. + * + * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise. **/ gboolean g_simple_async_result_propagate_error (GSimpleAsyncResult *simple, @@ -269,10 +334,11 @@ g_simple_async_result_propagate_error (GSimpleAsyncResult *simple, /** * g_simple_async_result_set_op_res_gpointer: - * @simple: - * @op_res: - * @destroy_op_res: + * @simple: a #GSimpleAsyncResult. + * @op_res: a pointer result from an asynchronous function. + * @destroy_op_res: a #GDestroyNotify function. * + * Sets the operation result within the asynchronous result to a pointer. **/ void g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult *simple, @@ -287,9 +353,11 @@ g_simple_async_result_set_op_res_gpointer (GSimpleAsyncResult *simple, /** * g_simple_async_result_get_op_res_gpointer: - * @simple: + * @simple: a #GSimpleAsyncResult. * - * Returns: gpointer. + * Gets a pointer result as returned by the asynchronous function. + * + * Returns: a pointer from the result. **/ gpointer g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult *simple) @@ -300,9 +368,10 @@ g_simple_async_result_get_op_res_gpointer (GSimpleAsyncResult *simple) /** * g_simple_async_result_set_op_res_gssize: - * @simple: - * @op_res: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gssize. * + * Sets the operation result within the asynchronous result to the given @op_res. **/ void g_simple_async_result_set_op_res_gssize (GSimpleAsyncResult *simple, @@ -314,9 +383,11 @@ g_simple_async_result_set_op_res_gssize (GSimpleAsyncResult *simple, /** * g_simple_async_result_get_op_res_gssize: - * @simple: + * @simple: a #GSimpleAsyncResult. * - * Returns: + * Gets a gssize from the asynchronous result. + * + * Returns: a gssize returned from the asynchronous function. **/ gssize g_simple_async_result_get_op_res_gssize (GSimpleAsyncResult *simple) @@ -327,8 +398,10 @@ g_simple_async_result_get_op_res_gssize (GSimpleAsyncResult *simple) /** * g_simple_async_result_set_op_res_gboolean: - * @simple: - * @op_res: + * @simple: a #GSimpleAsyncResult. + * @op_res: a #gboolean. + * + * Sets the operation result to a boolean within the asynchronous result. * **/ void @@ -341,9 +414,12 @@ g_simple_async_result_set_op_res_gboolean (GSimpleAsyncResult *simple, /** * g_simple_async_result_get_op_res_gboolean: - * @simple: + * @simple: a #GSimpleAsyncResult. * - * Returns a #gboolean. + * Gets the operation result boolean from within the asynchronous result. + * + * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's + * result was %FALSE. **/ gboolean g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult *simple) @@ -354,11 +430,10 @@ g_simple_async_result_get_op_res_gboolean (GSimpleAsyncResult *simple) /** * g_simple_async_result_set_from_error: - * @simple: + * @simple: a #GSimpleAsyncResult. * @error: #GError. * - * Sets the result from given @error. - * + * Sets the result from a #GError. **/ void g_simple_async_result_set_from_error (GSimpleAsyncResult *simple, @@ -390,14 +465,14 @@ _g_error_new_valist (GQuark domain, /** * g_simple_async_result_set_error_va: - * @simple: - * @domain: - * @code: - * @format: + * @simple: a #GSimpleAsyncResult. + * @domain: a #GQuark (usually #G_IO_ERROR). + * @code: an error code. + * @format: a formatted error reporting string. * @args: va_list of arguments. * - * Sets error va_list, suitable for language bindings. - * + * Sets an error within the asynchronous result without a #GError. Unless + * writing a binding, see g_simple_async_result_set_error(). **/ void g_simple_async_result_set_error_va (GSimpleAsyncResult *simple, @@ -416,11 +491,13 @@ g_simple_async_result_set_error_va (GSimpleAsyncResult *simple, /** * g_simple_async_result_set_error: - * @simple: - * @domain: - * @code: - * @format: - * @... + * @simple: a #GSimpleAsyncResult. + * @domain: a #GQuark (usually #G_IO_ERROR). + * @code: an error code. + * @format: a formatted error reporting string. + * @Varargs: a list of variables to fill in @format. + * + * Sets an error within the asynchronous result without a #GError. * **/ void @@ -443,7 +520,9 @@ g_simple_async_result_set_error (GSimpleAsyncResult *simple, /** * g_simple_async_result_complete: - * @simple: + * @simple: a #GSimpleAsyncResult. + * + * Completes an asynchronous I/O job. * **/ void @@ -469,7 +548,10 @@ complete_in_idle_cb (gpointer data) /** * g_simple_async_result_complete_in_idle: - * @simple: + * @simple: a #GSimpleAsyncResult. + * + * Completes an asynchronous function in the main event loop using + * an idle function. * **/ void @@ -525,10 +607,13 @@ run_in_thread (GIOJob *job, /** * g_simple_async_result_run_in_thread: - * @simple: - * @func: + * @simple: a #GSimpleAsyncResult. + * @func: a #GSimpleAsyncThreadFunc. * @io_priority: the io priority of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. + * + * Runs the asynchronous job in a separated thread. + * **/ void g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple, @@ -550,12 +635,14 @@ g_simple_async_result_run_in_thread (GSimpleAsyncResult *simple, /** * g_simple_async_report_error_in_idle: * @object: - * @callback: - * @user_data: - * @domain: - * @code: - * @format: - * @... + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * @domain: a #GQuark containing the error domain (usually #G_IO_ERROR). + * @code: a specific error code. + * @format: a formatted error reporting string. + * @Varargs: a list of variables to fill in @format. + * + * Reports an error in an idle function. * **/ void diff --git a/gio/gsimpleasyncresult.h b/gio/gsimpleasyncresult.h index 4c4ecf8e6..0607f8835 100644 --- a/gio/gsimpleasyncresult.h +++ b/gio/gsimpleasyncresult.h @@ -35,9 +35,23 @@ G_BEGIN_DECLS #define G_IS_SIMPLE_ASYNC_RESULT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SIMPLE_ASYNC_RESULT)) #define G_SIMPLE_ASYNC_RESULT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SIMPLE_ASYNC_RESULT, GSimpleAsyncResultClass)) +/** + * GSimpleAsyncResult: + * + * A simple implementation of #GAsyncResult. + **/ typedef struct _GSimpleAsyncResult GSimpleAsyncResult; typedef struct _GSimpleAsyncResultClass GSimpleAsyncResultClass; +/** + * GSimpleAsyncThreadFunc: + * @res: a #GSimpleAsyncResult. + * @object: a #GObject. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * + * Simple thread function that runs an asynchronous operation and + * checks for cancellation. + **/ typedef void (*GSimpleAsyncThreadFunc) (GSimpleAsyncResult *res, GObject *object, GCancellable *cancellable); diff --git a/gio/gsocketinputstream.c b/gio/gsocketinputstream.c index 890e8e1f8..1b7b2b8a1 100644 --- a/gio/gsocketinputstream.c +++ b/gio/gsocketinputstream.c @@ -37,9 +37,17 @@ #include "gsocketinputstream.h" #include "gcancellable.h" #include "gasynchelper.h" - #include "glibintl.h" +/** + * SECTION:gsocketinputstream + * @short_description: Socket Input Stream + * @see_also: #GInputStream. + * + * #GSocketInputStream implements #GInputStream for reading from a socket, + * including asynchronous operations. + **/ + G_DEFINE_TYPE (GSocketInputStream, g_socket_input_stream, G_TYPE_INPUT_STREAM); struct _GSocketInputStreamPrivate { @@ -128,12 +136,13 @@ g_socket_input_stream_init (GSocketInputStream *socket) /** * g_socket_input_stream_new: - * @fd: file descriptor. - * @close_fd_at_close: boolean value + * @fd: socket file descriptor. + * @close_fd_at_close: a #gboolean. * + * Creates a new #GSocketInputStream for the given @fd. If @close_fd_at_close + * is %TRUE, the socket will be closed when the stream is closed. * - * Returns: new #GInputStream. If @close_fd_at_close is %TRUE, - * @fd will be closed when the #GInputStream is closed. + * Returns: a #GSocketInputStream. **/ GInputStream * g_socket_input_stream_new (int fd, diff --git a/gio/gsocketinputstream.h b/gio/gsocketinputstream.h index 31b79ce50..ec98cdb85 100644 --- a/gio/gsocketinputstream.h +++ b/gio/gsocketinputstream.h @@ -34,6 +34,11 @@ G_BEGIN_DECLS #define G_IS_SOCKET_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_INPUT_STREAM)) #define G_SOCKET_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_INPUT_STREAM, GSocketInputStreamClass)) +/** + * GSocketInputStream: + * + * Implements #GInputStream for reading from sockets. + **/ typedef struct _GSocketInputStream GSocketInputStream; typedef struct _GSocketInputStreamClass GSocketInputStreamClass; typedef struct _GSocketInputStreamPrivate GSocketInputStreamPrivate; @@ -50,6 +55,7 @@ struct _GSocketInputStreamClass { GInputStreamClass parent_class; + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gsocketoutputstream.c b/gio/gsocketoutputstream.c index 54539f589..b42162feb 100644 --- a/gio/gsocketoutputstream.c +++ b/gio/gsocketoutputstream.c @@ -37,9 +37,17 @@ #include "gcancellable.h" #include "gsimpleasyncresult.h" #include "gasynchelper.h" - #include "glibintl.h" +/** + * SECTION:gsocketoutputstream + * @short_description: Socket Output Stream + * @see_also: #GOutputStream. + * + * #GSocketOutputStream implements #GOutputStream for writing to a socket, including + * asynchronous operations. + **/ + G_DEFINE_TYPE (GSocketOutputStream, g_socket_output_stream, G_TYPE_OUTPUT_STREAM); @@ -116,8 +124,11 @@ g_socket_output_stream_init (GSocketOutputStream *socket) /** * g_socket_output_stream_new: - * @fd: file descriptor. - * @close_fd_at_close: boolean value. + * @fd: socket's file descriptor. + * @close_fd_at_close: a #gboolean. + * + * Creates a new socket output stream for @fd. If @close_fd_at_close + * is %TRUE, the socket will be closed when the output stream is destroyed. * * Returns: #GOutputStream. If @close_fd_at_close is %TRUE, then * @fd will be closed when the #GOutputStream is closed. diff --git a/gio/gsocketoutputstream.h b/gio/gsocketoutputstream.h index cff198654..09527def3 100644 --- a/gio/gsocketoutputstream.h +++ b/gio/gsocketoutputstream.h @@ -34,6 +34,11 @@ G_BEGIN_DECLS #define G_IS_SOCKET_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_OUTPUT_STREAM)) #define G_SOCKET_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_OUTPUT_STREAM, GSocketOutputStreamClass)) +/** + * GSocketOutputStream: + * + * Implements #GOutputStream for outputting to sockets. + **/ typedef struct _GSocketOutputStream GSocketOutputStream; typedef struct _GSocketOutputStreamClass GSocketOutputStreamClass; typedef struct _GSocketOutputStreamPrivate GSocketOutputStreamPrivate; @@ -50,6 +55,7 @@ struct _GSocketOutputStreamClass { GOutputStreamClass parent_class; + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index e27b03374..d46c726c9 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -24,6 +24,14 @@ #include "gthemedicon.h" +/** + * SECTION:gthemedicon + * @short_description: Themed Icons + * @see_also: #GIcon, #GLoadableIcon. + * + * #GThemedIcon is an implementation of #GIcon for themed icons. + **/ + static void g_themed_icon_icon_iface_init (GIconIface *iface); struct _GThemedIcon @@ -70,9 +78,11 @@ g_themed_icon_init (GThemedIcon *themed) /** * g_themed_icon_new: - * @iconname: + * @iconname: a string containing an icon name. * - * Returns: a new #GIcon. + * Creates a new themed icon for @iconname. + * + * Returns: a new #GThemedIcon. **/ GIcon * g_themed_icon_new (const char *iconname) @@ -91,10 +101,12 @@ g_themed_icon_new (const char *iconname) /** * g_themed_icon_new_from_names: - * @iconnames: - * @len: + * @iconnames: an array of strings containing icon names. + * @len: the number of elements in the @iconnames array. * - * Returns: a new #GIcon. + * Creates a new themed icon for @iconnames. + * + * Returns: a new #GThemedIcon. **/ GIcon * g_themed_icon_new_from_names (char **iconnames, int len) @@ -121,9 +133,11 @@ g_themed_icon_new_from_names (char **iconnames, int len) /** * g_themed_icon_get_names: - * @icon: + * @icon: a #GThemedIcon. * - * Returns: + * Gets the names of icons from within @icon. + * + * Returns: a list of icon names. **/ const char * const * g_themed_icon_get_names (GThemedIcon *icon) diff --git a/gio/gthemedicon.h b/gio/gthemedicon.h index f560f1871..b249d3565 100644 --- a/gio/gthemedicon.h +++ b/gio/gthemedicon.h @@ -34,6 +34,11 @@ G_BEGIN_DECLS #define G_IS_THEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON)) #define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass)) +/** + * GThemedIcon: + * + * An implementation of #GIcon for themed icons. + **/ typedef struct _GThemedIcon GThemedIcon; typedef struct _GThemedIconClass GThemedIconClass; diff --git a/gio/gunixdrive.c b/gio/gunixdrive.c index 464399264..25e05392c 100644 --- a/gio/gunixdrive.c +++ b/gio/gunixdrive.c @@ -30,7 +30,6 @@ #include "gdriveprivate.h" #include "gthemedicon.h" #include "gvolumemonitor.h" - #include "glibintl.h" struct _GUnixDrive { diff --git a/gio/gunixmounts.c b/gio/gunixmounts.c index da23bd4c0..244581d87 100644 --- a/gio/gunixmounts.c +++ b/gio/gunixmounts.c @@ -47,6 +47,14 @@ #include "gfile.h" #include "gfilemonitor.h" +/** + * SECTION:gunixmounts + * @short_description: Unix Mounts + * + * Routines for managing mounted UNIX mount points and paths. + * + **/ + struct _GUnixMount { char *mount_path; char *device_path; @@ -898,8 +906,12 @@ get_mount_points_timestamp (void) * g_get_unix_mounts: * @time_read: guint64 to contain a timestamp. * - * Returns a #GList of the UNIX mounts. If @time_read - * is set, it will be filled with the mount timestamp. + * Gets a #GList of strings containing the unix mounts. If @time_read + * is set, it will be filled with the mount timestamp, + * allowing for checking if the mounts have changed with + * g_unix_mounts_changed_since(). + * + * Returns: a #GList of the UNIX mounts. **/ GList * g_get_unix_mounts (guint64 *time_read) @@ -912,11 +924,14 @@ g_get_unix_mounts (guint64 *time_read) /** * g_get_unix_mount_at: - * @mount_path: path to mount. + * @mount_path: path for a possible unix mount. * @time_read: guint64 to contain a timestamp. * - * Returns a #GUnixMount. If @time_read - * is set, it will be filled with the mount timestamp. + * Gets a #GUnixMount for a given mount path. If @time_read + * is set, it will be filled with a unix timestamp for checking + * if the mounts have changed since with g_unix_mounts_changed_since(). + * + * Returns: a #GUnixMount. **/ GUnixMount * g_get_unix_mount_at (const char *mount_path, @@ -947,8 +962,12 @@ g_get_unix_mount_at (const char *mount_path, * g_get_unix_mount_points: * @time_read: guint64 to contain a timestamp. * - * Returns a #GList of the UNIX mountpoints. If @time_read - * is set, it will be filled with the mount timestamp. + * Gets a #GList of strings containing the unix mount points. + * If @time_read is set, it will be filled with the mount timestamp, + * allowing for checking if the mounts have changed with + * g_unix_mounts_points_changed_since(). + * + * Returns a #GList of the UNIX mountpoints. **/ GList * g_get_unix_mount_points (guint64 *time_read) @@ -960,9 +979,11 @@ g_get_unix_mount_points (guint64 *time_read) } /** - * g_unix_mounts_change_since: + * g_unix_mounts_changed_since: * @time: guint64 to contain a timestamp. * + * Checks if the unix mounts have changed since a given unix time. + * * Returns %TRUE if the mounts have changed since @time. **/ gboolean @@ -972,9 +993,11 @@ g_unix_mounts_changed_since (guint64 time) } /** - * g_unix_mount_points_change_since: + * g_unix_mount_points_changed_since: * @time: guint64 to contain a timestamp. * + * Checks if the unix mount points have changed since a given unix time. + * * Returns %TRUE if the mount points have changed since @time. **/ gboolean @@ -1015,7 +1038,11 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); gobject_class->finalize = g_unix_mount_monitor_finalize; - + /** + * GUnixMountMonitor::mounts-changed: + * + * Emitted when the unix mounts have changed. + **/ signals[MOUNTS_CHANGED] = g_signal_new ("mounts_changed", G_TYPE_FROM_CLASS (klass), @@ -1024,7 +1051,11 @@ g_unix_mount_monitor_class_init (GUnixMountMonitorClass *klass) NULL, NULL, g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0); - + /** + * GUnixMountMonitor::mountpoints-changed: + * + * Emitted when the unix mount points have changed. + **/ signals[MOUNTPOINTS_CHANGED] = g_signal_new ("mountpoints_changed", G_TYPE_FROM_CLASS (klass), @@ -1098,7 +1129,9 @@ g_unix_mount_monitor_init (GUnixMountMonitor *monitor) /** * g_unix_mount_monitor_new: * - * Returns a new #GUnixMountMonitor. + * Gets a new #GUnixMountMonitor. + * + * Returns: a #GUnixMountMonitor. **/ GUnixMountMonitor * g_unix_mount_monitor_new (void) @@ -1116,6 +1149,7 @@ g_unix_mount_monitor_new (void) * g_unix_mount_free: * @mount_entry: a #GUnixMount. * + * Frees a unix mount. **/ void g_unix_mount_free (GUnixMount *mount_entry) @@ -1130,8 +1164,9 @@ g_unix_mount_free (GUnixMount *mount_entry) /** * g_unix_mount_point_free: - * @mount_point: + * @mount_point: unix mount point to free. * + * Frees a unix mount point. **/ void g_unix_mount_point_free (GUnixMountPoint *mount_point) @@ -1162,6 +1197,8 @@ strcmp_null (const char *str1, * @mount1: first #GUnixMount to compare. * @mount2: second #GUnixMount to compare. * + * Compares two unix mounts. + * * Returns 1, 0 or -1 if @mount1 is greater than, equal to, * or less than @mount2, respectively. **/ @@ -1196,8 +1233,9 @@ g_unix_mount_compare (GUnixMount *mount1, * g_unix_mount_get_mount_path: * @mount_entry: input #GUnixMount to get the mount path for. * - * Returns the mount path for @mount_entry. + * Gets the mount path for a unix mount. * + * Returns: the mount path for @mount_entry. **/ const char * g_unix_mount_get_mount_path (GUnixMount *mount_entry) @@ -1211,6 +1249,9 @@ g_unix_mount_get_mount_path (GUnixMount *mount_entry) * g_unix_mount_get_device_path: * @mount_entry: a #GUnixMount. * + * Gets the device path for a unix mount. + * + * Returns: a string containing the device path. **/ const char * g_unix_mount_get_device_path (GUnixMount *mount_entry) @@ -1224,6 +1265,9 @@ g_unix_mount_get_device_path (GUnixMount *mount_entry) * g_unix_mount_get_fs_type: * @mount_entry: a #GUnixMount. * + * Gets the filesystem type for the unix mount. + * + * Returns: a string containing the file system type. **/ const char * g_unix_mount_get_fs_type (GUnixMount *mount_entry) @@ -1237,8 +1281,9 @@ g_unix_mount_get_fs_type (GUnixMount *mount_entry) * g_unix_mount_is_readonly: * @mount_entry: a #GUnixMount. * - * Returns %TRUE if @mount_entry is read only. + * Checks if a unix mount is mounted read only. * + * Returns: %TRUE if @mount_entry is read only. **/ gboolean g_unix_mount_is_readonly (GUnixMount *mount_entry) @@ -1252,6 +1297,9 @@ g_unix_mount_is_readonly (GUnixMount *mount_entry) * g_unix_mount_is_system_internal: * @mount_entry: a #GUnixMount. * + * Checks if a unix mount is a system path. + * + * Returns: %TRUE if the unix mount is for a system path. **/ gboolean g_unix_mount_is_system_internal (GUnixMount *mount_entry) @@ -1266,6 +1314,8 @@ g_unix_mount_is_system_internal (GUnixMount *mount_entry) * @mount1: a #GUnixMount. * @mount2: a #GUnixMount. * + * Compares two unix mount points. + * * Returns 1, 0 or -1 if @mount1 is greater than, equal to, * or less than @mount2, respectively. **/ @@ -1306,8 +1356,11 @@ g_unix_mount_point_compare (GUnixMountPoint *mount1, /** * g_unix_mount_point_get_mount_path: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Gets the mount path for a unix mount point. + * + * Returns: a string containing the mount path. **/ const char * g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point) @@ -1319,8 +1372,11 @@ g_unix_mount_point_get_mount_path (GUnixMountPoint *mount_point) /** * g_unix_mount_point_get_device_path: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Gets the device path for a unix mount point. + * + * Returns: a string containing the device path. **/ const char * g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point) @@ -1332,8 +1388,11 @@ g_unix_mount_point_get_device_path (GUnixMountPoint *mount_point) /** * g_unix_mount_point_get_fs_type: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Gets the file system type for the mount point. + * + * Returns: a string containing the file system type. **/ const char * g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point) @@ -1345,8 +1404,11 @@ g_unix_mount_point_get_fs_type (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_readonly: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Checks if a unix mount point is read only. + * + * Returns: %TRUE if a mount point is read only. **/ gboolean g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point) @@ -1358,8 +1420,11 @@ g_unix_mount_point_is_readonly (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_user_mountable: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Checks if a unix mount point is mountable by the user. + * + * Returns: %TRUE if the mount point is user mountable. **/ gboolean g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point) @@ -1371,8 +1436,11 @@ g_unix_mount_point_is_user_mountable (GUnixMountPoint *mount_point) /** * g_unix_mount_point_is_loopback: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Checks if a unix mount point is a loopback device. + * + * Returns: %TRUE if the mount point is a loopback. %FALSE otherwise. **/ gboolean g_unix_mount_point_is_loopback (GUnixMountPoint *mount_point) @@ -1482,6 +1550,10 @@ guess_mount_type (const char *mount_path, * g_unix_mount_guess_type: * @mount_entry: a #GUnixMount. * + * Guesses the type of a unix mount. If the mount type cannot be + * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * + * Returns: a #GUnixMountType. **/ GUnixMountType g_unix_mount_guess_type (GUnixMount *mount_entry) @@ -1498,8 +1570,12 @@ g_unix_mount_guess_type (GUnixMount *mount_entry) /** * g_unix_mount_point_guess_type: - * @mount_point: a #GUnixMount. + * @mount_point: a #GUnixMountPoint. * + * Guesses the type of a unix mount point. If the mount type cannot be + * determined, returns %G_UNIX_MOUNT_TYPE_UNKNOWN. + * + * Returns: a #GUnixMountType. **/ GUnixMountType g_unix_mount_point_guess_type (GUnixMountPoint *mount_point) diff --git a/gio/gunixmounts.h b/gio/gunixmounts.h index 7e9c03b11..401612c3f 100644 --- a/gio/gunixmounts.h +++ b/gio/gunixmounts.h @@ -28,9 +28,38 @@ G_BEGIN_DECLS +/** + * GUnixMount: + * + * Defines a Unix mount. + **/ typedef struct _GUnixMount GUnixMount; + +/** + * GUnixMountPoint: + * + * Defines a Unix mount point (e.g. "/dev"). + **/ typedef struct _GUnixMountPoint GUnixMountPoint; +/** + * GUnixMountType: + * @G_UNIX_MOUNT_TYPE_UNKNOWN: Unknown UNIX mount type. + * @G_UNIX_MOUNT_TYPE_FLOPPY: Floppy disk UNIX mount type. + * @G_UNIX_MOUNT_TYPE_CDROM: CDROM UNIX mount type. + * @G_UNIX_MOUNT_TYPE_NFS: Network File System (NFS) UNIX mount type. + * @G_UNIX_MOUNT_TYPE_ZIP: ZIP UNIX mount type. + * @G_UNIX_MOUNT_TYPE_JAZ: JAZZ UNIX mount type. + * @G_UNIX_MOUNT_TYPE_MEMSTICK: Memory Stick UNIX mount type. + * @G_UNIX_MOUNT_TYPE_CF: Compact Flash UNIX mount type. + * @G_UNIX_MOUNT_TYPE_SM: Smart Media UNIX mount type. + * @G_UNIX_MOUNT_TYPE_SDMMC: SD/MMC UNIX mount type. + * @G_UNIX_MOUNT_TYPE_IPOD: iPod UNIX mount type. + * @G_UNIX_MOUNT_TYPE_CAMERA: Digital camera UNIX mount type. + * @G_UNIX_MOUNT_TYPE_HD: Hard drive UNIX mount type. + * + * Types of UNIX mounts. + **/ typedef enum { G_UNIX_MOUNT_TYPE_UNKNOWN, G_UNIX_MOUNT_TYPE_FLOPPY, @@ -47,6 +76,11 @@ typedef enum { G_UNIX_MOUNT_TYPE_HD } GUnixMountType; +/** + * GUnixMountMonitor: + * + * Watches #GUnixMounts for changes. + **/ typedef struct _GUnixMountMonitor GUnixMountMonitor; typedef struct _GUnixMountMonitorClass GUnixMountMonitorClass; diff --git a/gio/gunixvolume.c b/gio/gunixvolume.c index 6ce1260c7..a6e9867b2 100644 --- a/gio/gunixvolume.c +++ b/gio/gunixvolume.c @@ -31,7 +31,6 @@ #include "gvolumeprivate.h" #include "gvolumemonitor.h" #include "gthemedicon.h" - #include "glibintl.h" struct _GUnixVolume { diff --git a/gio/gunixvolumemonitor.c b/gio/gunixvolumemonitor.c index 2430e4bcc..08ad02d79 100644 --- a/gio/gunixvolumemonitor.c +++ b/gio/gunixvolumemonitor.c @@ -30,7 +30,6 @@ #include "gunixvolume.h" #include "gunixdrive.h" #include "gvolumeprivate.h" - #include "glibintl.h" struct _GUnixVolumeMonitor { diff --git a/gio/gurifuncs.c b/gio/gurifuncs.c index 2e1072319..757a9c0e2 100644 --- a/gio/gurifuncs.c +++ b/gio/gurifuncs.c @@ -24,6 +24,17 @@ #include "gurifuncs.h" #include "string.h" +/** + * SECTION:gurifuncs + * @short_description: URI Functions + * + * Functions for manipulating Universal Resource Identifiers (URIs) as + * defined by RFC 3986. It is highly recommended that you have read and + * understand RFC 3986 for understanding this API. A copy of RFC 3986 + * can be found at . + * + **/ + static int unescape_character (const char *scanner) { @@ -47,6 +58,8 @@ unescape_character (const char *scanner) * @escaped_string_end: a string. * @illegal_characters: a string of illegal characters not to be allowed. * + * Unescapes a segment of an escaped string. + * * Returns: an unescaped version of @escaped_string or %NULL on error. * The returned string should be freed when no longer needed. **/ @@ -109,10 +122,10 @@ g_uri_unescape_segment (const char *escaped_string, * @escaped_string: an escaped string to be unescaped. * @illegal_characters: a string of illegal characters not to be allowed. * - * Returns: an unescaped version of @escaped_string. - * - * The returned string should be freed when no longer needed - * + * Unescapes a whole escaped string. + * + * Returns: an unescaped version of @escaped_string. The returned string + * should be freed when no longer needed. **/ char * g_uri_unescape_string (const char *escaped_string, @@ -125,13 +138,12 @@ g_uri_unescape_string (const char *escaped_string, * g_uri_get_scheme: * @uri: a valid URI. * - * Returns: The "Scheme" component of the URI, or %NULL on error. - * RFC 3986 decodes the scheme as: + * Gets the scheme portion of a URI. RFC 3986 decodes the scheme as: * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * Popular schemes include "file", "http", "svn", etc. - * + * Common schemes include "file", "http", "svn+ssh", etc. + * + * Returns: The "Scheme" component of the URI, or %NULL on error. * The returned string should be freed when no longer needed. - * **/ char * g_uri_get_scheme (const char *uri) @@ -205,8 +217,9 @@ gunichar_ok (gunichar c) * @reserved_chars_allowed: a string of reserve characters allowed to be used. * @allow_utf8: set %TRUE if the return value may include UTF8 characters. * - * Returns a #GString with the escaped URI appended. - * + * Appends an escaped URI to @string. + * + * Returns: a #GString with the escaped URI appended. **/ GString * g_string_append_uri_escaped (GString *string, @@ -253,11 +266,12 @@ g_string_append_uri_escaped (GString *string, * g_uri_escape_string: * @unescaped: the unescaped input string. * @reserved_chars_allowed: a string of reserve characters allowed to be used. - * @allow_utf8: set to %TRUE if string can include UTF8 characters. + * @allow_utf8: a #gboolean. Set to %TRUE if string can include UTF8 characters. * - * Returns an escaped version of @unescaped. + * Escapes a string for use in a URI. * - * The returned string should be freed when no longer needed. + * Returns: an escaped version of @unescaped. The returned string should be + * freed when no longer needed. **/ char * g_uri_escape_string (const char *unescaped, diff --git a/gio/gurifuncs.h b/gio/gurifuncs.h index cace2d90e..f162d0d76 100644 --- a/gio/gurifuncs.h +++ b/gio/gurifuncs.h @@ -27,10 +27,39 @@ G_BEGIN_DECLS +/** + * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: + * + * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + **/ #define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@" + +/** + * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS + * + * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + **/ #define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;=" + +/** + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: + * + * Allowed characters in path elements. Includes "!$&'()*+,;=:@". + **/ #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@" + +/** + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: + * + * Allowed characters in a path. Includes "!$&'()*+,;=:@/". + **/ #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/" + +/** + * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: + * + * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". + **/ #define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":" char * g_uri_unescape_string (const char *escaped_string, diff --git a/gio/gvfs.c b/gio/gvfs.c index 4dc1f256b..94f821983 100644 --- a/gio/gvfs.c +++ b/gio/gvfs.c @@ -27,6 +27,15 @@ #include "giomodule.h" #include "glibintl.h" +/** + * SECTION:gvfs + * @short_description: Virtual File System + * @include: gio/gvfs.h + * + * Entry point for using GIO functionality. + * + **/ + G_DEFINE_TYPE (GVfs, g_vfs, G_TYPE_OBJECT); static void @@ -41,9 +50,11 @@ g_vfs_init (GVfs *vfs) /** * g_vfs_is_active: - * @vfs: an #GVfs. + * @vfs: a #GVfs. * - * Returns TRUE if construction of the @vfs was successful and its now active. + * Checks if the VFS is active. + * + * Returns: %TRUE if construction of the @vfs was successful and it is now active. **/ gboolean g_vfs_is_active (GVfs *vfs) @@ -60,11 +71,12 @@ g_vfs_is_active (GVfs *vfs) /** * g_vfs_get_file_for_path: - * @vfs: an input #GVfs. + * @vfs: a #GVfs. * @path: a string containing a VFS path. * - * Returns a #GFile for the given @path. + * Gets a #GFile for @path. * + * Returns: a #GFile. **/ GFile * g_vfs_get_file_for_path (GVfs *vfs, @@ -82,14 +94,16 @@ g_vfs_get_file_for_path (GVfs *vfs, /** * g_vfs_get_file_for_uri: - * @vfs: an input #GVfs. - * @uri: an input string containing a URI path. - * + * @vfs: a#GVfs. + * @uri: a string containing a URI path. + * + * Gets a #GFile for @uri. + * * This operation never fails, but the returned object * might not support any I/O operation if the uri * is malformed or if the uri type is not supported. * - * Returns a #GFile for the given @uri. + * Returns: a #GFile. * **/ GFile * @@ -108,10 +122,11 @@ g_vfs_get_file_for_uri (GVfs *vfs, /** * g_vfs_get_supported_uri_schemes: - * @vfs: an input #GVfs. + * @vfs: a #GVfs. * - * Returns: + * Gets a list of URI schemes supported by GVFS. * + * Returns: a list of strings. **/ const gchar * const * g_vfs_get_supported_uri_schemes (GVfs *vfs) @@ -127,7 +142,7 @@ g_vfs_get_supported_uri_schemes (GVfs *vfs) /** * g_vfs_parse_name: - * @vfs: an input #GVfs. + * @vfs: a #GVfs. * @parse_name: a string to be parsed by the VFS module. * * This operation never fails, but the returned object might @@ -135,7 +150,6 @@ g_vfs_get_supported_uri_schemes (GVfs *vfs) * be parsed by the #GVfs module. * * Returns a #GFile for the given @parse_name. - * **/ GFile * g_vfs_parse_name (GVfs *vfs, @@ -230,7 +244,9 @@ get_default_vfs (gpointer arg) /** * g_vfs_get_default: * - * Returns the default #GVfs for the system. + * Gets the default #GVfs for the system. + * + * Returns: a #GVfs. **/ GVfs * g_vfs_get_default (void) @@ -243,7 +259,9 @@ g_vfs_get_default (void) /** * g_vfs_get_local: * - * Returns the local #GVfs for the system. + * Gets the local #GVfs for the system. + * + * Returns: a #GVfs. **/ GVfs * g_vfs_get_local (void) diff --git a/gio/gvfs.h b/gio/gvfs.h index ebc82bded..ce7e3cd8c 100644 --- a/gio/gvfs.h +++ b/gio/gvfs.h @@ -35,6 +35,11 @@ G_BEGIN_DECLS #define G_IS_VFS(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_VFS)) #define G_IS_VFS_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_VFS)) +/** + * GVfs: + * + * Virtual File System object. + **/ typedef struct _GVfs GVfs; /* Dummy typedef */ typedef struct _GVfsClass GVfsClass; @@ -61,7 +66,7 @@ struct _GVfsClass const char *parse_name); - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void); diff --git a/gio/gvolume.c b/gio/gvolume.c index 280f46c26..1f60525c2 100644 --- a/gio/gvolume.c +++ b/gio/gvolume.c @@ -26,6 +26,33 @@ #include "gsimpleasyncresult.h" #include "glibintl.h" +/** + * SECTION:gvolume + * @short_description: mounted volume management + * + * Class for managing mounted volumes. + * + * Unmounting volumes is an asynchronous operation. For more information about + * asynchronous operations, see #GAsyncReady and #GSimpleAsyncReady. To unmount a volume, + * first call g_volume_unmount() with (at least) the volume and a #GAsyncReadyCallback. + * The callback will be fired when the operation has resolved (either with success or failure), + * and a #GAsyncReady structure will be passed to the callback. + * That callback should then call g_volume_unmount_finish() with + * the volume and the #GAsyncReady data to see if the operation was completed successfully. + * If an @error is present when g_volume_unmount_finish() is called, then it will + * be filled with any error information. + * + * Ejecting volumes is also an asynchronous operation. + * To eject a volume, call g_volume_eject() with (at least) the volume to eject + * and a #GAsyncReadyCallback. The callback will be fired when the eject operation + * has resolved (either with success or failure), and a #GAsyncReady structure will + * be passed to the callback. That callback should then call g_volume_eject_finish() + * with the volume and the #GAsyncReady data to determine if the operation was completed + * successfully. If an @error is present when g_volume_eject_finish() is called, then + * it will be filled with any error information. + * + **/ + static void g_volume_base_init (gpointer g_class); static void g_volume_class_init (gpointer g_class, gpointer class_data); @@ -73,6 +100,11 @@ g_volume_base_init (gpointer g_class) if (! initialized) { + /** + * GVolume::changed: + * + * Emitted when the volume has been changed. + **/ g_signal_new (I_("changed"), G_TYPE_VOLUME, G_SIGNAL_RUN_LAST, @@ -89,8 +121,9 @@ g_volume_base_init (gpointer g_class) * g_volume_get_root: * @volume: a #GVolume. * - * Returns a #GFile. + * Gets the root directory on @volume. * + * Returns a #GFile. **/ GFile * g_volume_get_root (GVolume *volume) @@ -108,10 +141,10 @@ g_volume_get_root (GVolume *volume) * g_volume_get_name: * @volume: a #GVolume. * - * Returns the name for the given @volume. - * - * The returned string should be freed when no longer needed. + * Gets the name of @volume. * + * Returns the name for the given @volume. The returned string should + * be freed when no longer needed. **/ char * g_volume_get_name (GVolume *volume) @@ -127,10 +160,11 @@ g_volume_get_name (GVolume *volume) /** * g_volume_get_icon: - * @volume: + * @volume: a #GVolume. * - * Returns the #GIcon for the given @volume. + * Gets the icon for @volume. * + * Returns: a #GIcon. **/ GIcon * g_volume_get_icon (GVolume *volume) @@ -146,10 +180,11 @@ g_volume_get_icon (GVolume *volume) /** * g_volume_get_drive: - * @volume: + * @volume: a #GVolume. * - * Returns the #GDrive for the given @volume. + * Gets the drive for the @volume. * + * Returns: a #GDrive. **/ GDrive * g_volume_get_drive (GVolume *volume) @@ -165,7 +200,9 @@ g_volume_get_drive (GVolume *volume) /** * g_volume_can_unmount: - * @volume: + * @volume: a #GVolume. + * + * Checks if @volume can be mounted. * * Returns %TRUE if the @volume can be unmounted. **/ @@ -183,10 +220,11 @@ g_volume_can_unmount (GVolume *volume) /** * g_volume_can_eject: - * @volume: + * @volume: a #GVolume. + * + * Checks if @volume can be ejected. * * Returns %TRUE if the @volume can be ejected. - * **/ gboolean g_volume_can_eject (GVolume *volume) @@ -202,10 +240,14 @@ g_volume_can_eject (GVolume *volume) /** * g_volume_unmount: - * @volume: - * @callback: - * @user_data: + * @volume: a #GVolume. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. * + * Unmounts a volume. This is an asynchronous operation, and is finished by calling + * g_volume_unmount_finish() with the @volume and #GAsyncResults data returned in the + * @callback. * **/ void @@ -235,12 +277,15 @@ g_volume_unmount (GVolume *volume, /** * g_volume_unmount_finish: - * @volume: - * @result: + * @volume: a #GVolume. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Return: * + * Finishes unmounting a volume. If any errors occured during the operation, + * @error will be set to contain the errors and %FALSE will be returned. + * + * Returns: %TRUE if the volume was successfully unmounted. %FALSE otherwise. **/ gboolean g_volume_unmount_finish (GVolume *volume, @@ -265,9 +310,14 @@ g_volume_unmount_finish (GVolume *volume, /** * g_volume_eject: - * @volume: - * @callback: - * @user_data: + * @volume: a #GVolume. + * @cancellable: optional #GCancellable object, %NULL to ignore. + * @callback: a #GAsyncReadyCallback. + * @user_data: user data passed to @callback. + * + * Ejects a volume. This is an asynchronous operation, and is finished + * by calling g_volume_eject_finish() from the @callback with the @volume and + * #GAsyncResults returned in the callback. * **/ void @@ -297,12 +347,15 @@ g_volume_eject (GVolume *volume, /** * g_volume_eject_finish: - * @volume: - * @result: + * @volume: a #GVolume. + * @result: a #GAsyncResult. * @error: a #GError location to store the error occuring, or %NULL to * ignore. - * Returns: * + * Finishes ejecting the volume. If any errors occured during the operation, + * @error will be set to contain the errors and %FALSE will be returned. + * + * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. **/ gboolean g_volume_eject_finish (GVolume *volume, diff --git a/gio/gvolume.h b/gio/gvolume.h index 38addbe19..d45c901fb 100644 --- a/gio/gvolume.h +++ b/gio/gvolume.h @@ -34,9 +34,31 @@ G_BEGIN_DECLS #define G_VOLUME_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_VOLUME, GVolumeIface)) /* GVolume typedef is in gfile.h due to include order issues */ +/** + * GDrive: + * + * Opaque drive object. + **/ typedef struct _GDrive GDrive; /* Dummy typedef */ typedef struct _GVolumeIface GVolumeIface; +/** + * GVolumeIface: + * @g_iface: The parent interface. + * @changed: Changed signal that is emitted when the volume's state has changed. + * @get_root: Gets a #GFile to the root directory of the #GVolume. + * @get_name: Gets a string containing the name of the #GVolume. + * @get_icon: Gets a #GIcon for the #GVolume. + * @get_drive: Gets a #GDrive the volume is located on. + * @can_unmount: Checks if a #GVolume can be unmounted. + * @can_eject: Checks if a #GVolume can be ejected. + * @unmount: Starts unmounting a #GVolume. + * @unmount_finish: Finishes an unmounting operation. + * @eject: Starts ejecting a #GVolume. + * @eject_finish: Finishes an eject operation. + * + * Interface for implementing operations for mounted volumes. + **/ struct _GVolumeIface { GTypeInterface g_iface; diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c index a1b7c9b82..a1c983c88 100644 --- a/gio/gvolumemonitor.c +++ b/gio/gvolumemonitor.c @@ -24,6 +24,15 @@ #include "gvolumemonitor.h" #include "glibintl.h" +/** + * SECTION:gvolumemonitor + * @short_description: Volume Monitor + * @see_also: #GDirectoryMonitor, #GFileMonitor + * + * Monitors a mounted volume for changes. + * + **/ + G_DEFINE_TYPE (GVolumeMonitor, g_volume_monitor, G_TYPE_OBJECT); enum { @@ -56,6 +65,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass) gobject_class->finalize = g_volume_monitor_finalize; + /** + * GVolumeMonitor::volume-mounted: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: the volume that was mounted. + * + * Emitted when a volume is mounted. + **/ signals[VOLUME_MOUNTED] = g_signal_new (I_("volume_mounted"), G_TYPE_VOLUME_MONITOR, G_SIGNAL_RUN_LAST, @@ -63,7 +79,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass) NULL, NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_VOLUME); - + /** + * GVolumeMonitor::volume-pre-unmount: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: the volume that is being unmounted. + * + * Emitted when a volume is about to be unmounted. + **/ signals[VOLUME_PRE_UNMOUNT] = g_signal_new (I_("volume_pre_unmount"), G_TYPE_VOLUME_MONITOR, G_SIGNAL_RUN_LAST, @@ -71,7 +93,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass) NULL, NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_VOLUME); - + /** + * GVolumeMonitor::volume-unmounted: + * @volume_monitor: The volume monitor emitting the signal. + * @volume: the volume that was unmounted. + * + * Emitted when a volume is unmounted. + **/ signals[VOLUME_UNMOUNTED] = g_signal_new (I_("volume_unmounted"), G_TYPE_VOLUME_MONITOR, G_SIGNAL_RUN_LAST, @@ -79,7 +107,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass) NULL, NULL, g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_VOLUME); - + /** + * GVolumeMonitor::drive-connected: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: a #GDrive that was connected. + * + * Emitted when a drive is connected to the system. + **/ signals[DRIVE_CONNECTED] = g_signal_new (I_("drive_connected"), G_TYPE_VOLUME_MONITOR, G_SIGNAL_RUN_LAST, @@ -88,7 +122,13 @@ g_volume_monitor_class_init (GVolumeMonitorClass *klass) g_cclosure_marshal_VOID__OBJECT, G_TYPE_NONE, 1, G_TYPE_DRIVE); - + /** + * GVolumeMonitor::drive-disconnected: + * @volume_monitor: The volume monitor emitting the signal. + * @drive: a #GDrive that was disconnected. + * + * Emitted when a drive is disconnected from the system. + **/ signals[DRIVE_DISCONNECTED] = g_signal_new (I_("drive_disconnected"), G_TYPE_VOLUME_MONITOR, G_SIGNAL_RUN_LAST, @@ -107,8 +147,9 @@ g_volume_monitor_init (GVolumeMonitor *monitor) * g_volume_monitor_get_mounted_volumes: * @volume_monitor: a #GVolumeMonitor. * - * Returns a #GList of mounted #GVolumes. + * Gets a list of volumes mounted on the computer. * + * Returns a #GList of mounted #GVolumes. **/ GList * g_volume_monitor_get_mounted_volumes (GVolumeMonitor *volume_monitor) @@ -126,8 +167,9 @@ g_volume_monitor_get_mounted_volumes (GVolumeMonitor *volume_monitor) * g_volume_monitor_get_connected_drives: * @volume_monitor: a #GVolumeMonitor. * - * Returns a #GList of connected #GDrives. + * Gets a list of drives connected to the computer. * + * Returns: a #GList of connected #GDrives. **/ GList * g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor) diff --git a/gio/gvolumemonitor.h b/gio/gvolumemonitor.h index ef990a1c4..63892e925 100644 --- a/gio/gvolumemonitor.h +++ b/gio/gvolumemonitor.h @@ -36,11 +36,19 @@ G_BEGIN_DECLS #define G_IS_VOLUME_MONITOR(o) (G_TYPE_CHECK_INSTANCE_TYPE ((o), G_TYPE_VOLUME_MONITOR)) #define G_IS_VOLUME_MONITOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_VOLUME_MONITOR)) +/** + * GVolumeMonitor: + * @parent: The parent class. + * + * A Volume Monitor that watches for volume events. + **/ typedef struct _GVolumeMonitor GVolumeMonitor; typedef struct _GVolumeMonitorClass GVolumeMonitorClass; struct _GVolumeMonitor { GObject parent; + + /*< private >*/ gpointer priv; }; @@ -65,7 +73,7 @@ struct _GVolumeMonitorClass { GList * (*get_mounted_volumes) (GVolumeMonitor *volume_monitor); GList * (*get_connected_drives) (GVolumeMonitor *volume_monitor); - + /*< private >*/ /* Padding for future expansion */ void (*_g_reserved1) (void); void (*_g_reserved2) (void);