/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

[scriptable, uuid(37fde795-7ff4-40fd-925b-3ebc07ba0cd1)]
interface nsITelephonyListener : nsISupports
{
  /**
   * Notified when a telephony call changes state.
   *
   * @param callIndex
   *        Call identifier assigned by the RIL.
   * @param callState
   *        One of the nsITelephonyProvider::CALL_STATE_* values.
   * @param number
   *        Number of the other party.
   * @param isActive
   *        Indicates whether this call is the currently active one.
   * @param isOutgoing
   *        Indicates whether this call is outgoing or incoming.
   * @param isEmergency
   *        Indicates whether this call is an emergency call.
   */
  void callStateChanged(in unsigned long callIndex,
                        in unsigned short callState,
                        in AString number,
                        in boolean isActive,
                        in boolean isOutgoing,
                        in boolean isEmergency);

  /**
   * Called when enumeration asked by nsITelephonyProvider::enumerateCalls
   * is completed.
   */
  void enumerateCallStateComplete();

  /**
   * Called when nsITelephonyProvider is asked to enumerate the current
   * telephony call state (nsITelephonyProvider::enumerateCalls). This is
   * called once per call that is currently managed by the RIL.
   *
   * @param callIndex
   *        Call identifier assigned by the RIL.
   * @param callState
   *        One of the nsITelephonyProvider::CALL_STATE_* values.
   * @param number
   *        Number of the other party.
   * @param isActive
   *        Indicates whether this call is the active one.
   * @param isOutgoing
   *        Indicates whether this call is outgoing or incoming.
   *
   * @return true to continue enumeration or false to cancel.
   */
  boolean enumerateCallState(in unsigned long callIndex,
                             in unsigned short callState,
                             in AString number,
                             in boolean isActive,
                             in boolean isOutgoing,
                             in boolean isEmergency);

  /**
   * Called when RIL error occurs.
   *
   * @param callIndex
   *        Call identifier assigned by the RIL. -1 if no connection
   * @param error
   *        Error from RIL.
   */
  void notifyError(in long callIndex,
                   in AString error);
};

/**
 * XPCOM component (in the content process) that provides the telephony
 * information.
 */
[scriptable, uuid(099e1d81-f247-4ebb-89d8-cd89dd5f6ed4)]
interface nsITelephonyProvider : nsISupports
{
  const unsigned short CALL_STATE_UNKNOWN = 0;
  const unsigned short CALL_STATE_DIALING = 1;
  const unsigned short CALL_STATE_ALERTING = 2;
  const unsigned short CALL_STATE_CONNECTING = 3;
  const unsigned short CALL_STATE_CONNECTED = 4;
  const unsigned short CALL_STATE_HOLDING = 5;
  const unsigned short CALL_STATE_HELD = 6;
  const unsigned short CALL_STATE_RESUMING = 7;
  const unsigned short CALL_STATE_DISCONNECTING = 8;
  const unsigned short CALL_STATE_DISCONNECTED = 9;
  const unsigned short CALL_STATE_INCOMING = 10;

  /**
   * Called when a content process registers receiving unsolicited messages from
   * RadioInterfaceLayer in the chrome process. Only a content process that has
   * the 'telephony' permission is allowed to register.
   */
  void registerTelephonyMsg(in nsITelephonyListener listener);
  void unregisterTelephonyMsg(in nsITelephonyListener listener);

  /**
   * Will continue calling listener.enumerateCallState until the listener
   * returns false.
   */
  void enumerateCalls(in nsITelephonyListener listener);

  /**
   * Functionality for making and managing phone calls.
   */
  void dial(in DOMString number);
  void dialEmergency(in DOMString number);
  void hangUp(in unsigned long callIndex);

  void startTone(in DOMString dtmfChar);
  void stopTone();

  void answerCall(in unsigned long callIndex);
  void rejectCall(in unsigned long callIndex);
  void holdCall(in unsigned long callIndex);
  void resumeCall(in unsigned long callIndex);

  attribute bool microphoneMuted;
  attribute bool speakerEnabled;
};