net.zer0bandwidth.android.lib.telephony

Class TelephonyController

java.lang.Object

net.zer0bandwidth.android.lib.telephony.TelephonyController

public class TelephonyController
extends java.lang.Object

Provides programmatic access to common call control tasks.

As an Instance

An instance of this class provides programmatic access to the Android OS internal telephony controller. This class is based on several interesting StackOverflow posts and is still highly experimental. The member functions represent a large portion of the ITelephony interface as discovered in the Android open source repository. However, in this class, several of those methods are marked as deprecated. For each of these deprecated methods, there is a static alternative that does not require the reflexive workarounds of this class, and which will likely be more efficient. Though marked as deprecated, there is no plan to remove them from this library; the deprecation is merely an encouragement to choose alternatives.

As a Static Utils Class

Static methods of the class are a more intuitive shorthand for "normal" operations related to call control, and do not require the construction of an instance.

Since:

zer0bandwidth-net/android 0.0.5 (#16)

See Also:

StackOverflow Q.599443: How to hang up outgoing call in Android?, StackOverflow Q.2001146: Reflection to access advanced telephony features, Prasanta Paul, "Call Control in Android", 2010-09-03, Android Source: com.android.internal.telephony.ITelephony, StackOverflow Q.4816683: How to make a phone call programmatically

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	LOG_TAG
protected java.lang.Class<?>	m_clsITelephony A persistent reflection into the Android internal telephony controller.
protected android.content.Context	m_ctx The context in which the controller operates.
protected java.lang.Object	m_mgrServices A persistent reference to the Android internal service manager.
protected java.lang.Object	m_mgrTelephony A persistent reference to the Android internal telephony controller.
static java.lang.String	SERVICE_MANAGER_CLASS
static java.lang.String	SERVICE_MANAGER_NATIVE_CLASS
static java.lang.String	TELEPHONY_INTERFACE

Constructor Summary

Constructors

Constructor and Description
TelephonyController(android.content.Context ctx) Initializes the controller in the given context.

Method Summary

Modifier and Type	Method and Description
void	answerRingingCall() Answers an incoming call.
void	answerRingingCallForSubscriber(int id) Answers an incoming call on behalf of a subscriber.
void	call(java.lang.String pkgCaller, java.lang.String sNumber) Deprecated. Use placeCall(android.content.Context, java.lang.String) instead.
void	dial(java.lang.String sNumber) Dials the specified number, but does not call it.
boolean	disableDataConnectivity() Disables the data connection over the cell radio.
protected java.lang.String	dumpDiscoveredMethods() Used to discover the actual definition of the ITelephony interface as visible to the current app.
boolean	enableDataConnectivity() Enables the data connection over the cell radio.
boolean	endCall() Terminates a call in progress.
boolean	endCallForSubscriber(int id) Terminates a call in progress on behalf of a subscriber.
static int	getCallState(android.content.Context ctx) Indicates the current call state.
int	getDataState() Deprecated. Use getDataState(Context) instead.
static int	getDataState(android.content.Context ctx) Indicates the current call state.
static android.telephony.TelephonyManager	getManager(android.content.Context ctx) Fetches an instance of the device's telephony manager.
protected TelephonyController	init() Initializes the member object that represents the Android telephony controller.
protected java.lang.Object	invoke(java.lang.String sMethod, java.lang.Class<?>[] aclsTypes, java.lang.Object[] aoParams) Standard method of reflectively invoking a method of the telephony manager.
boolean	isDataConnectivityPossible() Indicates whether the cell radio supports data connectivity.
static boolean	isIdle(android.content.Context ctx) Indicates whether the phone is in "idle" state — that is, no outbound or inbound calls are in progress.
boolean	isIdle(java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isIdle(Context) instead.
boolean	isIdleForSubscriber(int id, java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isIdle(Context) instead.
static boolean	isOffhook(android.content.Context ctx) Indicates whether the phone is "off-hook" — that is, waiting for a call to complete, or fully engaged with an active call.
boolean	isOffhook(java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isOffhook(Context) instead.
boolean	isOffhookForSubscriber(int id, java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isOffhook(Context) instead.
boolean	isRadioOn(java.lang.String pkgCaller) Indicates whether the cell radio is active.
boolean	isRadioOnForSubscriber(int id, java.lang.String pkgCaller) Indicates whether the cell radio is active.
static boolean	isRinging(android.content.Context ctx) Indicates whether there is currently an incoming call that is causing either a ring tone or a call waiting tone.
boolean	isRinging(java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isRinging(Context) instead.
boolean	isRingingForSubscriber(int id, java.lang.String pkgCaller) Deprecated. Use getCallState(android.content.Context) or isRinging(Context) instead.
static void	placeCall(android.content.Context ctx, java.lang.String sNumber) Places an outbound call to the specified telephone number.
boolean	setRadio(boolean bEnabled) Sets the cell radio on or off.
void	silenceRinger() Silences the ringer if an incoming call is ringing.
boolean	supplyPin(java.lang.String sPIN) Supply a PIN to unlock the phone's SIM card.
boolean	supplyPinForSubscriber(int id, java.lang.String sPIN) Supply a PIN to unlock the phone's SIM card.
boolean	supplyPuk(java.lang.String sPUK, java.lang.String sPIN) Supply a PUK (Personal Unlocking Key) to unlock the SIM and set its PIN to a new value.
boolean	supplyPukForSubscriber(int id, java.lang.String sPUK, java.lang.String sPIN) Supply a PUK (Personal Unlocking Key) to unlock the SIM and set its PIN to a new value.
void	toggleRadio() Toggles the state of the cell radio.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOG_TAG

public static final java.lang.String LOG_TAG

SERVICE_MANAGER_CLASS

public static final java.lang.String SERVICE_MANAGER_CLASS

See Also:

Constant Field Values

SERVICE_MANAGER_NATIVE_CLASS

public static final java.lang.String SERVICE_MANAGER_NATIVE_CLASS

See Also:

Constant Field Values

TELEPHONY_INTERFACE

public static final java.lang.String TELEPHONY_INTERFACE

See Also:

Constant Field Values

m_ctx

protected android.content.Context m_ctx

The context in which the controller operates. Must be supplied in the constructor, and cannot be null.

m_mgrServices

protected java.lang.Object m_mgrServices

A persistent reference to the Android internal service manager.

m_clsITelephony

protected java.lang.Class<?> m_clsITelephony

A persistent reflection into the Android internal telephony controller.

m_mgrTelephony

protected java.lang.Object m_mgrTelephony

A persistent reference to the Android internal telephony controller. Member methods in this class will consume its interface via reflection.

Constructor Detail

TelephonyController

public TelephonyController(android.content.Context ctx)
                    throws ControllerConstructionException

Initializes the controller in the given context.

Parameters:

ctx - the context in which the controller will operate

Throws:

ControllerConstructionException - if any failures occur under the hood

See Also:

init()

Method Detail

getManager

public static android.telephony.TelephonyManager getManager(android.content.Context ctx)

Fetches an instance of the device's telephony manager. As of 0.2.0, this is merely an alias for Managers.get(android.content.Context, java.lang.Class<MGR>) with the appropriate class selected.

Parameters:

ctx - the context in which services are available

Returns:

the device's telephony manager service

getCallState

public static int getCallState(android.content.Context ctx)
                        throws java.lang.SecurityException

Indicates the current call state. Equivalent to calling TelephonyManager.getCallState() on an existing instance of the manager. This method requires the android.permission.READ_PHONE_STATE permission, and will throw a SecurityException if the permission is not granted at runtime.

Parameters:

ctx - the context in which to check call state

Returns:

one of the call state indicators provided by TelephonyManager: CALL_STATE_RINGING, CALL_STATE_OFFHOOK, or CALL_STATE_IDLE

Throws:

java.lang.SecurityException - if the android.permission.READ_PHONE_STATE permission is not granted to the app at runtime

isIdle

public static boolean isIdle(android.content.Context ctx)
                      throws java.lang.SecurityException

Indicates whether the phone is in "idle" state — that is, no outbound or inbound calls are in progress.

Parameters:

ctx - the context in which to check call state

Returns:

true if the call state is "idle"

Throws:

java.lang.SecurityException - if the android.permission.READ_PHONE_STATE permission is not granted to the app at runtime

isOffhook

public static boolean isOffhook(android.content.Context ctx)
                         throws java.lang.SecurityException

Indicates whether the phone is "off-hook" — that is, waiting for a call to complete, or fully engaged with an active call.

Parameters:

ctx - the context in which to check call state

Returns:

true if the call state is "off-hook"

Throws:

java.lang.SecurityException - if the android.permission.READ_PHONE_STATE permission is not granted to the app at runtime

isRinging

public static boolean isRinging(android.content.Context ctx)
                         throws java.lang.SecurityException

Indicates whether there is currently an incoming call that is causing either a ring tone or a call waiting tone.

Parameters:

ctx - the context in which to check call state

Returns:

true if the call state is "ringing"

Throws:

java.lang.SecurityException - if the android.permission.READ_PHONE_STATE permission is not granted to the app at runtime

getDataState

public static int getDataState(android.content.Context ctx)

Indicates the current call state. Equivalent to calling TelephonyManager.getDataState() on an existing instance of the manager.

Parameters:

ctx - the context in which to check data state

Returns:

one of the data state indicators provided by TelephonyManager: TelephonyManager.DATA_DISCONNECTED, TelephonyManager.DATA_CONNECTING, TelephonyManager.DATA_CONNECTED, or TelephonyManager.DATA_SUSPENDED

placeCall

public static void placeCall(android.content.Context ctx,
                             java.lang.String sNumber)
                      throws java.lang.SecurityException

Places an outbound call to the specified telephone number. This method requires the android.permission.CALL_PHONE permission, and will throw a SecurityException if the permission is not granted at runtime.

Parameters:

ctx - the context in which to initiate the call

sNumber - a telephone number

Throws:

java.lang.SecurityException - if the android.permission.CALL_PHONE permission is not granted to the app at runtime

See Also:

PermissionCheckpoint.checkPermission(android.content.Context, java.lang.String)

init

protected TelephonyController init()
                            throws java.lang.ClassNotFoundException,
                                   java.lang.NoSuchMethodException,
                                   java.lang.IllegalAccessException,
                                   java.lang.reflect.InvocationTargetException

Initializes the member object that represents the Android telephony controller.

Returns:

(fluid)

Throws:

java.lang.ClassNotFoundException - if any of the various classes cannot be found via reflection

java.lang.NoSuchMethodException - if any of the various methods cannot be found via reflection

java.lang.IllegalAccessException - if a method invocation is forbidden

java.lang.reflect.InvocationTargetException - if a method cannot be invoked

dumpDiscoveredMethods

protected java.lang.String dumpDiscoveredMethods()

Used to discover the actual definition of the ITelephony interface as visible to the current app.

Returns:

the dumped methods (since 0.2.1/#53)

Since:

zer0bandwidth-net/android 0.0.6 (#17)

invoke

protected java.lang.Object invoke(java.lang.String sMethod,
                                  java.lang.Class<?>[] aclsTypes,
                                  java.lang.Object[] aoParams)
                           throws ControllerInvocationException

Standard method of reflectively invoking a method of the telephony manager.

Parameters:

sMethod - the name of the underlying method being invoked

aclsTypes - an array of parameter types, corresponding to the parameters given in aoParams (since zer0bandwidth-net/android 0.0.6 (#17))

aoParams - any parameters that would be passed to the underlying method, corresponding to the types given in aclsTypes (since zer0bandwidth-net/android 0.0.6 (#17))

Returns:

the return value of the underlying method

Throws:

ControllerInvocationException - if the invocation fails

answerRingingCall

public void answerRingingCall()
                       throws ControllerInvocationException

Answers an incoming call.

Throws:

ControllerInvocationException - if the invocation fails

answerRingingCallForSubscriber

public void answerRingingCallForSubscriber(int id)

Answers an incoming call on behalf of a subscriber.

Parameters:

id - the subscriber ID

Throws:

ControllerInvocationException - if the invocation fails

call

public void call(java.lang.String pkgCaller,
                 java.lang.String sNumber)
          throws ControllerInvocationException

Deprecated. Use placeCall(android.content.Context, java.lang.String) instead.

Dials the specified number and initiates an outbound call.

Parameters:

pkgCaller - the code package that is requesting the call

sNumber - the target phone number

Throws:

ControllerInvocationException - if the invocation fails

dial

public void dial(java.lang.String sNumber)
          throws ControllerInvocationException

Dials the specified number, but does not call it.

Parameters:

sNumber - the target phone number

Throws:

ControllerInvocationException - if the invocation fails

disableDataConnectivity

public boolean disableDataConnectivity()
                                throws ControllerInvocationException

Disables the data connection over the cell radio.

Returns:

(undocumented) indicates success?

Throws:

ControllerInvocationException - if the invocation fails

enableDataConnectivity

public boolean enableDataConnectivity()
                               throws ControllerInvocationException

Enables the data connection over the cell radio.

Returns:

(undocumented) indicates success?

Throws:

ControllerInvocationException - if the invocation fails

endCall

public boolean endCall()
                throws ControllerInvocationException

Terminates a call in progress.

Returns:

an indication of whether the call actually hung up

Throws:

ControllerInvocationException - if the invocation fails

endCallForSubscriber

public boolean endCallForSubscriber(int id)
                             throws ControllerInvocationException

Terminates a call in progress on behalf of a subscriber.

Parameters:

id - the subscriber ID

Returns:

an indication of whether the call actually hung up

Throws:

ControllerInvocationException - if the invocation fails

getDataState

public int getDataState()
                 throws ControllerInvocationException

Deprecated. Use getDataState(Context) instead.

Indicates the state of the data connection.

Returns:

(undocumented)

Throws:

ControllerInvocationException - if the invocation fails

isDataConnectivityPossible

public boolean isDataConnectivityPossible()
                                   throws ControllerInvocationException

Indicates whether the cell radio supports data connectivity.

Returns:

duh, consult name of method

Throws:

ControllerInvocationException - if the invocation fails

isIdle

public boolean isIdle(java.lang.String pkgCaller)
               throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isIdle(Context) instead.

Indicates whether the phone is in "idle" state — that is, no outbound or inbound calls are in progress.

Parameters:

pkgCaller - the code package making the inquiry

Returns:

true if the phone state is "idle"

Throws:

ControllerInvocationException - if the invocation fails

isIdleForSubscriber

public boolean isIdleForSubscriber(int id,
                                   java.lang.String pkgCaller)
                            throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isIdle(Context) instead.

Indicates whether the phone is in "idle" state — that is, no outbound or inbound calls are in progress.

Parameters:

id - the subscriber ID

pkgCaller - the code package making the inquiry

Returns:

true if the phone state is "idle"

Throws:

ControllerInvocationException - if the invocation fails

isOffhook

public boolean isOffhook(java.lang.String pkgCaller)
                  throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isOffhook(Context) instead.

Indicates whether the phone is "off-hook" — that is, waiting for a call to complete, or fully engaged with an active call

Parameters:

pkgCaller - the code package that is requesting the function

Returns:

true if the phone state is "off-hook"

Throws:

ControllerInvocationException - if the invocation fails

isOffhookForSubscriber

public boolean isOffhookForSubscriber(int id,
                                      java.lang.String pkgCaller)
                               throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isOffhook(Context) instead.

Indicates whether the phone is "off-hook" — that is, waiting for a call to complete, or fully engaged with an active call

Parameters:

id - the subscriber ID

pkgCaller - the code package making the inquiry

Returns:

true if the phone state is "off-hook"

Throws:

ControllerInvocationException - if the invocation fails

isRadioOn

public boolean isRadioOn(java.lang.String pkgCaller)
                  throws ControllerInvocationException

Indicates whether the cell radio is active.

Parameters:

pkgCaller - the code package making the inquiry

Returns:

true if the cell radio is active

Throws:

ControllerInvocationException - if the invocation fails

isRadioOnForSubscriber

public boolean isRadioOnForSubscriber(int id,
                                      java.lang.String pkgCaller)
                               throws ControllerInvocationException

Indicates whether the cell radio is active.

Parameters:

id - the subscriber ID

pkgCaller - the code package making the inquiry

Returns:

true if the cell radio is active

Throws:

ControllerInvocationException - if the invocation fails

isRinging

public boolean isRinging(java.lang.String pkgCaller)
                  throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isRinging(Context) instead.

Indicates whether there is currently an incoming call that is causing either a ring tone or a call waiting tone.

Parameters:

pkgCaller - the code package making the inquiry

Returns:

true if the phone state is "ringing"

Throws:

ControllerInvocationException - if the invocation fails

isRingingForSubscriber

public boolean isRingingForSubscriber(int id,
                                      java.lang.String pkgCaller)
                               throws ControllerInvocationException

Deprecated. Use getCallState(android.content.Context) or isRinging(Context) instead.

Indicates whether there is currently an incoming call that is causing either a ring tone or a call waiting tone.

Parameters:

id - the subscriber ID

pkgCaller - the code package making the inquiry

Returns:

true if the phone state is "ringing"

Throws:

ControllerInvocationException - if the invocation fails

setRadio

public boolean setRadio(boolean bEnabled)
                 throws ControllerInvocationException

Sets the cell radio on or off.

Parameters:

bEnabled - true to enable; false to disable

Returns:

(undocumented)

Throws:

ControllerInvocationException - if the invocation fails

silenceRinger

public void silenceRinger()
                   throws ControllerInvocationException

Silences the ringer if an incoming call is ringing. Also silences the vibrator.

Throws:

ControllerInvocationException - if the invocation fails

supplyPin

public boolean supplyPin(java.lang.String sPIN)
                  throws ControllerInvocationException

Supply a PIN to unlock the phone's SIM card.

Parameters:

sPIN - the PIN to be checked

Returns:

indicates whether the operation succeeded

Throws:

ControllerInvocationException - if the invocation fails

supplyPinForSubscriber

public boolean supplyPinForSubscriber(int id,
                                      java.lang.String sPIN)
                               throws ControllerInvocationException

Supply a PIN to unlock the phone's SIM card.

Parameters:

id - the subscriber ID

sPIN - the PIN to be checked

Returns:

indicates whether the operation succeeded

Throws:

ControllerInvocationException - if the invocation fails

supplyPuk

public boolean supplyPuk(java.lang.String sPUK,
                         java.lang.String sPIN)
                  throws ControllerInvocationException

Supply a PUK (Personal Unlocking Key) to unlock the SIM and set its PIN to a new value.

Parameters:

sPUK - the unlock key

sPIN - the new PIN to set

Returns:

indicates whether the operation succeeded

Throws:

ControllerInvocationException - if the invocation fails

supplyPukForSubscriber

public boolean supplyPukForSubscriber(int id,
                                      java.lang.String sPUK,
                                      java.lang.String sPIN)
                               throws ControllerInvocationException

Supply a PUK (Personal Unlocking Key) to unlock the SIM and set its PIN to a new value.

Parameters:

id - the subscriber ID

sPUK - the unlock key

sPIN - the new PIN to set

Returns:

indicates whether the operation succeeded

Throws:

ControllerInvocationException - if the invocation fails

toggleRadio

public void toggleRadio()
                 throws ControllerInvocationException

Toggles the state of the cell radio.

Throws:

ControllerInvocationException - if the invocation fails