Using Android Telephony APIs

Working with Telephony Utilities The Android SDK provides a number of useful utilities for applications to integrate phone features available on the device. Generally speaking, developers should consider an Android device first and foremost as a phone.Although these devices might also run applications, phone operations generally take precedence.Your application should not interrupt a phone conversation, for example.To avoid this kind of behavior, your application should know something about what the user is doing, so that it can react differently. For instance, an application might query the state of the phone and determine that the user is talking on the phone and then choose to vibrate instead of play an alarm. In other cases, applications might need to place a call or send a text message. Phones typically support a Short Message Service (SMS), which is popular for texting (text messaging). Enabling the capability to leverage this feature from an application can enhance the appeal of the application and add features that can’t be easily replicated on a desktop environment. Because many Android devices are phones, applications frequently deal with phone numbers and the contacts database; some might want to access the phone dialer to place calls or check phone status information.Adding telephony features to an application enables a more integrated user experience and enhances the overall value of the application to the users. 

Gaining Permission to Access Phone State Information

Let’s begin by looking at how to determine telephony state of the device, including the ability to request the hook state of the phone, information of the phone service, and utilities for handling and verifying phone numbers.The TelephonyManager object within the android.telephony package is a great place to start. Many of the method calls in this section require explicit permission set with the Android application manifest file.The READ_PHONE_STATE permission is required to retrieve information such as the call state, handset phone number, and device identifiers or serial numbers.The ACCESS_COARSE_LOCATION permission is required for cellular location information. Recall that we cover location-based services in detail in Chapter 14,“Using Location-Based Services (LBS) APIs.” The following block of XML is typically needed in your application’s AndroidManifest.xml file to access basic phone state information: Requesting Call State You can use the TelephonyManager object to retrieve the state of the phone and some information about the phone service itself, such as the phone number of the handset. You can request an instance of TelephonyManager using the getSystemService() method, like this: TelephonyManager telManager = (TelephonyManager) getSystemService(Context.TELEPHONY_SERVICE); With a valid TelephonyManager instance, an application can now make several queries. One important method is getCallState().This method can determine the voice call status of the handset.The following block of code shows how to query for the call state and all the possible return values: int callStatus = telManager.getCallState(); String callState = null; switch (callStatus) { case TelephonyManager.CALL_STATE_IDLE: callState = “Phone is idle.”; break; case TelephonyManager.CALL_STATE_OFFHOOK: callState = “Phone is in use.”; break; case TelephonyManager.CALL_STATE_RINGING: callState = “Phone is ringing!”; break; } Log.i(“telephony”, callState);

Requesting Service Information

In addition to call and service state information, your application can retrieve other information about the device.This information is less useful for the typical application but can diagnose problems or provide specialized services available only from certain provider networks.The following code retrieves several pieces of service information: String opName = telManager.getNetworkOperatorName(); Log.i(“telephony”, “operator name = “ + opName); String phoneNumber = telManager.getLine1Number(); Log.i(“telephony”, “phone number = “ + phoneNumber); String providerName = telManager.getSimOperatorName(); Log.i(“telephony”, “provider name = “ + providerName); The network operator name is the descriptive name of the current provider that the handset connects to.This is typically the current tower operator.The SIM operator name is typically the name of the provider that the user is subscribed to for service.The phone number for this application programming interface (API) is defined as the MSISDN, typically the directory number of a GSM handset (that is, the number someone would dial to reach that particular phone).