sbIMediaList.idl
Go to the documentation of this file.
1 /*
2 //
3 // BEGIN SONGBIRD GPL
4 //
5 // This file is part of the Songbird web player.
6 //
7 // Copyright(c) 2005-2008 POTI, Inc.
8 // http://songbirdnest.com
9 //
10 // This file may be licensed under the terms of of the
11 // GNU General Public License Version 2 (the "GPL").
12 //
13 // Software distributed under the License is distributed
14 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
15 // express or implied. See the GPL for the specific language
16 // governing rights and limitations.
17 //
18 // You should have received a copy of the GPL along with this
19 // program. If not, go to http://www.gnu.org/licenses/gpl.html
20 // or write to the Free Software Foundation, Inc.,
21 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 //
23 // END SONGBIRD GPL
24 //
25 */
26 
33 #include "sbIMediaItem.idl"
34 
35 interface nsIArray;
36 interface nsIPropertyBag;
37 interface nsISimpleEnumerator;
38 interface nsIStringEnumerator;
39 interface nsITreeView;
40 interface sbICascadeFilterSet;
41 interface sbILibrary;
44 interface sbIMediaListListener;
45 interface sbIMediaListView;
46 interface sbIMediaListViewState;
47 interface sbIPropertyArray;
48 
55 [scriptable, function, uuid(7062f4ae-2d8f-4984-9052-047c45ef057e)]
57 {
66  void onProgress(in unsigned long aItemsProcessed,
67  in boolean aComplete);
68 };
73 [scriptable, uuid(bb58effd-9cfc-4a2c-b65c-6d9a257e4972)]
75 {
83  void onProgress(in unsigned long aItemsProcessed,
84  in boolean aComplete);
85 
89  void onItemAdded(in sbIMediaItem aNewItem);
90 
94  void onComplete();
95 };
96 
105 [scriptable, uuid(d98a6d82-02a3-4192-8e14-1e445f6f9ac1)]
107 {
108  /*
109  Group: MediaList Constants
110  */
111 
121  /*
122  Const: ENUMERATIONTYPE_SNAPSHOT
123 
124  If this constant is specified when calling <enumerateAllItems()> or
125  <enumerateItemsByProperty()>, the EnumerationListener will recieve
126  a copy of the <MediaItem> instead of the <MediaItem> present in
127  the <MediaList>.
128 
129  Note:
130  This is the *suggested* constant to be used when calling <enumerateAllItems()>
131  or <enumerateItemsByProperty()>.
132 
133  Any properties changed on the copy of the <MediaItem> will also be
134  reflected in the <MediaItem> present in the list.
135 
136  Example:
137  (start code)
138  //This example assumes you already have a medialist in the variable named "mediaList".
139  //It also assumes that you have an enumeration listener in the variable named "enumListener".
140 
141  mediaList.enumerateAllItems(enumListener, 0);
142  (end)
143 
144  See Also:
145  <ENUMERATIONTYPE_LOCKING>
146  <enumerateAllItems()>
147  <enumerateItemsByProperty()>
148  */
149  const unsigned short ENUMERATIONTYPE_SNAPSHOT = 0;
150 
162  /*
163  Const: ENUMERATIONTYPE_LOCKING
164 
165  If this constant is specified when calling <enumerateAllItems()> or
166  <enumerateItemsByProperty()> the EnumerationListener will recieve
167  the actual <MediaItem> from the <MediaList>.
168 
169  Note:
170  This is the _suggested_ constant to use when attempting to change a lot of properties
171  on <MediaItems>, or when you need to process them individually without calling any other
172  functions on the <MediaList> during enumeration.
173 
174  Example:
175  (start code)
176  //This example assumes you already have a medialist in the variable named "mediaList".
177  //It also assumes that you have an enumeration listener in the variable named "enumListener".
178 
179  mediaList.enumerateAllItems(enumListener, 1);
180  (end)
181 
182  See Also:
183  <ENUMERATIONTYPE_SNAPSHOT>
184  <enumerateAllItems()>
185  <enumerateItemsByProperty()>
186  */
187  const unsigned short ENUMERATIONTYPE_LOCKING = 1;
188 
205  const unsigned short CONTENTTYPE_NONE = 0;
206 
207  const unsigned short CONTENTTYPE_AUDIO = 1;
208 
209  const unsigned short CONTENTTYPE_VIDEO = 2;
210 
211  const unsigned short CONTENTTYPE_MIX = 3;
212 
213  /*
214  Group: MediaList Properties
215  */
216 
221  /*
222  Prop: name
223 
224  The name of the media list.
225 
226  Type:
227  String
228 
229  Example:
230  (start code)
231  //Create or get a library.
232  var library = songbird.siteLibrary("", "");
233 
234  //Create a medialist.
235  var mediaList = library.createMediaList("simple");
236 
237  //Give it a name.
238  mediaList.name = "80's hits";
239  (end)
240  */
241  attribute AString name;
242 
247  /*
248  Prop: type
249 
250  The type of this media list.
251 
252  Type:
253  String
254 
255  Example:
256  (start code)
257  //Create or get a library.
258  var library = songbird.siteLibrary("", "");
259 
260  //Create a medialist.
261  var mediaList = library.createMediaList("simple");
262 
263  //Tell everyone this is a simple medialist.
264  alert("Hello everyone, this is a " + mediaList.type + " medialist!");
265  (end)
266  */
267  readonly attribute AString type;
268 
273  /*
274  Prop: length
275 
276  The length (in number of items) present in the media list.
277 
278  Type:
279  Number
280 
281  Example:
282  (start code)
283  //Create or get a library.
284  var library = songbird.siteLibrary("", "");
285 
286  //Create a mediaitem.
287  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
288 
289  //Create a medialist.
290  var mediaList = library.createMediaList("simple");
291 
292  //Add same item twice. We now have mediaItem at index 0 and 1.
293  mediaList.add(mediaItem);
294  mediaList.add(mediaItem);
295 
296  //Tell everyone there are 2 tracks in the medialist.
297  alert("There are " + mediaList.length + " mediaitems in the medialist.");
298  (end)
299  */
300  readonly attribute unsigned long length;
301 
306  /*
307  Prop: isEmpty
308 
309  Is the <MediaList> empty?
310 
311  Type:
312  Boolean
313 
314  Returns:
315  true - <MediaList> is empty.
316  false - <MediaList> is _not_ empty.
317 
318  Example:
319  (start code)
320  //Create or get a library.
321  var library = songbird.siteLibrary("", "");
322 
323  //Create a mediaitem.
324  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
325 
326  //Create a medialist.
327  var mediaList = library.createMediaList("simple");
328 
329  //Add same item twice. We now have mediaItem at index 0 and 1.
330  mediaList.add(mediaItem);
331  mediaList.add(mediaItem);
332 
333  //Clear the medialist.
334  mediaList.clear();
335 
336  //Check to see if the mediaList is empty.
337  //The property in this case will be true.
338  var empty = mediaList.isEmpty;
339  (end)
340  */
341  readonly attribute boolean isEmpty;
342 
348  /*
349  Prop: userEditableContent
350 
351  Is the <MediaList>'s content user-editable?
352 
353  Type:
354  Boolean
355 
356  Returns:
357  true - <MediaList> content can be modified by user.
358  false - <MediaList> content should not be modified by user.
359 
360  userEditableContent lists have content that may be changed by the user. This
361  is the default behavior.
362 
363  This attribute is different from sbILibraryResource.userEditable in that
364  non-userEditable resources cannot be renamed or removed, while non-
365  userEditableContent lists can.
366 
367  For instance, a medialist residing on a device that has been physically made
368  readonly should not be deleted or renamed, and should not be added media items
369  by the user (either via drag and drop, "send to" menus, or any other
370  interactive method), its userEditable attribute will be set to false.
371 
372  On the other hand, a smart playlist is an instance of a list whose content is
373  always read-only (its userEditableContent attribute is always false), but that
374  may itself be read-write (if its userEditable attribute is true, the default):
375  in this case, like in the previous one, media items should still not be added
376  or removed from the list by the user (either via drag and drop, "send to"
377  menu, or any other interactive method), but the list itself may still be
378  removed from its parent library, renamed, as well as have its rule set
379  modified by the user (which will yield content that may be different but will
380  still be read-only). On the other hand, a smart playlist whose userEditable
381  attribute is false cannot be renamed, removed, added tracks to, nor have its
382  rule set modified by the user.
383 
384  */
385 
386  readonly attribute boolean userEditableContent;
387 
388  /*
389  Group: MediaList Methods
390  */
391 
398  /*
399  Method: getItemByGuid()
400 
401  Get a <MediaItem> from the <MediaList> by using its <MediaItem::guid>.
402 
403  Prototype:
404  <MediaItem> getItemByGuid(String guid);
405 
406  Parameters:
407  guid - The global unique identifier (<MediaItem::guid>) of the <MediaItem>.
408 
409  Returns:
410  The <MediaItem> with the requested guid.
411 
412  Throws:
413  Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
414  when there is no <MediaItem> with the requested guid.
415 
416  Example:
417  (start code)
418  //Create or get a library.
419  var library = songbird.siteLibrary("", "");
420 
421  //Create a mediaitem.
422  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
423 
424  //Create a medialist.
425  var mediaList = library.createMediaList("simple");
426 
427  //Add same item twice. We now have mediaItem at index 0 and 1.
428  mediaList.add(mediaItem);
429 
430  //Get the same item by guid.
431  var sameMediaItem = mediaList.getItemByGuid(mediaItem.guid);
432  (end)
433 
434  See Also:
435  <getItemByIndex()>
436  <indexOf()>
437  <lastIndexOf()>
438  <contains()>
439  */
440  sbIMediaItem getItemByGuid(in AString aGuid);
441 
448  /*
449  Method: getItemByIndex()
450 
451  Get a <MediaItem> from the <MediaList> by using its index in the <MediaList>.
452 
453  Prototype:
454  <MediaItem> getItemByIndex(Number index)
455 
456  Parameters:
457  index - The index of the <MediaItem>. Index starts at 0.
458 
459  Returns:
460  The <MediaItem> present at the requested index.
461 
462  Throws:
463  Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
464  when there is no <MediaItem> at the requested index.
465 
466  Example:
467  (start code)
468  //Create or get a library.
469  var library = songbird.siteLibrary("", "");
470 
471  //Create a mediaitem.
472  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
473 
474  //Create a medialist.
475  var mediaList = library.createMediaList("simple");
476 
477  //Add same item twice. We now have mediaItem at index 0 and 1.
478  mediaList.add(mediaItem);
479  mediaList.add(mediaItem);
480 
481  //Get the mediaitem at index 1.
482  var sameMediaItem = mediaList.getItemByIndex(1);
483  (end)
484 
485  See Also:
486  <getItemByGuid()>
487  <indexOf()>
488  <lastIndexOf()>
489  <contains()>
490  */
491  sbIMediaItem getItemByIndex(in unsigned long aIndex);
492 
498  /*
499  Method: getListContentType()
500 
501  Get the content type of <MediaList>.
502 
503  Prototype:
504  unsigned short getListContentType()
505 
506  Returns:
507  One of the CONTENTTYPE values above.
508 
509  Throws:
510  Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
511  when there is no <MediaItem> at the requested index.
512 
513  Example:
514  (start code)
515  //Create or get a library.
516  var library = songbird.siteLibrary("", "");
517 
518  //Create an audio mediaitem.
519  var audioMediaItem = library.createMediaItem("http://path/to/item.mp3");
520 
521  //Create a medialist.
522  var mediaList1 = library.createMediaList("simple");
523 
524  //Add audio item.
525  mediaList1.add(audioMediaItem);
526 
527  //The content type is CONTENTTYPE_AUDIO.
528  mediaList1.getListContentType();
529 
530  //Create a video mediaitem.
531  videoMediaItem = library.createMediaItem("http://path/to/item.avi");
532 
533  //Add video item.
534  mediaList1.add(videoMediaItem);
535 
536  //The content type is CONTENTTYPE_MIX
537  mediaList1.getListContentType();
538 
539  //Create another medialist.
540  var mediaList2 = library.createMediaList("simple");
541 
542  //Add video item.
543  mediaList2.add(videoMediaItem);
544 
545  //The content type is CONTENTTYPE_VIDEO
546  mediaList2.getListContentType();
547  (end)
548 
549  See Also:
550  <CONTENTTYPE_NONE>
551  <CONTENTTYPE_AUDIO>
552  <CONTENTTYPE_VIDEO>
553  <CONTENTTYPE_MIX>
554  */
555  unsigned short getListContentType();
556 
572  /*
573  Method: enumerateAllItems()
574 
575  Enumerate all <MediaItems> in the <MediaList>.
576 
577  Prototype:
578  enumerateAllItems(EnumerationListener enumListener, Number enumType)
579 
580  Parameters:
581  enumListener - An EnumerationListener object. See example below.
582  [optional] enumType - The type of enumeration desired. Valid values for enumType
583  are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>. Default is <ENUMERATIONTYPE_SNAPSHOT>.
584 
585  Note:
586  Do not use <ENUMERATIONTYPE_LOCKING> unless you fit a usage scenario described in the
587  <ENUMERATIONTYPE_LOCKING> constant documentation.
588 
589  Example:
590  (start code)
591  (end)
592 
593  See Also:
594  <ENUMERATIONTYPE_SNAPSHOT>
595  <ENUMERATIONTYPE_LOCKING>
596  <enumerateItemsByProperty()>
597  */
598  void enumerateAllItems(in sbIMediaListEnumerationListener aEnumerationListener,
599  [optional] in unsigned short aEnumerationType);
600 
616  /*
617  Method: enumerateItemsByProperty()
618 
619  Enumerate the <MediaItems> in the <MediaList> that have a certain property
620  and value match.
621 
622  This function is useful if you are looking for all items having, for example,
623  an artistName value of "Tom Waits".
624 
625  Prototype:
626  enumerateItemsByProperty(String id, String value, EnumerationListener enumListener)
627 
628  Parameters:
629  id - The ID of the property to match.
630  value - The value of the property to match.
631  enumListener - The enumeration listener.
632  [optional] enumType - The type of enumeration desired. Valid values for enumType
633  are <ENUMERATIONTYPE_SNAPSHOT> and <ENUMERATIONTYPE_LOCKING>.
634  Defaults to ENUMERATIONTYPE_SNAPSHOT.
635 
636  Example:
637  (start code)
638  (end)
639 
640  See Also:
641  <ENUMERATIONTYPE_SNAPSHOT>
642  <ENUMERATIONTYPE_LOCKING>
643  <enumerateAllItems()>
644  */
645  void enumerateItemsByProperty(in AString aPropertyID,
646  in AString aPropertyValue,
647  in sbIMediaListEnumerationListener aEnumerationListener,
648  [optional] in unsigned short aEnumerationType);
649 
658  void enumerateItemsByProperties(in sbIPropertyArray aProperties,
659  in sbIMediaListEnumerationListener aEnumerationListener,
660  [optional] in unsigned short aEnumerationType);
661 
670  nsIArray getItemsByProperty(in AString aPropertyID,
671  in AString aPropertyValue);
672 
681  PRUint32 getItemCountByProperty(in AString aPropertyID,
682  in AString aPropertyValue);
683 
692  nsIArray getItemsByProperties(in sbIPropertyArray aProperties);
693 
702  /*
703  Method: indexOf()
704 
705  Get the index for a <MediaItem> present in the <MediaList>.
706 
707  Prototype:
708  Number indexOf(<MediaItem> mediaItem, Number startFrom)
709 
710  Parameters:
711  mediaItem - The <MediaItem> to find.
712  startFrom - If specfied, the index position at which to start searching. Index starts at 0.
713 
714  Returns:
715  The index where the <MediaItem> was first found.
716 
717  Throws:
718  Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
719  when the <MediaItem> cannot be found.
720 
721  Example:
722  (start code)
723  //Create or get a library.
724  var library = songbird.siteLibrary("", "");
725 
726  //Create a mediaitem.
727  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
728 
729  //Create a medialist.
730  var mediaList = library.createMediaList("simple");
731 
732  //Add same item twice. We now have mediaItem at index 0 and 1.
733  mediaList.add(mediaItem);
734  mediaList.add(mediaItem);
735 
736  //Get the first occurrence of mediaItem.
737  //The returned value in this case will be 0.
738  var index = mediaList.indexOf(mediaItem, 0);
739  (end)
740 
741  See Also:
742  <lastIndexOf()>
743  <contains()>
744  */
745  unsigned long indexOf(in sbIMediaItem aMediaItem,
746  [optional] in unsigned long aStartFrom);
747 
756  /*
757  Method: lastIndexOf()
758 
759  Get the *last* index for a <MediaItem> present in the <MediaList>.
760 
761  Prototype:
762  Number lastIndexOf(<MediaItem> mediaItem, Number startFrom)
763 
764  Parameters:
765  mediaItem - The <MediaItem> to find.
766  startFrom - The index position at which to start searching. Index starts at 0.
767 
768  Returns:
769  The *last* index where the <MediaItem> was first found.
770 
771  Throws:
772  Not Available (Components.results.NS_ERROR_NOT_AVAILABLE)
773  when the <MediaItem> cannot be found.
774 
775  Example:
776  (start code)
777  //Create or get a library.
778  var library = songbird.siteLibrary("", "");
779 
780  //Create a mediaitem.
781  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
782 
783  //Create a medialist.
784  var mediaList = library.createMediaList("simple");
785 
786  //Add same item twice. We now have mediaItem at index 0 and 1.
787  mediaList.add(mediaItem);
788  mediaList.add(mediaItem);
789 
790  //Get the last occurrence of mediaItem.
791  //The returned value in this case will be 1.
792  var index = mediaList.lastIndexOf(mediaItem, 0);
793  (end)
794 
795  See Also:
796  <indexOf()>
797  <contains()>
798  */
799  unsigned long lastIndexOf(in sbIMediaItem aMediaItem,
800  in unsigned long aStartFrom);
801 
808  /*
809  Method: contains()
810 
811  Verify that this <MediaList> contains the requested <MediaItem>.
812 
813  Prototype:
814  Boolean contains(<MediaItem> mediaItem)
815 
816  Parameters:
817  mediaItem - The <MediaItem> to verify.
818 
819  Returns:
820  true - The <MediaItem> *is present* in the <MediaList>.
821  false - The <MediaItem> *is _not_ present*.
822 
823  Example:
824  (start code)
825  //Create or get a library.
826  var library = songbird.siteLibrary("", "");
827 
828  //Create a mediaitem.
829  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
830 
831  //Create a medialist.
832  var mediaList = library.createMediaList("simple");
833 
834  //Add same item twice. We now have mediaItem at index 0 and 1.
835  mediaList.add(mediaItem);
836  mediaList.add(mediaItem);
837 
838  //Check to see if mediaList contains mediaItem.
839  //The returned value in this case will be true.
840  var containsItem = mediaList.contains(mediaItem;
841  (end)
842 
843  See Also:
844  <indexOf()>
845  <lastIndexOf()>
846  */
847  boolean contains(in sbIMediaItem aMediaItem);
848 
854  /*
855  Method: add()
856 
857  Add a <MediaItem> to this <MediaList>.
858 
859  Prototype:
860  add(<MediaItem> mediaItem);
861 
862  // additional forms ( Webpage API only )
863 
864  add(<MediaItem> mediaItem [, boolean shouldDownload]);
865 
866  add(String urlToMedia [, boolean shouldDownload]);
867 
868  add(Array mediaItemURLArray [, boolean shouldDownload]);
869 
870  Parameters:
871  mediaItem - The <MediaItem> to add.
872  urlToMediaItem - The address of the <MediaItem>(s) to add.
873  mediaItemURLArray - An array containing the address(es)
874  of the <MediaItem>(s) to add.
875  shouldDownload - a boolean indicating whether to download or not. It is
876  optional and if absent defaults to FALSE. (only exposed on WebpageAPI
877  calls currently). This only applies if this media list is in the main
878  library.
879 
880  In the additional forms urls to the <MediaItem>s can be passed directly
881  to the <MediaList> for addition. The <MediaItems> will be created and
882  added this <MediaList>. The additional forms are ONLY available through
883  the WebpageAPI.
884 
885  Example:
886  (start code)
887  //Create or get a library.
888  var library = songbird.siteLibrary("", "");
889 
890  //Create a mediaitem.
891  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
892 
893  //Create a medialist.
894  var mediaList = library.createMediaList("simple");
895 
896  //Add same item twice. We now have mediaItem at index 0 and 1.
897  mediaList.add(mediaItem);
898 
899  //Alternate forms
900  mediaList.add(mediaItem, false); // no download
901  mediaList.add(mediaItem, true); // download
902  mediaList.add("http://path/to/a/cool/item.mp3"); // no download
903  mediaList.add("http://path/to/a/great/item.mp3", false); // no download
904  mediaList.add("http://path/to/a/rockin/item.mp3", true); // download
905 
906  mediaList.add(["http://path/to/another/cool/item.mp3",
907  "http://path/to/another/great/item.mp3",
908  "http://path/to/another/rockin/item.mp3"], true);
909  (end)
910 
911  See Also:
912  <addAll()>
913  <remove()>
914  <removeByIndex()>
915  <clear()>
916  */
917  void add(in sbIMediaItem aMediaItem);
918 
927  /*
928  Method: addItem()
929 
930  Add a <MediaItem> to this <MediaList>.
931 
932  Prototype:
933  addItem(<MediaItem> mediaItem);
934 
935  Parameters:
936  mediaItem - The <MediaItem> to add.
937 
938  Example:
939  (start code)
940  //Create or get a library.
941  var library = songbird.siteLibrary("", "");
942 
943  //Create a mediaitem.
944  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
945 
946  //Create a medialist.
947  var mediaList = library.createMediaList("simple");
948 
949  //Add same item twice. We now have mediaItem at index 0 and 1.
950  var newItem = mediaList.addItem(mediaItem);
951 
952  (end)
953 
954  See Also:
955  <addAll()>
956  <remove()>
957  <removeByIndex()>
958  <clear()>
959  */
960  sbIMediaItem addItem(in sbIMediaItem aMediaItem);
966  /*
967  Method: addAll()
968 
969  Add all the <MediaItems> from a <MediaList> into this <MediaList>.
970 
971  Prototype:
972  addAll(<MediaList> mediaList)
973 
974  Parameters:
975  mediaList - The <MediaList> whose <MediaItems> are to be added.
976 
977  Example:
978  (start code)
979  //This example assumes you already have medialists in
980  //variables named mediaListFrom and mediaListTo.
981 
982  //Add all mediaitems from mediaListFrom to mediaListTo.
983  mediaListTo.addAll(mediaListFrom);
984  (end)
985  */
986  void addAll(in sbIMediaList aMediaList);
987 
993  void addSome(in nsISimpleEnumerator aMediaItems);
994 
1004  void addMediaItems(in nsISimpleEnumerator aMediaItems,
1005  in sbIAddMediaItemsListener aListener,
1006  in boolean aAsync);
1007 
1013  /*
1014  Method: remove()
1015 
1016  Remove the first occurrence of the given <MediaItem> from this <MediaList>.
1017 
1018  Prototype:
1019  remove(<MediaItem> mediaItem)
1020 
1021  Parameters:
1022  mediaItem - The <MediaItem> to remove.
1023 
1024  Example:
1025  (start code)
1026  //Create or get a library.
1027  var library = songbird.siteLibrary("", "");
1028 
1029  //Create a mediaitem.
1030  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
1031 
1032  //Create a medialist.
1033  var mediaList = library.createMediaList("simple");
1034 
1035  //Add same item twice. We now have mediaItem at index 0 and 1.
1036  mediaList.add(mediaItem);
1037  mediaList.add(mediaItem);
1038 
1039  //Remove the first occurrence of the mediaitem.
1040  mediaList.remove(mediaItem);
1041 
1042  ... //Now only the second occurrence remains and its index is now 0.
1043  (end)
1044 
1045  See Also:
1046  <add()>
1047  <addAll()>
1048  <removeByIndex()>
1049  */
1050  void remove(in sbIMediaItem aMediaItem);
1051 
1057  /*
1058  Method: removeByIndex()
1059 
1060  Remove a <MediaItem> from the <MediaList> using its index.
1061 
1062  Prototype:
1063  removeByIndex(Number index)
1064 
1065  Parameters:
1066  index - The index of the <MediaItem> to remove.
1067 
1068  Throws:
1069  Invalid Argument (Components.results.NS_ERROR_INVALID_ARG)
1070  when the <MediaItem> cannot be found.
1071 
1072  Example:
1073  (start code)
1074  //Create or get a library.
1075  var library = songbird.siteLibrary("", "");
1076 
1077  //Create a mediaitem.
1078  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
1079 
1080  //Create a medialist.
1081  var mediaList = library.createMediaList("simple");
1082 
1083  //Add same item twice. We now have mediaItem at index 0 and 1.
1084  mediaList.add(mediaItem);
1085  mediaList.add(mediaItem);
1086 
1087  //Remove the duplicate item.
1088  mediaList.removeByIndex(1);
1089  (end)
1090 
1091  See Also:
1092  <add()>
1093  <addAll()>
1094  <remove()>
1095  */
1096  void removeByIndex(in unsigned long aIndex);
1097 
1102  void removeSome(in nsISimpleEnumerator aMediaItems);
1103 
1107  /*
1108  Method: clear()
1109 
1110  Clear the <MediaList>. This will remove all <MediaItems> from this <MediaList>.
1111 
1112  Prototype:
1113  clear()
1114 
1115  Note:
1116  This is the *preferred* way to remove all <MediaItems> from a <MediaList>
1117  because it is optimized for speed.
1118 
1119  Example:
1120  (start code)
1121  //Create or get a library.
1122  var library = songbird.siteLibrary("", "");
1123 
1124  //Create a mediaitem.
1125  var mediaItem = library.createMediaItem("http://path/to/item.mp3");
1126 
1127  //Create a medialist.
1128  var mediaList = library.createMediaList("simple");
1129 
1130  //Add same item twice. We now have mediaItem at index 0 and 1.
1131  mediaList.add(mediaItem);
1132  mediaList.add(mediaItem);
1133 
1134  ... //Do something with the medialist.
1135 
1136  //Clear the medialist.
1137  mediaList.clear();
1138 
1139  //Check to see if the medialist is empty.
1140  //The property in this case will be true.
1141  var empty = mediaList.isEmpty;
1142  (end)
1143  */
1144  void clear();
1145 
1146  const unsigned long LISTENER_FLAGS_ITEMADDED = 1 << 0;
1147  const unsigned long LISTENER_FLAGS_BEFOREITEMREMOVED = 1 << 1;
1148  const unsigned long LISTENER_FLAGS_AFTERITEMREMOVED = 1 << 2;
1149  const unsigned long LISTENER_FLAGS_ITEMUPDATED = 1 << 3;
1150  const unsigned long LISTENER_FLAGS_BEFORELISTCLEARED = 1 << 4;
1151  const unsigned long LISTENER_FLAGS_LISTCLEARED = 1 << 5;
1152  const unsigned long LISTENER_FLAGS_BATCHBEGIN = 1 << 6;
1153  const unsigned long LISTENER_FLAGS_BATCHEND = 1 << 7;
1154  const unsigned long LISTENER_FLAGS_ITEMMOVED = 1 << 8;
1155  const unsigned long LISTENER_FLAGS_ALL = 0xffffffff;
1156 
1173  void addListener(in sbIMediaListListener aListener,
1174  [optional] in boolean aOwnsWeak,
1175  [optional] in unsigned long aFlags,
1176  [optional] in sbIPropertyArray aPropertyFilter);
1177 
1182  void removeListener(in sbIMediaListListener aListener);
1183 
1194 
1200  void runInBatchMode(in sbIMediaListBatchCallback aCallback,
1201  [optional] in nsISupports aUserData);
1202 
1203  /*
1204  * \brief Return the distinct values in the list for a given property
1205  * \param aPropertyID Propery ID to get distinct values for
1206  * \return String enumerator of distinct values for the given property
1207  */
1208 
1209  /*
1210  Method: getDistinctValuesForProperty()
1211 
1212  Get all distinct (unique) values in this <MediaList> for a given property.
1213 
1214  This function is useful if you want to know all the unique artistName property
1215  values for example.
1216 
1217  Prototype:
1218  Enumerator getDistinctValuesForProperty(String id)
1219 
1220  Parameters:
1221  id - The ID of the property for which all distinct values are desired.
1222 
1223  Returns:
1224  Enumerator, contains Strings.
1225 
1226  Example:
1227  (start code)
1228  (end)
1229 
1230  See Also:
1231  <enumerateItemsByProperty()>
1232 
1233  <getProperty()>
1234  */
1235  nsIStringEnumerator getDistinctValuesForProperty(in AString aPropertyID);
1236 };
1237 
1242 [scriptable, function, uuid(02e86553-31e9-4564-b2db-2756b6d5e52f)]
1244 {
1245  void runBatched([optional] in nsISupports aUserData);
1246 };
nsIStringEnumerator getDistinctValuesForProperty(in AString aPropertyID)
sbIMediaItem addItem(in sbIMediaItem aMediaItem)
addItem a media item to this list
void addListener(in sbIMediaListListener aListener, [optional] in boolean aOwnsWeak, [optional] in unsigned long aFlags, [optional] in sbIPropertyArray aPropertyFilter)
Add a listener to this media list.
unsigned long indexOf(in sbIMediaItem aMediaItem, [optional] in unsigned long aStartFrom)
Get the first index of a media item in the list.
void removeByIndex(in unsigned long aIndex)
Remove a media item from the list by index.
nsIArray getItemsByProperties(in sbIPropertyArray aProperties)
Interface used to enumerate the items in a media list.
sbIMediaItem getItemByGuid(in AString aGuid)
Get a media item in the list by guid.
void onProgress(in unsigned long aItemsProcessed, in boolean aComplete)
Callback function that reports progress of async operations.
boolean contains(in sbIMediaItem aMediaItem)
Check if the list contains a media item.
void runInBatchMode(in sbIMediaListBatchCallback aCallback, [optional] in nsISupports aUserData)
Runs the given callback with the given user data in batch mode.
void addMediaItems(in nsISimpleEnumerator aMediaItems, in sbIAddMediaItemsListener aListener, in boolean aAsync)
Adds media items suppled by the provided enumerator.
Cascade filter management for a media list.
void enumerateItemsByProperties(in sbIPropertyArray aProperties, in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
Enumerate the media items that match a list of property IDs and values.
void removeListener(in sbIMediaListListener aListener)
Remove a listener from this media list.
void onProgress(in unsigned long aItemsProcessed, in boolean aComplete)
void add(in sbIMediaItem aMediaItem)
Add a media item to this list.
unsigned short getListContentType()
Get the content type of the media list.
void onItemAdded(in sbIMediaItem aNewItem)
const unsigned long LISTENER_FLAGS_BEFOREITEMREMOVED
var uuid
A brief description of the contents of this interface.
const unsigned short CONTENTTYPE_AUDIO
void addAll(in sbIMediaList aMediaList)
Add the contents of a media list to this list.
readonly attribute boolean userEditableContent
True if the user should be allowed to edit the content of this media list.
A distinct view on a given media list.
readonly attribute AString type
The type of media list (eg "simple")
const unsigned long LISTENER_FLAGS_BATCHEND
PRUint32 getItemCountByProperty(in AString aPropertyID, in AString aPropertyValue)
Interface used to listen to changes to a media list.
sbIMediaListView createView([optional] in sbIMediaListViewState aState)
Create a new, raw view for this list. This is generally not the function that you want to use for mak...
readonly attribute unsigned long length
Returns the length of the list.
Saved state of a media list view.
void enumerateItemsByProperty(in AString aPropertyID, in AString aPropertyValue, in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
Enumerate the media items in the list that match a given property ID and value.
void addSome(in nsISimpleEnumerator aMediaItems)
Adds media items suppled by the provided enumerator NOTE: This method is now deprecated.
sbIMediaItem getItemByIndex(in unsigned long aIndex)
Get a media item in the list by index.
const unsigned short CONTENTTYPE_VIDEO
const unsigned long LISTENER_FLAGS_BEFORELISTCLEARED
const unsigned long LISTENER_FLAGS_BATCHBEGIN
const unsigned short ENUMERATIONTYPE_SNAPSHOT
This flag means that the list being enumerated is a copy that may become out of date.
const unsigned short CONTENTTYPE_MIX
Definition of the sbIMediaItem interface.
const unsigned long LISTENER_FLAGS_AFTERITEMREMOVED
Interface for use with async methods on sbIMediaList. NOTE: this interface is now deprecated...
attribute AString name
The name of the media list.
const unsigned short CONTENTTYPE_NONE
These flags specify the contentType of the media list.
void runBatched([optional] in nsISupports aUserData)
void clear()
Clear the list.
Media library abstraction.
Definition: sbILibrary.idl:82
const unsigned long LISTENER_FLAGS_LISTCLEARED
const unsigned long LISTENER_FLAGS_ITEMMOVED
const unsigned long LISTENER_FLAGS_ITEMADDED
unsigned long lastIndexOf(in sbIMediaItem aMediaItem, in unsigned long aStartFrom)
Get the last index of a media item int he list.
const unsigned long LISTENER_FLAGS_ALL
Interface that defines a single item of media in the system.
const unsigned long LISTENER_FLAGS_ITEMUPDATED
void enumerateAllItems(in sbIMediaListEnumerationListener aEnumerationListener, [optional] in unsigned short aEnumerationType)
Enumerate all items in the list.
restoreWindow aState
An interface to carry around arrays of nsIProperty instances. Users of this interface should only QI ...
void removeSome(in nsISimpleEnumerator aMediaItems)
Removed media items suppled by the provided enumerator.
readonly attribute boolean isEmpty
Is the list empty?
const unsigned short ENUMERATIONTYPE_LOCKING
This flag means that the list is protected from changes by other threads during the enumeration...
nsIArray getItemsByProperty(in AString aPropertyID, in AString aPropertyValue)