Songbird / Development / Songbird Add-Ons API Documentation

sbIMediaList Interface Reference

A brief description of the contents of this interface. More...

import "sbIMediaList.idl";

Inheritance diagram for sbIMediaList:

sbIMediaItem sbILibraryResource sbILibrary sbILocalDatabaseSmartMediaList sbIDeviceLibrary List of all members.

Public Member Functions

sbIMediaItem getItemByGuid (in AString aGuid)
 Get a media item in the list by guid.
sbIMediaItem getItemByIndex (in unsigned long aIndex)
 Get a media item in the list by index.
void enumerateAllItems (in sbIMediaListEnumerationListener aEnumerationListener,[optional] in unsigned short aEnumerationType)
 Enumerate all items in the list.
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.
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.
nsIArray getItemsByProperty (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.
unsigned long lastIndexOf (in sbIMediaItem aMediaItem, in unsigned long aStartFrom)
 Get the last index of a media item int he list.
boolean contains (in sbIMediaItem aMediaItem)
 Check if the list contains a media item.
void add (in sbIMediaItem aMediaItem)
 Add a media item to this list.
void addAll (in sbIMediaList aMediaList)
 Add the contents of a media list to this list.
void addSome (in nsISimpleEnumerator aMediaItems)
 Adds media items suppled by the provided enumerator.
void remove (in sbIMediaItem aMediaItem)
 Remove the first occurrence of the given media item from the list.
void removeByIndex (in unsigned long aIndex)
 Remove a media item from the list by index.
void removeSome (in nsISimpleEnumerator aMediaItems)
 Removed media items suppled by the provided enumerator.
void clear ()
 Clear the list.
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.
void removeListener (in sbIMediaListListener aListener)
 Remove a listener from this media list.
sbIMediaListView createView ([optional] in sbIMediaListViewState aState)
 Create a new view for this list.
void runInBatchMode (in sbIMediaListBatchCallback aCallback,[optional] in nsISupports aUserData)
 Runs the given callback with the given user data in batch mode.

Public Attributes

const unsigned short ENUMERATIONTYPE_SNAPSHOT = 0
 This flag means that the list being enumerated is a copy that may become out of date.
const unsigned short ENUMERATIONTYPE_LOCKING = 1
 This flag means that the list is protected from changes by other threads during the enumeration.
attribute AString name
 The name of the media list.
readonly attribute AString type
 The type of media list (eg "simple").
readonly attribute unsigned
long 
length
 Returns the length of the list.
readonly attribute boolean isEmpty
 Is the list empty?
readonly attribute boolean userEditableContent
 True if the user should be allowed to edit the content of this media list.
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_LISTCLEARED = 1 << 4
const unsigned long LISTENER_FLAGS_BATCHBEGIN = 1 << 5
const unsigned long LISTENER_FLAGS_BATCHEND = 1 << 6
const unsigned long LISTENER_FLAGS_ITEMMOVED = 1 << 7
const unsigned long LISTENER_FLAGS_ALL = 0xffffffff

Detailed Description

A brief description of the contents of this interface.

A detailed description of this interface

See also:
List of "see also" interfaces

Definition at line 58 of file sbIMediaList.idl.


Member Function Documentation

sbIMediaItem sbIMediaList::getItemByGuid ( in AString  aGuid  ) 

Get a media item in the list by guid.

Parameters:
aGuid Guid of the media item
Returns:
Media item with the requested guid or null if not found

sbIMediaItem sbIMediaList::getItemByIndex ( in unsigned long  aIndex  ) 

Get a media item in the list by index.

Parameters:
aIndex Index of the media item
Returns:
Media item with the requested index

void sbIMediaList::enumerateAllItems ( in sbIMediaListEnumerationListener  aEnumerationListener,
[optional] in unsigned short  aEnumerationType 
)

Enumerate all items in the list.

Do not use ENUMERATIONTYPE_LOCKING unless you fit a usage scenario described in the ENUMERATIONTYPE_LOCKING constant documentation.

Do not remove items during enumeration, regardless of enumeration type! This will cause functional issues during enumeration because the property cache will no longer contain associated data for items even though the item instance is still valid!

Parameters:
aEnumerationListener - The enumeration listener.
aEnumerationType - One of the ENUMERATIONTYPE values above. Default is ENUMERATIONTYPE_SNAPSHOT.

void sbIMediaList::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.

Do not remove items during enumeration, regardless of enumeration type! This will cause functional issues during enumeration because the property cache will no longer contain associated data for items even though the item instance is still valid!

Parameters:
aPropertyID - Property ID to search.
aPropertyValue - Property value to search.
aEnumerationListener - The enumeration listener.
[optional] aEnumerationType - One of the ENUMERATIONTYPE values above. Default is <ENUMERATIONTYPE_SNAPSHOT>.

void sbIMediaList::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.

Parameters:
aProperties - A list of property ID/value pairs.
aEnumerationListener - The enumeration listener.
[optional] aEnumerationType - One of the ENUMERATIONTYPE values above.

nsIArray sbIMediaList::getItemsByProperty ( in AString  aPropertyID,
in AString  aPropertyValue 
)

Get all items that have a certain property set to the specified value.

Parameters:
aPropertyID The property id.
aPropertyValue The property value.
Returns:
An array of sbIMediaItem elements.
Exceptions:
NS_ERROR_NOT_AVAILABLE when no items match the criteria.

nsIArray sbIMediaList::getItemsByProperties ( in sbIPropertyArray  aProperties  ) 

Get all items that have a all properties set to the values specified.

Parameters:
aProperties The property array containing property key/value pairs.
Returns:
An array of sbIMediaItem elements.
Exceptions:
NS_ERROR_NOT_AVAILABLE when no items match the criteria.

unsigned long sbIMediaList::indexOf ( in sbIMediaItem  aMediaItem,
[optional] in unsigned long  aStartFrom 
)

Get the first index of a media item in the list.

Parameters:
aMediaItem Media item to search for
aStartFrom If specified, the index to start the search from.
Returns:
The index that the media item was first found at, or throws NS_ERROR_NOT_AVAILABLE if not found

unsigned long sbIMediaList::lastIndexOf ( in sbIMediaItem  aMediaItem,
in unsigned long  aStartFrom 
)

Get the last index of a media item int he list.

Parameters:
aMediaItem Media item to search for
aStartFrom ben write me
Returns:
The index that the media item was last found at, or throws NS_ERROR_NOT_AVAILABLE if not found

boolean sbIMediaList::contains ( in sbIMediaItem  aMediaItem  ) 

Check if the list contains a media item.

Parameters:
aMediaItem Media item to search for
Returns:
true if the media item was found, false if it was not found

void sbIMediaList::add ( in sbIMediaItem  aMediaItem  ) 

Add a media item to this list.

Parameters:
aMediaItem The media item to add to the list

void sbIMediaList::addAll ( in sbIMediaList  aMediaList  ) 

Add the contents of a media list to this list.

Parameters:
aMediaList The media list whose contents are to be added

void sbIMediaList::addSome ( in nsISimpleEnumerator  aMediaItems  ) 

Adds media items suppled by the provided enumerator.

Parameters:
aMediaItems An enumerator returning sbIMediaItem objects

void sbIMediaList::remove ( in sbIMediaItem  aMediaItem  ) 

Remove the first occurrence of the given media item from the list.

Parameters:
aMediaItem Media item to remove

void sbIMediaList::removeByIndex ( in unsigned long  aIndex  ) 

Remove a media item from the list by index.

Parameters:
aIndex Index of the item to remove

void sbIMediaList::removeSome ( in nsISimpleEnumerator  aMediaItems  ) 

Removed media items suppled by the provided enumerator.

Parameters:
aMediaItems An enumerator returning sbIMediaItem objects

void sbIMediaList::addListener ( in sbIMediaListListener  aListener,
[optional] in boolean  aOwnsWeak,
[optional] in unsigned long  aFlags,
[optional] in sbIPropertyArray  aPropertyFilter 
)

Add a listener to this media list.

Parameters:
aListener The listener to add
aOwnsWeak If set to false, the media list will hold a strong reference to |aListener|. If set to true and |aListener| supports the nsIWeakReference interface, a weak reference will be held. Otherwise an error will be returned.
aFlags A bit mask made up the LISTENER_FLAGS_ constants above. Use this to filter out unwanted notifications. If not set, this will default to LISTENER_FLAGS_ALL
aPropertyFilter If this argument is specified, the onItemUpdated notification will only be sent for updates to any of the properties specified in the array. Note that the values of the properties in the array are ignored. If not set or null, no filtering will be applied.

void sbIMediaList::removeListener ( in sbIMediaListListener  aListener  ) 

Remove a listener from this media list.

Parameters:
aListener The listener to remove

sbIMediaListView sbIMediaList::createView ( [optional] in sbIMediaListViewState  aState  ) 

Create a new view for this list.

Parameters:
aState Optional initial state for the view
Returns:
The new view

void sbIMediaList::runInBatchMode ( in sbIMediaListBatchCallback  aCallback,
[optional] in nsISupports  aUserData 
)

Runs the given callback with the given user data in batch mode.

See also:
sbIMediaListBatchCallback


Member Data Documentation

const unsigned short sbIMediaList::ENUMERATIONTYPE_SNAPSHOT = 0

This flag means that the list being enumerated is a copy that may become out of date.

Use this flag if you don't care whether or not other threads change the list's contents. The listener may make changes to the list at any time but those changes will not be reflected in the enumeration sequence.

Definition at line 101 of file sbIMediaList.idl.

const unsigned short sbIMediaList::ENUMERATIONTYPE_LOCKING = 1

This flag means that the list is protected from changes by other threads during the enumeration.

Use this flag if you need to be certain that the contents of the list are not changed during enumeration. Note that all other threads will block until the enumeration is complete. Furthermore, changes made to list from the listener are not permitted until the listener has received the onEnumerationEnd notification.

Definition at line 139 of file sbIMediaList.idl.


The documentation for this interface was generated from the following file:
Generated on Tue Mar 10 14:29:00 2009 for Songbird by  doxygen 1.5.2