ACCESS Developer Network | Using Media Selector Data Model | Data, Model, Function, ^top^, Metadata

This chapter discusses how to use the Media Selector Data Model API.

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 Media Cataloger builds and maintains the Media Selector Data Model. The Data Model provides the mechanism through which application can access to the Cataloger's stored file metadata. The Extractors, when they extract metadata from media files, and applications, when they add (or delete) media files, use the Data Model API to load values into tables in the internal databases. Applications can then use the Data Model APIs to query the public data model for information about those files. The Media Selector GUI presents that information to users.For more information about the architecture of the Media Selector Data Model, see "The Media Selector Data Model."

The Media Selector Data Model APIs (alp_ms_dml_*) provide applications with the ability to add metadata to the Data Model, query the Data Model based on sort and search criteria, and retrieve metadata, stored in the Data Model, about media files indexed in the Media Selector catalog.

Adding Metadata to the Data Model ^TOP^

To add metadata information to the Data Model, from applications or Extractors, you must add the new metadata to an entry to store in the Data Model. To do this, use the following steps:

Open the Data Model.
Create a metadata entry.
Store the metadata values in the entry.
Commit the entry to the Data Model.
Destroy the entry to free the resource.
Close the Data Model.

The following sections describe the functions used add metadata to the Data Model:

"Manipulating the Data Model."

"Creating a Metadata Entry."

"Adding Metadata to the Data Model Entry."

Manipulating the Data Model ^TOP^

These function provide basic housekeeping facilities for the Data Model: open, close, flush.

Use the alp_ms_dml_flush to flush the transaction buffer in the unlikely event that your application tries to read back newly written data before a successful close. If you use open/write/close, then open/read/close, your application does not need to flush.

alp_ms_dml_open Function ^TOP^

Purpose

Open the MediaSelector DML for updating the data within.

Prototype

alp_status_t alp_ms_dml_open (
   AlpDmlH *dmlH
)

alp_ms_dml_close Function ^TOP^

Purpose

Close the MediaSelector DML when updating is complete.

Prototype

alp_status_t alp_ms_dml_close (
   AlpDmlH dmlH
)

alp_ms_dml_flush Function ^TOP^

Purpose

Flush the MediaSelector DML transaction buffers.

Prototype

alp_status_t alp_ms_dml_flush (
   AlpDmlH dmlH
)

Creating a Metadata Entry ^TOP^

When an application wants to add metadata to the data model, it needs to populate a metadata entry with the necessary information. Extractors use this functionality to add information to the data model based on the file types they support. Use these functions to create a metadata entry, commit it to the data model (after you've populated it (using the alp_ms_dml_item_set_* functions), and destroy the entry when finished.

These metadata types must match the defined metadata category names. See the ALP_MS_ITEM_TYPE_* constants, described in "Media Categories and Their Contents," for more information.

alp_ms_dml_item_create Function ^TOP^

Purpose

Create item metadata entry of a specified type

Prototype

alp_status_t alp_ms_dml_item_create (
   const char *item_type,
   AlpDmlItemH *itemH,
   const char *path
)

The path parameter indicates the full path to the file which has the specified metadata. Note the following conditions:

The file must already be indexed.
The path must be a 'true' path such as you get from the Linux realpath function. This function may fail if you use a symlink (such as /media) instead of a 'true' path (such as /tmp/media).

alp_ms_dml_commit_item Function ^TOP^

Purpose

Commit the filled in metadata to the database.

Prototype

alp_status_t alp_ms_dml_commit_item (
   AlpDmlH dmlH,
   AlpDmlItemH itemH
)

alp_ms_dml_item_destroy Function ^TOP^

Purpose

Clean up after finished with an item.

Prototype

alp_status_t alp_ms_dml_item_destroy (
   AlpDmlItemH itemH
)

Adding Metadata to the Data Model Entry ^TOP^

After creating a metadata entry (with alp_ms_dml_item_create), use these functions to set metadata values, based on data type, in the entry.

For the integer versions of these functions, the value parameter is of type *int, (or *int64_t), not simple int. Passing a NULL value sets the database field to NULL.

For the string version, as with the integer functions, NULL is a valid value, and stores a SQL null in the database table.

alp_ms_dml_item_set_int32 Function ^TOP^

Purpose

Sets integer value metadata.

Prototype

alp_status_t alp_ms_dml_item_set_int32 (
   AlpDmlItemH itemH,
   const char *dml_column,
   int32_t *value
)

alp_ms_dml_item_set_int64 Function ^TOP^

Purpose

Sets integer value metadata.

Prototype

alp_status_t alp_ms_dml_item_set_int64 (
   AlpDmlItemH itemH,
   const char *dml_column,
   int64_t *value
)

alp_ms_dml_item_set_string Function ^TOP^

Purpose

Sets string value metadata.

Prototype

alp_status_t alp_ms_dml_item_set_string (
   AlpDmlItemH itemH,
   const char *dml_column,
   const char *value
)

Querying the Data Model ^TOP^

The alp_ms_dml_statement_* APIs provide functionality to query and retrieve information from the data model. An application creates data model query statements, then executes the statements to find metadata entries based on the criteria set up in the search query. The alp_ms_dml_statement_parameters_* functions set the values for sort category, field matching, and sort order to define the query criteria. The alp_ms_dml_statement_get_* functions retrieve the metadata values and column information from the model.

The following sections describe the functions used create and execute a search query on the Data Model and retrieve metadata from returned query result:

Setting Up Data Model Queries ^TOP^

To set up a query, use the following functions to set values for the fields in your alp_ms_dml_statement_parameters structure.

See "The Media Selector Data Model Query" for more information about these fields and their values.

These parameters define the conditions for your search.

typedef struct 
{ 
	const char *category; 
	const char *fields; 
	const char *filter; 
	const char *matchField; 
	const char *match; 
	const char *regexField; 
	const char *regex; 
	const char *includedCategories; 
	const char *excludedCategories; 
	const char *sortby; 
	bool ascending; 
	int start; 
	int limit; 
} alp_ms_dml_statement_parameters;

alp_ms_dml_statement_parameters_clear Function ^TOP^

Purpose

Initialize parameters block - set all fields to default values (binary zero).

Prototype

alp_status_t alp_ms_dml_statement_parameters_clear (
   alp_ms_dml_statement_parameters *parameters
)

alp_ms_dml_statement_build_single_file_filter Function ^TOP^

Purpose

Generate a filter to select a single file. (Looks up file_id and dir_id.)

Prototype

alp_status_talp_ms_dml_statement_build_single_file_filter(
   const char* filename,
   char** filter
);

Given the filename that you want to retrieve metadata for, this function creates a filter in the form of a string. The caller owns the returned string, and must call g_free when done with the string

alp_ms_dml_statement_parameters_set_fields Function ^TOP^

Purpose

Set both category and fields.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_fields (
   alp_ms_dml_statement_parameters *parameters,
   const char *category,
   const char *fields
)

alp_ms_dml_statement_parameters_set_match Function ^TOP^

Purpose

Set both match and matchField.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_match (
   alp_ms_dml_statement_parameters *parameters,
   const char *matchField,
   const char *match
)

alp_ms_dml_statement_parameters_set_regex Function ^TOP^

Purpose

Set both regex and regexField - slow but powerful matching.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_regex (
   alp_ms_dml_statement_parameters *parameters,
   const char *regexField,
   const char *regex
)

alp_ms_dml_statement_parameters_set_skip Function ^TOP^

Purpose

Set start/limit - restrict results to a 'window'.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_skip (
   alp_ms_dml_statement_parameters *parameters,
   int start,
   int limit
)

alp_ms_dml_statement_parameters_set_select_by_category Function ^TOP^

Purpose

Set both includedCategories and excludedCategories.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_select_by_category(
   alp_ms_dml_statement_parameters* parameters,
   const char *includedCategories,
   const char *excludedCategories
);

The values for includedCategories and excludedCategories are defined in comma-separated list of categories. This function provides a way to narrow the range of categories that a file is in. For example, including "audio" while excluding "voice,ringtones" gives you all audio files that are neither voice or ringtone files.

alp_ms_dml_statement_parameters_set_sort Function ^TOP^

Purpose

Set sort info.

Prototype

alp_status_t alp_ms_dml_statement_parameters_set_sort (
   alp_ms_dml_statement_parameters *parameters,
   const char *sortby,
   bool ascending
)

Creating and Executing Data Model Queries ^TOP^

These functions control the creation and execution of DML query statements.

For functions that provide query statement string, the caller owns the returned string, and must call g_free() when completely done with the string. The caller is not done with the string until it passes the parameter block to the alp_ms_dml_statement_begin function. (This is broadly true of all strings in the parameter block: The block-setting functions do not make copies, and the strings must 'live" until alp_ms_dml_statement_begin function uses them to create the query statement.) The alp_ms_dml_statement_begin creates a statement but does not actually apply it.

alp_ms_dml_statement_begin Function ^TOP^

Purpose

Begin dml statement using the given criteria.

Prototype

alp_status_t alp_ms_dml_statement_begin (
   AlpDmlH dmlH,
   AlpDmlStatementH *stmtH,
   alp_ms_dml_statement_parameters *params,
   int *numResults
)

alp_ms_dml_statement_end Function ^TOP^

Purpose

Close statement handle.

Prototype

alp_status_t alp_ms_dml_statement_end (
   AlpDmlStatementH stmtH
)

alp_ms_dml_statement_exec Function ^TOP^

Purpose

Run dml statement using the given criteria, and call callback method once per row.

Prototype

alp_status_t alp_ms_dml_statement_exec (
   AlpDmlH dmlH,
   AlpMsCallbackFunction callback,
   void *data,
   alp_ms_dml_statement_parameters *params,
   int *numResults
)

The callback or numResults values can be NULL.

alp_ms_dml_statement_next Function ^TOP^

Purpose

Advance to the next statement.

Prototype

alp_status_t alp_ms_dml_statement_next (
   AlpDmlStatementH stmtH
)

For this function, ALP_STATUS_OK means that there is data to be read. Use the alp_ms_dml_statement_get_* functions to do this.

Retrieving Metadata from the Data Model ^TOP^

Getting Values from the Data Model

Use these functions to retrieve metadata, based on data type, from the Data Model, given the name of the column.

alp_ms_dml_statement_get_int32 Function ^TOP^

Purpose

Get an int32_t from column by name.

Prototype

alp_status_t alp_ms_dml_statement_get_int32 (
   AlpDmlStatementH stmtH,
   const char *dml_column,
   int32_t *value
)

alp_ms_dml_statement_get_int64 Function ^TOP^

Purpose

Get an int64_t from column by name.

Prototype

alp_status_t alp_ms_dml_statement_get_int64 (
   AlpDmlStatementH stmtH,
   const char *dml_column,
   int64_t *value
)

alp_ms_dml_statement_get_string Function ^TOP^

Purpose

Get a string from column by name. Caller does NOT own string, and should not free it!

Prototype

alp_status_t alp_ms_dml_statement_get_string (
   AlpDmlStatementH stmtH,
   const char *dml_column,
   const char **value
)

Listing the Available Columns

In most cases you know what column names are available to your applications. If not, alp_ms_dml_statement_get_columns retrieves this information. This function is most useful to developers writing tools or frameworks.

alp_ms_dml_statement_get_columns Function ^TOP^

Purpose

Get the list of column names - useful when fields=="*".

Prototype

alp_status_t alp_ms_dml_statement_get_columns (
   AlpDmlStatementH stmtH,
   int *columnCount,
   gchar ***columnNames
)

Getting the Current Row Location

alp_ms_dml_statement_get_file_url Function ^TOP^

Purpose

Get a file URL for current row. This may be used in conjunction with alp_mf_get_url_path() to get a path to the file. Caller owns the returned string, and must free it with g_free!

Prototype

alp_status_t alp_ms_dml_statement_get_file_url (
   AlpDmlStatementH stmtH,
   const char **url
)