MafwMetadata

MafwMetadata — Metadata representation in MAFW

Synopsis

#define             MAFW_METADATA_KEY_ADDED
#define             MAFW_METADATA_KEY_MODIFIED
#define             MAFW_METADATA_KEY_ALBUM
#define             MAFW_METADATA_KEY_ALBUM_INFO_URI
#define             MAFW_METADATA_KEY_ALBUM_ART
#define             MAFW_METADATA_KEY_ALBUM_ART_URI
#define             MAFW_METADATA_KEY_ALBUM_ART_LARGE_URI
#define             MAFW_METADATA_KEY_ALBUM_ART_MEDIUM_URI
#define             MAFW_METADATA_KEY_ALBUM_ART_SMALL_URI
#define             MAFW_METADATA_KEY_RENDERER_ART_URI
#define             MAFW_METADATA_KEY_ORGANIZATION
#define             MAFW_METADATA_KEY_PAUSED_POSITION
#define             MAFW_METADATA_KEY_PAUSED_THUMBNAIL_URI
#define             MAFW_METADATA_KEY_VIDEO_SOURCE
#define             MAFW_METADATA_KEY_ARTIST
#define             MAFW_METADATA_KEY_ARTIST_INFO_URI
#define             MAFW_METADATA_KEY_AUDIO_BITRATE
#define             MAFW_METADATA_KEY_AUDIO_CODEC
#define             MAFW_METADATA_KEY_BITRATE
#define             MAFW_METADATA_KEY_BPP
#define             MAFW_METADATA_KEY_CHILDCOUNT        (n)
#define             MAFW_METADATA_KEY_CHILDCOUNT_1
#define             MAFW_METADATA_KEY_CHILDCOUNT_2
#define             MAFW_METADATA_KEY_CHILDCOUNT_3
#define             MAFW_METADATA_KEY_CHILDCOUNT_4
#define             MAFW_METADATA_KEY_CHILDCOUNT_5
#define             MAFW_METADATA_KEY_CHILDCOUNT_6
#define             MAFW_METADATA_KEY_CHILDCOUNT_7
#define             MAFW_METADATA_KEY_CHILDCOUNT_8
#define             MAFW_METADATA_KEY_CHILDCOUNT_9
#define             MAFW_METADATA_KEY_COMMENT
#define             MAFW_METADATA_KEY_COMPOSER
#define             MAFW_METADATA_KEY_COPYRIGHT
#define             MAFW_METADATA_KEY_COUNT
#define             MAFW_METADATA_KEY_DESCRIPTION
#define             MAFW_METADATA_KEY_DIDL
#define             MAFW_METADATA_KEY_DURATION
#define             MAFW_METADATA_KEY_ENCODING
#define             MAFW_METADATA_KEY_EXIF_XML
#define             MAFW_METADATA_KEY_FILENAME
#define             MAFW_METADATA_KEY_FILESIZE
#define             MAFW_METADATA_KEY_GENRE
#define             MAFW_METADATA_KEY_ICON
#define             MAFW_METADATA_KEY_ICON_URI
#define             MAFW_METADATA_KEY_IS_SEEKABLE
#define             MAFW_METADATA_KEY_LAST_PLAYED
#define             MAFW_METADATA_KEY_LYRICS
#define             MAFW_METADATA_KEY_LYRICS_URI
#define             MAFW_METADATA_KEY_PLAY_COUNT
#define             MAFW_METADATA_KEY_PROTOCOL_INFO
#define             MAFW_METADATA_KEY_RATING
#define             MAFW_METADATA_KEY_RES_X
#define             MAFW_METADATA_KEY_RES_Y
#define             MAFW_METADATA_KEY_TAGS
#define             MAFW_METADATA_KEY_THUMBNAIL
#define             MAFW_METADATA_KEY_THUMBNAIL_URI
#define             MAFW_METADATA_KEY_TITLE
#define             MAFW_METADATA_KEY_TRACK
#define             MAFW_METADATA_KEY_VIDEO_BITRATE
#define             MAFW_METADATA_KEY_VIDEO_CODEC
#define             MAFW_METADATA_KEY_VIDEO_FRAMERATE
#define             MAFW_METADATA_KEY_YEAR
#define             MAFW_METADATA_KEY_MIME
#define             MAFW_METADATA_KEY_URI
#define             MAFW_METADATA_VALUE_MIME_CONTAINER
gboolean            (*MafwMetadataComparator)           (MafwFilterType rel,
                                                         const gchar *key,
                                                         const GValue *lhsgv,
                                                         const GValue *rshgv);
#define             mafw_metadata_add_int               (md, key, ...)
#define             mafw_metadata_add_boolean           (md, key, ...)
#define             mafw_metadata_add_double            (md, key, ...)
#define             mafw_metadata_add_int64             (md, key, ...)
#define             mafw_metadata_add_long              (md, key, ...)
#define             mafw_metadata_add_uint              (md, key, ...)
#define             mafw_metadata_add_uint64            (md, key, ...)
#define             mafw_metadata_add_ulong             (md, key, ...)
void                mafw_metadata_add_something         (GHashTable *md,
                                                         const gchar *key,
                                                         GType argvtype,
                                                         guint nvalues,
                                                         ...);
#define             mafw_metadata_add_str               (md, key, ...)
#define             mafw_metadata_add_val               (md, key, ...)
gint                mafw_metadata_compare               (GHashTable *md1,
                                                         GHashTable *md2,
                                                         const gchar *const *terms,
                                                         MafwMetadataComparator funcomp);
gboolean            mafw_metadata_filter                (GHashTable *md,
                                                         const MafwFilter *filter,
                                                         MafwMetadataComparator funcomp);
GValue*             mafw_metadata_first                 (GHashTable *md,
                                                         const gchar *key);
GHashTable*         mafw_metadata_new                   (void);
guint               mafw_metadata_nvalues               (gconstpointer value);
gboolean            mafw_metadata_ordered               (MafwFilterType rel,
                                                         const gchar *key,
                                                         const GValue *lhsgv,
                                                         const GValue *rhsgv);
void                mafw_metadata_print                 (GHashTable *md,
                                                         const gchar *domain);
void                mafw_metadata_print_one             (const gchar *key,
                                                         gpointer val,
                                                         const gchar *domain);
void                mafw_metadata_release               (GHashTable *md);
const gchar**       mafw_metadata_relevant_keys         (const gchar *const *keys,
                                                         const MafwFilter *filter,
                                                         const gchar *const *sorting);
gchar**             mafw_metadata_sorting_terms         (const gchar *sorting);
gchar*              mafw_metadata_freeze                (GHashTable *md,
                                                         gsize *sstreamp);
GByteArray*         mafw_metadata_freeze_bary           (GHashTable *md);
GHashTable*         mafw_metadata_thaw                  (const gchar *stream,
                                                         gsize sstream);
GHashTable*         mafw_metadata_thaw_bary             (GByteArray *bary);
gchar*              mafw_metadata_val_freeze            (gpointer val,
                                                         gsize *sstreamp);
void                mafw_metadata_val_freeze_bary       (GByteArray *bary,
                                                         gpointer val);
gpointer            mafw_metadata_val_thaw_bary         (GByteArray *bary,
                                                         gsize *i);

Description

Metadata of objects in the framework are represented in "s" called mafw metadata hash tables as tag-value pairs. Tags (keys of the hash table) are strings, while values are "s". In a mafw metadata hash table Every tag has at least one one.

Use mafw_metadata_new() to create a mafw metadata hash table. You can use mafw_metadata_release() when you don't need it anymore, or you can use the regular GLib function.

You can add metadata to the hash table with the mafw_metadata_add_*() functions. If you set the value of the same tag several times the values will automatically be merged, forming a multiple-valued tag. String values set with mafw_metadata_add_string() are duplicated. Once you set one type of value to a metadata tag you must not set another one with a different type.

One way to query the structure is using ordinary g_hash_table_*() functions. This case with mafw_metadata_nvalues() you can enable your client to deal with multiple-valued tags correctly. However, if you are only prepared to handle single-valued ones you may use the mafw_metadata_first() function.

Software development is facilitated by the mafw_metadata_print*() functions. You can extend the set of recognized metadata value types by adding cases to check_mdvtype() and mafw_callbas_argv2gval(). Make sure you update mafw_metadata_freeze() and mafw_metadata_thaw() too.

Details

MAFW_METADATA_KEY_ADDED

#define MAFW_METADATA_KEY_ADDED		"added"

Date when item was added into the database. Its value is a long integer.


MAFW_METADATA_KEY_MODIFIED

#define MAFW_METADATA_KEY_MODIFIED	"modified"

Date when item was added into the database. Its value is a long integer.


MAFW_METADATA_KEY_ALBUM

#define MAFW_METADATA_KEY_ALBUM		"album"

Describes the album of the item. Its value is a string.


MAFW_METADATA_KEY_ALBUM_INFO_URI

#define MAFW_METADATA_KEY_ALBUM_INFO_URI	"album-info-uri"

An URI pointing to album information. Its value is an integer.


MAFW_METADATA_KEY_ALBUM_ART

#define MAFW_METADATA_KEY_ALBUM_ART		"album-art"

Album art image. Its value is a byte array.


MAFW_METADATA_KEY_ALBUM_ART_URI

#define MAFW_METADATA_KEY_ALBUM_ART_URI	"album-art-uri"

An URI pointing to the original album art image. Its value is a string.


MAFW_METADATA_KEY_ALBUM_ART_LARGE_URI

#define MAFW_METADATA_KEY_ALBUM_ART_LARGE_URI	"album-art-large-uri"

An URI pointing to large album art image. Its value is a string.


MAFW_METADATA_KEY_ALBUM_ART_MEDIUM_URI

#define MAFW_METADATA_KEY_ALBUM_ART_MEDIUM_URI	"album-art-medium-uri"

An URI pointing to medium album art image. Its value is a string.


MAFW_METADATA_KEY_ALBUM_ART_SMALL_URI

#define MAFW_METADATA_KEY_ALBUM_ART_SMALL_URI	"album-art-small-uri"

An URI pointing to small album art image. Its value is a string.


MAFW_METADATA_KEY_RENDERER_ART_URI

#define MAFW_METADATA_KEY_RENDERER_ART_URI	"renderer-art-uri"

Album art image uri coming from renderer. Its value is a string.


MAFW_METADATA_KEY_ORGANIZATION

#define MAFW_METADATA_KEY_ORGANIZATION		"organization"

Describes the organization of the item. Its value is a string.


MAFW_METADATA_KEY_PAUSED_POSITION

#define MAFW_METADATA_KEY_PAUSED_POSITION   "paused-position"

Position where the item is paused. Its value is an integer.


MAFW_METADATA_KEY_PAUSED_THUMBNAIL_URI

#define MAFW_METADATA_KEY_PAUSED_THUMBNAIL_URI   "paused-thumbnail-uri"

URI pointing to the thumbnail of the frame where video was paused. Its value is a string.


MAFW_METADATA_KEY_VIDEO_SOURCE

#define MAFW_METADATA_KEY_VIDEO_SOURCE         "video-source"

Information about the source of the video. Provides information like, for example, the hardware used to record it. Its value is a string.


MAFW_METADATA_KEY_ARTIST

#define MAFW_METADATA_KEY_ARTIST		"artist"

Describes the artist of the item. Its value is a string.


MAFW_METADATA_KEY_ARTIST_INFO_URI

#define MAFW_METADATA_KEY_ARTIST_INFO_URI	"artist-info-uri"

An URI pointing to artist description. Its value is a string.


MAFW_METADATA_KEY_AUDIO_BITRATE

#define MAFW_METADATA_KEY_AUDIO_BITRATE	"audio-bitrate"

The bitrate used to encode the item. Its value is an integer.


MAFW_METADATA_KEY_AUDIO_CODEC

#define MAFW_METADATA_KEY_AUDIO_CODEC		"audio-codec"

The coder/decoder information for item. Its value is a string.


MAFW_METADATA_KEY_BITRATE

#define MAFW_METADATA_KEY_BITRATE		"bitrate"

Describes the bitrate of the item. Its value is an integer.


MAFW_METADATA_KEY_BPP

#define MAFW_METADATA_KEY_BPP			"bpp"

Describes how many bits are used to represent a pixel. Its value is an integer.


MAFW_METADATA_KEY_CHILDCOUNT()

#define MAFW_METADATA_KEY_CHILDCOUNT(n)		g_strdup_printf("childcount(%d)", (n))

Describes the amount of child items the item has at level n. MAFW_METADATA_KEY_CHILDCOUNT(1) is the number of chldren, MAFW_METADATA_KEY_CHILDCOUNT(2) is the number of grandchildren, and so on. Its value is an integer. Everytime this macro is invoked, new memory is created. User must free it when no needed.

n : at which level should the count be computed. First is level 1 (children)

MAFW_METADATA_KEY_CHILDCOUNT_1

#define MAFW_METADATA_KEY_CHILDCOUNT_1          "childcount(1)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(1).


MAFW_METADATA_KEY_CHILDCOUNT_2

#define MAFW_METADATA_KEY_CHILDCOUNT_2          "childcount(2)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(2).


MAFW_METADATA_KEY_CHILDCOUNT_3

#define MAFW_METADATA_KEY_CHILDCOUNT_3          "childcount(3)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(3).


MAFW_METADATA_KEY_CHILDCOUNT_4

#define MAFW_METADATA_KEY_CHILDCOUNT_4          "childcount(4)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(4).


MAFW_METADATA_KEY_CHILDCOUNT_5

#define MAFW_METADATA_KEY_CHILDCOUNT_5          "childcount(5)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(5).


MAFW_METADATA_KEY_CHILDCOUNT_6

#define MAFW_METADATA_KEY_CHILDCOUNT_6          "childcount(6)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(6).


MAFW_METADATA_KEY_CHILDCOUNT_7

#define MAFW_METADATA_KEY_CHILDCOUNT_7          "childcount(7)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(7).


MAFW_METADATA_KEY_CHILDCOUNT_8

#define MAFW_METADATA_KEY_CHILDCOUNT_8          "childcount(8)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(8).


MAFW_METADATA_KEY_CHILDCOUNT_9

#define MAFW_METADATA_KEY_CHILDCOUNT_9          "childcount(9)"

Static version of MAFW_METADATA_KEY_CHILDCOUNT(9).


MAFW_METADATA_KEY_COMMENT

#define MAFW_METADATA_KEY_COMMENT		"comment"

Comment describing the item. Its value is a string.


MAFW_METADATA_KEY_COMPOSER

#define MAFW_METADATA_KEY_COMPOSER		"composer"

Describes the composer of the item. Its value is a string.


MAFW_METADATA_KEY_COPYRIGHT

#define MAFW_METADATA_KEY_COPYRIGHT		"copyright"

Copyright disclaimer. Its value is a string.


MAFW_METADATA_KEY_COUNT

#define MAFW_METADATA_KEY_COUNT		"count"

Describes how may times the item exists. Its value is an integer.


MAFW_METADATA_KEY_DESCRIPTION

#define MAFW_METADATA_KEY_DESCRIPTION		"description"

A human readable description of the item. Its value is string.


MAFW_METADATA_KEY_DIDL

#define MAFW_METADATA_KEY_DIDL			"didl"

Item metadata in DIDL lite format. Its value is a string.


MAFW_METADATA_KEY_DURATION

#define MAFW_METADATA_KEY_DURATION		"duration"

Describes the duration of the item (in seconds). Its value is an integer.


MAFW_METADATA_KEY_ENCODING

#define MAFW_METADATA_KEY_ENCODING		"encoding"

Describes how the item is encoded. Its value is a string.


MAFW_METADATA_KEY_EXIF_XML

#define MAFW_METADATA_KEY_EXIF_XML		"exif-xml"

Exif information in XML format. Its value is a string.


MAFW_METADATA_KEY_FILENAME

#define MAFW_METADATA_KEY_FILENAME		"filename"

Original filename of the item resource. Its value is a string.


MAFW_METADATA_KEY_FILESIZE

#define MAFW_METADATA_KEY_FILESIZE		"filesize"

Size (in bytes) of the resource file pointed by the item. Its value is an integer.


MAFW_METADATA_KEY_GENRE

#define MAFW_METADATA_KEY_GENRE		"genre"

Describes the genre of the item. Its value is a string.


MAFW_METADATA_KEY_ICON

#define MAFW_METADATA_KEY_ICON			"icon"

Icon image. Its value is a byte array.


MAFW_METADATA_KEY_ICON_URI

#define MAFW_METADATA_KEY_ICON_URI		"icon-uri"

An URI pointing to icon image. Its value is a string.


MAFW_METADATA_KEY_IS_SEEKABLE

#define MAFW_METADATA_KEY_IS_SEEKABLE		"is-seekable"

Describes if item is seekable. Its value is a boolean.


MAFW_METADATA_KEY_LAST_PLAYED

#define MAFW_METADATA_KEY_LAST_PLAYED		"last-played"

Describes the time in epoch, when the item was played last time. Its value is a long integer.


MAFW_METADATA_KEY_LYRICS

#define MAFW_METADATA_KEY_LYRICS		"lyrics"

Item lyrics. Its value is a string.


MAFW_METADATA_KEY_LYRICS_URI

#define MAFW_METADATA_KEY_LYRICS_URI		"lyrics-uri"

An URI pointing to lyrics related to item. Its value is a string.


MAFW_METADATA_KEY_PLAY_COUNT

#define MAFW_METADATA_KEY_PLAY_COUNT		"play-count"

Describes how may times the item has been played/viewed. Its value is an integer.


MAFW_METADATA_KEY_PROTOCOL_INFO

#define MAFW_METADATA_KEY_PROTOCOL_INFO	"protocol-info"

Describes how may times the item exists. Its value is a string. Specified in UPnP ConnectionManager documentation.


MAFW_METADATA_KEY_RATING

#define MAFW_METADATA_KEY_RATING		"rating"

Describes the rating of the item. Its value is an integer.


MAFW_METADATA_KEY_RES_X

#define MAFW_METADATA_KEY_RES_X		"res-x"

Describes the horizontal resolution of the item. Its value is an integer.


MAFW_METADATA_KEY_RES_Y

#define MAFW_METADATA_KEY_RES_Y		"res-y"

Describes the vertical resolution of the item. Its value is an integer.


MAFW_METADATA_KEY_TAGS

#define MAFW_METADATA_KEY_TAGS			"tags"

List of tags describing the item. Its value is a list of strings.


MAFW_METADATA_KEY_THUMBNAIL

#define MAFW_METADATA_KEY_THUMBNAIL		"thumbnail"

Image thumbnail. Its value is a byte array.


MAFW_METADATA_KEY_THUMBNAIL_URI

#define MAFW_METADATA_KEY_THUMBNAIL_URI	"thumbnail-uri"

URI pointing to a thumbnail. Its value is a string.


MAFW_METADATA_KEY_TITLE

#define MAFW_METADATA_KEY_TITLE		"title"

Describes the title of the item. Its value is a string.


MAFW_METADATA_KEY_TRACK

#define MAFW_METADATA_KEY_TRACK		"track"

Describes the track of the item. Its value is an integer.


MAFW_METADATA_KEY_VIDEO_BITRATE

#define MAFW_METADATA_KEY_VIDEO_BITRATE	"video-bitrate"

The bitrate used to encode the item. Its value is an integer.


MAFW_METADATA_KEY_VIDEO_CODEC

#define MAFW_METADATA_KEY_VIDEO_CODEC		"video-codec"

The coder/decoder information for item. Its value is a string.


MAFW_METADATA_KEY_VIDEO_FRAMERATE

#define MAFW_METADATA_KEY_VIDEO_FRAMERATE	"video-framerate"

The amount of frames per second. Its value is a float.


MAFW_METADATA_KEY_YEAR

#define MAFW_METADATA_KEY_YEAR			"year"

Describes the year of the item. Its value is an integer.


MAFW_METADATA_KEY_MIME

#define MAFW_METADATA_KEY_MIME			"mime-type"

Describes the type and format of the item. Its value is a string of <type> '/' <subtype> defined in RFC2045 section 5.1. The value should be interpreted according to that standard.


MAFW_METADATA_KEY_URI

#define MAFW_METADATA_KEY_URI			"uri"

The URI by which any renderer supporting the schema should be able to locate the item. The value of this metadata is a string, as defined in RFC 3986.metadata


MAFW_METADATA_VALUE_MIME_CONTAINER

#define MAFW_METADATA_VALUE_MIME_CONTAINER      "x-mafw/container"

This is the MIME type of a container provided by MAFW source components.


MafwMetadataComparator ()

gboolean            (*MafwMetadataComparator)           (MafwFilterType rel,
                                                         const gchar *key,
                                                         const GValue *lhsgv,
                                                         const GValue *rshgv);

Prototype of a function comparing metadata values of key. rel is a relation to be asserted, either mafw_f_eq, mafw_f_approx, mafw_f_lt or mafw_f_gt. lhsgv is the left-hand side of the relation, while rhsgv is the right-hand side. The "s" have the same G_VALUE_TYPE.

rel : the filter
key : the key
lhsgv : left argument
rshgv : right argument
Returns : TRUE rel is asserted.

mafw_metadata_add_int()

#define             mafw_metadata_add_int(md, key, ...)

Adds arbitrary number of integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_boolean()

#define             mafw_metadata_add_boolean(md, key, ...)

Adds arbitrary number of boolean values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_double()

#define             mafw_metadata_add_double(md, key, ...)

Adds arbitrary number of double floating pointer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_int64()

#define             mafw_metadata_add_int64(md, key, ...)

Adds arbitrary number of 64 bits integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_long()

#define             mafw_metadata_add_long(md, key, ...)

Adds arbitrary number of long integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_uint()

#define             mafw_metadata_add_uint(md, key, ...)

Adds arbitrary number of unsigned integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_uint64()

#define             mafw_metadata_add_uint64(md, key, ...)

Adds arbitrary number of unsigned 64 bits integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_ulong()

#define             mafw_metadata_add_ulong(md, key, ...)

Adds arbitrary number of unsigned long integer values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are evaluated only once. The integers can, in fact, either be signed or unsigned; their interpretation is up to the one reading the values.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_something ()

void                mafw_metadata_add_something         (GHashTable *md,
                                                         const gchar *key,
                                                         GType argvtype,
                                                         guint nvalues,
                                                         ...);

Adds nvalues number of metadata values of type argvtype to the mafw metadata hash table md.

md : hash table created with mafw_metadata_new()
key : key to use
argvtype : GType of the values
nvalues : number of values to add. If zero, nothing is done.
... : list of values of argvtype to add. All values need to have the same type.

mafw_metadata_add_str()

#define             mafw_metadata_add_str(md, key, ...)

Adds arbitrary number of string values to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are duplicated.

md : hash table
key : key to use
... : list of values

mafw_metadata_add_val()

#define             mafw_metadata_add_val(md, key, ...)

Adds arbitrary number of _values_ of arbitrary GValues to the metadata hash table md. If key already exists in the hash table the new values are appended. key will be duplicated if necessary. If the varadic argument list is empty, nothing is added to md. The value arguments are duplicated. Retrieval of metadata values from md can be done as usual.

md : hash table
key : key to use
... : list of values

mafw_metadata_compare ()

gint                mafw_metadata_compare               (GHashTable *md1,
                                                         GHashTable *md2,
                                                         const gchar *const *terms,
                                                         MafwMetadataComparator funcomp);

Utility function to be called from "tions" to help sorting browse results in mafw_source_browse() implementations.

Compares two mafw metadata hash tables, like a GCompareDataFunc (but not exactly so because it takes more parameters). The order of the hash tables is a function of the sorting terms, a sliced mafw_source_browse() sorting expression. funcomp is used to compare metadata values, and defaults to mafw_metadata_ordered().

For each tag in terms if one of the hash tables has value for it, but the other does not, the latter is sorted downwards. Otherwise the values are compared, and if they are sorting equally the next term is considered. If either or both of the hash tables are NULL it is handled as if it did not have value for any of the terms.

During comparison as many values of the same key are compared one by one as possible, but not more. Since a key may have multiple values this can be more than one. If difference is found that will determine the order of the hash tables, observing the direction requested in current sorting term. Otherwise the hash table having less values for the current tag will be sorted upwards. Conceptually, this is very similar to strcmp().

md1 : first hash table
md2 : second hash table
terms : comparison terms
funcomp : comparison function
Returns : value greater than 0 if first value is greater than second, a negative value if first smaller than second, and 0 if both are equal.

mafw_metadata_filter ()

gboolean            mafw_metadata_filter                (GHashTable *md,
                                                         const MafwFilter *filter,
                                                         MafwMetadataComparator funcomp);

Utility function to help filtering browse results in mafw_source_browse() implementations.

Returns whether mafw metadata hash table md matches filter, a preparsed filter expression. For the purpose of evaluating the filter metadata tags (keys of md) are considered attributes. funcomp is a function used to compare metadata. If it's NULL mafw_metadata_ordered() is assumed.

The semantics of filter is complemented as follows:

  • Simple expressions referring to tags not existing in md are ignored.

  • Relations over multiple-valued tags are asserted if the relation holds for at least one value.

  • For the purpose of comparison metadata of filter are converted to the type of the value of the appropriate tag of md.

  • Filters not referring to existing keys in md are considered matching.

  • Empty metadata (md is NULL) or empty filter (filter is NULL) match with everything.

md : hash table
filter : filter
funcomp : comparison function
Returns : TRUE if match, FALSE otherwise.

mafw_metadata_first ()

GValue*             mafw_metadata_first                 (GHashTable *md,
                                                         const gchar *key);

Convenience function to obtain the first GValue of key in the mafw metadata hash table md. Returns NULL if no such key in md.

md : hash table
key : key
Returns : a GValue containing the first value with that key.

mafw_metadata_new ()

GHashTable*         mafw_metadata_new                   (void);

Creates a new mafw metadata hash table. The hash table has string keys, and either GValue or GValueArray values.

Returns : a new hash table that can be filled with metadata and with the suitable destructors for keys and values

mafw_metadata_nvalues ()

guint               mafw_metadata_nvalues               (gconstpointer value);

Use this function to determine how to handle value, which shall be obtained with an ordinary g_hash_table_lookup(). If value is NULL (lookup failed) 0 is returned. If the tag is found to have one value you may assume value is a GValue. Otherwise it needs to be treated as a GValueArray.

value : value
Returns : the number of values of a metadata tag from a mafw metadata hash table.

mafw_metadata_ordered ()

gboolean            mafw_metadata_ordered               (MafwFilterType rel,
                                                         const gchar *key,
                                                         const GValue *lhsgv,
                                                         const GValue *rhsgv);

Generic mafw_metadata_filter() comparator capable of dealing with strings and integers. It is used by default, and you are advised to call it as a fallback from your custom comparator function. Strings are compared ignoring their case. The approximate matching of strings is executed in terms of globbing. key is ignored.

rel : filter type
key : key
lhsgv : left comparison element
rhsgv : right comparison element
Returns : a positive integer if left argument is bigger than right, a negative if left is smaller than right and 0 if equal.

mafw_metadata_print ()

void                mafw_metadata_print                 (GHashTable *md,
                                                         const gchar *domain);

Dumps the contents of a mafw metadata hash table.

The format of the output looks like: """ <tab><key1>: `<value11>' <tab><key2>: `<value21>', `<value22>', `<value33>' """.

md : hash table
domain : domain. If domain is NULL entries are g_print()ed, otherwise they are g_log()ed from domain at debug level.

mafw_metadata_print_one ()

void                mafw_metadata_print_one             (const gchar *key,
                                                         gpointer val,
                                                         const gchar *domain);

Like mafw_metadata_print(), but prints only the given key-val pair, as obtained from a mafw metadata hash table.

key : key
val : value
domain : domain

mafw_metadata_release ()

void                mafw_metadata_release               (GHashTable *md);

Convenience function to release a mafw metadata hash table. Does nothing if md is NULL.

md : hash table

mafw_metadata_relevant_keys ()

const gchar**       mafw_metadata_relevant_keys         (const gchar *const *keys,
                                                         const MafwFilter *filter,
                                                         const gchar *const *sorting);

Helps deciding what metadata a MafwSource implementation will need while browsing the upstream in order to be able to observe the filter and sorting criteria of mafw_source_browse(). The strings in the array are taken directly from keys, filter and sorting without duplication, so the returned array is valid only as long as the structures are valid. Free the array with g_free().

Note

Some actions are are performed not to include duplicate tag names in the returned array, but it is not guaranteed.

keys : keys
filter : filter
sorting : sorting criteria
Returns : all metadata tags in a NULL-terminated string array being referenced either in keys, filter or sorting. Any of the parameters may be NULL. Returns NULL if no tags are referred at all.

mafw_metadata_sorting_terms ()

gchar**             mafw_metadata_sorting_terms         (const gchar *sorting);

Creates a spliced sorting term array from a mafw_source_browse() sorting criteria suitable for mafw_metadata_compare() as input.

sorting : sorting criteria
Returns : NULL if sorting is NULL or empty. Free with g_strfreev().

mafw_metadata_freeze ()

gchar*              mafw_metadata_freeze                (GHashTable *md,
                                                         gsize *sstreamp);

Like mafw_metadata_freeze_bary(), but returns a conventional C character array instead of a GByteArray.

md : hash table
sstreamp : pointer to return the stream size
Returns : the a conventional gchar*.

mafw_metadata_freeze_bary ()

GByteArray*         mafw_metadata_freeze_bary           (GHashTable *md);

Serializes a mafw metadata hash table. The returned stream is suitable for sending to another process or storing on the disk, but is not architecture-independent. md can be NULL.

  • stream := <entry> *
  • entry := <key> <nvalues> <value> 1*
  • key := <C-string>
  • nvalues := <uint32>
  • value := <GType> <data>
  • GType := <uint32>
  • data := <uint32> | <C-string>

md : hash table.
Returns : a GByteArray..

mafw_metadata_thaw ()

GHashTable*         mafw_metadata_thaw                  (const gchar *stream,
                                                         gsize sstream);

Like mafw_metadata_thaw_bary(), but the input stream is taken from a conventional C character array instead of a GByteArray.

stream : a gchar* with the stream
sstream : the stream size
Returns : a GHashTable.

mafw_metadata_thaw_bary ()

GHashTable*         mafw_metadata_thaw_bary             (GByteArray *bary);

Recreates the mafw metadata hash table from its serialized from. The serialized and deserialized hash tables contain the same information, but are not byte-equivalent. Returns NULL if bary does not contain any keys after all. If the input stream is found syntactically incorrect the program is aborted.

bary : the byte array
Returns : a GHashTable.

mafw_metadata_val_freeze ()

gchar*              mafw_metadata_val_freeze            (gpointer val,
                                                         gsize *sstreamp);

Like mafw_metadata_val_freeze_bary(), but returns a conventional C character array instead of a GByteArray.

val : a pointer
sstreamp : the pointer to store the stream size
Returns : the streams as a gchar*

mafw_metadata_val_freeze_bary ()

void                mafw_metadata_val_freeze_bary       (GByteArray *bary,
                                                         gpointer val);

Encodes a mafw metadata hash table value, handling both single- and multiple-valued tags.

bary : the GByteArray
val : the pointer

mafw_metadata_val_thaw_bary ()

gpointer            mafw_metadata_val_thaw_bary         (GByteArray *bary,
                                                         gsize *i);

Recreates the mafw metadata value, or value-array from its serialized from. If the input stream is found syntactically incorrect the program is aborted.

bary : the GByteArray
i : the pointer to store the size
Returns : the pointer