glib r6492 - trunk/gio
- From: matthiasc svn gnome org
- To: svn-commits-list gnome org
- Subject: glib r6492 - trunk/gio
- Date: Mon, 11 Feb 2008 07:12:56 +0000 (GMT)
Author: matthiasc
Date: Mon Feb 11 07:12:56 2008
New Revision: 6492
URL: http://svn.gnome.org/viewvc/glib?rev=6492&view=rev
Log:
Documentation additions
Modified:
trunk/gio/ChangeLog
trunk/gio/gappinfo.c
trunk/gio/gappinfo.h
trunk/gio/gdesktopappinfo.c
trunk/gio/gdesktopappinfo.h
trunk/gio/gdrive.c
trunk/gio/giomodule.c
trunk/gio/giomodule.h
trunk/gio/glocaldirectorymonitor.h
trunk/gio/glocalfilemonitor.h
trunk/gio/gvolume.c
trunk/gio/gvolume.h
trunk/gio/gvolumemonitor.c
Modified: trunk/gio/gappinfo.c
==============================================================================
--- trunk/gio/gappinfo.c (original)
+++ trunk/gio/gappinfo.c Mon Feb 11 07:12:56 2008
@@ -532,7 +532,7 @@
/**
* g_app_info_launch_default_for_uri:
* @uri: the uri to show
- * @context: an optional #GAppLaunchContext.
+ * @launch_context: an optional #GAppLaunchContext.
* @error: a #GError.
*
* Utility function that launches the default application
@@ -543,9 +543,9 @@
* Returns: %TRUE on success, %FALSE on error.
**/
gboolean
-g_app_info_launch_default_for_uri (const char *uri,
- GAppLaunchContext *launch_context,
- GError **error)
+g_app_info_launch_default_for_uri (const char *uri,
+ GAppLaunchContext *launch_context,
+ GError **error)
{
GAppInfo *app_info;
GFile *file;
Modified: trunk/gio/gappinfo.h
==============================================================================
--- trunk/gio/gappinfo.h (original)
+++ trunk/gio/gappinfo.h Mon Feb 11 07:12:56 2008
@@ -186,9 +186,9 @@
gboolean must_support_uris);
GAppInfo *g_app_info_get_default_for_uri_scheme (const char *uri_scheme);
-gboolean g_app_info_launch_default_for_uri (const char *uri,
- GAppLaunchContext *launch_context,
- GError **error);
+gboolean g_app_info_launch_default_for_uri (const char *uri,
+ GAppLaunchContext *launch_context,
+ GError **error);
/**
* GAppLaunchContext:
Modified: trunk/gio/gdesktopappinfo.c
==============================================================================
--- trunk/gio/gdesktopappinfo.c (original)
+++ trunk/gio/gdesktopappinfo.c Mon Feb 11 07:12:56 2008
@@ -1662,7 +1662,9 @@
* @uri_scheme: a string containing a URI scheme.
*
* Gets the default application for launching applications
- * using this URI scheme.
+ * using this URI scheme. A URI scheme is the initial part
+ * of the URI, up to but not including the ':', e.g. "http",
+ * "ftp" or "sip".
*
* Returns: #GAppInfo for given @uri_scheme or %NULL on error.
**/
@@ -2520,9 +2522,22 @@
{
}
+/**
+ * g_desktop_app_info_lookup_get_default_for_uri_scheme:
+ * @lookup: a #GDesktopAppInfoLookup
+ * @uri_scheme: a string containing a URI scheme.
+ *
+ * Gets the default application for launching applications
+ * using this URI scheme.
+ *
+ * There should be little reason to use this function directly,
+ * it is preferred to use g_app_info_get_default_for_uri_scheme().
+ *
+ * Returns: #GAppInfo for given @uri_scheme or %NULL on error.
+ */
GAppInfo *
g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
- const char *uri_scheme)
+ const char *uri_scheme)
{
GDesktopAppInfoLookupIface *iface;
Modified: trunk/gio/gdesktopappinfo.h
==============================================================================
--- trunk/gio/gdesktopappinfo.h (original)
+++ trunk/gio/gdesktopappinfo.h Mon Feb 11 07:12:56 2008
@@ -59,6 +59,12 @@
#define G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME "gio-desktop-app-info-lookup"
+/**
+ * GDesktopAppInfoLookup:
+ *
+ * Interface that is used by backends to associate default
+ * handlers with URI schemes.
+ */
typedef struct _GDesktopAppInfoLookup GDesktopAppInfoLookup;
typedef struct _GDesktopAppInfoLookupIface GDesktopAppInfoLookupIface;
@@ -70,9 +76,9 @@
const char *uri_scheme);
};
-GType g_desktop_app_info_lookup_get_type (void) G_GNUC_CONST;
-GAppInfo * g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
- const char *uri_scheme);
+GType g_desktop_app_info_lookup_get_type (void) G_GNUC_CONST;
+GAppInfo *g_desktop_app_info_lookup_get_default_for_uri_scheme (GDesktopAppInfoLookup *lookup,
+ const char *uri_scheme);
G_END_DECLS
Modified: trunk/gio/gdrive.c
==============================================================================
--- trunk/gio/gdrive.c (original)
+++ trunk/gio/gdrive.c Mon Feb 11 07:12:56 2008
@@ -215,6 +215,9 @@
* @drive: a #GDrive.
*
* Get a list of mountable volumes for @drive.
+ *
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
*
* Returns: #GList containing any #GVolume<!---->s on the given @drive.
**/
Modified: trunk/gio/giomodule.c
==============================================================================
--- trunk/gio/giomodule.c (original)
+++ trunk/gio/giomodule.c Mon Feb 11 07:12:56 2008
@@ -41,11 +41,55 @@
* @include: gio.h
*
* Provides an interface and default functions for loading and unloading
- * modules. This is used internally to make gio extensible, but can also
- * be used by other to implement module loading.
+ * modules. This is used internally to make GIO extensible, but can also
+ * be used by others to implement module loading.
*
**/
+/**
+ * SECTION:extensionpoints
+ * @short_description: Extension Points
+ * @include: gio.h
+ * @see_also: <link linkend="gio-extension-points">Extending GIO</link>
+ *
+ * #GIOExtensionPoint provides a mechanism for modules to extend the
+ * functionality of the library or application that loaded it in an
+ * organized fashion.
+ *
+ * An extension point is identified by a name, and it may optionally
+ * require that any implementation must by of a certain type (or derived
+ * thereof). Use g_io_extension_point_register() to register an
+ * extension point, and g_io_extension_point_set_required_type() to
+ * set a required type.
+ *
+ * A module can implement an extension point by specifying the #GType
+ * that implements the functionality. Additionally, each implementation
+ * of an extension point has a name, and a priority. Use
+ * g_io_extension_point_implement() to implement an extension point.
+ *
+ * |[
+ * GIOExtensionPoint *ep;
+ *
+ * /* Register an extension point */
+ * ep = g_io_extension_point_register ("my-extension-point");
+ * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ * ]|
+ *
+ * |[
+ * /* Implement an extension point */
+ * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
+ * g_io_extension_point_implement ("my-extension-point",
+ * my_example_impl_get_type (),
+ * "my-example",
+ * 10);
+ * ]|
+ *
+ * It is up to the code that registered the extension point how
+ * it uses the implementations that have been associated with it.
+ * Depending on the use case, it may use all implementations, or
+ * only the one with the highest priority, or pick a specific
+ * one by name.
+ */
struct _GIOModule {
GTypeModule parent_instance;
@@ -323,6 +367,15 @@
g_free (ep);
}
+/**
+ * g_io_extension_point_register:
+ * @name: The name of the extension point
+ *
+ * Registers an extension point.
+ *
+ * Returns: the new #GIOExtensionPoint. This object is owned by GIO
+ * and should not be freed
+ */
GIOExtensionPoint *
g_io_extension_point_register (const char *name)
{
@@ -352,6 +405,15 @@
return ep;
}
+/**
+ * g_io_extension_point_lookup:
+ * @name: the name of the extension point
+ *
+ * Looks up an existing extension point.
+ *
+ * Returns: the #GIOExtensionPoint, or %NULL if there is no
+ * registered extension point with the given name
+ */
GIOExtensionPoint *
g_io_extension_point_lookup (const char *name)
{
@@ -368,6 +430,14 @@
}
+/**
+ * g_io_extension_point_set_required_type:
+ * @extension_point: a #GIOExtensionPoint
+ * @type: the #GType to require
+ *
+ * Sets the required type for @extension_point to @type.
+ * All implementations must henceforth have this type.
+ */
void
g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point,
GType type)
@@ -375,18 +445,47 @@
extension_point->required_type = type;
}
+/**
+ * g_io_extension_point_get_required_type:
+ * @extension_point: a #GIOExtensionPoint
+ *
+ * Gets the required type for @extension_point.
+ *
+ * Returns: the #GType that all implementations must have,
+ * or #G_TYPE_INVALID if the extension point has no required type
+ */
GType
g_io_extension_point_get_required_type (GIOExtensionPoint *extension_point)
{
return extension_point->required_type;
}
+/**
+ * g_io_extension_point_get_extensions:
+ * @extension_point: a #GIOExtensionPoint
+ *
+ * Gets a list of all extensions that implement this extension point.
+ * The list is sorted by priority, beginning with the highest priority.
+ *
+ * Returns: a #GList of #GIOExtension<!-- -->s. The list is owned by
+ * GIO and should not be modified
+ */
GList *
g_io_extension_point_get_extensions (GIOExtensionPoint *extension_point)
{
return extension_point->extensions;
}
+/**
+ * g_io_extension_point_get_extension_by_name:
+ * @extension_point: a #GIOExtensionPoint
+ * @name: the name of the extension to get
+ *
+ * Finds a #GIOExtension for an extension point by name.
+ *
+ * Returns: the #GIOExtension for @extension_point that has the
+ * given name, or %NULL if there is no extension with that name
+ */
GIOExtension *
g_io_extension_point_get_extension_by_name (GIOExtensionPoint *extension_point,
const char *name)
@@ -414,11 +513,26 @@
return extension_b->priority - extension_a->priority;
}
+/**
+ * g_io_extension_point_implement:
+ * @extension_point_name: the name of the extension point
+ * @type: the #GType to register as extension
+ * @extension_name: the name for the extension
+ * @priority: the priority for the extension
+ *
+ * Registers @type as extension for the extension point with name
+ * @extension_point_name.
+ *
+ * If @type has already been registered as an extension for this
+ * extension point, the existing #GIOExtension object is returned.
+ *
+ * Returns: a #GIOExtension object for #GType
+ */
GIOExtension *
g_io_extension_point_implement (const char *extension_point_name,
- GType type,
+ GType type,
const char *extension_name,
- gint priority)
+ gint priority)
{
GIOExtensionPoint *extension_point;
GIOExtension *extension;
@@ -463,25 +577,60 @@
return extension;
}
+/**
+ * g_io_extension_ref_class:
+ * @extension: a #GIOExtension
+ *
+ * Gets a reference to the class for the type that is
+ * associated with @extension.
+ *
+ * Returns: the #GTypeClass for the type of @extension
+ */
GTypeClass *
g_io_extension_ref_class (GIOExtension *extension)
{
return g_type_class_ref (extension->type);
}
-
+/**
+ * g_io_extension_get_type:
+ * @extension: a #GIOExtension
+ *
+ * Gets the type associated with @extension.
+ *
+ * Returns: the type of @extension
+ */
GType
g_io_extension_get_type (GIOExtension *extension)
{
return extension->type;
}
+/**
+ * g_io_extension_get_name:
+ * @extension: a #GIOExtension
+ *
+ * Gets the name under which @extension was registered.
+ *
+ * Note that the same type may be registered as extension
+ * for multiple extension points, under different names.
+ *
+ * Returns: the name of @extension.
+ */
const char *
g_io_extension_get_name (GIOExtension *extension)
{
return extension->name;
}
+/**
+ * g_io_extension_get_priority:
+ * @extension: a #GIOExtension
+ *
+ * Gets the priority with which @extension was registered.
+ *
+ * Returns: the priority of @extension
+ */
gint
g_io_extension_get_priority (GIOExtension *extension)
{
Modified: trunk/gio/giomodule.h
==============================================================================
--- trunk/gio/giomodule.h (original)
+++ trunk/gio/giomodule.h Mon Feb 11 07:12:56 2008
@@ -55,8 +55,8 @@
GList *g_io_modules_load_all_in_directory (const char *dirname);
-GIOExtensionPoint *g_io_extension_point_register (const char *extension_point);
-GIOExtensionPoint *g_io_extension_point_lookup (const char *extension_point);
+GIOExtensionPoint *g_io_extension_point_register (const char *name);
+GIOExtensionPoint *g_io_extension_point_lookup (const char *name);
void g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point,
GType type);
GType g_io_extension_point_get_required_type (GIOExtensionPoint *extension_point);
@@ -78,8 +78,9 @@
* 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.
+ * 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);
@@ -87,8 +88,9 @@
* 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.
+ * 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);
Modified: trunk/gio/glocaldirectorymonitor.h
==============================================================================
--- trunk/gio/glocaldirectorymonitor.h (original)
+++ trunk/gio/glocaldirectorymonitor.h Mon Feb 11 07:12:56 2008
@@ -58,9 +58,9 @@
GType g_local_directory_monitor_get_type (void) G_GNUC_CONST;
-GFileMonitor* _g_local_directory_monitor_new (const char* dirname,
- GFileMonitorFlags flags,
- GError **error);
+GFileMonitor* _g_local_directory_monitor_new (const char *dirname,
+ GFileMonitorFlags flags,
+ GError **error);
G_END_DECLS
Modified: trunk/gio/glocalfilemonitor.h
==============================================================================
--- trunk/gio/glocalfilemonitor.h (original)
+++ trunk/gio/glocalfilemonitor.h Mon Feb 11 07:12:56 2008
@@ -52,9 +52,9 @@
GType g_local_file_monitor_get_type (void) G_GNUC_CONST;
-GFileMonitor* _g_local_file_monitor_new (const char* pathname,
- GFileMonitorFlags flags,
- GError **error);
+GFileMonitor* _g_local_file_monitor_new (const char *pathname,
+ GFileMonitorFlags flags,
+ GError **error);
G_END_DECLS
Modified: trunk/gio/gvolume.c
==============================================================================
--- trunk/gio/gvolume.c (original)
+++ trunk/gio/gvolume.c Mon Feb 11 07:12:56 2008
@@ -56,6 +56,19 @@
* #GAsyncReady data to see if the operation was completed
* successfully. If an @error is present when g_volume_mount_finish()
* is called, then it will be filled with any error information.
+ *
+ * <para id="volume-identifier">
+ * It is sometimes necessary to directly access the underlying
+ * operating system object behind a volume (e.g. for passing a volume
+ * to an application via the commandline). For this purpose, GIO
+ * allows to obtain an 'identifier' for the volume. There can be
+ * different kinds of identifiers, such as Hal UDIs, filesystem labels,
+ * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
+ * uuids. GIO uses predefind strings as names for the different kinds
+ * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
+ * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
+ * to obtain an identifier for a volume.
+ * </para>
**/
static void g_volume_base_init (gpointer g_class);
@@ -288,6 +301,14 @@
return (* iface->can_eject) (volume);
}
+/**
+ * g_volume_should_automount:
+ * @volume: a #GVolume
+ *
+ * Returns whether the volume should be automatically mounted.
+ *
+ * Returns: %TRUE if the volume should be automatically mounted.
+ */
gboolean
g_volume_should_automount (GVolume *volume)
{
@@ -441,7 +462,9 @@
* @volume: a #GVolume
* @kind: the kind of identifier to return
*
- * Gets the identifier of the given kind for @volume.
+ * Gets the identifier of the given kind for @volume.
+ * See the <link linkend="volume-identifier">introduction</link>
+ * for more information about volume identifiers.
*
* Returns: a newly allocated string containing the
* requested identfier, or %NULL if the #GVolume
@@ -467,10 +490,10 @@
/**
* g_volume_enumerate_identifiers:
* @volume: a #GVolume
- *
- * Gets the kinds of identifiers that @volume has.
- * Use g_volume_get_identifer() to obtain the identifiers
- * themselves.
+ *
+ * Gets the kinds of <link linkend="volume-identifier">identifiers</link>
+ * that @volume has. Use g_volume_get_identifer() to obtain
+ * the identifiers themselves.
*
* Returns: a %NULL-terminated array of strings containing
* kinds of identifiers. Use g_strfreev() to free.
Modified: trunk/gio/gvolume.h
==============================================================================
--- trunk/gio/gvolume.h (original)
+++ trunk/gio/gvolume.h Mon Feb 11 07:12:56 2008
@@ -34,10 +34,39 @@
G_BEGIN_DECLS
+/**
+ * G_VOLUME_IDENTIFIER_KIND_HAL_UDI:
+ *
+ * The string used to obtain a Hal UDI with g_volume_get_identifier().
+ */
#define G_VOLUME_IDENTIFIER_KIND_HAL_UDI "hal-udi"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE:
+ *
+ * The string used to obtain a Unix device path with g_volume_get_identifier().
+ */
#define G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE "unix-device"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_LABEL:
+ *
+ * The string used to obtain a filesystem label with g_volume_get_identifier().
+ */
#define G_VOLUME_IDENTIFIER_KIND_LABEL "label"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_UUID:
+ *
+ * The string used to obtain a UUID with g_volume_get_identifier().
+ */
#define G_VOLUME_IDENTIFIER_KIND_UUID "uuid"
+
+/**
+ * G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT:
+ *
+ * The string used to obtain a NFS mount with g_volume_get_identifier().
+ */
#define G_VOLUME_IDENTIFIER_KIND_NFS_MOUNT "nfs-mount"
@@ -62,10 +91,11 @@
* @mount_finish: Finishes a mount operation.
* @eject: Ejects a given #GVolume.
* @eject_finish: Finishes an eject operation.
- * @get_identifier: Returns the identifier of the given kind, or %NULL if
+ * @get_identifier: Returns the <link linkend="volume-identifier">identifier</link> of the given kind, or %NULL if
* the #GVolume doesn't have one.
* @enumerate_identifiers: Returns an array strings listing the kinds
- * of identifiers which the #GVolume has.
+ * of <link linkend="volume-identifier">identifiers</link> which the #GVolume has.
+ * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted.
*
* Interface for implementing operations for mountable volumes.
**/
Modified: trunk/gio/gvolumemonitor.c
==============================================================================
--- trunk/gio/gvolumemonitor.c (original)
+++ trunk/gio/gvolumemonitor.c Mon Feb 11 07:12:56 2008
@@ -238,11 +238,11 @@
* @volume_monitor: a #GVolumeMonitor.
*
* Gets a list of drives connected to the system.
- *
- * The returned list should be freed with g_list_free(), but
- * its elements need not be freed.
*
- * Returns: a #GList of connected #GDrives - free with g_list_free().
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
+ *
+ * Returns: a #GList of connected #GDrive<!-- -->s
**/
GList *
g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor)
@@ -261,11 +261,11 @@
* @volume_monitor: a #GVolumeMonitor.
*
* Gets a list of the volumes on the system.
- *
- * The returned list should be freed with g_list_free(), but
- * its elements need not be freed.
*
- * Returns: a #GList of #GVolume - free with g_list_free().
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
+ *
+ * Returns: a #GList of #GVolume<!-- -->s.
**/
GList *
g_volume_monitor_get_volumes (GVolumeMonitor *volume_monitor)
@@ -285,10 +285,10 @@
*
* Gets a list of the mounts on the system.
*
- * The returned list should be freed with g_list_free(), but
- * its elements need not be freed.
+ * The returned list should be freed with g_list_free(), after
+ * its elements have been unreffed with g_object_unref().
*
- * Returns: a #GList of #GMount - free with g_list_free().
+ * Returns: a #GList of #GMount<!-- -->s
**/
GList *
g_volume_monitor_get_mounts (GVolumeMonitor *volume_monitor)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
