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.
Details
enum GnomeMetadataError_t
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.
gnome_metadata_set ()
int gnome_metadata_set (const char *file,
const char *name,
int size,
const char *data);
Sets metadata associated with file and name.
file :
File with which metadata will be associated
name :
Metadata key.
size :
Size in bytes of data
data :
Data to be stored.
Returns :
0 on success or an error code.
gnome_metadata_remove ()
int gnome_metadata_remove (const char *file,
const char *name);
Remove a piece of metadata associated with file.
file :
File name
name :
Metadata key.
Returns :
0 on success, or an error code.
gnome_metadata_list ()
char** gnome_metadata_list (const char *file);
file :
File name.
Returns :
an array of all metadata keys associated with file. The
array is NULL terminated. The result can be freed with
g_strfreev(). This only returns keys for which there
is a particular association with file. It will not return keys
for which a regex or other match succeeds.
gnome_metadata_get ()
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 g_malloc()d.
file :
File name
name :
Metadata key
size :
Return parameter for size of data
buffer :
Return parameter for data
Returns :
0, or an error code. On error *buffer will be set to NULL.
gnome_metadata_get_fast ()
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.
file :
File name
name :
Metadata key
size :
Return parameter for size of data
buffer :
Return parameter for data
Returns :
0, or an error code. On error *buffer will be set to
NULL.
gnome_metadata_rename ()
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.
from :
Source file name
to :
Destination file name
Returns :
0 on success, or an error code.
gnome_metadata_copy ()
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.
from :
Source file name
to :
Destination file name
Returns :
0 on success, or an error code.
gnome_metadata_delete ()
int gnome_metadata_delete (const char *file);
This function deletes all metadata associated with file.
It should be called after a file is deleted.
