sbILibraryResource.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 "nsISupports.idl"

interface nsIStringEnumerator;
interface nsIURI;
interface sbIPropertyArray;

[scriptable, uuid(d0ed8ac0-1a2a-11dd-bd0b-0800200c9a66)]
interface sbILibraryResource : nsISupports
{
  /*
  Group: Resource Properties
  */

  /*
  Prop: guid

  The global unique identifier of this Library object.
  
  Type:
    String

  Note:
    <MediaItem>, <MediaList> and <Library> are all Library Objects.
  */
  readonly attribute AString guid;

  /*
  Prop: created

  The creation time of this Library object.

  Type:
    Number, in (TODO units???)

  Note:
    <MediaItem>, <MediaList> and <Library> are all Library Objects.
  */
  readonly attribute long long created;

  /*
  Prop: updated

  The last update time of this Library object. Changing any property
  constitutes an update.

  Type:
    Number, in (TODO units???)
  
  Note:
    <MediaItem>, <MediaList> and <Library> are all Library Objects.
  */
  readonly attribute long long updated;

  readonly attribute nsIStringEnumerator propertyIDs;
  
  readonly attribute boolean userEditable;

  /*
  Group: Resource Methods
  */

  /*
  Method: getProperty()

  Get the value of a property for this library object.

  Prototype:
    String getProperty(String id)

  Parameters:
    id - The ID property value requested.

  Example:
    (start code)
    //This example assumes you already have created 
    //a mediaitem and assigned it to mediaItem.

    //Get the albumName property from a mediaitem.
    var albumName = mediaItem.getProperty("http://songbirdnest.com/data/1.0#albumName");
    (end)

  Standard Properties:
    http://songbirdnest.com/data/1.0#albumDetailUrl - A URL with information on the album
    http://songbirdnest.com/data/1.0#albumName - The name of the album
    http://songbirdnest.com/data/1.0#artistDetailUrl - A URL with information on the artist
    http://songbirdnest.com/data/1.0#artistName - The name of the artist
    http://songbirdnest.com/data/1.0#bitRate - The bit rate of the media, in bits per second
    http://songbirdnest.com/data/1.0#bpm - The number of beats per minute
    http://songbirdnest.com/data/1.0#columnSpec - Column display data
    http://songbirdnest.com/data/1.0#composerName - The name of the composer
    http://songbirdnest.com/data/1.0#copyrightURL - A URL with information on the copyright
    http://songbirdnest.com/data/1.0#defaultColumnSpec - Default column display data
    http://songbirdnest.com/data/1.0#disableDownload - Prevent this item from being downloaded
    http://songbirdnest.com/data/1.0#discNumber - The number of disc this media appears on in a compilation
    http://songbirdnest.com/data/1.0#downloadDetails - Download state and progress
    http://songbirdnest.com/data/1.0#duration - The duration of this media, in microseconds
    http://songbirdnest.com/data/1.0#enableAutoDownload - whether this item should be automatically downloaded when added to the main library
    http://songbirdnest.com/data/1.0#excludeFromHistory - This track should not be logged in playback history when played
    http://songbirdnest.com/data/1.0#genre - The genre of this media
    http://songbirdnest.com/data/1.0#hidden - Whether this item should be hidden from the user
    http://songbirdnest.com/data/1.0#isPartOfCompilation - Whether this media is part of a compilation
    http://songbirdnest.com/data/1.0#lastPlayTime - The last time the media was played
    http://songbirdnest.com/data/1.0#lyricistName - The name of the lyricist
    http://songbirdnest.com/data/1.0#lyrics - The lyrics of the media
    http://songbirdnest.com/data/1.0#originPage - The page this media was located on
    http://songbirdnest.com/data/1.0#originPageTitle - The title of the page this media was located on
    http://songbirdnest.com/data/1.0#originURL - The URL this media was retrived from
    http://songbirdnest.com/data/1.0#playCount - The number of times this media has been played
    http://songbirdnest.com/data/1.0#primaryImageURL - The URL of the primary image
    http://songbirdnest.com/data/1.0#producerName - The name of the producer
    http://songbirdnest.com/data/1.0#rating - The user-set rating of the item, either 0 (unset) or in the range 1-5
    http://songbirdnest.com/data/1.0#recordLabelName - The name of the record label
    http://songbirdnest.com/data/1.0#sampleRate - The sample rate of the media, in samples per second
    http://songbirdnest.com/data/1.0#skipCount - The number of times this item was skipped
    http://songbirdnest.com/data/1.0#totalDiscs - The total number of discs in a compilation
    http://songbirdnest.com/data/1.0#totalTracks - The total number of tracks in a compilation
    http://songbirdnest.com/data/1.0#trackName - The name of the track
    http://songbirdnest.com/data/1.0#trackNumber - The track number of this media in a compilation
    http://songbirdnest.com/data/1.0#year - The year the media was released

  Note:
    Metadata for the <MediaItems> may get updated and overwritten during playback.
    See <Metadata Updates> for more details about cases where metadata may 
    get updated.

  See Also:
    <setProperty()>
  */
  AString getProperty(in AString aID);

  /*
  Method: setProperty()

  Set the value of a property for this library object.

  Prototype:
    setProperty(String id, String value)

  Example:
    (start code)
    //This example assumes you already have created 
    //a mediaitem and assigned it to mediaItem.

    //Set the albumName property from a mediaitem.
    mediaItem.setProperty("http://songbirdnest.com/data/1.0#albumName", "Let Us Play");
    (end)

  Standard Properties:
    http://songbirdnest.com/data/1.0#albumDetailUrl - A URL with information on the album
    http://songbirdnest.com/data/1.0#albumName - The name of the album
    http://songbirdnest.com/data/1.0#artistDetailUrl - A URL with information on the artist
    http://songbirdnest.com/data/1.0#artistName - The name of the artist
    http://songbirdnest.com/data/1.0#bitRate - The bit rate of the media, in bits per second
    http://songbirdnest.com/data/1.0#bpm - The number of beats per minute
    http://songbirdnest.com/data/1.0#columnSpec - Column display data
    http://songbirdnest.com/data/1.0#composerName - The name of the composer
    http://songbirdnest.com/data/1.0#defaultColumnSpec - Default column display data
    http://songbirdnest.com/data/1.0#disableDownload - Prevent this item from being downloaded
    http://songbirdnest.com/data/1.0#discNumber - The number of disc this media appears on in a compilation
    http://songbirdnest.com/data/1.0#downloadDetails - Download state and progress
    http://songbirdnest.com/data/1.0#duration - The duration of this media, in microseconds
    http://songbirdnest.com/data/1.0#enableAutoDownload - whether this item should be automatically downloaded when added to the main library
    http://songbirdnest.com/data/1.0#excludeFromHistory - This track should not be logged in playback history when played
    http://songbirdnest.com/data/1.0#genre - The genre of this media
    http://songbirdnest.com/data/1.0#hidden - Whether this item should be hidden from the user
    http://songbirdnest.com/data/1.0#isPartOfCompilation - Whether this media is part of a compilation
    http://songbirdnest.com/data/1.0#lyricistName - The name of the lyricist
    http://songbirdnest.com/data/1.0#lyrics - The lyrics of the media
    http://songbirdnest.com/data/1.0#primaryImageURL - The URL of the primary image
    http://songbirdnest.com/data/1.0#producerName - The name of the producer
    http://songbirdnest.com/data/1.0#rating - The user-set rating of the item, either 0 (unset) or in the range 1-5
    http://songbirdnest.com/data/1.0#recordLabelName - The name of the record label
    http://songbirdnest.com/data/1.0#sampleRate - The sample rate of the media, in samples per second
    http://songbirdnest.com/data/1.0#totalDiscs - The total number of discs in a compilation
    http://songbirdnest.com/data/1.0#totalTracks - The total number of tracks in a compilation
    http://songbirdnest.com/data/1.0#trackName - The name of the track
    http://songbirdnest.com/data/1.0#trackNumber - The track number of this media in a compilation
    http://songbirdnest.com/data/1.0#year - The year the media was released

  Note:
    Metadata for the <MediaItems> may get updated and overwritten during playback.
    See <Metadata Updates> for more details about cases where metadata may 
    get updated.

  See Also:
    <getProperty()>
  */
  void setProperty(in AString aID, in AString aValue);

  sbIPropertyArray getProperties([optional] in sbIPropertyArray aPropertyIDs);

  void setProperties(in sbIPropertyArray aProperties);

  boolean equals(in sbILibraryResource aOtherLibraryResource);
};