ACCESS Developer Network | Using Media Files | File, Mime, Function, Char, Media

This chapter discusses how to use the MediaFiles API to gather information associated with media files.

NOTE: See the related reference material for the API in the "Content Management" Module and the /usr/include/alp/mediaselector_api.h File Reference. The online reference guide has the most current information about the API.

Overview ^TOP^

The purpose of this group of functions is to alleviate the problems associated with storage and retrieval of media from a device.

Because any application has access to global settings, and new mime types can be registered when a new extractor is installed, this scheme may be extended to new types of media.

These functions address the following concerns:

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

Working with the MediaFiles API ^TOP^

The MediaFiles APIs support two general areas of functionality:

Finding File Types and Locations ^TOP^

The MediaFiles APIs provide several different approaches to finding locations and files, based on what information is available about the file. The ACCESS Linux Platform has standard locations for various types of files, and conventions for storage locations for files on the device and on external storage cards. These APIs help your applications store and retrieve files in the standard locations and gather information about those files.

Finding File Locations for Well-behaved Applications

When you develop a "well-behaved" application, that is, one which follows the system's suggestions for file location and behavior, you can use this API to retrieve the appropriate location to store your media file:

alp_mf_get_media_path Function ^TOP^

Purpose

Given a file name and a volume ID, return a path to the directory where the file should live.

Prototype

alp_status_t alp_mf_get_media_path (
   const char *udi,
   const char *filename,
   char **outpath
)

The API uses the following to determine the full directory path of the location where the file should be saved:

The volume identifier (uid) of the volume to save the file to. This value is specified in the AlpVolumeSvcsFSinfo.udi field available from Volume Services.
The filename, or even just the extension, of the file to be saved.

NOTE: You must call g_free() on the location path when done to free the resource.

After calling this function and saving the new file to the directory, you should update the catalog to make the file visible. You should call the alp_ms_cat_update function, or for a single file, the more efficient alp_ms_cat_index_file function.

This component uses the AlpFileMime facilities to interface to the Cataloger's mime database to determine the mimetype of the file from the name. It then uses the AlpGlobalSettings API to retrieve the associated path based on the volume type information.

The paths are stored as values in the form: relative/path/from/mountpoint/

The keys are in the format: card_type/mime_supertype

For example:

In addition, Cataloger takes the following actions:

Unrecognized mimetypes are mapped to generic.
Unrecognized card types are mapped to generic.
The local device is of type device.

Mime subtypes are not currently considered.

An example using alp_mf_get_media_path follows:

#!cpp 
int 
AppClass::SaveMedia(const AlpVolumeSvcsFSinfo& _info, const 
string& _file) 
{ 
    char* dir; 
    alp_status_t result = alp_mf_get_media_path(_info.udi, 
_file.c_str(), &dir); 
    if( ALP_STATUS_OK == result ) 
    { 
        string fullpath(dir); 
        fullpath += _file; 
 
// save that file! 
        ... 
 
        g_free(dir); 
    } 
    else 
    { 
        // something is wrong! 
    { 
 
    return result; 
}

Loading Icons and Thumbnails

These APIs provide applications with the ability to retrieve paths for icons, previews, and thumbnails for media files.

These functions return ALP_STATUS_OK on success.

NOTE: For these functions, you must call g_free() on the location path when done to free the resource.

alp_mf_get_file_icon_path Function ^TOP^

Purpose

Provides a path to load an icon from a specific file.

Prototype

alp_status_t alp_mf_get_file_icon_path (
   const char *path,
   char **pathout
)

alp_mf_get_mime_icon_path Function ^TOP^

Purpose

Provides a path to load an icon from a specific mime type.

Prototype

alp_status_t alp_mf_get_mime_icon_path (
   const char *mime,
   char **pathout
)

alp_mf_get_file_thumbnail_path_extended Function ^TOP^

Purpose

Provides a path to load a thumbnail for a new or existing (such as a cached thumbnail) file.

Prototype

alp_status_t alp_mf_get_file_thumbnail_path_extended (
   const char *path,
   const char *notification,
   char **pathout,
   int *token
)

If you use this function with a new file, one that has to be generated asynchronously. alp_mf_get_file_thumbnail_path_extended returns ALP_STATUS_MF_PENDING and broadcasts a notification from ALP_MF_THUMBNAILER_PSEUDOAPP when the file is ready. The notification parameter allows the application to specify what the function broadcasts when complete. The notification contains a sizeof(int)-sized token which matches the token returned when you called this function. The function passes the token, as an out parameter, to the calling application.

Locating Real and Virtual Paths

These functions allow applications to work with the results of the Media Selector return values. Use them to translate those selections to real paths and translate real paths to virtual ones that work the next time off-device files (on card) are available. (A virtual path is described by a mountpoint neutral location identifier (URL) For example, between card insertions, the actual path to a particular file might be different because cards get different mount point names. The URL keeps a persistent record of the file's location.

The Cataloger retrieves the volume identifiers, associated with a specific udi, from the AlpVolumeSvcsFSinfo.udi field available from volume services. NULL is used to indicate the device local file system.

The char** parameters are out parameters. The function does not read these values; it overwrites them to pass values to the calling application.

NOTE: You must call g_free() on the location path when done to free the resource.

alp_mf_get_file_url Function ^TOP^

Purpose

Given a path to a valid media file, get a mountpoint neutral location identifier (URL).

Prototype

alp_status_t alp_mf_get_file_url (
   const char *full_path,
   char **urlout
)

alp_mf_get_path_udi Function ^TOP^

Purpose

Given a path to a valid media file, get its volume identifiers.

Prototype

alp_status_t alp_mf_get_path_udi (
   const char *path,
   char **udi
)

alp_mf_get_url_path Function ^TOP^

Purpose

Given a valid media file's mountpoint neutral location identifier (URL), get a full path.

Prototype

alp_status_t alp_mf_get_url_path (
   const char *url,
   char **pathout
)

alp_mf_get_url_udi Function ^TOP^

Purpose

Given a valid media file's mountpoint neutral location identifier (URL), get its volume identifiers.

Prototype

alp_status_t alp_mf_get_url_udi (
   const char *url,
   char **udi
)

Identifying Media Selector File Types

Use alp_mf_get_media_file_type_id to retrieve the Media Selector file_type_id, to use when interacting with Media Selector queries.

alp_mf_get_media_file_type_id Function ^TOP^

Purpose

Given a path to a file, get the MediaSelector file type id for that file.

Prototype

alp_status_t alp_mf_get_media_file_type_id (
   const char *desc,
   int32_t *ftid
)

Retrieving a File's Mime String

Use the alp_mf_get_mime_for_file function to retrieve a complete mime string for a specified file. This is a shortcut for the functions alp_mf_mime_init, alp_mf_mime_get_mine_string, and alp_mf_mime_fini. It return information in the mime object, described in "Identifying Mime Types for Media Files." This function is useful when other services, such as Exchange Manager or Email applications, want to check and use a mimetype for a file.

This function recognizes preferred MIME types. See "Using Multiple MIME Types" for more information.

alp_mf_get_mime_for_file Function ^TOP^

Purpose

A convenience shortcut for getting a simple complete mime string for a file.

Prototype

alp_status_t alp_mf_get_mime_for_file (
   const char *file,
   char **outmime
)

Identifying Mime Types for Media Files ^TOP^

The alp_mf_file_mime_* API is an object-oriented API, centered on the AlpFileMime object. Applications can use these functions to get information about files. Use these APIs to create and set the mime object. (They cannot change anything related to the file or its mimetype.)

Using Multiple MIME Types

A single file extension can have multiple MIME types associated with it. Functions that retrieve MIME types (alp_mf_get_mime_for_file, alp_mf_mime_get_mime_string, alp_mf_mime_get_subtype, and alp_mf_mime_get_supertype) take the following actions:

If one of these mappings is marked as "preferred" in the manifest, the function returns the preferred MIME type.
If multiple mappings are marked as "preferred", the function chooses the newest preferred mapping.
If there are no preferred mappings, the function chooses the newest un-preferred ("extra") mapping.

See "Preferred MIME Mapping" for instructions on how to add preferred mapping to the manifest.

Creating and Destroying the AlpFileMime Object

Use the following functions to create and destroy a file mime object.The purpose of creating the mime object is to pass it to one of the alp_mf_mime_get_* functions to use with mime extraction. You must free it (with alp_mf_mime_fini) when you're done with it.

alp_mf_mime_init Function ^TOP^

Purpose

Create a media file mime object.

Prototype

alp_status_t alp_mf_mime_init (
   const char *file,
   AlpFileMime *handle
)

alp_mf_mime_fini Function ^TOP^

Purpose

Destroy a file mime object when finished with it.

Prototype

alp_status_t alp_mf_mime_fini (
   AlpFileMime handle
)

Extracting the Contents of the Mime String

Use the following functions to extract the contents of a file mime object.

These functions recognize preferred MIME types. See "Using Multiple MIME Types" for more information.

alp_mf_mime_get_mime_string Function ^TOP^

Purpose

Extract the complete mime string.

Prototype

char * alp_mf_mime_get_mime_string (
   AlpFileMime handle
)

alp_mf_mime_get_subtype Function ^TOP^

Purpose

Extract just the subtype of the file mime.

Prototype

char * alp_mf_mime_get_subtype (
   AlpFileMime handle
)

alp_mf_mime_get_supertype Function ^TOP^

Purpose

Extract just the supertype of the file mime.

Prototype

char * alp_mf_mime_get_supertype (
   AlpFileMime handle
)

Setting a File MIME

Use the alp_mf_mime_set_to function to set an initialized file mime object to refer to the mimetype of a different file. This operation is faster than creating a new mime object.

alp_mf_mime_set_to Function ^TOP^

Purpose

Set the file mime to a different file. This is faster than creating a new one.

Prototype

alp_status_t alp_mf_mime_set_to (
   AlpFileMime handle,
   const char *file
)

Determining If a Mime Type Is Supported

Use the alp_mf_mime_is_supported function to determine if the Cataloger supports this mimetype. It returns the following values:

true, if the file is supported.
false, if the file is not supported.

alp_mf_mime_is_supported Function ^TOP^

Purpose

Determine if the file is supported by the mime database.

Prototype

bool alp_mf_mime_is_supported (
   AlpFileMime handle
)