michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: interface FMRadio : EventTarget {
michael@0:   /* Indicates if the FM radio is enabled. */
michael@0:   readonly attribute boolean enabled;
michael@0: 
michael@0:   /* Indicates if the antenna is plugged and available. */
michael@0:   readonly attribute boolean antennaAvailable;
michael@0: 
michael@0:   /**
michael@0:    * Current frequency in MHz. The value will be null if the FM radio is
michael@0:    * disabled.
michael@0:    */
michael@0:   readonly attribute double? frequency;
michael@0: 
michael@0:   /* The upper bound of frequency in MHz. */
michael@0:   readonly attribute double frequencyUpperBound;
michael@0: 
michael@0:   /* The lower bound of frequency in MHz. */
michael@0:   readonly attribute double frequencyLowerBound;
michael@0: 
michael@0:   /**
michael@0:    * The difference in frequency between two "adjacent" channels, in MHz. That
michael@0:    * is, any two radio channels' frequencies differ by at least channelWidth
michael@0:    * MHz. Usually, the value is one of:
michael@0:    *  - 0.05 MHz
michael@0:    *  - 0.1  MHz
michael@0:    *  - 0.2  MHz
michael@0:    */
michael@0:   readonly attribute double channelWidth;
michael@0: 
michael@0:   /* Fired when the FM radio is enabled. */
michael@0:   attribute EventHandler onenabled;
michael@0: 
michael@0:   /* Fired when the FM radio is disabled. */
michael@0:   attribute EventHandler ondisabled;
michael@0: 
michael@0:   /**
michael@0:    * Fired when the antenna becomes available or unavailable, i.e., fired when
michael@0:    * the antennaAvailable attribute changes.
michael@0:    */
michael@0:   attribute EventHandler onantennaavailablechange;
michael@0: 
michael@0:   /* Fired when the FM radio's frequency is changed. */
michael@0:   attribute EventHandler onfrequencychange;
michael@0: 
michael@0:   /**
michael@0:    * Power the FM radio off. The disabled event will be fired if this request
michael@0:    * completes successfully.
michael@0:    */
michael@0:   DOMRequest disable();
michael@0: 
michael@0:   /**
michael@0:    * Power the FM radio on, and tune the radio to the given frequency in MHz.
michael@0:    * This will fail if the given frequency is out of range. The enabled event
michael@0:    * and frequencychange event will be fired if this request completes
michael@0:    * successfully.
michael@0:    */
michael@0:   DOMRequest enable(double frequency);
michael@0: 
michael@0:   /**
michael@0:    * Tune the FM radio to the given frequency. This will fail if the given
michael@0:    * frequency is out of range.
michael@0:    *
michael@0:    * Note that the FM radio may not tuned to the exact frequency given. To get
michael@0:    * the frequency the radio is actually tuned to, wait for the request to fire
michael@0:    * sucess (or wait for the frequencychange event to fire), and then read the
michael@0:    * frequency attribute.
michael@0:    */
michael@0:   DOMRequest setFrequency(double frequency);
michael@0: 
michael@0:   /**
michael@0:    * Tell the FM radio to seek up to the next channel. If the frequency is
michael@0:    * successfully changed, the frequencychange event will be triggered.
michael@0:    *
michael@0:    * Only one seek is allowed at once: If the radio is seeking when the seekUp
michael@0:    * is called, error will be fired.
michael@0:    */
michael@0:   DOMRequest seekUp();
michael@0: 
michael@0:   /**
michael@0:    * Tell the FM radio to seek down to the next channel. If the frequency is
michael@0:    * successfully changed, the frequencychange event will be triggered.
michael@0:    *
michael@0:    * Only one seek is allowed at once: If the radio is seeking when the
michael@0:    * seekDown is called, error will be fired.
michael@0:    */
michael@0:   DOMRequest seekDown();
michael@0: 
michael@0:   /**
michael@0:    * Cancel the seek action. If the radio is not currently seeking up or down,
michael@0:    * error will be fired.
michael@0:    */
michael@0:   DOMRequest cancelSeek();
michael@0: };
michael@0: