sbIMediaList.idl

Go to the documentation of this file.

/*
//
// BEGIN SONGBIRD GPL
//
// This file is part of the Songbird web player.
//
// Copyright(c) 2005-2008 POTI, Inc.
// http://songbirdnest.com
//
// This file may be licensed under the terms of of the
// GNU General Public License Version 2 (the "GPL").
//
// Software distributed under the License is distributed
// on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
// express or implied. See the GPL for the specific language
// governing rights and limitations.
//
// You should have received a copy of the GPL along with this
// program. If not, go to http://www.gnu.org/licenses/gpl.html
// or write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//
// END SONGBIRD GPL
//
*/

#include "sbIMediaItem.idl"

interface nsIArray;
interface nsIPropertyBag;
interface nsISimpleEnumerator;
interface nsIStringEnumerator;
interface nsITreeView;
interface sbICascadeFilterSet;
interface sbILibrary;
interface sbIMediaListBatchCallback;
interface sbIMediaListEnumerationListener;
interface sbIMediaListListener;
interface sbIMediaListView;
interface sbIMediaListViewState;
interface sbIPropertyArray;

[scriptable, function, uuid(7062f4ae-2d8f-4984-9052-047c45ef057e)]
interface sbIMediaListAsyncListener : nsISupports
{
  void onProgress(in unsigned long aItemsProcessed,
                  in boolean aComplete);
};
[scriptable, uuid(bb58effd-9cfc-4a2c-b65c-6d9a257e4972)]
interface sbIAddMediaItemsListener : nsISupports
{
  void onProgress(in unsigned long aItemsProcessed,
                  in boolean aComplete);

  void onItemAdded(in sbIMediaItem aNewItem);

  void onComplete();
};

[scriptable, uuid(d98a6d82-02a3-4192-8e14-1e445f6f9ac1)]
interface sbIMediaList : sbIMediaItem
{
  /*
  Group: MediaList Constants
  */

  /*
  Const: ENUMERATIONTYPE_SNAPSHOT

  If this constant is specified when calling <enumerateAllItems()> or
  <enumerateItemsByProperty()>, the EnumerationListener will recieve
  a copy of the <MediaItem> instead of the <MediaItem> present in
  the <MediaList>.

  Note:
    This is the *suggested* constant to be used when calling <enumerateAllItems()>
    or <enumerateItemsByProperty()>.

    Any properties changed on the copy of the <MediaItem> will also be
    reflected in the <MediaItem> present in the list.

  Example:
    (start code)
    //This example assumes you already have a medialist in the variable named "mediaList".
    //It also assumes that you have an enumeration listener in the variable named "enumListener".

    mediaList.enumerateAllItems(enumListener, 0);
    (end)

  See Also:
    <ENUMERATIONTYPE_LOCKING>
    <enumerateAllItems()>
    <enumerateItemsByProperty()>
  */
  const unsigned short ENUMERATIONTYPE_SNAPSHOT = 0;

  /*
  Const: ENUMERATIONTYPE_LOCKING

  If this constant is specified when calling <enumerateAllItems()> or
  <enumerateItemsByProperty()> the EnumerationListener will recieve
  the actual <MediaItem> from the <MediaList>.

  Note:
    This is the _suggested_ constant to use when attempting to change a lot of properties
    on <MediaItems>, or when you need to process them individually without calling any other
    functions on the <MediaList> during enumeration.

  Example:
    (start code)
    //This example assumes you already have a medialist in the variable named "mediaList".
    //It also assumes that you have an enumeration listener in the variable named "enumListener".

    mediaList.enumerateAllItems(enumListener, 1);
    (end)

  See Also:
    <ENUMERATIONTYPE_SNAPSHOT>
    <enumerateAllItems()>
    <enumerateItemsByProperty()>
  */
  const unsigned short ENUMERATIONTYPE_LOCKING  = 1;

  const unsigned short CONTENTTYPE_NONE = 0;

  const unsigned short CONTENTTYPE_AUDIO = 1;

  const unsigned short CONTENTTYPE_VIDEO = 2;

  const unsigned short CONTENTTYPE_MIX = 3;

  /*
  Group: MediaList Properties
  */

  /*
  Prop: name

  The name of the media list.

  Type:
    String

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Give it a name.
    mediaList.name = "80's hits";
    (end)
  */
  attribute AString name;

  /*
  Prop: type

  The type of this media list.

  Type:
    String

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Tell everyone this is a simple medialist.
    alert("Hello everyone, this is a " + mediaList.type + " medialist!");
    (end)
  */
  readonly attribute AString type;

  /*
  Prop: length

  The length (in number of items) present in the media list.

  Type:
    Number

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Tell everyone there are 2 tracks in the medialist.
    alert("There are " + mediaList.length + " mediaitems in the medialist.");
    (end)
  */
  readonly attribute unsigned long length;

  /*
  Prop: isEmpty

  Is the <MediaList> empty?

  Type:
    Boolean

  Returns:
    true - <MediaList> is empty.
    false - <MediaList> is _not_ empty.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Clear the medialist.
    mediaList.clear();

    //Check to see if the mediaList is empty.
    //The property in this case will be true.
    var empty = mediaList.isEmpty;
    (end)
  */
  readonly attribute boolean isEmpty;

  /*
  Prop: userEditableContent

  Is the <MediaList>'s content user-editable?

  Type:
    Boolean

  Returns:
    true - <MediaList> content can be modified by user.
    false - <MediaList> content should not be modified by user.

  userEditableContent lists have content that may be changed by the user. This
  is the default behavior.

  This attribute is different from sbILibraryResource.userEditable in that
  non-userEditable resources cannot be renamed or removed, while non-
  userEditableContent lists can.

  For instance, a medialist residing on a device that has been physically made
  readonly should not be deleted or renamed, and should not be added media items
  by the user (either via drag and drop, "send to" menus, or any other
  interactive method), its userEditable attribute will be set to false.

  On the other hand, a smart playlist is an instance of a list whose content is
  always read-only (its userEditableContent attribute is always false), but that
  may itself be read-write (if its userEditable attribute is true, the default):
  in this case, like in the previous one, media items should still not be added
  or removed from the list by the user (either via drag and drop, "send to"
  menu, or any other interactive method), but the list itself may still be
  removed from its parent library, renamed, as well as have its rule set
  modified by the user (which will yield content that may be different but will
  still be read-only). On the other hand, a smart playlist whose userEditable
  attribute is false cannot be renamed, removed, added tracks to, nor have its
  rule set modified by the user.

  */

  readonly attribute boolean userEditableContent;

  /*
  Group: MediaList Methods
  */

  /*
  Method: getItemByGuid()

  Get a <MediaItem> from the <MediaList> by using its <MediaItem::guid>.

  Prototype:
    <MediaItem> getItemByGuid(String guid);

  Parameters:
    guid - The global unique identifier (<MediaItem::guid>) of the <MediaItem>.

  Returns:
    The <MediaItem> with the requested guid.

  Throws:
    Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
    when there is no <MediaItem> with the requested guid.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);

    //Get the same item by guid.
    var sameMediaItem = mediaList.getItemByGuid(mediaItem.guid);
    (end)

  See Also:
    <getItemByIndex()>
    <indexOf()>
    <lastIndexOf()>
    <contains()>
  */
  sbIMediaItem getItemByGuid(in AString aGuid);

  /*
  Method: getItemByIndex()

  Get a <MediaItem> from the <MediaList> by using its index in the <MediaList>.

  Prototype:
    <MediaItem> getItemByIndex(Number index)

  Parameters:
    index - The index of the <MediaItem>. Index starts at 0.

  Returns:
    The <MediaItem> present at the requested index.

  Throws:
    Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
    when there is no <MediaItem> at the requested index.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Get the mediaitem at index 1.
    var sameMediaItem = mediaList.getItemByIndex(1);
    (end)

  See Also:
    <getItemByGuid()>
    <indexOf()>
    <lastIndexOf()>
    <contains()>
  */
  sbIMediaItem getItemByIndex(in unsigned long aIndex);

  /*
  Method: getListContentType()

  Get the content type of <MediaList>.

  Prototype:
    unsigned short getListContentType()

  Returns:
    One of the CONTENTTYPE values above.

  Throws:
    Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
    when there is no <MediaItem> at the requested index.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create an audio mediaitem.
    var audioMediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList1 = library.createMediaList("simple");

    //Add audio item.
    mediaList1.add(audioMediaItem);

    //The content type is CONTENTTYPE_AUDIO.
    mediaList1.getListContentType();

    //Create a video mediaitem.
    videoMediaItem = library.createMediaItem("http://path/to/item.avi");

    //Add video item.
    mediaList1.add(videoMediaItem);

    //The content type is CONTENTTYPE_MIX
    mediaList1.getListContentType();

    //Create another medialist.
    var mediaList2 = library.createMediaList("simple");

    //Add video item.
    mediaList2.add(videoMediaItem);

    //The content type is CONTENTTYPE_VIDEO
    mediaList2.getListContentType();
    (end)

  See Also:
    <CONTENTTYPE_NONE>
    <CONTENTTYPE_AUDIO>
    <CONTENTTYPE_VIDEO>
    <CONTENTTYPE_MIX>
  */
  unsigned short getListContentType();

  /*
  Method: enumerateAllItems()

  Enumerate all <MediaItems> in the <MediaList>.

  Prototype:
    enumerateAllItems(EnumerationListener enumListener, Number enumType)

  Parameters:
    enumListener - An EnumerationListener object. See example below.
    [optional] enumType - The type of enumeration desired. Valid values for enumType
               are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>. Default is <ENUMERATIONTYPE_SNAPSHOT>.

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

  Example:
    (start code)
    (end)

  See Also:
    <ENUMERATIONTYPE_SNAPSHOT>
    <ENUMERATIONTYPE_LOCKING>
    <enumerateItemsByProperty()>
  */
  void enumerateAllItems(in sbIMediaListEnumerationListener aEnumerationListener,
                         [optional] in unsigned short aEnumerationType);

  /*
  Method: enumerateItemsByProperty()

  Enumerate the <MediaItems> in the <MediaList> that have a certain property
  and value match.

  This function is useful if you are looking for all items having, for example,
  an artistName value of "Tom Waits".

  Prototype:
    enumerateItemsByProperty(String id, String value, EnumerationListener enumListener)

  Parameters:
    id - The ID of the property to match.
    value - The value of the property to match.
    enumListener - The enumeration listener.
    [optional] enumType - The type of enumeration desired. Valid values for enumType
               are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>.
               Defaults to ENUMERATIONTYPE_SNAPSHOT.

  Example:
    (start code)
    (end)

  See Also:
    <ENUMERATIONTYPE_SNAPSHOT>
    <ENUMERATIONTYPE_LOCKING>
    <enumerateAllItems()>
  */
  void enumerateItemsByProperty(in AString aPropertyID,
                                in AString aPropertyValue,
                                in sbIMediaListEnumerationListener aEnumerationListener,
                                [optional] in unsigned short aEnumerationType);

  void enumerateItemsByProperties(in sbIPropertyArray aProperties,
                                  in sbIMediaListEnumerationListener aEnumerationListener,
                                  [optional] in unsigned short aEnumerationType);

  nsIArray getItemsByProperty(in AString aPropertyID,
                              in AString aPropertyValue);

  PRUint32 getItemCountByProperty(in AString aPropertyID,
                                  in AString aPropertyValue);

  nsIArray getItemsByProperties(in sbIPropertyArray aProperties);

  /*
  Method: indexOf()

  Get the index for a <MediaItem> present in the <MediaList>.

  Prototype:
    Number indexOf(<MediaItem> mediaItem, Number startFrom)

  Parameters:
    mediaItem - The <MediaItem> to find.
    startFrom - If specfied, the index position at which to start searching. Index starts at 0.

  Returns:
    The index where the <MediaItem> was first found.

  Throws:
    Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
    when the <MediaItem> cannot be found.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Get the first occurrence of mediaItem.
    //The returned value in this case will be 0.
    var index = mediaList.indexOf(mediaItem, 0);
    (end)

  See Also:
    <lastIndexOf()>
    <contains()>
  */
  unsigned long indexOf(in sbIMediaItem aMediaItem,
                        [optional] in unsigned long aStartFrom);

  /*
  Method: lastIndexOf()

  Get the *last* index for a <MediaItem> present in the <MediaList>.

  Prototype:
    Number lastIndexOf(<MediaItem> mediaItem, Number startFrom)

  Parameters:
    mediaItem - The <MediaItem> to find.
    startFrom - The index position at which to start searching. Index starts at 0.

  Returns:
    The *last* index where the <MediaItem> was first found.

  Throws:
    Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
    when the <MediaItem> cannot be found.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Get the last occurrence of mediaItem.
    //The returned value in this case will be 1.
    var index = mediaList.lastIndexOf(mediaItem, 0);
    (end)

  See Also:
    <indexOf()>
    <contains()>
  */
  unsigned long lastIndexOf(in sbIMediaItem aMediaItem,
                            in unsigned long aStartFrom);

  /*
  Method: contains()

  Verify that this <MediaList> contains the requested <MediaItem>.

  Prototype:
    Boolean contains(<MediaItem> mediaItem)

  Parameters:
    mediaItem - The <MediaItem> to verify.

  Returns:
    true - The <MediaItem> *is present* in the <MediaList>.
    false - The <MediaItem> *is _not_ present*.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Check to see if mediaList contains mediaItem.
    //The returned value in this case will be true.
    var containsItem = mediaList.contains(mediaItem;
    (end)

  See Also:
    <indexOf()>
    <lastIndexOf()>
  */
  boolean contains(in sbIMediaItem aMediaItem);

  /*
  Method: add()

  Add a <MediaItem> to this <MediaList>.

  Prototype:
    add(<MediaItem> mediaItem);

    // additional forms ( Webpage API only )

    add(<MediaItem> mediaItem [, boolean shouldDownload]);

    add(String urlToMedia [, boolean shouldDownload]);

    add(Array mediaItemURLArray [, boolean shouldDownload]);

  Parameters:
    mediaItem - The <MediaItem> to add.
    urlToMediaItem - The address of the <MediaItem>(s) to add.
    mediaItemURLArray - An array containing the address(es)
      of the <MediaItem>(s) to add.
    shouldDownload - a boolean indicating whether to download or not. It is
      optional and if absent defaults to FALSE. (only exposed on WebpageAPI
      calls currently).  This only applies if this media list is in the main
      library.

    In the additional forms urls to the <MediaItem>s can be passed directly
    to the <MediaList> for addition. The <MediaItems> will be created and
    added this <MediaList>. The additional forms are ONLY available through
    the WebpageAPI.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);

    //Alternate forms
    mediaList.add(mediaItem, false);                         // no download
    mediaList.add(mediaItem, true);                          // download
    mediaList.add("http://path/to/a/cool/item.mp3");         // no download
    mediaList.add("http://path/to/a/great/item.mp3", false); // no download
    mediaList.add("http://path/to/a/rockin/item.mp3", true); // download

    mediaList.add(["http://path/to/another/cool/item.mp3",
                   "http://path/to/another/great/item.mp3",
                   "http://path/to/another/rockin/item.mp3"], true);
    (end)

  See Also:
    <addAll()>
    <remove()>
    <removeByIndex()>
    <clear()>
  */
  void add(in sbIMediaItem aMediaItem);

  /*
  Method: addItem()

  Add a <MediaItem> to this <MediaList>.

  Prototype:
    addItem(<MediaItem> mediaItem);

  Parameters:
    mediaItem - The <MediaItem> to add.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    var newItem = mediaList.addItem(mediaItem);

    (end)

  See Also:
    <addAll()>
    <remove()>
    <removeByIndex()>
    <clear()>
  */
  sbIMediaItem addItem(in sbIMediaItem aMediaItem);
  /*
  Method: addAll()

  Add all the <MediaItems> from a <MediaList> into this <MediaList>.

  Prototype:
    addAll(<MediaList> mediaList)

  Parameters:
    mediaList - The <MediaList> whose <MediaItems> are to be added.

  Example:
    (start code)
    //This example assumes you already have medialists in
    //variables named mediaListFrom and mediaListTo.

    //Add all mediaitems from mediaListFrom to mediaListTo.
    mediaListTo.addAll(mediaListFrom);
    (end)
  */
  void addAll(in sbIMediaList aMediaList);

   void addSome(in nsISimpleEnumerator aMediaItems);
   
  void addMediaItems(in nsISimpleEnumerator aMediaItems,
                     in sbIAddMediaItemsListener aListener,
                     in boolean aAsync);

  /*
  Method: remove()

  Remove the first occurrence of the given <MediaItem> from this <MediaList>.

  Prototype:
    remove(<MediaItem> mediaItem)

  Parameters:
    mediaItem - The <MediaItem> to remove.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Remove the first occurrence of the mediaitem.
    mediaList.remove(mediaItem);

    ... //Now only the second occurrence remains and its index is now 0.
    (end)

  See Also:
    <add()>
    <addAll()>
    <removeByIndex()>
  */
  void remove(in sbIMediaItem aMediaItem);

  /*
  Method: removeByIndex()

  Remove a <MediaItem> from the <MediaList> using its index.

  Prototype:
    removeByIndex(Number index)

  Parameters:
    index - The index of the <MediaItem> to remove.

  Throws:
    Invalid Argument (Components.results.NS_ERROR_INVALID_ARG)
    when the <MediaItem> cannot be found.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    //Remove the duplicate item.
    mediaList.removeByIndex(1);
    (end)

  See Also:
    <add()>
    <addAll()>
    <remove()>
  */
  void removeByIndex(in unsigned long aIndex);

  void removeSome(in nsISimpleEnumerator aMediaItems);

  /*
  Method: clear()

  Clear the <MediaList>. This will remove all <MediaItems> from this <MediaList>.

  Prototype:
    clear()

  Note:
    This is the *preferred* way to remove all <MediaItems> from a <MediaList>
    because it is optimized for speed.

  Example:
    (start code)
    //Create or get a library.
    var library = songbird.siteLibrary("", "");

    //Create a mediaitem.
    var mediaItem = library.createMediaItem("http://path/to/item.mp3");

    //Create a medialist.
    var mediaList = library.createMediaList("simple");

    //Add same item twice. We now have mediaItem at index 0 and 1.
    mediaList.add(mediaItem);
    mediaList.add(mediaItem);

    ... //Do something with the medialist.

    //Clear the medialist.
    mediaList.clear();

    //Check to see if the medialist is empty.
    //The property in this case will be true.
    var empty = mediaList.isEmpty;
    (end)
  */
  void clear();

  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;

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

  void removeListener(in sbIMediaListListener aListener);

  sbIMediaListView createView([optional] in sbIMediaListViewState aState);

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

  /*
   * \brief Return the distinct values in the list for a given property
   * \param aPropertyID Propery ID to get distinct values for
   * \return String enumerator of distinct values for the given property
   */

  /*
  Method: getDistinctValuesForProperty()

  Get all distinct (unique) values in this <MediaList> for a given property.

  This function is useful if you want to know all the unique artistName property
  values for example.

  Prototype:
    Enumerator getDistinctValuesForProperty(String id)

  Parameters:
    id - The ID of the property for which all distinct values are desired.

  Returns:
    Enumerator, contains Strings.

  Example:
    (start code)
    (end)

  See Also:
    <enumerateItemsByProperty()>

    <getProperty()>
  */
  nsIStringEnumerator getDistinctValuesForProperty(in AString aPropertyID);
};

[scriptable, function, uuid(02e86553-31e9-4564-b2db-2756b6d5e52f)]
interface sbIMediaListBatchCallback : nsISupports
{
  void runBatched([optional] in nsISupports aUserData);
};