Songbird / Development / Songbird Add-Ons API Documentation

components/remoteapi/public/sbIRemotePlayer.idl

Go to the documentation of this file.
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 };

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