David Sutton SMS TELEPHONY IN ANDROID

OUTLINE  This week’s exercise, an SMS Pub Quiz  Simulating telephony on an emulator  Broadcast Intents and broadcast receivers  Sending and receiving SMS messages  Implementing the pub quiz app Do exercise 1

THIS WEEK’S APPLICATION AN SMS PUB QUIZ  We will create a simple application that will allow users to participate in a quiz by SMS.  Pressing the “Send” button on the UI sends a numbered question to subscribed quizzers.  A quizzer can subscribe by sending a text message containing the word “subscribe” followed by his name (or his team’s name).  A quizzer can answer a question by sending an SMS consisting of the number of the question, followed by his answer.

SIMULATING TELEPHONY ON AN EMULATOR Three methods 1.Connect to the emulator via Telnet and use sms or gsm commands 2.Open the DDMS Perspective and use the Emulator Control tab. 3.Send messages calls between different emulator instances using ports as telephone numbers.

IDENTIFYING THE PORT ON WHICH AN EMULATOR RUNS This is the port number, it can be used to access the emulator via telnet. It can also be used as a telephone number when calling this emulator from another.

TELNET ACCESS Port on which the emulator is running Simulates arrival of an SMS message from number specified. Simulates arrival of a voice call from number specified. Simulates termination of a call. More detail at

THE DDMS PERSPECTIVE

CALLING ONE EMULATOR FROM ANOTHER Port number of another emulator used as phone number Do exercises 2,3, and 4.

INTENTS REVISITED  An Intent is a means by which one Activity can invoke another (or others).  There are two types of Intent:  An explicit Intent names the Activity to be launched.  An implicit Intent specifies an action to be performed. It is then up to the operating system to decide which Activity, or Activities, should perform that action.  The action is specified as a text string. By convention these strings are constructed using the same form as java package names. For example “android.provider.Telephony.SMS_RECEIVED”  An Intent can carry additional information in the form of a data URI and/or a bundle of extras (key-value pairs).

BROADCAST INTENTS  If an Intent is broadcast then all Activities registered to receive the Intent will process it.  An Activity that wishes to receive a broadcast Intent should extend the BroadcastReceiver class and override its onReceive method.  An Activity can be registered to receive an Intent in two ways: o In code – this means that the Activity will only respond while it is running. o In the application manifest – an Activity that is registered in this manner always responds, even if it has been killed.

INTENTS OF INTEREST WHEN WRITING TELEPHONY APPS  The String “android.intent.action.DIAL”, when used as the action of an Intent, indicates an intent to dial a number. The associated data URI gives the number to be dialled. This String can be represented using the constant Intent. ACTION_DIAL.  The String "android.intent.action.SENDTO” indicates an intention to send a message. If it is associated with a data URI using the sms schema notation (e.g. “sms: ”) it will be interpreted as an intent to send an SMS message. This String can be represented using the constant Intent.SENDTO.  The String “android.provider.Telephony.SMS_RECEIVED”, when used as the action of an Intent, indicates that the device has received an SMS message. There is, as yet, no constant for that String so you have to write it out in full.

SENDING AN SMS MESSAGE FROM AN ANDROID ACTIVITY  There are two ways of sending an SMS message programatically: 1.Create an Intent with the action String “android.intent.action.SENDTO” and a data URI that uses the sms schema (see previous slide). This will be processed by whatever Activity is responsible for sending SMS messages, usually the native messaging activity. 2.Use the SmsManager class. You can get an instance of this by calling the static method SmsManager.getDefault(). The SmsManager class has just four non-static methods:  sendTextMessage – sends a text message.  sendDataMessage – sends a data based message.  divideMessage – divide a message into a number of fragments, none of which are bigger than the maximum size for a text.  sendMultipartTextMessage – send a multi-part text based message

RECEIVING AN SMS MESSAGE  When a device receives an SMS message an Intent with the action string “android.provider.Telephony.SMS_RECEIVED” is broadcast. An application that wishes to react to an incoming message must register an appropriate BroadcastReceiver.

EXTRACTING DATA FROM AN SMS MESSAGE  The text of an SMS, along with its metadata, are encoded in an array of Protocol Data Units (PDUs).  The PDUs are attached to the SMS_RECEIVED intent as an extra with the key “pdus”.  They can be decoded by using them to create and SmsMessage object. The SmsMessage class contains methods that allow the text of the message to be extracted along with its metadata (originating address etc.).

PERMISSIONS  An application that wishes to receive SMS messages must include the permission "android.permission.RECEIVE_SMS” in its manifest  An application that wishes to send SMS messages must include the permission “android.permission.SEND_SMS”

UI FOR PUB QUIZ APP EditText components with appropriate hints. There should be a list view here, which will contain the phone numbers of our quizzers. Button TextView Do exercise 5

A QUIZZER CLASS Quizzer -String name -String origAddress -int nbrAnswered -int nbrCorrect +Quizzer(String name, String origAddress) +String getName() +String getOrigAddress() +void incNbrAnswered() +void incNbrCorrect() +String toString() Team name Phone number for team Number of questions answered Number of correct answers Add 1 to number of correct answers Add 1 to number of questions answered Return a String containing the name of the team, the number of questions they have answered and the number of correct answers, for example “The Brain (23/24”) Do exercise 6

DISPLAYING A LIST OF QUIZZERS public class PubQuiz extends Activity { private ListView quizzersLst; private ArrayList quizzers; private ArrayAdapter protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_pub_quiz); quizzersLst = (ListView) findViewById(R.id.quizzers_lst); quizzers = new ArrayList (); adapter = new ArrayAdapter (this, android.R.layout.simple_list_item_1, quizzers); quizzersLst.setAdapter(adapter); Do exercise 7

CREATING A RECEIVER FOR SMS MESSAGES protected void onCreate(Bundle savedInstanceState) { …. BroadcastReceiver myReceiver = new BroadcastReceiver() public void onReceive(Context context, Intent intent) { Bundle bundle = intent.getExtras(); Object[] pdus = (Object[]) bundle.get("pdus"); for (Object pduObj:pdus) { byte[] pdu = (byte[]) pduObj; SmsMessage message = SmsMessage.createFromPdu(pdu); processMessage(message); } }; We will define this method later.

REGISTERING THE RECEIVER public class PubQuiz extends Activity { private static final String SMS_RECEIVED = "android.provider.Telephony.SMS_RECEIVED"; protected void onCreate(Bundle savedInstanceState) { BroadcastReceiver myReceiver = new BroadcastReceiver() { … }; IntentFilter filter = new IntentFilter(SMS_RECEIVED); registerReceiver(myReceiver, filter); }

PROCESSING MESSAGES  We will allow people to subscribe to the pub quiz by sending a message of the form subscribe  So for example subscribe The Swots Would add a team called “The Swots” whose name should appear in the list at the bottom of the screen.

PROCESSING MESSAGES private static final String SUBSCRIBE_STR = "subscribe"; private ReentrantLock lock = new ReentrantLock(); ….. private void processMessage(SmsMessage message) { String messageText = message.getMessageBody(); Scanner scan = new Scanner(messageText); if(scan.hasNext()) { if (scan.next().equalsIgnoreCase(SUBSCRIBE_STR)) { String name = scan.nextLine().trim(); String origAdress = message.getOriginatingAddress(); Quizzer quizzer = new Quizzer(name, origAdress); lock.lock(); try { quizzers.add(quizzer); adapter.notifyDataSetChanged(); } finally {lock.unlock();} } Ensures thread safety of modifications to ArrayList

USER INTERFACE Do exercise 8

SENDING QUESTIONS private EditText questionEdt; private EditText answerEdt; private Button sendBtn; private ArrayList answers = new ArrayList protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_pub_quiz); questionEdt = (EditText) findViewById(R.id.question_edt); answerEdt = (EditText) findViewById(R.id.answer_edt); sendBtn = (Button) findViewById(R.id.send_btn); sendBtn.setOnClickListener(new OnClickListener() public void onClick(View v) { sendQuestion(); } }); This method is defined on the next slide

SENDING QUESTIONS private void sendQuestion() { SmsManager manager = SmsManager.getDefault(); String question = questionEdt.getEditableText().toString(); String answer = answerEdt.getEditableText().toString(); answers.add(answer); String sentQuestion = "" + answers.size() + " " + question; for (Quizzer quizzer : quizzers) { manager.sendTextMessage(quizzer.getOrigAddress(), null, sentQuestion, null, null); } Do exercise 9

PROCESSING ANSWERS  In order to answer a question, a quizzer must send a text message consisting of the number of the question, followed by the answer. So for example if question 2 was “What is the capital of Portugal” the quizzer might send a text message “2 Lisbon”.  We will need to update the processMessage method of our main Activity so that it correctly responds to messages beginning with an integer, as well as messages beginning with the word “subscribe”.

PROCESSING ANSWERS String messageText = message.getMessageBody(); Scanner scan = new Scanner(messageText); if (scan.hasNextInt()) { int questionNo = scan.nextInt(); String origAddress = message.getOriginatingAddress(); Quizzer quizzer = getQuizzer(origAddress); if (quizzer != null && questionNo <= answers.size()) { lock.lock(); try { quizzer.incNbrAnswered(); String answer = scan.nextLine().trim(); if (answer.equalsIgnoreCase(answers.get(questionNo - 1).trim())) { quizzer.incNbrCorrect(); } adapter.notifyDataSetChanged(); } finally {lock.unlock();} } if (scan.hasNext()) { …. process subscribe messages

USER INTERFACE Do exercise 10

SUMMARY  We can simulate telephony on the emulator in three different ways.  Intents may be either explicit or implicit  A broadcast Intent is processed by all applications that are registered to receive it.  An SMS message is encoded as a set of protocol data units, which can be decoded using the SMSMessage class.  The SMSManager class can be used to send SMS mesages.