| Gnome Library Reference Manual | |||
|---|---|---|---|
| <<< Previous Page | Home | Up | Next Page >>> | 
| #include <gnome.h> enum GnomeMetadataError_t; int gnome_metadata_set (const char *file, const char *name, int size, const char *data); int gnome_metadata_remove (const char *file, const char *name); char** gnome_metadata_list (const char *file); int gnome_metadata_get (const char *file, const char *name, int *size, char **buffer); int gnome_metadata_get_fast (const char *file, const char *name, int *size, char **buffer); int gnome_metadata_rename (const char *from, const char *to); int gnome_metadata_copy (const char *from, const char *to); int gnome_metadata_delete (const char *file); void gnome_metadata_regex_add (const char *regex, const char *key, int size, const char *data); void gnome_metadata_regex_remove (const char *regex, const char *key); void gnome_metadata_type_add (const char *type, const char *key, int size, const char *data); void gnome_metadata_type_remove (const char *type, const char *key); void gnome_metadata_lock (void); void gnome_metadata_unlock (void); | 
One of the problems that a desktop environment faces is the fact that it is usually necessary to have a mechanism for storing information about a file's properties. For example, applications might want to bind an icon for a specific executable file or bind a small thumbnail image for a graphic produced by a graphics program. These icons should be semantically attached to the main file.
The GNOME metadata was implemented by Tom Tromey at Cygnus, given a number of design constraints and tradeoffs (described in detail in [TROMEY]).
Here is a list of the GNOME metadata features:
Binding the information on a per-file basis: This is a per-user setting and each user keeps track of his own bindings. System defaults apply on top of these.
Binding information by file content: Given the type of the file (using file signatures, similar to the Unix-file(1) command).
Binding information by a regular expression. For example, a default icon for gif files would be provided by a regular expression "*.\.gif$".
The metadata system is optimized to provide a coherent GUI solution, rather than as a compromise to kludging existing command line tools.
Most ordinary uses of files will continue to work without metadata, just as they do now.
There are a number of standard properties for file metadata in GNOME, for example: "View" stores the action for viewing the file contents; "Open" stores analogous action for editing; "Icon" which contains the icon used for displaying the file on the desktop. For a complete list of the existing keys see FIXME.
| typedef enum
{
	GNOME_METADATA_OK = 0,		   /* No error. */
	GNOME_METADATA_IO_ERROR,	   /* IO or other low-level
					      communications/storage
					      error.  */
	GNOME_METADATA_NOT_FOUND	   /* Information not found.  */
} GnomeMetadataError_t; | 
This describes the errors that can be returned by some gnome-metadata functions.
| int         gnome_metadata_set              (const char *file,
                                             const char *name,
                                             int size,
                                             const char *data); | 
Sets metadata associated with file and name.
| int         gnome_metadata_remove           (const char *file,
                                             const char *name); | 
Remove a piece of metadata associated with file.
| int         gnome_metadata_get              (const char *file,
                                             const char *name,
                                             int *size,
                                             char **buffer); | 
Get a piece of metadata associated with file.  size and buffer
are result parameters.  *buffer is 
| int         gnome_metadata_get_fast         (const char *file,
                                             const char *name,
                                             int *size,
                                             char **buffer); | 
Like gnome_metadata_get(), but won't run the `file' command to characterize the file type.
| int         gnome_metadata_rename           (const char *from,
                                             const char *to); | 
This function moves metadata associated with file from to file to. It should be called after a file is renamed.
| int         gnome_metadata_copy             (const char *from,
                                             const char *to); | 
This function copies metadata associated with file from to file to. It should be called after a file is copied.
| int gnome_metadata_delete (const char *file); | 
This function deletes all metadata associated with file. It should be called after a file is deleted.
| void        gnome_metadata_regex_add        (const char *regex,
                                             const char *key,
                                             int size,
                                             const char *data); | 
Add a regular expression to the internal list. This regex is used when matching requests for the metadata key.
| void        gnome_metadata_regex_remove     (const char *regex,
                                             const char *key); | 
Remove the regular expression from the internal list.
| void        gnome_metadata_type_add         (const char *type,
                                             const char *key,
                                             int size,
                                             const char *data); | 
Add a file type to the internal list. This pairing is used when matching requests for the metadata key.
| void        gnome_metadata_type_remove      (const char *type,
                                             const char *key); | 
Remove a type/key pairing from the internal list.
| void gnome_metadata_lock (void); | 
Locks the metadata system. Used if you are going to invoke many metadata operations to speed up metadata access.