sbIMediaLibrary Interface Reference

The media library object constructs SQL queries designed to reference the library of a database. More...

import "sbIMediaLibrary.idl";

List of all members.

Public Member Functions

void setQueryObject (in sbIDatabaseQuery queryObj)
 Set the database query object that the library will use to make queries to the database.
sbIDatabaseQuery getQueryObject ()
 Get the database query object that is being used by the library to make database queries.
void createDefaultLibrary ()
 Create the library table with default metadata columns.
AString addMedia (in AString mediaURL, in PRUint32 metaColumnCount,[array, size_is(metaColumnCount)] in wstring metaColumnNames, in PRUint32 metaValueCount,[array, size_is(metaValueCount)] in wstring metaValues, in PRBool checkForUniqueFilename, in PRBool willRunQueryLater)
 Add a new piece of media to the library.
PRBool removeMediaByURL (in AString mediaURL, in PRBool willRunQueryLater)
 Remove a track from the library.
PRBool removeMediaByGUID (in AString mediaGUID, in PRBool willRunQueryLater)
 Remove a track from the library.
PRBool purgeDefaultLibrary (in PRBool willRunQueryLater)
 Remove all tracks from the library.
AString findByGUID (in AString mediaGUID)
 Get a track's URL from its GUID.
AString findByURL (in AString mediaURL)
 Get a track's GUID from its URL.
void addColumn (in AString columnName, in AString columnType)
 Add a column to the library table.
void deleteColumn (in AString columnName)
 Remove a column from the library table.
void getColumnInfo ()
 Load the column info for the table into the resultset.
void setColumnInfo (in AString columnName, in AString columnReadableName, in PRBool isColumnEverVisible, in PRBool isColumnVisibleByDefault, in PRBool isMetadataColumn, in PRInt32 columnSortWeight, in PRInt32 columnDefaultUIWidth, in AString columnDataType, in PRBool isColumnReadOnly, in PRBool willRunQueryLater)
 Update the Column Info table with new data.
void getUniqueValuesByColumn (in AString columnName, out PRUint32 columnUniqueValCount,[array, size_is(columnUniqueValCount), retval] out wstring columnUniqueValues)
 Get the array of metadata column names in the Column Info tableGet the Unique list of values across the library for the column.
PRBool setValueByIndex (in PRInt32 mediaIndex, in AString columnName, in AString columnValue, in PRBool willRunQueryLater)
 Set cell a value into the library table.
PRBool setValuesByIndex (in PRInt32 mediaIndex, in PRUint32 metaColumnCount,[array, size_is(metaColumnCount)] in wstring metaColumnNames, in PRUint32 metaValueCount,[array, size_is(metaValueCount)] in wstring metaValues, in PRBool willRunQueryLater)
 Set multiple values into a single database row.
AString getValueByIndex (in PRInt32 mediaIndex, in AString columnName)
 Get cell a value from the library table.
void getValuesByIndex (in PRInt32 mediaIndex, in PRUint32 metaColumnCount,[array, size_is(metaColumnCount)] in wstring metaColumnNames, out PRUint32 metaValueCount,[array, size_is(metaValueCount), retval] out wstring metaValues)
 Get multiple values from a single database row.
PRBool setValueByGUID (in AString mediaGUID, in AString columnName, in AString columnValue, in PRBool willRunQueryLater)
 Set cell a value into the library table.
PRBool setValuesByGUID (in AString mediaGUID, in PRUint32 metaColumnCount,[array, size_is(metaColumnCount)] in wstring metaColumnNames, in PRUint32 metaValueCount,[array, size_is(metaValueCount)] in wstring metaValues, in PRBool willRunQueryLater)
 Set multiple values into a single database row.
AString getValueByGUID (in AString mediaGUID, in AString columnName)
 Get cell a value from the library table.
void getValuesByGUID (in AString mediaGUID, in PRUint32 metaColumnCount,[array, size_is(metaColumnCount)] in wstring metaColumnNames, out PRUint32 metaValueCount,[array, size_is(metaValueCount), retval] out wstring metaValues)
 Get multiple values from a single database row.


Detailed Description

The media library object constructs SQL queries designed to reference the library of a database.

The media library is a "database-helper" object. Its purpose is to translate common library-centric activities into the SQL queries required to make it happen.

See also:
sbIDatabaseQuery, DatabaseQuery.h, sbIPlaylist, sbIPlaylistManager

Definition at line 57 of file sbIMediaLibrary.idl.


Member Function Documentation

void sbIMediaLibrary::addColumn ( in AString  columnName,
in AString  columnType 
)

Add a column to the library table.

Parameters:
columnName The name of the new column (not human readable -- internal name)
columnType The type of the new column
See also:
deleteColumn, getColumnInfo, setColumnInfo, getMetadataColumns

AString sbIMediaLibrary::addMedia ( in AString  mediaURL,
in PRUint32  metaColumnCount,
[array, size_is(metaColumnCount)] in wstring  metaColumnNames,
in PRUint32  metaValueCount,
[array, size_is(metaValueCount)] in wstring  metaValues,
in PRBool  checkForUniqueFilename,
in PRBool  willRunQueryLater 
)

Add a new piece of media to the library.

This method constructs the SQL query required to insert a new track into the library. If the checkForUniqueFilename parameter is true, the code will first see if the mediaURL exists and, if so, update that track with the given metadata information and return that GUID rather than create a new row in the database.

Metadata is passed along with the track to fill columns in the database based upon a pair of string arrays. The metaColumnNames and metaValues should have an equal number of members - each index corresponds to each column-value pair set into the database.

Parameters:
mediaURL The URL to the media to add
metaColumnCount The number of items in the metaColumnNames parameter
metaColumnNames An array of strings identifying columns to be fill with metadata (matching the metaValues array)
metaValueCount The number of items in the metaValues parameter
metaValues An array of strings identifying metadata values to be inserted (matching the metaColumnNames array)
checkForUniqueFilename If true, see if the file already exists. If so, return the GUID found.
willRunQueryLater If false, execute the query before returning
Returns:
The GUID for the track added (or found)
See also:
removeMediaByURL, removeMediaByGUID, findByGUID, findByURL

void sbIMediaLibrary::createDefaultLibrary (  ) 

Create the library table with default metadata columns.

This method will synchronously execute the query required to create the default library in the given database.

See also:
sbMediaLibrary.js

void sbIMediaLibrary::deleteColumn ( in AString  columnName  ) 

Remove a column from the library table.

Todo:
deleteColumn is not yet implemented
Parameters:
columnName The name of the column to delete
See also:
addColumn, getColumnInfo, setColumnInfo, getMetadataColumns

AString sbIMediaLibrary::findByGUID ( in AString  mediaGUID  ) 

Get a track's URL from its GUID.

Parameters:
mediaGUID The GUID of the track to find
Returns:
The URL of the track
See also:
findByURL

AString sbIMediaLibrary::findByURL ( in AString  mediaURL  ) 

Get a track's GUID from its URL.

This will find the first track matching the URL if there are more than one.

Parameters:
mediaURL The URL of the track to find
Returns:
The GUID of the track
See also:
findByGUID

void sbIMediaLibrary::getColumnInfo (  ) 

Load the column info for the table into the resultset.

Column Info is kept in a separate table with the following columns:

  column_name TEXT UNIQUE, // The column name in the library
  readable_name TEXT, // The human readable name displayed in the UI
  is_visible INTEGER(0, 1) DEFAULT 0, // If the column may ever be displayed
  default_visibility INTEGER(0, 1) DEFAULT 0, // If the column defaults visible
  is_metadata INTEGER(0, 1) DEFAULT 0, // If the column holds metadata (vs service info)
  sort_weight INTEGER DEFAULT 0, // The default ordering of columns in the UI
  width INTEGER DEFAULT -1, // The default relative width
  type TEXT DEFAULT 'text', // The type of column
  readonly INTEGER(0,1) DEFAULT 0 // If the column may be edited by the user

For instance, to get all of the human readable names of the columns:

function GetColumnNames(aLibrary) {
  // Create the objects
  var medialib = Components.classes["@songbirdnest.com/Songbird/MediaLibrary;1"]
    .createInstance(Components.interfaces.sbIMediaLibrary);
  var query = Components.classes["@songbirdnest.com/Songbird/DatabaseQuery;1"]
    .createInstance(Components.interfaces.sbIDatabaseQuery);

  // Setup the objects
  query.setDatabaseGUID(aLibrary)
  medialib.setQueryObject(query);

  // Get the column info
  medialib.getColumnInfo();
  var resultset = query.getResultObject();

  // Parse the resultset
  var column_names = "";
  for (var i = 0; i < resultset.getRowCount(); i++) {
    column_names += resultset.getRowCellByColumn(i, "column_name") + " ";
  }
  return column_names;
}
See also:
sbIDatabaseQuery, addColumn, deleteColumn, setColumnInfo, getMetadataColumns

sbIDatabaseQuery sbIMediaLibrary::getQueryObject (  ) 

Get the database query object that is being used by the library to make database queries.

Returns:
The database query object that the library uses.
See also:
sbIDatabaseQuery

void sbIMediaLibrary::getUniqueValuesByColumn ( in AString  columnName,
out PRUint32  columnUniqueValCount,
[array, size_is(columnUniqueValCount), retval] out wstring  columnUniqueValues 
)

Get the array of metadata column names in the Column Info tableGet the Unique list of values across the library for the column.

Essentially equivalent to the list in a filterlist UI element.

Parameters:
columnName The column for which to retrieve values
columnUniqueValCount The number of items in the array
columnUniqueValues The array of unique values
See also:
setValueByIndex, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByIndex, getValuesByGUID

AString sbIMediaLibrary::getValueByGUID ( in AString  mediaGUID,
in AString  columnName 
)

Get cell a value from the library table.

Parameters:
mediaGUID The guid of the cell to get, where media library row GUID equals mediaGUID
columnName The name of the column for the cell to get
Returns:
The value of the cell
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByIndex, getValuesByIndex, getValuesByGUID

AString sbIMediaLibrary::getValueByIndex ( in PRInt32  mediaIndex,
in AString  columnName 
)

Get cell a value from the library table.

Todo:
This won't work, it tries to use row number as ID.
Parameters:
mediaIndex The row number of the cell to get
columnName The name of the column for the cell to get
Returns:
The value of the cell
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByGUID, getValuesByIndex, getValuesByGUID

void sbIMediaLibrary::getValuesByGUID ( in AString  mediaGUID,
in PRUint32  metaColumnCount,
[array, size_is(metaColumnCount)] in wstring  metaColumnNames,
out PRUint32  metaValueCount,
[array, size_is(metaValueCount), retval] out wstring  metaValues 
)

Get multiple values from a single database row.

Parameters:
mediaGUID The guid of the cell to get, where media library row GUID equals mediaGUID
metaColumnCount The number of items in the array
metaColumnNames The array of columns to get
metaValueCount The number of items in the array
metaValues The array of values retrieved
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByIndex

void sbIMediaLibrary::getValuesByIndex ( in PRInt32  mediaIndex,
in PRUint32  metaColumnCount,
[array, size_is(metaColumnCount)] in wstring  metaColumnNames,
out PRUint32  metaValueCount,
[array, size_is(metaValueCount), retval] out wstring  metaValues 
)

Get multiple values from a single database row.

Todo:
This won't work, it tries to use row number as ID.
Parameters:
mediaIndex The row number of the cell to get
metaColumnCount The number of items in the array
metaColumnNames The array of columns to get
metaValueCount The number of items in the array
metaValues The array of values retrieved
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByGUID

PRBool sbIMediaLibrary::purgeDefaultLibrary ( in PRBool  willRunQueryLater  ) 

Remove all tracks from the library.

Parameters:
willRunQueryLater If false, execute the query before returning
Returns:
True, if the query was successfully added
See also:
removeMediaByGUID, addMedia

PRBool sbIMediaLibrary::removeMediaByGUID ( in AString  mediaGUID,
in PRBool  willRunQueryLater 
)

Remove a track from the library.

Parameters:
mediaGUID The GUID of the track to remove
willRunQueryLater If false, execute the query before returning
Returns:
True, if the query was successfully added
See also:
removeMediaByGUID, addMedia

PRBool sbIMediaLibrary::removeMediaByURL ( in AString  mediaURL,
in PRBool  willRunQueryLater 
)

Remove a track from the library.

Parameters:
mediaURL The URL of the track to remove
willRunQueryLater If false, execute the query before returning
Returns:
True, if the query was successfully added
See also:
removeMediaByGUID, addMedia

void sbIMediaLibrary::setColumnInfo ( in AString  columnName,
in AString  columnReadableName,
in PRBool  isColumnEverVisible,
in PRBool  isColumnVisibleByDefault,
in PRBool  isMetadataColumn,
in PRInt32  columnSortWeight,
in PRInt32  columnDefaultUIWidth,
in AString  columnDataType,
in PRBool  isColumnReadOnly,
in PRBool  willRunQueryLater 
)

Update the Column Info table with new data.

Parameters:
columnName The column to be changed
columnReadableName The new readable name
isColumnEverVisible The new global visibility bit
isColumnVisibleByDefault The new default visibility bit
isMetadataColumn The new is metadata bit
columnSortWeight The new sort weight
columnDefaultWidth The new default width
columnDataType The new type
isColumnReadOnly The new readonly bit
willRunQueryLater If false, execute the query before returning
See also:
addColumn, deleteColumn, getColumnInfo, getMetadataColumns

void sbIMediaLibrary::setQueryObject ( in sbIDatabaseQuery  queryObj  ) 

Set the database query object that the library will use to make queries to the database.

Parameters:
queryObj Database query object you wish to use with this library.
See also:
sbIDatabaseQuery

PRBool sbIMediaLibrary::setValueByGUID ( in AString  mediaGUID,
in AString  columnName,
in AString  columnValue,
in PRBool  willRunQueryLater 
)

Set cell a value into the library table.

Parameters:
mediaGUID The guid of the cell to get, where media library row GUID equals mediaGUID
columnName The name of the column for the cell to set
columnValue The value of the cell to be set
willRunQueryLater If false, execute the query before returning
Returns:
See also:
getUniqueValuesByColumn, setValueByIndex, setValuesByIndex, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByIndex, getValuesByGUID

PRBool sbIMediaLibrary::setValueByIndex ( in PRInt32  mediaIndex,
in AString  columnName,
in AString  columnValue,
in PRBool  willRunQueryLater 
)

Set cell a value into the library table.

Todo:
This won't work, it tries to use row number as ID.
Parameters:
mediaIndex The row number of the cell to set
columnName The name of the column for the cell to set
columnValue The value of the cell to be set
willRunQueryLater If false, execute the query before returning
Returns:
True if the query was properly loaded/executed
See also:
getUniqueValuesByColumn, setValueByGUID, setValuesByIndex, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByIndex, getValuesByGUID

PRBool sbIMediaLibrary::setValuesByGUID ( in AString  mediaGUID,
in PRUint32  metaColumnCount,
[array, size_is(metaColumnCount)] in wstring  metaColumnNames,
in PRUint32  metaValueCount,
[array, size_is(metaValueCount)] in wstring  metaValues,
in PRBool  willRunQueryLater 
)

Set multiple values into a single database row.

Parameters:
mediaGUID The guid of the cell to get, where media library row GUID equals mediaGUID
metaColumnCount The number of items in the array
metaColumnNames The array of columns to set
metaValueCount The number of items in the array
metaValues The array of values to be set
willRunQueryLater If false, execute the query before returning
Returns:
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByIndex, getValueByIndex, getValueByGUID, getValuesByIndex, getValuesByGUID

PRBool sbIMediaLibrary::setValuesByIndex ( in PRInt32  mediaIndex,
in PRUint32  metaColumnCount,
[array, size_is(metaColumnCount)] in wstring  metaColumnNames,
in PRUint32  metaValueCount,
[array, size_is(metaValueCount)] in wstring  metaValues,
in PRBool  willRunQueryLater 
)

Set multiple values into a single database row.

Todo:
This won't work, it tries to use row number as ID.
Parameters:
mediaIndex The row number of the cell to set
metaColumnCount The number of items in the array
metaColumnNames The array of columns to set
metaValueCount The number of items in the array
metaValues The array of values to be set
willRunQueryLater If false, execute the query before returning
Returns:
True if the query was properly loaded/executed
See also:
getUniqueValuesByColumn, setValueByIndex, setValueByGUID, setValuesByGUID, getValueByIndex, getValueByGUID, getValuesByIndex, getValuesByGUID


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:55 2006 for Songbird by  doxygen 1.4.7