Songbird / Development / Songbird Add-Ons API Documentation

components/remoteapi/public/sbIRemoteLibrary.idl

00001 /*
00002 //
00003 // BEGIN SONGBIRD GPL
00004 //
00005 // This file is part of the Songbird web player.
00006 //
00007 // Copyright(c) 2005-2008 POTI, Inc.
00008 // http://songbirdnest.com
00009 //
00010 // This file may be licensed under the terms of of the
00011 // GNU General Public License Version 2 (the "GPL").
00012 //
00013 // Software distributed under the License is distributed
00014 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
00015 // express or implied. See the GPL for the specific language
00016 // governing rights and limitations.
00017 //
00018 // You should have received a copy of the GPL along with this
00019 // program. If not, go to http://www.gnu.org/licenses/gpl.html
00020 // or write to the Free Software Foundation, Inc.,
00021 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00022 //
00023 // END SONGBIRD GPL
00024 //
00025  */
00026 
00032 #include "nsISupports.idl"
00033 #include "sbIRemoteMediaList.idl"
00034 
00035 interface nsISimpleEnumerator;
00036 interface nsIStringEnumerator;
00037 interface sbIMediaItem;
00038 interface sbIMediaList;
00039 interface nsIVariant;
00040 
00041 [scriptable, function, uuid(27bfbb84-ac22-46bd-b1bb-cf3baf6f3b3c)]
00042 interface sbICreateMediaListCallback : nsISupports
00043 {
00044   void onCreated(in sbIMediaList aMediaList);
00045 };
00046 
00047 /*
00048 Class: Library
00049 
00050 A <Library> is a collection of <MediaItems> and <MediaLists>.
00051 It is possible to create a <Library> using the <Songbird::siteLibrary>
00052 function.
00053 
00054 Inherits:
00055   <MediaList> <MediaItem>
00056 
00057 Example:
00058   (start code)
00059   //Create or get a library.
00060   var library = songbird.siteLibrary("", "");
00061 
00062   //Create a medialist using the library.
00063   var mediaList = library.createSimpleMediaList("Name of List");
00064 
00065   //Create some mediaitems and add them to the medialist.
00066   var itemURLs = ["http://path/to/song.mp3", "http://path/to/another/song.mp3"];
00067   for(var url in itemURLs) {
00068 
00069     //Calling createMediaItem may throw an exception when it fails
00070     //to create the mediaitem.
00071 
00072     try {
00073       var mediaItem = library.createMediaItem(url);
00074       mediaList.add(mediaItem);
00075     }
00076     catch(e) {
00077 
00078       //Dump it.
00079       dump("Failed creation of mediaitem: " + e);
00080 
00081       //Or alert it.
00082       alert("Failed creation of mediaitem: " + e);
00083 
00084       //Oops the URL was not valid.
00085       if(e.result == Components.results.NS_ERROR_INVALID_ARG) {
00086         alert("The URL: " + url + " was not valid.");
00087       }
00088 
00089     }
00090   }
00091   (end code)
00092 
00093 See Also:
00094   <Songbird>
00095   <MediaItem>
00096   <MediaList>
00097 */
00098 
00110 [scriptable, uuid(a8193c8e-4f9a-4b31-ae7b-4f4ee07f4efb)]
00111 interface sbIRemoteLibrary : nsISupports
00112 {
00124   /*
00125   Group: Library Properties
00126   */
00127 
00128   /*
00129   Prop: scanMediaOnCreation
00130 
00131   Set this property to true if you wish all new <MediaItems>
00132   created to be scanned for metadata.
00133 
00134   Set this property to false if you wish to skip scanning
00135   for metadata when <MediaItems> are created.
00136 
00137   If you are attempting to set all of your own metadata for <MediaItems>
00138   you create, you may set this to false to prevent your metadata
00139   from being overwritten.
00140 
00141   Note:
00142     This property defaults to _true_.
00143 
00144   Type:
00145     Boolean
00146   */
00147   attribute boolean scanMediaOnCreation;
00148 
00160   /*
00161   Group: Library Methods
00162   */
00163 
00164   /*
00165   Method: createMediaItem()
00166 
00167   Create a <MediaItem> from a URL. You may pass in
00168   http and https URLs. Local file URLs are not permitted.
00169 
00170   Prototype:
00171     <MediaItem> createMediaItem(String url)
00172 
00173   Parameters:
00174     url - A URL referring to a media file.
00175 
00176   Returns:
00177     The newly created <MediaItem>.
00178 
00179   Throws:
00180     Invalid Argument (Components.results.NS_ERROR_INVALID_ARG)
00181     if the URL isn't http or https.
00182 
00183   Example:
00184     (start code)
00185     //Create or get a library.
00186     var library = songbird.siteLibrary("", "");
00187 
00188     //Create the mediaitem from a url pointing to a media file.
00189     var mediaItem = null;
00190 
00191     //This function may throw if it fails to create the item because
00192     //the URL is invalid.
00193     try {
00194       mediaItem = library.createMediaItem("http://path/to/file.mp3");
00195     }
00196     catch(e) {
00197       //Oops, bad URL.
00198       if(e.result == Components.results.NS_ERROR_INVALID_ARG) {
00199         alert("Oops, the URL was not valid.");
00200       }
00201     }
00202     (end)
00203 
00204   Note:
00205     Metadata for the <MediaItems> may get updated and overwritten during playback.
00206     See <Metadata Updates> for more details about cases where metadata may
00207     get updated.
00208 
00209   See Also:
00210     <createSimpleMediaList()>
00211     <createMediaListFromURL()>
00212   */
00213   sbIMediaItem createMediaItem(in AString aURL);
00214 
00228   /*
00229   Method: createSimpleMediaList()
00230 
00231   Create a simple <MediaList> with the given name.
00232 
00233   Prototype:
00234     <MediaList> createSimpleMediaList(String name, String siteID)
00235 
00236   Parameters:
00237     name   - The name of the <MediaList> to create.
00238     siteID - An optional siteID to assign. If unspecified then the siteID will
00239              use the value passed for name.
00240 
00241   Returns:
00242     The newly created <MediaList> or null.
00243 
00244   Example:
00245     (start code)
00246     //Create or get a library.
00247     var library = songbird.siteLibrary("", "");
00248 
00249     //Create an empty medialist.
00250     var mediaList = library.createSimpleMediaList("MyList");
00251     (end)
00252 
00253   See Also:
00254     <createMediaItem()>
00255     <createSimpleMediaList()>
00256     <createMediaListFromURL()>
00257   */
00258   sbIRemoteMediaList createSimpleMediaList(in AString aName,
00259                                            [optional] in AString aSiteID);
00260 
00276   /*
00277   Method: createMediaListFromURL()
00278 
00279   Create a <MediaList> from a URL. The URL may point to an
00280   m3u, pls, rss or html file. After being created, the <MediaList>
00281   will contain all valid <MediaItems> it could create from the URLs
00282   it found in the file.
00283 
00284   Prototype:
00285     <MediaList> createMediaListFromURL(String url, Function callback)
00286 
00287   Parameters:
00288     url - The URL of the file to use for creating the <MediaList>.
00289     callback - The optional function that gets called when the load is complete.
00290                This function is passed a single argument that is the newly
00291                created list.
00292 
00293   Example:
00294     (start code)
00295     //Create or get a library.
00296     var library = songbird.siteLibrary("", "");
00297 
00298     //Create the medialist from a url pointing to a file.
00299     library.createMediaListFromURL("http://path/to/file.m3u",
00300       function(list) {
00301         alert("loaded " + list.length + " items!");
00302       }
00303     );
00304     (end)
00305 
00306   See Also:
00307     <createMediaItem()>
00308     <createSimpleMediaList()>
00309   */
00310   void createMediaListFromURL(in AString aName,
00311                               in AString aURL,
00312                               [optional] in sbICreateMediaListCallback aCallback,
00313                               [optional] in AString aSiteID);
00314 
00323   [noscript] void connectToDefaultLibrary(in AString aLibName);
00324 
00331   /*
00332   Method: getMediaListBySiteID()
00333 
00334   Get the site media list with the given siteID.
00335 
00336   Prototype:
00337     <MediaList> getMediaListBySiteID(String siteID)
00338 
00339   Paramters:
00340     name - The siteID of the media list to fetch
00341 
00342   Returns:
00343     The corresponding media list, or null if not found
00344 
00345   Example:
00346     (start code)
00347     //Create or get a library.
00348     var library = songbird.siteLibrary("", "");
00349 
00350     //Fetch the shopping cart media list
00351     var mediaList = library.getMediaListBySiteID("Shopping Cart");
00352     (end)
00353 
00354   See Also:
00355     <createSimpleMediaList()>
00356   */
00357   sbIRemoteMediaList getMediaListBySiteID( in AString aSiteID );
00358 
00359   /*
00360   Method: getPlaylists()
00361 
00362   Get an Enumerator containing all of the <MediaLists> in the <Library>.
00363 
00364   Prototype:
00365     Enumerator getPlaylists()
00366 
00367   Returns:
00368     An Enumerator containing all of the
00369     <MediaLists> present in the <Library>.
00370 
00371   Example:
00372     (start code)
00373     //Create or get a library.
00374     var library = songbird.siteLibrary("", "");
00375 
00376     //Get all MediaLists.
00377     var mediaLists = library.getPlaylists();
00378 
00379     while(mediaLists.hasMoreElements()) {
00380       var mediaList = mediaLists.getNext();
00381 
00382       //Do something with the MediaList
00383       alert(mediaList.name);
00384     }
00385     (end)
00386 
00387   See Also:
00388     <getArtists()>
00389     <albums>
00390     <genres>
00391     <years>
00392 
00393   External Reference:
00394     Please see <http://www.xulplanet.com/references/xpcomref/ifaces/nsISimpleEnumerator.html> for nsISimpleEnumerator interface reference.
00395   */
00396   readonly attribute nsISimpleEnumerator playlists;
00397 
00398 
00399   /*
00400   Method: mostPlayedArtists
00401 
00402   Get the most played artists from the <Library>.
00403 
00404   Prototype:
00405     Array mostPlayedArtists
00406 
00407   Returns:
00408     An array of the most played artists - up to 100.
00409 
00410   Example:
00411     (start code)
00412     var artists = window.songbird.mainLibrary.mostPlayedArtists;
00413     for (var i in artists) {
00414       var elem = document.createElement('li');
00415       elem.textContent = artists[i];
00416       output.appendChild(elem);
00417     }
00418     (end)
00419 
00420   See Also:
00421     <artists>
00422   */
00423 
00424   readonly attribute nsIVariant mostPlayedArtists;
00425 };
00426 
00438 [scriptable, uuid(023734d0-0ba2-4c19-9fe6-58646282b586)]
00439 interface sbIRemoteSiteLibrary : sbIRemoteLibrary
00440 {
00445   readonly attribute AString filename;
00446 
00472   [noscript] void connectToSiteLibrary(in AUTF8String aDomain,
00473                                        in AUTF8String aPath);
00474 };

Generated on Tue Mar 10 14:28:55 2009 for Songbird by  doxygen 1.5.2