XmlPullParser

The XmlPullParser provided by the framework is another efficient way of parsing incoming XML data. Like SAX, the parsing is stream based; it does not require much memory to parse large document feeds because the entire XML data structure does not need to be loaded before parsing can begin. Let’s see an example of using XmlPullParser to parse our RSS feed data. Unlike with SAX, however, we must manually advance the parser through the data stream every step of the way, even over the tag elements we aren’t interested in.

Listing 4-30 contains a factory class that iterates over the feed to construct model elements.

Listing 4-30. Factory Class to Parse XML into Model Objects

public class NewsItemFactory {
 
    /* Data Model Class */
    public static class NewsItem {
        public String title;
        public String link;
        public String description;
         
        @Override
        public String toString() {
            return title;
        }
    }
     
    /*
     * Parse the RSS feed out into a list of NewsItem elements
     */
    public static List<NewsItem> parseFeed(XmlPullParser parser)
            throws XmlPullParserException, IOException {
        List<NewsItem> items = new ArrayList<NewsItem>();
         
        while (parser.next() != XmlPullParser.END_TAG) {
            if (parser.getEventType() != XmlPullParser.START_TAG){
                continue;
            }
                 
            if (parser.getName().equals("rss") ||
                    parser.getName().equals("channel")) {
                //Skip these items, but allow to drill inside
            } else if (parser.getName().equals("item")) {
                NewsItem newsItem = readItem(parser);
                items.add(newsItem);
            } else {
                //Skip any other elements and their children
                skip(parser);
            }
        }
         
        //Return the parsed list
        return items;
    }
     
    /*
     * Parse each <item> element in the XML into a NewsItem
     */
    private static NewsItem readItem(XmlPullParser parser) throws
            XmlPullParserException, IOException {
        NewsItem newsItem = new NewsItem();
         
        //Must start with an <item> element to be valid
        parser.require(XmlPullParser.START_TAG, null, "item");
        while (parser.next() != XmlPullParser.END_TAG) {
            if (parser.getEventType() != XmlPullParser.START_TAG){
                continue;
            }
             
            String name = parser.getName();
            if (name.equals("title")) {
                parser.require(XmlPullParser.START_TAG,
                        null, "title");
                newsItem.title = readText(parser);
                parser.require(XmlPullParser.END_TAG,
                        null, "title");
            } else if (name.equals("link")) {
                parser.require(XmlPullParser.START_TAG,
                        null, "link");
                newsItem.link = readText(parser);
                parser.require(XmlPullParser.END_TAG,
                        null, "link");
            } else if (name.equals("description")) {
                parser.require(XmlPullParser.START_TAG,
                        null, "description");
                newsItem.description = readText(parser);
                parser.require(XmlPullParser.END_TAG,
                        null, "description");
            } else {
                //Skip any other elements and their children
                skip(parser);
            }
        }
         
        return newsItem;
    }
     
    /*
     * Read the text content of the current element, which is the
     * data contained between the start and end tag
     */
    private static String readText(XmlPullParser parser) throws
            IOException, XmlPullParserException {
        String result = "";
        if (parser.next() == XmlPullParser.TEXT) {
            result = parser.getText();
            parser.nextTag();
        }
        return result;
    }
     
    /*
     * Helper method to skip over the current element and any
     * children it may have underneath it
     */
    private static void skip(XmlPullParser parser) throws
            XmlPullParserException, IOException {
        if (parser.getEventType() != XmlPullParser.START_TAG) {
            throw new IllegalStateException();
        }
         
        /*
         * For every new tag, increase the depth counter.
         * Decrease it for each tag's end and return when we
         * have reached an end tag that matches the one we
         * started with.
         */
        int depth = 1;
        while (depth != 0) {
            switch (parser.next()) {
            case XmlPullParser.END_TAG:
                depth--;
                break;
            case XmlPullParser.START_TAG:
                depth++;
                break;
            }
        }
    }
}

Pull parsing works by processing the data stream as a series of events. The application advances the parser to the next event by calling the next() method or one of the specialized variations. The following are the event types the parser will advance within:

• START_DOCUMENT: The parser will return this event when it is first initialized. It will be in this state only until the first call to next(), nextToken(), or nextTag().
• START_TAG: The parser has just read a start tag element. The tag name can be retrieved with getName(), and any attributes that were present can be read with getAttributeValue() and associated methods.
• TEXT: Character data inside the tag element was read and can be obtained with getText().
• END_TAG: The parser has just read an end tag element. The tag name of the matching start tag can be retrieved with getName().
• END_DOCUMENT: The end of the data stream has been reached.

Because we must advance the parser ourselves, we have created a helper skip() method to assist in moving the parser past tags we aren’t interested in. This method walks from the current position through all nested child elements until the matching end tag is reached, skipping over them. It does this through a depth counter that increments for each start tag and decrements for each end tag. When the depth counter reaches zero, we have reached the matching end tag for the initial position.

The parser in this example starts iterating through the tags in the stream, looking for <item> tags that it can parse into a NewsItem when the parseFeed() method is called. Every element that is not one of these is skipped over, with the exception of two: <rss> and <channel>. All the items are nested within these two tags, so although we aren’t interested in them directly, we cannot hand them off to skip(), or all our items will be skipped as well.

The task of parsing each <item> element is handled by readItem(), where a new NewsItem is constructed and filled in by the data found within. The method begins by calling require(), which is a security check to ensure the XML is formatted as we expect. The method will quietly return if the current parser event matches the namespace and tag name passed in; otherwise, it will throw an exception. As we iterate through the child elements, we look specifically for the title, link, and description tags so we can read their values into the model data. After finding each tag, readText() advances the parser and pulls the enclosed character data out. Again, there are other elements inside <item> that we aren’t parsing, so we call skip() in the case of any tag we don’t need.

You can see that XmlPullParser is extremely flexible because you control every step of the process, but this also requires more code to accomplish the same result. Listing 4-31 shows our feed display activity reworked to use the new parser.

Listing 4-31. Activity Displaying Parsed XML Feed

public class PullFeedActivity extends Activity implements
        ResponseCallback {
    private static final String TAG = "FeedReader";
    private static final String FEED_URI =
            "http://news.google.com/?output=rss";
 
    private ListView mList;
    private ArrayAdapter<NewsItem> mAdapter;
    private ProgressDialog mProgress;
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
         
        mList = new ListView(this);
        mAdapter = new ArrayAdapter<NewsItem>(this,
                android.R.layout.simple_list_item_1,
                android.R.id.text1);
        mList.setAdapter(mAdapter);
        mList.setOnItemClickListener(
                new AdapterView.OnItemClickListener() {
            @Override
            public void onItemClick(AdapterView<?> parent, View v,
                    int position, long id) {
                NewsItem item = mAdapter.getItem(position);
                Intent intent = new Intent(Intent.ACTION_VIEW);
                intent.setData(Uri.parse(item.link));
                startActivity(intent);
            }
        });
         
        setContentView(mList);
    }
 
    @Override
    public void onResume() {
        super.onResume();
        //Retrieve the RSS feed
        try{
            HttpGet feedRequest = new HttpGet(new URI(FEED_URI));
            RestTask task = new RestTask();
            task.setResponseCallback(this);
            task.execute(feedRequest);
            mProgress = ProgressDialog.show(this, "Searching",
                    "Waiting For Results…", true);
        } catch (Exception e) {
            Log.w(TAG, e);
        }
    }
     
    @Override
    public void onRequestSuccess(String response) {
        if (mProgress != null) {
            mProgress.dismiss();
            mProgress = null;
        }
        //Process the response data
        try {
            XmlPullParser parser = Xml.newPullParser();
            parser.setInput(new StringReader(response));
            //Jump to the first tag
            parser.nextTag();
             
            mAdapter.clear();
            for(NewsItem i : NewsItemFactory.parseFeed(parser)) {
                mAdapter.add(i);
            }
            mAdapter.notifyDataSetChanged();
        } catch (Exception e) {
            Log.w(TAG, e);
        }
    }
     
    @Override
    public void onRequestError(Exception error) {
        if (mProgress != null) {
            mProgress.dismiss();
            mProgress = null;
        }
        //Display the error
        mAdapter.clear();
        mAdapter.notifyDataSetChanged();
        Toast.makeText(this, error.getMessage(),
                Toast.LENGTH_SHORT).show();
    }
}

A fresh XmlPullParser can be instantiated using Xml.newPullParser(), and the input data source can be a Reader or InputStream instance passed to setInput(). In our case, the response data from the web service is already in a String, so we wrap that in a StringReader to have the parser consume. We can pass the parser to NewsItemFactory, which will then return a list of NewsItem elements that we can add to the ListAdapter and display just as we did before.

Bluetooth Peer-to-Peer

Listings 4-35 through 4-37 illustrate an example that uses Bluetooth to find other users nearby and quickly exchange contact information (in this case, just an email address). Connections are made over Bluetooth by discovering available ”services” and connecting to them by referencing their unique 128-bit UUID value. The UUID of the service you want to use must either be discovered or known ahead of time.

In this example, the same application is running on both devices on each end of the connection, so we have the freedom to define the UUID in code as a constant because both devices will have a reference to it.

Listing 4-35. AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:versionCode="1"
    android:versionName="1.0"
    package="com.examples.bluetooth">
 
    <uses-sdk android:minSdkVersion="5" />
 
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission
        android:name="android.permission.BLUETOOTH_ADMIN"/>
 
    <application android:icon="@drawable/icon"
       android:label="@string/app_name">
       <activity android:name=".ExchangeActivity"
          android:label="@string/app_name">
          <intent-filter>
             <action
                android:name="android.intent.action.MAIN" />
             <category
                android:name="android.intent.category.LAUNCHER" />
          </intent-filter>
       </activity>
    </application>
</manifest>

Listing 4-36. res/layout/main.xml

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <TextView
        android:id="@+id/label"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:textAppearance="?android:attr/textAppearanceLarge"
        android:text="Enter Your Email:" />
    <EditText
        android:id="@+id/emailField"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_below="@id/label"
        android:singleLine="true"
        android:inputType="textEmailAddress" />
    <Button
        android:id="@+id/scanButton"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true"
        android:text="Connect and Share" />
    <Button
        android:id="@+id/listenButton"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_above="@id/scanButton"
        android:text="Listen for Sharers" />
</RelativeLayout>

The user interface for this example consists of an EditText for users to enter an email address, and two buttons to initiate communication. The Listen for Sharers button puts the device into listen mode. In this mode, the device will accept and communicate with any device that attempts to connect with it. The Connect and Share button puts the device into search mode. In this mode, the device searches for any device that is currently listening and makes a connection (see Listing 4-37).

Listing 4-37. Bluetooth Exchange Activity

public class ExchangeActivity extends Activity {
 
    // Unique UUID for this application (generated from the web)
    private static final UUID MY_UUID =
        UUID.fromString("321cb8fa-9066-4f58-935e-ef55d1ae06ec");
    //Friendly name to match while discovering
    private static final String SEARCH_NAME = "bluetooth.recipe";
 
    BluetoothAdapter mBtAdapter;
    BluetoothSocket mBtSocket;
    Button listenButton, scanButton;
    EditText emailField;
 
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        requestWindowFeature(
                Window.FEATURE_INDETERMINATE_PROGRESS);
        setContentView(R.layout.main);
 
        //Check the system status
        mBtAdapter = BluetoothAdapter.getDefaultAdapter();
        if(mBtAdapter == null) {
            Toast.makeText(this, "Bluetooth is not supported.",
                Toast.LENGTH_SHORT).show();
            finish();
            return;
        }
        if (!mBtAdapter.isEnabled()) {
            Intent enableIntent = new Intent(
                    BluetoothAdapter.ACTION_REQUEST_ENABLE);
            startActivityForResult(enableIntent, REQUEST_ENABLE);
        }
 
        emailField = (EditText)findViewById(R.id.emailField);
        listenButton = (Button)findViewById(R.id.listenButton);
        listenButton.setOnClickListener(
                new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                //Make sure the device is discoverable first
                if (mBtAdapter.getScanMode() != BluetoothAdapter
                        .SCAN_MODE_CONNECTABLE_DISCOVERABLE) {
                    Intent discoverableIntent = new Intent(
                            BluetoothAdapter
                                .ACTION_REQUEST_DISCOVERABLE);
                    discoverableIntent.putExtra(BluetoothAdapter.
                            EXTRA_DISCOVERABLE_DURATION, 300);
                    startActivityForResult(discoverableIntent,
                            REQUEST_DISCOVERABLE);
                    return;
                }
                startListening();
            }
        });
        scanButton = (Button)findViewById(R.id.scanButton);
        scanButton.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                mBtAdapter.startDiscovery();
                setProgressBarIndeterminateVisibility(true);
            }
        });
    }
 
    @Override
    public void onResume() {
        super.onResume();
        //Register the activity for broadcast intents
        IntentFilter filter = new IntentFilter(
                BluetoothDevice.ACTION_FOUND);
        registerReceiver(mReceiver, filter);
        filter = new IntentFilter(
                BluetoothAdapter.ACTION_DISCOVERY_FINISHED);
        registerReceiver(mReceiver, filter);
    }
 
    @Override
    public void onPause() {
        super.onPause();
        unregisterReceiver(mReceiver);
    }
 
    @Override
    public void onDestroy() {
        super.onDestroy();
        try {
            if(mBtSocket != null) {
                mBtSocket.close();
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
 
    private static final int REQUEST_ENABLE = 1;
    private static final int REQUEST_DISCOVERABLE = 2;
 
    @Override
    protected void onActivityResult(int requestCode,
            int resultCode, Intent data) {
        switch(requestCode) {
        case REQUEST_ENABLE:
            if(resultCode != Activity.RESULT_OK) {
                Toast.makeText(this, "Bluetooth Not Enabled.",
                    Toast.LENGTH_SHORT).show();
                finish();
            }
            break;
        case REQUEST_DISCOVERABLE:
            if(resultCode == Activity.RESULT_CANCELED) {
                Toast.makeText(this, "Must be discoverable.",
                    Toast.LENGTH_SHORT).show();
            } else {
                startListening();
            }
            break;
        default:
            break;
        }
    }
 
    //Start a server socket and listen
    private void startListening() {
        AcceptTask task = new AcceptTask();
        task.execute(MY_UUID);
        setProgressBarIndeterminateVisibility(true);
    }
 
    //AsyncTask to accept incoming connections
    private class AcceptTask extends
            AsyncTask<UUID, Void, BluetoothSocket> {
 
        @Override
        protected BluetoothSocket doInBackground(UUID… params) {
            String name = mBtAdapter.getName();
            try {
                //While listening, set the discovery name to
                // a specific value
                mBtAdapter.setName(SEARCH_NAME);
                BluetoothServerSocket socket = mBtAdapter
                        .listenUsingRfcommWithServiceRecord(
                            "BluetoothRecipe", params[0]);
                BluetoothSocket connected = socket.accept();
                //Reset the BT adapter name
                mBtAdapter.setName(name);
                return connected;
            } catch (IOException e) {
                e.printStackTrace();
                mBtAdapter.setName(name);
                return null;
            }
        }
 
        @Override
        protected void onPostExecute(BluetoothSocket socket) {
            if(socket == null) {
                return;
            }
            mBtSocket = socket;
            ConnectedTask task = new ConnectedTask();
            task.execute(mBtSocket);
        }
 
    }
 
    //AsyncTask to receive a single line of data and post
    private class ConnectedTask extends
            AsyncTask<BluetoothSocket,Void,String> {
 
        @Override
        protected String doInBackground(
                BluetoothSocket... params) {
            InputStream in = null;
            OutputStream out = null;
            try {
                //Send your data
                out = params[0].getOutputStream();
                String email = emailField.getText().toString();
                out.write(email.getBytes());
                //Receive the other's data
                in = params[0].getInputStream();
                byte[] buffer = new byte[1024];
                in.read(buffer);
                //Create a clean string from results
                String result = new String(buffer);
                //Close the connection
                mBtSocket.close();
                return result.trim();
            } catch (Exception exc) {
                return null;
            }
        }
 
        @Override
        protected void onPostExecute(String result) {
            Toast.makeText(ExchangeActivity.this, result,
                    Toast.LENGTH_SHORT).show();
            setProgressBarIndeterminateVisibility(false);
        }
    }
 
    // The BroadcastReceiver that listens for discovered devices
    private BroadcastReceiver mReceiver =
            new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            String action = intent.getAction();
 
            // When discovery finds a device
            if (BluetoothDevice.ACTION_FOUND.equals(action)) {
                // Get the BluetoothDevice object from the Intent
                BluetoothDevice device =
                    intent.getParcelableExtra(
                        BluetoothDevice.EXTRA_DEVICE);
                if(TextUtils.equals(device.getName(),
                        SEARCH_NAME)) {
                    //Matching device found, connect
                    mBtAdapter.cancelDiscovery();
                    try {
                        mBtSocket = device
                            .createRfcommSocketToServiceRecord(
                                MY_UUID);
                        mBtSocket.connect();
                        ConnectedTask task = new ConnectedTask();
                        task.execute(mBtSocket);
                    } catch (IOException e) {
                        e.printStackTrace();
                    }
                }
            //When discovery is complete
            } else if (BluetoothAdapter.ACTION_DISCOVERY_FINISHED
                    .equals(action)) {
                setProgressBarIndeterminateVisibility(false);
            }
 
        }
    };
}

When the application first starts up, it runs some basic checks on the Bluetooth status of the device. If BluetoothAdapter.getDefaultAdapter() returns null, it is an indication that the device does not have Bluetooth support, and the application will go no further. Even with Bluetooth on the device, it must be enabled for the application to use it. If Bluetooth is disabled, the preferred method for enabling the adapter is to send an Intent to the system with BluetoothAdapter.ACTION_REQUEST_ENABLE as the action. This notifies the user of the issue, and that user can then enable Bluetooth. A BluetoothAdapter can be manually enabled with the enable() method, but we strongly discourage you from doing this unless you have requested the user’s permission another way.

With Bluetooth validated, the application waits for user input. As mentioned previously, the example can be put into one of two modes on each device: listen mode or search mode. Let’s look at the path each mode takes.

Bluetooth Beyond Android

As we mentioned in the beginning of this section, Bluetooth is found in many wireless devices besides mobile phones and tablets. RFCOMM interfaces also exist in devices such as Bluetooth modems and serial adapters. The same APIs that were used to create the peer-to-peer connection between Android devices can also be used to connect to other embedded Bluetooth devices for the purposes of monitoring and control.

The key to establishing a connection with these embedded devices is obtaining the UUID of the RFCOMM services they support. Bluetooth services that are part of a profile standard, and their identifiers, are defined by the Bluetooth Special Interest Group (SIG); so you may be able to obtain the UUID you require for a given device from the documentation provided on www.bluetooth.org. However, if your device manufacturer has defined a device-specific UUID for a custom service type and it is not readily documented, we must have a way to discover it. As with the previous example, with the proper UUID we can create a BluetoothSocket and transmit data.

The capability to do this exists in the SDK, although prior to Android 4.0.3 (API Level 15) it was not part of the public SDK. There are two methods on BluetoothDevice that will provide this information; fetchUuidsWithSdp() and getUuids(). The latter simply returns the cached instances for the device  found during discovery, while the former asynchronously connects to the device and does a fresh query. Because of this, when using fetchUuidsWithSdp(), you must register a BroadcastReceiver that will receive Intents set with the BluetoothDevice.ACTION_UUID action string to discover the UUID values.

public ParcelUuid servicesFromDevice(BluetoothDevice device) {
    try {
        Class cl =
            Class.forName("android.bluetooth.BluetoothDevice");
        Class[] par = {};
        Method method = cl.getMethod("getUuids", par);
        Object[] args = {};
        ParcelUuid[] retval =
            (ParcelUuid[]) method.invoke(device, args);
        return retval;
    } catch (Exception e) {
        e.printStackTrace();
        return null;
    }
}

Verifying a Route

Mobile devices have multiple connectivity routes (WiFi, 3G/4G, and so forth), and it is common for a device to be connected to a network that doesn’t have a route to the external Web; this is especially common with WiFi networks. ConnectivityManager alone simply notifies you of whether or not your device has associated with a particular network, but says nothing of that network’s ability to access an outside IP address. Add to this the fact that when a device attempts to connect through a network that is “connected” but has no valid route, the time the network stack can take to time out and fail properly can be minutes.

You may find yourself in a situation where it is smarter to check for a valid Internet connection rather than just an association with a network. Listing 4-39 builds on the previous reachability check to do just that.

Listing 4-39. Smarter ConnectivityManager Wrapper

public static boolean hasNetworkConnection(Context context) {
        final ConnectivityManager connectivityManager =
                (ConnectivityManager) context.getSystemService(
                        Context.CONNECTIVITY_SERVICE);
        final NetworkInfo activeNetworkInfo =
                connectivityManager.getActiveNetworkInfo();
 
        //If we aren't even associated with a network, we're done
        boolean connected = (null != activeNetworkInfo)
                && activeNetworkInfo.isConnected();
        if (!connected) return false;
 
        //Check if we can access a remote server
        boolean routeExists;
        try {
            //Check Google Public DNS
            InetAddress host = InetAddress.getByName("8.8.8.8");
 
            Socket s = new Socket();
            s.connect(new InetSocketAddress(host, 53), 5000);
            //It exists if no exception is thrown
            routeExists = true;
            s.close();
        } catch (IOException e) {
            routeExists = false;
        }
 
        return (connected && routeExists);
}

After verifying the same reachability condition as before, Listing 4-39 goes a step further and attempts to open a socket to the well-known standard IPv4 address for the Google Public DNS (8.8.8.8) with a 5-second time-out. If a connection to this host succeeds, we can have a relatively high level of confidence that the device can access any active Internet resource. The advantage to this approach over attempting to fully connect directly to your remote server is that this code will fail faster, forcing up to only a 5-second delay before telling the user they really don’t have the Internet connection they think they do.

It is considered good practice to call a reachability check whenever a network request fails and to notify the user that their request failed because of a lack of connectivity. Listing 4-40 is an example of doing this when a network access fails.

Listing 4-40. Notify User of Connectivity Failure

try {
    //Attempt to access network resource. May throw
    // HttpResponseException or some other IOException on failure
} catch (Exception e) {
    if( !isNetworkReachable() ) {
        AlertDialog.Builder builder =
                new AlertDialog.Builder(context);
        builder.setTitle("No Network Connection");
        builder.setMessage("The Network is unavailable."
                + " Please try your request again later.");
        builder.setPositiveButton("OK",null);
        builder.create().show();
    }
}

Determining Connection Type

In cases where it is also essential to know whether the user is connected to a network that charges for bandwidth, we can call NetworkInfo.getType() on the active network connection (see Listing 4-41).

Listing 4-41. ConnectivityManager Bandwidth Checking

public boolean isWifiReachable() {
    ConnectivityManager mManager =
            (ConnectivityManager)context.getSystemService(
                    Context.CONNECTIVITY_SERVICE);
    NetworkInfo current = mManager.getActiveNetworkInfo();
    if(current == null) {
        return false;
    }
    return (current.getType() == ConnectivityManager.TYPE_WIFI);
}

This modified version of the reachability check determines whether the user is attached to a WiFi connection, typically indicating that the user has a faster connection where bandwidth isn’t tariffed.

Beaming with Foreground Push

If you want to send simple content between devices over NFC, you can use the foreground push mechanism to create an NfcMessage containing one or more NfcRecord instances. Listings 4-42 and 4-43 illustrate creating a simple NfcMessage to push to another device.

Listing 4-42. AndroidManifest.xml

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.examples.nfcbeam"
    android:versionCode="1"
    android:versionName="1.0" >
 
    <uses-sdk
        android:minSdkVersion="16"
        android:targetSdkVersion="16" />
 
    <uses-permission android:name="android.permission.NFC" />
    <application
       android:icon="@drawable/ic_launcher"
       android:label="NfcBeam">
       <activity
          android:name=".NfcActivity"
          android:label="NfcActivity"
          android:launchMode="singleTop">
          <intent-filter>
             <action android:name="android.intent.action.MAIN" />
             <category android:name="android.intent.category.LAUNCHER" />
          </intent-filter>
          <intent-filter>
             <action android:name="android.nfc.action.NDEF_DISCOVERED" />
             <category android:name="android.intent.category.DEFAULT" />
             <data android:mimeType=
                 "application/com.example.androidrecipes.beamtext"/>
          </intent-filter>
        </activity>
    </application>
</manifest>

First notice that android.permission.NFC is required to work with the NFC service. Second, note the custom <intent-filter> placed on our activity. This is how Android will know which application to launch in response to the content it receives.

Listing 4-43. Activity Generating an NFC Foreground Push

public class NfcActivity extends Activity implements
        CreateNdefMessageCallback, OnNdefPushCompleteCallback {
    private static final String TAG = "NfcBeam";
    private NfcAdapter mNfcAdapter;
    private TextView mDisplay;
     
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        mDisplay = new TextView(this);
        setContentView(mDisplay);
         
        // Check for available NFC Adapter
        mNfcAdapter = NfcAdapter.getDefaultAdapter(this);
        if (mNfcAdapter == null) {
          mDisplay.setText("NFC not available on this device.");
        } else {
            // Register callback to set NDEF message. Setting
            // this makes NFC data push active while the Activity
            // is in the foreground.
            mNfcAdapter.setNdefPushMessageCallback(this, this);
            // Register callback for message-sent success
            mNfcAdapter.setOnNdefPushCompleteCallback(this, this);
        }
    }
     
    @Override
    public void onResume() {
        super.onResume();
        // Check to see if a Beam launched this Activity
        if (NfcAdapter.ACTION_NDEF_DISCOVERED
                .equals(getIntent().getAction())) {
            processIntent(getIntent());
        }
    }
 
    @Override
    public void onNewIntent(Intent intent) {
        // onResume gets called after this to handle the intent
        setIntent(intent);
    }
 
    void processIntent(Intent intent) {
        Parcelable[] rawMsgs = intent.getParcelableArrayExtra(
                NfcAdapter.EXTRA_NDEF_MESSAGES);
        // only one message sent during the beam
        NdefMessage msg = (NdefMessage) rawMsgs[0];
        // record 0 contains the MIME type
        mDisplay.setText(new String(
                msg.getRecords()[0].getPayload()) );
    }
     
    @Override
    public NdefMessage createNdefMessage(NfcEvent event) {
        String text = String.format(
                "Sending A Message From Android Recipes at %s",
                DateFormat.getTimeFormat(this)
                        .format(new Date()) );
        NdefMessage msg = new NdefMessage(NdefRecord.createMime(
                "application/com.example.androidrecipes.beamtext",
                text.getBytes()) );
        return msg;
    }
     
    @Override
    public void onNdefPushComplete(NfcEvent event) {
        //This callback happens on a binder thread, don't update
        // the UI directly from this method.
        Log.i(TAG, "Message Sent!");
    }
}

This example application encompasses both the sending and receiving of an NFC push, so the same application should be installed on both devices: the one that is sending and the one that is receiving the data. The activity registers itself for foreground push by using the setNdefPushMessageCallback() method on the NfcAdapter. This call does two things simultaneously. It tells the NFC service to call this activity at the moment a transfer is initiated to receive the message it needs to send, and it also activates NFC push whenever this activity is in the foreground. There is also an alternate version of this called setNdefPushMessage() that takes the message directly rather than implementing a callback.

The callback method constructs an NdefMessage containing a single NFC Data Exchange Format (NDEF) MIME record (created with the NdefRecord.createMime() method). MIME records are simple ways of passing application-specific data. The createMime() method takes both a string for the MIME type and a byte array for the raw data. The information can be anything from a text string to a small image; your application is responsible for packing and unpacking it. Notice that the MIME type here matches the type defined in the manifest’s <intent-filter>.

In order for the push to work, the sending device must have this activity active in the foreground, and the receiving device must not be locked. When the user touches the two devices together, the sending screen shows Android’s Touch to Beam UI, and a tap of the screen sends the message to the other device. As soon as the message is received, the application launches on the receiving device, and the sending device’s onNdefPushComplete() callback is triggered.

On the receiving device, the activity is launched with the ACTION_NDEF_DISCOVERED Intent, so our example will inspect the Intent for the NdefMessage and unpack the payload, turning it back from bytes into a string. This method of using Intent matching to send NFC data is the most flexible, but sometimes you want your application to be explicitly called. This is where Android Application Records come in.

Android Application Records

Your application can provide an additional NdefRecord inside an NdefMessage that directs Android to call a specific package name on the receiving device. To include this in our previous example, we would simply modify the CreateNdefMessageCallback like so:

@Override
public NdefMessage createNdefMessage(NfcEvent event) {
    String text = String.format(
            "Sending A Message From Android Recipes at %s",
            DateFormat.getTimeFormat(this)
                    .format(new Date()) );
    NdefMessage msg = new NdefMessage(NdefRecord.createMime(
            "application/com.example.androidrecipes.beamtext",
            text.getBytes()),
            NdefRecord
                .createApplicationRecord("com.examples.nfcbeam"));
    return msg;
}

With the addition of NdefRecord.createApplicationRecord(), this push message is now guaranteed to launch only our com.examples.nfcbeam package. The text information is still the first record in the message, so our unpacking of the received message remains unchanged.

Beaming Larger Content

We mentioned at the beginning of this recipe that sending large content blobs over NFC is not a great idea. However, Android Beam has the capability to handle that as well. Have a look at Listings 4-44 and 4-45 for examples of sending large image files over Beam.

Listing 4-44. AndroidManifest.xml

<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.examples.nfcbeam"
    android:versionCode="1"
    android:versionName="1.0" >
 
    <uses-sdk
        android:minSdkVersion="16"
        android:targetSdkVersion="16" />
 
    <uses-permission android:name="android.permission.NFC" />
    <application
       android:icon="@drawable/ic_launcher"
       android:label="NfcBeam">
       <activity
          android:name=".BeamActivity"
          android:label="BeamActivity"
          android:launchMode="singleTop">
          <intent-filter>
             <action android:name="android.intent.action.MAIN" />
             <category
                android:name="android.intent.category.LAUNCHER" />
          </intent-filter>
          <intent-filter>
             <action android:name="android.intent.action.VIEW" />
             <data android:mimeType="image/*" />
          </intent-filter>
       </activity>
    </application>
 
</manifest>

Listing 4-45. Activity to Transfer an Image File

public class BeamActivity extends Activity implements
        CreateBeamUrisCallback, OnNdefPushCompleteCallback {
    private static final String TAG = "NfcBeam";
    private static final int PICK_IMAGE = 100;
     
    private NfcAdapter mNfcAdapter;
    private Uri mSelectedImage;
     
    private TextView mUriName;
    private ImageView mPreviewImage;
     
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
         
        mUriName = (TextView) findViewById(R.id.text_uri);
        mPreviewImage =
                (ImageView) findViewById(R.id.image_preview);
         
        // Check for available NFC Adapter
        mNfcAdapter = NfcAdapter.getDefaultAdapter(this);
        if (mNfcAdapter == null) {
            mUriName.setText("NFC not available on this device.");
        } else {
            // Register callback to set NDEF message
            mNfcAdapter.setBeamPushUrisCallback(this, this);
            // Register callback for message-sent success
            mNfcAdapter.setOnNdefPushCompleteCallback(this, this);
        }
    }
     
    @Override
    protected void onActivityResult(int requestCode,
            int resultCode, Intent data) {
        if (requestCode == PICK_IMAGE && resultCode == RESULT_OK
                && data != null) {
            mUriName.setText( data.getData().toString() );
            mSelectedImage = data.getData();
        }
    }
     
    @Override
    public void onResume() {
        super.onResume();
        //Check to see that the Activity started due to
        // an Android Beam
        if (Intent.ACTION_VIEW.equals(getIntent().getAction())) {
            processIntent(getIntent());
        }
    }
 
    @Override
    public void onNewIntent(Intent intent) {
        // onResume gets called after this to handle the intent
        setIntent(intent);
    }
 
    void processIntent(Intent intent) {
        Uri data = intent.getData();
        if(data != null) {
            mPreviewImage.setImageURI(data);
        } else {
            mUriName.setText("Received Invalid Image Uri");
        }
    }
     
    public void onSelectClick(View v) {
        Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
        intent.setType("image/*");
        startActivityForResult(intent, PICK_IMAGE);
    }
 
    @Override
    public Uri[] createBeamUris(NfcEvent event) {
        if (mSelectedImage == null) {
            return null;
        }
        return new Uri[] {mSelectedImage};
    }
     
    @Override
    public void onNdefPushComplete(NfcEvent event) {
        //This callback happens on a binder thread, don't update
        // the UI directly from this method. This is a good time
        // to tell your user they don't need to hold
        // their phones together anymore!
        Log.i(TAG, "Push Complete!");
    }
}

This example uses CreateBeamUrisCallback, which allows an application to construct an array of Uri instances pointing to content you would like to transmit. Android will do the work of negotiating the initial connection over NFC but will then drop to a more suitable connection such as Bluetooth or WiFi Direct to finish the larger transfers.

In this case, the data on the receiving device is launched using the system’s standard Intent.ACTION_VIEW action, so it is not necessary to load the application on both devices. However, our application does filter for ACTION_VIEW so the receiving device could use it to view the received image content if the user prefers.

Here, the user is asked to select an image from the device to transfer, and then the Uri of that content is displayed once selected. As soon as the user touches that device to another, the same Touch to Beam UI (see Figure 4-4) displays, and the transfer begins when the screen is tapped.

Once the NFC portion of the transfer is complete, the onNdefPushComplete() method is called on the sending device. At this point, the transfer has moved to another connection, so the users don’t need to hold their phones together anymore.

The receiving device will display a progress notification in the system’s window shade while the file is transferring. When the transfer is complete, the user can tap on the notification to view the content. If this application is chosen as the content viewer, the image will be shown in our application’s ImageView. One possible disadvantage to registering your application with such a generic Intent is that every application on the device can then ask your application to view images, so choose your filters wisely!

USB Overview

Before looking at an example of how Android interacts with USB devices, let’s take a moment to define some USB terms:

• Endpoint: The smallest building block of a USB device. These are what your application eventually connects to for the purpose of sending and receiving data. They can take the form of four main types:
  • Control: Used for configuration and status commands. Every device has at least one control endpoint, called endpoint 0, that is not attached to any interface.
  • Interrupt: Used for small, high-priority control commands.
  • Bulk: Large data transfer. Commonly found in bidirectional pair (1 IN and 1 OUT).
  • Isochronous: Used for real-time data transfer such as audio. Not supported by the latest Android SDK as of this writing.

• Interface: A collection of endpoints to represent a “logical” device.
  • Physical USB devices can manifest themselves to the host as multiple logical devices, and they do this by exposing multiple interfaces.

• Configuration: Collection of one or more interfaces. The USB protocol enforces that only one configuration can be active at any one time on a device. In fact, most devices have only one configuration at all. Think of this as the device’s operating mode.

Getting Notified of Device Connections

In order for Android to notify your application when a particular device is connected, you need to register the device types you are interested in with an <intent-filter> in the manifest. Take a look at Listings 4-48 and 4-49 to see how this is done.

Listing 4-48. Partial AndroidManifest.xml

<activity
   android:name=".USBActivity"
   android:label="@string/title_activity_usb" >
   <intent-filter>
      <action android:name="android.intent.action.MAIN" />
      <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <intent-filter>
      <action android:name=
         "android.hardware.usb.action.USB_DEVICE_ATTACHED" />
   </intent-filter>
 
   <meta-data android:name=
      "android.hardware.usb.action.USB_DEVICE_ATTACHED"
      android:resource="@xml/device_filter" />
</activity>

Listing 4-49. res/xml/device_filter.xml

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <usb-device vendor-id="5432" product-id="9876" />
</resources>

The activity you want to launch with a connection has a filter added to it with the USB_DEVICE_ATTACHED action string and with some XML metadata describing the devices you are interested in. There are several device attribute fields you can place into <usb-device> to filter which connection events notify your application:

• vendor-id
• product-id
• class
• subclass
• protocol

You can define as many of these as necessary to fit your application. For example, if you want to communicate with only one specific device, you might define both vendor-id and product-id as the example code did. If you are more interested in all devices of a given type (say, all mass-storage devices), you might define only the class attribute. It is even allowable to define no attributes, and have your application match on any device connected!