dom/tv/nsITVService.idl

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   3  * You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 #include "nsISupports.idl"
   6
   7 interface nsIArray;
   8
   9 %{C++
  10 #define TV_TUNER_DATA_CID \
  11   { 0x1f36be28, 0xf9fe, 0x2dc3, { 0xbf, 0x2a, 0x17, 0x97, 0x93, 0x40, 0xff, 0xe1 } }
  12 #define TV_TUNER_DATA_CONTRACTID \
  13   "@mozilla.org/tv/tvtunerdata;1"
  14 %}
  15
  16 /**
  17  * XPCOM component which acts as the container for tuner data.
  18  *
  19  * NOTE: Use do_CreateInstance() to create the Gecko provided implementation,
  20  * and then uses the setter functions to adjust the properties of the object
  21  * before passing it.
  22  */
  23 [scriptable, builtinclass, uuid(608d3f7e-f9f1-4b3c-82c2-3eb60b1d3de8)]
  24 interface nsITVTunerData : nsISupports
  25 {
  26   attribute DOMString id;
  27
  28   /**
  29    * Get the supported source types of the tuner. Please refer to
  30    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
  31    *
  32    * @param count       The number of supported source types.
  33    * @param sourceTypes An array of supported source types.
  34    */
  35   void getSupportedSourceTypes([optional] out unsigned long count,
  36                                [retval, array, size_is(count)] out string sourceTypes);
  37
  38   /**
  39    * Set the supported source types of the tuner. Please refer to
  40    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
  41    *
  42    * @param count       The number of supported source types.
  43    * @param sourceTypes An array of supported source types.
  44    */
  45   void setSupportedSourceTypes(in unsigned long count,
  46                                [array, size_is(count)] in string sourceTypes);
  47 };
  48
  49 %{C++
  50 #define TV_CHANNEL_DATA_CID \
  51   { 0xdafe6881, 0x0964, 0xdb5b, { 0x59, 0xc6, 0x20, 0x0b, 0xa6, 0x59, 0xe6, 0x68 } }
  52 #define TV_CHANNEL_DATA_CONTRACTID \
  53   "@mozilla.org/tv/tvchanneldata;1"
  54 %}
  55
  56 /**
  57  * XPCOM component which acts as the container for channel data.
  58  *
  59  * NOTE: Use do_CreateInstance() to create the Gecko provided implementation,
  60  * and then uses the setter functions to adjust the properties of the object
  61  * before passing it.
  62  */
  63 [scriptable, builtinclass, uuid(5d01ea74-2db6-11e4-9dba-74d02b97e723)]
  64 interface nsITVChannelData : nsISupports
  65 {
  66   attribute DOMString networkId;
  67   attribute DOMString transportStreamId;
  68   attribute DOMString serviceId;
  69   attribute DOMString type;
  70   attribute DOMString number;
  71   attribute DOMString name;
  72   [infallible] attribute boolean isEmergency;
  73   [infallible] attribute boolean isFree;
  74 };
  75
  76 %{C++
  77 #define TV_PROGRAM_DATA_CID \
  78   { 0x11415eeb, 0x27a6, 0x1c04, { 0x91, 0x33, 0x3e, 0x0a, 0xdd, 0x48, 0x5d, 0xb3 } }
  79 #define TV_PROGRAM_DATA_CONTRACTID \
  80   "@mozilla.org/tv/tvprogramdata;1"
  81 %}
  82
  83 /**
  84  * XPCOM component which acts as the container for program data.
  85  *
  86  * NOTE: Use do_CreateInstance() to create the Gecko provided implementation,
  87  * and then uses the setter functions to adjust the properties of the object
  88  * before passing it.
  89  */
  90 [scriptable, builtinclass, uuid(ed65422e-2d97-11e4-89d6-74d02b97e723)]
  91 interface nsITVProgramData : nsISupports
  92 {
  93   attribute DOMString eventId;
  94   attribute DOMString title;
  95   [infallible] attribute unsigned long long startTime;
  96   [infallible] attribute unsigned long long duration;
  97   attribute DOMString description;
  98   attribute DOMString rating;
  99
 100   /**
 101    * Get the audio languages of the program. Please refer to
 102    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
 103    *
 104    * @param count     The number of languages.
 105    * @param languages An array of languages.
 106    */
 107   void getAudioLanguages([optional] out unsigned long count,
 108                          [retval, array, size_is(count)] out string languages);
 109
 110   /**
 111    * Set the audio languages of the program. Please refer to
 112    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
 113    *
 114    * @param count     The number of languages.
 115    * @param languages An array of languages.
 116    */
 117   void setAudioLanguages(in unsigned long count,
 118                          [array, size_is(count)] in string languages);
 119
 120   /**
 121    * Get the subtitle languages of the program. Please refer to
 122    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
 123    *
 124    * @param count     The number of languages.
 125    * @param languages An array of languages.
 126    */
 127   void getSubtitleLanguages([optional] out unsigned long count,
 128                             [retval, array, size_is(count)] out string languages);
 129
 130   /**
 131    * Set the subtitle languages of the program. Please refer to
 132    * http://seanyhlin.github.io/TV-Manager-API/ for available values.
 133    *
 134    * @param count     The number of languages.
 135    * @param languages An array of languages.
 136    */
 137   void setSubtitleLanguages(in unsigned long count,
 138                             [array, size_is(count)] in string languages);
 139 };
 140
 141 [builtinclass, uuid(c3fd7a8c-21e4-11e4-97e8-74d02b97e723)]
 142 interface nsITVSourceListener : nsISupports
 143 {
 144   /**
 145    * Called when a channel is detected through scanning (after
 146    * |nsITVService::startScanningChannels()| is invoked and probably before
 147    * |nsITVService::stopScanningChannels()|, if any, is invoked).
 148    *
 149    * @param tunerId     The ID of the tuner which the source belongs to.
 150    * @param sourceType  The type of the source which the channel belongs to.
 151    *                    Please refer to http://seanyhlin.github.io/TV-Manager-API/
 152    *                    for available values.
 153    * @param channelData The data of the added channel.
 154    */
 155   void notifyChannelScanned(in DOMString tunerId,
 156                             in DOMString sourceType,
 157                             in nsITVChannelData channelData);
 158
 159   /**
 160    * Called when the operation of channel scanning is complete (after
 161    * |nsITVService::startScanningChannels()| is invoked).
 162    *
 163    * @param tunerId     The ID of the tuner which the source belongs to.
 164    * @param sourceType  The type of the source which the channel belongs to.
 165    *                    Please refer to http://seanyhlin.github.io/TV-Manager-API/
 166    *                    for available values.
 167    */
 168   void notifyChannelScanComplete(in DOMString tunerId,
 169                                  in DOMString sourceType);
 170
 171   /**
 172    * Called when the operation of channel scanning is forced to stop due to
 173    * something wrong during scanning.
 174    *
 175    * @param tunerId     The ID of the tuner which the source belongs to.
 176    * @param sourceType  The type of the source which the channel belongs to.
 177    *                    Please refer to http://seanyhlin.github.io/TV-Manager-API/
 178    *                    for available values.
 179    */
 180   void notifyChannelScanStopped(in DOMString tunerId,
 181                                 in DOMString sourceType);
 182
 183   /**
 184    * Called when a new EIT is broadcasted.
 185    *
 186    * @param tunerId         The ID of the tuner which the source belongs to.
 187    * @param sourceType      The type of the source which the channel belongs to.
 188    *                        Please refer to http://seanyhlin.github.io/TV-Manager-API/
 189    *                        for available values.
 190    * @param channelData     The channel data which the programs belong to.
 191    * @param programDataList An array of correspondent program data.
 192    * @param count           The number of programs.
 193    */
 194   void notifyEITBroadcasted(in DOMString tunerId,
 195                             in DOMString sourceType,
 196                             in nsITVChannelData channelData,
 197                             [array, size_is(count)] in nsITVProgramData programDataList,
 198                             in unsigned long count);
 199 };
 200
 201 [builtinclass, uuid(a19e6e7e-2293-11e4-b335-74d02b97e723)]
 202 interface nsITVServiceCallback : nsISupports
 203 {
 204   const unsigned short TV_ERROR_OK = 0;
 205   const unsigned short TV_ERROR_FAILURE = 1;
 206   const unsigned short TV_ERROR_INVALID_ARG = 2;
 207   const unsigned short TV_ERROR_NO_SIGNAL = 3;
 208   const unsigned short TV_ERROR_NOT_SUPPORTED = 4;
 209
 210   /**
 211    * Called when something wrong happens.
 212    *
 213    * @param errorCode Error code listed above from the underlying layer.
 214    */
 215   void notifyError(in unsigned short errorCode);
 216
 217   /**
 218    * Called when the operation succeeds.
 219    *
 220    * @param dataList A list of data.
 221    *                 An array of |nsITVTunerData| when used for |getTuners()|.
 222    *                 An array of |nsITVChannelData| ordered by the LCN (Logical
 223    *                 Channel Number) when used for |getChannels()|.
 224    *                 An array of |nsITVProgramData| ordered by the start time
 225    *                 for |getPrograms()|.
 226    *                 An array of |nsITVChannelData| with only one element for
 227    *                 |setChannel()|.
 228    *                 An array of |nsISupportsString| with only one element for
 229    *                 |getOverlayId()|.
 230    *
 231    * NOTE: |nsIArray| is adopted to prevent this interface from being split into
 232    * multiple interfaces with different |notifySuccess|. Though the
 233    * implementation of TV service may need |nsIMutableArray| to fill in the
 234    * array, it doesn't seem necessary for other places to use the mutable one.
 235    */
 236   void notifySuccess([optional] in nsIArray dataList);
 237 };
 238
 239 %{C++
 240 #define TV_SERVICE_CONTRACTID \
 241   "@mozilla.org/tv/tvservice;1"
 242 %}
 243
 244 /**
 245  * XPCOM component which interacts with the underlying TV components.
 246  *
 247  * NOTE: The implementation is expected to be done by TV vendors to cooperate
 248  * with their own TV stack. The methods should not be called on any thread
 249  * except for the XPCOM main thread.
 250  *
 251  * NOTE: The callbacks passing in the methods must be called asynchronously. In
 252  * the implementation, actual runnable objects may need to be created and call
 253  * the callback off of the runnables, after the function returns.
 254  * TVServiceRunnables.h provides some ready-made runnables and could be used in
 255  * the following way.
 256  *
 257  * nsCOMPtr<nsIRunnable> runnable =
 258  *   new TVServiceNotifyRunnable(callback, dataList, optional errorCode);
 259  * return NS_DispatchToCurrentThread(runnable);
 260  */
 261 [uuid(1b17e3cc-1c84-11e4-a4d4-74d02b97e723)]
 262 interface nsITVService : nsISupports
 263 {
 264   attribute nsITVSourceListener sourceListener;
 265
 266   /**
 267    * Get all tuners.
 268    *
 269    * @param callback   The callback object where either |notifyError| or
 270    *                   |notifySuccess|, which takes an array of
 271    *                   |nsITVTunerData|, is expected.
 272    */
 273   void getTuners(in nsITVServiceCallback callback);
 274
 275   /**
 276    * Set the source type to be used by the given tuner.
 277    *
 278    * @param tunerId    The ID of the tuner.
 279    * @param sourceType The source type to be used.
 280    * @param callback   The callback object where either |notifyError| or
 281    *                   |notifySuccess| is expected.
 282    */
 283   void setSource(in DOMString tunerId,
 284                  in DOMString sourceType,
 285                  in nsITVServiceCallback callback);
 286
 287   /**
 288    * Start scanning channels on the given tuner.
 289    *
 290    * Once the operation successfully starts, a series of |notifyChannelScanned|
 291    * from |nsITVSourceListener| are expected, and followed by one of either
 292    * |notifyChannelScanComplete| or |notifyChannelScanStopped|.
 293    *
 294    * @param tunerId     The ID of the tuner.
 295    * @param sourceType  The source type to be used.
 296    * @param callback    The callback object where either |notifyError| or
 297    *                    |notifySuccess| is expected.
 298    */
 299   void startScanningChannels(in DOMString tunerId,
 300                              in DOMString sourceType,
 301                              in nsITVServiceCallback callback);
 302
 303   /**
 304    * Stop scanning channels on the given tuner.
 305    *
 306    * Once the operation succeeds, a call of |notifyChannelScanStopped| from
 307    * |nsITVSourceListener| should be expected.
 308    *
 309    * @param tunerId    The ID of the tuner.
 310    * @param sourceType The source type to be used.
 311    * @param callback   The callback object where either |notifyError| or
 312    *                   |notifySuccess| is expected.
 313    */
 314   void stopScanningChannels(in DOMString tunerId,
 315                             in DOMString sourceType,
 316                             in nsITVServiceCallback callback);
 317
 318   /**
 319    * Clear the cache for scanned channels, if any, from the underlying layer.
 320    */
 321   void clearScannedChannelsCache();
 322
 323   /**
 324    * Set the channel to be used by the tuner.
 325    *
 326    * @param tunerId       The ID of the tuner.
 327    * @param sourceType    The source type to be used.
 328    * @param channelNumber The LCN (Logical Channel Number) of the channel.
 329    * @param callback      The callback object where either |notifyError| or
 330    *                      |notifySuccess| is expected.
 331    */
 332   void setChannel(in DOMString tunerId,
 333                   in DOMString sourceType,
 334                   in DOMString channelNumber,
 335                   in nsITVServiceCallback callback);
 336
 337   /**
 338    * Get the channels, ordered by the LCN (Logical Channel Number), of a given
 339    * source type.
 340    *
 341    * @param tunerId       The ID of the tuner.
 342    * @param sourceType    The source type to be used.
 343    * @param callback      The callback object where either |notifyError| or
 344    *                      |notifySuccess|, which takes an array of
 345    *                      |nsITVChannelData| ordered by the LCN (Logical Channel
 346    *                      Number), is expected.
 347    */
 348   void getChannels(in DOMString tunerId,
 349                    in DOMString sourceType,
 350                    in nsITVServiceCallback callback);
 351
 352   /**
 353    * Get the programs, ordered by the start time, of a given channel.
 354    *
 355    * @param tunerId       The ID of the tuner.
 356    * @param sourceType    The source type to be used.
 357    * @param channelNumber The LCN (Logical Channel Number) of the channel.
 358    * @param startTime     The begining of the searching time frame for programs.
 359    * @param endTime       The end of the searching time frame for programs.
 360    * @param callback      The callback object where either |notifyError| or
 361    *                      |notifySuccess|, which takes an array of
 362    *                      |nsITVProgramData| ordered by the start time, is
 363    *                      expected.
 364    */
 365   void getPrograms(in DOMString tunerId,
 366                    in DOMString sourceType,
 367                    in DOMString channelNumber,
 368                    in unsigned long long startTime,
 369                    in unsigned long long endTime,
 370                    in nsITVServiceCallback callback);
 371
 372   /**
 373    * Get the overlay ID of a given tuner.
 374    *
 375    * @param tunerId       The ID of the tuner.
 376    * @param callback      The callback object where either |notifyError| or
 377    *                      |notifySuccess|, which takes an array of
 378    *                      |nsISupportsString| with only one element, is expected.
 379    */
 380   void getOverlayId(in DOMString tunerId,
 381                     in nsITVServiceCallback callback);
 382 };