diff options
| -rw-r--r-- | gio/ChangeLog | 9 | ||||
| -rw-r--r-- | gio/gappinfo.c | 8 | ||||
| -rw-r--r-- | gio/gappinfo.h | 6 | ||||
| -rw-r--r-- | gio/gdesktopappinfo.c | 19 | ||||
| -rw-r--r-- | gio/gdesktopappinfo.h | 12 | ||||
| -rw-r--r-- | gio/gdrive.c | 3 | ||||
| -rw-r--r-- | gio/giomodule.c | 159 | ||||
| -rw-r--r-- | gio/giomodule.h | 14 | ||||
| -rw-r--r-- | gio/glocaldirectorymonitor.h | 6 | ||||
| -rw-r--r-- | gio/glocalfilemonitor.h | 6 | ||||
| -rw-r--r-- | gio/gvolume.c | 33 | ||||
| -rw-r--r-- | gio/gvolume.h | 34 | ||||
| -rw-r--r-- | gio/gvolumemonitor.c | 22 |
13 files changed, 284 insertions, 47 deletions
diff --git a/gio/ChangeLog b/gio/ChangeLog index eed5f24a8..8758fa6a6 100644 --- a/gio/ChangeLog +++ b/gio/ChangeLog @@ -1,3 +1,12 @@ +2008-02-11 Matthias Clasen <mclasen@redhat.com> + + * *.c: Documentation additions + +2008-02-10 Matthias Clasen <mclasen@redhat.com> + + * gappinfo.h: Formatting cleanup + * gappinfo.c: Fix up docs. + 2008-02-09 Matthias Clasen <mclasen@redhat.com> * gunixmounts.c: Consistently use getmntent_r() and fall diff --git a/gio/gappinfo.c b/gio/gappinfo.c index 251ff969b..1ef8152d8 100644 --- a/gio/gappinfo.c +++ b/gio/gappinfo.c @@ -532,7 +532,7 @@ g_app_info_should_show (GAppInfo *appinfo) /** * 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 @@ g_app_info_should_show (GAppInfo *appinfo) * 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; diff --git a/gio/gappinfo.h b/gio/gappinfo.h index b1872ba0a..d0fddf75b 100644 --- a/gio/gappinfo.h +++ b/gio/gappinfo.h @@ -186,9 +186,9 @@ GAppInfo *g_app_info_get_default_for_type (const char *content_type, gboolean must_support_uris); GAppInfo *g_app_info_get_default_for_uri_scheme (const char *uri_scheme); -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: diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 252d4a563..2ddff6cc7 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -1662,7 +1662,9 @@ g_app_info_get_default_for_type (const char *content_type, * @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_base_init (gpointer g_class) { } +/** + * 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; diff --git a/gio/gdesktopappinfo.h b/gio/gdesktopappinfo.h index 85307d066..f8d7250b6 100644 --- a/gio/gdesktopappinfo.h +++ b/gio/gdesktopappinfo.h @@ -59,6 +59,12 @@ void g_desktop_app_info_set_desktop_env (const char *desktop_env); #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 @@ struct _GDesktopAppInfoLookupIface 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 diff --git a/gio/gdrive.c b/gio/gdrive.c index 18a7ecde8..ed75d03cd 100644 --- a/gio/gdrive.c +++ b/gio/gdrive.c @@ -215,6 +215,9 @@ g_drive_has_volumes (GDrive *drive) * @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. **/ diff --git a/gio/giomodule.c b/gio/giomodule.c index 9ec12ffda..1b5a06d93 100644 --- a/gio/giomodule.c +++ b/gio/giomodule.c @@ -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_io_extension_point_free (GIOExtensionPoint *ep) 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 @@ g_io_extension_point_register (const char *name) 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_lookup (const char *name) } +/** + * 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 @@ g_io_extension_point_set_required_type (GIOExtensionPoint *extension_point, 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 @@ extension_prio_compare (gconstpointer a, 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 @@ g_io_extension_point_implement (const char *extension_point_name, 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) { diff --git a/gio/giomodule.h b/gio/giomodule.h index 76c27cef5..2801d7736 100644 --- a/gio/giomodule.h +++ b/gio/giomodule.h @@ -55,8 +55,8 @@ GIOModule *g_io_module_new (const gchar *filename); 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 @@ GTypeClass* g_io_extension_ref_class (GIOExtension *extension); * 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 @@ 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. + * 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); diff --git a/gio/glocaldirectorymonitor.h b/gio/glocaldirectorymonitor.h index c40e5efcd..7265ce449 100644 --- a/gio/glocaldirectorymonitor.h +++ b/gio/glocaldirectorymonitor.h @@ -58,9 +58,9 @@ struct _GLocalDirectoryMonitorClass { 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 diff --git a/gio/glocalfilemonitor.h b/gio/glocalfilemonitor.h index 81a38a3c0..f667f8460 100644 --- a/gio/glocalfilemonitor.h +++ b/gio/glocalfilemonitor.h @@ -52,9 +52,9 @@ struct _GLocalFileMonitorClass { 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 diff --git a/gio/gvolume.c b/gio/gvolume.c index 28bf63520..3aa174daf 100644 --- a/gio/gvolume.c +++ b/gio/gvolume.c @@ -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 @@ g_volume_can_eject (GVolume *volume) 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 @@ g_volume_eject_finish (GVolume *volume, * @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_get_identifier (GVolume *volume, /** * 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. diff --git a/gio/gvolume.h b/gio/gvolume.h index c5b8c564d..c46220111 100644 --- a/gio/gvolume.h +++ b/gio/gvolume.h @@ -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 @@ G_BEGIN_DECLS * @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. **/ diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c index fbd6ab02e..d17438bbd 100644 --- a/gio/gvolumemonitor.c +++ b/gio/gvolumemonitor.c @@ -238,11 +238,11 @@ g_volume_monitor_init (GVolumeMonitor *monitor) * @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 @@ g_volume_monitor_get_connected_drives (GVolumeMonitor *volume_monitor) * @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 @@ g_volume_monitor_get_volumes (GVolumeMonitor *volume_monitor) * * 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) |