Media library abstraction. More...

import"sbILibrary.idl";

Inheritance diagram for sbILibrary:

Collaboration diagram for sbILibrary:

Public Member Functions
boolean	containsItemWithSameIdentity (in sbIMediaItem aMediaItem)
	Checks if another mediaitem with the same identity as aMediaItem is already present in the library. This function can be called on the parent library of aMediaItem and it will only return true if a mediaitem other than the param aMediaItem has the same identity as aMediaItem. More...

nsIArray	getItemsWithSameIdentity (in sbIMediaItem aMediaItem)
	Find mediaitems in the library that have the same identity as aMediaItem. Returns an empty array if none are found. This function can be called on the parent library of aMediaItem and it will only return a mediaitem other than the param aMediaItem. More...

nsIChannel	resolve (in nsIURI aUri)
	Resolves a songbird schemed URL to a channel. Throws an exception if the item referenced in the URL is not found. More...

sbIMediaItem	createMediaItem (in nsIURI aContentUri, [optional] in sbIPropertyArray aProperties, [optional] in boolean aAllowDuplicates)
	Creates a new media item aContentUri The URI pointing to the content of the new media item. Use sbILibraryUtils.getContentURI or getFileContentURI to produce library content URI's. More...

boolean	createMediaItemIfNotExist (in nsIURI aContentUri, [optional] in sbIPropertyArray aProperties, [optional] out sbIMediaItem aResultItem)
	Create a new media item, disallowing duplicates, and return if it did. More...

sbIMediaList	createMediaList (in AString aType, [optional] in sbIPropertyArray aProperties)
	Creates a new media list. More...

sbIMediaList	copyMediaList (in AString aType, in sbIMediaList aSource, in boolean aDontCopyContent)
	Creates a new media list. More...

sbIMediaItem	getMediaItem (in AString aGuid)
	Get a media item. More...

sbIMediaItem	getDuplicate (in sbIMediaItem aMediaItem)
	Search for and return a duplicate of the media item specified by aMediaItem. More...

void	clearItems ()
	Clear all media items (excluding medialists) from the library. More...

void	clearItemsByType (in AString aContentType)
	Clear items of a certain CONTENT_TYPE (see sbStandardProperties.h). More...

void	registerMediaListFactory (in sbIMediaListFactory aFactory)
	Register a new media list type at run time. More...

void	optimize ([optional] in boolean aAnalyzeOnly)
	Called when the library should remove unsupported media list types, unknown property types, temporary items, or otherwise optimize its performance or size. More...

void	flush ()
	Called when the library should save any cached data to disk. More...

nsIArray	batchCreateMediaItems (in nsIArray aURIArray, [optional] in nsIArray aPropertyArrayArray, [optional] in boolean aAllowDuplicates)
	Create many media items from a list of URIs, and notify their addition. More...

nsIArray	batchCreateMediaItemsIfNotExist (in nsIArray aURIArray, [optional] in nsIArray aPropertyArrayArray, [optional] out nsIArray aResultItemArray)
	Create many media items from a list of URIs, disallowing duplicates, and return which items were created. More...

void	batchCreateMediaItemsAsync (in sbIBatchCreateMediaItemsListener aListener, in nsIArray aURIArray, [optional] in nsIArray aPropertyArrayArray, [optional] in boolean aAllowDuplicates)
	Asychronously create many media items from a list of URIs. More...

Public Member Functions inherited from sbIMediaList
sbIMediaItem	getItemByGuid (in AString aGuid)
	Get a media item in the list by guid. More...

sbIMediaItem	getItemByIndex (in unsigned long aIndex)
	Get a media item in the list by index. More...

unsigned short	getListContentType ()
	Get the content type of the media list. More...

void	enumerateAllItems (in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
	Enumerate all items in the list. More...

void	enumerateItemsByProperty (in AString aPropertyID, in AString aPropertyValue, in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
	Enumerate the media items in the list that match a given property ID and value. More...

void	enumerateItemsByProperties (in sbIPropertyArray aProperties, in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
	Enumerate the media items that match a list of property IDs and values. More...

nsIArray	getItemsByProperty (in AString aPropertyID, in AString aPropertyValue)

PRUint32	getItemCountByProperty (in AString aPropertyID, in AString aPropertyValue)

nsIArray	getItemsByProperties (in sbIPropertyArray aProperties)

unsigned long	indexOf (in sbIMediaItem aMediaItem, [optional] in unsigned long aStartFrom)
	Get the first index of a media item in the list. More...

unsigned long	lastIndexOf (in sbIMediaItem aMediaItem, in unsigned long aStartFrom)
	Get the last index of a media item int he list. More...

boolean	contains (in sbIMediaItem aMediaItem)
	Check if the list contains a media item. More...

void	add (in sbIMediaItem aMediaItem)
	Add a media item to this list. More...

sbIMediaItem	addItem (in sbIMediaItem aMediaItem)
	addItem a media item to this list More...

void	addAll (in sbIMediaList aMediaList)
	Add the contents of a media list to this list. More...

void	addSome (in nsISimpleEnumerator aMediaItems)
	Adds media items suppled by the provided enumerator NOTE: This method is now deprecated. More...

void	addMediaItems (in nsISimpleEnumerator aMediaItems, in sbIAddMediaItemsListener aListener, in boolean aAsync)
	Adds media items suppled by the provided enumerator. More...

void	remove (in sbIMediaItem aMediaItem)
	Remove the first occurrence of the given media item from the list. More...

void	removeByIndex (in unsigned long aIndex)
	Remove a media item from the list by index. More...

void	removeSome (in nsISimpleEnumerator aMediaItems)
	Removed media items suppled by the provided enumerator. More...

void	clear ()
	Clear the list. More...

void	addListener (in sbIMediaListListener aListener, [optional] in boolean aOwnsWeak, [optional] in unsigned long aFlags, [optional] in sbIPropertyArray aPropertyFilter)
	Add a listener to this media list. More...

void	removeListener (in sbIMediaListListener aListener)
	Remove a listener from this media list. More...

sbIMediaListView	createView ([optional] in sbIMediaListViewState aState)
	Create a new, raw view for this list. This is generally not the function that you want to use for making views as it will create a completely raw view, for example lacking any filterConstraint. Please consider using sbLibraryUtils.createStandardMediaListView and proceed carefully if you use this method instead. More...

void	runInBatchMode (in sbIMediaListBatchCallback aCallback, [optional] in nsISupports aUserData)
	Runs the given callback with the given user data in batch mode. More...

nsIStringEnumerator	getDistinctValuesForProperty (in AString aPropertyID)

Public Member Functions inherited from sbIMediaItem
void	testIsURIAvailable (in nsIObserver aObserver)
	Test if this media item is available for playback. More...

nsIChannel	openInputStreamAsync (in nsIStreamListener aListener, in nsISupports aContext)
	Asynchronously get an input stream to the content of the media item. More...

nsIInputStream	openInputStream ()
	Synchronously get an input stream to the content of the media item. More...

nsIOutputStream	openOutputStream ()
	Get an output stream to the content of the media item. More...

AString	toString ()
	Get a string representation of the media item, useful for debugging. More...

Public Member Functions inherited from sbILibraryResource
AString	getProperty (in AString aID)
	Get the value of a property of this resource. More...

void	setProperty (in AString aID, in AString aValue)
	Set the value of a property on this resource. More...

sbIPropertyArray	getProperties ([optional] in sbIPropertyArray aPropertyIDs)
	Get properties from this resource in a property array. More...

void	setProperties (in sbIPropertyArray aProperties)
	Sets the properties and values in the supplied property array to this resource. This works as if you called setProperty on each property in the array. More...

boolean	equals (in sbILibraryResource aOtherLibraryResource)
	Tests the equality of two library resources. More...

Public Attributes
readonly attribute sbIDevice	device
	Reference to the device that this library is stored on. More...

readonly attribute boolean	supportsForeignMediaItems
	Declares if this library will host foreign media items. More...

readonly attribute nsIPropertyBag2	creationParameters
	Holds the parameters with which this library was created. More...

readonly attribute sbILibraryFactory	factory
	Holds the factory that created this library. More...

readonly attribute nsIStringEnumerator	mediaListTypes
	A list of available media list types. More...

Public Attributes inherited from sbIMediaList
const unsigned short	ENUMERATIONTYPE_SNAPSHOT = 0
	This flag means that the list being enumerated is a copy that may become out of date. More...

const unsigned short	ENUMERATIONTYPE_LOCKING = 1
	This flag means that the list is protected from changes by other threads during the enumeration. More...

const unsigned short	CONTENTTYPE_NONE = 0
	These flags specify the contentType of the media list. More...

const unsigned short	CONTENTTYPE_AUDIO = 1

const unsigned short	CONTENTTYPE_VIDEO = 2

const unsigned short	CONTENTTYPE_MIX = 3

attribute AString	name
	The name of the media list. More...

readonly attribute AString	type
	The type of media list (eg "simple") More...

readonly attribute unsigned long	length
	Returns the length of the list. More...

readonly attribute boolean	isEmpty
	Is the list empty? More...

readonly attribute boolean	userEditableContent
	True if the user should be allowed to edit the content of this media list. More...

const unsigned long	LISTENER_FLAGS_ITEMADDED = 1 << 0

const unsigned long	LISTENER_FLAGS_BEFOREITEMREMOVED = 1 << 1

const unsigned long	LISTENER_FLAGS_AFTERITEMREMOVED = 1 << 2

const unsigned long	LISTENER_FLAGS_ITEMUPDATED = 1 << 3

const unsigned long	LISTENER_FLAGS_BEFORELISTCLEARED = 1 << 4

const unsigned long	LISTENER_FLAGS_LISTCLEARED = 1 << 5

const unsigned long	LISTENER_FLAGS_BATCHBEGIN = 1 << 6

const unsigned long	LISTENER_FLAGS_BATCHEND = 1 << 7

const unsigned long	LISTENER_FLAGS_ITEMMOVED = 1 << 8

const unsigned long	LISTENER_FLAGS_ALL = 0xffffffff

Public Attributes inherited from sbIMediaItem
readonly attribute sbILibrary	library
	The library that this media item is contained in. More...

readonly attribute boolean	isMutable
	Can the media item be changed? More...

readonly attribute sbIMediaItemController	itemController
	An interface to the media item controller (if any) that determines this item's availability for playback. More...

attribute long long	mediaCreated
	Creation time of the media item as a unix timestamp. More...

attribute long long	mediaUpdated
	Last modification time of the media item as a unix timestamp. More...

attribute nsIURI	contentSrc
	A nsIURI that resolves to the content of the media item. More...

attribute long long	contentLength
	Size (in bytes) of the content of the media item. More...

attribute AString	contentType
	Content type of the content of the media item, typically a mime type (should this be renamed?) More...

Public Attributes inherited from sbILibraryResource
readonly attribute AString	guid
	The guid of this resource. More...

readonly attribute long long	created
	The creation time of this resource as a unix timestamp. More...

readonly attribute long long	updated
	The last update time of this resource as a unix timestamp. More...

readonly attribute nsIStringEnumerator	propertyIDs
	Returns a string enumerator of the IDs of all the properties set on this resource. More...

readonly attribute boolean	userEditable
	True if users should be allowed to modify the resource. More...

Detailed Description

Media library abstraction.

The library interface is the primary means of exposing media library data to Songbird. Implementors of this interface must also provide implementations of sbIMediaItem and sbIMediaList.

See Also: sbIMediaItem, sbIMediaList

Definition at line 82 of file sbILibrary.idl.

Member Function Documentation

nsIArray sbILibrary::batchCreateMediaItems	(	in nsIArray	aURIArray,
		[optional] in nsIArray	aPropertyArrayArray,
		[optional] in boolean	aAllowDuplicates
	)

Create many media items from a list of URIs, and notify their addition.

Parameters

aURIArray	nsIArray of nsIURI objects
aPropertyArrayArray	Optional array of sbIPropertyArray. If specified, the properties specified at each array index will be used in the creation of the new media item at the same array index.
aAllowDuplicates	If false, URIs specified in aURIArray that already exist in the library will not be created and not returned. If true, media items will be created for all of the URIs specified regardless if they already exist. The default is false.

Returns: nsIArray of the new sbIMediaItem objects

void sbILibrary::batchCreateMediaItemsAsync	(	in sbIBatchCreateMediaItemsListener	aListener,
		in nsIArray	aURIArray,
		[optional] in nsIArray	aPropertyArrayArray,
		[optional] in boolean	aAllowDuplicates
	)

Asychronously create many media items from a list of URIs.

Parameters

aListener	Listener to receive progress and complete notifications
aURIArray	nsIArray of nsIURI objects
aPropertyArrayArray	Optional array of sbIPropertyArray. If specified, the properties specified at each array index will be used in the creation of the new media item at the same array index.
aAllowDuplicates	If false, URIs specified in aURIArray that already exist in the library will not be created and not returned. If true, media items will be created for all of the URIs specified regardless if they already exist. The default is false.

nsIArray sbILibrary::batchCreateMediaItemsIfNotExist	(	in nsIArray	aURIArray,
		[optional] in nsIArray	aPropertyArrayArray,
		[optional] out nsIArray	aResultItemArray
	)

Create many media items from a list of URIs, disallowing duplicates, and return which items were created.

Parameters

aURIArray	nsIArray of nsIURI objects
aPropertyArrayArray	Optional array of sbIPropertyArray. If specified, the properties specified at each array index will be used in the creation of the new media item at the same array index.
aResultItemArray	nsIArray of sbIMediaItem objects that were created (or found).

Returns: nsIArray of nsIVariant objects of type VTYPE_BOOL indicating which items were newly created.

void sbILibrary::clearItems ( )

Clear all media items (excluding medialists) from the library.

Note: If you wish to clear the entire library (including medialists) use clear() instead.

void sbILibrary::clearItemsByType ( in AString aContentType )

Clear items of a certain CONTENT_TYPE (see sbStandardProperties.h).

boolean sbILibrary::containsItemWithSameIdentity ( in sbIMediaItem aMediaItem )

Checks if another mediaitem with the same identity as aMediaItem is already present in the library. This function can be called on the parent library of aMediaItem and it will only return true if a mediaitem other than the param aMediaItem has the same identity as aMediaItem.

Parameters

aMediaItem The mediaitem whose identity will be calculated and we will check if another mediaitem with that identity is already in the library.

Returns: True if a mediaitem with the same identity as aMediaItem but with a different guid is present in the library.

sbIMediaList sbILibrary::copyMediaList	(	in AString	aType,
		in sbIMediaList	aSource,
		in boolean	aDontCopyContent
	)

Creates a new media list.

Parameters

aType	- The type of media list to create.
aSource	- A media list whose items and properties are to be copied.
aDontCopyContent	- Do not copy the list content if true.

Returns: A new media list.

sbIMediaItem sbILibrary::createMediaItem	(	in nsIURI	aContentUri,
		[optional] in sbIPropertyArray	aProperties,
		[optional] in boolean	aAllowDuplicates
	)

Creates a new media item aContentUri The URI pointing to the content of the new media item. Use sbILibraryUtils.getContentURI or getFileContentURI to produce library content URI's.

Parameters

aProperties	Optional initial properties for this new item
aAllowDuplicates	If false, an attempt to create a new media item with a content URI that already exists in the library will simply return the existing item rather than creating a new one. If true, a new media item will be created with the specified content URI regardless if it is a duplicate. The default is false.

Returns: A new, persisted media item

boolean sbILibrary::createMediaItemIfNotExist	(	in nsIURI	aContentUri,
		[optional] in sbIPropertyArray	aProperties,
		[optional] out sbIMediaItem	aResultItem
	)

Create a new media item, disallowing duplicates, and return if it did.

Parameters

[optional] aResultItem the item that was created (or found)

Returns: Whether a new media item was created

See Also: createMediaItem

sbIMediaList sbILibrary::createMediaList	(	in AString	aType,
		[optional] in sbIPropertyArray	aProperties
	)

Creates a new media list.

Parameters

aType	- The type of media list to create.
aProperties	Optional initial properties for this new item

Returns: A new media list.

void sbILibrary::flush ( )

Called when the library should save any cached data to disk.

sbIMediaItem sbILibrary::getDuplicate ( in sbIMediaItem aMediaItem )

Search for and return a duplicate of the media item specified by aMediaItem.

Parameters

aMediaItem Media item for which to get duplicate.

Returns: Duplicate media item or null if no duplicates.

nsIArray sbILibrary::getItemsWithSameIdentity ( in sbIMediaItem aMediaItem )

Find mediaitems in the library that have the same identity as aMediaItem. Returns an empty array if none are found. This function can be called on the parent library of aMediaItem and it will only return a mediaitem other than the param aMediaItem.

Parameters

aMediaItem The mediaitem whose identity will be calculated and we will check if other mediaitems with that identity are already in the library.

Returns: An array of mediaitems with the same identity as aMediaItem that are not the same as aMediaItem (as determined by guid). An empty array is returned if none are found.

sbIMediaItem sbILibrary::getMediaItem ( in AString aGuid )

Get a media item.

Parameters

aGuid Guid of media item to get

Returns: The requested media item

void sbILibrary::optimize ( [optional] in boolean aAnalyzeOnly )

Called when the library should remove unsupported media list types, unknown property types, temporary items, or otherwise optimize its performance or size.

Hints for transfer service to possibly add a transcode step

Parameters

aAnalyzeOnly - Optimize will only run analysis of the library for performance.

void sbILibrary::registerMediaListFactory ( in sbIMediaListFactory aFactory )

Register a new media list type at run time.

Parameters

aFactory - The factory that will create the media list

nsIChannel sbILibrary::resolve ( in nsIURI aUri )

Resolves a songbird schemed URL to a channel. Throws an exception if the item referenced in the URL is not found.

Parameters

aUri	The nsIURI to a media item to resolve

Returns: An open channel to the content of the referenced media item

Member Data Documentation

readonly attribute nsIPropertyBag2 sbILibrary::creationParameters

Holds the parameters with which this library was created.

Definition at line 97 of file sbILibrary.idl.

readonly attribute sbIDevice sbILibrary::device

Reference to the device that this library is stored on.

Definition at line 87 of file sbILibrary.idl.

readonly attribute sbILibraryFactory sbILibrary::factory

Holds the factory that created this library.

Definition at line 102 of file sbILibrary.idl.

readonly attribute nsIStringEnumerator sbILibrary::mediaListTypes

A list of available media list types.

Definition at line 226 of file sbILibrary.idl.

readonly attribute boolean sbILibrary::supportsForeignMediaItems

Declares if this library will host foreign media items.

Definition at line 92 of file sbILibrary.idl.

The documentation for this interface was generated from the following file:

/home/martin/dev/nightingale-hacking/components/library/base/public/sbILibrary.idl

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

Member Data Documentation