Integrating with Android Services

Introduction  Android has numerous built-in functionality that can be called from within your applications  SMS/MMS  Telephony (calls)  GPRS/3G  WIFI  These functions can be seamlessly integrated into your apps  Due to the use of Intents

Permissions  Just like with earlier topics requiring file system access many built-in functions require the use of permissions  These are needed to inform the user what sort of features an application requires  Very important if you download apps, e.g. from the Android Market

SMS

Basic SMS Concepts  Message types  Text (max 160 characters/message)  Binary (max 140 bytes/message)  Multi-part messages  if a message is too large it can be sent as several parts and reassembled at the destination  each part is a separate message with special information indicating the different parts form one whole message  Usually, only a maximum of 3 parts is recommended since parts can be lost in transit  If a part is lost, essentially the message is now useless

Basic SMS Concepts  Port number  a special value indication what type of application is going to use the message  e.g. sending vCard via SMS uses port 9204  Applications can define their own port number for their specific purposes

Overview  Android provides a means to access the phone’s SMS service  Applications can both send and receive SMS messages  Port-based messages are also supported on device  Sending of ported and non-ported sms is supported  However, the emulator does not properly handle receiving port-based SMS (they never arrive)  Non-port based messages are properly handled  They can be received with no problem

Permissions  To be able to access SMS you need to make sure the following permissions are placed in your AndroidManifest.xml  For sending:  For receiving:

Sending SMS  To send SMS on Android you need to use the following classes  SmsManager  PendingIntent

SmsManager  SmsManager is a system class that holds the instance referencing the phone’s SMS system  android.telephony.SmsManager  You do not create instances of this class; it is a singleton  You refer to this instance using the static getDefault() method

SmsManager  SmsManager has several methods for sending SMS  Each is used for specific circumstances  sendTextMessage(String destinationAddress, String scAddress, String text, PendingIntent sen tIntent, PendingIntent deliveryIntent) sendTextMessageString PendingIntent  Send a text based SMS.  sendMultipartTextMessage(String destinationAddress, String scAddress, ArrayList parts, ArrayList sentIntents, ArrayList deliveryIntents) sendMultipartTextMessageString ArrayListStringArrayListPendingIntentArrayListPendingIntent  Send a multi-part text based SMS.  sendDataMessage(String destinationAddress, String scAddress, short destinationPort, byte[] data, PendingIntent sentIntent, PendingIntent deliveryIntent) sendDataMessageString PendingIntent  Send a data based SMS to a specific application port

Simple sending  The simplest way to send a message is to use sendTextMessage()  It makes the assumption that the message is at most 160 characters long  Anything beyond that will be truncated and lost

sendTextMessage()  sendTextMessage has several parameters: sendTextMessage  String destinationAddress – phone number to send to String  String scAddress – smsc address (usually null) String  String text – message that will be sent String  PendingIntent sentIntent – intent that will be triggered when the message is sent PendingIntent  PendingIntent deliveryIntent – intent that will be triggered when the message is delivered PendingIntent

PendingIntent  A PendingIntent is a special kind of intent in that it is deferred  The intent is triggered after a specific condition is met  E.g. when message is sent or delivered  There are two ways of getting PendingIntents used for SMS  PendingIntent.getActivity()  PendingIntent.getBroadcast()

PendingIntent.getActivity()  This is used to signal that you want to open a specific activity when this PendingIntent is triggered  This method has several parameters  Context - The Context in which this PendingIntent should start the activity.  requestCode - (currently not used).  intent - Intent of the activity to be launched.  flags - any of the flags as supported by Intent.fillIn() to control which unspecified parts of the intent that can be supplied when the actual send happens (usually just 0)Intent.fillIn()

Example NOTE: the intent used will be triggered using startActivity() with this being the context for the activity PendingIntent pi = PendingIntent.getActivity(this, 0, new Intent(this, Sms1Activity.class), 0);

Example private void sendSMS(String phoneNumber, String message) { // this will re-open the Sms1Activity upon completion PendingIntent pi = PendingIntent.getActivity(this, 0, new Intent(this, Sms1Activity.class), 0); SmsManager sms = SmsManager.getDefault(); sms.sendTextMessage(phoneNumber, null, // null == use default SMSC message, pi, // sent intent null); }

Listening for SMS status  Status updates for services are send out using a broadcast  You need to specify a broadcast receiver to listen for these broadcasts  Broadcast receivers are all sub-types of the BroadcastReceiver class  android.content.BroadcastReceiver  Defines an onReceive() method  These must then be registered with the Context/Activity in order for them to be triggered

BroadcastReceiver  The values returned by getResultCode() are defined by the Broadcast being made private class DeliveredBroadCastReceiver extends BroadcastReceiver public void onReceive(Context arg0, Intent arg1) { switch (getResultCode()) { case Activity.RESULT_OK: Toast.makeText(getBaseContext(), "SMS delivered", Toast.LENGTH_SHORT).show(); break; case Activity.RESULT_CANCELED: Toast.makeText(getBaseContext(), "SMS not delivered", Toast.LENGTH_SHORT).show(); break; }

Example private class SentBroadcastReceiver extends BroadcastReceiver public void onReceive(Context arg0, Intent arg1) { switch (getResultCode()) { case Activity.RESULT_OK: break; // these constants are defined in the SmsManager case SmsManager.RESULT_ERROR_GENERIC_FAILURE: break; case SmsManager.RESULT_ERROR_NO_SERVICE: break; case SmsManager.RESULT_ERROR_NULL_PDU: break; case SmsManager.RESULT_ERROR_RADIO_OFF: break; }

Unregistering receivers  Receivers must be unregistered from an activity when the activity finishes.  unregisterReceiver(receiver)  NOTE: this means you may need to hold on to references of the receivers so you can pass them as parameters to this method

Example  A good place to put this where the back behaviour is done or where you close the Activity public void onBackPressed() { back(); } private void back() { finish(); // must remove receivers or else and error will occur unregisterReceiver(sentBroadcastReceiver); }

Multipart Messages  Multipart messages are handled in a similar fashion to single messages  However, you will need to split the long message into smaller parts  Use SmsManager.divideMessage(String)  This will return an ArrayList containing the individual Strings to be sent

Multipart Messages  Like single messages, multipart messages use PendingIntents to handle post-send/delivery actions  Since multiple messages are used, multiple intents are also used per part  These are passed as an ArrayList  See example

sendMultipartTextMessage()  sendMultipartTextMessage has several parameters: sendMultipartTextMessage  String destinationAddress – phone number to send to String  String scAddress – smsc address (usually null) String  String text – message that will be sent String  ArrayList sentIntents – intents that will be triggered when each part is sentPendingIntent  ArrayList deliveryIntents – intents that will be triggered when each part is deliveredPendingIntent

Threads  Usually sending SMS is done in a separate thread to insure the UI thread is not blocked by the action  This is particularly important with multipart messages if you want to track the progress of the sending process

Upcoming  In the next lecture:  Threaded updates using Handler  Receiving SMS messages  Using multiple emulators to simulate multiple phones  Programmatically triggering a call

Threaded updates  Android is very specific as to which thread alters the contents of the UI  Only the UI thread is allowed to touch the UI related objects  Any other thead doing this will trigger an Exception  Updates from another thread are done via a Handler