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
+2007-11-27 Andrew Walton <awalton@svn.gnome.org>
+ * 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 <j@bitron.ch>
* gbufferedinputstream.c: (g_buffered_input_stream_peek_buffer),
#include "glibintl.h"
#include <gioerror.h>
+/**
+ * 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,
/**
* g_app_info_dup:
* @appinfo: a #GAppInfo.
+ *
+ * Creates a duplicate of a #GAppInfo.
*
* Returns: a duplicate of @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,
/**
* 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)
/**
* g_app_info_get_name:
* @appinfo: a #GAppInfo.
+ *
+ * Gets the installed name of the application.
*
* Returns: the name of the application for @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)
/**
* 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.
* @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,
* @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,
* @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.
/**
* 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.
* @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.
**/
/**
* g_app_info_get_icon:
* @appinfo: a #GAppInfo.
+ *
+ * Gets the default icon for the application.
*
* Returns: the default #GIcon for @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,
/**
* 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.
**/
* @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,
* @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,
/**
* 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)
* @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,
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 <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"/>.
*
+ * Returns: a startup notifaction ID for the application, or %NULL if not supported.
**/
char *
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,
#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)
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 #GAppInfo<!-- -->s 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
+ * <ulink url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
+ * <citetitle>FreeDesktop.Org Startup Notification Specification</citetitle></ulink>.
+ * @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
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);
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;
};
#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)
{
#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:
+ * <informalexample>
+ * <programlisting>
+ * 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);
+ *
+ * /<!-- -->* ... *<!-- -->/
+ * </programlisting>
+ * </informalexample>
+ *
+ * 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);
* 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)
* g_async_result_get_source_object:
* @res: a #GAsyncResult.
*
+ * Gets the source object from a #GAsyncResult.
+ *
* Returns: the source object for the @res.
**/
GObject *
#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;
*/
#include <config.h>
-
#include "gbufferedinputstream.h"
#include "ginputstream.h"
#include "gsimpleasyncresult.h"
#include <string.h>
-
#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 {
* 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)
}
/**
- * 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,
* 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
* @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,
#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;
GAsyncResult *result,
GError **error);
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
*/
#include <config.h>
-
#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 {
* 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
* @size: a #gsize.
*
* Sets the size of the internal buffer to @size.
- *
**/
void
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.
**/
/**
* 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,
* 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 *
* @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 *
#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;
{
GOutputStreamClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include <fcntl.h>
#include <gioerror.h>
#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.
*/
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),
/**
* g_cancellable_new:
+ *
+ * Creates a new #GCancellable object.
*
- * Returns: a new #GCancellable object.
+ * Returns: a #GCancellable.
**/
GCancellable *
g_cancellable_new (void)
/**
* 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.
**/
* @cancellable: a #GCancellable object.
*
* Resets @cancellable to its uncancelled state.
- *
**/
void
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.
**/
* 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
*
* Will set @cancellable to cancelled, and will emit the CANCELLED
* signal. This function is thread-safe.
- *
**/
void
g_cancellable_cancel (GCancellable *cancellable)
#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;
GObjectClass parent_class;
void (* cancelled) (GCancellable *cancellable);
-
+
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
*/
#include <config.h>
-
#include <sys/types.h>
#include <dirent.h>
#include <string.h>
#include <stdio.h>
-
#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
/**
* 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.
/**
* g_content_type_is_unknown:
- * @type: a content type string. a content type string.
+ * @type: a content type string.
+ *
+ * Checks if the content type is known by GIO.
*
- * Returns:
+ * Returns: %TRUE if the type is unknown.
**/
gboolean
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.
**/
/**
* 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.
**/
/**
* 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.
**/
* 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)
* @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,
/**
* 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 *
#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;
/**
* 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.
**/
* 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
/**
* 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.
* 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,
*
* 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.
*
* 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.
*
* 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.
*
* 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.
* @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,
#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;
struct _GDataInputStreamClass
{
GBufferedInputStreamClass parent_class;
-
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
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,
#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;
};
* g_data_output_stream_new:
* @base_stream: a #GOutputStream.
*
+ * Creates a new data output stream for @base_stream.
+ *
* Returns: #GDataOutputStream.
**/
GDataOutputStream *
/**
* 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,
/**
* 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)
* @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.
**/
/**
* 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.
**/
/**
* 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.
**/
/**
* 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.
**/
/**
* 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.
**/
/**
* 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.
**/
/**
* 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.
**/
* @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,
#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;
struct _GDataOutputStreamClass
{
GFilterOutputStreamClass parent_class;
-
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include "gvfs.h"
#include "glibintl.h"
+/**
+ * SECTION:gdirectorymonitor
+ * @short_description: Directory Monitor
+ * @see_also: #GFileMonitor.
+ *
+ * Monitors a directory for changes.
+ *
+ **/
+
enum {
CHANGED,
LAST_SIGNAL
/**
* 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)
/**
* 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
/**
* 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)
/**
* 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
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;
/* Virtual Table */
gboolean (*cancel)(GDirectoryMonitor* monitor);
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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);
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,
*
* 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)
* g_drive_has_volumes:
* @drive: a #GDrive.
*
+ * Checks if a drive has any volumes.
+ *
* Returns: %TRUE if @drive contains volumes, %FALSE otherwise.
**/
gboolean
* 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 #GVolume<!---->s on the given @drive.
* NOTE: Fact-check this.
**/
GList *
* 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
* 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
* 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
* 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
* @result: a #GAsyncResult.
* @error: a #GError.
*
+ * Finishes mounting a drive.
+ *
* Returns: %TRUE, %FALSE if operation failed.
**/
gboolean
/**
* 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,
* @result: a #GAsyncResult.
* @error: a #GError.
*
+ * Finishes ejecting a drive.
+ *
* Returns: %TRUE if the drive has been ejected successfully,
* %FALSE otherwise.
**/
#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
#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. #GFile<!-- -->s 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 #GFile<!-- -->s.
+ *
+ * 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);
* 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)
* @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.
* 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)
* 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)
* 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)
* 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)
* 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)
* 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.
**/
* 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.
* @file1: the first #GFile.
* @file2: the second #GFile.
*
+ * Checks equality of two given #GFile<!-- -->s
+ *
* Returns: %TRUE if @file1 and @file2 are equal.
* %FALSE if either is not a #GFile.
**/
* 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)
* @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.
* @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,
* @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,
* @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,
* @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.
**/
/**
* 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,
/**
* 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
* @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 *
/**
* 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.
**/
/**
* 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.
*
* 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
/**
* 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.
+ *
+ * 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.
+ * Returns: #GFileInfo for given @file or %NULL on error.
**/
GFileInfo *
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,
* @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,
* @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,
* @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.
**/
* @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.
* @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.
/**
* 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,
/**
* 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,
*
* 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
* @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,
*
* 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
/**
* 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 *
*
* 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
/**
* 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.
**/
* @progress_callback_data: userdata to pass to @progress_callback
* @error: #GError to set on error
*
+ * <!-- Source Friendly Version
* List of possible errors resulting from g_file_copy():
* source dest flags res
* - * * G_IO_ERROR_NOT_FOUND
* dir * 0 G_IO_ERROR_EXISTS
* dir dir overwr G_IO_ERROR_WOULD_MERGE
* dir file overwr G_IO_ERROR_WOULD_RECURSE
+ * Docbook version below -->
+ *
+ * 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.
+ *
+ * <table>
+ * <title>g_file_copy() Error Conditions</title>
+ * <tgroup cols='4' align='left'><thead>
+ * <row><entry>Source</entry><entry>Destination</entry><entry>Flags</entry><entry>Results in</entry></row>
+ * </thead><tbody>
+ * <row><entry>%NULL</entry><entry>Anything</entry><entry>Anything</entry><entry>%G_IO_ERROR_NOT_FOUND</entry></row>
+ * <row><entry>File</entry><entry>%NULL</entry><entry>Anything</entry><entry>No Error</entry></row>
+ * <row><entry>File</entry><entry>Anything</entry><entry>0</entry><entry>%G_IO_ERROR_EXISTS</entry></row>
+ * <row><entry>File</entry><entry>File</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>No Error</entry></row>
+ * <row><entry>File</entry><entry>Directory</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_IS_DIRECTORY</entry></row>
+ * <row><entry>Directory</entry><entry>%NULL</entry><entry>Anything</entry><entry>%G_IO_ERROR_WOULD_RECURSE</entry></row>
+ * <row><entry>Directory</entry><entry>Anything</entry><entry>0</entry><entry>%G_IO_ERROR_EXISTS</entry></row>
+ * <row><entry>Directory</entry><entry>Directory</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_IS_DIRECTORY</entry></row>
+ * <row><entry>Directory</entry><entry>File</entry><entry>%G_FILE_COPY_OVERWRITE</entry><entry>%G_IO_ERROR_WOULD_RECURSE</entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
*
* Returns: %TRUE on success, %FALSE otherwise.
**/
/**
* 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:
- *
+ * <!-- Source version
* source dest flags results in
* - * * G_IO_ERROR_NOT_FOUND
* file - * ok
* dir * 0 G_IO_ERROR_EXISTS
* dir dir overwr G_IO_ERROR_WOULD_MERGE
* dir file overwr ok || G_IO_ERROR_WOULD_RECURSE
- *
+ * Pretty Docbook version -->
+ * <table>
+ * <title>g_file_move() Error Conditions</title>
+ * <tgroup cols='4' align='left'><thead>
+ * <row><entry>Source</entry><entry>Destination</entry>
+ * <entry>Flags</entry><entry>Results in</entry></row>
+ * </thead><tbody>
+ * <row><entry> %NULL </entry><entry> Anything </entry>
+ * <entry> Anything </entry><entry> %G_IO_ERROR_NOT_FOUND </entry></row>
+ * <row><entry> File </entry><entry> %NULL </entry>
+ * <entry> Anything </entry><entry> No Error </entry></row>
+ * <row><entry> File </entry><entry> Anything </entry>
+ * <entry> 0 </entry><entry> %G_IO_ERROR_EXISTS </entry></row>
+ * <row><entry> File </entry><entry> File </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> No Error </entry></row>
+ * <row><entry> File </entry><entry> Directory </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> %G_IO_ERROR_IS_DIRECTORY </entry></row>
+ * <row><entry> Directory </entry><entry> %NULL </entry>
+ * <entry> Anything </entry><entry> No Error or %G_IO_ERROR_WOULD_RECURSE </entry></row>
+ * <row><entry> Directory </entry><entry> Anything </entry>
+ * <entry> 0 </entry><entry> %G_IO_ERROR_EXISTS </entry></row>
+ * <row><entry> Directory </entry><entry> Directory </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> %G_IO_ERROR_IS_DIRECTORY </entry></row>
+ * <row><entry> Directory </entry><entry> File </entry>
+ * <entry> %G_FILE_COPY_OVERWRITE </entry><entry> No Error or %G_IO_ERROR_WOULD_RECURSE </entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
* Returns: %TRUE on successful move, %FALSE otherwise.
**/
gboolean
* @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
* @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
* @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
/**
* 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
* @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,
*
* 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
/**
* 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 *
* @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
* @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.
* 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,
* @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.
* @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
* @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
* @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,
}
/**
- * 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.
* @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.
**/
* @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.
**/
* @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.
**/
* @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.
**/
* @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,
* @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.
*
**/
* @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,
* @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,
* @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.
**/
* @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.
**/
* @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.
**/
* @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
* @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,
* 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.
*
* 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
/**
* 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
*
* 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
/**
* 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
/**
* 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
* 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.
*
* 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.
/**
* 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.
**/
#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),
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 #GFile<!-- -->s.
+ * @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 #GFileAttribute<!-- -->s that can be set.
+ * @_query_settable_attributes_async: Asynchronously gets a list of #GFileAttribute<!-- -->s 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;
GFileMonitor* (*monitor_file) (GFile *file,
GFileMonitorFlags flags,
GCancellable *cancellable);
+
};
GType g_file_get_type (void) G_GNUC_CONST;
#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().
+ *
+ * <para>
+ * <table>
+ * <title>GFileAttributes Namespaces</title>
+ * <tgroup cols='2' align='left'><thead>
+ * <row><entry>Namspace</entry><entry>Description</entry></row>
+ * </thead>
+ * <tbody>
+ * <row><entry>"std"</entry><entry>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.</entry></row>
+ * <row><entry>"etag"</entry><entry>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.</entry></row>
+ * <row><entry>"id"</entry><entry>The "Identification" namespace. This
+ * namespace is used by file managers and applications that list directories
+ * to check for loops and to uniquely identify files.</entry></row>
+ * <row><entry>"access"</entry><entry>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.</entry></row>
+ * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes
+ * simple boolean keys for checking if a file or path supports mount operations, e.g.
+ * mount, unmount, eject.</entry></row>
+ * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
+ * access, changed, created times. </entry></row>
+ * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
+ * information and may not be available for all files. Examples include
+ * the UNIX "UID", "GID", etc.</entry></row>
+ * <row><entry>"dos"</entry><entry>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.</entry></row>
+ * <row><entry>"owner"</entry><entry>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.</entry></row>
+ * <row><entry>"thumbnail"</entry><entry>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.</entry></row>
+ * <row><entry>"fs"</entry><entry>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.</entry></row>
+ * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
+ * contain information about the current GVFS backend in use. </entry></row>
+ * </tbody>
+ * </tgroup>
+ * </table>
+ * </para>
+ *
+ * More namespaces can be added from GIO modules or by individual applications.
+ * For more information about writing GIO modules, see #GIOModule.
+ *
+ * <para><table>
+ * <title>GFileAttributes Built-in Keys and Value Types</title>
+ * <tgroup cols='3' align='left'><thead>
+ * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row>
+ * </thead><tbody>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_TYPE</entry><entry>std:type</entry><entry>uint32 (#GFileType)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_HIDDEN</entry><entry>std:is_hidden</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_BACKUP</entry><entry>std:is_backup</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_SYMLINK</entry><entry>std:is_symlink</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_IS_VIRTUAL</entry><entry>std:is_virtual</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_NAME</entry><entry>std:name</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_DISPLAY_NAME</entry><entry>std:display_name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_EDIT_NAME</entry><entry>std:edit_name</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_ICON</entry><entry>std:icon</entry><entry>object (#GIcon)</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_CONTENT_TYPE</entry><entry>std:content_type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_FAST_CONTENT_TYPE</entry><entry>std:fast_content_type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SIZE</entry><entry>std:size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SYMLINK_TARGET</entry><entry>std:symlink_target</entry><entry>byte string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_TARGET_URI</entry><entry>std:target_uri</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_STD_SORT_ORDER</entry><entry>std:sort_order</entry><entry>int32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag:value</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id:file</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ID_FS</entry><entry>id:fs</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access:can_read</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access:can_write</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access:can_execute</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access:can_delete</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access:can_trash</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access:can_rename</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable:can_mount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable:can_unmount</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable:can_eject</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable:unix_device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable:hal_udi</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time:modified</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time:modified_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time:access</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time:access_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time:changed</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time:changed_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time:created</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time:created_usec</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix:device</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix:inode</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix:mode</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix:nlink</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix:uid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix:gid</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix:rdev</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix:block_size</entry><entry>uint32</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix:blocks</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix:is_mountpoint</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos:is_archive</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos:is_system</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner:user</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner:user_real</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner:group</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail:path</entry><entry>bytestring</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail:failed</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_SIZE</entry><entry>fs:size</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_FREE</entry><entry>fs:free</entry><entry>uint64</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_TYPE</entry><entry>fs:type</entry><entry>string</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_FS_READONLY</entry><entry>fs:readonly</entry><entry>boolean</entry></row>
+ * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs:backend</entry><entry>string</entry></row>
+ * </tbody></tgroup></table></para>
+ *
+ **/
+
+/**
* g_file_attribute_value_free:
* @attr: a #GFileAttributeValue.
*
/**
* 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,
/**
* g_file_attribute_value_new:
*
- * Returns: a new #GFileAttributeValue.
+ * Creates a new file attribute.
+ *
+ * Returns: a #GFileAttributeValue.
**/
GFileAttributeValue *
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 *
* @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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
* 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)
/**
* 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
/**
* 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
/**
* 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,
/**
* 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
/**
* 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
/**
* 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
/**
* 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,
* @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
/**
* 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)
* 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 *
* g_file_attribute_info_list_ref:
* @list: a #GFileAttributeInfoList to reference.
*
+ * References a file attribute info list.
+ *
* Returns: #GFileAttributeInfoList or %NULL on error.
**/
GFileAttributeInfoList *
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 #GFileAttributeValue<!-- -->s.
+ **/
typedef enum {
G_FILE_ATTRIBUTE_TYPE_INVALID = 0,
G_FILE_ATTRIBUTE_TYPE_STRING,
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,
#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;
} 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 #GFileAttributeInfo<!-- -->s.
+ * @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 #GFileAttributeInfo<!-- -->s.
+ **/
typedef struct {
GFileAttributeInfo *infos;
int n_infos;
#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 {
* @result: a #GAsyncResult.
* @error: a #GError location to store the error occuring, or %NULL to
* ignore.
+ *
+ *
+ *
* Returns:
**/
GList *
* @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
#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;
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);
#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,
/**
* g_file_icon_new:
- * @file:
+ * @file: a #GFile.
+ *
+ * Creates a new icon for a file.
*
- * Returns:
+ * Returns: a #GIcon for the given @file, or %NULL on error.
**/
GIcon *
g_file_icon_new (GFile *file)
/**
* g_file_icon_get_file:
- * @icon:
+ * @icon: a #GIcon.
+ *
+ * Gets the #GFile associated with the given @icon.
*
- * Returns:
+ * Returns: a #GFile, or %NULL.
**/
GFile *
g_file_icon_get_file (GFileIcon *icon)
#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;
* Author: Alexander Larsson <alexl@redhat.com>
*/
+/**
+ * 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 <config.h>
#include <string.h>
/**
* g_file_info_new:
*
- * Returns: a new #GFileInfo.
+ * Creates a new file info structure.
+ *
+ * Returns: a #GFileInfo.
**/
GFileInfo *
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 #GFileAttribute<!-- -->s from @src_info to @dest_info.
**/
void
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 *
* @mask: a #GFileAttributeMatcher.
*
* Sets @mask on @info to match specific attribute types.
- *
**/
void
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)
* @info: a #GFileInfo.
*
* Clears the status information from @info.
- *
**/
void
g_file_info_clear_status (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.
/**
* 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
/**
* 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,
/**
* 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
/**
* 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.
/**
* 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.
/**
* 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.
/**
* 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.
/**
* g_file_info_get_attribute_boolean:
* @info: a #GFileInfo.
- * @attribute: a string.
+ * @attribute: a file attribute key.
+ *
+ * Gets the value of a boolean attribute. If the attribute does not
+ * contain a boolean value, %FALSE will be returned.
*
- * Returns:
+ * Returns: the boolean value contained within the attribute.
**/
gboolean
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,
/**
* 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,
/**
* g_file_info_get_attribute_uint64:
- * @info:
- * @attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ *
+ * 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:
+ * Returns: a unsigned 64-bit integer from the attribute.
**/
guint64
g_file_info_get_attribute_uint64 (GFileInfo *info,
/**
* g_file_info_get_attribute_int64:
- * @info:
- * @attribute:
+ * @info: a #GFileInfo.
+ * @attribute: a file attribute key.
+ *
+ * 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:
+ * Returns: a signed 64-bit integer from the attribute.
**/
gint64
g_file_info_get_attribute_int64 (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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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.
*
**/
/**
* 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
/**
* 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
/**
* 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,
* 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
* 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
* 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)
* 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
* 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)
* 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)
* 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)
* g_file_info_get_icon:
* @info: a #GFileInfo.
*
+ * Gets the icon for a file.
+ *
* Returns: #GIcon for the given @info.
**/
GIcon *
* 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)
* 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)
/**
* 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.
*
**/
* 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)
* 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)
* 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)
/**
* 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,
/**
* 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,
/**
* 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
/**
* 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
/**
* 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
/**
* 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.
*
**/
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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
#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)
{
}
/**
- * 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. #GFileAttributeMatcher<!-- -->s 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:
+ * <table>
+ * <title>File Attribute Matcher strings and results</title>
+ * <tgroup cols='2' align='left'><thead>
+ * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
+ * <tbody>
+ * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
+ * <row><entry>"std:is_hidden"</entry><entry>matches only the key is_hidden in the std namespace.</entry></row>
+ * <row><entry>"std:type,unix:*"</entry><entry>matches the type key in the std namespace and all keys in the unix
+ * namespace.</entry></row>
+ * </tbody></tgroup>
+ * </table>
+ *
+ * Returns: a #GFileAttributeMatcher.
**/
GFileAttributeMatcher *
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 *
/**
* 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,
/**
* 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,
/**
* g_file_attribute_matcher_enumerate_namespace:
* @matcher: a #GFileAttributeMatcher.
- * @ns:
+ * @ns: a string containing a file attribute namespace.
+ *
+ * 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.)
*
- * Returns: %TRUE, %FALSE.
+ * 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,
* 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)
#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,
} 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;
#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);
/**
* 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,
/**
* 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
/**
* 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 *
/**
* g_file_input_stream_tell:
- * @stream:
+ * @stream: a #GFileInputStream.
+ *
+ * Gets the current position in the stream.
*
- * Returns:
+ * Returns: a #goffset with the position in the stream.
**/
goffset
g_file_input_stream_tell (GFileInputStream *stream)
/**
* 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.
**/
/**
* 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,
#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;
GFileInfo *(*query_info_finish) (GFileInputStream *stream,
GAsyncResult *res,
GError **error);
-
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include "gvfs.h"
#include "glibintl.h"
+/**
+ * SECTION:gfilemonitor
+ * @short_description: File Monitor
+ * @see_also: #GDirectoryMonitor
+ *
+ * Monitors a file for changes.
+ *
+ **/
+
enum {
CHANGED,
LAST_SIGNAL
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,
/**
* g_file_monitor_cancel:
- * @monitor:
+ * @monitor: a #GFileMonitor.
+ *
+ * Cancels a file monitor.
*
* Returns: %TRUE if monitor was cancelled.
**/
/**
* 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
#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,
typedef struct _GFileMonitorClass GFileMonitorClass;
typedef struct _GFileMonitorPrivate GFileMonitorPrivate;
+/**
+ * GFileMonitor:
+ *
+ * Watches for changes within a #GFile.
+ **/
struct _GFileMonitor
{
GObject parent;
/* Virtual Table */
gboolean (*cancel)(GFileMonitor* monitor);
-
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include <string.h>
#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
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,
/**
* g_filename_completer_new:
*
- * Returns: a new #GFilenameCompleter.
+ * Creates a new filename completer.
+ *
+ * Returns: a #GFilenameCompleter.
**/
GFilenameCompleter *
g_filename_completer_new (void)
* @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.
**/
/**
* 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.
#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;
/* signals */
void (* got_completion_data) (GFilenameCompleter *filename_completer);
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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);
/**
* 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,
/**
* 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
* 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().
/**
* 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)
/**
* 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)
/**
* g_file_output_stream_can_seek:
- * @stream:
+ * @stream: a #GFileOutputStream.
+ *
+ * Checks if the stream can be seeked.
*
- * Returns:
+ * Returns: %TRUE if seeking is supported by the stream.
**/
gboolean
g_file_output_stream_can_seek (GFileOutputStream *stream)
/**
* 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,
/**
* g_file_output_stream_can_truncate:
- * @stream:
+ * @stream: a #GFileOutputStream.
+ *
+ * Checks if the stream can be truncated.
*
* Returns: %TRUE if stream can be truncated.
**/
/**
* 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,
#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;
#include "ginputstream.h"
#include "glibintl.h"
+/**
+ * SECTION:gfilterinputstream
+ * @short_description: Filter Input Stream.
+ *
+ **/
+
enum {
PROP_0,
PROP_BASE_STREAM
#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;
struct _GFilterInputStreamClass
{
GInputStreamClass parent_class;
-
+
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include "goutputstream.h"
#include "glibintl.h"
+/**
+ * SECTION:gfilteroutputstream
+ * @short_description: Filter Output Stream
+ *
+ **/
+
enum {
PROP_0,
PROP_BASE_STREAM
#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;
{
GOutputStreamClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
* 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.
**/
* @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
#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 #GIcon<!-- -->s 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;
#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 {
* 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,
/**
* 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.
/**
* 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,
/**
* 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,
/**
* 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,
* g_input_stream_is_closed:
* @stream: input stream.
*
+ * Checks if an input stream is closed.
+ *
* Returns: %TRUE if the stream is closed.
**/
gboolean
* g_input_stream_has_pending:
* @stream: input stream.
*
+ * Checks if an input stream has pending actions.
+ *
* Returns: %TRUE if @stream has pending actions.
**/
gboolean
#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;
GAsyncResult *result,
GError **error);
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#include "gioerror.h"
/**
+ * SECTION:gioerror
+ * @short_description: Error helper functions.
+ *
+ **/
+
+/**
* g_io_error_quark:
+ *
+ * Gets the GIO Error Quark.
*
- * Return value: The quark used as %G_IO_ERROR
+ * Return value: a #GQuark.
**/
GQuark
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)
{
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,
* 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,
#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;
* 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 *
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)
#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;
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
#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;
* @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
* @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
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,
*/
#include <config.h>
-
#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,
/**
* 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,
/**
* 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
/**
* 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,
#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;
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,
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,
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,
*/
#include <config.h>
-
#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;
#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;
#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;
#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;
{
GOutputStreamClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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 {
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),
_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),
_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),
/**
* g_mount_operation_new:
*
- * Returns: a new #GMountOperation.
+ * Creates a new mount operation.
+ *
+ * Returns: a #GMountOperation.
**/
GMountOperation *
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)
/**
* g_mount_operation_set_username:
- * @op:
+ * @op: a #GMountOperation.
* @username: input username.
+ *
+ * Sets the user name within @op to @username.
*
**/
void
/**
* 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)
/**
* g_mount_operation_set_password:
- * @op: the given #GMountOperation.
+ * @op: a #GMountOperation.
* @password: password to set.
*
* Sets the mount operation's password to @password.
/**
* 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.
**/
/**
* 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,
/**
* g_mount_operation_get_domain:
- * @op:
+ * @op: a #GMountOperation.
+ *
+ * Gets the domain of the mount operation.
*
- * Returns: a const string set to the domain.
+ * Returns: a string set to the domain.
**/
const char *
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.
/**
* 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
}
/**
- * 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
/**
* 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)
/**
* 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,
/**
* 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,
#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;
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,
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,
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);
*/
#include <config.h>
-
#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 {
*
* 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,
/**
* 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,
* @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,
/**
* 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
* @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,
/**
* 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
* @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
/**
* 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,
/**
* 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.
**/
/**
* g_output_stream_has_pending:
- * @stream:
+ * @stream: a #GOutputStream.
+ *
+ * Checks if an ouput stream has pending actions.
*
* Returns: %TRUE if @stream has pending actions.
**/
/**
* 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,
#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;
GAsyncResult *result,
GError **error);
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
/**
* g_poll_file_monitor_new:
- * @file:
+ * @file: a #GFile.
+ *
+ * Polls @file for changes.
*
* Returns a new #GFileMonitor for the given #GFile.
**/
#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);
/**
* 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)
/**
* g_seekable_can_seek:
- * @seekable:
+ * @seekable: a #GSeekable.
+ *
+ * Tests if the stream supports the #GSeekableIface.
*
* Returns: %TRUE if @seekable can be seeked. %FALSE otherwise.
**/
/**
* 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,
/**
* g_seekable_can_truncate:
- * @seekable:
+ * @seekable: a #GSeekable.
+ *
+ * Tests if the stream can be truncated.
*
- * Returns:
+ * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
**/
gboolean
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,
#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;
#include <gio/gioerror.h>
#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 #GAsyncReadyCallback<!-- -->s, 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 <!-- TODO: Crosslink -->,
+ * or it can use #GThread<!-- -->s 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
/**
* 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,
/**
* 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,
/**
* g_simple_async_result_new_error:
- * @source_object:
- * @callback:
- * @user_data:
- * @domain:
- * @code:
- * @format:
- * @...
- *
- * Returns: #GSimpleAsyncResult.
+ * @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.
+ *
+ * Creates a new #GSimpleAsyncResult with a set error.
+ *
+ * Returns: a #GSimpleAsyncResult.
**/
GSimpleAsyncResult *
g_simple_async_result_new_error (GObject *source_object,
/**
* 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
/**
* 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)
}
/**
- * 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.
+ *
+ * Propegates an error from within the simple asynchronous result to
+ * a given destination.
*
- * Returns:
+ * Returns: %TRUE if the error was propegated to @dest. %FALSE otherwise.
**/
gboolean
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,
/**
* 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)
/**
* 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,
/**
* g_simple_async_result_get_op_res_gssize:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ *
+ * Gets a gssize from the asynchronous result.
*
- * Returns:
+ * Returns: a gssize returned from the asynchronous function.
**/
gssize
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
/**
* g_simple_async_result_get_op_res_gboolean:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ *
+ * Gets the operation result boolean from within the asynchronous result.
*
- * Returns a #gboolean.
+ * 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)
/**
* 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,
/**
* 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,
/**
* 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
/**
* g_simple_async_result_complete:
- * @simple:
+ * @simple: a #GSimpleAsyncResult.
+ *
+ * Completes an asynchronous I/O job.
*
**/
void
/**
* 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
/**
* 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,
/**
* 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
#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);
#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 {
/**
* 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,
#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;
{
GInputStreamClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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);
/**
* 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.
#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;
{
GOutputStreamClass parent_class;
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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
/**
* 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)
/**
* 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.
+ *
+ * Creates a new themed icon for @iconnames.
*
- * Returns: a new #GIcon.
+ * Returns: a new #GThemedIcon.
**/
GIcon *
g_themed_icon_new_from_names (char **iconnames, int len)
/**
* g_themed_icon_get_names:
- * @icon:
+ * @icon: a #GThemedIcon.
+ *
+ * Gets the names of icons from within @icon.
*
- * Returns:
+ * Returns: a list of icon names.
**/
const char * const *
g_themed_icon_get_names (GThemedIcon *icon)
#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;
#include "gdriveprivate.h"
#include "gthemedicon.h"
#include "gvolumemonitor.h"
-
#include "glibintl.h"
struct _GUnixDrive {
#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;
* 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)
/**
* 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,
* 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)
}
/**
- * 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
}
/**
- * 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
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),
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),
/**
* g_unix_mount_monitor_new:
*
- * Returns a new #GUnixMountMonitor.
+ * Gets a new #GUnixMountMonitor.
+ *
+ * Returns: a #GUnixMountMonitor.
**/
GUnixMountMonitor *
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)
/**
* 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)
* @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.
**/
* 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)
* 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)
* 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)
* 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)
* 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)
* @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.
**/
/**
* 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)
/**
* 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)
/**
* 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)
/**
* 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)
/**
* 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)
/**
* 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)
* 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)
/**
* 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)
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,
G_UNIX_MOUNT_TYPE_HD
} GUnixMountType;
+/**
+ * GUnixMountMonitor:
+ *
+ * Watches #GUnixMount<!-- -->s for changes.
+ **/
typedef struct _GUnixMountMonitor GUnixMountMonitor;
typedef struct _GUnixMountMonitorClass GUnixMountMonitorClass;
#include "gvolumeprivate.h"
#include "gvolumemonitor.h"
#include "gthemedicon.h"
-
#include "glibintl.h"
struct _GUnixVolume {
#include "gunixvolume.h"
#include "gunixdrive.h"
#include "gvolumeprivate.h"
-
#include "glibintl.h"
struct _GUnixVolumeMonitor {
#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 <ulink url="http://www.ietf.org/rfc/rfc3986.txt"/>.
+ *
+ **/
+
static int
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.
**/
* @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,
* 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)
* @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,
* 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,
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,
#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
/**
* g_vfs_is_active:
- * @vfs: an #GVfs.
+ * @vfs: a #GVfs.
+ *
+ * Checks if the VFS is active.
*
- * Returns TRUE if construction of the @vfs was successful and its now active.
+ * Returns: %TRUE if construction of the @vfs was successful and it is now active.
**/
gboolean
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,
/**
* 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 *
/**
* 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)
/**
* 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
* be parsed by the #GVfs module.
*
* Returns a #GFile for the given @parse_name.
- *
**/
GFile *
g_vfs_parse_name (GVfs *vfs,
/**
* 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)
/**
* 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)
#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;
const char *parse_name);
-
+ /*< private >*/
/* Padding for future expansion */
void (*_g_reserved1) (void);
void (*_g_reserved2) (void);
#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);
if (! initialized)
{
+ /**
+ * GVolume::changed:
+ *
+ * Emitted when the volume has been changed.
+ **/
g_signal_new (I_("changed"),
G_TYPE_VOLUME,
G_SIGNAL_RUN_LAST,
* 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)
* 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)
/**
* 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)
/**
* 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)
/**
* g_volume_can_unmount:
- * @volume:
+ * @volume: a #GVolume.
+ *
+ * Checks if @volume can be mounted.
*
* Returns %TRUE if the @volume can be unmounted.
**/
/**
* g_volume_can_eject:
- * @volume:
+ * @volume: a #GVolume.
*
- * Returns %TRUE if the @volume can be ejected.
+ * Checks if @volume can be ejected.
*
+ * Returns %TRUE if the @volume can be ejected.
**/
gboolean
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
/**
* 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,
/**
* 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
/**
* 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,
#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;
#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 {
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,
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,
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,
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,
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,
* 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)
* 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)
#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;
};
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);
projects / platform / upstream / glib.git / commitdiff