Gnome Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# gnome-metadata

## Name

gnome-metadata -- File metadata information storage.

## Synopsis

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

## Description

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.

`file` : | File name
Returns : | `0` on success, or an error code.

### gnome_metadata_regex_add ()

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

`regex` : | The regular expression.
`key` : | The metadata key.
`size` : | Size of data in bytes.
`data` : | The data.

### gnome_metadata_regex_remove ()

    void        gnome_metadata_regex_remove     (const char *regex,
                                                 const char *key);

Remove the regular expression from the internal list.

`regex` : | The regular expression.
`key` : | The metadata key.

### gnome_metadata_type_add ()

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

`type` : | File type
`key` : | The metadata key.
`size` : | Size of data in bytes.
`data` : | The data.

### gnome_metadata_type_remove ()

    void        gnome_metadata_type_remove      (const char *type,
                                                 const char *key);

Remove a type/key pairing from the internal list.

`type` : | The file type.
`key` : | The metadata key.

### gnome_metadata_lock ()

    void        gnome_metadata_lock             (void);

Locks the metadata system. Used if you are going to invoke many metadata operations to speed up metadata access.

### gnome_metadata_unlock ()

    void        gnome_metadata_unlock           (void);

Unlocks the metadata system. Used if you are going to invoke many metadata operations to speed up metadata access.

<<< Previous Page | Home | Up | Next Page >>>
gnome-i18n | gnome-mime-info