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 00033 #include "nsISupports.idl" 00034 00035 interface nsIObserver; 00036 interface nsISimpleEnumerator; 00037 interface nsIURI; 00038 interface sbIMediaItem; 00039 interface sbIMediaListView; 00040 interface sbIRemoteCommands; 00041 interface sbIRemoteLibrary; 00042 interface sbIRemoteMediaList; 00043 interface sbIRemoteWebPlaylist; 00044 00045 /* 00046 Class: Songbird 00047 00048 The Songbird object provides several pieces of functionality to your web page: playback, 00049 download, listener adding and removing and library creation and retrieval. 00050 00051 This object provides you with functions that enable you to initiate playback 00052 of URL's, <MediaLists> and <WebPlaylists>. Basic playback control functions are also 00053 provided. 00054 00055 The Songbird object provides download functionality as well. You may use it to download 00056 <MediaItems>, <MediaLists> and user selected items present in the <WebPlaylist>. 00057 00058 You may listen for download events by adding "downloadstart" or 00059 "downloadcomplete" event listeners to the document object. These events will 00060 only be sent to handlers within the scope of the page that originated the 00061 downloaded items. The event listener is provided the downloaded media item 00062 within the main Songbird library. To access the media item properties, the user 00063 must have enabled remote access to the main Songbird library. 00064 00065 The Songbird object is accessible (from Javascript) using the "songbird" global variable attached 00066 to the currently loaded document. See the example below. 00067 00068 Example: 00069 (start code) 00070 <script> 00071 //Get the currently playing artist. 00072 var artist = songbird.currentArtist; 00073 00074 //Create default library with current domain and path automatically guessed. 00075 //This is the suggested way to create your site library. 00076 var library = songbird.siteLibrary; 00077 00078 // Look up the artist in your web service database 00079 // ... 00080 00081 //Create a media item from a file 00082 var mediaItem = library.createMediaItem("http://mirrors.creativecommons.org/ccmixter/contrib/Wired/David%20Byrne%20-%20My%20Fair%20Lady.mp3"); 00083 00084 //Create a simple media list. 00085 var mediaList = library.createSimpleMediaList("PlaylistName"); 00086 00087 //Add a mediaitem to it. 00088 mediaList.add(mediaItem); 00089 00090 //Play it. 00091 songbird.playMediaList(mediaList, 0); 00092 00093 //You may also want to trigger a download to the users machine, for this mediaitem. 00094 function onDownloadComplete(aEvent) { 00095 // The event item is the one in the user's main library. 00096 alert(aEvent.item.guid); 00097 alert(aEvent.status); 00098 } 00099 document.addEventListener("downloadcomplete", onDownloadComplete, false); 00100 songbird.downloadItem(mediaItem); 00101 </script> 00102 (end) 00103 00104 See Also: 00105 For more information about the <MediaItem> object, see the <MediaItem> reference. 00106 For more information about the <MediaList> object, see the <MediaList> reference. 00107 For more information about the <WebPlaylist> object, see the <WebPlaylist> reference. 00108 */ 00116 [scriptable, uuid(d2caab8d-35fd-41f8-9716-62ed422c244b)] 00117 interface sbIRemotePlayer : nsISupports 00118 { 00119 00120 /* 00121 Group: Properties 00122 */ 00123 00128 /* 00129 Prop: name 00130 00131 The name of the player. 00132 00133 Type: 00134 String 00135 */ 00136 readonly attribute AString name; 00137 00142 /* 00143 Prop: currentArtist 00144 00145 The name of the artist for the currently playing track. 00146 00147 Type: 00148 String 00149 */ 00150 readonly attribute AString currentArtist; 00151 00156 /* 00157 Prop: currentAlbum 00158 00159 The name of the album for the currently playing media item. 00160 00161 Type: 00162 String 00163 */ 00164 readonly attribute AString currentAlbum; 00165 00170 /* 00171 Prop: currentTrack 00172 00173 The track name of the currently playing media item. 00174 00175 Type: 00176 String 00177 */ 00178 readonly attribute AString currentTrack; 00179 00187 /* 00188 Prop: playing 00189 00190 This is the playing state of the application. If stopped this will be false, 00191 otherwise this will be true. If the application is paused this will be true 00192 so for a complete status you need to check the paused state as well. 00193 00194 Type: 00195 boolean 00196 */ 00197 readonly attribute boolean playing; 00198 00206 /* 00207 Prop: paused 00208 00209 This is the pause state of the application. This will be true if the 00210 application has been paused during playback. It will be false if not 00211 paused or stopped. 00212 00213 Type: 00214 boolean 00215 */ 00216 readonly attribute boolean paused; 00217 00227 /* 00228 Prop: repeat 00229 00230 The repeat state for playback. This can be one of three values: 00231 0 - no repeat 00232 1 - repeat the current track forever 00233 2 - repeat the current playlist forever 00234 00235 Type: 00236 integer 00237 */ 00238 readonly attribute long long repeat; 00239 00246 /* 00247 Prop: shuffle 00248 00249 The shuffle state for playback. This will be true if shuffle is enabled, 00250 false otherwise. 00251 00252 Type: 00253 boolean 00254 */ 00255 readonly attribute boolean shuffle; 00256 00261 /* 00262 Prop: position 00263 00264 The location of playback within the current media, in milliseconds. 00265 00266 Type: 00267 integer 00268 */ 00269 attribute long long position; 00270 00275 /* 00276 Prop: volume 00277 00278 The volume of the application on a range from 0 to 255. 00279 00280 Type: 00281 integer 00282 */ 00283 readonly attribute long long volume; 00284 00291 /* 00292 Prop: mute 00293 00294 True if muted or the volume is set to 0, false otherwise 00295 00296 Type: 00297 boolean 00298 */ 00299 readonly attribute boolean mute; 00300 00305 /* 00306 Prop: commands 00307 00308 The collection of <Commands> associated with the current page. 00309 00310 Type: 00311 <Commands> 00312 */ 00313 readonly attribute sbIRemoteCommands commands; 00314 00319 /* 00320 Prop: webPlaylist 00321 00322 The current <WebPlaylist> object associated with this <Player> instance. 00323 00324 Type: 00325 <WebPlaylist> 00326 */ 00327 readonly attribute sbIRemoteWebPlaylist webPlaylist; 00328 00329 /* 00330 Prop: mainLibrary 00331 00332 The main <Library> for Songbird. This will contain all the <MediaItem>s the 00333 user has on their system. 00334 00335 Type: 00336 <Library> 00337 00338 Example: 00339 (start code) 00340 var mainLib = songbird.mainLibrary; 00341 (end code) 00342 00343 See Also: 00344 <webLibrary> 00345 <libraries()> 00346 <siteLibrary> 00347 */ 00348 readonly attribute sbIRemoteLibrary mainLibrary; 00349 00350 /* 00351 Prop: webLibrary 00352 00353 The web <Library> for Songbird. This will contain all the <MediaItem>s that 00354 have been discovered on web pages the user has visited. 00355 00356 Type: 00357 <Library> 00358 00359 Example: 00360 (start code) 00361 var webLib = songbird.webLibrary; 00362 (end code) 00363 00364 See Also: 00365 <mainLibrary> 00366 <libraries()> 00367 <siteLibrary> 00368 */ 00369 readonly attribute sbIRemoteLibrary webLibrary; 00370 00371 /* 00372 Prop: siteLibrary 00373 00374 Access to a sitelibrary for the current scope (domain and path). If you wish to 00375 change the scope, use <setSiteScope()>. 00376 00377 If a library was already created for the scope, the existing library will be returned. 00378 00379 Type: 00380 <Library> 00381 00382 Example: 00383 (start code) 00384 //Access your site library 00385 var library = songbird.siteLibrary; 00386 (end) 00387 00388 See Also: 00389 <setSiteScope()> 00390 */ 00391 readonly attribute sbIRemoteLibrary siteLibrary; 00392 00393 00397 /* 00398 Prop: downloadMediaList 00399 00400 This <MediaList> is the list that gets all the <MediaItems>s that get 00401 added throught the 3 download methods. If the user has enabled downloading, 00402 tracks can be added to this playlist directly in order to begin downloads. 00403 00404 Type: 00405 <MediaList> 00406 00407 Example: 00408 (start code) 00409 // Get the download media list 00410 var dlList = songbird.downloadMediaList; 00411 (end) 00412 00413 See Also: 00414 <downloadItem()> 00415 <downloadList()> 00416 <downloadSelected()> 00417 */ 00418 00419 readonly attribute sbIRemoteMediaList downloadMediaList; 00420 00421 /* 00422 Group: Methods 00423 */ 00424 00428 /* 00429 Method: addListener() 00430 00431 Add a listener to get notified of changes to Songbird metadata and state. 00432 00433 Prototype: 00434 addListener(String key, Object listener) 00435 00436 Parameters: 00437 key - The key for the metadata or state value. 00438 listener - The listener that will get called when the metadata or state value specified by the key changes. 00439 00440 Example: 00441 (start code) 00442 //Make a listener object. The listener must always have at least this function. 00443 00444 //You may add any number of functions and properties to it for your own use. 00445 00446 //Make sure to save this object somewhere so you may unregister it when you are done 00447 //listening for changes. 00448 var listener = { 00449 observer: function(subject, topic, data) { 00450 } 00451 } 00452 00453 var key = "metadata.genre"; 00454 00455 songbird.addListener(key, listener); 00456 00457 ... 00458 00459 songbird.removeListener(key, listener); 00460 (end) 00461 00462 See Also: 00463 <removeListener()> 00464 00465 Visit <Listener Topics> for a list of keys for metadata and state. 00466 00467 Visit <http://www.xulplanet.com/references/xpcomref/ifaces/nsIObserver.html> for nsIObserver interface reference. 00468 */ 00469 void addListener( in AString aKey, 00470 in nsIObserver aObserver ); 00471 00476 /* 00477 Method: removeListener() 00478 00479 Remove a listener that was previously added using <addListener>. 00480 00481 Prototype: 00482 removeListener(String key, Object listener) 00483 00484 Parameters: 00485 key - The key for the metadata or state value. 00486 listener - The listener that was previously added using <addListener>. 00487 00488 Example: 00489 (start code) 00490 //This example assumes there was a listener object named 'listener' that was previously 00491 //created and added using the key 'metadata.genre'. 00492 00493 ... 00494 00495 var key = "metadata.genre"; 00496 songbird.removeListener(key, listener); 00497 (end) 00498 00499 See Also: 00500 <addListener()> 00501 */ 00502 void removeListener( in AString aKey, 00503 in nsIObserver aObserver ); 00504 00508 /* 00509 Method: downloadItem() 00510 00511 Download a <MediaItem>. <MediaList>s and <Library>ies not allowed. 00512 00513 Prototype: 00514 downloadItem(<MediaItem> mediaItem) 00515 00516 Parameters: 00517 mediaItem - The <MediaItem> to download. 00518 00519 Example: 00520 (start code) 00521 //Create or get library. 00522 var library = songbird.siteLibrary("", ""); 00523 00524 //Create the mediaitem. 00525 var mediaItem = library.createMediaItem("http://path/to/item.mp3"); 00526 00527 //Download the mediaitem to the users local machine. 00528 songbird.downloadItem(mediaItem); 00529 (end) 00530 00531 See Also: 00532 <downloadList()> 00533 <downloadSelected()> 00534 */ 00535 void downloadItem( in sbIMediaItem aItem ); 00536 00541 /* 00542 Method: downloadList() 00543 00544 Download a <MediaList>. As <Library>ies are <MediaList>s they are 00545 allowed here. 00546 00547 Prototype: 00548 downloadList(<MediaList> mediaList) 00549 00550 Parameters: 00551 mediaList - The <MediaList> to download. 00552 00553 Example: 00554 (start code) 00555 //Create or get site library. 00556 var library = songbird.siteLibrary("", ""); 00557 00558 //Create mediaitem. 00559 var mediaItem = library.createMediaItem("http://path/to/item.mp3"); 00560 00561 //Create medialist to download. 00562 var mediaList = library.createSimpleMediaList("Name of List"); 00563 00564 //Add item to medialist. 00565 mediaList.add(mediaItem); 00566 00567 //Download the medialist. 00568 songbird.downloadList(mediaList); 00569 (end) 00570 00571 See Also: 00572 <downloadItem()> 00573 <downloadSelected()> 00574 */ 00575 void downloadList( in sbIRemoteMediaList aList ); 00576 00581 /* 00582 Method: downloadSelected() 00583 00584 Download the <MediaItems> selected by the user in a <WebPlaylist>. 00585 00586 Prototype: 00587 downloadSelected(<WebPlaylist> webPlaylist) 00588 00589 Parameters: 00590 webPlaylist - The <WebPlaylist> from which to download the selected <MediaItems>. 00591 00592 Example: 00593 (start code) 00594 //Download the mediaitems currently selected by the user in 00595 //the current webplaylist. 00596 00597 songbird.downloadSelected(songbird.webPlaylist); 00598 (end) 00599 00600 See Also: 00601 <downloadItem()> 00602 <downloadList()> 00603 */ 00604 void downloadSelected( in sbIRemoteWebPlaylist aWebPlaylist ); 00605 00610 /* 00611 Method: play() 00612 00613 Prototype: 00614 play() 00615 00616 Begin playback at the current location in the <WebPlaylist>. 00617 00618 Example: 00619 (start code) 00620 songbird.play(); 00621 (end) 00622 00623 Note: 00624 Metadata for the <MediaItems> may get updated and overwritten during playback. 00625 See <Metadata Updates> for more details about cases where metadata may 00626 get updated. 00627 00628 See Also: 00629 <playURL()> 00630 <playMediaList()> 00631 <pause()> 00632 <stop()> 00633 <previous()> 00634 <next()> 00635 */ 00636 void play(); 00637 00638 /* 00639 Method: playMediaList() 00640 00641 Begin playback of a <MediaList> at the specified index in the list. 00642 00643 Prototype: 00644 playMediaList(<MediaList> mediaList, Number index) 00645 00646 Parameters: 00647 mediaList - The <MediaList> to play. 00648 index - Where to start playing in the list. Index starts at 0. 00649 00650 Example: 00651 (start code) 00652 //Songbird object implements Player. 00653 //Play the media list, starting with item at index 2. 00654 00655 player.playMediaList(mediaList, 2); 00656 (end) 00657 00658 Note: 00659 Metadata for <MediaItems> may get updated and overwritten during playback. 00660 See <Metadata Updates> for more details about cases where metadata may 00661 get updated. 00662 00663 See Also: 00664 <play()> 00665 <playURL()> 00666 <pause()> 00667 <stop()> 00668 <previous()> 00669 <next()> 00670 */ 00671 void playMediaList( in sbIRemoteMediaList aList, 00672 in PRInt32 aIndex ); 00673 00678 /* 00679 Method: playURL() 00680 00681 Begin playback of a URL. 00682 00683 Prototype: 00684 playURL(String url) 00685 00686 Parameters: 00687 url - The URL to play. 00688 00689 Example: 00690 (start code) 00691 songbird.playURL("http://path/to/item.mp3"); 00692 (end) 00693 00694 Note: 00695 Metadata for the <MediaItem> associated with this URL may get updated 00696 and overwritten during playback. See <Metadata Updates> for more details 00697 about cases where metadata may get updated. 00698 00699 See Also: 00700 <play()> 00701 <playMediaList()> 00702 <pause()> 00703 <stop()> 00704 <previous()> 00705 <next()> 00706 */ 00707 void playURL(in AString aURL); 00708 00713 /* 00714 Method: stop() 00715 00716 Stop playback. 00717 00718 Prototype: 00719 stop() 00720 00721 Example: 00722 (start code) 00723 songbird.stop(); 00724 (end) 00725 00726 See Also: 00727 <play()> 00728 <playURL()> 00729 <playMediaList()> 00730 <pause()> 00731 <previous()> 00732 <next()> 00733 */ 00734 void stop(); 00735 00740 /* 00741 Method: pause() 00742 00743 Pause playback. 00744 00745 Prototype: 00746 pause() 00747 00748 Example: 00749 (start code) 00750 songbird.pause(); 00751 (end) 00752 00753 See Also: 00754 <play()> 00755 <playURL()> 00756 <playMediaList()> 00757 <stop()> 00758 <previous()> 00759 <next()> 00760 */ 00761 void pause(); 00762 00767 /* 00768 Method: next() 00769 00770 Skip to the next item, if there is one, and begin playing. 00771 00772 If there is no next item playback will continue until the 00773 end of the current item. 00774 00775 Prototype: 00776 next() 00777 00778 Example: 00779 (start code) 00780 songbird.next(); 00781 (end) 00782 00783 See Also: 00784 <play()> 00785 <playURL()> 00786 <playMediaList()> 00787 <pause()> 00788 <stop()> 00789 <previous()> 00790 */ 00791 void next(); 00792 00797 /* 00798 Method: previous() 00799 00800 Skip to the previous item, if there is one, and begin playing. 00801 00802 If there is no previous item playback will continue until the of the current item. 00803 00804 Prototype: 00805 previous() 00806 00807 Example: 00808 (start code) 00809 songbird.previous(); 00810 (end) 00811 00812 See Also: 00813 <play()> 00814 <playURL()> 00815 <playMediaList()> 00816 <pause()> 00817 <stop()> 00818 <next()> 00819 */ 00820 void previous(); 00821 00822 /* 00823 Method: setSiteScope() 00824 00825 Set the scope for which to access site-specific privilegs such as the <siteLibrary>. 00826 By default, the page's current domain and path is used. 00827 Use an empty string for the domain and the path to use the default values. 00828 00829 Note: 00830 This may not be called more than once, and not after accessing the <siteLibrary>. 00831 Accessing <siteLibrary> without calling <setSiteScope()> defaults to the most 00832 restrictive scope possible (i.e. full host name, deepest path). 00833 00834 Prototype: 00835 setSiteScope(String domain, String path) 00836 00837 Parameters: 00838 domain - The domain name of the library. This may be an empty string. 00839 path - The path within the domain for the library. This may be an empty string. 00840 00841 Example: 00842 (start code) 00843 // sets the site scope to TLD+1 (will throw unless the page was on *.example.com) 00844 songbird.setSiteScope("example.com", ""); 00845 // sets the site scope to default values 00846 // (will throw because it has already been set once) 00847 songbird.setSiteScope("", ""); 00848 (end) 00849 00850 See Also: 00851 <siteLibrary> 00852 */ 00853 void setSiteScope(in AUTF8String aDomain, in AUTF8String aPath); 00854 00858 nsIURI getSiteScope(); 00859 00860 /* 00861 Method: libraries() 00862 00863 Access to any library in the system via path or 'magic' keyword. 00864 00865 Prototype: 00866 libraries(String libraryID) 00867 00868 Parameters: 00869 libraryID - Library ID you wish to access, this can be a path or 'magic' keyword. 00870 Currently supported keywords are "main" and "web". 00871 00872 Example: 00873 (start code) 00874 var libraryID = "web"; 00875 var library = songbird.libraries(libraryID); 00876 (end) 00877 00878 See Also: 00879 <siteLibrary> 00880 */ 00881 sbIRemoteLibrary libraries(in AString aLibraryID); 00882 00886 [noscript] void fireEventToContent(in AString aClass, in AString aType); 00887 00891 [noscript] void fireMediaItemStatusEventToContent(in AString aClass, 00892 in AString aType, 00893 in sbIMediaItem aMediaItem, 00894 in long aStatus); 00895 00899 [noscript] void onCommandsChanged(); 00900 00904 /* 00905 Method: hasAccess() 00906 00907 Check if the code has access to a category. 00908 00909 Prototype: 00910 boolean hasAccess( String Category ) 00911 00912 Parameters: 00913 Category - The category to check for access to. See <Security> for a list 00914 of valid categories. 00915 00916 Example: 00917 (start code) 00918 ... 00919 if (songbird.hasAccess('Read Current')) 00920 { 00921 var artist = songbird.currentArtist; 00922 } 00923 ... 00924 (end) 00925 */ 00926 boolean hasAccess( in AString aRemotePermCataegory ); 00927 00928 /* Group: Property Creation 00929 00930 Properties define the list of available columns, as well as provide a 00931 means of storing data about a <MediaItem>. This section defines and 00932 explains the parameters for the various property creation methods below. 00933 00934 Common Parameters: 00935 ID - A unique text id of the new property. Does not need to be in URL format 00936 but that is a recommended format for ensuring uniqueness. 00937 displayName - The displayed name of the property. 00938 readOnly - If true this property's value can NOT be edited by the user. 00939 viewable - If true this property will be viewable in all locations of Songbird 00940 including the main library. 00941 nullSort - The type of null sorting desired. When sorted will empty values 00942 sort small or large; see below for more detail. 00943 00944 Specific Parameters: 00945 timeType - Determines the formatting of the datetime string. Present only in 00946 <createDateTimeProperty()>. 00947 buttonLabel - The text displayed on a button. Present only in 00948 <createButtonProperty()> and <createDownloadButtonProperty()>. For 00949 standard button properties the absence of this parameter at property 00950 creation allows buttons to have different text on them by setting 00951 the value of the property on various <MediaItem>s. That is not 00952 possible with download buttons as the value determines the state 00953 and therefore the display of the button. The text for download 00954 buttons MUST be set at creation or the button will not have any 00955 and will not draw properly. 00956 00957 nullSort values: 00958 0 - Null values are infinitely small. This is the default. 00959 1 - Null values are infinitely large. 00960 2 - Null values are always first (regardless of sort direction) 00961 3 - Null values are always last 00962 00963 timeType values: 00964 -1 - Unintialized 00965 0 - 2007-03-28 , in localized format 00966 1 - HH:mm:ss.ms, in localized format. Limited to 24 hour days. 00967 2 - Long date format, 2007-03-28 12:33:01 , no milliseconds. 00968 3 - Duration, represented in HH:mm:ss.ms, in localized format. May exceed 24 hours 00969 4 - Timestamp format, respects unix time, microsecond format. Also internal 00970 storage type. 00971 00972 See: 00973 <createTextProperty()>, <createDateTimeProperty()>, <createURIProperty()>, 00974 <createNumberProperty()>, <createImageProperty()>, <createRatingsProperty()>, 00975 <createButtonProperty()>, <createDownloadButtonProperty()> 00976 */ 00977 00978 /* 00979 Func: createTextProperty() 00980 00981 Add a text property to the system that will be available for all media items. 00982 Properties define the set of possible columns available to the <WebPlaylist> 00983 00984 Prototype: 00985 createTextProperty ( in AString ID, 00986 in AString displayName, 00987 [optional] in boolean readOnly = false, 00988 [optional] in boolean viewable = false, 00989 [optional] in unsigned long nullSort = 0 ) 00990 00991 Parameters: 00992 See <Property Creation> for a complete list of parameter types and their values. 00993 00994 Example: 00995 (start code) 00996 //This example assumes you already have created 00997 //a mediaitem and assigned it to mediaItem. 00998 00999 // Create a property that indicates what store this item is from. 01000 songbird.createTextProperty("http://example.com/Store", 01001 "Store", true, false, 0); 01002 01003 // Add the store name to the media item 01004 mediaitem.setProperty("Store", "Amazon"); 01005 (end) 01006 01007 See Also: 01008 <createDateTimeProperty()> 01009 <createURIProperty()> 01010 <createNumberProperty()> 01011 <createImageProperty()> 01012 <createRatingsProperty()> 01013 <createButtonProperty()> 01014 <createDownloadButtonProperty()> 01015 */ 01016 void createTextProperty( in AString ID, 01017 in AString displayName, 01018 [optional] in boolean readOnly, 01019 [optional] in boolean viewable, 01020 [optional] in unsigned long nullSort ); 01021 01022 /* 01023 Func: createDateTimeProperty() 01024 01025 Add a date time property to the system that will be available for all media 01026 items. 01027 Properties define the set of possible columns available to the <WebPlaylist>. 01028 This property accept values for time in microseconds, 5 minutes 52 seconds 01029 would be a value of 352000000. For the date based time types the time is the 01030 number of microseconds from the linux epoch: 1 January 1970 00:00:00 UTC. 01031 01032 Prototype: 01033 createDateTimeProperty ( in AString ID, 01034 in AString displayName, 01035 in PRInt32 timeType, 01036 [optional] in boolean readOnly = false, 01037 [optional] in boolean viewable = false, 01038 [optional] in unsigned long nullSort = 0 ) 01039 01040 Parameters: 01041 See <Property Creation> for a complete list of parameter types and their values. 01042 01043 Example: 01044 (start code) 01045 //This example assumes you already have created 01046 //a mediaitem and assigned it to mediaItem. 01047 01048 // Create a property of when this item was added to the store 01049 songbird.createDateTimeProperty("http://example.com/DateAdded", 01050 "Added", true, false, 0); 01051 01052 // Add the added date to the media item 01053 mediaitem.setProperty("DateAdded", "4948575738"); 01054 (end) 01055 01056 See Also: 01057 <createTextProperty()> 01058 <createURIProperty()> 01059 <createNumberProperty()> 01060 <createImageProperty()> 01061 <createRatingsProperty()> 01062 <createButtonProperty()> 01063 <createDownloadButtonProperty()> 01064 */ 01065 void createDateTimeProperty( in AString ID, 01066 in AString displayName, 01067 in PRInt32 timeType, 01068 [optional] in boolean readOnly, 01069 [optional] in boolean viewable, 01070 [optional] in unsigned long nullSort ); 01071 01072 /* 01073 Func: createURIProperty() 01074 01075 Add a URI property to the system that will be available for all media items. 01076 Properties define the set of possible columns available to the <WebPlaylist> 01077 01078 Prototype: 01079 createURIProperty ( in AString ID, 01080 in AString displayName, 01081 [optional] in boolean readOnly = false, 01082 [optional] in boolean viewable = false, 01083 [optional] in unsigned long nullSort = 0 ) 01084 01085 Parameters: 01086 See <Property Creation> for a complete list of parameter types and their values. 01087 01088 Example: 01089 (start code) 01090 //This example assumes you already have created 01091 //a mediaitem and assigned it to mediaItem. 01092 01093 // Create a property that links to the store 01094 songbird.createURIProperty("http://example.com/StoreLink", 01095 "Store", true, false, 0); 01096 01097 // Add a url to the media item 01098 mediaitem.setProperty("StoreLink", "http://www.store.com/item.php?id=1"); 01099 (end) 01100 01101 See Also: 01102 <createTextProperty()> 01103 <createDateTimeProperty()> 01104 <createNumberProperty()> 01105 <createImageProperty()> 01106 <createRatingsProperty()> 01107 <createButtonProperty()> 01108 <createDownloadButtonProperty()> 01109 */ 01110 void createURIProperty( in AString ID, 01111 in AString displayName, 01112 [optional] in boolean readOnly, 01113 [optional] in boolean viewable, 01114 [optional] in unsigned long nullSort ); 01115 01116 /* 01117 Func: createNumberProperty() 01118 01119 Add a number property to the system that will be available for all media 01120 items. 01121 Properties define the set of possible columns available to the <WebPlaylist> 01122 01123 Prototype: 01124 createNumberProperty ( in AString ID, 01125 in AString displayName, 01126 [optional] in boolean readOnly = false, 01127 [optional] in boolean viewable = false, 01128 [optional] in unsigned long nullSort = 0 ) 01129 01130 Parameters: 01131 See <Property Creation> for a complete list of parameter types and their values. 01132 01133 Example: 01134 (start code) 01135 //This example assumes you already have created 01136 //a mediaitem and assigned it to mediaItem. 01137 01138 // Create a property that shows the price of this item 01139 songbird.createNumberProperty("http://example.com/Price", "Price", true); 01140 01141 // Add a price to the media item 01142 mediaitem.setProperty("Price", "0.99"); 01143 (end) 01144 01145 See Also: 01146 <createTextProperty()> 01147 <createDateTimeProperty()> 01148 <createURIProperty()> 01149 <createImageProperty()> 01150 <createRatingsProperty()> 01151 <createButtonProperty()> 01152 <createDownloadButtonProperty()> 01153 */ 01154 void createNumberProperty( in AString ID, 01155 in AString displayName, 01156 [optional] in boolean readOnly, 01157 [optional] in boolean viewable, 01158 [optional] in unsigned long nullSort ); 01159 01160 /* 01161 Func: createImageProperty() 01162 01163 Add an image property to the system that will be available for all media 01164 items. 01165 Properties define the set of possible columns available to the <WebPlaylist> 01166 01167 Prototype: 01168 createImageProperty ( in AString ID, 01169 in AString displayName, 01170 [optional] in boolean readOnly = false, 01171 [optional] in boolean viewable = false, 01172 [optional] in unsigned long nullSort = 0 ) 01173 01174 Parameters: 01175 See <Property Creation> for a complete list of parameter types and their values. 01176 01177 Example: 01178 (start code) 01179 //This example assumes you already have created 01180 //a mediaitem and assigned it to mediaItem. 01181 01182 // Create a property that shows the logo of the store this item is from 01183 songbird.createImageProperty("http://example.com/Logo", 01184 "Logo", true, false, 0); 01185 01186 // Add a logo to the media item 01187 mediaitem.setProperty("Logo", "http://www.domain.com/image.jpg"); 01188 (end) 01189 01190 See Also: 01191 <createTextProperty()> 01192 <createDateTimeProperty()> 01193 <createURIProperty()> 01194 <createNumberProperty()> 01195 <createRatingsProperty()> 01196 <createButtonProperty()> 01197 <createDownloadButtonProperty()> 01198 */ 01199 void createImageProperty( in AString ID, 01200 in AString displayName, 01201 [optional] in boolean readOnly, 01202 [optional] in boolean viewable, 01203 [optional] in unsigned long nullSort ); 01204 01205 /* 01206 Func: createRatingsProperty() 01207 01208 Add a ratings property to the system that will be available for all media 01209 items. 01210 Properties define the set of possible columns available to the <WebPlaylist>. 01211 01212 Prototype: 01213 createRatingsProperty ( in AString ID, 01214 in AString displayName, 01215 [optional] in boolean readOnly = false, 01216 [optional] in boolean viewable = false, 01217 [optional] in unsigned long nullSort = 0 ) 01218 01219 Parameters: 01220 See <Property Creation> for a complete list of parameter types and their values. 01221 01222 Example: 01223 (start code) 01224 //This example assumes you already have created 01225 //a mediaitem and assigned it to mediaItem. 01226 01227 // Create a property that shows what the average rating for this item is 01228 songbird.createRatingsProperty("http://example.com/StoreRatings", "Ratings"); 01229 01230 // Add a share button to the media item 01231 mediaitem.setProperty("StoreRatings", "2"); 01232 (end) 01233 01234 See Also: 01235 <createTextProperty()> 01236 <createDateTimeProperty()> 01237 <createURIProperty()> 01238 <createNumberProperty()> 01239 <createImageProperty()> 01240 <createButtonProperty()> 01241 <createDownloadButtonProperty()> 01242 */ 01243 void createRatingsProperty( in AString ID, 01244 in AString displayName, 01245 [optional] in boolean readOnly, 01246 [optional] in boolean viewable, 01247 [optional] in unsigned long nullSort ); 01248 01249 /* 01250 Func: createButtonProperty() 01251 01252 Add a button property to the system that will be available for all media 01253 items. 01254 Properties define the set of possible columns available to the <WebPlaylist> 01255 01256 Prototype: 01257 createButtonProperty ( in AString ID, 01258 in AString displayName, 01259 in AString buttonLabel, 01260 [optional] in boolean readOnly = false, 01261 [optional] in boolean viewable = false, 01262 [optional] in unsigned long nullSort = 0 ) 01263 01264 Parameters: 01265 See <Property Creation> for a complete list of parameter types and their values. 01266 01267 Example: 01268 (start code) 01269 //This example assumes you already have created 01270 //a mediaitem and assigned it to mediaItem. 01271 01272 // Create a property that allows the user to share this item with others 01273 songbird.createButtonProperty("http://example.com/ShareItem", 01274 "Share", "Share Me", true, false, 0); 01275 01276 // Add a share button to the media item 01277 mediaitem.setProperty("ShareItem", "Share me"); 01278 (end) 01279 01280 See Also: 01281 <createDateTimeProperty()> 01282 <createURIProperty()> 01283 <createNumberProperty()> 01284 <createImageProperty()> 01285 <createRatingsProperty()> 01286 <createButtonProperty()> 01287 <createDownloadButtonProperty()> 01288 */ 01289 void createButtonProperty( in AString ID, 01290 in AString displayName, 01291 in AString buttonLabel, 01292 [optional] in boolean readOnly, 01293 [optional] in boolean viewable, 01294 [optional] in unsigned long nullSort ); 01295 01296 /* 01297 Func: createDownloadButtonProperty() 01298 01299 Add a download button property to the system that will be available for all 01300 media items. 01301 Properties define the set of possible columns available to the <WebPlaylist>. 01302 The value to set on this button is a triple field value that includes the 01303 size of the object and the amount downloaded. The fields are separated by 01304 '|' characters. The format is: 01305 (start code) 01306 <mode>|<total size>|<current size> 01307 (end) 01308 01309 Prototype: 01310 createDownloadButtonProperty ( in AString ID, 01311 in AString displayName, 01312 in AString buttonLabel, 01313 [optional] in boolean readOnly = false, 01314 [optional] in boolean viewable = false, 01315 [optional] in unsigned long nullSort = 0 ) 01316 01317 Parameters: 01318 See <Property Creation> for a complete list of parameter types and their values. 01319 01320 Download Mode Types: 01321 0 - none 01322 1 - new 01323 2 - starting 01324 3 - downloading 01325 4 - paused 01326 5 - complete 01327 01328 Example: 01329 (start code) 01330 //This example assumes you already have created 01331 //a mediaitem and assigned it to mediaItem. 01332 01333 // Create a property that will allow the user to get the item (Download) 01334 songbird.createDownloadButtonProperty("http://example.com/DownlodButton", 01335 "Download", "Get", true, false, 0); 01336 01337 // Add a download button to the media item 01338 mediaitem.setProperty("DownloadButton", "1|0|0"); 01339 01340 (end) 01341 01342 See Also: 01343 <createTextProperty()> 01344 <createDateTimeProperty()> 01345 <createURIProperty()> 01346 <createNumberProperty()> 01347 <createImageProperty()> 01348 <createRatingsProperty()> 01349 <createButtonProperty()> 01350 */ 01351 void createDownloadButtonProperty( in AString ID, 01352 in AString displayName, 01353 in AString buttonLabel, 01354 [optional] in boolean readOnly, 01355 [optional] in boolean viewable, 01356 [optional] in unsigned long nullSort ); 01357 01358 };