1. Integrating with Android Services

2. 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

3. 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

4. SMS

5. 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

6. 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

7. 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

8. 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:

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

10. 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

11. 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

12. 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

13. 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

14. 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()

15. 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()

16. 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);

17. 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); }

18. 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

19. BroadcastReceiver  The values returned by getResultCode() are defined by the Broadcast being made private class DeliveredBroadCastReceiver extends BroadcastReceiver { @Override 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; }

20. Example private class SentBroadcastReceiver extends BroadcastReceiver { @Override 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; }

21. 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

22. 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); }

23. 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

24. 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

25. 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

26. 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

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

28. 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