mmmd_get()

Get metadata fields from a media item

Synopsis:

#include <mm/md.h>
int mmmd_get( mmmd_hdl_t *hdl, 
              const char *item, 
              const char *types, 
              const char *source, 
              uint32_t count, 
              char **md )

Arguments:

hdl
The handle of the session associated with the mediastore from which metadata is being read.
item
A URL or an absolute path to the file containing the metadata being read. For URLs, the prefix depends on the type of file being read (see "Supported file types" for details).
types
A string storing the requested metadata types (fields) as a series of group-attributes listings. Here, group refers to the metadata category (e.g., title) while attributes refers to the list of requested attributes (e.g., artist, album).
Each group-attributes listing must be followed by a line-break character (\n). Within a listing, the group and the attributes must be separated by the :: delimiter, while individual attributes must be separated by commas, as shown in this example with two listings:
md_title::name,artist,album\nmd_video::width,height
This syntactic grouping of metadata types makes it easy to request multiple related fields.
source
A string specifying the metadata source (i.e., the MDP to use). Currently, this feature isn't supported so this argument must be NULL to indicate that all sources can be used.
count
The number of desired matches (i.e., responses from MDPs).
If count is 0, all responses are collated to return the highest-rated response (see the Description for an explanation).
If count is nonzero, the number of responses returned is less than or equal to count, starting with the highest-rated response. No collation is performed.
md
A pointer to a string reference to the buffer storing the response. The library allocates the buffer memory, writes the metadata in this memory, and sets the string reference but the caller owns the memory and hence, is reponsible for freeing it later.
Examples of the formatting and typical contents of the response buffer are given in the Description.

Library:

libmd

Description:

This function gets the specified metadata fields from the specified item. The types string must state the requested fields as group-attributes listings, as explained in the Arguments.

Because different MDPs support different fields, libmd uses as many MDPs as necessary to extract metadata for all the fields listed in types. The order that libmd uses to invoke the MDPs is the plugin preference order for the file type indicated by the URL or path in item. This file type-based preference order is stated in the configuration file.

For the lists of fields supported by different MDPs, see "Included MDPs".

The metadata pointer (md) should be deallocated using free() when the metadata is no longer needed. The libmd library sets this pointer to a valid, non-null value only if the return value is greater than 0, meaning metadata was found.

Examples:

Retrieving multiple responses

Setting count to a value greater than 0 allows you to retrieve multiple matches (responses) for metadata fields. Your client code can then choose the set of responses that provides the user with the most accurate and complete metadata possible. The number of responses returned is less than count if the number of MDPs supporting any of the requested fields is also less than count. A nonzero value for this argument simply limits the number of responses that can be returned.

Suppose a client sets count to 3 and requests the md_title_artist and md_title_orientation fields from a POSIX file while the MDP preference order for POSIX files is mmf, mediafs, exif. The MMF and MediaFS MDPs support the first field but not the second; the Exif MDP supports the second field but not the first. The libmd library then stores a pointer in md that references the following string:

md_src_name::mmf\nmd_src_rating::0\nmd_title_artist::some_artist\n
md_src_name::mediafs\nmd_src_rating::1\nmd_title_artist::some_artist\n
md_src_name::exif\nmd_src_rating::2\nmd_title_orientation::landscape\0

The name and rating of the MDP that produced the metadata are placed in front of every metadata field. Ratings are offsets in the zero-based list of preferred MDPs, so 0 indicates the first plugin listed, 1 indicates the second listed, and so on. The metadata is represented as a name-value pair and placed after the MDP name and rating.

Retrieving the highest-rated responses

Setting count to 0 makes libmd collate the responses from many MDPs into one result set to produce the highest-rated response, which is the set of metadata field values obtained from the MDPs listed earliest in the plugin preference order.

Suppose a client sets count to 0 and requests the md_title_width, md_title_height, and md_title_orientation fields from a POSIX file while the MDP preference order is the same as listed in the last example. The MMF and MediaFS MDPs support the first two fields but not the last; only the Exif MDP supports the last field. The libmd library then sets md to reference the following string:

md_title_width::response_from_MMF\nmd_title_height::response_from_MMF\n
md_title_orientation::response_from_Exif

Because MMF is rated ahead of MediaFS, this first MDP's values for md_title_width and md_title_height are returned. Neither MMF nor MediaFS supports md_title_orientation, so the value from Exif for this last field is returned. Note that the MDP names and ratings aren't shown for individual fields in this case because the responses come from potentially many MDPs.

Returns:

>0
The number of responses, when successful.
0
No metadata was retrieved but no errors occurred.
-1
An error occurred (call mmmd_error_info() for details).