luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 15:06:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation additions

Browse Source 
svn path=/trunk/; revision=6492
This commit is contained in:
Matthias Clasen 2008-02-11 07:12:56 +00:00
parent 5e45af1f07
commit 826d8c5b41
13 changed files with 284 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
gio/ChangeLog
View File

@ -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

8
gio/gappinfo.c
View File

@ -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;

6
gio/gappinfo.h
View File

@ -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:

19
gio/gdesktopappinfo.c
View File

@ -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;

12
gio/gdesktopappinfo.h
View File

@ -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

3
gio/gdrive.c
View File

@ -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.
**/

159
gio/giomodule.c
View File

@ -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;
*
* /&ast; Register an extension point &ast;/
* ep = g_io_extension_point_register ("my-extension-point");
* g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
* ]|
*
* |[
* /&ast; Implement an extension point &ast;/
* 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)
{

14
gio/giomodule.h
View File

@ -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);

6
gio/glocaldirectorymonitor.h
View File

@ -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

6
gio/glocalfilemonitor.h
View File

@ -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

33
gio/gvolume.c
View File

@ -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.

34
gio/gvolume.h
View File

@ -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.
**/

22
gio/gvolumemonitor.c
View File

@ -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)