gecko-dev/dom/telephony/nsITelephonyService.idl

/* 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"

interface nsIMobileCallForwardingOptions;

[scriptable, uuid(464d4cf8-454a-4cdb-9329-bfe7ede97103)]
interface nsITelephonyListener : nsISupports
{
  /**
   * Notified when a telephony call changes state.
   *
   * @param clientId
            Indicate the RIL client, 0 ~ (number of client - 1).
   * @param callIndex
   *        Call identifier assigned by the RIL.
   * @param callState
   *        One of the nsITelephonyService::CALL_STATE_* values.
   * @param number
   *        Number of the other party.
   * @param numberPresentation
   *        Presentation of the call number.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   * @param name
   *        Name of the other party.
   * @param namePresentation
   *        Presentation of the call name.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   * @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.
   * @param isSwitchable
   *        Indicates whether this call can be switched between states of
   *        nsITelephonyService::CALL_STATE_CONNECTED and
   *        nsITelephonyService::CALL_STATE_HELD.
   * @param isMergeable
   *        Indicates whether this call be be added into a conference.
   */
  void callStateChanged(in unsigned long clientId,
                        in unsigned long callIndex,
                        in unsigned short callState,
                        in AString number,
                        in unsigned short numberPresentation,
                        in AString name,
                        in unsigned short namePresentation,
                        in boolean isOutgoing,
                        in boolean isEmergency,
                        in boolean isConference,
                        in boolean isSwitchable,
                        in boolean isMergeable);

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

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

  /**
   * Called when nsITelephonyService is asked to enumerate the current
   * telephony call state (nsITelephonyService::enumerateCalls). This is
   * called once per call that is currently managed by the RIL.
   *
   * @param clientId
            Indicate the RIL client, 0 ~ (number of client - 1).
   * @param callIndex
   *        Call identifier assigned by the RIL.
   * @param callState
   *        One of the nsITelephonyService::CALL_STATE_* values.
   * @param number
   *        Number of the other party.
   * @param numberPresentation
   *        Presentation of the call number.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   * @param name
   *        Name of the other party.
   * @param namePresentation
   *        Presentation of the call name.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   * @param isOutgoing
   *        Indicates whether this call is outgoing or incoming.
   * @param isConference
   *        Indicates whether this call is a conference call.
   * @param isSwitchable
   *        Indicates whether this call can be switched between states of
   *        nsITelephonyService::CALL_STATE_CONNECTED and
   *        nsITelephonyService::CALL_STATE_HELD.
   * @param isMergeable
   *        Indicates whether this call be be added into a conference.
   */
  void enumerateCallState(in unsigned long clientId,
                          in unsigned long callIndex,
                          in unsigned short callState,
                          in AString number,
                          in unsigned short numberPresentation,
                          in AString name,
                          in unsigned short namePresentation,
                          in boolean isOutgoing,
                          in boolean isEmergency,
                          in boolean isConference,
                          in boolean isSwitchable,
                          in boolean isMergeable);

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

  /**
   * Called when RIL error occurs.
   *
   * @param clientId
            Indicate the RIL client, 0 ~ (number of client - 1).
   * @param callIndex
   *        Call identifier assigned by the RIL. -1 if no connection
   * @param error
   *        Error from RIL.
   */
  void notifyError(in unsigned long clientId,
                   in long callIndex,
                   in AString error);

  /**
   * Called when a waiting call comes in CDMA networks.
   *
   * @param clientId
            Indicate the RIL client, 0 ~ (number of client - 1).
   * @param number
   *        Number of the other party.
   * @param numberPresentation
   *        Presentation of the call number.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   * @param name
   *        Name of the other party.
   * @param namePresentation
   *        Presentation of the call name.
   *        One of the nsITelephonyProvider::CALL_PRESENTATION_* values.
   */
  void notifyCdmaCallWaiting(in unsigned long clientId,
                             in AString number,
                             in unsigned short numberPresentation,
                             in AString name,
                             in unsigned short namePresentation);

  /**
   * Called when RIL error occurs to creating or separating a conference call.
   *
   * @param name
   *        Error name. Possible values are addError and removeError.
   * @param message
   *        Detailed error message from RIL.
   */
  void notifyConferenceError(in AString name,
                             in AString message);
};

/**
 * A callback interface for handling asynchronous response.
 */
[scriptable, uuid(cffc3f9d-2c88-4a14-8ebc-f216caf0cc1d)]
interface nsITelephonyCallback : nsISupports
{
  void notifySuccess();
  void notifyError(in AString error);
};

/**
 * A callback interface for handling asynchronous response for telephony.dial.
 */
[scriptable, uuid(e16c6e6f-93c6-4e1e-99bf-592b98f67e15)]
interface nsITelephonyDialCallback : nsITelephonyCallback
{
  /**
   * Called when a dial request is treated as an MMI code and it is about to
   * process the request.
   *
   * @param serviceCode
   *        MMI service code key string that defined in MMI_KS_SC_*
   */
  void notifyDialMMI(in AString serviceCode);

  /**
   * Called when a dial request is treated as a call setup and the result
   * succeeds.
   *
   * @param clientId
            Indicate the RIL client, 0 ~ (number of client - 1).
   * @param callIndex
   *        Call index from RIL.
   * @param number
   *        Dialed out phone number (ex: Temporary CLIR prefix will be removed)
   */
  void notifyDialCallSuccess(in unsigned long cliendId,
                             in unsigned long callIndex,
                             in AString number);

  /**
   * Called when a MMI code request succeeds.
   * The function should only be called after notifyDialMMI.
   */
  void notifyDialMMISuccess(in AString statusMessage);
  void notifyDialMMISuccessWithInteger(in AString statusMessage,
                                       in unsigned short aAdditionalInformation);
  void notifyDialMMISuccessWithStrings(in AString statusMessage,
                                       in unsigned long aLength,
                                       [array, size_is(aLength)] in wstring aAdditionalInformation);
  void notifyDialMMISuccessWithCallForwardingOptions(in AString statusMessage,
                                                     in unsigned long aLength,
                                                     [array, size_is(aLength)] in nsIMobileCallForwardingOptions aAdditionalInformation);

  /**
   * Called when a MMI code request fails.
   * The function should only be called after notifyDialMMI.
   */
  void notifyDialMMIError(in AString error);
  void notifyDialMMIErrorWithInfo(in AString error, in unsigned short info);
};

%{C++
#define TELEPHONY_SERVICE_CID \
  { 0x9cf8aa52, 0x7c1c, 0x4cde, { 0x97, 0x4e, 0xed, 0x2a, 0xa0, 0xe7, 0x35, 0xfa } }
#define TELEPHONY_SERVICE_CONTRACTID \
  "@mozilla.org/telephony/telephonyservice;1"
%}

/**
 * XPCOM component (in the content process) that provides the telephony
 * information.
 */
[scriptable, uuid(a91fa6be-0acc-4d36-99f1-3e3a88e83ae9)]
interface nsITelephonyService : 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;

  const unsigned short CALL_PRESENTATION_ALLOWED = 0;
  const unsigned short CALL_PRESENTATION_RESTRICTED = 1;
  const unsigned short CALL_PRESENTATION_UNKNOWN = 2;
  const unsigned short CALL_PRESENTATION_PAYPHONE = 3;

  readonly attribute unsigned long defaultServiceId;

  /**
   * 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 registerListener(in nsITelephonyListener listener);
  void unregisterListener(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 unsigned long clientId, in DOMString number,
            in boolean isEmergency, in nsITelephonyDialCallback callback);

  void sendTones(in unsigned long clientId, in DOMString dtmfChars,
                 in unsigned long pauseDuration, in unsigned long toneDuration,
                 in nsITelephonyCallback callback);

  void startTone(in unsigned long clientId, in DOMString dtmfChar);
  void stopTone(in unsigned long clientId);

  void answerCall(in unsigned long clientId,
                  in unsigned long callIndex,
                  in nsITelephonyCallback callback);
  void rejectCall(in unsigned long clientId,
                  in unsigned long callIndex,
                  in nsITelephonyCallback callback);
  void hangUpCall(in unsigned long clientId,
                  in unsigned long callIndex,
                  in nsITelephonyCallback callback);
  void holdCall(in unsigned long clientId,
                in unsigned long callIndex,
                in nsITelephonyCallback callback);
  void resumeCall(in unsigned long clientId,
                  in unsigned long callIndex,
                  in nsITelephonyCallback callback);

  void conferenceCall(in unsigned long clientId);
  void separateCall(in unsigned long clientId, in unsigned long callIndex);
  void hangUpConference(in unsigned long clientId,
                        in nsITelephonyCallback callback);
  void holdConference(in unsigned long clientId);
  void resumeConference(in unsigned long clientId);

  /**
   * Send an USSD on existing session. It results in error if the session is
   * not existed.
   *
   * If successful, callback.notifySuccess() will be called.
   * Otherwise, callback.notifyError() will be called.
   */
  void sendUSSD(in unsigned long clientId, in DOMString ussd,
                in nsITelephonyCallback callback);

  /**
   * Cancel an existing USSD session.
   *
   * If successful, callback.notifySuccess() will be called.
   * Otherwise, callback.notifyError() will be called.
   */
  void cancelUSSD(in unsigned long cliendId, in nsITelephonyCallback callback);

  attribute bool microphoneMuted;
  attribute bool speakerEnabled;
};

%{C++
template<typename T> struct already_AddRefed;

already_AddRefed<nsITelephonyService>
NS_CreateTelephonyService();
%}