/* 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(a5818719-e1b6-4fdc-8551-006055fa9996)]
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.
   * @param isConference
   *        Indicates whether this call is a conference call.
   */
  void callStateChanged(in unsigned long callIndex,
                        in unsigned short callState,
                        in AString number,
                        in boolean isActive,
                        in boolean isOutgoing,
                        in boolean isEmergency,
                        in boolean isConference);

  /**
   * Called when participants of a conference call have been updated, and the
   * conference call state changes.
   *
   * @param callState
   *        Possible values are: nsITelephonyProvider::CALL_STATE_UNKNOWN,
   *        nsITelephonyProvider::CALL_STATE_HELD,
   *        nsITelephonyProvider::CALL_STATE_CONNECTED.
   */
  void conferenceCallStateChanged(in unsigned short callState);

  /**
   * 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.
   * @param isConference
   *        Indicates whether this call is a conference call.
   * @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,
                             in boolean isConference);

  /**
   * Notify when RIL receives supplementary service notification.
   *
   * @param callIndex
   *        Call identifier assigned by the RIL. -1 if not specified
   * @param notification
   *        One of the nsITelephonyProvider::NOTIFICATION_* values.
   */
  void supplementaryServiceNotification(in long callIndex,
                                        in unsigned short notification);

  /**
   * 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);

  /**
   * Called when a waiting call comes in CDMA networks.
   *
   * @param number
   *        Number of the other party.
   */
  void notifyCdmaCallWaiting(in AString number);
};

/**
 * XPCOM component (in the content process) that provides the telephony
 * information.
 */
[scriptable, uuid(45a2f856-4e07-499a-94c6-624f90c3345b)]
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;

  const unsigned short NOTIFICATION_REMOTE_HELD = 0;
  const unsigned short NOTIFICATION_REMOTE_RESUMED = 1;

  /**
   * 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);

  void conferenceCall();
  void separateCall(in unsigned long callIndex);
  void holdConference();
  void resumeConference();

  attribute bool microphoneMuted;
  attribute bool speakerEnabled;
};