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 };