This chapter describes the basic concepts and components of the Media Selector Service. It is an overview of the available services; the following chapters describe its processes, application programming interfaces, and uses in applications in greater detail.

Overview ^TOP^

The Media Selector Service enables application to sort, filter, and select files stored on the device. Media Selector provides the underlying mechanism to catalog and index files with information about their type and properties. Applications that manipulate files call the Media Selector UI to present users available content to select, such as pictures, music, ring tones, and other documents from both internal (device) and external (cards) storage.

Unlike traditional linux hierarchical directory searching, Media Selector allows users to browse all physically available media on their device, expansion cards, or mounted volumes using powerful queries. This releases the users from location-dependent searching by device. It lets them find information based on the properties of a file, for example, "Show me all media, sorted by size" or "Show me all audio files in the 'rock' genre." An application calls Media Selector to present users with the results of their search. From the list presented, the Media Selector lets users select files, then passes that information back to the application (the caller) that manipulates those files, for example, browsers, media players, and media capture applications.

The Media Selector provides applications with the ability to query device and external storage for files. You can customize the Media Selector widget and dialog via parameters, rather than editing a template in Glade, to add functionality. An application can call Media Selector as a dialog within that application, and using parameters, add an additional button. With this button, the user can launch a given plug-in that provides its own UI and handles its own communication. Through it, the application locates the appropriate storage location, stores the file, and returns the reference. The users can navigate and select a existing piece of media based on filtered and sorted lists presented by the interface. The application which calls Media Selector uses the Media Selector libraries to turn that reference into a filename. From the file and its metadata, the application determines how to process the file.

Architecture and Components ^TOP^

Media Selector is a collection of processes and APIs which manage search and location of files based on properties of those files. It maintains a set of databases to catalog information about files and provides applications that manipulate files an interface to that information. The databases that Media Selector uses are referred to as meta databases because they are used to store metadata and location information about files.

Media Selector interacts with other frameworks to simplify the search for files and their locations. For example, applications developers can use Media Selector in combination with multimedia applications using the Multimedia Framework. Media Selector can provide location information to store or retrieve multimedia files. It uses information maintained by the Hiker Application Framework Volume Services to find mount-point independent and physical file locations. It uses the Hiker SAL APIs to manage the metadata databases that it uses to catalog and search the available files. It assesses the ACCESS Linux Platform Global Settings.

Media Selector consists of the following major components:

• Cataloger
• Graphical User Interface
• Extractor plug-in libraries

Figure 3.1  

The Media Selector Service supports a set of APIs to enable applications to provide easy access to files. Figure 3.1 shows an overview of the services available. These APIs let applications access information stored in the meta databases, get media selections from the users, manipulate the cataloger, and provide file location and type information:

• Cataloger
• Media Selector Data Model (DML)
• Media Files library
• Media Selector GUI widgets
• Media Selector Error Messages.
• alp_catalog (msutil) tool
• Extractor interface

The following sections briefly describe these components.

Cataloger ^TOP^

To facilitate fast queries across all available volumes, the Media Selector relies on a background process to gather metadata from media files and store it in its databases.

This process, the Cataloger, maintains the set of meta databases. The system automatically launches the cataloger at boot time or system reset. It includes the mediacatd daemon and a set of APIs to allow applications to interact with files, the meta databases, and the cataloger itself.

• The cataloger daemon (mediacatd) and its APIs
• The data access library, used to interact with the user-accessible data model (mediaselector_dml).
• The media files library (mediafile).

The Media Selector Service includes a command-line utility, alp_catalog (in previous releases, msutil), as a debugging tool. This command provides direct interaction with the components of the Media Selector Service, useful while developing an application.

See Chapter 5, "Introducing Media Cataloger," for more information about architecture and design of the cataloger.

Cataloger API

Applications can use the functions in the Cataloger API to interact with the catalog, including the following actions:

• Register and unregister a directory.
• Index or unindex a single file.
• Process and update the catalog.
• Copy a file and its extracted metadata, without re-extracting that metadata.
• Check whether an extractor exists to support a specified file type.

See Chapter 6, "Using Media Cataloger," for more information about using the cataloger API.

Media Selector Data Model (DML) API

Applications can use the functions in the Media Selector Data Model API to create, maintain, and query the metadata in the data model, including the following actions:

• Create queries to retrieve information about files based on properties.
• Write information about file metadata to the databases. Extractors use these functions to discover the meta data and add it to the database.

See Chapter 7, "Using Media Selector Data Model," for more information about the data model and it access interfaces.

Media Files Library

Applications can use the functions in the Media Files Library when they store or retrieve media from a device.

Applications can use these functions for the following actions:

• Where should an application store new media?
• On what type of volume is a particular piece of media located?
• How does an application store references to media between reboots/card insertions/removals?
• How does an application get thumbnails/previews for media files?

See Chapter 8, "Using Media Files," for more information about using the Media File Library.

alp_catalog tool

The Media Selector utility, alp_ catalog (in previous releases, msutil), is a command line program which allows you to interrogate and modify the Media Selector subsystem. This tool helps you debug as you develop applications that use the Media Selector Service. You can use this command to directly examine the contents of the meta databases and verify the available extractor plug-ins.

See Chapter 5, "Introducing Media Cataloger," for more information about the alp_catalog tool.

Media Selector Error Messages ^TOP^

Media Selector errors have ALP_CLASS_MEDIASELECTOR in the first byte, and a category code in the second byte; the low word is the actual error code. To use the error string library for ALP_CLASS_MEDIASELECTOR: include the error message file:

#include <alp/errormgr_base.h> 

Use the alp_err_string_exists and alp_err_get_string functions to get human-readable strings for these errors.

Media Selector Graphical User Interface ^TOP^

The Media Selector Service has a separate API available so applications can create a GTK widget (mediaselector) or dialog (mediaselectordlg). These elements present users the results of file queries and retrieve users' file selections.

See Chapter 4, "Using Media Selector User Interface," for more information about the Media Selector user interface.

Extractor Plug-ins Libraries ^TOP^

Extractors are libraries (ALP bundles) that register with the Cataloger to extract metadata from a defined type of media file. These plug-ins do the work of populating the meta databases with the appropriate information for the file type.

If you provide a new file type for an application—a browser, a viewer, a player—you must create and register an extractor to support your file type. Extractors can also allow you to assign an file type with an extension, but no additional metadata, to an existing type.

The ACCESS Linux Platform system ships standard extractors which read metadata from common file types.

See Chapter 9, "Using Extractor Plug-Ins," for more information about the extractors and how to create one for your file type.

Searching with Media Selector ^TOP^

Media Selector's primary use is to simplify the users' search for files. It accomplishes this by sorting and filtering available files based on their properties, rather than physical location on the device or storage card. To provide this information to the interface, it implements filters and sorts to construct queries that interrogate the meta databases it builds. Using the information about the location of the file stored with its metadata, Media Selector display file selections to the users and can pass the selection back to the calling application.

Media Selector organizes and presents the file information based on the following criteria:

• Category selection (All, Audio,....)
• Filter (All, Games, Utilities, Favorites,....)
• Sort by (Data Size, File Name, File Type,....)
• Sort order (ascending or descending)

Media Selector creates an SQL-like query that resembles the following general form:

SELECT <result> FROM <tablelist> WHERE <cat_selection> and 
<filter_selection> and ORDER BY <sortby>; 

See Chapter 5, "Introducing Media Cataloger," for information about how Media Selector builds the queries for the data model.

Media Selector uses the following definitions with the Cataloger and the MediaSelector widgets. With the Cataloger, if provides access to the Media Selector Data Model. For the widgets, it defines the properties used to sort and organize information about media files.

The basic properties used by the Media Selector widgets to define the search include the following:

• ALP_MS_PROP_CATEGORY

  Media Selector provides a set of common categories, represented internally as individual SQL tables, including audio, document, image, ringtone, video, and voice.

  • ALP_MS_CATEGORY_ALL—evaluate all categories and "other".
  • ALP_MS_CATEGORY_APPLICATION—application.
  • ALP_MS_CATEGORY_AUDIO—audio.
  • ALP_MS_CATEGORY_COLLECTION—applications can implement collections as a special category.
  • ALP_MS_CATEGORY_IMAGE —image.
  • ALP_MS_CATEGORY_OTHER —"other" - all files not handled by the system.
  • ALP_MS_CATEGORY_RINGTONE—ringtone.
  • ALP_MS_CATEGORY_VIDEO—video.
  • ALP_MS_CATEGORY_VOICE—voice.
• ALP_MS_PROP_FILTER

  Media Selector uses categories and fields in the meta database to create filters to limit and organize selections.

• ALP_MS_PROP_MATCH

  Media Selector uses field and value comparisons to information in the meta database to specify and limit selections.

• ALP_MS_PROP_SORTBY

  Media Selector provides standard values to determine what to sort by, including the following.

  • ALP_MS_SORTBY_LOCATION—file location.
  • ALP_MS_SORTBY_NAME—file name.
  • ALP_MS_SORTBY_SIZE—file size.
  • ALP_MS_SORTBY_TIME—last modification time for the file.
  • ALP_MS_SORTBY_TYPE—file type.
• ALP_MS_PROP_SORT_ASCENDING

  Media Selector supports two standard sort orders:

  • ALP_MS_SORT_DESCENDING —reverse sort, high to low.
  • ALP_MS_SORT_ASCENDING—normal sort, low to high.
• ALP_MS_PROP_VIEW_MODE

  Media Selector displays the available file information in one of the following view modes:

  • ALP_MS_SINGLE_VIEW—one line per file entry.
  • ALP_MS_MULTI_VIEW—two lines per file entry.
  • ALP_MS_GALLERY_VIEW—a gallery (icon grid) view.